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

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

@@ -1,13 +1,13 @@
 import { ValidatorMap, InferValidatorMap, Validator } from '@lunora/values';
 /**
-* Opaque reference to a Lunora function. Mirrors the `FunctionReference` shape
-* emitted by `@lunora/codegen` (and consumed by `@lunora/client`). We avoid a
-* direct dependency to keep this package usable from the codegen pipeline
-* itself — identical rationale to `@lunora/scheduler`'s copy.
-*
-* The runtime identifier lives in `__lunoraRef` — this MUST stay in lockstep
-* with the codegen emit + `@lunora/client`'s `FunctionReference`.
-*/
+ * Opaque reference to a Lunora function. Mirrors the `FunctionReference` shape
+ * emitted by `@lunora/codegen` (and consumed by `@lunora/client`). We avoid a
+ * direct dependency to keep this package usable from the codegen pipeline
+ * itself — identical rationale to `@lunora/scheduler`'s copy.
+ *
+ * The runtime identifier lives in `__lunoraRef` — this MUST stay in lockstep
+ * with the codegen emit + `@lunora/client`'s `FunctionReference`.
+ */
 interface FunctionReference {
   readonly __lunoraRef: string;
   /** Marker phantom type — discriminates queries / mutations / actions. */
@@ -53,11 +53,11 @@ interface WorkflowInstanceLike {
   terminate: () => Promise<void>;
 }
 /**
-* The subset of the Cloudflare `Workflow` binding the package consumes.
-* `createBatch` is a non-optional method on the real binding (Cloudflare's
-* `Workflow` class declares it unconditionally), so it is required here too —
-* the handle never has to guard for its absence.
-*/
+ * The subset of the Cloudflare `Workflow` binding the package consumes.
+ * `createBatch` is a non-optional method on the real binding (Cloudflare's
+ * `Workflow` class declares it unconditionally), so it is required here too —
+ * the handle never has to guard for its absence.
+ */
 interface WorkflowBindingLike<Params = Record<string, unknown>> {
   create: (options?: WorkflowCreateOptions<Params>) => Promise<WorkflowInstanceLike>;
   createBatch: (batch: ReadonlyArray<WorkflowCreateOptions<Params>>) => Promise<WorkflowInstanceLike[]>;
@@ -80,10 +80,10 @@ interface WorkflowStepConfigLike {
   timeout?: number | string;
 }
 /**
-* The per-attempt info Cloudflare passes a `step.do` callback. Mirrors
-* `WorkflowStepContext` — `attempt` is the 1-based retry counter (`> 1` on
-* retries) and `step` carries the durable step's name + invocation count.
-*/
+ * The per-attempt info Cloudflare passes a `step.do` callback. Mirrors
+ * `WorkflowStepContext` — `attempt` is the 1-based retry counter (`> 1` on
+ * retries) and `step` carries the durable step's name + invocation count.
+ */
 interface WorkflowStepContextLike {
   /** 1-based attempt counter — `> 1` means this is a retry. */
   attempt: number;
@@ -114,19 +114,19 @@ interface WorkflowStepRollbackOptionsLike<T = unknown> {
   rollbackConfig?: WorkflowStepConfigLike;
 }
 /**
-* The durable step API Cloudflare hands the workflow body. Mirrors
-* `WorkflowStep` — `do` memoizes + retries its callback, `sleep`/`sleepUntil`
-* are durable delays, and `waitForEvent` hibernates until an external event.
-* `do`'s two overloads mirror Cloudflare's: an optional leading `config` and an
-* optional trailing `rollback` (compensation run when a later step fails).
-*
-* Known mirror gap: Cloudflare constrains `do&lt;T extends Rpc.Serializable&lt;T>>` so
-* a non-serializable step result (a function, `Map`, class instance, …) is a
-* compile error there. `Rpc.Serializable` lives in `@cloudflare/workers-types`
-* and is not Node-importable, so this Node-safe mirror uses a bare `&lt;T>` and
-* cannot enforce that — a non-serializable result type-checks here but fails at
-* runtime on the platform. Keep step results JSON-serialisable.
-*/
+ * The durable step API Cloudflare hands the workflow body. Mirrors
+ * `WorkflowStep` — `do` memoizes + retries its callback, `sleep`/`sleepUntil`
+ * are durable delays, and `waitForEvent` hibernates until an external event.
+ * `do`'s two overloads mirror Cloudflare's: an optional leading `config` and an
+ * optional trailing `rollback` (compensation run when a later step fails).
+ *
+ * Known mirror gap: Cloudflare constrains `do&lt;T extends Rpc.Serializable&lt;T>>` so
+ * a non-serializable step result (a function, `Map`, class instance, …) is a
+ * compile error there. `Rpc.Serializable` lives in `@cloudflare/workers-types`
+ * and is not Node-importable, so this Node-safe mirror uses a bare `&lt;T>` and
+ * cannot enforce that — a non-serializable result type-checks here but fails at
+ * runtime on the platform. Keep step results JSON-serialisable.
+ */
 interface WorkflowStepLike {
   do: {
     <T>(name: string, callback: (context: WorkflowStepContextLike) => Promise<T>, rollback?: WorkflowStepRollbackOptionsLike<T>): Promise<T>;
@@ -155,25 +155,25 @@ interface RunFunctionOptions {
   shardKey?: string;
 }
 /**
-* Calls a Lunora query / mutation / action from inside a workflow and resolves
-* with its result. Wrap it in {@link WorkflowStepLike.do} to make the call a
-* durable, memoized, retried step:
-*
-* ```ts
-* const charge = await ctx.step.do("charge", () => ctx.run(api.payments.charge, { id }));
-* ```
-*/
+ * Calls a Lunora query / mutation / action from inside a workflow and resolves
+ * with its result. Wrap it in {@link WorkflowStepLike.do} to make the call a
+ * durable, memoized, retried step:
+ *
+ * ```ts
+ * const charge = await ctx.step.do("charge", () => ctx.run(api.payments.charge, { id }));
+ * ```
+ */
 type WorkflowRunFunction = <F extends FunctionReference>(function_: F, args?: ArgsOf<F>, options?: RunFunctionOptions) => Promise<unknown>;
 /** Map of validators describing a step's args record — the same shape a Lunora function's `args` uses. Alias of `@lunora/values`' shared {@link ValidatorMap}. */
 type StepArgsValidator = ValidatorMap;
 /** Infer the args object type from a {@link StepArgsValidator} (optional validators → optional keys). Alias of `@lunora/values`' shared {@link InferValidatorMap}. */
 type InferStepArgs<A extends StepArgsValidator> = InferValidatorMap<A>;
 /**
-* The context a {@link StepDefinition} handler receives as its first argument
-* (the validated args are the second). Bundles the native per-attempt info
-* (`attempt`, `config`, `step`) with the Worker `env`, the Lunora runner, and a
-* logger.
-*/
+ * The context a {@link StepDefinition} handler receives as its first argument
+ * (the validated args are the second). Bundles the native per-attempt info
+ * (`attempt`, `config`, `step`) with the Worker `env`, the Lunora runner, and a
+ * logger.
+ */
 interface StepRunContext {
   /** 1-based retry counter — `> 1` means Cloudflare is retrying the step. */
   readonly attempt: number;
@@ -226,10 +226,10 @@ interface StepConfig<A extends StepArgsValidator, Result> {
   rollbackConfig?: WorkflowStepConfigLike;
 }
 /**
-* A `defineStep` result — a reusable, schema-validated durable step. Run it from
-* a workflow body with `ctx.runStep(step, args)`. The phantom generics carry the
-* inferred args + result types to the call site.
-*/
+ * A `defineStep` result — a reusable, schema-validated durable step. Run it from
+ * a workflow body with `ctx.runStep(step, args)`. The phantom generics carry the
+ * inferred args + result types to the call site.
+ */
 interface StepDefinition<A extends StepArgsValidator = StepArgsValidator, Result = unknown> {
   /** Validators for the step's args. */
   readonly args: A;
@@ -254,33 +254,33 @@ interface RunStepOptions {
   config?: WorkflowStepConfigLike;
 }
 /**
-* Run a reusable {@link StepDefinition} as a durable, memoized, retried step:
-* validates the args before the body runs and the result after (when the step
-* declares `returns`), and forwards any rollback handler to Cloudflare.
-*
-* ```ts
-* const data = await ctx.runStep(fetchImage, { imageKey });
-* ```
-*/
+ * Run a reusable {@link StepDefinition} as a durable, memoized, retried step:
+ * validates the args before the body runs and the result after (when the step
+ * declares `returns`), and forwards any rollback handler to Cloudflare.
+ *
+ * ```ts
+ * const data = await ctx.runStep(fetchImage, { imageKey });
+ * ```
+ */
 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.
-*/
+ * 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).
-  */
+   * 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;
@@ -292,11 +292,11 @@ interface WorkflowBranch<Output = unknown> {
   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.
-*/
+ * 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;
@@ -313,20 +313,20 @@ interface BranchCompensationParams {
   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 };
+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 }),
-* ]);
-* ```
-*/
+ * 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 {
@@ -334,17 +334,17 @@ interface WorkflowSpawnOptions {
   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.
-*/
+ * 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 fan-out primitives
-* (`parallel` / `spawn`), the Worker `env`, and a logger.
-*/
+ * 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 fan-out primitives
+ * (`parallel` / `spawn`), the Worker `env`, and a logger.
+ */
 interface WorkflowRunContext<Params = Record<string, unknown>> {
   /** The Worker environment bindings. */
   readonly env: Record<string, unknown>;
@@ -372,19 +372,19 @@ interface WorkflowConfig<Params = Record<string, unknown>, Output = unknown> {
   /** The workflow body — the multi-step durable program. */
   handler: WorkflowHandler<Params, Output>;
   /**
-  * Optional override for the deployed workflow name — the `workflows[].name`
-  * written to `wrangler.jsonc`. Defaults to a kebab-cased form of the
-  * `lunora/workflows.ts` export name (`orderPipeline` → `order-pipeline`).
-  * This does NOT change the binding name, which is always derived from the
-  * export name (`orderPipeline` → `WORKFLOW_ORDER_PIPELINE`).
-  */
+   * Optional override for the deployed workflow name — the `workflows[].name`
+   * written to `wrangler.jsonc`. Defaults to a kebab-cased form of the
+   * `lunora/workflows.ts` export name (`orderPipeline` → `order-pipeline`).
+   * This does NOT change the binding name, which is always derived from the
+   * export name (`orderPipeline` → `WORKFLOW_ORDER_PIPELINE`).
+   */
   name?: string;
 }
 /**
-* A `defineWorkflow` result — the config plus the runtime brand codegen and the
-* config layer use to discover it. The phantom `__params` / `__output` carry
-* the inferred types to the generated `ctx.workflows` handle.
-*/
+ * A `defineWorkflow` result — the config plus the runtime brand codegen and the
+ * config layer use to discover it. The phantom `__params` / `__output` carry
+ * the inferred types to the generated `ctx.workflows` handle.
+ */
 interface WorkflowDefinition<Params = Record<string, unknown>, Output = unknown> extends WorkflowConfig<Params, Output> {
   /** Phantom marker for the output type — never present at runtime. */
   readonly __output?: Output;
@@ -394,9 +394,9 @@ interface WorkflowDefinition<Params = Record<string, unknown>, Output = unknown>
   readonly isLunoraWorkflow: true;
 }
 /**
-* A typed handle to one declared workflow, addressable from `ctx.workflows`.
-* Thin pass-through over the Cloudflare `Workflow` binding.
-*/
+ * A typed handle to one declared workflow, addressable from `ctx.workflows`.
+ * Thin pass-through over the Cloudflare `Workflow` binding.
+ */
 interface WorkflowHandle<Params = Record<string, unknown>> {
   /** Start a new instance (optionally with an id + params). */
   create: (options?: WorkflowCreateOptions<Params>) => Promise<WorkflowInstanceLike>;
@@ -406,9 +406,9 @@ interface WorkflowHandle<Params = Record<string, unknown>> {
   get: (id: string) => Promise<WorkflowInstanceLike>;
 }
 /**
-* The `ctx.workflows` surface available on `MutationCtx` and `ActionCtx`. Each
-* declared workflow is reachable by its `lunora/workflows.ts` export name.
-*/
+ * The `ctx.workflows` surface available on `MutationCtx` and `ActionCtx`. Each
+ * declared workflow is reachable by its `lunora/workflows.ts` export name.
+ */
 interface Workflows {
   /** Resolve the handle for a declared workflow by export name. */
   get: <Params = Record<string, unknown>>(name: string) => WorkflowHandle<Params>;
@@ -416,10 +416,10 @@ interface Workflows {
 /** Options for `createWorkflows`. */
 interface LunoraWorkflowsOptions {
   /**
-  * Map of `lunora/workflows.ts` export name → its Cloudflare `Workflow`
-  * binding. Codegen builds this from `env` (`{ orderPipeline:
-  * env.WORKFLOW_ORDER_PIPELINE }`); for manual wiring construct it yourself.
-  */
+   * Map of `lunora/workflows.ts` export name → its Cloudflare `Workflow`
+   * binding. Codegen builds this from `env` (`{ orderPipeline:
+   * env.WORKFLOW_ORDER_PIPELINE }`); for manual wiring construct it yourself.
+   */
   bindings: Record<string, WorkflowBindingLike>;
 }
 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.10",
+  "version": "1.0.0-alpha.12",
   "description": "Durable workflows for Lunora: defineWorkflow over Cloudflare Workflows, generated WorkflowEntrypoint classes, and the ctx.workflows surface",
   "keywords": [
     "cloudflare",
@@ -48,8 +48,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.5",
-    "@lunora/values": "1.0.0-alpha.8"
+    "@lunora/errors": "1.0.0-alpha.7",
+    "@lunora/values": "1.0.0-alpha.10"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"