@nestjs/workflows 0.0.4 → 0.0.5

package/dist/core/interfaces/leased-worker-options.interface.d.ts

@@ -40,7 +40,11 @@ export interface LeasedRun {
     readonly detached: boolean;
     /**
      * Renews the lease now, as the heartbeat does (a long step that proves it's alive): `false` once it's lost. A renewal
-     * that fails (the store is unreachable) keeps the lease, which the next heartbeat renews before it runs out.
+     * that fails (the store is unreachable) keeps the lease, which the next heartbeat renews before it runs out. One
+     * renewal is in flight at a time: called while one is (a heartbeat's held up by the store), it waits for that one, then
+     * for one more that goes out as soon as it answered, or beside it once it went a heartbeat interval unanswered, and
+     * resolves with that one's answer. None goes once the lease was lost, the run ended or was detached, before the call
+     * or meanwhile: it then resolves `false` if the lease was lost, else `true`.
      */
     renew(): Promise<boolean>;
     /** Marks the lease lost, when a fenced write found it gone: aborts `signal` and stops renewing. */

package/dist/core/workers/leased-worker.d.ts

@@ -2,8 +2,11 @@ import type { LeasedWorkerOptions } from '../interfaces/leased-worker-options.in
 /**
  * A claim-execute loop under leases, any number of processes sharing a store: it claims due items (as many as it has
  * free slots), executes them, renews each one's lease every `heartbeatInterval` (a third of the lease by default), and
- * aborts an item's `signal` when a renewal finds its lease gone. It looks for work every `pollInterval`, and at once
- * after `kick()` (a local write made something due) or when an item ends. `drain()` runs due items on demand, for
+ * aborts an item's `signal` when a renewal finds its lease gone. An item has one renewal in flight at a time, so a store
+ * that holds a renewal up (a lock its row waits on) gets no more of them meanwhile: one asked for in the meantime goes
+ * out once that one answered, or beside it once it went a heartbeat interval unanswered (a connection that died without
+ * an error never answers), and none more while those two are in flight. It looks for work every `pollInterval`, and at
+ * once after `kick()` (a local write made something due) or when an item ends. `drain()` runs due items on demand, for
  * tests and scripts.
  *
  * Shutdown is graceful: call `shutdown()` from `onModuleDestroy`. It stops claiming, waits for the claims in flight

package/dist/core/workers/leased-worker.js

@@ -7,8 +7,11 @@ import { setRepeatingTimer, setTimer } from '../utils/timer.util.js';
 /**
  * A claim-execute loop under leases, any number of processes sharing a store: it claims due items (as many as it has
  * free slots), executes them, renews each one's lease every `heartbeatInterval` (a third of the lease by default), and
- * aborts an item's `signal` when a renewal finds its lease gone. It looks for work every `pollInterval`, and at once
- * after `kick()` (a local write made something due) or when an item ends. `drain()` runs due items on demand, for
+ * aborts an item's `signal` when a renewal finds its lease gone. An item has one renewal in flight at a time, so a store
+ * that holds a renewal up (a lock its row waits on) gets no more of them meanwhile: one asked for in the meantime goes
+ * out once that one answered, or beside it once it went a heartbeat interval unanswered (a connection that died without
+ * an error never answers), and none more while those two are in flight. It looks for work every `pollInterval`, and at
+ * once after `kick()` (a local write made something due) or when an item ends. `drain()` runs due items on demand, for
  * tests and scripts.
  *
  * Shutdown is graceful: call `shutdown()` from `onModuleDestroy`. It stops claiming, waits for the claims in flight
@@ -211,7 +214,7 @@ export class LeasedWorker {
         }
     }
     launch(item) {
-        const run = new Run(item, () => this.renew(run));
+        const run = new Run(item, this.heartbeatMs, () => this.renew(run));
         this.runs.add(run);
         if (this.stopped) {
             run.halt();
@@ -228,7 +231,7 @@ export class LeasedWorker {
         run.done = executing
             .catch((error) => this.report(error, 'execute'))
             .finally(() => {
-            clearInterval(run.heartbeat);
+            run.end();
             this.runs.delete(run);
         });
         return run.done;
@@ -247,12 +250,21 @@ export class LeasedWorker {
 }
 /** A claimed item's run: its signal, its heartbeat, and what became of its lease. */
 class Run {
-    constructor(item, renewer) {
+    constructor(item, heartbeatMs, renewer) {
         this.item = item;
+        this.heartbeatMs = heartbeatMs;
         this.renewer = renewer;
         this.controller = new AbortController();
         this.lost = false;
         this.isDetached = false;
+        /** Its `execute` settled: no more renewals. */
+        this.ended = false;
+        /** The renewals in flight: one, or two once the older went a heartbeat interval unanswered. */
+        this.inFlight = new Set();
+        /** How many renewals went out: the next one's `seq` follows. */
+        this.sent = 0;
+        /** The `seq` of the latest renewal that landed (the store wrote its `until`). */
+        this.landed = 0;
     }
     get signal() {
         return this.controller.signal;
@@ -263,10 +275,78 @@ class Run {
     get detached() {
         return this.isDetached;
     }
-    async renew() {
-        if (this.lost || this.isDetached) {
-            return !this.lost;
+    /**
+     * Renews the lease (a heartbeat's tick, or the item's own call), one renewal at a time: a store that holds one up
+     * would otherwise get another at each tick, each holding a connection, and an older one could land after a newer
+     * one, shortening the lease. One asked for while another is in flight sends nothing then: it goes out once that one
+     * answered, its `until` read then (so after a renewal that was held up, the lease's deadline counts from when it
+     * answered), those asked for meanwhile sharing it, and resolves with its answer. A renewal a heartbeat interval
+     * unanswered no longer holds the next one back, as it may never answer (a connection that died without an error):
+     * the next goes out beside it, and no third while both are in flight. One that lands after a later one did leaves
+     * its older `until`, so one more follows it. None goes once the lease is lost (an answer, or `loseLease()`), the run
+     * ended, or it was detached: those asked for meanwhile resolve as `renew()` would then.
+     */
+    renew() {
+        if (this.lost || this.isDetached || this.ended) {
+            return Promise.resolve(!this.lost);
+        }
+        return this.canSend() ? this.send() : this.ask();
+    }
+    /** Whether a renewal can go out now: none is in flight, or one went a heartbeat interval unanswered; never a third. */
+    canSend() {
+        const [oldest, next] = this.inFlight;
+        return !oldest || (!next && oldest.late);
+    }
+    /** Asks for the renewal that goes out as soon as one can (`flush()`): its callers' answer. */
+    ask() {
+        if (!this.again) {
+            let resolve;
+            const promise = new Promise((resolved) => (resolve = resolved));
+            this.again = { promise, resolve };
+        }
+        return this.again.promise;
+    }
+    /**
+     * Sends the renewal asked for meanwhile if one can go out now (a renewal answered, or went a heartbeat interval
+     * unanswered). None goes once the lease is lost, the run ended or was detached: its callers hear what `renew()` would
+     * say then.
+     */
+    flush() {
+        const again = this.again;
+        if (!again) {
+            return;
+        }
+        if (this.lost || this.isDetached || this.ended) {
+            this.again = undefined;
+            again.resolve(!this.lost);
+        }
+        else if (this.canSend()) {
+            this.again = undefined;
+            void this.send().then(again.resolve);
         }
+    }
+    /** Sends a renewal, and once it answered, before its callers hear it, the one asked for meanwhile if it can go. */
+    send() {
+        const renewal = {
+            seq: ++this.sent,
+            late: false,
+            // Unanswered for a heartbeat interval, it no longer holds the next one back.
+            timer: setTimer(() => {
+                renewal.late = true;
+                this.flush();
+            }, this.heartbeatMs).unref(),
+        };
+        this.inFlight.add(renewal);
+        const answer = this.renewOnce(renewal.seq);
+        void answer.then(() => {
+            clearTimeout(renewal.timer);
+            this.inFlight.delete(renewal);
+            this.flush();
+        });
+        return answer;
+    }
+    /** One renewal: `false` once it found the lease gone; one that fails keeps the lease. */
+    async renewOnce(seq) {
         let held;
         try {
             held = await this.renewer();
@@ -277,8 +357,14 @@ class Run {
         }
         if (!held) {
             this.loseLease();
+            return false;
+        }
+        // It landed after a later renewal did (on a slower connection): the store keeps its older `until` now.
+        if (seq < this.landed) {
+            void this.ask();
         }
-        return held;
+        this.landed = Math.max(this.landed, seq);
+        return true;
     }
     loseLease() {
         if (this.lost) {
@@ -299,4 +385,9 @@ class Run {
         this.isDetached = true;
         clearInterval(this.heartbeat);
     }
+    /** Its `execute` settled: no more heartbeats, and no more renewals. */
+    end() {
+        this.ended = true;
+        clearInterval(this.heartbeat);
+    }
 }

package/dist/testing/index.js

@@ -426,11 +426,11 @@ export function workflowStoreContract(createStore, options = {}) {
     add('write() with a signal records it as signal() does, only when the write lands', async (t) => {
         await t.create('parent', 0);
         await t.create('child', 1);
-        await t.claim(1, { token: 'p', limit: 1 });
+        equal((await t.claim(1, { token: 'p', limit: 1 })).instances.map((i) => i.id), ['parent'], 'the parent, claimed');
         const parked = { wakeAt: FAR, waits: [{ signal: 'child.ended', key: 'child' }], signalCursor: 0 };
-        await t.store.write('parent', 'p', { now: 2, entries: [], status: 'suspended', release: parked });
-        await t.claim(3, { token: 'stale', leaseUntil: 4 });
-        await t.claim(5, { token: 'c' });
+        equal(await t.store.write('parent', 'p', { now: 2, entries: [], status: 'suspended', release: parked }), true, 'the parent, parked');
+        equal((await t.claim(3, { token: 'stale', leaseUntil: 4 })).instances.map((i) => i.id), ['child'], 'the child, claimed under a lease that ends at 4');
+        equal((await t.claim(5, { token: 'c' })).instances.map((i) => i.id), ['child'], 'the child, claimed again once that lease ended');
         const ended = { name: 'child.ended', key: 'child', dedupeId: 'child', payload: { status: 'completed', output: { label: 'LBL-1' } }, now: 6 };
         const finish = (token, now) => t.store.write('child', token, { now, entries: [], status: 'completed', output: 1, error: null, release: { wakeAt: null, waits: [], signalCursor: 0 }, signal: { ...ended, now } });
         equal(await finish('stale', 6), false, 'a stale write');

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@nestjs/workflows",
-  "version": "0.0.4",
-  "description": "Nest - modern, fast, powerful node.js web framework (@workflows)",
+  "version": "0.0.5",
+  "description": "Durable workflows for NestJS: long-running processes written as plain async code that survive restarts, with no workflow server to run.",
+  "keywords": [
+    "nestjs",
+    "nest",
+    "workflow",
+    "workflows",
+    "durable-execution",
+    "durable-workflows",
+    "saga",
+    "orchestration",
+    "long-running",
+    "compensation"
+  ],
   "author": "Kamil Mysliwiec",
   "license": "MIT",
   "url": "https://github.com/nestjs/workflows#readme",
@@ -69,17 +81,17 @@
   "devDependencies": {
     "@commitlint/cli": "21.2.4",
     "@commitlint/config-angular": "21.2.4",
-    "@electric-sql/pglite": "0.5.12",
-    "@nestjs/common": "12.2.0",
-    "@nestjs/core": "12.2.0",
-    "@nestjs/cqrs": "12.1.1",
+    "@electric-sql/pglite": "0.5.15",
+    "@nestjs/common": "12.3.3",
+    "@nestjs/core": "12.3.3",
+    "@nestjs/cqrs": "12.1.2",
     "@nestjs/drizzle": "0.0.2",
-    "@nestjs/locks": "0.0.4",
+    "@nestjs/locks": "0.0.5",
     "@nestjs/mail": "0.0.1",
-    "@nestjs/outbox": "0.1.3",
-    "@nestjs/platform-express": "12.2.0",
-    "@nestjs/platform-fastify": "12.2.0",
-    "@nestjs/testing": "12.2.0",
+    "@nestjs/outbox": "0.1.4",
+    "@nestjs/platform-express": "12.3.3",
+    "@nestjs/platform-fastify": "12.3.3",
+    "@nestjs/testing": "12.3.3",
     "@prisma/adapter-mariadb": "7.10.1",
     "@prisma/adapter-pg": "7.10.1",
     "@prisma/client": "7.10.1",
@@ -87,20 +99,20 @@
     "@types/pg": "8.23.1",
     "drizzle-orm": "0.45.4",
     "husky": "9.1.7",
-    "kysely": "0.29.7",
+    "kysely": "0.29.8",
     "lint-staged": "17.6.0",
     "mysql2": "3.24.6",
-    "oxlint": "1.89.0",
+    "oxlint": "1.91.0",
     "pg": "8.23.1",
     "prettier": "3.9.10",
     "prisma": "7.10.1",
     "reflect-metadata": "0.2.2",
-    "release-it": "21.1.1",
+    "release-it": "21.1.2",
     "rxjs": "7.8.2",
     "typeorm": "1.1.2",
     "typescript": "7.0.2",
-    "vite": "8.3.5",
-    "vitest": "5.0.5"
+    "vite": "8.3.6",
+    "vitest": "5.1.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0 || ^12.0.0",