@lunora/workflow 1.0.0-alpha.9 → 1.0.0-alpha.91

package/README.md

@@ -85,10 +85,33 @@ The handler context bundles:
 - `ctx.step` — the native Cloudflare durable-step API (`do` / `sleep` / `sleepUntil` / `waitForEvent`).
 - `ctx.run(ref, args, opts?)` — call a Lunora query / mutation / action; wrap in `ctx.step.do(...)` for durability.
 - `ctx.runStep(step, args, opts?)` — run a reusable, schema-validated `defineStep` as a durable step (see below).
+- `ctx.waitForEvent(event, opts?)` — hibernate until a declared `defineWorkflowEvent` arrives; resolves with its validated payload (see below).
 - `ctx.event` / `ctx.params` — the triggering event and its payload.
 - `ctx.env` — the Worker bindings.
 - `ctx.log` — a workflow-prefixed logger surfaced in `wrangler tail` / Studio.
 
+### Declared events (`defineWorkflowEvent`)
+
+`step.waitForEvent(name, { type })` and `instance.sendEvent({ type })` match on a bare string, and the payload crosses as `unknown` — so a typo hibernates the instance until its timeout with no error anywhere, and a changed payload shape resumes the workflow on garbage. Declare the event once and both ends import the same value:
+
+```ts
+// lunora/events.ts
+import { defineWorkflowEvent } from "@lunora/workflow";
+import { v } from "@lunora/values";
+
+export const orderApproved = defineWorkflowEvent("order-approved", v.object({ approvedBy: v.string() }));
+```
+
+```ts
+// inside the workflow body — typed and parsed
+const { approvedBy } = await ctx.waitForEvent(orderApproved, { name: "await approval", timeout: "7 days" });
+
+// from a mutation/action — validated before the send
+await ctx.workflows.get("orderPipeline").sendEvent(instanceId, orderApproved, { approvedBy });
+```
+
+Pass a stable `{ name }` on any wait that can outlive a deploy: the step is otherwise labelled `event:<type>`, so renaming the event type also renames the durable step and an instance that already recorded the wait replays into a fresh one nothing will satisfy.
+
 ### Reusable steps (`defineStep`)
 
 A step authored inline with `ctx.step.do("name", () => …)` is fine for one-offs, but `defineStep` lets you define a step **once** — schema-validated and reusable across workflows. Args are validated (with `@lunora/values`) **before** the body runs, and the return value is validated **after** (when you declare `returns`), so a bad payload fails fast instead of corrupting later steps. Scaffold one with `vis generate lunora-step --name=chargeOrder` (appends to `lunora/steps.ts`), or write it by hand:
@@ -169,7 +192,9 @@ export const checkout = mutation.input({ orderId: v.string() }).mutation(async (
 });
 ```
 
-A handle exposes `create({ id?, params?, retention? })`, `createBatch([...])`, and `get(id)`. An instance handle exposes its lifecycle: `status()`, `pause()`, `resume()`, `terminate()`, and `sendEvent({ type, payload })` (to satisfy a `waitForEvent`).
+A handle exposes `create({ id?, params?, retention? })`, `createBatch({ instances })` or `createBatch({ count, params?, retention? })` (returns `{ created, errors }`, one error per instance it did not create), `deleteBatch([...ids])` (up to 100), `get(id)`, and `sendEvent(instanceId, event, payload)` — the typed delivery of a declared event (see above). `create`/`get` return the native Cloudflare instance, which exposes its own lifecycle: `status()`, `pause()`, `resume()`, `restart()`, `terminate()`, `delete()`, `subscribe({ cursor?, filter? })` (streams the instance's event history, then new events), and the untyped `sendEvent({ type, payload })`.
+
+`defineWorkflow` also takes deploy settings, which codegen writes into the workflow's `wrangler.jsonc` entry: `schedules` (cron expressions that each start an instance), `limits: { steps }`, and `defaultRetention: { successRetention, errorRetention }`. Scheduled workflows are refused on the Node and celld targets.
 
 ### Runtime requirements
 
@@ -181,7 +206,7 @@ A handle exposes `create({ id?, params?, retention? })`, `createBatch([...])`, a
 ### Manual wiring (without codegen)
 
 1. Author `lunora/workflows.ts` as above.
-2. Re-export the generated class from your worker entry — wrangler requires every `workflows[].class_name` to be exported:
+2. Re-export the generated class from your worker entry — wrangler requires every workflow export to be a class the worker exports:
 
     ```ts
     import LunoraWorkflow from "@lunora/workflow/do";
@@ -194,17 +219,17 @@ A handle exposes `create({ id?, params?, retention? })`, `createBatch([...])`, a
     }
     ```
 
-3. Add the binding to `wrangler.jsonc`:
+3. Declare it in `wrangler.jsonc`'s `exports` (Wrangler 4.142.0+):
 
     ```jsonc
     {
-        "workflows": [{ "name": "order-pipeline", "binding": "WORKFLOW_ORDER_PIPELINE", "class_name": "OrderPipelineWorkflow" }],
+        "exports": { "OrderPipelineWorkflow": { "type": "workflow", "name": "order-pipeline" } },
     }
     ```
 
-4. Build `ctx.workflows` from the binding: `createWorkflows({ bindings: { orderPipeline: env.WORKFLOW_ORDER_PIPELINE } })`.
+4. Build `ctx.workflows` from the invoking context's exports: `createWorkflows({ bindings: { orderPipeline: ctx.exports.OrderPipelineWorkflow } })`.
 
-The `workflowClassName` / `workflowBindingName` / `workflowDefaultName` helpers produce exactly these names so codegen and config never disagree.
+The `workflowClassName` / `workflowDefaultName` helpers produce exactly these names so codegen and config never disagree.
 
 ### Observing instances (REST client)
 
@@ -223,7 +248,7 @@ const detail = await client.getInstance({ workflowName: "order-pipeline", instan
 await client.setInstanceStatus({ workflowName: "order-pipeline", instanceId: detail.id, action: "terminate" });
 ```
 
-> This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/addons/workflows)**.
+> This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/packages/workflow)**.
 
 ## Related
 

package/dist/do/index.d.mts

@@ -1,22 +1,22 @@
 import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from 'cloudflare:workers';
-import { W as WorkflowDefinition } from "../packem_shared/types.d-C9W6rEWv.mjs";
+import { W as WorkflowDefinition } from "../packem_shared/types.d-zivJ8nEf.mjs";
 import '@lunora/values';
 /**
-* Base class for the generated `WorkflowEntrypoint` classes. Applies a
-* `defineWorkflow` definition onto Cloudflare's `WorkflowEntrypoint`: `run`
-* assembles the Lunora context (native `step`/`event` + the `ctx.run` function
-* dispatcher + a logger) and invokes the user's handler.
-*
-* Generated subclasses stay one line of behavior:
-*
-* ```ts
-* export class OrderPipelineWorkflow extends LunoraWorkflow {
-*     constructor(ctx: ExecutionContext, env: Record<string, unknown>) {
-*         super(ctx, env, orderPipeline, "orderPipeline");
-*     }
-* }
-* ```
-*/
+ * Base class for the generated `WorkflowEntrypoint` classes. Applies a
+ * `defineWorkflow` definition onto Cloudflare's `WorkflowEntrypoint`: `run`
+ * assembles the Lunora context (native `step`/`event` + the `ctx.run` function
+ * dispatcher + a logger) and invokes the user's handler.
+ *
+ * Generated subclasses stay one line of behavior:
+ *
+ * ```ts
+ * export class OrderPipelineWorkflow extends LunoraWorkflow {
+ *     constructor(ctx: ExecutionContext, env: Record<string, unknown>) {
+ *         super(ctx, env, orderPipeline, "orderPipeline");
+ *     }
+ * }
+ * ```
+ */
 declare class LunoraWorkflow<Params = Record<string, unknown>, Output = unknown> extends WorkflowEntrypoint<Record<string, unknown>, Params> {
   #private;
   constructor(context: ConstructorParameters<typeof WorkflowEntrypoint>[0], env: Record<string, unknown>, definition: WorkflowDefinition<Params, Output>, exportName?: string);

package/dist/do/index.d.ts

@@ -1,22 +1,22 @@
 import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from 'cloudflare:workers';
-import { W as WorkflowDefinition } from "../packem_shared/types.d-C9W6rEWv.js";
+import { W as WorkflowDefinition } from "../packem_shared/types.d-zivJ8nEf.js";
 import '@lunora/values';
 /**
-* Base class for the generated `WorkflowEntrypoint` classes. Applies a
-* `defineWorkflow` definition onto Cloudflare's `WorkflowEntrypoint`: `run`
-* assembles the Lunora context (native `step`/`event` + the `ctx.run` function
-* dispatcher + a logger) and invokes the user's handler.
-*
-* Generated subclasses stay one line of behavior:
-*
-* ```ts
-* export class OrderPipelineWorkflow extends LunoraWorkflow {
-*     constructor(ctx: ExecutionContext, env: Record<string, unknown>) {
-*         super(ctx, env, orderPipeline, "orderPipeline");
-*     }
-* }
-* ```
-*/
+ * Base class for the generated `WorkflowEntrypoint` classes. Applies a
+ * `defineWorkflow` definition onto Cloudflare's `WorkflowEntrypoint`: `run`
+ * assembles the Lunora context (native `step`/`event` + the `ctx.run` function
+ * dispatcher + a logger) and invokes the user's handler.
+ *
+ * Generated subclasses stay one line of behavior:
+ *
+ * ```ts
+ * export class OrderPipelineWorkflow extends LunoraWorkflow {
+ *     constructor(ctx: ExecutionContext, env: Record<string, unknown>) {
+ *         super(ctx, env, orderPipeline, "orderPipeline");
+ *     }
+ * }
+ * ```
+ */
 declare class LunoraWorkflow<Params = Record<string, unknown>, Output = unknown> extends WorkflowEntrypoint<Record<string, unknown>, Params> {
   #private;
   constructor(context: ConstructorParameters<typeof WorkflowEntrypoint>[0], env: Record<string, unknown>, definition: WorkflowDefinition<Params, Output>, exportName?: string);

package/dist/do/index.mjs

@@ -1,44 +1 @@
-import { WorkflowEntrypoint } from 'cloudflare:workers';
-import { NonRetryableError } from 'cloudflare:workflows';
-import { convertNonRetryableError } from '../packem_shared/NonRetryableError-Dn2dTyBS.mjs';
-import { extractBranchMarker, stripBranchMarker, signalBranchParentSafe, errorOutcome, okOutcome } from '../packem_shared/MAX_BRANCHES-EO5xYS_3.mjs';
-import { createWorkflowRunContext } from '../packem_shared/createWorkflowRunContext-BDSHE8iO.mjs';
-
-class LunoraWorkflow extends WorkflowEntrypoint {
-  /** The `lunora/workflows.ts` export name, for log correlation. */
-  #lunoraName;
-  /** The `defineWorkflow` result this entrypoint runs. */
-  #definition;
-  constructor(context, env, definition, exportName) {
-    super(context, env);
-    this.#definition = definition;
-    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: handlerEvent,
-      exportName: this.#lunoraName,
-      nonRetryableErrorClass: NonRetryableError,
-      step: nativeStep
-    });
-    let output;
-    try {
-      output = await this.#definition.handler(context);
-    } catch (error) {
-      if (marker) {
-        await signalBranchParentSafe({ env: this.env, log: context.log, step: nativeStep }, marker, errorOutcome(error));
-      }
-      return convertNonRetryableError(error, NonRetryableError);
-    }
-    if (marker) {
-      await signalBranchParentSafe({ env: this.env, log: context.log, step: nativeStep }, marker, okOutcome(output));
-    }
-    return output;
-  }
-}
-
-export { LunoraWorkflow as default };
+import{WorkflowEntrypoint as l}from"cloudflare:workers";import{NonRetryableError as i}from"cloudflare:workflows";import{convertNonRetryableError as h}from"../packem_shared/NonRetryableError-BPu01mU8.mjs";import{extractBranchMarker as m,stripBranchMarker as x,signalBranchParentSafe as p,errorOutcome as f,okOutcome as u}from"../packem_shared/MAX_BRANCHES-Bcw3dss9.mjs";import{createWorkflowRunContext as y}from"../packem_shared/createWorkflowRunContext-CRTTub21.mjs";class N extends l{#r;#t;constructor(t,e,o,r){super(t,e),this.#t=o,this.#r=r??"workflow"}async run(t,e){const o=e,r=m(t.payload),c=r?{...t,payload:x(t.payload)}:t,a=y({env:this.env,exports:this.ctx.exports,event:c,exportName:this.#r,nonRetryableErrorClass:i,step:o});let n;try{n=await this.#t.handler(a)}catch(s){return r&&await p({env:this.env,exports:this.ctx.exports,log:a.log,step:o},r,f(s)),h(s,i)}return r&&await p({env:this.env,exports:this.ctx.exports,log:a.log,step:o},r,u(n)),n}}export{N as default};