@lunora/workflow 1.0.0-alpha.2 → 1.0.0-alpha.4

package/dist/do/index.d.mts

@@ -1,5 +1,5 @@
 import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from 'cloudflare:workers';
-import { W as WorkflowDefinition } from "../packem_shared/types.d-CQO_koGe.mjs";
+import { W as WorkflowDefinition } from "../packem_shared/types.d-Fdeu2P2C.mjs";
 import '@lunora/values';
 /**
 * Base class for the generated `WorkflowEntrypoint` classes. Applies a

package/dist/do/index.d.ts

@@ -1,5 +1,5 @@
 import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from 'cloudflare:workers';
-import { W as WorkflowDefinition } from "../packem_shared/types.d-CQO_koGe.js";
+import { W as WorkflowDefinition } from "../packem_shared/types.d-Fdeu2P2C.js";
 import '@lunora/values';
 /**
 * Base class for the generated `WorkflowEntrypoint` classes. Applies a

package/dist/do/index.mjs

@@ -1,7 +1,8 @@
 import { WorkflowEntrypoint } from 'cloudflare:workers';
 import { NonRetryableError } from 'cloudflare:workflows';
 import { convertNonRetryableError } from '../packem_shared/NonRetryableError-Dn2dTyBS.mjs';
-import { createWorkflowRunContext } from '../packem_shared/createWorkflowLogger-DR8P4ZoY.mjs';
+import { stripBranchMarker, signalBranchParent, extractBranchMarker, errorOutcome, okOutcome } from '../packem_shared/MAX_BRANCHES-C9MJIFii.mjs';
+import { createWorkflowRunContext } from '../packem_shared/createWorkflowRunContext-BsMyGuMR.mjs';
 
 class LunoraWorkflow extends WorkflowEntrypoint {
   /** The `lunora/workflows.ts` export name, for log correlation. */
@@ -14,18 +15,29 @@ class LunoraWorkflow extends WorkflowEntrypoint {
     this.#lunoraName = exportName ?? "workflow";
   }
   async run(event, step) {
+    const nativeStep = step;
+    const marker = extractBranchMarker(event.payload);
+    const handlerEvent = marker ? { ...event, payload: stripBranchMarker(event.payload) } : event;
     const context = createWorkflowRunContext({
       env: this.env,
-      event,
+      event: handlerEvent,
       exportName: this.#lunoraName,
       nonRetryableErrorClass: NonRetryableError,
-      step
+      step: nativeStep
     });
+    let output;
     try {
-      return await this.#definition.handler(context);
+      output = await this.#definition.handler(context);
     } catch (error) {
+      if (marker) {
+        await signalBranchParent({ env: this.env, step: nativeStep }, marker, errorOutcome(error));
+      }
       return convertNonRetryableError(error, NonRetryableError);
     }
+    if (marker) {
+      await signalBranchParent({ env: this.env, step: nativeStep }, marker, okOutcome(output));
+    }
+    return output;
   }
 }
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { a as Workflows, L as LunoraWorkflowsOptions, S as StepArgsValidator, b as StepConfig, c as StepDefinition, d as WorkflowConfig, W as WorkflowDefinition, e as WorkflowInstanceStatus, f as WorkflowLogger, g as WorkflowEventLike, h as WorkflowStepLike, i as WorkflowRunContext, j as WorkflowRunFunction, k as WorkflowRunStepFunction } from "./packem_shared/types.d-CQO_koGe.mjs";
-export type { A as ArgsOf, F as FunctionReference, I as InferStepArgs, R as RunFunctionOptions, l as RunStepOptions, m as StepHandler, n as StepRollbackContext, o as StepRollbackHandler, p as StepRunContext, q as WorkflowBindingLike, r as WorkflowCreateOptions, s as WorkflowHandle, t as WorkflowHandler, u as WorkflowInstanceLike, v as WorkflowRollbackContextLike, w as WorkflowRollbackHandlerLike, x as WorkflowStatusResult, y as WorkflowStepConfigLike, z as WorkflowStepContextLike, B as WorkflowStepRollbackOptionsLike } from "./packem_shared/types.d-CQO_koGe.mjs";
+import { a as Workflows, L as LunoraWorkflowsOptions, S as StepArgsValidator, b as StepConfig, c as StepDefinition, d as WorkflowConfig, W as WorkflowDefinition, e as WorkflowBranch, f as WorkflowInstanceStatus, g as WorkflowEventLike, h as WorkflowStepLike, i as WorkflowRunContext, j as WorkflowLogger, k as WorkflowRunFunction, l as WorkflowRunStepFunction } from "./packem_shared/types.d-Fdeu2P2C.mjs";
+export type { A as ArgsOf, F as FunctionReference, I as InferStepArgs, R as RunFunctionOptions, m as RunStepOptions, n as StepHandler, o as StepRollbackContext, p as StepRollbackHandler, q as StepRunContext, r as WorkflowBindingLike, s as WorkflowBranchOutputs, t as WorkflowCreateOptions, u as WorkflowHandle, v as WorkflowHandler, w as WorkflowInstanceLike, x as WorkflowParallelFunction, y as WorkflowRollbackContextLike, z as WorkflowRollbackHandlerLike, B as WorkflowSpawnFunction, C as WorkflowSpawnOptions, D as WorkflowStatusResult, E as WorkflowStepConfigLike, G as WorkflowStepContextLike, H as WorkflowStepRollbackOptionsLike } from "./packem_shared/types.d-Fdeu2P2C.mjs";
 import '@lunora/values';
 /** Wiring info for one declared workflow, emitted by codegen into the generated shard. */
 interface WorkflowBindingSpec {
@@ -131,6 +131,21 @@ declare const toNativeNonRetryableError: (error: NonRetryableError, NativeNonRet
 * Always throws — the `never` return lets callers `return convertNonRetryableError(...)`.
 */
 declare const convertNonRetryableError: (error: unknown, NativeNonRetryableError: NativeNonRetryableErrorConstructor | undefined) => never;
+/** Hard cap on branches per `ctx.parallel` call — auto-scale, never silently spawn unbounded DOs. */
+declare const MAX_BRANCHES = 100;
+/** The params key the parent injects so a child knows to signal completion back. Stripped before the user handler sees `ctx.params`. */
+
+/**
+* Build a single fan-out branch: a declared child workflow referenced by its
+* `lunora/workflows.ts` export name, plus the params it is created with. Pass the
+* output type as the generic argument so `ctx.parallel(...)` infers the result
+* tuple — e.g. `branch("imageTag", { key })` typed as `branch` of `{ tags }`.
+*/
+declare const branch: <Output = unknown>(workflow: string, params?: Record<string, unknown>, options?: {
+  id?: string;
+  timeout?: number | string;
+}) => WorkflowBranch<Output>;
+/** Build the success outcome a completed branch reports to its parent. */
 /** The lifecycle mutations the REST API exposes via `PATCH .../instances/{id}`. */
 type WorkflowInstanceAction = "pause" | "resume" | "terminate";
 /** Configuration for a {@link WorkflowsRestClient}. */
@@ -209,24 +224,6 @@ interface WorkflowsRestClient {
 * snake_case payload into the camelCase shapes the studio renders.
 */
 declare const createWorkflowsRestClient: (config: WorkflowsRestConfig) => WorkflowsRestClient;
-interface RunnerOptions {
-  /** Worker `env` — read `LUNORA_ORIGIN_URL` + `LUNORA_ADMIN_TOKEN` at call time. */
-  env: Record<string, unknown>;
-  /** Injectable fetch (tests); defaults to the global. */
-  fetchImpl?: typeof fetch;
-}
-/**
-* Build a {@link WorkflowRunFunction} that invokes a Lunora function by POSTing
-* to the Worker's `/_lunora/scheduler/dispatch` endpoint — the same path the
-* SchedulerDO and the Queues workpool dispatch through — authenticated with the
-* admin bearer. The parsed JSON body (the function's return value) is resolved;
-* an empty/non-JSON body resolves to `undefined`.
-*
-* Wrap calls in `ctx.step.do(...)` to make them durable + memoized + retried.
-*/
-declare const createWorkflowRunner: (options: RunnerOptions) => WorkflowRunFunction;
-/** Console-backed logger, prefixed with the workflow name for log correlation. */
-declare const createWorkflowLogger: (exportName: string) => WorkflowLogger;
 interface RunContextOptions<Params> {
   env: Record<string, unknown>;
   event: WorkflowEventLike<Params>;
@@ -266,4 +263,4 @@ interface RunStepDeps {
 * converted to the native one and any declared rollback forwarded to Cloudflare.
 */
 declare const createRunStep: (deps: RunStepDeps) => WorkflowRunStepFunction;
-export { type LunoraWorkflowsOptions, type NativeNonRetryableErrorConstructor, NonRetryableError, type StepArgsValidator, type StepConfig, type StepDefinition, type WorkflowBindingSpec, type WorkflowConfig, type WorkflowDefinition, type WorkflowEventLike, type WorkflowInstanceAction, type WorkflowInstanceDetail, type WorkflowInstancePage, type WorkflowInstanceStatus, type WorkflowInstanceSummary, type WorkflowLogger, type WorkflowRunContext, type WorkflowRunFunction, type WorkflowRunStepFunction, type WorkflowStepDetail, type WorkflowStepLike, type Workflows, type WorkflowsRestClient, type WorkflowsRestConfig, WorkflowsRestError, convertNonRetryableError, createRunStep, createWorkflowContext, createWorkflowLogger, createWorkflowRunContext, createWorkflowRunner, createWorkflows, createWorkflowsRestClient, defineStep, defineWorkflow, isNonRetryableError, isStepDefinition, isWorkflowDefinition, toNativeNonRetryableError, validateStepArgs, workflowBindingName, workflowClassName, workflowDefaultName };
+export { type LunoraWorkflowsOptions, MAX_BRANCHES, type NativeNonRetryableErrorConstructor, NonRetryableError, type StepArgsValidator, type StepConfig, type StepDefinition, type WorkflowBindingSpec, type WorkflowBranch, type WorkflowConfig, type WorkflowDefinition, type WorkflowEventLike, type WorkflowInstanceAction, type WorkflowInstanceDetail, type WorkflowInstancePage, type WorkflowInstanceStatus, type WorkflowInstanceSummary, type WorkflowLogger, type WorkflowRunContext, type WorkflowRunFunction, type WorkflowRunStepFunction, type WorkflowStepDetail, type WorkflowStepLike, type Workflows, type WorkflowsRestClient, type WorkflowsRestConfig, WorkflowsRestError, branch, convertNonRetryableError, createRunStep, createWorkflowContext, createWorkflowRunContext, createWorkflows, createWorkflowsRestClient, defineStep, defineWorkflow, isNonRetryableError, isStepDefinition, isWorkflowDefinition, toNativeNonRetryableError, validateStepArgs, workflowBindingName, workflowClassName, workflowDefaultName };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as Workflows, L as LunoraWorkflowsOptions, S as StepArgsValidator, b as StepConfig, c as StepDefinition, d as WorkflowConfig, W as WorkflowDefinition, e as WorkflowInstanceStatus, f as WorkflowLogger, g as WorkflowEventLike, h as WorkflowStepLike, i as WorkflowRunContext, j as WorkflowRunFunction, k as WorkflowRunStepFunction } from "./packem_shared/types.d-CQO_koGe.js";
-export type { A as ArgsOf, F as FunctionReference, I as InferStepArgs, R as RunFunctionOptions, l as RunStepOptions, m as StepHandler, n as StepRollbackContext, o as StepRollbackHandler, p as StepRunContext, q as WorkflowBindingLike, r as WorkflowCreateOptions, s as WorkflowHandle, t as WorkflowHandler, u as WorkflowInstanceLike, v as WorkflowRollbackContextLike, w as WorkflowRollbackHandlerLike, x as WorkflowStatusResult, y as WorkflowStepConfigLike, z as WorkflowStepContextLike, B as WorkflowStepRollbackOptionsLike } from "./packem_shared/types.d-CQO_koGe.js";
+import { a as Workflows, L as LunoraWorkflowsOptions, S as StepArgsValidator, b as StepConfig, c as StepDefinition, d as WorkflowConfig, W as WorkflowDefinition, e as WorkflowBranch, f as WorkflowInstanceStatus, g as WorkflowEventLike, h as WorkflowStepLike, i as WorkflowRunContext, j as WorkflowLogger, k as WorkflowRunFunction, l as WorkflowRunStepFunction } from "./packem_shared/types.d-Fdeu2P2C.js";
+export type { A as ArgsOf, F as FunctionReference, I as InferStepArgs, R as RunFunctionOptions, m as RunStepOptions, n as StepHandler, o as StepRollbackContext, p as StepRollbackHandler, q as StepRunContext, r as WorkflowBindingLike, s as WorkflowBranchOutputs, t as WorkflowCreateOptions, u as WorkflowHandle, v as WorkflowHandler, w as WorkflowInstanceLike, x as WorkflowParallelFunction, y as WorkflowRollbackContextLike, z as WorkflowRollbackHandlerLike, B as WorkflowSpawnFunction, C as WorkflowSpawnOptions, D as WorkflowStatusResult, E as WorkflowStepConfigLike, G as WorkflowStepContextLike, H as WorkflowStepRollbackOptionsLike } from "./packem_shared/types.d-Fdeu2P2C.js";
 import '@lunora/values';
 /** Wiring info for one declared workflow, emitted by codegen into the generated shard. */
 interface WorkflowBindingSpec {
@@ -131,6 +131,21 @@ declare const toNativeNonRetryableError: (error: NonRetryableError, NativeNonRet
 * Always throws — the `never` return lets callers `return convertNonRetryableError(...)`.
 */
 declare const convertNonRetryableError: (error: unknown, NativeNonRetryableError: NativeNonRetryableErrorConstructor | undefined) => never;
+/** Hard cap on branches per `ctx.parallel` call — auto-scale, never silently spawn unbounded DOs. */
+declare const MAX_BRANCHES = 100;
+/** The params key the parent injects so a child knows to signal completion back. Stripped before the user handler sees `ctx.params`. */
+
+/**
+* Build a single fan-out branch: a declared child workflow referenced by its
+* `lunora/workflows.ts` export name, plus the params it is created with. Pass the
+* output type as the generic argument so `ctx.parallel(...)` infers the result
+* tuple — e.g. `branch("imageTag", { key })` typed as `branch` of `{ tags }`.
+*/
+declare const branch: <Output = unknown>(workflow: string, params?: Record<string, unknown>, options?: {
+  id?: string;
+  timeout?: number | string;
+}) => WorkflowBranch<Output>;
+/** Build the success outcome a completed branch reports to its parent. */
 /** The lifecycle mutations the REST API exposes via `PATCH .../instances/{id}`. */
 type WorkflowInstanceAction = "pause" | "resume" | "terminate";
 /** Configuration for a {@link WorkflowsRestClient}. */
@@ -209,24 +224,6 @@ interface WorkflowsRestClient {
 * snake_case payload into the camelCase shapes the studio renders.
 */
 declare const createWorkflowsRestClient: (config: WorkflowsRestConfig) => WorkflowsRestClient;
-interface RunnerOptions {
-  /** Worker `env` — read `LUNORA_ORIGIN_URL` + `LUNORA_ADMIN_TOKEN` at call time. */
-  env: Record<string, unknown>;
-  /** Injectable fetch (tests); defaults to the global. */
-  fetchImpl?: typeof fetch;
-}
-/**
-* Build a {@link WorkflowRunFunction} that invokes a Lunora function by POSTing
-* to the Worker's `/_lunora/scheduler/dispatch` endpoint — the same path the
-* SchedulerDO and the Queues workpool dispatch through — authenticated with the
-* admin bearer. The parsed JSON body (the function's return value) is resolved;
-* an empty/non-JSON body resolves to `undefined`.
-*
-* Wrap calls in `ctx.step.do(...)` to make them durable + memoized + retried.
-*/
-declare const createWorkflowRunner: (options: RunnerOptions) => WorkflowRunFunction;
-/** Console-backed logger, prefixed with the workflow name for log correlation. */
-declare const createWorkflowLogger: (exportName: string) => WorkflowLogger;
 interface RunContextOptions<Params> {
   env: Record<string, unknown>;
   event: WorkflowEventLike<Params>;
@@ -266,4 +263,4 @@ interface RunStepDeps {
 * converted to the native one and any declared rollback forwarded to Cloudflare.
 */
 declare const createRunStep: (deps: RunStepDeps) => WorkflowRunStepFunction;
-export { type LunoraWorkflowsOptions, type NativeNonRetryableErrorConstructor, NonRetryableError, type StepArgsValidator, type StepConfig, type StepDefinition, type WorkflowBindingSpec, type WorkflowConfig, type WorkflowDefinition, type WorkflowEventLike, type WorkflowInstanceAction, type WorkflowInstanceDetail, type WorkflowInstancePage, type WorkflowInstanceStatus, type WorkflowInstanceSummary, type WorkflowLogger, type WorkflowRunContext, type WorkflowRunFunction, type WorkflowRunStepFunction, type WorkflowStepDetail, type WorkflowStepLike, type Workflows, type WorkflowsRestClient, type WorkflowsRestConfig, WorkflowsRestError, convertNonRetryableError, createRunStep, createWorkflowContext, createWorkflowLogger, createWorkflowRunContext, createWorkflowRunner, createWorkflows, createWorkflowsRestClient, defineStep, defineWorkflow, isNonRetryableError, isStepDefinition, isWorkflowDefinition, toNativeNonRetryableError, validateStepArgs, workflowBindingName, workflowClassName, workflowDefaultName };
+export { type LunoraWorkflowsOptions, MAX_BRANCHES, type NativeNonRetryableErrorConstructor, NonRetryableError, type StepArgsValidator, type StepConfig, type StepDefinition, type WorkflowBindingSpec, type WorkflowBranch, type WorkflowConfig, type WorkflowDefinition, type WorkflowEventLike, type WorkflowInstanceAction, type WorkflowInstanceDetail, type WorkflowInstancePage, type WorkflowInstanceStatus, type WorkflowInstanceSummary, type WorkflowLogger, type WorkflowRunContext, type WorkflowRunFunction, type WorkflowRunStepFunction, type WorkflowStepDetail, type WorkflowStepLike, type Workflows, type WorkflowsRestClient, type WorkflowsRestConfig, WorkflowsRestError, branch, convertNonRetryableError, createRunStep, createWorkflowContext, createWorkflowRunContext, createWorkflows, createWorkflowsRestClient, defineStep, defineWorkflow, isNonRetryableError, isStepDefinition, isWorkflowDefinition, toNativeNonRetryableError, validateStepArgs, workflowBindingName, workflowClassName, workflowDefaultName };

package/dist/index.mjs

@@ -3,6 +3,7 @@ export { default as createWorkflows } from './packem_shared/createWorkflows-BoSY
 export { defineStep, isStepDefinition } from './packem_shared/defineStep-DJQtLw7g.mjs';
 export { defineWorkflow, isWorkflowDefinition, workflowBindingName, workflowClassName, workflowDefaultName } from './packem_shared/defineWorkflow-DbUC-oCN.mjs';
 export { NonRetryableError, convertNonRetryableError, isNonRetryableError, toNativeNonRetryableError } from './packem_shared/NonRetryableError-Dn2dTyBS.mjs';
+export { MAX_BRANCHES, branch } from './packem_shared/MAX_BRANCHES-C9MJIFii.mjs';
 export { WorkflowsRestError, createWorkflowsRestClient } from './packem_shared/WorkflowsRestError-b06i7K5j.mjs';
-export { createWorkflowLogger, createWorkflowRunContext, createWorkflowRunner } from './packem_shared/createWorkflowLogger-DR8P4ZoY.mjs';
+export { createWorkflowRunContext } from './packem_shared/createWorkflowRunContext-BsMyGuMR.mjs';
 export { createRunStep, validateStepArgs } from './packem_shared/createRunStep-8jOXxP2o.mjs';

package/dist/packem_shared/MAX_BRANCHES-C9MJIFii.mjs

@@ -0,0 +1,108 @@
+import { NonRetryableError } from './NonRetryableError-Dn2dTyBS.mjs';
+
+const MAX_BRANCHES = 100;
+const BRANCH_MARKER_KEY = "__lunoraBranch";
+const SPAWN_STEP_PREFIX = "lunora:spawn:";
+const AWAIT_STEP_PREFIX = "lunora:await:";
+const SIGNAL_STEP_PREFIX = "lunora:signal:";
+const BRANCH_EVENT_PREFIX = "lunora:branch:";
+const branch = (workflow, params, options) => {
+  return { id: options?.id, params, timeout: options?.timeout, workflow };
+};
+const serializeError = (error) => {
+  if (error instanceof Error) {
+    return { message: error.message, name: error.name };
+  }
+  return { message: String(error), name: "Error" };
+};
+const okOutcome = (value) => {
+  return { status: "ok", value };
+};
+const errorOutcome = (error) => {
+  return { error: serializeError(error), status: "error" };
+};
+const createParallel = (deps) => {
+  const run = async (branches) => {
+    if (branches.length === 0) {
+      return [];
+    }
+    if (branches.length > MAX_BRANCHES) {
+      throw new NonRetryableError(
+        `ctx.parallel: ${String(branches.length)} branches exceeds the cap of ${String(MAX_BRANCHES)} — split the fan-out or raise the work into fewer child workflows`
+      );
+    }
+    const planned = branches.map((item, index) => {
+      const childId = deps.nextChildId(item.id);
+      return { childId, eventType: `${BRANCH_EVENT_PREFIX}${childId}`, index, item };
+    });
+    await Promise.all(
+      planned.map(
+        (plan) => deps.step.do(`${SPAWN_STEP_PREFIX}${plan.childId}`, async () => {
+          const binding = deps.resolveBinding(plan.item.workflow);
+          const marker = { eventType: plan.eventType, index: plan.index, parentBinding: deps.parentBinding, parentId: deps.instanceId };
+          await binding.create({ id: plan.childId, params: { ...plan.item.params, [BRANCH_MARKER_KEY]: marker } });
+          return plan.childId;
+        })
+      )
+    );
+    const results = [];
+    for (const plan of planned) {
+      const event = await deps.step.waitForEvent(`${AWAIT_STEP_PREFIX}${plan.childId}`, {
+        timeout: plan.item.timeout,
+        type: plan.eventType
+      });
+      const outcome = event.payload;
+      if (outcome.status === "error") {
+        throw new NonRetryableError(`ctx.parallel: branch "${plan.item.workflow}" (#${String(plan.index)}) failed: ${outcome.error.message}`);
+      }
+      results.push(outcome.value);
+    }
+    return results;
+  };
+  return run;
+};
+const createSpawn = (deps) => async (workflow, params, options) => {
+  const childId = deps.nextChildId(options?.id);
+  await deps.step.do(`${SPAWN_STEP_PREFIX}${childId}`, async () => {
+    const binding = deps.resolveBinding(workflow);
+    await binding.create({ id: childId, params });
+    return childId;
+  });
+  return deps.resolveBinding(workflow).get(childId);
+};
+const extractBranchMarker = (payload) => {
+  if (typeof payload !== "object" || payload === null) {
+    return void 0;
+  }
+  const marker = payload[BRANCH_MARKER_KEY];
+  if (typeof marker !== "object" || marker === null) {
+    return void 0;
+  }
+  const candidate = marker;
+  if (typeof candidate.eventType !== "string" || typeof candidate.parentBinding !== "string" || typeof candidate.parentId !== "string" || typeof candidate.index !== "number") {
+    return void 0;
+  }
+  return { eventType: candidate.eventType, index: candidate.index, parentBinding: candidate.parentBinding, parentId: candidate.parentId };
+};
+const stripBranchMarker = (payload) => {
+  if (typeof payload !== "object" || payload === null) {
+    return payload;
+  }
+  const rest = { ...payload };
+  Reflect.deleteProperty(rest, BRANCH_MARKER_KEY);
+  return rest;
+};
+const signalBranchParent = async (deps, marker, outcome) => {
+  const binding = deps.env[marker.parentBinding];
+  if (!binding || typeof binding.get !== "function") {
+    return;
+  }
+  const getParent = binding.get.bind(binding);
+  await deps.step.do(`${SIGNAL_STEP_PREFIX}${String(marker.index)}`, async () => {
+    const parent = await getParent(marker.parentId);
+    await parent.sendEvent({ payload: outcome, type: marker.eventType });
+    return marker.eventType;
+  });
+};
+
+export { BRANCH_MARKER_KEY, MAX_BRANCHES, branch, createParallel, createSpawn, errorOutcome, extractBranchMarker, okOutcome, signalBranchParent, stripBranchMarker };

package/dist/packem_shared/createWorkflowRunContext-BsMyGuMR.mjs

@@ -0,0 +1,110 @@
+import { workflowBindingName } from './defineWorkflow-DbUC-oCN.mjs';
+import { createSpawn, createParallel } from './MAX_BRANCHES-C9MJIFii.mjs';
+import { createRunStep } from './createRunStep-8jOXxP2o.mjs';
+
+const createDispatchLogger = (prefix) => {
+  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 SCHEDULER_DISPATCH_PATH = "/_lunora/scheduler/dispatch";
+const trimTrailingSlashes = (value) => {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") {
+    end -= 1;
+  }
+  return value.slice(0, end);
+};
+const createDispatchRunner = (options) => {
+  const { label } = 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(`${label}: 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(`${label}: \`LUNORA_ORIGIN_URL\` must be set on the Worker env so a handler can call back into Lunora functions`);
+    }
+    const token = options.env.LUNORA_ADMIN_TOKEN;
+    if (typeof token !== "string" || token.length === 0) {
+      throw new Error(`${label}: \`LUNORA_ADMIN_TOKEN\` must be set on the Worker env to authenticate function dispatch`);
+    }
+    const url = `${trimTrailingSlashes(origin)}${SCHEDULER_DISPATCH_PATH}`;
+    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(`${label}: 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 createWorkflowRunContext = (options) => {
+  const log = createDispatchLogger(`[workflow:${options.exportName}]`);
+  const run = createDispatchRunner({ env: options.env, fetchImpl: options.fetchImpl, label: "@lunora/workflow" });
+  const resolveBinding = (workflow) => {
+    const bindingName = workflowBindingName(workflow);
+    const binding = options.env[bindingName];
+    if (!binding || typeof binding.create !== "function" || typeof binding.get !== "function") {
+      throw new Error(
+        `@lunora/workflow: cannot spawn child workflow "${workflow}" — no Workflow binding "${bindingName}" on env (is it declared in lunora/workflows.ts?)`
+      );
+    }
+    return binding;
+  };
+  let childCounter = 0;
+  const nextChildId = (explicit) => {
+    if (explicit !== void 0) {
+      return explicit;
+    }
+    const id = `${options.event.instanceId}-c${String(childCounter)}`;
+    childCounter += 1;
+    return id;
+  };
+  const fanOutDeps = {
+    env: options.env,
+    instanceId: options.event.instanceId,
+    nextChildId,
+    parentBinding: workflowBindingName(options.exportName),
+    resolveBinding,
+    step: options.step
+  };
+  return {
+    env: options.env,
+    event: options.event,
+    log,
+    parallel: createParallel(fanOutDeps),
+    params: options.event.payload,
+    run,
+    runStep: createRunStep({ env: options.env, log, nonRetryableErrorClass: options.nonRetryableErrorClass, run, step: options.step }),
+    spawn: createSpawn(fanOutDeps),
+    step: options.step
+  };
+};
+
+export { createWorkflowRunContext };

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

@@ -264,9 +264,55 @@ 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 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;
+}
+/** 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 +321,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 +391,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, WorkflowSpawnFunction as B, WorkflowSpawnOptions as C, WorkflowStatusResult as D, WorkflowStepConfigLike as E, FunctionReference as F, WorkflowStepContextLike as G, WorkflowStepRollbackOptionsLike as H, 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, 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-Fdeu2P2C.d.ts}

@@ -264,9 +264,55 @@ 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 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;
+}
+/** 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 +321,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 +391,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, WorkflowSpawnFunction as B, WorkflowSpawnOptions as C, WorkflowStatusResult as D, WorkflowStepConfigLike as E, FunctionReference as F, WorkflowStepContextLike as G, WorkflowStepRollbackOptionsLike as H, 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, 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.2",
+  "version": "1.0.0-alpha.4",
   "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,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/values": "1.0.0-alpha.2"
+    "@lunora/values": "1.0.0-alpha.3"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"

package/dist/packem_shared/createWorkflowLogger-DR8P4ZoY.mjs

@@ -1,76 +0,0 @@
-import { createRunStep } from './createRunStep-8jOXxP2o.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 };