@nestjs/workflows 0.0.3 → 0.0.5

package/dist/utils/storable-text.util.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Where the engine stores a piece of text, which decides what it asks the store (`WorkflowStore.unstorableText()`):
+ * - `payload`: an input, a result, a payload, a status, an output, in a JSON column, which a codec encodes;
+ * - `cancelReason`: a cancel's reason, in a text column, which a codec encodes;
+ * - `name`: a journal entry's name (a step's, a wait's, `$child:<id>`), which the entry's JSON holds too, never encoded;
+ * - `key`: an id, a name or a key in a text column of its own, never encoded.
+ */
+export type TextPlace = 'payload' | 'cancelReason' | 'name' | 'key';
+/** What the store can't keep of `text` at a place (such as `'U+0000'`), or `undefined`. */
+export type TextCheck = (text: string) => string | undefined;
+/** A place's check, or `undefined` where the store keeps any text (`EncodedWorkflowStore.textCheck()`). */
+export type TextChecks = (place: TextPlace) => TextCheck | undefined;
+/** `'U+0000'` when `text` holds it (PostgreSQL keeps it in neither `text` nor `jsonb`), else `undefined`. */
+export declare function nulIn(text: string): string | undefined;
+/** `'a lone UTF-16 surrogate'` when `text` holds one (PostgreSQL and MySQL refuse it in JSON), else `undefined`. */
+export declare function loneSurrogateIn(text: string): string | undefined;
+/**
+ * The first string of a JSON value (what `JSON.parse()` returns), a value or an object's key, that `check` refuses,
+ * with its path (`$.lines[0].note`), or `undefined`. Walks with a stack of its own, so a value as deep as
+ * `JSON.stringify()` takes can't overflow the call stack; the path is built only for what it finds.
+ */
+export declare function findUnstorableText(value: unknown, check: TextCheck): {
+    path: string;
+    problem: string;
+} | undefined;
+/** Throws a `TypeError` that names `what` when `check` refuses `text`. */
+export declare function assertStorableText(what: string, text: string | null | undefined, check: TextCheck | undefined): void;
+/** The same for a JSON value (what `normalize()` returns), naming where in `what` the text sits. */
+export declare function assertStorableJson(what: string, value: unknown, check: TextCheck | undefined): void;
+/** `assertStorableJson()`'s error, for a caller that reports it in its own way, or `undefined`. */
+export declare function unstorableJson(what: string, value: unknown, check: TextCheck | undefined): TypeError | undefined;
+/**
+ * `text`, with U+0000 and lone surrogates replaced with U+FFFD when `check` refuses it: for an error's text, which is
+ * recorded whatever it holds.
+ */
+export declare function storableText(text: string, check: TextCheck | undefined): string;

package/dist/utils/storable-text.util.js

@@ -0,0 +1,96 @@
+/** `'U+0000'` when `text` holds it (PostgreSQL keeps it in neither `text` nor `jsonb`), else `undefined`. */
+export function nulIn(text) {
+    return text.includes('\u0000') ? 'U+0000' : undefined;
+}
+/** `'a lone UTF-16 surrogate'` when `text` holds one (PostgreSQL and MySQL refuse it in JSON), else `undefined`. */
+export function loneSurrogateIn(text) {
+    return text.isWellFormed() ? undefined : 'a lone UTF-16 surrogate';
+}
+/**
+ * The first string of a JSON value (what `JSON.parse()` returns), a value or an object's key, that `check` refuses,
+ * with its path (`$.lines[0].note`), or `undefined`. Walks with a stack of its own, so a value as deep as
+ * `JSON.stringify()` takes can't overflow the call stack; the path is built only for what it finds.
+ */
+export function findUnstorableText(value, check) {
+    const pending = [{ value, parent: undefined, at: undefined }];
+    for (let step = pending.pop(); step; step = pending.pop()) {
+        if (step.keyProblem) {
+            return { path: `${pathOf(step)} (its key)`, problem: step.keyProblem };
+        }
+        const current = step.value;
+        if (typeof current === 'string') {
+            const problem = check(current);
+            if (problem) {
+                return { path: pathOf(step), problem };
+            }
+        }
+        else if (Array.isArray(current)) {
+            // Last first, so the first is checked first. Numbers, booleans and null hold no text.
+            for (let i = current.length - 1; i >= 0; i--) {
+                if (holdsText(current[i])) {
+                    pending.push({ value: current[i], parent: step, at: i });
+                }
+            }
+        }
+        else if (current !== null && typeof current === 'object') {
+            const keys = Object.keys(current);
+            for (let i = keys.length - 1; i >= 0; i--) {
+                const key = keys[i];
+                const child = current[key];
+                const keyProblem = check(key);
+                if (keyProblem || holdsText(child)) {
+                    pending.push({ value: child, parent: step, at: key, keyProblem });
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/** Throws a `TypeError` that names `what` when `check` refuses `text`. */
+export function assertStorableText(what, text, check) {
+    const problem = check && typeof text === 'string' ? check(text) : undefined;
+    if (problem) {
+        throw unstorable(what, problem);
+    }
+}
+/** The same for a JSON value (what `normalize()` returns), naming where in `what` the text sits. */
+export function assertStorableJson(what, value, check) {
+    const refused = unstorableJson(what, value, check);
+    if (refused) {
+        throw refused;
+    }
+}
+/** `assertStorableJson()`'s error, for a caller that reports it in its own way, or `undefined`. */
+export function unstorableJson(what, value, check) {
+    const found = check && findUnstorableText(value, check);
+    return found ? unstorable(`${what} at ${found.path}`, found.problem) : undefined;
+}
+/**
+ * `text`, with U+0000 and lone surrogates replaced with U+FFFD when `check` refuses it: for an error's text, which is
+ * recorded whatever it holds.
+ */
+export function storableText(text, check) {
+    return check?.(text) === undefined ? text : text.replaceAll('\u0000', '�').toWellFormed();
+}
+function unstorable(where, problem) {
+    return new TypeError(`${where} holds ${problem}, which the workflow store can't keep.`);
+}
+function holdsText(value) {
+    return typeof value === 'string' || (value !== null && typeof value === 'object');
+}
+function pathOf(step) {
+    let path = '';
+    for (let at = step; at; at = at.parent) {
+        path = segment(at.at) + path;
+    }
+    return path;
+}
+function segment(at) {
+    if (at === undefined) {
+        return '$';
+    }
+    if (typeof at === 'number') {
+        return `[${at}]`;
+    }
+    return /^[A-Za-z_$][\w$]*$/.test(at) ? `.${at}` : `[${JSON.stringify(at)}]`;
+}

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@nestjs/workflows",
-  "version": "0.0.3",
-  "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",
@@ -51,6 +63,7 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "format": "prettier --write \"**/*.ts\"",
     "lint": "oxlint lib/",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
     "generate:prisma": "prisma generate --config tests/fixtures/prisma/prisma.config.ts && prisma generate --config tests/fixtures/prisma-mysql/prisma.config.ts",
     "prepublish:npm": "npm run build",
     "publish:npm": "npm publish --access public",
@@ -66,40 +79,40 @@
     "@nestjs/store-kit": "^0.1.0"
   },
   "devDependencies": {
-    "@commitlint/cli": "21.2.3",
-    "@commitlint/config-angular": "21.2.3",
-    "@electric-sql/pglite": "0.5.8",
-    "@nestjs/common": "12.1.2",
-    "@nestjs/core": "12.1.2",
-    "@nestjs/cqrs": "12.1.0",
-    "@nestjs/drizzle": "0.0.1",
-    "@nestjs/locks": "0.0.2",
+    "@commitlint/cli": "21.2.4",
+    "@commitlint/config-angular": "21.2.4",
+    "@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.5",
     "@nestjs/mail": "0.0.1",
-    "@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",
+    "@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",
     "@types/node": "24.19.2",
     "@types/pg": "8.23.1",
     "drizzle-orm": "0.45.4",
     "husky": "9.1.7",
-    "kysely": "0.29.6",
+    "kysely": "0.29.8",
     "lint-staged": "17.6.0",
-    "mysql2": "3.24.5",
-    "oxlint": "1.87.0",
+    "mysql2": "3.24.6",
+    "oxlint": "1.91.0",
     "pg": "8.23.1",
     "prettier": "3.9.10",
-    "prisma": "7.10.0",
+    "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.4",
-    "vitest": "5.0.3"
+    "vite": "8.3.6",
+    "vitest": "5.1.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0 || ^12.0.0",