@zola_do/workflow-engine 0.2.4 → 0.2.6

package/README.md

@@ -1,7 +1,20 @@
 # @zola_do/workflow-engine
 
+[![npm version](https://img.shields.io/npm/v/@zola_do/workflow-engine.svg)](https://www.npmjs.com/package/@zola_do/workflow-engine)
+[![npm downloads](https://img.shields.io/npm/dm/@zola_do/workflow-engine.svg)](https://www.npmjs.com/package/@zola_do/workflow-engine)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
 State machine workflow converter for NestJS. Converts UI JSON (node/edge graph) to XState-compatible state machine definitions.
 
+## Overview
+
+`@zola_do/workflow-engine` provides:
+
+- **UI JSON Conversion** — Transform React Flow / node-editor JSON to state machines
+- **XState Compatibility** — Output suitable for XState or similar libraries
+- **Node Type Support** — Handles start, parallel, and custom node types
+- **State Transitions** — Automatic edge-to-transition mapping
+
 ## Installation
 
 ```bash
@@ -12,15 +25,13 @@ npm install @zola_do/workflow-engine
 npm install @zola_do/nestjs-shared
 ```
 
-## Usage
+## Quick Start
 
-### Module Setup
-
-Register `WorkflowEngineService` in your module:
+### 1. Register Service
 
 ```typescript
-import { Module } from '@nestjs/common';
-import { WorkflowEngineService } from '@zola_do/workflow-engine';
+import { Module } from "@nestjs/common";
+import { WorkflowEngineService } from "@zola_do/workflow-engine";
 
 @Module({
   providers: [WorkflowEngineService],
@@ -29,45 +40,467 @@ import { WorkflowEngineService } from '@zola_do/workflow-engine';
 export class WorkflowModule {}
 ```
 
-### Converting UI JSON to State Machine
-
-The service converts a React Flow / node-editor style JSON (nodes and edges) into a state machine definition:
+### 2. Convert Workflow
 
 ```typescript
-import { Injectable } from '@nestjs/common';
-import { WorkflowEngineService } from '@zola_do/workflow-engine';
+import { Injectable } from "@nestjs/common";
+import { WorkflowEngineService } from "@zola_do/workflow-engine";
 
 @Injectable()
 export class WorkflowController {
   constructor(private readonly workflowEngine: WorkflowEngineService) {}
 
-  async convertWorkflow(uiJson: {
-    nodes: Array<{ id: string; type: string; data: { label: string } }>;
-    edges: Array<{ source: string; target: string; label?: string }>;
-  }) {
-    const machine = await this.workflowEngine.convertToStateMachine(uiJson);
-    return machine;
-    // Returns { id, initial, states } suitable for XState or similar
+  @Post("workflows/:id/compile")
+  async compileWorkflow(@Param("id") id: string) {
+    const uiJson = await this.workflowService.getUiJson(id);
+
+    const stateMachine = this.workflowEngine.convertToStateMachine(uiJson);
+
+    return {
+      definition: stateMachine,
+      xstateReady: true,
+    };
   }
 }
 ```
 
-### Input Format
+## Workflow Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    Workflow Conversion Flow                          │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  UI Editor (React Flow)                                             │
+│  ┌─────────────────────────────────────────┐                        │
+│  │  nodes: [                               │                        │
+│  │    { id: '1', type: 'start', ... },    │                        │
+│  │    { id: '2', type: 'task', ... },      │                        │
+│  │    { id: '3', type: 'end', ... }        │                        │
+│  │  ]                                      │                        │
+│  │  edges: [                                │                        │
+│  │    { source: '1', target: '2' },        │                        │
+│  │    { source: '2', target: '3' }         │                        │
+│  │  ]                                      │                        │
+│  └────────────────────┬────────────────────┘                        │
+│                       │                                               │
+│                       │ convertToStateMachine()                       │
+│                       ▼                                               │
+│  ┌─────────────────────────────────────────┐                        │
+│  │  State Machine Definition               │                        │
+│  │                                         │                        │
+│  │  {                                      │                        │
+│  │    id: 'workflow-uuid',                 │                        │
+│  │    initial: 'Start',                    │                        │
+│  │    states: {                            │                        │
+│  │      Start: {                          │                        │
+│  │        on: { NEXT: 'Task' }            │                        │
+│  │      },                                 │                        │
+│  │      Task: {                            │                        │
+│  │        on: { DONE: 'End' }              │                        │
+│  │      },                                 │                        │
+│  │      End: { type: 'final' }             │                        │
+│  │    }                                    │                        │
+│  │  }                                      │                        │
+│  └─────────────────────────────────────────┘                        │
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## Input Format
+
+### Node Types
+
+```typescript
+interface WorkflowNode {
+  id: string;
+  type: "start" | "end" | "task" | "condition" | "parallel" | string;
+  data: {
+    label?: string;
+    [key: string]: any;
+  };
+  position?: { x: number; y: number };
+}
+```
+
+### Edge Types
+
+```typescript
+interface WorkflowEdge {
+  id?: string;
+  source: string; // Source node ID
+  target: string; // Target node ID
+  label?: string; // Event/transition name
+  data?: {
+    condition?: string; // For conditional edges
+    [key: string]: any;
+  };
+}
+```
+
+### Example UI JSON
+
+```typescript
+const uiJson = {
+  nodes: [
+    {
+      id: "node-1",
+      type: "start",
+      data: { label: "Start" },
+      position: { x: 100, y: 100 },
+    },
+    {
+      id: "node-2",
+      type: "task",
+      data: { label: "Review Application" },
+      position: { x: 300, y: 100 },
+    },
+    {
+      id: "node-3",
+      type: "condition",
+      data: { label: "Approved?" },
+      position: { x: 500, y: 100 },
+    },
+    {
+      id: "node-4",
+      type: "task",
+      data: { label: "Send Approval Email" },
+      position: { x: 700, y: 50 },
+    },
+    {
+      id: "node-5",
+      type: "task",
+      data: { label: "Send Rejection Email" },
+      position: { x: 700, y: 150 },
+    },
+    {
+      id: "node-6",
+      type: "end",
+      data: { label: "End" },
+      position: { x: 900, y: 100 },
+    },
+  ],
+  edges: [
+    { source: "node-1", target: "node-2" },
+    { source: "node-2", target: "node-3" },
+    { source: "node-3", target: "node-4", label: "YES" },
+    { source: "node-3", target: "node-5", label: "NO" },
+    { source: "node-4", target: "node-6" },
+    { source: "node-5", target: "node-6" },
+  ],
+};
+```
+
+## Output Format
+
+### State Machine Structure
+
+```typescript
+interface StateMachine {
+  id: string; // UUID
+  initial: string; // Initial state name
+  states: {
+    [stateName: string]: {
+      type?: "final" | "atomic";
+      on?: {
+        [event: string]: string | StateMachine;
+      };
+      meta?: {
+        type?: string;
+        [key: string]: any;
+      };
+      states?: {
+        [nestedState: string]: any;
+      };
+    };
+  };
+}
+```
+
+### Example Output
+
+```typescript
+const stateMachine = {
+  id: "550e8400-e29b-41d4-a716-446655440000",
+  initial: "Start",
+  states: {
+    Start: {
+      on: { NEXT: "Review Application" },
+      meta: { type: "start" },
+    },
+    "Review Application": {
+      on: { NEXT: "Approved?" },
+      meta: { type: "task" },
+    },
+    "Approved?": {
+      on: {
+        YES: "Send Approval Email",
+        NO: "Send Rejection Email",
+      },
+      meta: { type: "condition" },
+    },
+    "Send Approval Email": {
+      on: { NEXT: "End" },
+      meta: { type: "task" },
+    },
+    "Send Rejection Email": {
+      on: { NEXT: "End" },
+      meta: { type: "task" },
+    },
+    End: {
+      type: "final",
+      meta: { type: "end" },
+    },
+  },
+};
+```
+
+## Node Type Handling
+
+### Start Node
+
+```typescript
+{
+  id: 'node-1',
+  type: 'start',
+  data: { label: 'Start' },
+}
+// Becomes: initial state in output
+```
+
+### End Node
+
+```typescript
+{
+  id: 'node-2',
+  type: 'end',
+  data: { label: 'End' },
+}
+// Becomes: { type: 'final' } state
+```
+
+### Task Node
+
+```typescript
+{
+  id: 'node-3',
+  type: 'task',
+  data: { label: 'Process Order' },
+}
+// Becomes: { on: { NEXT: 'nextState' }, meta: { type: 'task' } }
+```
+
+### Condition Node
+
+```typescript
+{
+  id: 'node-4',
+  type: 'condition',
+  data: { label: 'Is Valid?' },
+}
+// Becomes: { on: { YES: 'trueState', NO: 'falseState' } }
+```
+
+### Parallel Node
+
+```typescript
+{
+  id: 'node-5',
+  type: 'parallel',
+  data: { label: 'Parallel Tasks' },
+}
+// Becomes: { type: 'parallel', states: { ... } }
+```
+
+## Real-World Examples
 
-- **nodes:** Array of `{ id, type, data: { label } }`. `type: 'start'` denotes the initial node.
-- **edges:** Array of `{ source, target, label? }`. Defines transitions between states.
+### Approval Workflow
 
-### Output Format
+```typescript
+const approvalWorkflow = {
+  nodes: [
+    { id: "1", type: "start", data: { label: "Submit" } },
+    { id: "2", type: "task", data: { label: "Manager Review" } },
+    { id: "3", type: "condition", data: { label: "Approved?" } },
+    { id: "4", type: "task", data: { label: "Send Approval" } },
+    { id: "5", type: "task", data: { label: "Notify Rejection" } },
+    { id: "6", type: "end", data: { label: "Done" } },
+  ],
+  edges: [
+    { source: "1", target: "2" },
+    { source: "2", target: "3" },
+    { source: "3", target: "4", label: "YES" },
+    { source: "3", target: "5", label: "NO" },
+    { source: "4", target: "6" },
+    { source: "5", target: "6" },
+  ],
+};
+
+const stateMachine = workflowEngine.convertToStateMachine(approvalWorkflow);
+```
+
+### Multi-Step Form
+
+```typescript
+const formWorkflow = {
+  nodes: [
+    { id: "s1", type: "start", data: { label: "Step 1" } },
+    { id: "s2", type: "task", data: { label: "Personal Info" } },
+    { id: "s3", type: "task", data: { label: "Address" } },
+    { id: "s4", type: "task", data: { label: "Payment" } },
+    { id: "s5", type: "condition", data: { label: "Valid?" } },
+    { id: "s6", type: "end", data: { label: "Complete" } },
+  ],
+  edges: [
+    { source: "s1", target: "s2" },
+    { source: "s2", target: "s3" },
+    { source: "s3", target: "s4" },
+    { source: "s4", target: "s5" },
+    { source: "s5", target: "s6", label: "YES" },
+    { source: "s5", target: "s2", label: "NO" }, // Go back
+  ],
+};
+```
+
+## XState Integration
+
+The output is compatible with XState:
+
+```typescript
+import { createMachine } from "xstate";
+import { interpret } from "xstate";
+
+const machine = createMachine(stateMachine);
+
+const actor = interpret(machine).start();
+
+actor.send({ type: "NEXT" }); // Transition to next state
+actor.send({ type: "YES" }); // Transition on condition
+```
+
+### Full XState Example
+
+```typescript
+import { createMachine, interpret } from "xstate";
+
+@Controller("workflows")
+export class WorkflowExecutionController {
+  @Post(":id/execute")
+  async executeWorkflow(@Param("id") id: string) {
+    const definition = await this.workflowService.getCompiledDefinition(id);
+    const machine = createMachine(definition);
+
+    const actor = interpret(machine)
+      .onTransition((state) => {
+        console.log("Current state:", state.value);
+      })
+      .start();
+
+    // Execute workflow steps
+    const result = await this.executeSteps(actor, definition);
+
+    return result;
+  }
+
+  private async executeSteps(actor: any, definition: any) {
+    const states = Object.keys(definition.states);
+    for (const state of states) {
+      if (definition.states[state].type === "final") {
+        break;
+      }
+      await this.performStateAction(state);
+      actor.send({ type: "NEXT" });
+    }
+    return { completed: true };
+  }
+}
+```
+
+## API Reference
+
+### Service
+
+```typescript
+class WorkflowEngineService {
+  convertToStateMachine(uiJson: UiJson): StateMachine;
+}
+```
+
+### Types
+
+```typescript
+interface UiJson {
+  nodes: WorkflowNode[];
+  edges: WorkflowEdge[];
+}
+
+interface WorkflowNode {
+  id: string;
+  type: string;
+  data: Record<string, any>;
+  position?: { x: number; y: number };
+}
+
+interface WorkflowEdge {
+  id?: string;
+  source: string;
+  target: string;
+  label?: string;
+  data?: Record<string, any>;
+}
+
+interface StateMachine {
+  id: string;
+  initial: string;
+  states: Record<string, any>;
+}
+```
+
+## Troubleshooting
+
+### Q: Node label not used?
+
+Ensure nodes have a `data.label` property:
+
+```typescript
+// ❌ No label
+{ id: '1', type: 'start' }
+
+// ✅ With label
+{ id: '1', type: 'start', data: { label: 'Start' } }
+```
+
+### Q: Edge transitions not working?
+
+Check edge labels match expected events:
+
+```typescript
+// For condition nodes, edge labels become transition events
+{ source: '3', target: '4', label: 'YES' }
+// Triggers: state.on.YES
+```
+
+### Q: Parallel nodes not handled?
+
+Parallel nodes create nested state configurations:
+
+```typescript
+{
+  type: 'parallel',
+  states: {
+    trackA: { initial: 'a1', states: { a1: {}, a2: {} } },
+    trackB: { initial: 'b1', states: { b1: {}, b2: {} } },
+  },
+}
+```
 
-Returns an object with:
+## Related Packages
 
-- `id` — UUID
-- `initial` — Initial state label
-- `states` — Map of state labels to `{ on: { EVENT: targetState }, meta: { type } }`
+None - standalone workflow package
 
-## Exports
+## License
 
-- `WorkflowEngineService` — `convertToStateMachine(uiJson)`
+ISC
 
 ## Community
 

package/dist/workflow-engine.service.d.ts

@@ -1,3 +1,6 @@
 export declare class WorkflowEngineService {
-    convertToStateMachine(uiJson: any): Promise<{}>;
+    convertToStateMachine(uiJson: any): Promise<{
+        schemaVersion: number;
+        definition: Record<string, any>;
+    }>;
 }

package/dist/workflow-engine.service.js

@@ -39,7 +39,7 @@ let WorkflowEngineService = class WorkflowEngineService {
                 meta: nodeMetaData,
             };
         });
-        return machine;
+        return { schemaVersion: 1, definition: machine };
     }
 };
 exports.WorkflowEngineService = WorkflowEngineService;

package/dist/workflow-engine.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-engine.service.js","sourceRoot":"","sources":["../src/workflow-engine.service.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA4C;AAC5C,mCAAoC;AAG7B,IAAM,qBAAqB,GAA3B,MAAM,qBAAqB;IAChC,KAAK,CAAC,qBAAqB,CAAC,MAAW;QACrC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3B,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;QAC9D,MAAM,OAAO,GAAG,EAAE,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAA,mBAAU,GAAE,CAAC;QAC7B,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC;QAC1C,OAAO,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YACxB,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;YAInE,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAChC,OAAO,CAAC,GAAG,CAAC,YAAY,OAAO,CAAC,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;YAC9D,CAAC;YACD,MAAM,UAAU,GAAG,EAAE,CAAC;YACtB,MAAM,YAAY,GAAG,EAAE,CAAC;YACxB,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;gBACjC,MAAM,KAAK,GACT,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;oBACjC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;oBAC1B,CAAC,CAAC,QAAQ,CAAC;gBACf,UAAU,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CACjC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,MAAM,CAC5B,CAAC,IAAI,CAAC,KAAK,CAAC;YACf,CAAC;YACD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACzE,YAAY,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;YAC5B,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;YACtC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,UAAU,EAAE,CAAC,GAAG;gBACnC,EAAE,EAAE,UAAU;gBACd,IAAI,EAAE,YAAY;aACnB,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,OAAO,OAAO,CAAC;IACjB,CAAC;CACF,CAAA;AAvCY,sDAAqB;gCAArB,qBAAqB;IADjC,IAAA,mBAAU,GAAE;GACA,qBAAqB,CAuCjC"}
+{"version":3,"file":"workflow-engine.service.js","sourceRoot":"","sources":["../src/workflow-engine.service.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA4C;AAC5C,mCAAoC;AAG7B,IAAM,qBAAqB,GAA3B,MAAM,qBAAqB;IAChC,KAAK,CAAC,qBAAqB,CAAC,MAAW;QACrC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3B,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;QAC9D,MAAM,OAAO,GAAwB,EAAE,CAAC;QACxC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAA,mBAAU,GAAE,CAAC;QAC7B,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC;QAC1C,OAAO,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YACxB,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;YAInE,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAChC,OAAO,CAAC,GAAG,CAAC,YAAY,OAAO,CAAC,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;YAC9D,CAAC;YACD,MAAM,UAAU,GAAG,EAAE,CAAC;YACtB,MAAM,YAAY,GAAG,EAAE,CAAC;YACxB,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;gBACjC,MAAM,KAAK,GACT,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;oBACjC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;oBAC1B,CAAC,CAAC,QAAQ,CAAC;gBACf,UAAU,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CACjC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,MAAM,CAC5B,CAAC,IAAI,CAAC,KAAK,CAAC;YACf,CAAC;YACD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACzE,YAAY,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;YAC5B,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;YACtC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,UAAU,EAAE,CAAC,GAAG;gBACnC,EAAE,EAAE,UAAU;gBACd,IAAI,EAAE,YAAY;aACnB,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IACnD,CAAC;CACF,CAAA;AAvCY,sDAAqB;gCAArB,qBAAqB;IADjC,IAAA,mBAAU,GAAE;GACA,qBAAqB,CAuCjC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zola_do/workflow-engine",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "State machine workflow converter for NestJS",
   "author": "zolaDO",
   "license": "ISC",