@lunora/workflow 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/packem_shared/{types.d-CQO_koGe.d.mts → types.d-C9W6rEWv.d.mts}

@@ -264,9 +264,86 @@ interface RunStepOptions {
 */
 type WorkflowRunStepFunction = <A extends StepArgsValidator, Result>(step: StepDefinition<A, Result>, args: InferStepArgs<A>, options?: RunStepOptions) => Promise<Result>;
 /**
+* One branch of a {@link WorkflowParallelFunction} fan-out — a declared child
+* workflow (referenced by its `lunora/workflows.ts` export name) plus the params
+* it is created with. The phantom `Output` carries the child's result type into
+* the `ctx.parallel(...)` result tuple. Build one with the `branch(...)` helper.
+*/
+interface WorkflowBranch<Output = unknown> {
+  /** Phantom marker for the branch output type — never present at runtime. */
+  readonly __output?: Output;
+  /**
+  * Optional group-saga compensation (plan 075 Phase 3): the `lunora/workflows.ts`
+  * export name of a workflow to run if a **sibling** branch in the same
+  * `ctx.parallel(...)` group fails **after** this branch has already completed.
+  * It is spawned fire-and-forget (a durable, replay-safe idempotent create) with
+  * {@link BranchCompensationParams} as its `ctx.params`. Omit for no
+  * compensation — a group where no branch sets this behaves exactly as a plain
+  * fan-out (fail-fast, no rollback).
+  */
+  readonly compensateWith?: string;
+  /** Optional explicit child instance id (defaults to a deterministic parent-derived id). */
+  readonly id?: string;
+  /** The params the child instance is created with — surfaced as the child's `ctx.params`. */
+  readonly params?: Record<string, unknown>;
+  /** Optional wait timeout for this branch (the parent's `waitForEvent` timeout). */
+  readonly timeout?: number | string;
+  /** The `lunora/workflows.ts` export name of the child workflow to run. */
+  readonly workflow: string;
+}
+/**
+* The `ctx.params` a group-saga compensation workflow (a branch's
+* {@link WorkflowBranch.compensateWith}) receives when a sibling's failure rolls
+* back the group. Everything is plain-serialisable — the compensation is an
+* ordinary declared workflow, so it can `ctx.runStep(...)` its own undo logic.
+*/
+interface BranchCompensationParams {
+  /** Index signature: this is a workflow `params` bag, so it is a valid `Record&lt;string, unknown>` payload. */
+  [key: string]: unknown;
+  /** The export name of the completed branch being compensated. */
+  branch: string;
+  /** The serialised error of the sibling branch whose failure triggered the group rollback. */
+  error: {
+    message: string;
+    name: string;
+  };
+  /** Declaration-order index of the completed branch being compensated. */
+  index: number;
+  /** The completed branch's output value — what it returned before the group failed. */
+  output?: unknown;
+}
+/** Map a tuple of {@link WorkflowBranch}es to the tuple of their output types, preserving order. */
+type WorkflowBranchOutputs<B extends ReadonlyArray<WorkflowBranch>> = { -readonly [K in keyof B]: B[K] extends WorkflowBranch<infer Output> ? Output : never };
+/**
+* Run branches as isolated child workflow instances and resolve with their
+* outputs in declaration order. Each branch gets its own Durable Object (own
+* memory / CPU / retry budget); the parent hibernates while they execute. Rejects
+* (non-retryable) on the first branch that fails.
+*
+* ```ts
+* const [tags, thumb] = await ctx.parallel([
+*     branch("imageTag", { key }),
+*     branch("thumbnail", { key }),
+* ]);
+* ```
+*/
+type WorkflowParallelFunction = <const B extends ReadonlyArray<WorkflowBranch>>(branches: B) => Promise<WorkflowBranchOutputs<B>>;
+/** Per-call options for {@link WorkflowSpawnFunction}. */
+interface WorkflowSpawnOptions {
+  /** Explicit child instance id (defaults to a deterministic parent-derived id). */
+  id?: string;
+}
+/**
+* Fire-and-forget start of a declared child workflow from inside a workflow body
+* — replay-safe (idempotent create), returns a live handle to the child. Use
+* {@link WorkflowParallelFunction} instead when you need to await results.
+*/
+type WorkflowSpawnFunction = (workflow: string, params?: Record<string, unknown>, options?: WorkflowSpawnOptions) => Promise<WorkflowInstanceLike>;
+/**
 * The context object passed to a `defineWorkflow` handler. Bundles the native
 * Cloudflare durability primitives (`step`, `event`) with the Lunora runner
-* (`run`), the reusable-step runner (`runStep`), the Worker `env`, and a logger.
+* (`run`), the reusable-step runner (`runStep`), the fan-out primitives
+* (`parallel` / `spawn`), the Worker `env`, and a logger.
 */
 interface WorkflowRunContext<Params = Record<string, unknown>> {
   /** The Worker environment bindings. */
@@ -275,12 +352,16 @@ interface WorkflowRunContext<Params = Record<string, unknown>> {
   readonly event: WorkflowEventLike<Params>;
   /** Structured logger surfaced in `wrangler tail` / Studio logs. */
   readonly log: WorkflowLogger;
+  /** Run branches as isolated child workflow instances and await their outputs (declaration-ordered tuple). */
+  readonly parallel: WorkflowParallelFunction;
   /** Convenience alias for `event.payload`. */
   readonly params: Readonly<Params>;
   /** Invoke a Lunora function; wrap in `step.do(...)` for durability. */
   readonly run: WorkflowRunFunction;
   /** Run a reusable, schema-validated {@link StepDefinition} as a durable step. */
   readonly runStep: WorkflowRunStepFunction;
+  /** Fire-and-forget start of a declared child workflow (replay-safe; returns a live handle). */
+  readonly spawn: WorkflowSpawnFunction;
   /** The native Cloudflare Workflows durable-step API. */
   readonly step: WorkflowStepLike;
 }
@@ -341,4 +422,4 @@ interface LunoraWorkflowsOptions {
   */
   bindings: Record<string, WorkflowBindingLike>;
 }
-export { ArgsOf as A, WorkflowStepRollbackOptionsLike as B, FunctionReference as F, InferStepArgs as I, LunoraWorkflowsOptions as L, RunFunctionOptions as R, StepArgsValidator as S, WorkflowDefinition as W, Workflows as a, StepConfig as b, StepDefinition as c, WorkflowConfig as d, WorkflowInstanceStatus as e, WorkflowLogger as f, WorkflowEventLike as g, WorkflowStepLike as h, WorkflowRunContext as i, WorkflowRunFunction as j, WorkflowRunStepFunction as k, RunStepOptions as l, StepHandler as m, StepRollbackContext as n, StepRollbackHandler as o, StepRunContext as p, WorkflowBindingLike as q, WorkflowCreateOptions as r, WorkflowHandle as s, WorkflowHandler as t, WorkflowInstanceLike as u, WorkflowRollbackContextLike as v, WorkflowRollbackHandlerLike as w, WorkflowStatusResult as x, WorkflowStepConfigLike as y, WorkflowStepContextLike as z };
+export { ArgsOf as A, BranchCompensationParams as B, WorkflowSpawnFunction as C, WorkflowSpawnOptions as D, WorkflowStatusResult as E, FunctionReference as F, WorkflowStepConfigLike as G, WorkflowStepContextLike as H, InferStepArgs as I, WorkflowStepRollbackOptionsLike as J, LunoraWorkflowsOptions as L, RunFunctionOptions as R, StepArgsValidator as S, WorkflowDefinition as W, Workflows as a, StepConfig as b, StepDefinition as c, WorkflowConfig as d, WorkflowBranch as e, WorkflowInstanceStatus as f, WorkflowEventLike as g, WorkflowStepLike as h, WorkflowRunContext as i, WorkflowLogger as j, WorkflowRunFunction as k, WorkflowRunStepFunction as l, RunStepOptions as m, StepHandler as n, StepRollbackContext as o, StepRollbackHandler as p, StepRunContext as q, WorkflowBindingLike as r, WorkflowBranchOutputs as s, WorkflowCreateOptions as t, WorkflowHandle as u, WorkflowHandler as v, WorkflowInstanceLike as w, WorkflowParallelFunction as x, WorkflowRollbackContextLike as y, WorkflowRollbackHandlerLike as z };

package/dist/packem_shared/{types.d-CQO_koGe.d.ts → types.d-C9W6rEWv.d.ts}

@@ -264,9 +264,86 @@ interface RunStepOptions {
 */
 type WorkflowRunStepFunction = <A extends StepArgsValidator, Result>(step: StepDefinition<A, Result>, args: InferStepArgs<A>, options?: RunStepOptions) => Promise<Result>;
 /**
+* One branch of a {@link WorkflowParallelFunction} fan-out — a declared child
+* workflow (referenced by its `lunora/workflows.ts` export name) plus the params
+* it is created with. The phantom `Output` carries the child's result type into
+* the `ctx.parallel(...)` result tuple. Build one with the `branch(...)` helper.
+*/
+interface WorkflowBranch<Output = unknown> {
+  /** Phantom marker for the branch output type — never present at runtime. */
+  readonly __output?: Output;
+  /**
+  * Optional group-saga compensation (plan 075 Phase 3): the `lunora/workflows.ts`
+  * export name of a workflow to run if a **sibling** branch in the same
+  * `ctx.parallel(...)` group fails **after** this branch has already completed.
+  * It is spawned fire-and-forget (a durable, replay-safe idempotent create) with
+  * {@link BranchCompensationParams} as its `ctx.params`. Omit for no
+  * compensation — a group where no branch sets this behaves exactly as a plain
+  * fan-out (fail-fast, no rollback).
+  */
+  readonly compensateWith?: string;
+  /** Optional explicit child instance id (defaults to a deterministic parent-derived id). */
+  readonly id?: string;
+  /** The params the child instance is created with — surfaced as the child's `ctx.params`. */
+  readonly params?: Record<string, unknown>;
+  /** Optional wait timeout for this branch (the parent's `waitForEvent` timeout). */
+  readonly timeout?: number | string;
+  /** The `lunora/workflows.ts` export name of the child workflow to run. */
+  readonly workflow: string;
+}
+/**
+* The `ctx.params` a group-saga compensation workflow (a branch's
+* {@link WorkflowBranch.compensateWith}) receives when a sibling's failure rolls
+* back the group. Everything is plain-serialisable — the compensation is an
+* ordinary declared workflow, so it can `ctx.runStep(...)` its own undo logic.
+*/
+interface BranchCompensationParams {
+  /** Index signature: this is a workflow `params` bag, so it is a valid `Record&lt;string, unknown>` payload. */
+  [key: string]: unknown;
+  /** The export name of the completed branch being compensated. */
+  branch: string;
+  /** The serialised error of the sibling branch whose failure triggered the group rollback. */
+  error: {
+    message: string;
+    name: string;
+  };
+  /** Declaration-order index of the completed branch being compensated. */
+  index: number;
+  /** The completed branch's output value — what it returned before the group failed. */
+  output?: unknown;
+}
+/** Map a tuple of {@link WorkflowBranch}es to the tuple of their output types, preserving order. */
+type WorkflowBranchOutputs<B extends ReadonlyArray<WorkflowBranch>> = { -readonly [K in keyof B]: B[K] extends WorkflowBranch<infer Output> ? Output : never };
+/**
+* Run branches as isolated child workflow instances and resolve with their
+* outputs in declaration order. Each branch gets its own Durable Object (own
+* memory / CPU / retry budget); the parent hibernates while they execute. Rejects
+* (non-retryable) on the first branch that fails.
+*
+* ```ts
+* const [tags, thumb] = await ctx.parallel([
+*     branch("imageTag", { key }),
+*     branch("thumbnail", { key }),
+* ]);
+* ```
+*/
+type WorkflowParallelFunction = <const B extends ReadonlyArray<WorkflowBranch>>(branches: B) => Promise<WorkflowBranchOutputs<B>>;
+/** Per-call options for {@link WorkflowSpawnFunction}. */
+interface WorkflowSpawnOptions {
+  /** Explicit child instance id (defaults to a deterministic parent-derived id). */
+  id?: string;
+}
+/**
+* Fire-and-forget start of a declared child workflow from inside a workflow body
+* — replay-safe (idempotent create), returns a live handle to the child. Use
+* {@link WorkflowParallelFunction} instead when you need to await results.
+*/
+type WorkflowSpawnFunction = (workflow: string, params?: Record<string, unknown>, options?: WorkflowSpawnOptions) => Promise<WorkflowInstanceLike>;
+/**
 * The context object passed to a `defineWorkflow` handler. Bundles the native
 * Cloudflare durability primitives (`step`, `event`) with the Lunora runner
-* (`run`), the reusable-step runner (`runStep`), the Worker `env`, and a logger.
+* (`run`), the reusable-step runner (`runStep`), the fan-out primitives
+* (`parallel` / `spawn`), the Worker `env`, and a logger.
 */
 interface WorkflowRunContext<Params = Record<string, unknown>> {
   /** The Worker environment bindings. */
@@ -275,12 +352,16 @@ interface WorkflowRunContext<Params = Record<string, unknown>> {
   readonly event: WorkflowEventLike<Params>;
   /** Structured logger surfaced in `wrangler tail` / Studio logs. */
   readonly log: WorkflowLogger;
+  /** Run branches as isolated child workflow instances and await their outputs (declaration-ordered tuple). */
+  readonly parallel: WorkflowParallelFunction;
   /** Convenience alias for `event.payload`. */
   readonly params: Readonly<Params>;
   /** Invoke a Lunora function; wrap in `step.do(...)` for durability. */
   readonly run: WorkflowRunFunction;
   /** Run a reusable, schema-validated {@link StepDefinition} as a durable step. */
   readonly runStep: WorkflowRunStepFunction;
+  /** Fire-and-forget start of a declared child workflow (replay-safe; returns a live handle). */
+  readonly spawn: WorkflowSpawnFunction;
   /** The native Cloudflare Workflows durable-step API. */
   readonly step: WorkflowStepLike;
 }
@@ -341,4 +422,4 @@ interface LunoraWorkflowsOptions {
   */
   bindings: Record<string, WorkflowBindingLike>;
 }
-export { ArgsOf as A, WorkflowStepRollbackOptionsLike as B, FunctionReference as F, InferStepArgs as I, LunoraWorkflowsOptions as L, RunFunctionOptions as R, StepArgsValidator as S, WorkflowDefinition as W, Workflows as a, StepConfig as b, StepDefinition as c, WorkflowConfig as d, WorkflowInstanceStatus as e, WorkflowLogger as f, WorkflowEventLike as g, WorkflowStepLike as h, WorkflowRunContext as i, WorkflowRunFunction as j, WorkflowRunStepFunction as k, RunStepOptions as l, StepHandler as m, StepRollbackContext as n, StepRollbackHandler as o, StepRunContext as p, WorkflowBindingLike as q, WorkflowCreateOptions as r, WorkflowHandle as s, WorkflowHandler as t, WorkflowInstanceLike as u, WorkflowRollbackContextLike as v, WorkflowRollbackHandlerLike as w, WorkflowStatusResult as x, WorkflowStepConfigLike as y, WorkflowStepContextLike as z };
+export { ArgsOf as A, BranchCompensationParams as B, WorkflowSpawnFunction as C, WorkflowSpawnOptions as D, WorkflowStatusResult as E, FunctionReference as F, WorkflowStepConfigLike as G, WorkflowStepContextLike as H, InferStepArgs as I, WorkflowStepRollbackOptionsLike as J, LunoraWorkflowsOptions as L, RunFunctionOptions as R, StepArgsValidator as S, WorkflowDefinition as W, Workflows as a, StepConfig as b, StepDefinition as c, WorkflowConfig as d, WorkflowBranch as e, WorkflowInstanceStatus as f, WorkflowEventLike as g, WorkflowStepLike as h, WorkflowRunContext as i, WorkflowLogger as j, WorkflowRunFunction as k, WorkflowRunStepFunction as l, RunStepOptions as m, StepHandler as n, StepRollbackContext as o, StepRollbackHandler as p, StepRunContext as q, WorkflowBindingLike as r, WorkflowBranchOutputs as s, WorkflowCreateOptions as t, WorkflowHandle as u, WorkflowHandler as v, WorkflowInstanceLike as w, WorkflowParallelFunction as x, WorkflowRollbackContextLike as y, WorkflowRollbackHandlerLike as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/workflow",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.10",
   "description": "Durable workflows for Lunora: defineWorkflow over Cloudflare Workflows, generated WorkflowEntrypoint classes, and the ctx.workflows surface",
   "keywords": [
     "cloudflare",
@@ -23,7 +23,7 @@
     "directory": "packages/workflow"
   },
   "files": [
-    "dist",
+    "./dist",
     "README.md",
     "LICENSE.md",
     "__assets__"
@@ -48,7 +48,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/values": "1.0.0-alpha.1"
+    "@lunora/errors": "1.0.0-alpha.5",
+    "@lunora/values": "1.0.0-alpha.8"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"

package/dist/packem_shared/createWorkflowLogger-FktqxNLe.mjs

@@ -1,76 +0,0 @@
-import { createRunStep } from './createRunStep-BsK4LsUX.mjs';
-
-const trimTrailingSlashes = (value) => {
-  let end = value.length;
-  while (end > 0 && value[end - 1] === "/") {
-    end -= 1;
-  }
-  return value.slice(0, end);
-};
-const createWorkflowRunner = (options) => {
-  const globalFetch = globalThis.fetch;
-  const fetchImpl = options.fetchImpl ?? (typeof globalFetch === "function" ? globalFetch.bind(globalThis) : void 0);
-  return async (function_, args, runOptions = {}) => {
-    if (typeof fetchImpl !== "function") {
-      throw new TypeError("@lunora/workflow: no fetch implementation available — pass fetchImpl or run on a platform with global fetch");
-    }
-    const origin = options.env.LUNORA_ORIGIN_URL;
-    if (typeof origin !== "string" || origin.length === 0) {
-      throw new Error("@lunora/workflow: `LUNORA_ORIGIN_URL` must be set on the Worker env so a workflow can call back into Lunora functions");
-    }
-    const token = options.env.LUNORA_ADMIN_TOKEN;
-    if (typeof token !== "string" || token.length === 0) {
-      throw new Error("@lunora/workflow: `LUNORA_ADMIN_TOKEN` must be set on the Worker env to authenticate workflow function dispatch");
-    }
-    const url = `${trimTrailingSlashes(origin)}/_lunora/scheduler/dispatch`;
-    const response = await fetchImpl(url, {
-      body: JSON.stringify({ args: args ?? {}, functionPath: function_.__lunoraRef, shardKey: runOptions.shardKey }),
-      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
-      method: "POST"
-    });
-    if (!response.ok) {
-      throw new Error(`@lunora/workflow: function dispatch failed (${String(response.status)}): ${await response.text()}`);
-    }
-    const text = await response.text();
-    if (text.length === 0) {
-      return void 0;
-    }
-    try {
-      return JSON.parse(text);
-    } catch {
-      return text;
-    }
-  };
-};
-const createWorkflowLogger = (exportName) => {
-  const prefix = `[workflow:${exportName}]`;
-  return {
-    debug: (message, ...rest) => {
-      console.debug(prefix, message, ...rest);
-    },
-    error: (message, ...rest) => {
-      console.error(prefix, message, ...rest);
-    },
-    info: (message, ...rest) => {
-      console.info(prefix, message, ...rest);
-    },
-    warn: (message, ...rest) => {
-      console.warn(prefix, message, ...rest);
-    }
-  };
-};
-const createWorkflowRunContext = (options) => {
-  const log = createWorkflowLogger(options.exportName);
-  const run = createWorkflowRunner({ env: options.env, fetchImpl: options.fetchImpl });
-  return {
-    env: options.env,
-    event: options.event,
-    log,
-    params: options.event.payload,
-    run,
-    runStep: createRunStep({ env: options.env, log, nonRetryableErrorClass: options.nonRetryableErrorClass, run, step: options.step }),
-    step: options.step
-  };
-};
-
-export { createWorkflowLogger, createWorkflowRunContext, createWorkflowRunner };

package/dist/packem_shared/createWorkflows-BoSYVIXg.mjs

@@ -1,23 +0,0 @@
-const handleFor = (binding) => {
-  return {
-    create: async (options) => binding.create(options),
-    createBatch: async (batch) => binding.createBatch(batch),
-    get: async (id) => binding.get(id)
-  };
-};
-const createWorkflows = (options) => {
-  const bindings = options.bindings ?? {};
-  return {
-    get: (name) => {
-      const binding = bindings[name];
-      if (binding === void 0) {
-        const known = Object.keys(bindings);
-        const suffix = known.length === 0 ? "no workflows are declared" : `known workflows: ${known.join(", ")}`;
-        throw new Error(`@lunora/workflow: no workflow named "${name}" (${suffix})`);
-      }
-      return handleFor(binding);
-    }
-  };
-};
-
-export { createWorkflows as default };