@dudousxd/nestjs-durable 0.47.1 → 0.48.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-durable",
-  "version": "0.47.1",
+  "version": "0.48.1",
   "description": "Durable workflows for NestJS — module, decorators, discovery and boot recovery",
   "license": "MIT",
   "author": "Davide Carvalho",
@@ -67,11 +67,12 @@
     "tsup": "8.3.5",
     "@dudousxd/nestjs-diagnostics": "0.5.0",
     "@tanstack/intent": "0.4.0",
-    "@dudousxd/durable-worker": "0.10.4",
-    "@dudousxd/nestjs-durable-core": "^0.78.0",
-    "@dudousxd/nestjs-durable-dashboard": "0.50.0",
-    "@dudousxd/nestjs-durable-transport-bullmq": "0.22.1",
-    "@dudousxd/nestjs-durable-transport-event-emitter": "^0.5.1"
+    "@dudousxd/durable-worker": "0.11.2",
+    "@dudousxd/nestjs-durable-core": "^0.80.0",
+    "@dudousxd/nestjs-durable-dashboard": "0.51.0",
+    "@dudousxd/nestjs-durable-testing": "^0.19.0",
+    "@dudousxd/nestjs-durable-transport-bullmq": "0.22.3",
+    "@dudousxd/nestjs-durable-transport-event-emitter": "^0.5.2"
   },
   "module": "./dist/index.js",
   "exports": {

package/skills/durable-setup/SKILL.md

@@ -76,6 +76,10 @@ await app.listen(3000);
 
 `start` **enqueues** the run and returns immediately with `{ runId, status: 'pending' }` — a worker
 runs the body, so the HTTP handler never blocks. Pass the workflow **class** for a typed input.
+Pass `opts.startAt` (epoch ms or a `Date`) to delay the start: the run is created `suspended` with
+its `wakeAt` set (the same durable timer `ctx.sleep` parks on, resumed by the timer poller once
+due), and `start` returns `{ runId, status: 'suspended' }` instead. A time that is not in the
+future starts the run at once.
 
 ```ts
 import { WorkflowService } from '@dudousxd/nestjs-durable';
@@ -158,7 +162,7 @@ name automatically; there's no `groups`/`remoteByConvention` flag to opt into.
 ### 1. Expecting `start` to return the workflow's result
 
 ```ts
-// ✗ Wrong — `start` enqueues; `result` is { runId, status: 'pending' }, never the run output
+// ✗ Wrong — `start` enqueues; `result` is { runId, status: 'pending' } (or 'suspended' with startAt), never the run output
 const result = await this.workflows.start(CheckoutWorkflow, order);
 return result.output; // undefined
 
@@ -167,7 +171,8 @@ const { runId } = await this.workflows.start(CheckoutWorkflow, order);
 return this.workflows.waitForRun(runId); // resolves once the run settles
 ```
 
-`start` creates the run as `'pending'` and a worker runs the body asynchronously; only `waitForRun`
+`start` creates the run as `'pending'` (or `'suspended'` when `opts.startAt` is in the future)
+and a worker runs the body asynchronously; only `waitForRun`
 resolves with the settled outcome. Source: packages/nestjs/src/workflow.service.ts.
 
 ### 2. Leaving `autoSchema` on in production

package/skills/durable-workflows/SKILL.md

@@ -146,6 +146,17 @@ outputs in input order (a `GatherError` carries the failed indexes, as for a chi
 const results = await ctx.all(this.lines.processLine, lines, { concurrency: 500 });
 ```
 
+When a failed item is an expected outcome rather than a reason to fail the run, use
+`ctx.allSettled` instead: the same fan, resolving with `{ status: 'fulfilled', value }` or
+`{ status: 'rejected', id, error, code?, details? }` per input, in input order, and never throwing for an item. The rejected `code`/`details` are the `FatalError`'s (absent for a plain `Error`). Throw
+`FatalError` in the step for a failure a retry can't fix (a schema mismatch); it settles as rejected
+without spending the retries:
+
+```ts
+const results = await ctx.allSettled(this.lines.validateLine, lines, { concurrency: 500 });
+const rejected = results.filter((r) => r.status === 'rejected');
+```
+
 Prefer it to `Promise.all` past a handful of steps: every result of a `Promise.all` replays the
 workflow, which makes a fan of N steps cost O(N²) checkpoint reads. Prefer it to a child-workflow
 `ctx.all` when each item is just a step: a child costs a whole run (row, turn, lease, signal).
@@ -213,7 +224,7 @@ 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.
+them, or `ctx.allSettled(...)` to get every outcome back instead of a `GatherError`.
 
 ## Common mistakes
 
@@ -276,4 +287,29 @@ async charge(order: Order) {
 ```
 
 Any thrown error is retried to the step's limit; only `FatalError` short-circuits retries.
+
+When a failure is an expected outcome rather than a reason to fail the run (a line that fails
+validation), route its code to an `@OnError` handler. The engine starts the handler workflow
+(`<workflow>.onError.<method>`) as run `<runId>.onError.<attempt>` with `{ runId, workflow, input, error }`
+when the run fails with that code, and the run settles with the handler's outcome (its output, or
+its error when the handler fails); the body never runs again, so a `ctx.all` over the workflow
+keeps going. It works for remote (Python) bodies too:
+
+```ts
+class InvalidLine extends FatalError {
+  static readonly code = 'invalid_line';
+}
+
+@OnError(InvalidLine) // or @OnError('invalid_line'); @OnError() catches anything else
+async invalid(ctx: WorkflowCtx, failure: OnErrorInput<Line>): Promise<LineResult> {
+  await ctx.step(this.steps.recordRejectedLine, { line: failure.input, error: failure.error.message });
+  return { ok: 0, failed: 1 };
+}
+```
+
+`error.details` is the third argument of `FatalError(message, code, details)` (e.g. validation
+issues). Retrying the run runs its body again; a new failure goes to a new handler run.
+It matches on `code`, never `instanceof`, must return `run`'s output type, and never sees
+cancellation (a `cancelled` run never routes), `nested_workflow_call` ctx misuse, or `non_determinism`
+(`NonDeterminismError` carries `code: 'non_determinism'`). `@Workflow({ onError: [{ code, workflow }] })` routes to another workflow.
 Source: packages/core/src/workflow-ctx.ts (`step` retry loop), packages/core/src/errors.ts.