@qualsoft/workflow-core

Core workflow engine and type definitions used by Qualsoft workflow-enabled applications. This package provides the workflow engine, state store interface, and helper utilities for driving step-based workflows.

Installation

npm install @qualsoft/workflow-core

Interface overview

Exports

import {
  WorkflowEngine,
  NoopActionRunner,
  resolveSteps,
  findAction,
  findStep,
  type WorkflowStateStore,
  type StepWorkflowDefinition,
  type WorkflowRecord,
  type WorkflowContext,
  type WorkflowRunInput,
  type WorkflowRunResult
} from '@qualsoft/workflow-core';

State store contract

Implement WorkflowStateStore to connect the engine to your persistence layer:

const stateStore: WorkflowStateStore = {
  async getWorkflowDefinition(formId, workflowId) {
    // Load definition
  },
  async getRecord(formId, recordId) {
    // Load record
  },
  async updateRecord(formId, recordId, payload) {
    // Persist updated record fields
  }
};

Running a workflow action

const engine = new WorkflowEngine({
  stateStore,
  actionRunner: new NoopActionRunner()
});

const result = await engine.run({
  formId: 'forms-123',
  workflowId: 'workflow-abc',
  recordId: 'record-789',
  actionId: 'approve-action',
  context: {
    user: { email: '[email protected]' },
    timestamp: new Date().toISOString()
  }
});

console.log(result.updatedRecord.statut);

Action runners on step entry

Workflow steps can define actionRunners that run when a record enters a step or after a delay. Each runner specifies a type (ex: assignUser, assignRole, updateRecordFields, notifyUser, slaTimer) and a trigger:

steps: [
  {
    id: 'review',
    label: 'Revue',
    actor: 'role',
    role: 'quality',
    fields: [],
    actions: [],
    actionRunners: [
      {
        id: 'review-notify',
        label: 'Notifier le responsable',
        type: 'notifyUser',
        trigger: {
          type: 'afterDelay',
          delay: { value: 2, unit: 'days', source: 'stepEntry' }
        },
        payload: {
          subject: 'Relance revue',
          message: 'Une revue est en attente.'
        }
      }
    ]
  }
]

The engine executes immediate runners via the ActionRunner interface and schedules delayed runners via scheduleTask.

Build

npm run build

The compiled JavaScript and type declarations are output to lib/.

Publish

npm version patch && npm publish --access public

The prepare script runs the build automatically during publish.