@meridianjs/workflow-engine 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,126 @@
+import { StepContext, MeridianContainer } from '@meridianjs/types';
+
+/**
+ * Returned by a step's invoke function to provide a separate
+ * compensateInput (the data the compensate function receives on rollback).
+ *
+ * If the invoke function returns a plain value (not a StepResponse),
+ * that value is used as both the step output AND the compensate input.
+ *
+ * @example
+ * async function invoke(input, ctx) {
+ *   const record = await svc.create(input)
+ *   return new StepResponse(record, { id: record.id })  // slim compensate input
+ * }
+ * async function compensate({ id }, ctx) {
+ *   await svc.delete(id)
+ * }
+ */
+declare class StepResponse<TOutput, TCompInput = TOutput> {
+    readonly output: TOutput;
+    readonly compensateInput: TCompInput;
+    constructor(output: TOutput, compensateInput: TCompInput);
+}
+
+/**
+ * Wraps the final return value of a workflow constructor function.
+ * The `output` becomes the `result` of the workflow run.
+ *
+ * @example
+ * createWorkflow("create-project", async (input) => {
+ *   const project = await createProjectStep(input)
+ *   return new WorkflowResponse(project)
+ * })
+ */
+declare class WorkflowResponse<T> {
+    readonly output: T;
+    constructor(output: T);
+}
+
+type InvokeFn<TInput, TOutput, TCompInput> = (input: TInput, ctx: StepContext) => Promise<TOutput | StepResponse<TOutput, TCompInput>>;
+type CompensateFn<TCompInput> = (input: TCompInput, ctx: StepContext) => Promise<void>;
+/**
+ * Defines a workflow step with an optional compensation (rollback) function.
+ *
+ * Returns a step function `(input: TInput) => Promise<TOutput>`.
+ * When called inside a workflow, automatically registers the compensation
+ * on the LIFO stack so it runs if a later step fails.
+ *
+ * @example
+ * const createProjectStep = createStep(
+ *   "create-project",
+ *   async (input: CreateProjectInput, { container }) => {
+ *     const svc = container.resolve("projectModuleService") as any
+ *     const project = await svc.createProject(input)
+ *     return new StepResponse(project, { projectId: project.id })
+ *   },
+ *   async ({ projectId }, { container }) => {
+ *     const svc = container.resolve("projectModuleService") as any
+ *     await svc.deleteProject(projectId)
+ *   }
+ * )
+ */
+declare function createStep<TInput, TOutput, TCompInput = TOutput>(name: string, invoke: InvokeFn<TInput, TOutput, TCompInput>, compensate?: CompensateFn<TCompInput>): (input: TInput) => Promise<TOutput>;
+
+type WorkflowTransactionStatus = "done" | "reverted" | "failed";
+interface WorkflowResult<TOutput> {
+    result: TOutput;
+    errors: Error[];
+    transaction_status: WorkflowTransactionStatus;
+}
+interface WorkflowRunner<TInput, TOutput> {
+    run(opts: {
+        input: TInput;
+    }): Promise<WorkflowResult<TOutput>>;
+}
+/**
+ * Defines a named workflow with a constructor function that orchestrates steps.
+ *
+ * Returns a factory `(container) => WorkflowRunner` so each request gets
+ * its own isolated run context with a fresh compensation stack.
+ *
+ * If any step throws, compensations run in LIFO order (saga pattern).
+ * Compensation errors are collected but do not re-throw.
+ *
+ * @example
+ * export const createProjectWorkflow = createWorkflow(
+ *   "create-project",
+ *   async (input: CreateProjectInput) => {
+ *     const project = await createProjectStep(input)
+ *     const _ = await logActivityStep({ entity_type: "project", entity_id: project.id })
+ *     return new WorkflowResponse(project)
+ *   }
+ * )
+ *
+ * // In a route handler:
+ * const { result, errors, transaction_status } = await createProjectWorkflow(req.scope).run({ input: req.body })
+ */
+declare function createWorkflow<TInput, TOutput>(name: string, constructorFn: (input: TInput) => Promise<WorkflowResponse<TOutput>>): (container: MeridianContainer) => WorkflowRunner<TInput, TOutput>;
+
+/**
+ * Transforms a step output value using a mapping function.
+ * A thin utility to make data transformations explicit in workflow constructors.
+ *
+ * @example
+ * const project = await createProjectStep(input)
+ * const activityInput = transform(project, (p) => ({
+ *   entity_type: "project" as const,
+ *   entity_id: p.id,
+ *   workspace_id: p.workspace_id,
+ * }))
+ * await logActivityStep(activityInput)
+ */
+declare function transform<T, U>(input: T, fn: (value: T) => U): U;
+/**
+ * Conditionally executes a step or block of code within a workflow.
+ * Returns undefined if the condition is false.
+ *
+ * @example
+ * const notification = await when(
+ *   !!input.assignee_id,
+ *   () => notifyAssigneeStep({ issue_id: issue.id, assignee_id: input.assignee_id! })
+ * )
+ */
+declare function when<T>(condition: boolean, fn: () => Promise<T>): Promise<T | undefined>;
+
+export { StepResponse, WorkflowResponse, type WorkflowResult, type WorkflowRunner, type WorkflowTransactionStatus, createStep, createWorkflow, transform, when };

package/dist/index.d.ts

@@ -0,0 +1,126 @@
+import { StepContext, MeridianContainer } from '@meridianjs/types';
+
+/**
+ * Returned by a step's invoke function to provide a separate
+ * compensateInput (the data the compensate function receives on rollback).
+ *
+ * If the invoke function returns a plain value (not a StepResponse),
+ * that value is used as both the step output AND the compensate input.
+ *
+ * @example
+ * async function invoke(input, ctx) {
+ *   const record = await svc.create(input)
+ *   return new StepResponse(record, { id: record.id })  // slim compensate input
+ * }
+ * async function compensate({ id }, ctx) {
+ *   await svc.delete(id)
+ * }
+ */
+declare class StepResponse<TOutput, TCompInput = TOutput> {
+    readonly output: TOutput;
+    readonly compensateInput: TCompInput;
+    constructor(output: TOutput, compensateInput: TCompInput);
+}
+
+/**
+ * Wraps the final return value of a workflow constructor function.
+ * The `output` becomes the `result` of the workflow run.
+ *
+ * @example
+ * createWorkflow("create-project", async (input) => {
+ *   const project = await createProjectStep(input)
+ *   return new WorkflowResponse(project)
+ * })
+ */
+declare class WorkflowResponse<T> {
+    readonly output: T;
+    constructor(output: T);
+}
+
+type InvokeFn<TInput, TOutput, TCompInput> = (input: TInput, ctx: StepContext) => Promise<TOutput | StepResponse<TOutput, TCompInput>>;
+type CompensateFn<TCompInput> = (input: TCompInput, ctx: StepContext) => Promise<void>;
+/**
+ * Defines a workflow step with an optional compensation (rollback) function.
+ *
+ * Returns a step function `(input: TInput) => Promise<TOutput>`.
+ * When called inside a workflow, automatically registers the compensation
+ * on the LIFO stack so it runs if a later step fails.
+ *
+ * @example
+ * const createProjectStep = createStep(
+ *   "create-project",
+ *   async (input: CreateProjectInput, { container }) => {
+ *     const svc = container.resolve("projectModuleService") as any
+ *     const project = await svc.createProject(input)
+ *     return new StepResponse(project, { projectId: project.id })
+ *   },
+ *   async ({ projectId }, { container }) => {
+ *     const svc = container.resolve("projectModuleService") as any
+ *     await svc.deleteProject(projectId)
+ *   }
+ * )
+ */
+declare function createStep<TInput, TOutput, TCompInput = TOutput>(name: string, invoke: InvokeFn<TInput, TOutput, TCompInput>, compensate?: CompensateFn<TCompInput>): (input: TInput) => Promise<TOutput>;
+
+type WorkflowTransactionStatus = "done" | "reverted" | "failed";
+interface WorkflowResult<TOutput> {
+    result: TOutput;
+    errors: Error[];
+    transaction_status: WorkflowTransactionStatus;
+}
+interface WorkflowRunner<TInput, TOutput> {
+    run(opts: {
+        input: TInput;
+    }): Promise<WorkflowResult<TOutput>>;
+}
+/**
+ * Defines a named workflow with a constructor function that orchestrates steps.
+ *
+ * Returns a factory `(container) => WorkflowRunner` so each request gets
+ * its own isolated run context with a fresh compensation stack.
+ *
+ * If any step throws, compensations run in LIFO order (saga pattern).
+ * Compensation errors are collected but do not re-throw.
+ *
+ * @example
+ * export const createProjectWorkflow = createWorkflow(
+ *   "create-project",
+ *   async (input: CreateProjectInput) => {
+ *     const project = await createProjectStep(input)
+ *     const _ = await logActivityStep({ entity_type: "project", entity_id: project.id })
+ *     return new WorkflowResponse(project)
+ *   }
+ * )
+ *
+ * // In a route handler:
+ * const { result, errors, transaction_status } = await createProjectWorkflow(req.scope).run({ input: req.body })
+ */
+declare function createWorkflow<TInput, TOutput>(name: string, constructorFn: (input: TInput) => Promise<WorkflowResponse<TOutput>>): (container: MeridianContainer) => WorkflowRunner<TInput, TOutput>;
+
+/**
+ * Transforms a step output value using a mapping function.
+ * A thin utility to make data transformations explicit in workflow constructors.
+ *
+ * @example
+ * const project = await createProjectStep(input)
+ * const activityInput = transform(project, (p) => ({
+ *   entity_type: "project" as const,
+ *   entity_id: p.id,
+ *   workspace_id: p.workspace_id,
+ * }))
+ * await logActivityStep(activityInput)
+ */
+declare function transform<T, U>(input: T, fn: (value: T) => U): U;
+/**
+ * Conditionally executes a step or block of code within a workflow.
+ * Returns undefined if the condition is false.
+ *
+ * @example
+ * const notification = await when(
+ *   !!input.assignee_id,
+ *   () => notifyAssigneeStep({ issue_id: issue.id, assignee_id: input.assignee_id! })
+ * )
+ */
+declare function when<T>(condition: boolean, fn: () => Promise<T>): Promise<T | undefined>;
+
+export { StepResponse, WorkflowResponse, type WorkflowResult, type WorkflowRunner, type WorkflowTransactionStatus, createStep, createWorkflow, transform, when };

package/dist/index.js

@@ -0,0 +1,139 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  StepResponse: () => StepResponse,
+  WorkflowResponse: () => WorkflowResponse,
+  createStep: () => createStep,
+  createWorkflow: () => createWorkflow,
+  transform: () => transform,
+  when: () => when
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/step-response.ts
+var StepResponse = class {
+  constructor(output, compensateInput) {
+    this.output = output;
+    this.compensateInput = compensateInput;
+  }
+};
+
+// src/workflow-response.ts
+var WorkflowResponse = class {
+  constructor(output) {
+    this.output = output;
+  }
+};
+
+// src/run-context.ts
+var import_node_async_hooks = require("async_hooks");
+var workflowRunContext = new import_node_async_hooks.AsyncLocalStorage();
+function getWorkflowRunContext() {
+  const ctx = workflowRunContext.getStore();
+  if (!ctx) {
+    throw new Error(
+      "No active workflow context. Steps must be called inside a createWorkflow constructor function."
+    );
+  }
+  return ctx;
+}
+
+// src/create-step.ts
+function createStep(name, invoke, compensate) {
+  return async (input) => {
+    const runCtx = getWorkflowRunContext();
+    const stepCtx = { container: runCtx.container };
+    const result = await invoke(input, stepCtx);
+    let output;
+    let compInput;
+    if (result instanceof StepResponse) {
+      output = result.output;
+      compInput = result.compensateInput;
+    } else {
+      output = result;
+      compInput = result;
+    }
+    if (compensate) {
+      const capturedCompInput = compInput;
+      runCtx.compensationStack.push(
+        async () => compensate(capturedCompInput, stepCtx)
+      );
+    }
+    return output;
+  };
+}
+
+// src/create-workflow.ts
+function createWorkflow(name, constructorFn) {
+  return (container) => ({
+    async run({ input }) {
+      const context = {
+        container,
+        compensationStack: []
+      };
+      try {
+        const response = await workflowRunContext.run(
+          context,
+          () => constructorFn(input)
+        );
+        return {
+          result: response.output,
+          errors: [],
+          transaction_status: "done"
+        };
+      } catch (error) {
+        const errors = [error];
+        const stack = [...context.compensationStack].reverse();
+        for (const compensate of stack) {
+          try {
+            await compensate();
+          } catch (compError) {
+            errors.push(compError);
+          }
+        }
+        return {
+          result: void 0,
+          errors,
+          transaction_status: "reverted"
+        };
+      }
+    }
+  });
+}
+
+// src/transform.ts
+function transform(input, fn) {
+  return fn(input);
+}
+async function when(condition, fn) {
+  if (condition) return fn();
+  return void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StepResponse,
+  WorkflowResponse,
+  createStep,
+  createWorkflow,
+  transform,
+  when
+});

package/dist/index.mjs

@@ -0,0 +1,107 @@
+// src/step-response.ts
+var StepResponse = class {
+  constructor(output, compensateInput) {
+    this.output = output;
+    this.compensateInput = compensateInput;
+  }
+};
+
+// src/workflow-response.ts
+var WorkflowResponse = class {
+  constructor(output) {
+    this.output = output;
+  }
+};
+
+// src/run-context.ts
+import { AsyncLocalStorage } from "async_hooks";
+var workflowRunContext = new AsyncLocalStorage();
+function getWorkflowRunContext() {
+  const ctx = workflowRunContext.getStore();
+  if (!ctx) {
+    throw new Error(
+      "No active workflow context. Steps must be called inside a createWorkflow constructor function."
+    );
+  }
+  return ctx;
+}
+
+// src/create-step.ts
+function createStep(name, invoke, compensate) {
+  return async (input) => {
+    const runCtx = getWorkflowRunContext();
+    const stepCtx = { container: runCtx.container };
+    const result = await invoke(input, stepCtx);
+    let output;
+    let compInput;
+    if (result instanceof StepResponse) {
+      output = result.output;
+      compInput = result.compensateInput;
+    } else {
+      output = result;
+      compInput = result;
+    }
+    if (compensate) {
+      const capturedCompInput = compInput;
+      runCtx.compensationStack.push(
+        async () => compensate(capturedCompInput, stepCtx)
+      );
+    }
+    return output;
+  };
+}
+
+// src/create-workflow.ts
+function createWorkflow(name, constructorFn) {
+  return (container) => ({
+    async run({ input }) {
+      const context = {
+        container,
+        compensationStack: []
+      };
+      try {
+        const response = await workflowRunContext.run(
+          context,
+          () => constructorFn(input)
+        );
+        return {
+          result: response.output,
+          errors: [],
+          transaction_status: "done"
+        };
+      } catch (error) {
+        const errors = [error];
+        const stack = [...context.compensationStack].reverse();
+        for (const compensate of stack) {
+          try {
+            await compensate();
+          } catch (compError) {
+            errors.push(compError);
+          }
+        }
+        return {
+          result: void 0,
+          errors,
+          transaction_status: "reverted"
+        };
+      }
+    }
+  });
+}
+
+// src/transform.ts
+function transform(input, fn) {
+  return fn(input);
+}
+async function when(condition, fn) {
+  if (condition) return fn();
+  return void 0;
+}
+export {
+  StepResponse,
+  WorkflowResponse,
+  createStep,
+  createWorkflow,
+  transform,
+  when
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@meridianjs/workflow-engine",
+  "version": "0.1.0",
+  "description": "Meridian workflow engine — DAG runner with LIFO saga compensation",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@meridianjs/types": "^0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "*"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}