@rytejs/core 0.6.0 → 0.7.0

package/dist/chunk-YTJGSTKG.js

@@ -0,0 +1,19 @@
+// src/compose.ts
+function compose(middleware) {
+  return async (ctx) => {
+    let index = -1;
+    async function dispatch(i) {
+      if (i <= index) throw new Error("next() called multiple times");
+      index = i;
+      const fn = middleware[i];
+      if (!fn) return;
+      await fn(ctx, () => dispatch(i + 1));
+    }
+    await dispatch(0);
+  };
+}
+
+export {
+  compose
+};
+//# sourceMappingURL=chunk-YTJGSTKG.js.map

package/dist/chunk-YTJGSTKG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/compose.ts"],"sourcesContent":["type Middleware<TCtx> = (ctx: TCtx, next: () => Promise<void>) => Promise<void>;\n\n/** Composes an array of middleware into a single function (Koa-style onion model). */\nexport function compose<TCtx>(middleware: Middleware<TCtx>[]): (ctx: TCtx) => Promise<void> {\n\treturn async (ctx: TCtx) => {\n\t\tlet index = -1;\n\t\tasync function dispatch(i: number): Promise<void> {\n\t\t\tif (i <= index) throw new Error(\"next() called multiple times\");\n\t\t\tindex = i;\n\t\t\tconst fn = middleware[i];\n\t\t\tif (!fn) return;\n\t\t\tawait fn(ctx, () => dispatch(i + 1));\n\t\t}\n\t\tawait dispatch(0);\n\t};\n}\n"],"mappings":";AAGO,SAAS,QAAc,YAA8D;AAC3F,SAAO,OAAO,QAAc;AAC3B,QAAI,QAAQ;AACZ,mBAAe,SAAS,GAA0B;AACjD,UAAI,KAAK,MAAO,OAAM,IAAI,MAAM,8BAA8B;AAC9D,cAAQ;AACR,YAAM,KAAK,WAAW,CAAC;AACvB,UAAI,CAAC,GAAI;AACT,YAAM,GAAG,KAAK,MAAM,SAAS,IAAI,CAAC,CAAC;AAAA,IACpC;AACA,UAAM,SAAS,CAAC;AAAA,EACjB;AACD;","names":[]}

package/dist/chunk-ZFRIE42B.js

@@ -0,0 +1,17 @@
+// src/store/errors.ts
+var ConcurrencyConflictError = class extends Error {
+  constructor(workflowId, expectedVersion, actualVersion) {
+    super(
+      `Concurrency conflict for workflow "${workflowId}": expected version ${expectedVersion}, actual ${actualVersion}`
+    );
+    this.workflowId = workflowId;
+    this.expectedVersion = expectedVersion;
+    this.actualVersion = actualVersion;
+  }
+  name = "ConcurrencyConflictError";
+};
+
+export {
+  ConcurrencyConflictError
+};
+//# sourceMappingURL=chunk-ZFRIE42B.js.map

package/dist/chunk-ZFRIE42B.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/store/errors.ts"],"sourcesContent":["export class ConcurrencyConflictError extends Error {\n\treadonly name = \"ConcurrencyConflictError\";\n\n\tconstructor(\n\t\treadonly workflowId: string,\n\t\treadonly expectedVersion: number,\n\t\treadonly actualVersion: number,\n\t) {\n\t\tsuper(\n\t\t\t`Concurrency conflict for workflow \"${workflowId}\": expected version ${expectedVersion}, actual ${actualVersion}`,\n\t\t);\n\t}\n}\n"],"mappings":";AAAO,IAAM,2BAAN,cAAuC,MAAM;AAAA,EAGnD,YACU,YACA,iBACA,eACR;AACD;AAAA,MACC,sCAAsC,UAAU,uBAAuB,eAAe,YAAY,aAAa;AAAA,IAChH;AANS;AACA;AACA;AAAA,EAKV;AAAA,EAVS,OAAO;AAWjB;","names":[]}

package/dist/executor/index.cjs

@@ -0,0 +1,185 @@
+"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/executor/index.ts
+var executor_exports = {};
+__export(executor_exports, {
+  WorkflowExecutor: () => WorkflowExecutor
+});
+module.exports = __toCommonJS(executor_exports);
+
+// src/compose.ts
+function compose(middleware) {
+  return async (ctx) => {
+    let index = -1;
+    async function dispatch(i) {
+      if (i <= index) throw new Error("next() called multiple times");
+      index = i;
+      const fn = middleware[i];
+      if (!fn) return;
+      await fn(ctx, () => dispatch(i + 1));
+    }
+    await dispatch(0);
+  };
+}
+
+// src/store/errors.ts
+var ConcurrencyConflictError = class extends Error {
+  constructor(workflowId, expectedVersion, actualVersion) {
+    super(
+      `Concurrency conflict for workflow "${workflowId}": expected version ${expectedVersion}, actual ${actualVersion}`
+    );
+    this.workflowId = workflowId;
+    this.expectedVersion = expectedVersion;
+    this.actualVersion = actualVersion;
+  }
+  name = "ConcurrencyConflictError";
+};
+
+// src/executor/executor.ts
+var WorkflowExecutor = class {
+  constructor(router, store) {
+    this.router = router;
+    this.store = store;
+  }
+  middleware = [];
+  use(middleware) {
+    this.middleware.push(middleware);
+    return this;
+  }
+  async execute(id, command, options) {
+    const stored = await this.store.load(id);
+    if (!stored) {
+      return { ok: false, error: { category: "not_found", id } };
+    }
+    if (options?.expectedVersion !== void 0 && options.expectedVersion !== stored.version) {
+      return {
+        ok: false,
+        error: {
+          category: "conflict",
+          id,
+          expectedVersion: options.expectedVersion,
+          actualVersion: stored.version
+        }
+      };
+    }
+    const ctx = {
+      id,
+      command,
+      stored,
+      result: null,
+      snapshot: null,
+      events: []
+    };
+    try {
+      const chain = [...this.middleware, this.dispatchHandler()];
+      await compose(chain)(ctx);
+    } catch (err) {
+      return {
+        ok: false,
+        error: {
+          category: "unexpected",
+          error: err,
+          message: err instanceof Error ? err.message : String(err)
+        }
+      };
+    }
+    if (ctx.snapshot) {
+      const newVersion = stored.version + 1;
+      const savedSnapshot = { ...ctx.snapshot, version: newVersion };
+      try {
+        await this.store.save({
+          id,
+          snapshot: ctx.snapshot,
+          expectedVersion: stored.version,
+          events: ctx.events
+        });
+      } catch (err) {
+        if (err instanceof ConcurrencyConflictError) {
+          return {
+            ok: false,
+            error: {
+              category: "conflict",
+              id,
+              expectedVersion: stored.version,
+              actualVersion: err.actualVersion
+            }
+          };
+        }
+        return {
+          ok: false,
+          error: {
+            category: "unexpected",
+            error: err,
+            message: err instanceof Error ? err.message : String(err)
+          }
+        };
+      }
+      return {
+        ok: true,
+        snapshot: savedSnapshot,
+        version: newVersion,
+        events: ctx.events
+      };
+    }
+    if (ctx.result && !ctx.result.ok) {
+      return { ok: false, error: ctx.result.error };
+    }
+    return {
+      ok: false,
+      error: {
+        category: "unexpected",
+        error: new Error("Pipeline completed without setting snapshot or error"),
+        message: "Pipeline completed without setting snapshot or error"
+      }
+    };
+  }
+  dispatchHandler() {
+    const definition = this.router.definition;
+    const router = this.router;
+    return async (ctx, _next) => {
+      const restoreResult = definition.deserialize(ctx.stored.snapshot);
+      if (!restoreResult.ok) {
+        ctx.result = {
+          ok: false,
+          error: {
+            category: "restore",
+            id: ctx.id,
+            issues: restoreResult.error.issues
+          }
+        };
+        return;
+      }
+      const dispatchResult = await router.dispatch(restoreResult.workflow, ctx.command);
+      ctx.result = dispatchResult;
+      if (dispatchResult.ok) {
+        ctx.snapshot = definition.serialize(dispatchResult.workflow);
+        ctx.events = dispatchResult.events.map((e) => ({
+          type: e.type,
+          data: e.data
+        }));
+      }
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WorkflowExecutor
+});
+//# sourceMappingURL=index.cjs.map

package/dist/executor/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/executor/index.ts","../../src/compose.ts","../../src/store/errors.ts","../../src/executor/executor.ts"],"sourcesContent":["export { WorkflowExecutor } from \"./executor.js\";\nexport type {\n\tExecutionResult,\n\tExecutorContext,\n\tExecutorError,\n\tExecutorMiddleware,\n} from \"./types.js\";\n","type Middleware<TCtx> = (ctx: TCtx, next: () => Promise<void>) => Promise<void>;\n\n/** Composes an array of middleware into a single function (Koa-style onion model). */\nexport function compose<TCtx>(middleware: Middleware<TCtx>[]): (ctx: TCtx) => Promise<void> {\n\treturn async (ctx: TCtx) => {\n\t\tlet index = -1;\n\t\tasync function dispatch(i: number): Promise<void> {\n\t\t\tif (i <= index) throw new Error(\"next() called multiple times\");\n\t\t\tindex = i;\n\t\t\tconst fn = middleware[i];\n\t\t\tif (!fn) return;\n\t\t\tawait fn(ctx, () => dispatch(i + 1));\n\t\t}\n\t\tawait dispatch(0);\n\t};\n}\n","export class ConcurrencyConflictError extends Error {\n\treadonly name = \"ConcurrencyConflictError\";\n\n\tconstructor(\n\t\treadonly workflowId: string,\n\t\treadonly expectedVersion: number,\n\t\treadonly actualVersion: number,\n\t) {\n\t\tsuper(\n\t\t\t`Concurrency conflict for workflow \"${workflowId}\": expected version ${expectedVersion}, actual ${actualVersion}`,\n\t\t);\n\t}\n}\n","import { compose } from \"../compose.js\";\nimport type { WorkflowRouter } from \"../router.js\";\nimport type { WorkflowSnapshot } from \"../snapshot.js\";\nimport { ConcurrencyConflictError } from \"../store/errors.js\";\nimport type { StoreAdapter } from \"../store/types.js\";\nimport type { WorkflowConfig } from \"../types.js\";\nimport type { ExecutionResult, ExecutorContext, ExecutorMiddleware } from \"./types.js\";\n\nexport class WorkflowExecutor<TConfig extends WorkflowConfig> {\n\tprivate readonly middleware: ExecutorMiddleware[] = [];\n\n\tconstructor(\n\t\tpublic readonly router: WorkflowRouter<TConfig>,\n\t\tprivate readonly store: StoreAdapter,\n\t) {}\n\n\tuse(middleware: ExecutorMiddleware): this {\n\t\tthis.middleware.push(middleware);\n\t\treturn this;\n\t}\n\n\tasync execute(\n\t\tid: string,\n\t\tcommand: { type: string; payload: unknown },\n\t\toptions?: { expectedVersion?: number },\n\t): Promise<ExecutionResult> {\n\t\t// 1. Load\n\t\tconst stored = await this.store.load(id);\n\t\tif (!stored) {\n\t\t\treturn { ok: false, error: { category: \"not_found\", id } };\n\t\t}\n\n\t\t// 2. Optimistic version check\n\t\tif (options?.expectedVersion !== undefined && options.expectedVersion !== stored.version) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: {\n\t\t\t\t\tcategory: \"conflict\",\n\t\t\t\t\tid,\n\t\t\t\t\texpectedVersion: options.expectedVersion,\n\t\t\t\t\tactualVersion: stored.version,\n\t\t\t\t},\n\t\t\t};\n\t\t}\n\n\t\t// 3. Build context\n\t\tconst ctx: ExecutorContext = {\n\t\t\tid,\n\t\t\tcommand,\n\t\t\tstored,\n\t\t\tresult: null,\n\t\t\tsnapshot: null,\n\t\t\tevents: [],\n\t\t};\n\n\t\t// 4. Run pipeline\n\t\ttry {\n\t\t\tconst chain = [...this.middleware, this.dispatchHandler()];\n\t\t\tawait compose(chain)(ctx);\n\t\t} catch (err) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: {\n\t\t\t\t\tcategory: \"unexpected\",\n\t\t\t\t\terror: err,\n\t\t\t\t\tmessage: err instanceof Error ? err.message : String(err),\n\t\t\t\t},\n\t\t\t};\n\t\t}\n\n\t\t// 5. Save if dispatch succeeded\n\t\tif (ctx.snapshot) {\n\t\t\tconst newVersion = stored.version + 1;\n\t\t\tconst savedSnapshot = { ...ctx.snapshot, version: newVersion };\n\n\t\t\ttry {\n\t\t\t\tawait this.store.save({\n\t\t\t\t\tid,\n\t\t\t\t\tsnapshot: ctx.snapshot,\n\t\t\t\t\texpectedVersion: stored.version,\n\t\t\t\t\tevents: ctx.events,\n\t\t\t\t});\n\t\t\t} catch (err) {\n\t\t\t\tif (err instanceof ConcurrencyConflictError) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tok: false,\n\t\t\t\t\t\terror: {\n\t\t\t\t\t\t\tcategory: \"conflict\",\n\t\t\t\t\t\t\tid,\n\t\t\t\t\t\t\texpectedVersion: stored.version,\n\t\t\t\t\t\t\tactualVersion: err.actualVersion,\n\t\t\t\t\t\t},\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\treturn {\n\t\t\t\t\tok: false,\n\t\t\t\t\terror: {\n\t\t\t\t\t\tcategory: \"unexpected\",\n\t\t\t\t\t\terror: err,\n\t\t\t\t\t\tmessage: err instanceof Error ? err.message : String(err),\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t}\n\n\t\t\treturn {\n\t\t\t\tok: true,\n\t\t\t\tsnapshot: savedSnapshot,\n\t\t\t\tversion: newVersion,\n\t\t\t\tevents: ctx.events,\n\t\t\t};\n\t\t}\n\n\t\t// 6. Dispatch failed — return the error\n\t\tif (ctx.result && !ctx.result.ok) {\n\t\t\treturn { ok: false, error: ctx.result.error };\n\t\t}\n\n\t\treturn {\n\t\t\tok: false,\n\t\t\terror: {\n\t\t\t\tcategory: \"unexpected\",\n\t\t\t\terror: new Error(\"Pipeline completed without setting snapshot or error\"),\n\t\t\t\tmessage: \"Pipeline completed without setting snapshot or error\",\n\t\t\t},\n\t\t};\n\t}\n\n\tprivate dispatchHandler(): ExecutorMiddleware {\n\t\tconst definition = this.router.definition;\n\t\tconst router = this.router;\n\n\t\treturn async (ctx, _next) => {\n\t\t\tconst restoreResult = definition.deserialize(ctx.stored.snapshot);\n\t\t\tif (!restoreResult.ok) {\n\t\t\t\tctx.result = {\n\t\t\t\t\tok: false as const,\n\t\t\t\t\terror: {\n\t\t\t\t\t\tcategory: \"restore\" as const,\n\t\t\t\t\t\tid: ctx.id,\n\t\t\t\t\t\tissues: restoreResult.error.issues,\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// as never: type erasure — executor holds WorkflowConfig base type,\n\t\t\t// but dispatch validates commands against Zod schemas at runtime\n\t\t\tconst dispatchResult = await router.dispatch(restoreResult.workflow, ctx.command as never);\n\n\t\t\t// biome-ignore lint/suspicious/noExplicitAny: type erasure — DispatchResult<TConfig> assigned to DispatchResult<WorkflowConfig>\n\t\t\tctx.result = dispatchResult as any;\n\n\t\t\tif (dispatchResult.ok) {\n\t\t\t\t// biome-ignore lint/suspicious/noExplicitAny: type erasure — TConfig narrows WorkflowSnapshot but ctx.snapshot is unparameterized\n\t\t\t\tctx.snapshot = definition.serialize(dispatchResult.workflow) as any as WorkflowSnapshot;\n\t\t\t\tctx.events = (dispatchResult.events as Array<{ type: string; data: unknown }>).map((e) => ({\n\t\t\t\t\ttype: e.type,\n\t\t\t\t\tdata: e.data,\n\t\t\t\t}));\n\t\t\t}\n\t\t};\n\t}\n}\n"],"mappings":"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","names":[]}

package/dist/executor/index.d.cts

@@ -0,0 +1,69 @@
+import { c as WorkflowRouter } from '../plugin-DHS8yUmS.cjs';
+import { S as StoredWorkflow, a as StoreAdapter } from '../types-BtMTMoOZ.cjs';
+import { a as WorkflowSnapshot, P as PipelineError, W as WorkflowConfig, D as DispatchResult } from '../snapshot-D5iZubCz.cjs';
+import 'zod';
+
+interface ExecutorContext {
+    readonly id: string;
+    readonly command: {
+        type: string;
+        payload: unknown;
+    };
+    readonly stored: StoredWorkflow;
+    result: DispatchResult<WorkflowConfig> | {
+        ok: false;
+        error: ExecutorError;
+    } | null;
+    snapshot: WorkflowSnapshot | null;
+    events: Array<{
+        type: string;
+        data: unknown;
+    }>;
+}
+type ExecutorMiddleware = (ctx: ExecutorContext, next: () => Promise<void>) => Promise<void>;
+type ExecutorError = {
+    category: "not_found";
+    id: string;
+} | {
+    category: "conflict";
+    id: string;
+    expectedVersion: number;
+    actualVersion: number;
+} | {
+    category: "restore";
+    id: string;
+    issues: unknown[];
+} | {
+    category: "unexpected";
+    error: unknown;
+    message: string;
+};
+type ExecutionResult = {
+    ok: true;
+    snapshot: WorkflowSnapshot;
+    version: number;
+    events: Array<{
+        type: string;
+        data: unknown;
+    }>;
+} | {
+    ok: false;
+    error: PipelineError<WorkflowConfig> | ExecutorError;
+};
+
+declare class WorkflowExecutor<TConfig extends WorkflowConfig> {
+    readonly router: WorkflowRouter<TConfig>;
+    private readonly store;
+    private readonly middleware;
+    constructor(router: WorkflowRouter<TConfig>, store: StoreAdapter);
+    use(middleware: ExecutorMiddleware): this;
+    execute(id: string, command: {
+        type: string;
+        payload: unknown;
+    }, options?: {
+        expectedVersion?: number;
+    }): Promise<ExecutionResult>;
+    private dispatchHandler;
+}
+
+export { type ExecutionResult, type ExecutorContext, type ExecutorError, type ExecutorMiddleware, WorkflowExecutor };

package/dist/executor/index.d.ts

@@ -0,0 +1,69 @@
+import { c as WorkflowRouter } from '../plugin-DHN3Pk52.js';
+import { S as StoredWorkflow, a as StoreAdapter } from '../types-C0nlrs5c.js';
+import { a as WorkflowSnapshot, P as PipelineError, W as WorkflowConfig, D as DispatchResult } from '../snapshot-D5iZubCz.js';
+import 'zod';
+
+interface ExecutorContext {
+    readonly id: string;
+    readonly command: {
+        type: string;
+        payload: unknown;
+    };
+    readonly stored: StoredWorkflow;
+    result: DispatchResult<WorkflowConfig> | {
+        ok: false;
+        error: ExecutorError;
+    } | null;
+    snapshot: WorkflowSnapshot | null;
+    events: Array<{
+        type: string;
+        data: unknown;
+    }>;
+}
+type ExecutorMiddleware = (ctx: ExecutorContext, next: () => Promise<void>) => Promise<void>;
+type ExecutorError = {
+    category: "not_found";
+    id: string;
+} | {
+    category: "conflict";
+    id: string;
+    expectedVersion: number;
+    actualVersion: number;
+} | {
+    category: "restore";
+    id: string;
+    issues: unknown[];
+} | {
+    category: "unexpected";
+    error: unknown;
+    message: string;
+};
+type ExecutionResult = {
+    ok: true;
+    snapshot: WorkflowSnapshot;
+    version: number;
+    events: Array<{
+        type: string;
+        data: unknown;
+    }>;
+} | {
+    ok: false;
+    error: PipelineError<WorkflowConfig> | ExecutorError;
+};
+
+declare class WorkflowExecutor<TConfig extends WorkflowConfig> {
+    readonly router: WorkflowRouter<TConfig>;
+    private readonly store;
+    private readonly middleware;
+    constructor(router: WorkflowRouter<TConfig>, store: StoreAdapter);
+    use(middleware: ExecutorMiddleware): this;
+    execute(id: string, command: {
+        type: string;
+        payload: unknown;
+    }, options?: {
+        expectedVersion?: number;
+    }): Promise<ExecutionResult>;
+    private dispatchHandler;
+}
+
+export { type ExecutionResult, type ExecutorContext, type ExecutorError, type ExecutorMiddleware, WorkflowExecutor };

package/dist/executor/index.js

@@ -0,0 +1,137 @@
+import {
+  compose
+} from "../chunk-YTJGSTKG.js";
+import {
+  ConcurrencyConflictError
+} from "../chunk-ZFRIE42B.js";
+
+// src/executor/executor.ts
+var WorkflowExecutor = class {
+  constructor(router, store) {
+    this.router = router;
+    this.store = store;
+  }
+  middleware = [];
+  use(middleware) {
+    this.middleware.push(middleware);
+    return this;
+  }
+  async execute(id, command, options) {
+    const stored = await this.store.load(id);
+    if (!stored) {
+      return { ok: false, error: { category: "not_found", id } };
+    }
+    if (options?.expectedVersion !== void 0 && options.expectedVersion !== stored.version) {
+      return {
+        ok: false,
+        error: {
+          category: "conflict",
+          id,
+          expectedVersion: options.expectedVersion,
+          actualVersion: stored.version
+        }
+      };
+    }
+    const ctx = {
+      id,
+      command,
+      stored,
+      result: null,
+      snapshot: null,
+      events: []
+    };
+    try {
+      const chain = [...this.middleware, this.dispatchHandler()];
+      await compose(chain)(ctx);
+    } catch (err) {
+      return {
+        ok: false,
+        error: {
+          category: "unexpected",
+          error: err,
+          message: err instanceof Error ? err.message : String(err)
+        }
+      };
+    }
+    if (ctx.snapshot) {
+      const newVersion = stored.version + 1;
+      const savedSnapshot = { ...ctx.snapshot, version: newVersion };
+      try {
+        await this.store.save({
+          id,
+          snapshot: ctx.snapshot,
+          expectedVersion: stored.version,
+          events: ctx.events
+        });
+      } catch (err) {
+        if (err instanceof ConcurrencyConflictError) {
+          return {
+            ok: false,
+            error: {
+              category: "conflict",
+              id,
+              expectedVersion: stored.version,
+              actualVersion: err.actualVersion
+            }
+          };
+        }
+        return {
+          ok: false,
+          error: {
+            category: "unexpected",
+            error: err,
+            message: err instanceof Error ? err.message : String(err)
+          }
+        };
+      }
+      return {
+        ok: true,
+        snapshot: savedSnapshot,
+        version: newVersion,
+        events: ctx.events
+      };
+    }
+    if (ctx.result && !ctx.result.ok) {
+      return { ok: false, error: ctx.result.error };
+    }
+    return {
+      ok: false,
+      error: {
+        category: "unexpected",
+        error: new Error("Pipeline completed without setting snapshot or error"),
+        message: "Pipeline completed without setting snapshot or error"
+      }
+    };
+  }
+  dispatchHandler() {
+    const definition = this.router.definition;
+    const router = this.router;
+    return async (ctx, _next) => {
+      const restoreResult = definition.deserialize(ctx.stored.snapshot);
+      if (!restoreResult.ok) {
+        ctx.result = {
+          ok: false,
+          error: {
+            category: "restore",
+            id: ctx.id,
+            issues: restoreResult.error.issues
+          }
+        };
+        return;
+      }
+      const dispatchResult = await router.dispatch(restoreResult.workflow, ctx.command);
+      ctx.result = dispatchResult;
+      if (dispatchResult.ok) {
+        ctx.snapshot = definition.serialize(dispatchResult.workflow);
+        ctx.events = dispatchResult.events.map((e) => ({
+          type: e.type,
+          data: e.data
+        }));
+      }
+    };
+  }
+};
+export {
+  WorkflowExecutor
+};
+//# sourceMappingURL=index.js.map

package/dist/executor/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/executor/executor.ts"],"sourcesContent":["import { compose } from \"../compose.js\";\nimport type { WorkflowRouter } from \"../router.js\";\nimport type { WorkflowSnapshot } from \"../snapshot.js\";\nimport { ConcurrencyConflictError } from \"../store/errors.js\";\nimport type { StoreAdapter } from \"../store/types.js\";\nimport type { WorkflowConfig } from \"../types.js\";\nimport type { ExecutionResult, ExecutorContext, ExecutorMiddleware } from \"./types.js\";\n\nexport class WorkflowExecutor<TConfig extends WorkflowConfig> {\n\tprivate readonly middleware: ExecutorMiddleware[] = [];\n\n\tconstructor(\n\t\tpublic readonly router: WorkflowRouter<TConfig>,\n\t\tprivate readonly store: StoreAdapter,\n\t) {}\n\n\tuse(middleware: ExecutorMiddleware): this {\n\t\tthis.middleware.push(middleware);\n\t\treturn this;\n\t}\n\n\tasync execute(\n\t\tid: string,\n\t\tcommand: { type: string; payload: unknown },\n\t\toptions?: { expectedVersion?: number },\n\t): Promise<ExecutionResult> {\n\t\t// 1. Load\n\t\tconst stored = await this.store.load(id);\n\t\tif (!stored) {\n\t\t\treturn { ok: false, error: { category: \"not_found\", id } };\n\t\t}\n\n\t\t// 2. Optimistic version check\n\t\tif (options?.expectedVersion !== undefined && options.expectedVersion !== stored.version) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: {\n\t\t\t\t\tcategory: \"conflict\",\n\t\t\t\t\tid,\n\t\t\t\t\texpectedVersion: options.expectedVersion,\n\t\t\t\t\tactualVersion: stored.version,\n\t\t\t\t},\n\t\t\t};\n\t\t}\n\n\t\t// 3. Build context\n\t\tconst ctx: ExecutorContext = {\n\t\t\tid,\n\t\t\tcommand,\n\t\t\tstored,\n\t\t\tresult: null,\n\t\t\tsnapshot: null,\n\t\t\tevents: [],\n\t\t};\n\n\t\t// 4. Run pipeline\n\t\ttry {\n\t\t\tconst chain = [...this.middleware, this.dispatchHandler()];\n\t\t\tawait compose(chain)(ctx);\n\t\t} catch (err) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: {\n\t\t\t\t\tcategory: \"unexpected\",\n\t\t\t\t\terror: err,\n\t\t\t\t\tmessage: err instanceof Error ? err.message : String(err),\n\t\t\t\t},\n\t\t\t};\n\t\t}\n\n\t\t// 5. Save if dispatch succeeded\n\t\tif (ctx.snapshot) {\n\t\t\tconst newVersion = stored.version + 1;\n\t\t\tconst savedSnapshot = { ...ctx.snapshot, version: newVersion };\n\n\t\t\ttry {\n\t\t\t\tawait this.store.save({\n\t\t\t\t\tid,\n\t\t\t\t\tsnapshot: ctx.snapshot,\n\t\t\t\t\texpectedVersion: stored.version,\n\t\t\t\t\tevents: ctx.events,\n\t\t\t\t});\n\t\t\t} catch (err) {\n\t\t\t\tif (err instanceof ConcurrencyConflictError) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tok: false,\n\t\t\t\t\t\terror: {\n\t\t\t\t\t\t\tcategory: \"conflict\",\n\t\t\t\t\t\t\tid,\n\t\t\t\t\t\t\texpectedVersion: stored.version,\n\t\t\t\t\t\t\tactualVersion: err.actualVersion,\n\t\t\t\t\t\t},\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\treturn {\n\t\t\t\t\tok: false,\n\t\t\t\t\terror: {\n\t\t\t\t\t\tcategory: \"unexpected\",\n\t\t\t\t\t\terror: err,\n\t\t\t\t\t\tmessage: err instanceof Error ? err.message : String(err),\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t}\n\n\t\t\treturn {\n\t\t\t\tok: true,\n\t\t\t\tsnapshot: savedSnapshot,\n\t\t\t\tversion: newVersion,\n\t\t\t\tevents: ctx.events,\n\t\t\t};\n\t\t}\n\n\t\t// 6. Dispatch failed — return the error\n\t\tif (ctx.result && !ctx.result.ok) {\n\t\t\treturn { ok: false, error: ctx.result.error };\n\t\t}\n\n\t\treturn {\n\t\t\tok: false,\n\t\t\terror: {\n\t\t\t\tcategory: \"unexpected\",\n\t\t\t\terror: new Error(\"Pipeline completed without setting snapshot or error\"),\n\t\t\t\tmessage: \"Pipeline completed without setting snapshot or error\",\n\t\t\t},\n\t\t};\n\t}\n\n\tprivate dispatchHandler(): ExecutorMiddleware {\n\t\tconst definition = this.router.definition;\n\t\tconst router = this.router;\n\n\t\treturn async (ctx, _next) => {\n\t\t\tconst restoreResult = definition.deserialize(ctx.stored.snapshot);\n\t\t\tif (!restoreResult.ok) {\n\t\t\t\tctx.result = {\n\t\t\t\t\tok: false as const,\n\t\t\t\t\terror: {\n\t\t\t\t\t\tcategory: \"restore\" as const,\n\t\t\t\t\t\tid: ctx.id,\n\t\t\t\t\t\tissues: restoreResult.error.issues,\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// as never: type erasure — executor holds WorkflowConfig base type,\n\t\t\t// but dispatch validates commands against Zod schemas at runtime\n\t\t\tconst dispatchResult = await router.dispatch(restoreResult.workflow, ctx.command as never);\n\n\t\t\t// biome-ignore lint/suspicious/noExplicitAny: type erasure — DispatchResult<TConfig> assigned to DispatchResult<WorkflowConfig>\n\t\t\tctx.result = dispatchResult as any;\n\n\t\t\tif (dispatchResult.ok) {\n\t\t\t\t// biome-ignore lint/suspicious/noExplicitAny: type erasure — TConfig narrows WorkflowSnapshot but ctx.snapshot is unparameterized\n\t\t\t\tctx.snapshot = definition.serialize(dispatchResult.workflow) as any as WorkflowSnapshot;\n\t\t\t\tctx.events = (dispatchResult.events as Array<{ type: string; data: unknown }>).map((e) => ({\n\t\t\t\t\ttype: e.type,\n\t\t\t\t\tdata: e.data,\n\t\t\t\t}));\n\t\t\t}\n\t\t};\n\t}\n}\n"],"mappings":"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","names":[]}

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(index_exports, {
   ValidationError: () => ValidationError,
   WorkflowRouter: () => WorkflowRouter,
   createKey: () => createKey,
+  defineGenericPlugin: () => defineGenericPlugin,
   defineMigrations: () => defineMigrations,
   definePlugin: () => definePlugin,
   defineWorkflow: () => defineWorkflow,
@@ -108,7 +109,13 @@ function defineWorkflow(name, config) {
     hasState(stateName) {
       return stateName in config.states;
     },
-    snapshot(workflow) {
+    hasCommand(commandName) {
+      return commandName in config.commands;
+    },
+    hasEvent(eventName) {
+      return eventName in config.events;
+    },
+    serialize(workflow) {
       return {
         id: workflow.id,
         definitionName: name,
@@ -116,10 +123,11 @@ function defineWorkflow(name, config) {
         data: workflow.data,
         createdAt: workflow.createdAt.toISOString(),
         updatedAt: workflow.updatedAt.toISOString(),
-        modelVersion: config.modelVersion ?? 1
+        modelVersion: config.modelVersion ?? 1,
+        version: workflow.version ?? 1
       };
     },
-    restore(snap) {
+    deserialize(snap) {
       const stateSchema = config.states[snap.state];
       if (!stateSchema) {
         return {
@@ -283,6 +291,9 @@ function definePlugin(fn) {
   Object.defineProperty(plugin, PLUGIN_SYMBOL, { value: true, writable: false });
   return plugin;
 }
+function defineGenericPlugin(fn) {
+  return definePlugin(fn);
+}
 function isPlugin(value) {
   return typeof value === "function" && PLUGIN_SYMBOL in value;
 }
@@ -456,6 +467,8 @@ function createContext(definition, originalWorkflow, command, deps, options) {
 var HOOK_EVENTS = /* @__PURE__ */ new Set([
   "dispatch:start",
   "dispatch:end",
+  "pipeline:start",
+  "pipeline:end",
   "transition",
   "error",
   "event"
@@ -640,6 +653,25 @@ var WorkflowRouter = class _WorkflowRouter {
    * @returns A {@link DispatchResult} indicating success or failure with the updated workflow and events
    */
   async dispatch(workflow, command) {
+    await this.hookRegistry.emit("dispatch:start", this.onHookError, workflow, command);
+    let result;
+    try {
+      result = await this.executePipeline(workflow, command);
+    } catch (err) {
+      result = {
+        ok: false,
+        error: {
+          category: "unexpected",
+          error: err,
+          message: err instanceof Error ? err.message : String(err)
+        }
+      };
+    } finally {
+      await this.hookRegistry.emit("dispatch:end", this.onHookError, workflow, command, result);
+    }
+    return result;
+  }
+  async executePipeline(workflow, command) {
     if (!this.definition.hasState(workflow.state)) {
       return {
         ok: false,
@@ -711,7 +743,7 @@ var WorkflowRouter = class _WorkflowRouter {
       this.deps,
       { wrapDeps: this.wrapDeps }
     );
-    await this.hookRegistry.emit("dispatch:start", this.onHookError, ctx);
+    await this.hookRegistry.emit("pipeline:start", this.onHookError, ctx);
     try {
       const composed = compose(chain);
       await composed(ctx);
@@ -734,7 +766,7 @@ var WorkflowRouter = class _WorkflowRouter {
           await this.hookRegistry.emit("event", this.onHookError, event, result.workflow);
         }
       }
-      await this.hookRegistry.emit("dispatch:end", this.onHookError, ctx, result);
+      await this.hookRegistry.emit("pipeline:end", this.onHookError, ctx, result);
       return result;
     } catch (err) {
       let result;
@@ -778,7 +810,7 @@ var WorkflowRouter = class _WorkflowRouter {
         };
       }
       await this.hookRegistry.emit("error", this.onHookError, result.error, ctx);
-      await this.hookRegistry.emit("dispatch:end", this.onHookError, ctx, result);
+      await this.hookRegistry.emit("pipeline:end", this.onHookError, ctx, result);
       return result;
     }
   }
@@ -790,6 +822,7 @@ var WorkflowRouter = class _WorkflowRouter {
   ValidationError,
   WorkflowRouter,
   createKey,
+  defineGenericPlugin,
   defineMigrations,
   definePlugin,
   defineWorkflow,