@lunora/workflow 0.0.0 → 1.0.0-alpha.1

package/dist/packem_shared/types.d-CQO_koGe.d.ts

@@ -0,0 +1,344 @@
+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`.
+*/
+interface FunctionReference {
+  readonly __lunoraRef: string;
+  /** Marker phantom type — discriminates queries / mutations / actions. */
+  readonly _kind?: "query" | "mutation" | "action";
+}
+type ArgsOf<F extends FunctionReference> = F extends {
+  _args?: infer A;
+} ? A : Record<string, unknown>;
+/** A workflow instance's lifecycle status. Mirrors `WorkflowInstanceStatus`. */
+type WorkflowInstanceStatus = "complete" | "errored" | "paused" | "queued" | "running" | "terminated" | "unknown" | "waiting" | "waitingForPause";
+/** Result of `WorkflowInstance.status()`. Mirrors Cloudflare's `InstanceStatus`. */
+interface WorkflowStatusResult {
+  error?: {
+    message: string;
+    name: string;
+  };
+  output?: unknown;
+  status: WorkflowInstanceStatus;
+}
+/** Options accepted by `Workflow.create`. Mirrors `WorkflowInstanceCreateOptions`. */
+interface WorkflowCreateOptions<Params = Record<string, unknown>> {
+  /** Unique-within-the-workflow instance id. Generated by Cloudflare when omitted. */
+  id?: string;
+  /** The event payload the instance is triggered with — surfaced as `event.payload`. */
+  params?: Params;
+  /** Instance retention policy (defaults to the account maximum). */
+  retention?: {
+    errorRetention?: string;
+    successRetention?: string;
+  };
+}
+/** A live handle to a single workflow instance. Mirrors `WorkflowInstance`. */
+interface WorkflowInstanceLike {
+  readonly id: string;
+  pause: () => Promise<void>;
+  restart: () => Promise<void>;
+  resume: () => Promise<void>;
+  sendEvent: (event: {
+    payload: unknown;
+    type: string;
+  }) => Promise<void>;
+  status: () => Promise<WorkflowStatusResult>;
+  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.
+*/
+interface WorkflowBindingLike<Params = Record<string, unknown>> {
+  create: (options?: WorkflowCreateOptions<Params>) => Promise<WorkflowInstanceLike>;
+  createBatch: (batch: ReadonlyArray<WorkflowCreateOptions<Params>>) => Promise<WorkflowInstanceLike[]>;
+  get: (id: string) => Promise<WorkflowInstanceLike>;
+}
+/** The `event` argument a workflow `run` receives. Mirrors `WorkflowEvent&lt;T>`. */
+interface WorkflowEventLike<Params = Record<string, unknown>> {
+  readonly instanceId: string;
+  readonly payload: Readonly<Params>;
+  readonly timestamp: Date;
+  readonly workflowName: string;
+}
+/** Per-step durability config. Mirrors the `WorkflowStepConfig.retries` shape. */
+interface WorkflowStepConfigLike {
+  retries?: {
+    backoff?: "constant" | "exponential" | "linear";
+    delay?: number | string;
+    limit: number;
+  };
+  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.
+*/
+interface WorkflowStepContextLike {
+  /** 1-based attempt counter — `> 1` means this is a retry. */
+  attempt: number;
+  /** The resolved per-step config for this invocation. */
+  config: WorkflowStepConfigLike;
+  /** The durable step's identity. */
+  step: {
+    count: number;
+    name: string;
+  };
+}
+/** The context a rollback handler receives. Mirrors `WorkflowRollbackContext` (`{ ctx, error, output, stepName }`). */
+interface WorkflowRollbackContextLike<T = unknown> {
+  /** The per-attempt step context (`attempt` / `config` / `step`) for the rolled-back step. */
+  ctx: WorkflowStepContextLike;
+  /** The error that triggered the rollback. */
+  error: Error;
+  /** The step's output if it completed before a later step failed, else `undefined`. */
+  output: T | undefined;
+  /** The durable step's name. */
+  stepName: string;
+}
+/** A native step rollback handler. Mirrors `WorkflowRollbackHandler`. */
+type WorkflowRollbackHandlerLike<T = unknown> = (context: WorkflowRollbackContextLike<T>) => Promise<void>;
+/** Native rollback options accepted by `step.do`. Mirrors the Cloudflare rollback-options shape. */
+interface WorkflowStepRollbackOptionsLike<T = unknown> {
+  rollback?: WorkflowRollbackHandlerLike<T>;
+  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.
+*/
+interface WorkflowStepLike {
+  do: {
+    <T>(name: string, callback: (context: WorkflowStepContextLike) => Promise<T>, rollback?: WorkflowStepRollbackOptionsLike<T>): Promise<T>;
+    <T>(name: string, config: WorkflowStepConfigLike, callback: (context: WorkflowStepContextLike) => Promise<T>, rollback?: WorkflowStepRollbackOptionsLike<T>): Promise<T>;
+  };
+  sleep: (name: string, duration: number | string) => Promise<void>;
+  sleepUntil: (name: string, timestamp: Date | number) => Promise<void>;
+  waitForEvent: <T = unknown>(name: string, options: {
+    timeout?: number | string;
+    type: string;
+  }) => Promise<{
+    payload: Readonly<T>;
+    type: string;
+  }>;
+}
+/** Minimal structured logger handed to the workflow body. */
+interface WorkflowLogger {
+  debug: (message: string, ...rest: unknown[]) => void;
+  error: (message: string, ...rest: unknown[]) => void;
+  info: (message: string, ...rest: unknown[]) => void;
+  warn: (message: string, ...rest: unknown[]) => void;
+}
+/** Per-call options for {@link WorkflowRunFunction}. */
+interface RunFunctionOptions {
+  /** Routing hint forwarded to the Worker so the call lands on the right shard. */
+  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 }));
+* ```
+*/
+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.
+*/
+interface StepRunContext {
+  /** 1-based retry counter — `> 1` means Cloudflare is retrying the step. */
+  readonly attempt: number;
+  /** The resolved durability config for this invocation. */
+  readonly config: WorkflowStepConfigLike;
+  /** The Worker environment bindings. */
+  readonly env: Record<string, unknown>;
+  /** Structured logger surfaced in `wrangler tail` / Studio logs. */
+  readonly log: WorkflowLogger;
+  /** Invoke a Lunora query / mutation / action. */
+  readonly run: WorkflowRunFunction;
+  /** The durable step's identity (name + invocation count). */
+  readonly step: {
+    count: number;
+    name: string;
+  };
+}
+/** The work a step performs. Receives the {@link StepRunContext} and the validated args. */
+type StepHandler<A extends StepArgsValidator, Result> = (context: StepRunContext, args: InferStepArgs<A>) => Promise<Result> | Result;
+/** The context a step rollback handler receives — the Lunora-flavored mirror of `WorkflowRollbackContext`. */
+interface StepRollbackContext<A extends StepArgsValidator, Result> {
+  /** The validated args the step ran with. */
+  readonly args: InferStepArgs<A>;
+  /** The Worker environment bindings. */
+  readonly env: Record<string, unknown>;
+  /** The error that triggered the rollback. */
+  readonly error: Error;
+  /** Structured logger. */
+  readonly log: WorkflowLogger;
+  /** The step's output if it completed before a later step failed, else `undefined`. */
+  readonly output: Result | undefined;
+  /** Invoke a Lunora function — e.g. to undo a write the step made. */
+  readonly run: WorkflowRunFunction;
+}
+/** A step compensation handler — runs when a later step fails after this one completed. */
+type StepRollbackHandler<A extends StepArgsValidator, Result> = (context: StepRollbackContext<A, Result>) => Promise<void> | void;
+/** Author-supplied config for {@link StepDefinition}, passed to `defineStep`. */
+interface StepConfig<A extends StepArgsValidator, Result> {
+  /** Validators for the step's args — the same map shape a Lunora function uses. */
+  args: A;
+  /** Optional durability config (retries / timeout) applied to the step. */
+  config?: WorkflowStepConfigLike;
+  /** The work the step performs. */
+  handler: StepHandler<A, Result>;
+  /** Optional validator for the return value — validated before the result leaves the step. */
+  returns?: Validator<Result>;
+  /** Optional compensation run when a later step fails after this one completed. */
+  rollback?: StepRollbackHandler<A, Result>;
+  /** Optional durability config for the rollback step itself. */
+  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.
+*/
+interface StepDefinition<A extends StepArgsValidator = StepArgsValidator, Result = unknown> {
+  /** Validators for the step's args. */
+  readonly args: A;
+  /** Optional per-step durability config. */
+  readonly config?: WorkflowStepConfigLike;
+  /** The step body. */
+  readonly handler: StepHandler<A, Result>;
+  /** Runtime brand check (see `isStepDefinition`). */
+  readonly isLunoraStep: true;
+  /** The durable step's name — also the `step.do(...)` label. */
+  readonly name: string;
+  /** Optional result validator. */
+  readonly returns?: Validator<Result>;
+  /** Optional compensation handler. */
+  readonly rollback?: StepRollbackHandler<A, Result>;
+  /** Optional rollback durability config. */
+  readonly rollbackConfig?: WorkflowStepConfigLike;
+}
+/** Per-call options for {@link WorkflowRunStepFunction}. */
+interface RunStepOptions {
+  /** Override the step's declared durability config for this call. */
+  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 });
+* ```
+*/
+type WorkflowRunStepFunction = <A extends StepArgsValidator, Result>(step: StepDefinition<A, Result>, args: InferStepArgs<A>, options?: RunStepOptions) => Promise<Result>;
+/**
+* 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.
+*/
+interface WorkflowRunContext<Params = Record<string, unknown>> {
+  /** The Worker environment bindings. */
+  readonly env: Record<string, unknown>;
+  /** The triggering event (id, payload, timestamp, workflow name). */
+  readonly event: WorkflowEventLike<Params>;
+  /** Structured logger surfaced in `wrangler tail` / Studio logs. */
+  readonly log: WorkflowLogger;
+  /** 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;
+  /** The native Cloudflare Workflows durable-step API. */
+  readonly step: WorkflowStepLike;
+}
+/** The workflow body. Receives a {@link WorkflowRunContext}, returns the output. */
+type WorkflowHandler<Params = Record<string, unknown>, Output = unknown> = (context: WorkflowRunContext<Params>) => Output | Promise<Output>;
+/** Author-supplied config for `defineWorkflow`. */
+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`).
+  */
+  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.
+*/
+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;
+  /** Phantom marker for the params type — never present at runtime. */
+  readonly __params?: Params;
+  /** Runtime brand check (see `isWorkflowDefinition`). */
+  readonly isLunoraWorkflow: true;
+}
+/**
+* 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>;
+  /** Start many instances in one batched RPC. */
+  createBatch: (batch: ReadonlyArray<WorkflowCreateOptions<Params>>) => Promise<WorkflowInstanceLike[]>;
+  /** Get a handle to an existing instance by id. */
+  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.
+*/
+interface Workflows {
+  /** Resolve the handle for a declared workflow by export name. */
+  get: <Params = Record<string, unknown>>(name: string) => WorkflowHandle<Params>;
+}
+/** 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.
+  */
+  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 };

package/package.json

@@ -1,29 +1,56 @@
 {
   "name": "@lunora/workflow",
-  "version": "0.0.0",
+  "version": "1.0.0-alpha.1",
   "description": "Durable workflows for Lunora: defineWorkflow over Cloudflare Workflows, generated WorkflowEntrypoint classes, and the ctx.workflows surface",
-  "license": "FSL-1.1-Apache-2.0",
+  "keywords": [
+    "cloudflare",
+    "durable-execution",
+    "lunora",
+    "saga",
+    "workers",
+    "workflows"
+  ],
   "homepage": "https://lunora.sh",
+  "bugs": "https://github.com/anolilab/lunora/issues",
+  "license": "FSL-1.1-Apache-2.0",
+  "author": {
+    "name": "Daniel Bannert",
+    "email": "d.bannert@anolilab.de"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/anolilab/lunora.git",
     "directory": "packages/workflow"
   },
-  "bugs": {
-    "url": "https://github.com/anolilab/lunora/issues"
-  },
-  "keywords": [
-    "lunora",
-    "cloudflare",
-    "workers",
-    "workflows",
-    "durable-execution",
-    "saga"
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md",
+    "__assets__"
   ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./do": {
+      "types": "./dist/do/index.d.ts",
+      "import": "./dist/do/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
+  "dependencies": {
+    "@lunora/values": "1.0.0-alpha.1"
+  },
+  "engines": {
+    "node": "^22.15.0 || >=24.11.0"
+  }
 }