Skip to content

PHASE3_SUMMARY.md

Latest commit

 

History

History
121 lines (94 loc) · 4.63 KB

PHASE3_SUMMARY.md

File metadata and controls

121 lines (94 loc) · 4.63 KB

Phase 3: Adaptation Package Sync - Summary

✅ Completed (100%)

Phase 3 successfully integrated the TypeScript transformer into the sync package, replacing JSON workflow storage with TypeScript .workflow.ts files.

Changes Made

1. WorkflowTransformerAdapter Created

File: packages/sync/src/services/workflow-transformer-adapter.ts

Adapter class bridging the sync package and transformer package:

  • convertToTypeScript(workflow, options) - Convert n8n JSON to TypeScript
  • compileToJson(tsContent) - Compile TypeScript back to n8n JSON
  • hashWorkflow(tsContent) - Hash TypeScript by compiling to normalized JSON
  • hashWorkflowFromJson(workflow) - Hash remote workflows not yet saved
  • convertToIWorkflow(workflow) - Convert N8nWorkflow tags (string[]) to IWorkflow tags (ITag[])

2. SyncEngine Adapted

File: packages/sync/src/services/sync-engine.ts

Modified to work with TypeScript files:

  • Changed import: WorkflowSanitizer → WorkflowTransformerAdapter
  • executePull() - Now writes TypeScript files instead of JSON
  • executeUpdate() - Compiles TS→JSON for API push, writes TS back
  • executeCreate() - Compiles TS→JSON for API create, writes TS back
  • readJsonFile() → readTypeScriptFile() - Reads raw TypeScript content

3. Watcher Adapted

File: packages/sync/src/services/watcher.ts

Modified to observe and hash TypeScript files:

  • Changed import: WorkflowSanitizer → WorkflowTransformerAdapter
  • File extension filter: .json → .workflow.ts (5 occurrences)
  • Filename generation: ${name}.json → ${name}.workflow.ts
  • Filename parsing: .replace('.json', '') → .replace('.workflow.ts', '')
  • readJsonFile() - Now extracts workflow ID via regex for TypeScript files
  • readWorkflowFile() - New async method for full workflow compilation
  • writeWorkflowFile() - Now writes TypeScript instead of JSON
  • refreshLocalState() - Uses hashWorkflow() for TypeScript files
  • Archive operations - Archives now saved as TypeScript
  • All hash calculations - Replaced WorkflowSanitizer.cleanForHash() with WorkflowTransformerAdapter.hashWorkflow() or hashWorkflowFromJson()

4. Dependencies Updated

File: packages/sync/package.json

Added transformer dependency:

"dependencies": {
    "@n8n-as-code/transformer": "0.1.0",
    ...
}

Technical Highlights

Hash Consistency Strategy

To ensure consistent hashing between local TypeScript and remote JSON workflows:

  1. Local files: Read TS → Compile to JSON → Normalize → Hash
  2. Remote workflows: Normalize JSON → Hash
  3. Normalization: Removes volatile fields (versionId, projectId, etc.)

This guarantees that TypeScript and JSON representations of the same workflow produce identical hashes.

Async Transformations

Many methods became async to support TypeScript compilation:

  • refreshLocalState() - Already async, now uses async hash computation
  • onLocalChange() - Already async, now uses async hash computation
  • resolveDuplicateIds() - Made async for hash computation
  • writeWorkflowFile() - Made async for TypeScript generation

ID Extraction Optimization

For quick ID extraction (avoiding full compilation):

// Quick regex extraction from @workflow({ id: "..." })
const idMatch = content.match(/@workflow\s*\(\s*{\s*id:\s*["']([^"']+)["']/);

Migration Impact

File Format Change

  • Before: my-workflow.json (JSON format)
  • After: my-workflow.workflow.ts (TypeScript with decorators)

Breaking Changes

  • Existing .json workflow files will NOT be automatically migrated
  • Users need to manually convert or re-pull workflows
  • .n8n-state.json may need reset if filenames change

Archive Format

  • Archives in .trash/ now stored as TypeScript files
  • Existing JSON archives remain readable but new ones use .workflow.ts

Verification

Build Status

npm run build -w @n8n-as-code/transformer ✅
npm run build -w @n8n-as-code/sync ✅

Type Safety

  • No TypeScript compilation errors
  • Proper type conversion between N8nWorkflow and IWorkflow
  • Tag conversion: string[] → ITag[] handled correctly

Next Steps

Phase 4: Adapt the skills package to:

  • Generate TypeScript documentation instead of JSON
  • Update workflow templates to TypeScript format
  • Modify n8n-agent to work with .workflow.ts files

Phase 5: Adapt CLI commands:

  • n8nac validate - Validate TypeScript syntax
  • n8nac convert - Convert JSON ↔ TypeScript

Phase 6: Documentation and integration testing:

  • Update README with TypeScript examples
  • Create migration guide for JSON → TypeScript
  • E2E tests for pull/push/sync cycle with TypeScript files