@pikku/queue-pg-boss 0.12.3 → 0.12.4

package/CHANGELOG.md

@@ -1,3 +1,66 @@
+## 0.12.4
+
+### Patch Changes
+
+- 92cd5b1: feat(workflow): workflow-owned step retries + stable invocationId
+
+  The workflow — not the queue — now owns step retry policy, and each step
+  invocation gets a stable idempotency key.
+  - **Default `retries: 5` with exponential backoff.** A step with no `retries`
+    previously inherited the queue's bare default (e.g. pg-boss `retry_limit 2`,
+    no backoff) so retries fired instantly and couldn't outlast a transient
+    outage. Retries now default to 5 with backoff, resolved at the workflow layer.
+  - **`retries: 0` is honored.** Dispatch previously passed `undefined` options
+    for `retries: 0`, letting the queue re-run a non-idempotent step up to its own
+    default. The resolved policy now always sets `attempts` (`retries: 0` →
+    `attempts: 1`), so the queue never second-guesses the workflow. The persisted
+    step retries and the dispatched `attempts` are resolved together so
+    "retries exhausted" and "no more redeliveries" are the same event.
+  - **`workflowStep.invocationId`** — a deterministic, dependency-free
+    `uuidv5(runId:stepName)` handed to every step. Unlike `stepId` (minted per
+    attempt), it is identical across retries, so a step can dedupe on it
+    (`ON CONFLICT (invocationId)`, Stripe idempotency keys, etc.).
+  - **queue-bullmq**: `mapPikkuJobToBull` now maps `backoff` (previously dropped,
+    so a step's backoff silently never applied on Redis), and `registerQueues`
+    throws a clear error when no logger is available (matching queue-pg-boss).
+  - **Dispatch failures are recoverable, not fatal.** A step is now marked
+    `scheduled` only _after_ it is successfully handed to its transport (queue or
+    scheduler) — a failed hand-off leaves it `pending` so a replay re-dispatches
+    it, instead of stranding it in `scheduled` (replay would pause forever on a
+    job that was never enqueued). A transport outage (e.g. pg-boss momentarily
+    down) is surfaced as a new `WorkflowDispatchException`, which the orchestrator
+    treats as transient: the run is left running and the orchestrator job is
+    rethrown for redelivery (it replays idempotently from the snapshot) rather
+    than the whole run being marked `failed`. The orchestrator job now also
+    carries its own retry policy, so this holds even when the orchestrator queue
+    is configured `retry_limit 0`. A genuine step error still fails the run.
+  - **Same step name can be invoked multiple times in one run.** Step rows are now
+    keyed per _invocation_: the Nth reach of a step name in a replay resolves to a
+    physical key (`name` for the first, `name#N` for repeats), so a literal
+    duplicate name no longer clobbers the earlier step's state. The first reach
+    keeps the bare name, so existing rows, graph-node matching and `invocationId`s
+    are unchanged. Ordinals are derived deterministically from DSL execution order
+    and reset each replay.
+  - **Step provenance (`fromStepName`) + graph cycles.** Every step now records
+    the predecessor it was scheduled from (`fromStepName`; entry steps have none),
+    persisted on the step row across all stores (in-memory, kysely, redis,
+    mongodb, cloudflare DO) and carried in the queued payload. The DSL wire
+    exposes the derived `fromInvocationId` (`uuidv5(runId:fromStepName)`) so
+    consumers get the stable predecessor key without a second persisted id —
+    `fromStepName` is the source of truth (it is replay-deterministic; `stepId`,
+    minted per row, is not). This makes the walked path reconstructable even when
+    a node is reached more than once: in `a → b → a → c` the second `a` is a
+    distinct ordinal instance (`a#1`) whose `fromStepName` is `b`.
+    The graph runner now supports **cycles**: a forward edge into an
+    already-started node still collapses to a single run (joins/diamonds are
+    unchanged), but a _back-edge_ — one whose target can reach its source — fires
+    a fresh ordinal instance, so a node can loop back to itself. Termination is
+    the graph's responsibility (branch routing must converge); the engine enforces
+    no visit cap.
+
+- Updated dependencies [92cd5b1]
+  - @pikku/core@0.12.38
+
 ## 0.12.0
 
 ## 0.12.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/queue-pg-boss",
-  "version": "0.12.3",
+  "version": "0.12.4",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -8,18 +8,22 @@
   "type": "module",
   "scripts": {
     "tsc": "tsc",
+    "test": "bash run-tests.sh",
     "ncu": "npx npm-check-updates",
     "build": "tsc -b",
     "release": "npm run build && npm test",
     "prepublishOnly": "yarn build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.9"
+    "@pikku/core": "^0.12.38"
   },
   "dependencies": {
     "pg-boss": "^12.14.0"
   },
   "devDependencies": {
     "typescript": "^5.9"
+  },
+  "exports": {
+    ".": "./dist/index.js"
   }
 }

package/run-tests.sh

@@ -1,3 +1,5 @@
 #!/bin/bash
 cd "$(dirname "$0")"
-node --loader tsx --test --experimental-test-coverage src/**/*.test.ts "$@"
+files=($(find src -type f -name "*.test.ts"))
+if [ ${#files[@]} -eq 0 ]; then echo "No test files found"; exit 0; fi
+node --import tsx --test "$@" "${files[@]}"

package/src/pg-boss-queue-service.test.ts

@@ -0,0 +1,51 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { mapPikkuJobToPgBoss } from './pg-boss-queue-service.js'
+
+// These guard the contract the workflow engine relies on: a step's resolved
+// retry policy (attempts + backoff) must survive translation into pg-boss
+// terms, so "workflow owns retries" actually reaches the queue.
+describe('mapPikkuJobToPgBoss — retry mapping', () => {
+  test('attempts → retryLimit (attempts - 1)', () => {
+    // Default policy: 5 retries → 6 attempts → retryLimit 5.
+    assert.equal(mapPikkuJobToPgBoss({ attempts: 6 }).retryLimit, 5)
+  })
+
+  test('attempts: 1 (retries: 0) → retryLimit 0 (pg-boss never re-runs it)', () => {
+    assert.equal(mapPikkuJobToPgBoss({ attempts: 1 }).retryLimit, 0)
+  })
+
+  test("backoff 'exponential' → retryBackoff true", () => {
+    assert.equal(
+      mapPikkuJobToPgBoss({ attempts: 6, backoff: 'exponential' })
+        .retryBackoff,
+      true
+    )
+  })
+
+  test('fixed backoff → retryBackoff false + retryDelay in seconds', () => {
+    const opts = mapPikkuJobToPgBoss({
+      attempts: 4,
+      backoff: { type: 'fixed', delay: 5000 },
+    })
+    assert.equal(opts.retryBackoff, false)
+    // pg-boss takes seconds; our delay is milliseconds.
+    assert.equal(opts.retryDelay, 5)
+  })
+
+  test('exponential object backoff → retryBackoff true + retryDelay in seconds', () => {
+    const opts = mapPikkuJobToPgBoss({
+      attempts: 4,
+      backoff: { type: 'exponential', delay: 2000 },
+    })
+    assert.equal(opts.retryBackoff, true)
+    assert.equal(opts.retryDelay, 2)
+  })
+
+  test('no options → no retry fields set', () => {
+    const opts = mapPikkuJobToPgBoss(undefined)
+    assert.equal(opts.retryLimit, undefined)
+    assert.equal(opts.retryBackoff, undefined)
+  })
+})

package/src/pg-boss-queue-worker.test.ts

@@ -4,12 +4,12 @@ import assert from 'node:assert/strict'
 import { PgBossQueueWorkers } from './pg-boss-queue-worker.js'
 
 describe('PgBossQueueWorkers', () => {
-  test('requires setJobRunner before registerQueues', async () => {
+  test('requires a logger (explicit or from singleton services)', async () => {
     const workers = new PgBossQueueWorkers({} as any)
 
     await assert.rejects(() => workers.registerQueues(), {
       message:
-        'PgBossQueueWorkers requires setJobRunner() before registerQueues()',
+        'Logger is required for registerQueues — pass it explicitly or ensure singleton services are initialized first',
     })
   })
 })