@nestjs/workflows 0.0.1

package/dist/core/interfaces/scheduler-options.interface.d.ts

@@ -0,0 +1,152 @@
+import type { LoggerService } from '@nestjs/common';
+import type { PayloadCodecs } from '../codecs/payload-codecs.js';
+import type { Clock } from './clock.interface.js';
+import type { PayloadContext } from './payload-codec.interface.js';
+import type { ScheduleOccurrence, ScheduleSpec } from './schedule.interface.js';
+import type { ScheduleRecord, ScheduleStore } from './schedule-store.interface.js';
+/**
+ * A schedule the code declares (a decorator's, a queue definition's), which the `Scheduler` keeps in step with the
+ * store at startup and every minute, also through a rolling deploy.
+ *
+ * ```ts
+ * const declared: DeclaredSchedule = {
+ *   id: 'weekly-digest',
+ *   target: 'emails',
+ *   version: 1,
+ *   spec: parseSchedule({ cron: '0 0 8 * * MON', tz: 'Europe/Warsaw' }),
+ *   payload: ({ at }: ScheduleOccurrence) => ({ week: isoWeek(new Date(at)) }),
+ * };
+ * ```
+ */
+export interface DeclaredSchedule<S extends ScheduleSpec = ScheduleSpec> {
+    /** Unique across the schedules of the store. */
+    id: string;
+    /** What it starts runs of. */
+    target: string;
+    /**
+     * The version of the code that declares it, such as the workflow's highest registered version (a package without
+     * versions passes 1): a process of older code leaves a newer version's declaration as it is while a process of that
+     * code confirms it.
+     */
+    version: number;
+    spec: S;
+    /** What each run gets: a JSON value, stored, or a function of the occurrence, which `fire` calls (never stored). */
+    payload: unknown | ((occurrence: ScheduleOccurrence) => unknown);
+}
+/**
+ * An occurrence the `Scheduler` asks its `fire` to start: the schedule as stored (its payload decoded), its spec, the
+ * code's declaration of it (for a declared schedule whose payload is a function), and the run's id, which is
+ * `occurrenceId(schedule.id, at)`: starting a second run with the same id must do nothing.
+ *
+ * ```ts
+ * fire: async ({ schedule, declared, id, at }) => {
+ *   const data = typeof declared?.payload === 'function' ? declared.payload({ id: schedule.id, at }) : schedule.payload;
+ *   const { created } = await jobs.add(schedule.target, data, { id });
+ *   return { created };
+ * },
+ * ```
+ */
+export interface DueOccurrence<S extends ScheduleSpec = ScheduleSpec> {
+    schedule: ScheduleRecord;
+    spec: S;
+    declared?: DeclaredSchedule<S>;
+    /** The run's id: `occurrenceId(schedule.id, at)`. */
+    id: string;
+    /** When the occurrence was due. */
+    at: number;
+    /** The production's time. */
+    now: number;
+}
+/**
+ * Occurrences a production passed over: missed while no worker was up (`'missed'`, see `missed`), or due while a run
+ * the schedule started was unfinished (`'overlap'`).
+ *
+ * ```ts
+ * skipped: (schedule, { reason, from, to }) => events.emit({ type: 'schedule-skipped', id: schedule.id, reason, from, to }),
+ * ```
+ */
+export interface ScheduleSkip {
+    reason: 'missed' | 'overlap';
+    /** The first occurrence it passed over (epoch milliseconds). */
+    from: number;
+    /** The last one. */
+    to: number;
+}
+/**
+ * What one `Scheduler.produce()` did: how many runs it started, and the runs it cancelled (`overlap:
+ * 'cancel-previous'`), which a worker running them in this process should stop at once.
+ *
+ * ```ts
+ * const { started, cancelled } = await scheduler.produce(worker.owner, worker.leaseMs);
+ * ```
+ */
+export interface ScheduleProduction {
+    started: number;
+    cancelled: string[];
+}
+/**
+ * What the `Scheduler` takes: its store, and the package's side of schedules (what a run is, how to start, list and
+ * cancel one), which it plugs in as functions.
+ *
+ * ```ts
+ * const scheduler = new Scheduler({
+ *   store: new InMemoryScheduleStore(),
+ *   targets: () => ['emails'],
+ *   declared: () => new Map([[digest.id, digest]]),
+ *   fire: ({ schedule, id }) => jobs.add(schedule.target, schedule.payload, { id }),
+ *   running: (schedule) => jobs.unfinished({ scheduleId: schedule.id }),
+ *   cancel: (id, reason) => jobs.cancel(id, reason),
+ * });
+ * ```
+ */
+export interface SchedulerOptions<S extends ScheduleSpec = ScheduleSpec> {
+    /** Where the schedules live, their payloads as the store keeps them (the scheduler encodes them with `codecs`). */
+    store: ScheduleStore;
+    /** The targets this process runs: it produces only their schedules. None: it neither produces nor reconciles. */
+    targets(): string[];
+    /** The schedules this process's code declares, by id. Default: none. */
+    declared?(): ReadonlyMap<string, DeclaredSchedule<S>>;
+    /**
+     * Starts the run of an occurrence with the id it is given, or finds the one that has it: `{ created }`. `null` skips
+     * the occurrence for good (its payload couldn't be computed: log why); throwing (the store refused it) retries it,
+     * backing off from a second to a minute, ten times in all.
+     */
+    fire(occurrence: DueOccurrence<S>): Promise<{
+        created: boolean;
+    } | null>;
+    /** The ids of the unfinished runs the schedule started, for its `overlap`. */
+    running(schedule: ScheduleRecord): Promise<string[]>;
+    /** Cancels a run (`overlap: 'cancel-previous'`): whether it was accepted. */
+    cancel(run: string, reason: string, now: number): Promise<boolean>;
+    /** Called after a production that passed over occurrences. */
+    skipped?(schedule: ScheduleRecord, skip: ScheduleSkip, now: number): void;
+    /** Where times come from. Default `systemClock`. */
+    clock?: Clock;
+    /** Encodes the schedules' payloads (`PayloadCodecs` of the package's codecs). Default: stored as they are. */
+    codecs?: PayloadCodecs;
+    /** The context a schedule's payload is encoded with. Default `{ field: 'payload', schedule: id }`. */
+    payloadContext?(schedule: string): PayloadContext;
+    /** The error a save that keeps losing races rejects with. Default: an `Error`. */
+    conflictError?(message: string): Error;
+    /** How its logs name things, such as `{ target: (name) => \`workflow "${name}"\`, targets: 'workflows' }`. */
+    labels?: SchedulerLabels;
+    /** Where it logs what it did (a deletion, a takeover) and what failed. Default: a Nest `Logger`. */
+    logger?: Pick<LoggerService, 'log' | 'warn' | 'error'>;
+}
+/**
+ * How the `Scheduler`'s logs name a package's things.
+ *
+ * ```ts
+ * const labels: SchedulerLabels = { target: (name) => `queue "${name}"`, targets: 'queues', payload: 'data', upsert: 'schedules.upsert()' };
+ * ```
+ */
+export interface SchedulerLabels {
+    /** A target, such as `workflow "digest"`. Default `target "digest"`. */
+    target?(name: string): string;
+    /** The targets, as what declares schedules, such as `'workflows'`. Default `'targets'`. */
+    targets?: string;
+    /** A schedule's payload, such as `'input'`. Default `'payload'`. */
+    payload?: string;
+    /** The call that saves a schedule at runtime, such as `'WorkflowSchedules.upsert()'`. Default `'upsert()'`. */
+    upsert?: string;
+}

package/dist/core/interfaces/scheduler-options.interface.js

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

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

@@ -0,0 +1 @@
+export * from './limits.js';

package/dist/core/limits/index.js

@@ -0,0 +1 @@
+export * from './limits.js';

package/dist/core/limits/limits.d.ts

@@ -0,0 +1,61 @@
+import type { ConcurrencyLimit, RateLimit, RateWindowState, ResolvedConcurrency, ResolvedRateLimit } from '../interfaces/limits.interface.js';
+/**
+ * The highest priority (the last to run): BullMQ's, which the family shares. Priorities are integers from 1 (first)
+ * to `MAX_PRIORITY`; lower runs first, and `0` (none given) runs before every other.
+ *
+ * ```ts
+ * const priority = options.priority ?? 0; // 0..MAX_PRIORITY
+ * ```
+ */
+export declare const MAX_PRIORITY = 2097151;
+/**
+ * Throws a `TypeError` that names `owner` unless `priority` is a priority: an integer from 0 (none) to
+ * `MAX_PRIORITY`.
+ *
+ * ```ts
+ * assertPriority(options.priority, 'add()'); // add(): invalid priority 1.5. Use an integer from 1 (first) to 2097151.
+ * ```
+ */
+export declare function assertPriority(priority: unknown, owner: string): asserts priority is number;
+/** Whether `value` is an integer from 0 (none) to `MAX_PRIORITY`. */
+export declare function isPriority(value: unknown): value is number;
+/**
+ * Checks concurrency limits (one, or one without a key and one with) and resolves them. Throws a `TypeError` that
+ * names `owner`, such as `queue "emails"`, for anything else.
+ *
+ * ```ts
+ * resolveConcurrency('queue "emails"', [{ limit: 20 }, { limit: 1, key: (email) => email.to }]);
+ * // { limit: 20, perKey: 1, key: (email) => email.to }
+ * ```
+ */
+export declare function resolveConcurrency<I = any>(owner: string, concurrency: ConcurrencyLimit<I> | ConcurrencyLimit<I>[]): ResolvedConcurrency<I>;
+/**
+ * Checks rate limits (one, or one without a key and one with) and resolves them, durations in milliseconds. Throws a
+ * `TypeError` that names `owner` for anything else.
+ *
+ * ```ts
+ * resolveRateLimit('queue "emails"', { max: 100, duration: '1s' });
+ * // { limit: { max: 100, duration: 1_000 }, perKey: null }
+ * ```
+ */
+export declare function resolveRateLimit<I = any>(owner: string, rateLimit: RateLimit<I> | RateLimit<I>[]): ResolvedRateLimit<I>;
+/**
+ * How many more starts a window of `max` takes at `now`: all of `max` when it ended (`windowEnd <= now`) or never
+ * opened.
+ *
+ * ```ts
+ * rateWindowRoom({ windowEnd: 60_000, count: 7 }, 10, 30_000); // 3
+ * rateWindowRoom({ windowEnd: 60_000, count: 7 }, 10, 60_000); // 10: it ended
+ * ```
+ */
+export declare function rateWindowRoom(window: RateWindowState | null | undefined, max: number, now: number): number;
+/**
+ * The window after `count` more starts at `now`: the open one, counted up, or, when it ended or never opened, a new
+ * one from `now` for `duration` milliseconds. Take only what `rateWindowRoom()` said fits, under the store's lock.
+ *
+ * ```ts
+ * takeRateWindow(undefined, 60_000, 1_000); // { windowEnd: 61_000, count: 1 }
+ * takeRateWindow({ windowEnd: 61_000, count: 1 }, 60_000, 2_000, 2); // { windowEnd: 61_000, count: 3 }
+ * ```
+ */
+export declare function takeRateWindow(window: RateWindowState | null | undefined, duration: number, now: number, count?: number): RateWindowState;

package/dist/core/limits/limits.js

@@ -0,0 +1,130 @@
+import { parseDuration } from '../time/duration.js';
+/**
+ * The highest priority (the last to run): BullMQ's, which the family shares. Priorities are integers from 1 (first)
+ * to `MAX_PRIORITY`; lower runs first, and `0` (none given) runs before every other.
+ *
+ * ```ts
+ * const priority = options.priority ?? 0; // 0..MAX_PRIORITY
+ * ```
+ */
+export const MAX_PRIORITY = 2_097_151;
+/**
+ * Throws a `TypeError` that names `owner` unless `priority` is a priority: an integer from 0 (none) to
+ * `MAX_PRIORITY`.
+ *
+ * ```ts
+ * assertPriority(options.priority, 'add()'); // add(): invalid priority 1.5. Use an integer from 1 (first) to 2097151.
+ * ```
+ */
+export function assertPriority(priority, owner) {
+    if (!isPriority(priority)) {
+        throw new TypeError(`${owner}: invalid priority ${JSON.stringify(priority)}. Use an integer from 1 (first) to ${MAX_PRIORITY}.`);
+    }
+}
+/** Whether `value` is an integer from 0 (none) to `MAX_PRIORITY`. */
+export function isPriority(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= MAX_PRIORITY;
+}
+/**
+ * Checks concurrency limits (one, or one without a key and one with) and resolves them. Throws a `TypeError` that
+ * names `owner`, such as `queue "emails"`, for anything else.
+ *
+ * ```ts
+ * resolveConcurrency('queue "emails"', [{ limit: 20 }, { limit: 1, key: (email) => email.to }]);
+ * // { limit: 20, perKey: 1, key: (email) => email.to }
+ * ```
+ */
+export function resolveConcurrency(owner, concurrency) {
+    const limits = Array.isArray(concurrency) ? concurrency : [concurrency];
+    if (limits.length === 0 || limits.length > 2) {
+        throw new TypeError(`${capitalized(owner)} has ${limits.length} concurrency limits. Give it one, or two: one without a key and one with.`);
+    }
+    const resolved = { limit: null, perKey: null };
+    for (const { limit, key } of limits) {
+        if (!Number.isSafeInteger(limit) || limit < 1) {
+            throw new TypeError(`Invalid concurrency limit ${JSON.stringify(limit)} for ${owner}. Use a positive integer.`);
+        }
+        if (key !== undefined && typeof key !== 'function') {
+            throw new TypeError(`Invalid concurrency key for ${owner}. Use a function of the input, such as (order) => order.customerId.`);
+        }
+        const slot = key === undefined ? 'limit' : 'perKey';
+        if (resolved[slot] !== null) {
+            throw new TypeError(`${capitalized(owner)} has two concurrency limits ${key === undefined ? 'without' : 'with'} a key. Give it at most one of each.`);
+        }
+        resolved[slot] = limit;
+        if (key) {
+            resolved.key = key;
+        }
+    }
+    return resolved;
+}
+/**
+ * Checks rate limits (one, or one without a key and one with) and resolves them, durations in milliseconds. Throws a
+ * `TypeError` that names `owner` for anything else.
+ *
+ * ```ts
+ * resolveRateLimit('queue "emails"', { max: 100, duration: '1s' });
+ * // { limit: { max: 100, duration: 1_000 }, perKey: null }
+ * ```
+ */
+export function resolveRateLimit(owner, rateLimit) {
+    const limits = Array.isArray(rateLimit) ? rateLimit : [rateLimit];
+    if (limits.length === 0 || limits.length > 2) {
+        throw new TypeError(`${capitalized(owner)} has ${limits.length} rate limits. Give it one, or two: one without a key and one with.`);
+    }
+    const resolved = { limit: null, perKey: null };
+    for (const { max, duration, key } of limits) {
+        if (!Number.isSafeInteger(max) || max < 1) {
+            throw new TypeError(`Invalid rate limit max ${JSON.stringify(max)} for ${owner}. Use a positive integer.`);
+        }
+        let ms;
+        try {
+            ms = parseDuration(duration);
+        }
+        catch {
+            ms = 0;
+        }
+        if (!(ms > 0)) {
+            throw new TypeError(`Invalid rate limit duration ${JSON.stringify(duration)} for ${owner}. Use a positive duration, such as "1m".`);
+        }
+        if (key !== undefined && typeof key !== 'function') {
+            throw new TypeError(`Invalid rate limit key for ${owner}. Use a function of the input, such as (order) => order.customerId.`);
+        }
+        const slot = key === undefined ? 'limit' : 'perKey';
+        if (resolved[slot] !== null) {
+            throw new TypeError(`${capitalized(owner)} has two rate limits ${key === undefined ? 'without' : 'with'} a key. Give it at most one of each.`);
+        }
+        resolved[slot] = { max, duration: ms };
+        if (key) {
+            resolved.key = key;
+        }
+    }
+    return resolved;
+}
+/**
+ * How many more starts a window of `max` takes at `now`: all of `max` when it ended (`windowEnd <= now`) or never
+ * opened.
+ *
+ * ```ts
+ * rateWindowRoom({ windowEnd: 60_000, count: 7 }, 10, 30_000); // 3
+ * rateWindowRoom({ windowEnd: 60_000, count: 7 }, 10, 60_000); // 10: it ended
+ * ```
+ */
+export function rateWindowRoom(window, max, now) {
+    return window && window.windowEnd > now ? max - window.count : max;
+}
+/**
+ * The window after `count` more starts at `now`: the open one, counted up, or, when it ended or never opened, a new
+ * one from `now` for `duration` milliseconds. Take only what `rateWindowRoom()` said fits, under the store's lock.
+ *
+ * ```ts
+ * takeRateWindow(undefined, 60_000, 1_000); // { windowEnd: 61_000, count: 1 }
+ * takeRateWindow({ windowEnd: 61_000, count: 1 }, 60_000, 2_000, 2); // { windowEnd: 61_000, count: 3 }
+ * ```
+ */
+export function takeRateWindow(window, duration, now, count = 1) {
+    return window && window.windowEnd > now ? { windowEnd: window.windowEnd, count: window.count + count } : { windowEnd: now + duration, count };
+}
+function capitalized(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}

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

@@ -0,0 +1 @@
+export * from './result-waiter.js';

package/dist/core/results/index.js

@@ -0,0 +1 @@
+export * from './result-waiter.js';

package/dist/core/results/result-waiter.d.ts

@@ -0,0 +1,54 @@
+import type { ResultOutcome, ResultWaiterOptions, ResultWaitOptions } from '../interfaces/result-waiter-options.interface.js';
+/**
+ * Waits for the outcome of something another part of the application runs (a workflow instance, a job): at once
+ * when this process ends it and says so (`settle()`), else by reading the store with a backoff (every 25 ms at
+ * first, doubling up to every second), which sees what other processes ended. A wait rejects past its `timeout`
+ * (the work goes on), when its `signal` aborts, and as soon as the waiter closes, without reading the store again:
+ * close it in `beforeApplicationShutdown`, which Nest runs after `onModuleDestroy` (where workers drain, so work that
+ * ends during the drain still answers) and before the HTTP server closes.
+ *
+ * ```ts
+ * @Injectable()
+ * export class JobResults implements BeforeApplicationShutdown {
+ *   private readonly results = new ResultWaiter<unknown>({ read: (id) => this.readOutcome(id) });
+ *
+ *   constructor(events: JobEvents) {
+ *     events.completed$.subscribe((job) => this.results.settle(job.id, { value: job.result }));
+ *   }
+ *
+ *   result(id: string, options?: ResultWaitOptions) {
+ *     return this.results.wait(id, options);
+ *   }
+ *
+ *   beforeApplicationShutdown() {
+ *     return this.results.close();
+ *   }
+ * }
+ * ```
+ */
+export declare class ResultWaiter<T = unknown> {
+    private readonly options;
+    private readonly waits;
+    private readonly closing;
+    constructor(options: ResultWaiterOptions<T>);
+    /** Whether `close()` was called: every wait since rejects at once. */
+    get closed(): boolean;
+    /**
+     * Resolves with the value `id` ended with, or rejects with its outcome's error; past `timeout` with the
+     * `timeoutError`, when `signal` aborts with its reason, and once the waiter closed with the `closedError`.
+     */
+    wait(id: string, options?: ResultWaitOptions): Promise<T>;
+    /**
+     * Settles the waits for `id` with its outcome at once, without a read, and a read in flight gives way to it: for
+     * what this process saw end. A function is only called when something waits for `id`. The first outcome wins.
+     */
+    settle(id: string, outcome: ResultOutcome<T> | (() => ResultOutcome<T>)): void;
+    /**
+     * Ends every wait (they reject with the `closedError`), and makes later ones reject at once. Resolves after a
+     * macrotask, so the callers that stopped waiting have answered by then: Node's `server.close()` closes only the
+     * connections idle at that moment, and one that answers later stays open until its keep-alive timeout.
+     */
+    close(): Promise<void>;
+    private add;
+    private remove;
+}

package/dist/core/results/result-waiter.js

@@ -0,0 +1,140 @@
+import { setImmediate as nextMacrotask } from 'node:timers/promises';
+import { parseDuration } from '../time/duration.js';
+/** What a read in flight gives way to: an outcome settled locally, or the waiter closing. */
+const SETTLED = Symbol('settled');
+/**
+ * Waits for the outcome of something another part of the application runs (a workflow instance, a job): at once
+ * when this process ends it and says so (`settle()`), else by reading the store with a backoff (every 25 ms at
+ * first, doubling up to every second), which sees what other processes ended. A wait rejects past its `timeout`
+ * (the work goes on), when its `signal` aborts, and as soon as the waiter closes, without reading the store again:
+ * close it in `beforeApplicationShutdown`, which Nest runs after `onModuleDestroy` (where workers drain, so work that
+ * ends during the drain still answers) and before the HTTP server closes.
+ *
+ * ```ts
+ * @Injectable()
+ * export class JobResults implements BeforeApplicationShutdown {
+ *   private readonly results = new ResultWaiter<unknown>({ read: (id) => this.readOutcome(id) });
+ *
+ *   constructor(events: JobEvents) {
+ *     events.completed$.subscribe((job) => this.results.settle(job.id, { value: job.result }));
+ *   }
+ *
+ *   result(id: string, options?: ResultWaitOptions) {
+ *     return this.results.wait(id, options);
+ *   }
+ *
+ *   beforeApplicationShutdown() {
+ *     return this.results.close();
+ *   }
+ * }
+ * ```
+ */
+export class ResultWaiter {
+    constructor(options) {
+        this.options = options;
+        this.waits = new Map();
+        this.closing = new AbortController();
+    }
+    /** Whether `close()` was called: every wait since rejects at once. */
+    get closed() {
+        return this.closing.signal.aborted;
+    }
+    /**
+     * Resolves with the value `id` ended with, or rejects with its outcome's error; past `timeout` with the
+     * `timeoutError`, when `signal` aborts with its reason, and once the waiter closed with the `closedError`.
+     */
+    async wait(id, options = {}) {
+        const timeoutMs = options.timeout === undefined ? Infinity : parseDuration(options.timeout);
+        const deadline = performance.now() + timeoutMs;
+        options.signal?.throwIfAborted();
+        let settle;
+        const settled = new Promise((resolve) => (settle = () => resolve(SETTLED)));
+        const wait = { closed: this.closed, settle };
+        const nudge = () => wait.wake?.();
+        const close = () => {
+            wait.closed = true;
+            settle();
+            nudge();
+        };
+        this.add(id, wait);
+        this.closing.signal.addEventListener('abort', close);
+        options.signal?.addEventListener('abort', nudge);
+        try {
+            for (let delay = 25;; delay = Math.min(delay * 2, 1_000)) {
+                const read = wait.outcome || wait.closed ? SETTLED : await Promise.race([this.options.read(id), settled]);
+                if (wait.outcome) {
+                    return unwrap(wait.outcome);
+                }
+                if (read === SETTLED) {
+                    throw this.options.closedError?.(id) ?? new Error(`The waiter closed while waiting for the result of "${id}".`);
+                }
+                if (read) {
+                    return unwrap(read);
+                }
+                options.signal?.throwIfAborted();
+                const remaining = deadline - performance.now();
+                if (remaining <= 0) {
+                    throw this.options.timeoutError?.(id, timeoutMs) ?? new Error(`"${id}" didn't end within ${timeoutMs}ms.`);
+                }
+                await new Promise((resolve) => {
+                    const timer = setTimeout(resolve, Math.min(delay, remaining));
+                    wait.wake = () => {
+                        clearTimeout(timer);
+                        resolve();
+                    };
+                });
+                wait.wake = undefined;
+            }
+        }
+        finally {
+            this.remove(id, wait);
+            this.closing.signal.removeEventListener('abort', close);
+            options.signal?.removeEventListener('abort', nudge);
+        }
+    }
+    /**
+     * Settles the waits for `id` with its outcome at once, without a read, and a read in flight gives way to it: for
+     * what this process saw end. A function is only called when something waits for `id`. The first outcome wins.
+     */
+    settle(id, outcome) {
+        const waits = this.waits.get(id);
+        if (!waits) {
+            return;
+        }
+        const settled = typeof outcome === 'function' ? outcome() : outcome;
+        for (const wait of waits) {
+            wait.outcome ??= settled;
+            wait.settle();
+            wait.wake?.();
+        }
+    }
+    /**
+     * Ends every wait (they reject with the `closedError`), and makes later ones reject at once. Resolves after a
+     * macrotask, so the callers that stopped waiting have answered by then: Node's `server.close()` closes only the
+     * connections idle at that moment, and one that answers later stays open until its keep-alive timeout.
+     */
+    async close() {
+        this.closing.abort();
+        await nextMacrotask();
+    }
+    add(id, wait) {
+        let waits = this.waits.get(id);
+        if (!waits) {
+            this.waits.set(id, (waits = new Set()));
+        }
+        waits.add(wait);
+    }
+    remove(id, wait) {
+        const waits = this.waits.get(id);
+        waits?.delete(wait);
+        if (waits?.size === 0) {
+            this.waits.delete(id);
+        }
+    }
+}
+function unwrap(outcome) {
+    if ('error' in outcome) {
+        throw outcome.error;
+    }
+    return outcome.value;
+}

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

@@ -0,0 +1 @@
+export * from './retry.js';

package/dist/core/retries/index.js

@@ -0,0 +1 @@
+export * from './retry.js';

package/dist/core/retries/retry.d.ts

@@ -0,0 +1,60 @@
+import type { ResolvedBackoff, ResolvedRetry, RetrySettings } from '../interfaces/retry-settings.interface.js';
+/**
+ * What `nextRetry()` decided after a failed attempt: retry after `delay` milliseconds, or give up because the
+ * attempts are spent (`'exhausted'`), `retryIf` returned false (`'refused'`), or `retryIf` or a backoff function threw
+ * (`'threw'`, with what it threw: record it as the failure, since retrying on would hide the bug).
+ *
+ * ```ts
+ * const next = nextRetry(policy, attempt, error);
+ * if (next.retry) {
+ *   await job.retryAt(clock.now() + next.delay);
+ * } else {
+ *   await job.fail(next.reason === 'threw' ? next.error : error);
+ * }
+ * ```
+ */
+export type RetryDecision = {
+    retry: true;
+    delay: number;
+} | {
+    retry: false;
+    reason: 'exhausted' | 'refused';
+} | {
+    retry: false;
+    reason: 'threw';
+    error: unknown;
+};
+/**
+ * Checks `retry` (a count, `false` or `RetrySettings`) and resolves it over `base`, field by field: `undefined` is
+ * `base`, `false` one attempt, a number the attempts. `base` defaults to the family's default: 3 attempts, 1s doubling
+ * up to 5m, no jitter. Throws a `TypeError` for invalid settings, so they fail where they are given rather than at the
+ * first retry.
+ *
+ * ```ts
+ * const defaults = resolveRetry(moduleOptions.retry);
+ * const policy = resolveRetry(jobOptions.retry, defaults);
+ * ```
+ */
+export declare function resolveRetry(retry: number | false | RetrySettings | undefined, base?: ResolvedRetry): ResolvedRetry;
+/**
+ * The wait (ms) after the failed `attempt` (1-based): `delay * factor^(attempt - 1)`, capped at `maxDelay`, then
+ * randomized by `jitter` (`'full'`: from 0 to the wait, `'equal'`: from half of it to all of it). `random` returns a
+ * number in `[0, 1)`, as `Math.random()` (the default) does.
+ *
+ * ```ts
+ * backoffDelay({ delay: 1_000, factor: 2, maxDelay: 60_000, jitter: 'none' }, 4); // 8_000
+ * ```
+ */
+export declare function backoffDelay(backoff: ResolvedBackoff, attempt: number, random?: () => number): number;
+/**
+ * Whether, and when, to retry after `attempt` (1-based) failed with `error`: not once the policy's attempts are
+ * spent, nor when `retryIf` returns false; otherwise after the backoff's wait. A `retryIf` or backoff function that
+ * throws gives up, with what it threw. Errors that must never be retried (a `NonRetryableStepError`) are the caller's
+ * to check first.
+ *
+ * ```ts
+ * const next = nextRetry(resolveRetry({ attempts: 3 }), 1, new Error('ECONNRESET'));
+ * // { retry: true, delay: 1_000 }
+ * ```
+ */
+export declare function nextRetry(policy: ResolvedRetry, attempt: number, error: unknown): RetryDecision;