@dudousxd/nestjs-durable 0.26.0 → 0.27.0

package/skills/durable-workflows/SKILL.md

@@ -2,10 +2,13 @@
 name: durable-workflows
 description: >
   Author durable workflows with @dudousxd/nestjs-durable — @Workflow({ name, version }) classes with a
-  run(ctx, input) body, local ctx.step(name, fn, opts) checkpoints, typed remote steps via remoteStep
-  + ctx.call handled by @DurableStep('name'), step retries/backoff, FatalError to stop retrying,
-  Promise.all fan-out, saga compensate undo callbacks, and run tags. Covers step vs ctx.call vs
-  sub-process log.sub annotations and constructor dependency injection inside a workflow class.
+  run(ctx, input) body and ONE durable step primitive: ctx.step(handlerRef | name, input, opts?),
+  always dispatched, always engine-scheduled. @Step()-decorated provider methods carry the routing
+  identity (derived Class.method name, or an explicit override); a method reference dispatches a
+  same-process/typed step, a string name dispatches a cross-runtime one (e.g. a Python worker). Covers
+  retries/backoff and FatalError, Promise.all fan-out, sub-process log.sub/subProcess annotations
+  inside a @Step handler, ctx.child for cross-runtime sub-workflows, and constructor dependency
+  injection inside a workflow class.
 license: MIT
 metadata:
   type: core
@@ -17,116 +20,160 @@ metadata:
 # Authoring durable workflows
 
 A workflow is a provider decorated with `@Workflow`; its `run(ctx, input)` method is the
-deterministic body the engine executes and replays. Work happens in **steps** — local
-(`ctx.step`) or remote (`ctx.call`) — each a durable checkpoint.
+deterministic body the engine executes and replays. Work happens in **steps** — always dispatched,
+always durably checkpointed. There is no local/remote placement choice: `ctx.step` is the ONE step
+primitive, and the worker that ends up serving it (this process, another pool, another language) is
+an infrastructure decision, not something the workflow body encodes.
 
 ## Setup
 
 ```ts title="checkout.workflow.ts"
-import { Workflow, DurableStep } from '@dudousxd/nestjs-durable';
-import { remoteStep, FatalError } from '@dudousxd/nestjs-durable-core';
+import { Workflow } from '@dudousxd/nestjs-durable';
 import type { WorkflowCtx } from '@dudousxd/nestjs-durable-core';
-import { Injectable } from '@nestjs/common';
-import { z } from 'zod';
-
-// 1. A typed remote step: the `name` is the contract a handler registers under.
-export const chargeCard = remoteStep({
-  name: 'payments.charge-card',
-  input: z.object({ orderId: z.string(), amountCents: z.number().int() }),
-  output: z.object({ chargeId: z.string() }),
-  retries: 3,
-});
+import { PaymentsWorker } from './payments.worker';
 
-// 2. The workflow — plain linear code; ctx primitives are the only durable surface.
+// 1. The workflow — plain linear code; ctx primitives are the only durable surface.
 @Workflow({ name: 'checkout', version: '1' })
 export class CheckoutWorkflow {
-  constructor(private readonly inventory: InventoryService) {} // normal DI
+  constructor(private readonly payments: PaymentsWorker) {} // normal DI
 
   async run(ctx: WorkflowCtx, order: { id: string; total: number }) {
-    // Local step: runs in-process, checkpointed, retried up to `retries`.
-    await ctx.step('reserveStock', () => this.inventory.reserve(order.id), { retries: 3 });
-    // Remote step: dispatched over the transport, may run in another process/language.
-    const charge = await ctx.call(chargeCard, { orderId: order.id, amountCents: order.total });
+    // Dispatch by METHOD REFERENCE: the routing name comes off the @Step-stamped method, typed by
+    // its own signature — refactor-safe, autocompleted.
+    await ctx.step(this.payments.reserveStock, order);
+
+    const charge = await ctx.step(this.payments.charge, {
+      orderId: order.id,
+      amountCents: order.total,
+    });
+
     return { chargeId: charge.chargeId };
   }
 }
+```
 
-// 3. A provider method handles the remote step in-process (with an in-process transport).
+```ts title="payments.worker.ts"
+import { Step } from '@dudousxd/nestjs-durable';
+import { Injectable } from '@nestjs/common';
+
+// 2. The step handlers this workflow dispatches to — each method is one durable checkpoint. All of
+// them happen to run in THIS process here (via the event-emitter transport), but nothing about the
+// workflow code above would change if `charge` moved to a separate Python/Node worker over BullMQ —
+// ctx.step dispatches by name either way.
 @Injectable()
 export class PaymentsWorker {
-  @DurableStep('payments.charge-card')
-  async charge(input: { orderId: string; amountCents: number }) {
+  @Step()                                          // name = "PaymentsWorker.reserveStock" (derived)
+  async reserveStock(_order: { id: string; total: number }): Promise<{ reserved: boolean }> {
+    // reserve inventory for order.id
+    return { reserved: true };
+  }
+
+  @Step('payments.charge-card')                    // explicit name override
+  async charge(input: { orderId: string; amountCents: number }): Promise<{ chargeId: string }> {
+    // await stripe.charge(...)
     return { chargeId: `ch_${input.orderId}` };
   }
 }
 ```
 
-Register all three as providers (see the durable-setup skill).
+Register all providers (see the durable-setup skill).
 
 ## Core patterns
 
-### Local step vs remote step
+### Two call forms — reference and string
 
-- `ctx.step(name, fn, opts?)` runs `fn` **here** and checkpoints its return value. Use for local IO
-  (DB writes, calling a service the app owns).
-- `ctx.call(remoteStep, input, opts?)` dispatches over the transport to a handler registered under
-  the same `name` (a `@DurableStep` method, another process, or a Python worker). Inputs/outputs are
-  validated against the `remoteStep` zod schemas at the boundary.
+```ts
+// JS handler in this codebase → pass the method reference. Name + input/output types come from the
+// @Step-decorated method — no separate def to declare or keep in sync.
+const r = await ctx.step(this.extraction.runExtractionPage, { page, key });
+
+// Cross-runtime handler (e.g. a Python @step) → there's no JS reference to import, so name it by
+// string. Both forms dispatch identically over the wire.
+const out = await ctx.step<ProcResult>('processing:proc', input);
+```
+
+`@Step()` (bare) derives the routing name from the method as `` `${ClassName}.${method}` ``;
+`@Step('custom:name')` overrides it explicitly — needed for a cross-runtime contract where the other
+side has no `@Step` of its own. `@Step({ name?, input?, output?, retries?, backoff?, backoffMs?,
+backoffMaxMs?, jitter?, timeoutMs? })` additionally opts into RUNTIME zod validation (`input`
+validates before the method runs, `output` validates its return value) and a def-level durable-retry
+policy — a bare `@Step()` skips both and dispatches with no retry/timeout.
 
-Both are first-class checkpoints: on crash/replay a `completed` one returns its saved result instead
-of re-executing.
+Every dispatched step is a first-class checkpoint: on crash/replay a `completed` one returns its
+saved result instead of re-executing.
 
 ### Retries, backoff, and FatalError
 
-Per-step retry config lives in `opts`; throw `FatalError` to stop retrying a business failure a retry
-can't fix.
+Retry policy can live on the `@Step` decorator (the default for every call to that handler) or be
+overridden per call site via `ctx.step`'s `opts` — a call-site value wins field-by-field.
 
 ```ts
-await ctx.step('charge', async () => {
+@Step({ retries: 5, backoff: 'exp', backoffMs: 200, jitter: true })
+async charge(order: Order) {
   const res = await this.stripe.charge(order);
-  if (res.declined) throw new FatalError('card declined', 'declined'); // fails the run now
+  if (res.declined) throw new FatalError('card declined', 'declined'); // fails the run now, no retry
   return res;
-}, { retries: 5, backoff: 'exp', backoffMs: 200, jitter: true });
+}
+```
+
+```ts
+// Per-call override — wins over the @Step-declared policy for THIS dispatch only.
+await ctx.step(this.payments.charge, order, { retries: 1 });
 ```
 
-`StepOptions` fields: `retries`, `backoff` (`'fixed'` | `'exp'`), `backoffMs`, `backoffMaxMs`,
-`jitter`, `timeoutMs` (remote liveness), `compensate` (saga).
+`StepDispatchOpts` (the `ctx.step` third argument): `queue`, `priority`, `fairnessKey`, `transport`,
+`retries`, `backoff` (`'fixed'` | `'exp'`), `backoffMs`, `backoffMaxMs`, `jitter`, `timeoutMs` (a
+liveness window — no result/heartbeat within it presumes the worker dead and re-dispatches).
 
-### Fan-out and sagas
+### Fan-out
 
-Run steps concurrently with `Promise.all` — each step's position is taken in the synchronous prefix,
-so replay stays deterministic:
+Dispatch steps concurrently with `Promise.all` — each `ctx.step` call takes its position in the
+synchronous prefix before suspending, so replay stays deterministic:
 
 ```ts
 const [a, b] = await Promise.all([
-  ctx.step('a', () => doA()),
-  ctx.step('b', () => doB()),
+  ctx.step(this.svc.stepA, input),
+  ctx.step(this.svc.stepB, input),
 ]);
 ```
 
-Register a saga `compensate` undo on a step; if the run later fails, compensations run in reverse:
+### Sub-process events inside a step
+
+For pure visibility *inside* one step's execution, the `@Step` handler's optional second argument
+(`log: StepLogger`) records annotations — they ride back with the step's result and are NOT separate
+checkpoints, so they re-run if the step retries:
 
 ```ts
-await ctx.step('reserve', () => this.inventory.reserve(id), {
-  compensate: () => this.inventory.release(id), // runs on later run failure, newest-first
-});
+import type { StepLogger } from '@dudousxd/nestjs-durable-core';
+
+@Step()
+async processBatch(batch: Item[], log: StepLogger) {
+  for (const item of batch) {
+    await handle(item);
+    log.sub(item.id, 'ok'); // shown under the step; not a checkpoint of its own
+  }
+}
 ```
 
-### Steps vs sub-process events
+### Cross-runtime sub-workflows: ctx.child
 
-A `ctx.step` / `ctx.call` is a durable, independently-replayed checkpoint. For pure visibility
-*inside* one step, emit sub-process events on the step logger — they are annotations, not
-checkpoints, and re-run if the step retries:
+`ctx.step` dispatches ONE step handler; to hand off a whole **workflow** — including to another
+language's runtime (e.g. a Python worker) — use `ctx.child` instead. Pass the child's class for a
+typed, same-runtime child, or a string name for a cross-runtime one:
 
 ```ts
-await ctx.step('process-batch', async (log) => {
-  for (const item of batch) {
-    await handle(item);
-    log.sub(item.id, 'ok'); // shown under the step; NOT a separate checkpoint
-  }
-});
+// Same-runtime, typed:
+const result = await ctx.child(ShippingWorkflow, { orderId: order.id });
+
+// Cross-runtime (e.g. a Python-registered workflow) — no class to import, so by name:
+const rows = await ctx.child<{ rows: number }>('processing', { baseId });
 ```
 
+`ctx.child` starts the child once (checkpointed) and suspends — zero compute — until it reaches a
+terminal state, then resumes with its output (or throws if the child failed). Use `ctx.all(Class,
+inputs)` / `ctx.all(name, inputs)` to fan out N children of the same workflow and wait for all of
+them.
+
 ## Common mistakes
 
 ### 1. Doing durable work directly in the body instead of in a step
@@ -138,45 +185,53 @@ async run(ctx, order) {
   return { ok: true };
 }
 
-// ✓ Correct — wrap side effects in a step so they checkpoint and run exactly once logically
+// ✓ Correct — move it into a @Step handler so it checkpoints and runs exactly once logically
 async run(ctx, order) {
-  await ctx.step('persist', () => this.db.insert(order));
+  await ctx.step(this.orders.persist, order);
   return { ok: true };
 }
 ```
 
-Only `ctx.step`/`ctx.call`/`ctx.transaction` results are checkpointed; raw work in the body re-runs
-on replay. Source: website/content/docs/concepts/durability.mdx.
+Only `ctx.step`/`ctx.transaction` results are checkpointed; raw work in the body re-runs on replay.
+Source: website/content/docs/concepts/durability.mdx.
 
-### 2. Mismatching the remoteStep `name` and the @DurableStep handler
+### 2. A method reference with no @Step stamp
 
 ```ts
-// ✗ Wrong — handler name ≠ the remoteStep name, so ctx.call(chargeCard) finds no handler
-export const chargeCard = remoteStep({ name: 'payments.charge-card', /* ... */ });
-@DurableStep('payments.charge')                 // typo / mismatch
-async charge(input) { /* ... */ }
-
-// ✓ Correct — the string is the contract; it must match byte-for-byte
-@DurableStep('payments.charge-card')
-async charge(input) { /* ... */ }
+// ✗ Wrong — plain method, no @Step decorator → ctx.step has no routing name to read
+class PaymentsWorker {
+  async charge(input: ChargeInput) { /* ... */ }
+}
+await ctx.step(this.payments.charge, input); // throws — "handler is not a @Step reference"
+
+// ✓ Correct — decorate the handler so its name is stamped for ctx.step to read
+class PaymentsWorker {
+  @Step()
+  async charge(input: ChargeInput) { /* ... */ }
+}
 ```
 
-The `name` string is the routing contract between `remoteStep`/`ctx.call` and the handler.
-Source: packages/core/src/remote-step-factory.ts, packages/nestjs/src/decorators.ts (`DurableStep`).
+`ctx.step` reads the routing name off a shared symbol `@Step` stamps on the method — the reference
+itself is never invoked directly (the serving worker re-resolves the real handler from DI), so an
+undecorated method has nothing for `ctx.step` to route on. Source: packages/nestjs/src/decorators.ts
+(`Step`), packages/core/src/workflow-ctx.ts (`step`).
 
 ### 3. Throwing a plain Error when you meant to stop retrying
 
 ```ts
 // ✗ Wrong — a plain Error is retried up to `retries`, wasting attempts on an unfixable failure
-await ctx.step('charge', async () => {
-  if (card.declined) throw new Error('declined'); // retried 5x
-}, { retries: 5 });
+@Step({ retries: 5 })
+async charge(order: Order) {
+  if (order.card.declined) throw new Error('declined'); // retried 5x
+}
 
 // ✓ Correct — FatalError fails the run immediately, no further attempts
 import { FatalError } from '@dudousxd/nestjs-durable-core';
-await ctx.step('charge', async () => {
-  if (card.declined) throw new FatalError('declined', 'card_declined');
-}, { retries: 5 });
+
+@Step({ retries: 5 })
+async charge(order: Order) {
+  if (order.card.declined) throw new FatalError('declined', 'card_declined');
+}
 ```
 
 Any thrown error is retried to the step's limit; only `FatalError` short-circuits retries.