@nestjs/workflows 0.0.2 → 0.0.3

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export { ChildWorkflowFailedError, isWorkflowInterrupt, NonRetryableStepError, S
 export type { SerializedWorkflowError } from './interfaces/index.js';
 export { WorkflowEvents, type WorkflowCancelledEvent, type WorkflowChildStartedEvent, type WorkflowCompensatingEvent, type WorkflowCompensationFailedEvent, type WorkflowCompletedEvent, type WorkflowCustomStatusEvent, type WorkflowDeletedEvent, type WorkflowEvent, type WorkflowFailedEvent, type WorkflowJournalLargeEvent, type WorkflowResumedEvent, type WorkflowRetriedEvent, type WorkflowScheduleSkippedEvent, type WorkflowSignalReceivedEvent, type WorkflowSignalTimedOutEvent, type WorkflowStartedEvent, type WorkflowStepCompensatedEvent, type WorkflowStepCompletedEvent, type WorkflowStepFailedEvent, type WorkflowSuspendedEvent, } from './events/index.js';
 export { WorkflowStorage } from './storage/index.js';
-export type { NewWorkflowInstance, NewWorkflowSignal, WorkflowCancelRequest, WorkflowClaim, WorkflowClaimRequest, WorkflowConcurrencyLimit, WorkflowInstanceDetails, WorkflowListQuery, WorkflowPurgeQuery, WorkflowPurgeResult, WorkflowRateLimitRule, WorkflowRateWindow, WorkflowRelease, WorkflowReopen, WorkflowScheduleClaimRequest, WorkflowScheduleQuery, WorkflowScheduleRecord, WorkflowScheduleSave, WorkflowScheduleWrite, WorkflowSignalQuery, WorkflowSignalRecord, WorkflowSignalResult, WorkflowStorageRegisterOptions, WorkflowStore, WorkflowWrite, } from './interfaces/index.js';
+export type { NewWorkflowInstance, NewWorkflowSignal, WorkflowCancelRequest, WorkflowClaim, WorkflowClaimRequest, WorkflowConcurrencyLimit, WorkflowInstanceDetails, WorkflowKeyKind, WorkflowListQuery, WorkflowPurgeQuery, WorkflowPurgeResult, WorkflowRateLimitRule, WorkflowRateWindow, WorkflowRelease, WorkflowReopen, WorkflowScheduleClaimRequest, WorkflowScheduleQuery, WorkflowScheduleRecord, WorkflowScheduleSave, WorkflowScheduleWrite, WorkflowSignalQuery, WorkflowSignalRecord, WorkflowSignalResult, WorkflowStorageRegisterOptions, WorkflowStore, WorkflowWrite, } from './interfaces/index.js';
 export * from './stores/index.js';
 export { AesGcmPayloadCodec, type AesGcmPayloadCodecOptions } from './core/codecs/index.js';
 export type { WorkflowPayloadCodec, WorkflowPayloadContext } from './interfaces/index.js';

package/dist/interfaces/workflow-store.interface.d.ts

@@ -204,7 +204,18 @@ export interface WorkflowStore {
      * See `WorkflowWrite` for what each field does.
      */
     write(id: string, token: string, write: WorkflowWrite): Promise<boolean>;
+    /**
+     * Optional, for a store whose ids, names or keys are bounded (columns of a fixed length): throws, synchronously, an
+     * error that names the key (a `RangeError`) when the store can't hold `value` as a `kind`. The engine calls it for
+     * what a run makes up as it goes (a step's or a wait's name, `$compensate:<step>`, a child's id and keys, a wait's
+     * signal and key) before it journals or starts anything with it, so the error fails the run at the call that made
+     * the key, and the instance compensates, instead of failing every write that carries it. Without this method, the
+     * store's own check in `write()` or `create()` is all there is, and the instance is retried as after any store error.
+     */
+    checkKey?(kind: WorkflowKeyKind, value: string): void;
 }
+/** The ids, names and keys `WorkflowStore.checkKey()` checks. */
+export type WorkflowKeyKind = 'instanceId' | 'workflow' | 'concurrencyKey' | 'rateLimitKey' | 'journalName' | 'signal' | 'signalKey';
 /** `WorkflowStore.get()`'s result, and `WorkflowClient.getStatus()`'s. */
 export interface WorkflowInstanceDetails extends WorkflowInstance {
     /** Signals the instance waits for, if suspended in `waitForSignal()`. */

package/dist/mysql/mysql-workflow.store.d.ts

@@ -1,7 +1,7 @@
 import { type OnModuleInit } from '@nestjs/common';
 import { type MigrationSqlOptions, type MigrationStatementsOptions } from '@nestjs/store-kit/mysql';
 import type { WorkflowInstance, WorkflowStatus } from '../interfaces/workflow-instance.interface.js';
-import type { NewWorkflowInstance, NewWorkflowSignal, WorkflowCancelRequest, WorkflowClaim, WorkflowClaimRequest, WorkflowInstanceDetails, WorkflowListQuery, WorkflowPurgeQuery, WorkflowPurgeResult, WorkflowReopen, WorkflowScheduleClaimRequest, WorkflowScheduleQuery, WorkflowScheduleRecord, WorkflowScheduleSave, WorkflowScheduleWrite, WorkflowSignalQuery, WorkflowSignalRecord, WorkflowSignalResult, WorkflowStore, WorkflowWrite } from '../interfaces/workflow-store.interface.js';
+import type { NewWorkflowInstance, NewWorkflowSignal, WorkflowCancelRequest, WorkflowClaim, WorkflowClaimRequest, WorkflowInstanceDetails, WorkflowKeyKind, WorkflowListQuery, WorkflowPurgeQuery, WorkflowPurgeResult, WorkflowReopen, WorkflowScheduleClaimRequest, WorkflowScheduleQuery, WorkflowScheduleRecord, WorkflowScheduleSave, WorkflowScheduleWrite, WorkflowSignalQuery, WorkflowSignalRecord, WorkflowSignalResult, WorkflowStore, WorkflowWrite } from '../interfaces/workflow-store.interface.js';
 import type { WorkflowStorage } from '../storage/workflow.storage.js';
 import type { MySqlWorkflowStoreOptions } from './interfaces/mysql-workflow-store-options.interface.js';
 /**
@@ -31,7 +31,9 @@ import type { MySqlWorkflowStoreOptions } from './interfaces/mysql-workflow-stor
  * On MySQL:
  * - Ids, names and keys are case- and accent-sensitive, and bounded: an instance id, a workflow's or a signal's name,
  *   a signal's key or id, a concurrency or rate-limit key hold at most 255 characters, a schedule's id 230, a
- *   journal entry's name 512. A longer one fails with a `RangeError` that names it, before any SQL.
+ *   journal entry's name 512. A longer one fails with a `RangeError` that names it, before any SQL. One a run makes up
+ *   (a step's or a wait's name, `$compensate:<step>`, a child's id or keys) is thrown where the run makes it
+ *   (`checkKey()`), so the run fails and compensates, as any error it throws.
  * - The application's transactions may be REPEATABLE READ, MySQL's default. `signal(..., { transaction })` finds the
  *   instances to wake with a locking read of their waits, which sees the latest committed ones whatever the level; the
  *   signal lock is held until the application's transaction ends, as on PostgreSQL. `start(..., { transaction })`
@@ -164,6 +166,8 @@ export declare class MySqlWorkflowStore implements WorkflowStore, OnModuleInit {
         terminateRequested: boolean;
     } | null>;
     write(id: string, token: string, write: WorkflowWrite): Promise<boolean>;
+    /** What a run makes up (a step's name, a child's id...), checked by the engine before it writes or starts anything with it. */
+    checkKey(kind: WorkflowKeyKind, value: string): void;
     /** The store's readiness (the server and the schema), then the signal lock's row: before its own first statement. */
     private ready;
     /**

package/dist/mysql/mysql-workflow.store.js

@@ -47,7 +47,9 @@ const ROWS_PER_INSERT = 1_000;
  * On MySQL:
  * - Ids, names and keys are case- and accent-sensitive, and bounded: an instance id, a workflow's or a signal's name,
  *   a signal's key or id, a concurrency or rate-limit key hold at most 255 characters, a schedule's id 230, a
- *   journal entry's name 512. A longer one fails with a `RangeError` that names it, before any SQL.
+ *   journal entry's name 512. A longer one fails with a `RangeError` that names it, before any SQL. One a run makes up
+ *   (a step's or a wait's name, `$compensate:<step>`, a child's id or keys) is thrown where the run makes it
+ *   (`checkKey()`), so the run fails and compensates, as any error it throws.
  * - The application's transactions may be REPEATABLE READ, MySQL's default. `signal(..., { transaction })` finds the
  *   instances to wake with a locking read of their waits, which sees the latest committed ones whatever the level; the
  *   signal lock is held until the application's transaction ends, as on PostgreSQL. `start(..., { transaction })`
@@ -604,8 +606,8 @@ WHERE ${p.in('id', ids)}`, p.values);
             checkSignal(write.signal);
         }
         for (const wait of write.release?.waits ?? []) {
-            checkKey("a wait's signal name", wait.signal, L.signal);
-            checkKey("a wait's signal key", wait.key, L.signalKey);
+            checkKey(KEYS.signal, wait.signal, L.signal);
+            checkKey(KEYS.signalKey, wait.key, L.signalKey);
         }
         return retryOnDeadlock(this.executor, async (tx) => {
             const release = write.release;
@@ -650,6 +652,10 @@ WHERE ${p.in('id', ids)}`, p.values);
             return true;
         });
     }
+    /** What a run makes up (a step's name, a child's id...), checked by the engine before it writes or starts anything with it. */
+    checkKey(kind, value) {
+        checkKey(KEYS[kind], value, L[kind]);
+    }
     // ---------------------------------------------------------------- internals
     /** The store's readiness (the server and the schema), then the signal lock's row: before its own first statement. */
     async ready() {
@@ -823,6 +829,16 @@ function checkSignal(s) {
 }
 function checkEntries(entries) {
     for (const entry of entries) {
-        checkKey("a journal entry's name (a step's, a wait's, or the engine's, such as $child: and a child's id)", entry.name, L.journalName);
+        checkKey(KEYS.journalName, entry.name, L.journalName);
     }
 }
+/** How the errors of `checkKey()`, and of `write()`'s own checks, name each key. */
+const KEYS = {
+    instanceId: 'an instance id',
+    workflow: "a workflow's name",
+    concurrencyKey: 'a concurrency key',
+    rateLimitKey: 'a rate-limit key',
+    journalName: "a journal entry's name (a step's, a wait's, or the engine's, such as $child: and a child's id)",
+    signal: "a wait's signal name",
+    signalKey: "a wait's signal key",
+};

package/dist/services/workflow-execution.service.d.ts

@@ -253,6 +253,14 @@ export declare class WorkflowExecution {
      * compensates (compensations may still record their entries) and fails.
      */
     private assertJournalRoom;
+    /**
+     * Throws the store's error for a key it can't hold (`WorkflowStore.checkKey()`), where the run makes the key: the
+     * run fails with it and compensates. Reaching the store, it would fail every write that carries it, and the instance
+     * would be retried at every lease, forever.
+     */
+    private checkKey;
+    /** A wait's signal and key, registered when the instance suspends. */
+    private checkWait;
     /** Fenced write of staged entries plus `entries`. */
     private write;
     private loseLease;

package/dist/services/workflow-execution.service.js

@@ -254,6 +254,7 @@ export class WorkflowExecution {
                 return { state: 'failed', error: entry.error };
             }
             try {
+                this.checkKey('journalName', name);
                 const attempt = await this.attempt(name, 'compensation', 
                 // Whatever the undo returns (a provider's response, say) is discarded: nothing
                 // reads it, so it can't fail the undo by being unserializable.
@@ -297,6 +298,10 @@ export class WorkflowExecution {
             throw this.interrupt('halt');
         }
         this.assertCanStart();
+        if (options.compensate) {
+            // Checked before the step runs: a side effect whose undo the store couldn't journal never happens.
+            this.checkKey('journalName', `${COMPENSATE}${name}`);
+        }
         const plan = this.plan(name, options);
         // Reserved in call order, so parallel steps compensate in the same order
         // on the first run and on a replay, whichever finished first.
@@ -341,6 +346,7 @@ export class WorkflowExecution {
             throw this.interrupt('halt');
         }
         this.assertAlive();
+        this.checkWait(wait);
         const deadline = entry
             ? (entry.wakeAt ?? null)
             : options.timeout !== undefined
@@ -424,6 +430,10 @@ export class WorkflowExecution {
             parentId: this.instance.id,
             parentClose,
         });
+        this.checkKey('instanceId', child.id);
+        this.checkKey('workflow', child.workflow);
+        this.checkKey('concurrencyKey', child.concurrencyKey);
+        this.checkKey('rateLimitKey', child.rateLimitKey);
         await this.reachFrontier(name);
         this.assertCanStart();
         // Recorded before the child exists, so a parent that crashes right after creating it still
@@ -475,6 +485,11 @@ export class WorkflowExecution {
             throw this.interrupt('halt');
         }
         this.assertAlive();
+        for (const branch of branches.values()) {
+            if (branch.wait) {
+                this.checkWait(branch.wait);
+            }
+        }
         // Timers count from when the wait was first reached: a replay keeps their deadlines.
         const now = this.deps.clock.now();
         const reached = entry?.data;
@@ -831,6 +846,7 @@ export class WorkflowExecution {
         const entry = this.journal.get(name);
         if (!entry && this.mode === 'run') {
             this.assertJournalRoom(name);
+            this.checkKey('journalName', name);
         }
         if (entry && entry.kind !== kind) {
             throw this.setFatal(new WorkflowNonDeterminismError(`${this.describe()} does not match its journal: "${name}" was recorded as a ${entry.kind}, but the code now calls it as a ${kind}. ${ADVICE}`));
@@ -958,6 +974,21 @@ export class WorkflowExecution {
         };
         throw this.interrupt('journal-limit');
     }
+    /**
+     * Throws the store's error for a key it can't hold (`WorkflowStore.checkKey()`), where the run makes the key: the
+     * run fails with it and compensates. Reaching the store, it would fail every write that carries it, and the instance
+     * would be retried at every lease, forever.
+     */
+    checkKey(kind, value) {
+        if (typeof value === 'string') {
+            this.deps.store.checkKey?.(kind, value);
+        }
+    }
+    /** A wait's signal and key, registered when the instance suspends. */
+    checkWait(wait) {
+        this.checkKey('signal', wait.signal);
+        this.checkKey('signalKey', wait.key);
+    }
     /** Fenced write of staged entries plus `entries`. */
     async write(entries) {
         if (this.detached) {

package/dist/storage/encoded-workflow.store.d.ts

@@ -18,6 +18,7 @@ export declare class EncodedWorkflowStore implements WorkflowInstanceStore {
     private readonly unreadable;
     readonly createInTransaction?: WorkflowStore['createInTransaction'];
     readonly signalInTransaction?: WorkflowStore['signalInTransaction'];
+    readonly checkKey?: WorkflowStore['checkKey'];
     constructor(
     /** The store itself: what it holds, undecoded. */
     inner: WorkflowStore, codecs: PayloadCodecs<WorkflowPayloadContext>);

package/dist/storage/encoded-workflow.store.js

@@ -21,6 +21,10 @@ export class EncodedWorkflowStore {
         if (typeof inner.signalInTransaction === 'function') {
             this.signalInTransaction = (transaction, signal) => toPromise(andThen(this.encodeSignal(signal), (encoded) => inner.signalInTransaction(transaction, encoded)));
         }
+        // Keys aren't encoded: the store checks them as they are.
+        if (typeof inner.checkKey === 'function') {
+            this.checkKey = (kind, value) => inner.checkKey(kind, value);
+        }
     }
     /** Whether a codec encodes what is written. */
     get encodes() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs/workflows",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Nest - modern, fast, powerful node.js web framework (@workflows)",
   "author": "Kamil Mysliwiec",
   "license": "MIT",
@@ -73,32 +73,32 @@
     "@nestjs/core": "12.1.2",
     "@nestjs/cqrs": "12.1.0",
     "@nestjs/drizzle": "0.0.1",
-    "@nestjs/locks": "0.0.1",
+    "@nestjs/locks": "0.0.2",
     "@nestjs/mail": "0.0.1",
-    "@nestjs/outbox": "0.1.0",
+    "@nestjs/outbox": "0.1.1",
     "@nestjs/platform-express": "12.1.2",
     "@nestjs/platform-fastify": "12.1.2",
     "@nestjs/testing": "12.1.2",
     "@prisma/adapter-mariadb": "7.10.0",
     "@prisma/adapter-pg": "7.10.0",
     "@prisma/client": "7.10.0",
-    "@types/node": "24.19.1",
+    "@types/node": "24.19.2",
     "@types/pg": "8.23.1",
-    "drizzle-orm": "0.45.3",
+    "drizzle-orm": "0.45.4",
     "husky": "9.1.7",
     "kysely": "0.29.6",
     "lint-staged": "17.6.0",
     "mysql2": "3.24.5",
     "oxlint": "1.87.0",
     "pg": "8.23.1",
-    "prettier": "3.9.9",
+    "prettier": "3.9.10",
     "prisma": "7.10.0",
     "reflect-metadata": "0.2.2",
     "release-it": "21.1.1",
     "rxjs": "7.8.2",
-    "typeorm": "1.1.1",
+    "typeorm": "1.1.2",
     "typescript": "7.0.2",
-    "vite": "8.3.3",
+    "vite": "8.3.4",
     "vitest": "5.0.3"
   },
   "peerDependencies": {