@nestjs/workflows 0.0.1

package/LICENSE

@@ -0,0 +1,23 @@
+(The MIT License)
+
+Copyright (c) 2026 Kamil Mysliwiec
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

package/README.md

@@ -0,0 +1,50 @@
+<p align="center">
+  <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
+</p>
+
+[travis-image]: https://api.travis-ci.org/nestjs/nest.svg?branch=master
+[travis-url]: https://travis-ci.org/nestjs/nest
+[linux-image]: https://img.shields.io/travis/nestjs/nest/master.svg?label=linux
+[linux-url]: https://travis-ci.org/nestjs/nest
+
+  <p align="center">A progressive <a href="http://nodejs.org" target="blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
+    <p align="center">
+<a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
+<a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
+<a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/dm/@nestjs/core.svg" alt="NPM Downloads" /></a>
+<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
+<a href="https://opencollective.com/nest#backer"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
+<a href="https://opencollective.com/nest#sponsor"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
+  <a href="https://paypal.me/kamilmysliwiec"><img src="https://img.shields.io/badge/Donate-PayPal-dc3d53.svg"/></a>
+  <a href="https://twitter.com/nestframework"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow"></a>
+</p>
+  <!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
+  [![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
+
+## Description
+
+Durable workflows module for [Nest](https://github.com/nestjs/nest): long-running, multi-step processes written as plain async code that survive restarts, with journaled steps, durable timers, signals and compensations, backed by your own database and with no third-party dependencies.
+
+## Installation
+
+```bash
+$ npm i --save @nestjs/workflows
+```
+
+## Quick Start
+
+[Overview & Tutorial](https://docs.nestjs.com/reliability/workflows)
+
+## Support
+
+Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
+
+## Stay in touch
+
+- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
+- Website - [https://nestjs.com](https://nestjs.com/)
+- Twitter - [@nestframework](https://twitter.com/nestframework)
+
+## License
+
+Nest is [MIT licensed](LICENSE).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// The `nest-workflows` command: the first-party stores' migrations from a shell or a CI step. `migrate` and `status`
+// pick the store by the URL (postgres:// or postgresql://: PostgresWorkflowStore; mysql://: MySqlWorkflowStore), and
+// `sql` prints PostgreSQL's unless `--dialect mysql` says otherwise.
+import { runStoreCli } from '@nestjs/store-kit';
+import { mysqlWorkflowStoreSchema } from './mysql/migrations/index.js';
+import { workflowStoreSchema } from './postgres/migrations/index.js';
+process.exitCode = await runStoreCli([workflowStoreSchema, mysqlWorkflowStoreSchema], process.argv.slice(2));

package/dist/core/codecs/aes-gcm-payload.codec.d.ts

@@ -0,0 +1,42 @@
+import type { PayloadCodec, PayloadContext } from '../interfaces/payload-codec.interface.js';
+/**
+ * What `AesGcmPayloadCodec` takes.
+ *
+ * ```ts
+ * const options: AesGcmPayloadCodecOptions = { keys: { '2026-09': process.env.PAYLOADS_KEY! }, current: '2026-09' };
+ * ```
+ */
+export interface AesGcmPayloadCodecOptions {
+    /**
+     * The keys by id (letters, digits, `_` and `-`): 32 random bytes each (AES-256), as a `Buffer` or `Uint8Array`,
+     * or as base64 (`openssl rand -base64 32`). Keep a key here while payloads it encrypted may still be read.
+     */
+    keys: Record<string, string | Uint8Array>;
+    /** The id of the key that encrypts. The others only decrypt: to rotate, add a key and make it `current`. */
+    current: string;
+    /** Deflate a payload of at least this many bytes (as JSON) before encrypting it; `false` never. Default 1024. */
+    compress?: number | false;
+}
+/**
+ * Encrypts payloads with AES-256-GCM (`node:crypto`), under a key derived for each payload from the configured one
+ * (HKDF-SHA256 with a random salt) and a random IV, so no key nears the 2^32 encryptions random IVs allow, and with
+ * the payload's context as additional authenticated data, so a payload that was changed, or moved to another place
+ * (another instance, journal entry, job or field), fails to decrypt instead of being read. The key's id is stored with
+ * each payload, so rotating keys needs no migration: payloads are decrypted with the key that encrypted them, and
+ * written with the current one. Payloads of 1 KiB or more are deflated first. Its `id` is `'aes-256-gcm'`.
+ *
+ * ```ts
+ * WorkflowsModule.forRoot({
+ *   codec: new AesGcmPayloadCodec({ keys: { '2026-09': process.env.WORKFLOWS_KEY! }, current: '2026-09' }),
+ * })
+ * ```
+ */
+export declare class AesGcmPayloadCodec implements PayloadCodec {
+    readonly id = "aes-256-gcm";
+    private readonly keys;
+    private readonly current;
+    private readonly threshold;
+    constructor(options: AesGcmPayloadCodecOptions);
+    encode(value: unknown, context: PayloadContext): string;
+    decode(data: string, context: PayloadContext): unknown;
+}

package/dist/core/codecs/aes-gcm-payload.codec.js

@@ -0,0 +1,119 @@
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from 'node:crypto';
+import { deflateRawSync, inflateRawSync } from 'node:zlib';
+import { describePlace, otherPlaces, WORKFLOW_PLACES } from '../utils/payload-place.util.js';
+const SALT_BYTES = 16;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const HEADER_BYTES = SALT_BYTES + IV_BYTES;
+/** The first byte of every plaintext: its format. Bit 0: deflated. */
+const DEFLATED = 1;
+/**
+ * Encrypts payloads with AES-256-GCM (`node:crypto`), under a key derived for each payload from the configured one
+ * (HKDF-SHA256 with a random salt) and a random IV, so no key nears the 2^32 encryptions random IVs allow, and with
+ * the payload's context as additional authenticated data, so a payload that was changed, or moved to another place
+ * (another instance, journal entry, job or field), fails to decrypt instead of being read. The key's id is stored with
+ * each payload, so rotating keys needs no migration: payloads are decrypted with the key that encrypted them, and
+ * written with the current one. Payloads of 1 KiB or more are deflated first. Its `id` is `'aes-256-gcm'`.
+ *
+ * ```ts
+ * WorkflowsModule.forRoot({
+ *   codec: new AesGcmPayloadCodec({ keys: { '2026-09': process.env.WORKFLOWS_KEY! }, current: '2026-09' }),
+ * })
+ * ```
+ */
+export class AesGcmPayloadCodec {
+    constructor(options) {
+        this.id = 'aes-256-gcm';
+        this.keys = new Map();
+        if (options === null || typeof options !== 'object' || options.keys === null || typeof options.keys !== 'object') {
+            throw new TypeError('AesGcmPayloadCodec: pass { keys: { [keyId]: key }, current: keyId }.');
+        }
+        for (const [id, key] of Object.entries(options.keys)) {
+            if (!/^[\w-]+$/.test(id)) {
+                throw new TypeError(`AesGcmPayloadCodec: invalid key id ${JSON.stringify(id)}. Use letters, digits, "_" and "-".`);
+            }
+            this.keys.set(id, keyBytes(id, key));
+        }
+        if (!this.keys.has(options.current)) {
+            throw new TypeError(`AesGcmPayloadCodec: current (${JSON.stringify(options.current)}) must be one of the keys' ids (${[...this.keys.keys()].join(', ') || 'none'}).`);
+        }
+        this.current = options.current;
+        const compress = options.compress ?? 1_024;
+        if (compress !== false && (!Number.isSafeInteger(compress) || compress < 0)) {
+            throw new TypeError(`AesGcmPayloadCodec: compress (${JSON.stringify(compress)}) must be a number of bytes, or false.`);
+        }
+        this.threshold = compress === false ? Infinity : compress;
+    }
+    encode(value, context) {
+        const json = Buffer.from(JSON.stringify(value), 'utf8');
+        const deflated = json.length >= this.threshold;
+        const plaintext = Buffer.concat([Buffer.of(deflated ? DEFLATED : 0), deflated ? deflateRawSync(json) : json]);
+        const header = randomBytes(HEADER_BYTES);
+        const cipher = createCipheriv('aes-256-gcm', derived(this.keys.get(this.current), header), header.subarray(SALT_BYTES));
+        cipher.setAAD(associated(this.current, context));
+        const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+        return `${this.current}.${Buffer.concat([header, ciphertext, cipher.getAuthTag()]).toString('base64url')}`;
+    }
+    decode(data, context) {
+        const dot = data.indexOf('.');
+        const id = data.slice(0, dot);
+        const key = this.keys.get(id);
+        if (dot < 0 || !key) {
+            throw new Error(`AesGcmPayloadCodec: a payload of ${describePlace(context)} was encrypted with key ${JSON.stringify(id)}, which isn't in keys. ` +
+                'Keep a key in keys while payloads it encrypted may still be read.');
+        }
+        const bytes = Buffer.from(data.slice(dot + 1), 'base64url');
+        let plaintext;
+        try {
+            const decipher = createDecipheriv('aes-256-gcm', derived(key, bytes), bytes.subarray(SALT_BYTES, HEADER_BYTES));
+            decipher.setAAD(associated(id, context));
+            decipher.setAuthTag(bytes.subarray(bytes.length - TAG_BYTES));
+            plaintext = Buffer.concat([decipher.update(bytes.subarray(HEADER_BYTES, bytes.length - TAG_BYTES)), decipher.final()]);
+        }
+        catch {
+            throw new Error(`AesGcmPayloadCodec: a payload of ${describePlace(context)} failed authentication: it was changed, or encrypted for another place.`);
+        }
+        const body = plaintext.subarray(1);
+        return JSON.parse(((plaintext[0] & DEFLATED) === DEFLATED ? inflateRawSync(body) : body).toString('utf8'));
+    }
+}
+function keyBytes(id, key) {
+    const advice = 'Give it 32 random bytes, as a Buffer, a Uint8Array, or base64 (`openssl rand -base64 32`).';
+    let bytes;
+    if (key instanceof Uint8Array) {
+        bytes = Buffer.from(key);
+    }
+    else if (typeof key === 'string') {
+        // Buffer.from() skips what isn't base64, so a key with a typo would decode to other bytes instead of failing.
+        const text = key.trim();
+        if (text.length === 0) {
+            throw new TypeError(`AesGcmPayloadCodec: key "${id}" is an empty string. ${advice}`);
+        }
+        if (!/^[A-Za-z0-9+/_-]+={0,2}$/.test(text)) {
+            throw new TypeError(`AesGcmPayloadCodec: key "${id}" isn't base64. ${advice}`);
+        }
+        bytes = Buffer.from(text, 'base64');
+    }
+    else {
+        const what = key === undefined ? "undefined (an environment variable that isn't set?)" : key === null ? 'null' : typeof key === 'object' ? 'an object' : `a ${typeof key}`;
+        throw new TypeError(`AesGcmPayloadCodec: key "${id}" is ${what}. ${advice}`);
+    }
+    if (bytes.length !== 32) {
+        throw new TypeError(`AesGcmPayloadCodec: key "${id}" is ${bytes.length} bytes; AES-256 takes 32 (as a Buffer, or base64: \`openssl rand -base64 32\`).`);
+    }
+    return bytes;
+}
+/** The payload's own key: HKDF-SHA256 of the configured key, with the salt that starts the payload's bytes. */
+function derived(key, bytes) {
+    return Buffer.from(hkdfSync('sha256', key, bytes.subarray(0, SALT_BYTES), 'nestjs-workflows payload', 32));
+}
+/**
+ * The additional authenticated data: the key's id, then the context: its `field` and workflows' places (`null` where
+ * absent) first, in the order this codec was built with, so what it encrypted then still decrypts, then any other
+ * key, by name, with its value.
+ */
+function associated(key, context) {
+    const places = WORKFLOW_PLACES.map((place) => context[place] ?? null);
+    const others = otherPlaces(context).flatMap((place) => [place, context[place]]);
+    return Buffer.from(JSON.stringify([key, context.field, ...places, ...others]), 'utf8');
+}

package/dist/core/codecs/index.d.ts

@@ -0,0 +1,2 @@
+export * from './aes-gcm-payload.codec.js';
+export * from './payload-codecs.js';

package/dist/core/codecs/index.js

@@ -0,0 +1,2 @@
+export * from './aes-gcm-payload.codec.js';
+export * from './payload-codecs.js';

package/dist/core/codecs/payload-codecs.d.ts

@@ -0,0 +1,59 @@
+import type { PayloadCodec, PayloadContext, SerializedError } from '../interfaces/payload-codec.interface.js';
+import { type Maybe } from '../utils/maybe.util.js';
+/**
+ * What `PayloadCodecs` names in its errors.
+ *
+ * ```ts
+ * new PayloadCodecs(codecs, { name: "QueuesModule's codec", type: 'QueuePayloadCodec' });
+ * ```
+ */
+export interface PayloadCodecsOptions {
+    /** The option the codecs come from, such as `"WorkflowsModule's codec"`. Default `"the module's codec"`. */
+    name?: string;
+    /** What a codec implements, such as `'WorkflowPayloadCodec'`. Default `'PayloadCodec'`. */
+    type?: string;
+}
+/**
+ * A package's payload codecs and the family's envelope, which stores what they encode as
+ * `$wf1:<codec id>:<encoded>`, so every package encodes alike and a codec reads what another package wrote. The
+ * first codec encodes; each payload is decoded by the codec whose id it carries, so a codec that was replaced keeps
+ * decoding what it wrote (list it after the new one). `null` and `undefined` stay as they are. Payloads stored before
+ * any codec was set are read as they are, and without codecs nothing is encoded, but a string that looks like an
+ * envelope is wrapped as one (`plain`) rather than stored as it is, and an encoded payload no listed codec knows fails
+ * to decode instead of being read as a string.
+ *
+ * ```ts
+ * const codecs = new PayloadCodecs([new AesGcmPayloadCodec({ keys, current: '2026-09' })], { name: "QueuesModule's codec" });
+ * const stored = await codecs.encode(job.data, { field: 'data', queue: 'emails', job: job.id });
+ * const data = await codecs.decode(row.data, { field: 'data', queue: 'emails', job: row.id });
+ * ```
+ */
+export declare class PayloadCodecs<C extends PayloadContext = PayloadContext> {
+    private readonly writer;
+    private readonly byId;
+    private readonly name;
+    constructor(codecs: PayloadCodec<C>[], options?: PayloadCodecsOptions);
+    /** Whether a codec encodes what is written (else payloads are stored as they are). */
+    get encodes(): boolean;
+    /** `value` in an envelope, or as it is (no codec, `null`, `undefined`). Synchronous when the codec is. */
+    encode(value: unknown, context: C): Maybe<unknown>;
+    /** The value in an envelope, or `stored` as it is when it isn't one. Throws for a codec that isn't listed. */
+    decode(stored: unknown, context: C): Maybe<unknown>;
+    /**
+     * An error with its `message` and `stack` encoded together into `message`, and its `name` as it is (the error's
+     * class, which the store may filter on, not the application's data); a nested error (a field holding another
+     * `SerializedError`) likewise, and nothing else. Without a codec, as it is, unless a message starts like an envelope.
+     */
+    encodeError<E extends SerializedError | null | undefined>(error: E, context: C): Maybe<E>;
+    /** What `encodeError()` encoded, decoded; an error stored as it is comes back as it is. */
+    decodeError<E extends SerializedError | null | undefined>(error: E, context: C): Promise<E>;
+}
+/**
+ * Whether a stored value is an encoded payload, in the family's envelope, rather than one stored as it is: a string
+ * starting with `$wf1:`. For stores that skip decoding what needs none.
+ *
+ * ```ts
+ * const payload = isEncodedPayload(row.data) ? await codecs.decode(row.data, context) : row.data;
+ * ```
+ */
+export declare function isEncodedPayload(value: unknown): value is string;

package/dist/core/codecs/payload-codecs.js

@@ -0,0 +1,130 @@
+import { andThen } from '../utils/maybe.util.js';
+import { describePlace } from '../utils/payload-place.util.js';
+/**
+ * An encoded payload as stored: `$wf1:<codec id>:<what the codec returned>`. The prefix tells it from a payload
+ * stored as it is (without a codec), and the codec's id picks the codec that decodes it. A payload stored as it is
+ * can't start with the prefix: a string that does (the application's data) is stored as a `plain` envelope of its
+ * JSON instead, so no payload is ever mistaken for another's envelope.
+ */
+const ENVELOPE = '$wf1:';
+/** The envelope's own codec, for a string that starts like one when no codec encodes it: its JSON. */
+const PLAIN = {
+    id: 'plain',
+    encode: (value) => JSON.stringify(value),
+    decode: (data) => JSON.parse(data),
+};
+/**
+ * A package's payload codecs and the family's envelope, which stores what they encode as
+ * `$wf1:<codec id>:<encoded>`, so every package encodes alike and a codec reads what another package wrote. The
+ * first codec encodes; each payload is decoded by the codec whose id it carries, so a codec that was replaced keeps
+ * decoding what it wrote (list it after the new one). `null` and `undefined` stay as they are. Payloads stored before
+ * any codec was set are read as they are, and without codecs nothing is encoded, but a string that looks like an
+ * envelope is wrapped as one (`plain`) rather than stored as it is, and an encoded payload no listed codec knows fails
+ * to decode instead of being read as a string.
+ *
+ * ```ts
+ * const codecs = new PayloadCodecs([new AesGcmPayloadCodec({ keys, current: '2026-09' })], { name: "QueuesModule's codec" });
+ * const stored = await codecs.encode(job.data, { field: 'data', queue: 'emails', job: job.id });
+ * const data = await codecs.decode(row.data, { field: 'data', queue: 'emails', job: row.id });
+ * ```
+ */
+export class PayloadCodecs {
+    constructor(codecs, options = {}) {
+        this.name = options.name ?? "the module's codec";
+        const ids = new Set();
+        for (const codec of codecs) {
+            if (codec === null || typeof codec !== 'object' || typeof codec.encode !== 'function' || typeof codec.decode !== 'function') {
+                throw new TypeError(`${this.name}: expected a ${options.type ?? 'PayloadCodec'} (an object with id, encode() and decode()), got ${String(codec)}.`);
+            }
+            if (typeof codec.id !== 'string' || !/^[\w.-]+$/.test(codec.id) || codec.id === PLAIN.id) {
+                throw new TypeError(`${this.name}: ${codec.constructor.name} has an invalid id ${JSON.stringify(codec.id)}. Use letters, digits, ".", "_" and "-" ` +
+                    `("${PLAIN.id}" is the envelope's).`);
+            }
+            if (ids.has(codec.id)) {
+                throw new TypeError(`${this.name}: two codecs have the id "${codec.id}". Give each its own.`);
+            }
+            ids.add(codec.id);
+        }
+        this.writer = codecs[0];
+        this.byId = new Map([...codecs, PLAIN].map((codec) => [codec.id, codec]));
+    }
+    /** Whether a codec encodes what is written (else payloads are stored as they are). */
+    get encodes() {
+        return this.writer !== undefined;
+    }
+    /** `value` in an envelope, or as it is (no codec, `null`, `undefined`). Synchronous when the codec is. */
+    encode(value, context) {
+        const writer = this.writer ?? (isEncodedPayload(value) ? PLAIN : undefined);
+        if (value === undefined || value === null || !writer) {
+            return value;
+        }
+        return andThen(writer.encode(value, context), (data) => `${ENVELOPE}${writer.id}:${data}`);
+    }
+    /** The value in an envelope, or `stored` as it is when it isn't one. Throws for a codec that isn't listed. */
+    decode(stored, context) {
+        if (!isEncodedPayload(stored)) {
+            return stored;
+        }
+        const end = stored.indexOf(':', ENVELOPE.length);
+        const id = stored.slice(ENVELOPE.length, end);
+        const codec = this.byId.get(id);
+        if (end < 0 || !codec) {
+            throw new Error(`A payload of ${describePlace(context)} was encoded by the codec "${id}", which ${this.name} option doesn't list. ` +
+                'Keep a codec listed (codec: [current, previous]) while payloads it encoded may still be read.');
+        }
+        return codec.decode(stored.slice(end + 1), context);
+    }
+    /**
+     * An error with its `message` and `stack` encoded together into `message`, and its `name` as it is (the error's
+     * class, which the store may filter on, not the application's data); a nested error (a field holding another
+     * `SerializedError`) likewise, and nothing else. Without a codec, as it is, unless a message starts like an envelope.
+     */
+    encodeError(error, context) {
+        if (error === null || error === undefined || (!this.writer && !messages(error).some(isEncodedPayload))) {
+            return error;
+        }
+        const secret = { message: error.message, ...(error.stack === undefined ? {} : { stack: error.stack }) };
+        const writer = this.writer ?? PLAIN;
+        const nested = nestedErrors(error);
+        return andThen(andThen(writer.encode(secret, context), (data) => `${ENVELOPE}${writer.id}:${data}`), (message) => andThen(all(nested.map(([, inner]) => this.encodeError(inner, context))), (encoded) => ({
+            name: error.name,
+            message,
+            ...Object.fromEntries(nested.map(([field], i) => [field, encoded[i]])),
+        })));
+    }
+    /** What `encodeError()` encoded, decoded; an error stored as it is comes back as it is. */
+    async decodeError(error, context) {
+        if (!isEncodedPayload(error?.message)) {
+            return error;
+        }
+        const { message, stack } = (await this.decode(error.message, context));
+        const nested = await Promise.all(nestedErrors(error).map(async ([field, inner]) => [field, await this.decodeError(inner, context)]));
+        return { name: error.name, message, ...(stack === undefined ? {} : { stack }), ...Object.fromEntries(nested) };
+    }
+}
+/**
+ * Whether a stored value is an encoded payload, in the family's envelope, rather than one stored as it is: a string
+ * starting with `$wf1:`. For stores that skip decoding what needs none.
+ *
+ * ```ts
+ * const payload = isEncodedPayload(row.data) ? await codecs.decode(row.data, context) : row.data;
+ * ```
+ */
+export function isEncodedPayload(value) {
+    return typeof value === 'string' && value.startsWith(ENVELOPE);
+}
+/** The fields of `error` that hold nested errors (workflows' `compensation`), in their order. */
+function nestedErrors(error) {
+    return Object.entries(error).filter((entry) => entry[0] !== 'name' && entry[0] !== 'message' && entry[0] !== 'stack' && isSerializedError(entry[1]));
+}
+/** The messages of `error` and of its nested errors. */
+function messages(error) {
+    return [error.message, ...nestedErrors(error).flatMap(([, inner]) => messages(inner))];
+}
+function isSerializedError(value) {
+    return typeof value === 'object' && value !== null && typeof value.name === 'string' && typeof value.message === 'string';
+}
+/** Every value, synchronously when none is a promise. */
+function all(values) {
+    return values.reduce((done, value) => andThen(done, (list) => andThen(value, (item) => [...list, item])), []);
+}

package/dist/core/index.d.ts

@@ -0,0 +1,16 @@
+export { ManualClock, parseDuration, systemClock, type Duration } from './time/index.js';
+export type { Clock } from './interfaces/index.js';
+export { backoffDelay, nextRetry, resolveRetry, type RetryDecision } from './retries/index.js';
+export type { BackoffSettings, ResolvedBackoff, ResolvedRetry, RetrySettings } from './interfaces/index.js';
+export { AesGcmPayloadCodec, isEncodedPayload, PayloadCodecs, type AesGcmPayloadCodecOptions, type PayloadCodecsOptions } from './codecs/index.js';
+export type { PayloadCodec, PayloadContext, SerializedError } from './interfaces/index.js';
+export { assertPriority, MAX_PRIORITY, rateWindowRoom, resolveConcurrency, resolveRateLimit, takeRateWindow } from './limits/index.js';
+export type { ConcurrencyLimit, RateLimit, RateWindow, RateWindowState, ResolvedConcurrency, ResolvedRateLimit } from './interfaces/index.js';
+export { ResultWaiter } from './results/index.js';
+export type { ResultOutcome, ResultWaiterOptions, ResultWaitOptions } from './interfaces/index.js';
+export { assertScheduleId, nextOccurrences, occurrenceId, parseSchedule } from './scheduling/index.js';
+export type { ScheduleMissed, ScheduleOccurrence, ScheduleOptions, ScheduleOverlap, ScheduleSpec, ScheduleTiming } from './interfaces/index.js';
+export { InMemoryScheduleStore, Scheduler, type ScheduleFields } from './scheduling/index.js';
+export type { DeclaredSchedule, DueOccurrence, ScheduleClaimRequest, ScheduleProduction, ScheduleQuery, ScheduleRecord, ScheduleSave, ScheduleSkip, ScheduleStore, ScheduleWrite, SchedulerLabels, SchedulerOptions, } from './interfaces/index.js';
+export { LeasedWorker } from './workers/index.js';
+export type { LeasedRun, LeasedWorkerOptions, LeaseRequest } from './interfaces/index.js';

package/dist/core/index.js

@@ -0,0 +1,21 @@
+// The `@nestjs/workflows/core` entry: the engine's storage-agnostic pieces, for building packages on them (a queue,
+// say) so they behave and read like workflows. Applications import `@nestjs/workflows`; nothing here is needed to
+// write or run workflows. Nothing here imports a driver.
+// Time: durations, and the clock every timestamp comes from
+export { ManualClock, parseDuration, systemClock } from './time/index.js';
+// Retries: the family's retry settings, resolved, and whether and when to retry after a failure
+export { backoffDelay, nextRetry, resolveRetry } from './retries/index.js';
+// Payloads: codecs, the AES-GCM one, and the family's envelope that stores what they encode
+export { AesGcmPayloadCodec, isEncodedPayload, PayloadCodecs } from './codecs/index.js';
+// Limits: concurrency and rate limits, priorities, and rate-limit window arithmetic (the claims themselves are a store's)
+export { assertPriority, MAX_PRIORITY, rateWindowRoom, resolveConcurrency, resolveRateLimit, takeRateWindow } from './limits/index.js';
+// Results: waiting for an outcome, settled at once by this process or read from the store with a backoff
+export { ResultWaiter } from './results/index.js';
+// Scheduling: schedule specs (cron with seconds, every, rrule, time zones, bounds, missed and overlap policies),
+// their occurrences, and the ids of the runs they start
+export { assertScheduleId, nextOccurrences, occurrenceId, parseSchedule } from './scheduling/index.js';
+// Scheduling: the engine (one run per occurrence, declared schedules in step with the code) and the store it runs
+// on, which `scheduleStoreContract()` from `@nestjs/workflows/testing` checks
+export { InMemoryScheduleStore, Scheduler } from './scheduling/index.js';
+// Workers: a claim-execute loop under leases, renewed on a heartbeat, drained at shutdown
+export { LeasedWorker } from './workers/index.js';

package/dist/core/interfaces/clock.interface.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Where every timestamp comes from (deadlines, retry times, lease expiry, schedule occurrences), so tests can move
+ * time without fake timers: `systemClock`, or a `ManualClock`.
+ *
+ * ```ts
+ * class Deadline {
+ *   constructor(private readonly clock: Clock = systemClock) {}
+ *
+ *   passed(at: number): boolean {
+ *     return this.clock.now() >= at;
+ *   }
+ * }
+ * ```
+ */
+export interface Clock {
+    /** Epoch milliseconds. */
+    now(): number;
+}

package/dist/core/interfaces/clock.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/index.d.ts

@@ -0,0 +1,9 @@
+export * from './clock.interface.js';
+export * from './leased-worker-options.interface.js';
+export * from './limits.interface.js';
+export * from './payload-codec.interface.js';
+export * from './result-waiter-options.interface.js';
+export * from './retry-settings.interface.js';
+export * from './schedule-store.interface.js';
+export * from './schedule.interface.js';
+export * from './scheduler-options.interface.js';

package/dist/core/interfaces/index.js

@@ -0,0 +1,9 @@
+export * from './clock.interface.js';
+export * from './leased-worker-options.interface.js';
+export * from './limits.interface.js';
+export * from './payload-codec.interface.js';
+export * from './result-waiter-options.interface.js';
+export * from './retry-settings.interface.js';
+export * from './schedule-store.interface.js';
+export * from './schedule.interface.js';
+export * from './scheduler-options.interface.js';

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

@@ -0,0 +1,94 @@
+import type { Duration } from '../time/duration.js';
+import type { Clock } from './clock.interface.js';
+/**
+ * The lease `LeasedWorker` asks its `claim` to take: every item the claim returns is leased to `owner` under `token`
+ * until `until`.
+ *
+ * ```ts
+ * claim: ({ owner, token, now, until }, limit) => store.claim({ owner, token, now, leaseUntil: until, limit }),
+ * ```
+ */
+export interface LeaseRequest {
+    /** The worker's id (`LeasedWorker.owner`), for the store's `leaseOwner`. */
+    owner: string;
+    /** A new token for this claim: the store fences every write under the lease with it. */
+    token: string;
+    /** The clock's time of the claim. */
+    now: number;
+    /** When the lease ends unless renewed: `now` plus the lease duration. */
+    until: number;
+}
+/**
+ * One claimed item's run, which `execute` receives: its `signal` aborts when the lease is lost (a renewal found it
+ * gone) or the worker shuts down, and the worker renews its lease every `heartbeatInterval` until `execute` settles.
+ *
+ * ```ts
+ * execute: async (job, run) => {
+ *   const result = await handler(job.data, { signal: run.signal });
+ *   if (!(await store.complete(job.id, job.token, result))) {
+ *     run.loseLease(); // another worker took the job over
+ *   }
+ * },
+ * ```
+ */
+export interface LeasedRun {
+    /** Aborts when the lease is lost or the worker shuts down: `leaseLost` tells which. */
+    readonly signal: AbortSignal;
+    /** The lease is gone: another worker may run the item now, so write nothing more under it. */
+    readonly leaseLost: boolean;
+    /** The worker stopped waiting for this run at shutdown (`shutdownTimeout`): it no longer renews, and the run should write nothing more. */
+    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.
+     */
+    renew(): Promise<boolean>;
+    /** Marks the lease lost, when a fenced write found it gone: aborts `signal` and stops renewing. */
+    loseLease(): void;
+}
+/**
+ * What `LeasedWorker` takes: how to claim, renew and execute items (the store's side), and the loop's settings, which
+ * default to workflows' (10 at once, a poll a second, 30 s leases renewed every third of that, a 10 s drain).
+ *
+ * ```ts
+ * const worker = new LeasedWorker<Job>({
+ *   concurrency: 5,
+ *   claim: (lease, limit) => store.claimJobs(lease, limit),
+ *   renew: (job, until) => store.renewJob(job.id, job.token, until),
+ *   execute: (job, run) => runJob(job, run),
+ * });
+ * ```
+ */
+export interface LeasedWorkerOptions<T> {
+    /** Leases up to `limit` due items under `lease`; `[]` when none is due. */
+    claim(lease: LeaseRequest, limit: number): Promise<T[]>;
+    /** Extends the lease of `item` to `until`; `false` when it is gone (its token isn't the item's any more). */
+    renew(item: T, until: number): Promise<boolean>;
+    /** Runs one claimed item. It may find `run.signal` already aborted (claimed as the worker shut down): hand it back. */
+    execute(item: T, run: LeasedRun): Promise<void>;
+    /**
+     * Called before claiming, in each poll (at most every `produceInterval`) and each round of `drain()`: work that makes
+     * items due (a schedule's occurrences). Resolves to how many it made: `drain()` goes on while it makes some.
+     */
+    produce?(): Promise<number>;
+    /** Names the worker in errors about its options, as their prefix: `worker.concurrency`. Default `'worker'`. */
+    name?: string;
+    /** The worker's id, shown as the lease owner. Default `hostname:pid:random`. */
+    owner?: string;
+    /** Items executed at once by this worker. Default 10. */
+    concurrency?: number;
+    /** How often to look for due items when not kicked. Default `'1s'`. */
+    pollInterval?: Duration;
+    /** How long a claim is valid without a renewal. Default `'30s'`. */
+    leaseDuration?: Duration;
+    /** How often a running item's lease is renewed. Default a third of `leaseDuration`. */
+    heartbeatInterval?: Duration;
+    /** How long `shutdown()` waits for running items before detaching them. Default `'10s'`. */
+    shutdownTimeout?: Duration;
+    /** The least time between two `produce()` calls of the polling loop (wall-clock). Default 0: every poll. */
+    produceInterval?: Duration;
+    /** Where lease times come from. Default `systemClock`. */
+    clock?: Clock;
+    /** Where the loop reports what failed; it carries on. Default: logged. `drain()` throws instead. */
+    onError?(error: unknown, stage: 'claim' | 'produce' | 'execute'): void;
+}

package/dist/core/interfaces/leased-worker-options.interface.js

@@ -0,0 +1 @@
+export {};