@dudousxd/nestjs-durable 0.47.0 → 0.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-durable",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "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/nestjs-durable-core": "^0.78.0",
-    "@dudousxd/nestjs-durable-dashboard": "0.50.0",
-    "@dudousxd/nestjs-durable-transport-bullmq": "0.22.0",
-    "@dudousxd/nestjs-durable-transport-event-emitter": "^0.5.1",
-    "@dudousxd/durable-worker": "0.10.3"
+    "@dudousxd/durable-worker": "0.11.0",
+    "@dudousxd/nestjs-durable-core": "^0.79.0",
+    "@dudousxd/nestjs-durable-dashboard": "0.51.0",
+    "@dudousxd/nestjs-durable-testing": "^0.18.0",
+    "@dudousxd/nestjs-durable-transport-bullmq": "0.22.1",
+    "@dudousxd/nestjs-durable-transport-event-emitter": "^0.5.1"
   },
   "module": "./dist/index.js",
   "exports": {

package/skills/durable-setup/SKILL.md

@@ -116,6 +116,12 @@ DurableModule.forRootAsync({
 });
 ```
 
+`BullMQTransport` has two concurrency knobs. `concurrency` (default `1`; a number, `'adaptive'`, or
+`{ mode: 'adaptive', min, max, ... }`) is how many TASKS a worker runs at once from each step queue.
+`resultConcurrency` (default `1`) is how many step RESULTS the engine side handles at once. Raise it
+for wide fans; one run's results still resume it in order on an instance. A non-finite or sub-1
+`resultConcurrency` falls back to `1`.
+
 ### Split API pods from worker pods
 
 `DurableModule.forRoot` is the ONE module; the role is inferred from which of `store`/`connection`

package/skills/durable-workflows/SKILL.md

@@ -6,7 +6,8 @@ description: >
   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
+  retries/backoff and FatalError, Promise.all fan-out, ctx.all over a @Step (step fans with
+  concurrency waves and waitAll/failFast), 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
@@ -145,10 +146,49 @@ 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).
 
+How the step fan behaves (`AllStepsOptions`):
+
+- `concurrency` sends strict waves of that many steps; the next wave goes out once the whole
+  previous wave has settled. It is part of the fan's identity, like `inputs` — don't change it under
+  an in-flight run. It must be a positive integer.
+- `mode: 'waitAll'` (default) lets every step settle, then throws `GatherError` with every failed
+  index. `mode: 'failFast'` throws `GatherError` with the first failure, sends no further waves, and
+  does NOT cancel steps already in flight.
+- A step only counts as failed once its retries (the `@Step` policy, or per-call `retries` /
+  `backoff`) are spent.
+- Rejected: a `queue` option, and a `@Step` that declares `timeoutMs`.
+- The steps share `parallelGroup` `steps:<firstSeq>:<size>[:failFast]`.
+
+```ts
+import { GatherError } from '@dudousxd/nestjs-durable-core';
+
+let failedAt: number | undefined;
+try {
+  await ctx.all(this.lines.processLine, lines, { concurrency: 500, mode: 'failFast' });
+} catch (err) {
+  if (!(err instanceof GatherError)) throw err;
+  failedAt = err.failures[0]?.index; // the first failed input's position
+}
+```
+
+For a wide fan over `BullMQTransport`, raise `resultConcurrency` (default 1) on the instances that
+consume results; one run's results still resume it in order on an instance.
+
 ### Sub-process events inside a step
 
 For pure visibility *inside* one step's execution, the `@Step` handler's optional second argument
@@ -184,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
 
@@ -247,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.recordDeadLetter, { 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.