@zola_do/workflow-engine

State machine workflow converter for NestJS. Converts UI JSON (node/edge graph) to XState-compatible state machine definitions.

Installation

# Install individually
npm install @zola_do/workflow-engine

# Or via meta package
npm install @zola_do/nestjs-shared

Usage

Module Setup

Register WorkflowEngineService in your module:

import { Module } from '@nestjs/common';
import { WorkflowEngineService } from '@zola_do/workflow-engine';

@Module({
  providers: [WorkflowEngineService],
  exports: [WorkflowEngineService],
})
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:

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
  }
}

Input Format

• nodes: Array of { id, type, data: { label } }. type: 'start' denotes the initial node.
• edges: Array of { source, target, label? }. Defines transitions between states.

Output Format

Returns an object with:

• id — UUID
• initial — Initial state label
• states — Map of state labels to { on: { EVENT: targetState }, meta: { type } }

Exports

• WorkflowEngineService — convertToStateMachine(uiJson)

Related Packages

• @zola_do/core — Shared types