@nestjs/workflows 0.0.1

package/dist/interfaces/workflow-decorator-options.interface.d.ts

@@ -0,0 +1,101 @@
+import type { ConcurrencyLimit, RateLimit, RateWindow, ResolvedConcurrency, ResolvedRateLimit } from '../core/interfaces/limits.interface.js';
+import type { Duration } from '../core/time/duration.js';
+import type { WorkflowScheduleSpec } from '../utils/schedule-spec.util.js';
+import type { WorkflowScheduleDeclaration } from './workflow-schedule.interface.js';
+export interface WorkflowMetadata {
+    name: string;
+    version: number;
+    /** In milliseconds. */
+    timeout?: number;
+    /** `null`: no limit. `undefined`: not known here (a workflow started by name that this process doesn't register). */
+    concurrency?: WorkflowConcurrencyMetadata | null;
+    /** `null`: no limit. `undefined`: not known here, as for `concurrency`. */
+    rateLimit?: WorkflowRateLimitMetadata | null;
+    /** `@Workflow(name, { schedules })`, validated. */
+    schedules?: WorkflowDeclaredSchedule[];
+}
+/** One of `@Workflow(name, { schedules })`, validated: its spec (as the store keeps it) and its input. */
+export interface WorkflowDeclaredSchedule {
+    id: string;
+    spec: WorkflowScheduleSpec;
+    /** A JSON value (normalized), or a function of the occurrence. */
+    input: unknown;
+}
+/** `@Workflow(name, { concurrency })`, validated. */
+export type WorkflowConcurrencyMetadata = ResolvedConcurrency;
+/** `@Workflow(name, { rateLimit })`, validated. */
+export type WorkflowRateLimitMetadata = ResolvedRateLimit;
+/** At most `max` executions start per window of `duration` milliseconds. */
+export type WorkflowRateWindow = RateWindow;
+/** One limit of `@Workflow(name, { concurrency })`. */
+export interface WorkflowConcurrency extends ConcurrencyLimit {
+    /** A positive integer: how many instances may run at once, of the workflow, or with `key`, per key. */
+    limit: number;
+    /**
+     * Makes `limit` a limit per key: the key of an instance, computed from its (JSON) input when
+     * it starts, such as `(order) => order.customerId`. `null` or `undefined` leaves the instance
+     * out of every key. `start()`'s `concurrencyKey` option overrides it.
+     */
+    key?: (input: any) => string | null | undefined;
+}
+/** One limit of `@Workflow(name, { rateLimit })`. */
+export interface WorkflowRateLimit extends RateLimit {
+    /** A positive integer: how many executions may start per `duration`, of the workflow, or with `key`, per key. */
+    max: number;
+    /** The window, such as `'1m'`. */
+    duration: Duration;
+    /**
+     * Makes the limit a limit per key: the key of an instance, computed from its (JSON) input when it starts, such
+     * as `(order) => order.customerId`. `null` or `undefined` leaves the instance out of every key. `start()`'s
+     * `rateLimitKey` option overrides it.
+     */
+    key?: (input: any) => string | null | undefined;
+}
+export interface WorkflowDecoratorOptions {
+    /**
+     * Bump when a change would not replay against journals written by the
+     * previous code (renamed, removed, reordered or inserted steps). Keep the old
+     * class registered until its instances finish. Default 1.
+     */
+    version?: number;
+    /**
+     * How long an instance may run, from its start to its end, sleeps and waits included. Once it
+     * passes, the instance stops at its next `ctx` call (a step that is running finishes first), runs
+     * its compensations and ends as `failed` with a `WorkflowTimeoutError`. The deadline is stored
+     * with the instance, so it holds across restarts, and a parked instance wakes for it. `start()`'s
+     * `timeout` option overrides it. Default: none.
+     */
+    timeout?: Duration;
+    /**
+     * How many instances may run at once, across every worker: `{ limit }` for the workflow,
+     * `{ limit, key }` per key (at most one instance per customer: `{ limit: 1, key: (order) =>
+     * order.customerId }`), or one of each in an array. An instance holds a slot while an
+     * execution runs it (compensations included), not while it sleeps or waits for a signal: a
+     * limit protects what the steps call, and an instance parked for days doesn't hold up the
+     * others. Instances past a limit stay due and queue, most overdue first; one busy key never
+     * holds back the others. Applies to every version of the workflow, with the highest
+     * registered version's limits. Default: none.
+     */
+    concurrency?: WorkflowConcurrency | WorkflowConcurrency[];
+    /**
+     * How many executions may start per window, across every worker: `{ max, duration }` for the workflow,
+     * `{ max, duration, key }` per key (at most 5 a minute per customer: `{ max: 5, duration: '1m', key: (order) =>
+     * order.customerId }`), or one of each in an array. Every execution counts: an instance's first run and each
+     * resumption (after a sleep, a signal, a retry's backoff, a cancel), because each can call what the limit
+     * protects. A window starts with the first execution after the previous window ended. Instances past a limit stay
+     * due and wait, in priority order; one busy key never holds back the others. Applies to every version of the
+     * workflow, with the highest registered version's limits. Default: none.
+     */
+    rateLimit?: WorkflowRateLimit | WorkflowRateLimit[];
+    /**
+     * Starts instances on a schedule: a `cron` expression, an interval (`every`) or an RFC 5545 `rrule`, in a
+     * time zone (`tz`), with an `id` unique across the application. Kept in step with the code, also in a rolling
+     * deploy: a process saves and confirms the schedules its highest registered version of the workflow declares, at
+     * startup and every minute, and removes one its code doesn't declare, of any workflow, once no process whose code
+     * declares it has confirmed it for five minutes (a process whose code declares it saves it again as it starts);
+     * it leaves a newer version's declaration as it is while a process of that code runs. Each occurrence starts one
+     * instance, whose id is `<schedule id>@<ISO time of the occurrence>`, however many workers there are;
+     * `WorkflowSchedules` pauses, resumes, triggers and lists them. Default: none.
+     */
+    schedules?: WorkflowScheduleDeclaration[];
+}

package/dist/interfaces/workflow-decorator-options.interface.js

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

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

@@ -0,0 +1,83 @@
+import type { SerializedWorkflowError } from './serialized-workflow-error.interface.js';
+export type WorkflowStatus = 'pending' | 'running' | 'suspended' | 'compensating' | 'completed' | 'failed' | 'cancelled' | 'compensation_failed';
+/** What happens to a child instance that is still running when its parent ends (`ctx.startChild()`'s `parentClose`). */
+export type WorkflowParentClose = 'cancel' | 'terminate' | 'abandon';
+export interface WorkflowInstance {
+    id: string;
+    workflow: string;
+    version: number;
+    /** The instance that started this one with `ctx.startChild()`, or `null`. */
+    parentId: string | null;
+    /** For a child: what happens to it if it is still running when its parent ends. */
+    parentClose: WorkflowParentClose | null;
+    /** The key its workflow's per-key concurrency limit counts it under, or `null`. */
+    concurrencyKey: string | null;
+    /** The key its workflow's per-key rate limit counts it under, or `null`. */
+    rateLimitKey: string | null;
+    /** Lower is claimed first; `0` (none given) before every other. */
+    priority: number;
+    /** The schedule that started it (`WorkflowSchedules`, `@Workflow(name, { schedules })`), or `null`. */
+    scheduleId: string | null;
+    /** For an instance a schedule started: when its occurrence was due (or triggered), or `null`. */
+    scheduledAt: number | null;
+    status: WorkflowStatus;
+    input: unknown;
+    output?: unknown;
+    error?: SerializedWorkflowError | null;
+    /** When the instance is next runnable. `null` = only a signal or cancel can wake it. */
+    wakeAt: number | null;
+    leaseOwner: string | null;
+    leaseUntil: number | null;
+    cancelRequested: boolean;
+    /** Set with `cancelRequested` by `WorkflowClient.terminate()`: stop without compensating. */
+    terminateRequested: boolean;
+    cancelReason: string | null;
+    /**
+     * When the run timeout passes (`@Workflow(name, { timeout })` or `start()`'s `timeout`), or
+     * `null` for none.
+     */
+    deadline: number | null;
+    /**
+     * What the workflow last set with `ctx.setStatus()` (JSON), or `null`. Written with the lease
+     * holder's writes, so it lags `setStatus()` until the instance's next journal write or
+     * suspension.
+     */
+    customStatus: unknown;
+    /** Signals with an id above this one can match the instance's waits. */
+    signalCursor: number;
+    /** Number of executions (claims) so far. */
+    runs: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface WorkflowJournalEntry {
+    name: string;
+    /** `retry`: an operator's `WorkflowClient.retry()`, recorded under `$retry:<n>` with what it retried in `data`. */
+    kind: 'step' | 'sleep' | 'signal' | 'any' | 'child' | 'commit' | 'now' | 'random' | 'uuid' | 'compensation' | 'retry';
+    /**
+     * `cancelled`: still pending (a sleep, a wait, a retry backoff) when the
+     * instance ended as `cancelled`, `failed` or `compensation_failed`.
+     */
+    status: 'pending' | 'completed' | 'failed' | 'cancelled';
+    /**
+     * JSON-safe step result, signal `{ signalId, payload }`, `waitForAny()` winner
+     * `{ key, signalId, payload }` (`signalId: null` for a timer), started child
+     * `{ id, workflow, version }`, or helper value.
+     */
+    result?: unknown;
+    error?: SerializedWorkflowError;
+    /** Attempts started (steps and compensations). */
+    attempts: number;
+    /** Sleep deadline, wait timeout, or retry time. `null` while an attempt runs. */
+    wakeAt?: number | null;
+    /** Last `heartbeat(progress)` checkpoint. */
+    progress?: unknown;
+    /** Wait spec (`{ signal, key }`), or a `waitForAny()`'s conditions (`{ waits, timers }`). */
+    data?: unknown;
+    updatedAt?: number;
+}
+/** A signal an instance is waiting for. */
+export interface WorkflowWait {
+    signal: string;
+    key: string | null;
+}

package/dist/interfaces/workflow-instance.interface.js

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

package/dist/interfaces/workflow-payload-codec.interface.d.ts

@@ -0,0 +1,32 @@
+import type { PayloadCodec, PayloadContext } from '../core/interfaces/payload-codec.interface.js';
+/**
+ * Where a payload is stored, which the codec receives with it, the same to encode and to decode: a codec that
+ * authenticates it (`AesGcmPayloadCodec` does) refuses a payload moved to another instance, entry or field.
+ */
+export interface WorkflowPayloadContext extends PayloadContext {
+    /**
+     * The field that holds it: of an instance (`input`, `output`, `error`, `customStatus`, `cancelReason`), of one of
+     * its journal entries (`result`, `progress`, `error`, `data`), of a signal (`payload`), or of a schedule (`input`).
+     */
+    field: 'input' | 'output' | 'error' | 'customStatus' | 'cancelReason' | 'result' | 'progress' | 'data' | 'payload';
+    /** The instance, for an instance's or a journal entry's payload. */
+    instanceId?: string;
+    /** The journal entry's name, for an entry's payload. */
+    entry?: string;
+    /** The signal's name, for a signal's payload. */
+    signal?: string;
+    /** The schedule's id, for a schedule's input. */
+    schedule?: string;
+}
+/**
+ * Encodes what workflows store for you before the store sees it, and decodes it on the way back: to encrypt it, or
+ * compress it. The module applies it to inputs, outputs, step results, checkpoints, journal entries' data, signal
+ * payloads, custom statuses, cancel reasons, schedule inputs, and errors' messages and stacks. Ids, names, keys,
+ * statuses and times stay as they are: the store matches on them. `WorkflowsModule.forRoot({ codec })` takes one
+ * (an instance, or a class Nest creates with its dependencies), or several: the first encodes, and each payload is
+ * decoded by the codec whose `id` it was stored with, so a codec you replace keeps decoding what it encoded.
+ * Payloads stored before any codec was set are read as they are. A `PayloadCodec` of `@nestjs/workflows/core` whose
+ * methods take any context (`AesGcmPayloadCodec`) is one.
+ */
+export interface WorkflowPayloadCodec extends PayloadCodec<WorkflowPayloadContext> {
+}

package/dist/interfaces/workflow-payload-codec.interface.js

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

package/dist/interfaces/workflow-retry-options.interface.d.ts

@@ -0,0 +1,9 @@
+import type { RetrySettings } from '../core/interfaces/retry-settings.interface.js';
+/**
+ * How a step (or compensation) retries. `retry: 5` means `{ attempts: 5 }`;
+ * `retry: false` means a single attempt. Workflows default to 3 attempts, a
+ * 1s first delay doubling up to 5m, no jitter. Every retry parks the instance
+ * durably: the wait survives restarts. A `NonRetryableStepError` never retries.
+ */
+export interface WorkflowRetryOptions extends RetrySettings {
+}

package/dist/interfaces/workflow-retry-options.interface.js

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

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

@@ -0,0 +1,11 @@
+import type { WorkflowContext } from './workflow-context.interface.js';
+/** Implemented by `@Workflow()` classes: `WorkflowRunner<Input, Output>`. */
+export interface WorkflowRunner<I = unknown, O = unknown> {
+    run(ctx: WorkflowContext, input: I): Promise<O>;
+}
+export type WorkflowInput<W> = W extends {
+    run(ctx: any, input: infer I): any;
+} ? I : unknown;
+export type WorkflowOutput<W> = W extends {
+    run(ctx: any, input: any): infer R;
+} ? Awaited<R> : unknown;

package/dist/interfaces/workflow-runner.interface.js

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

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

@@ -0,0 +1,104 @@
+import type { Type } from '@nestjs/common';
+import type { ScheduleMissed, ScheduleOccurrence, ScheduleOptions, ScheduleOverlap, ScheduleTiming } from '../core/interfaces/schedule.interface.js';
+import type { WorkflowInput } from './workflow-runner.interface.js';
+/**
+ * When a schedule's occurrences are: exactly one of `cron`, `every` or `rrule`, with its time zone and
+ * bounds. Times are wall-clock times in `tz`: on the day clocks go forward, a time that doesn't exist runs
+ * that much later (02:30 runs at 03:30); on the day they go back, a time that happens twice runs once, the
+ * first time. For a fixed interval whatever the clocks do, use `every` (or `tz: 'UTC'`).
+ */
+export type WorkflowScheduleTiming = ScheduleTiming;
+/**
+ * What a schedule does with occurrences no worker was up to start (a deploy, an outage): `'skip'` them (only an
+ * occurrence found within a minute of its time starts), start the latest of them `'once'`, or start `'all'` of
+ * them at once (the latest 100 at most; it needs `overlap: 'allow'`).
+ */
+export type WorkflowScheduleMissed = ScheduleMissed;
+/**
+ * What an occurrence does while an instance the schedule started is still running: `'skip'` it, `'allow'` it
+ * (both run), `'cancel-previous'` (the running one is cancelled, and compensates, while the new one starts), or
+ * `'buffer-one'` (it starts once the running one ends; one occurrence waits at most, later ones are skipped).
+ */
+export type WorkflowScheduleOverlap = ScheduleOverlap;
+/** What `@Workflow(name, { schedules })` and `WorkflowSchedules.upsert()` share. */
+export interface WorkflowScheduleOptions extends ScheduleOptions {
+    /** The priority of the instances it starts, as `WorkflowClient.start()`'s. Default: none. */
+    priority?: number;
+}
+/** An occurrence of a schedule: what a declared schedule's `input` function receives, and `ctx.schedule`. */
+export type WorkflowScheduleOccurrence = ScheduleOccurrence;
+/** One entry of `@Workflow(name, { schedules })`. */
+export interface WorkflowScheduleDeclaration<I = any> extends WorkflowScheduleOptions {
+    /** Unique across the application's schedules: letters, digits, `.`, `:`, `_` and `-`. */
+    id: string;
+    /**
+     * The input of the instances it starts: a JSON value, or a function of the occurrence, called by the worker
+     * that starts it (`input: ({ at }) => ({ week: isoWeek(at) })`). Default: none.
+     */
+    input?: ((occurrence: WorkflowScheduleOccurrence) => I) | ScheduleInputValue<I>;
+}
+/**
+ * A declared schedule's input as a value. Without a type for it, any JSON value: not `I` itself, since `any` or
+ * `unknown` in the union would swallow the function beside it, and with it the occurrence's type for its parameter.
+ */
+type ScheduleInputValue<I> = unknown extends I ? string | number | boolean | object | null : I;
+/** What `WorkflowSchedules.upsert()` takes. */
+export interface UpsertWorkflowScheduleOptions<W = unknown> extends WorkflowScheduleOptions {
+    /** The workflow it starts: the class, or its name. */
+    workflow: Type<W> | string;
+    /** Pin a version. Default: the highest the worker that starts an occurrence registers. */
+    version?: number;
+    /** The input of the instances it starts: a JSON value, stored with the schedule. Default: none. */
+    input?: WorkflowInput<W>;
+}
+/** What `WorkflowSchedules.preview()` takes, with the spec of a schedule that isn't stored. */
+export type WorkflowSchedulePreviewSpec = WorkflowScheduleTiming & Pick<WorkflowScheduleOptions, 'limit'>;
+/** A schedule, as `WorkflowSchedules.get()` and `list()` return it. */
+export interface WorkflowSchedule {
+    id: string;
+    /** The workflow it starts. */
+    workflow: string;
+    /** The version it starts, or `null`: the highest the worker that starts an occurrence registers. */
+    version: number | null;
+    /** Declared with `@Workflow(name, { schedules })`: kept in step with the code at startup. */
+    declared: boolean;
+    cron?: string;
+    /** In milliseconds. */
+    every?: number;
+    rrule?: string;
+    tz: string;
+    startAt: number | null;
+    endAt: number | null;
+    limit: number | null;
+    missed: WorkflowScheduleMissed;
+    overlap: WorkflowScheduleOverlap;
+    /** `0`: none. */
+    priority: number;
+    /** The stored input; `undefined` for a declared schedule whose input is a function. */
+    input?: unknown;
+    paused: boolean;
+    /** When its next occurrence is due (epoch milliseconds), or `null`: paused, or ended (`endAt`, `limit`, COUNT, UNTIL). */
+    nextAt: number | null;
+    /** Occurrences it started (or buffered) so far: what `limit` counts. */
+    runs: number;
+    /** An occurrence waiting for the running instance to end (`overlap: 'buffer-one'`), or `null`. */
+    bufferedAt: number | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/** What `WorkflowSchedules.list()` takes. */
+export interface WorkflowScheduleListFilter {
+    /** Only the schedules of this workflow. */
+    workflow?: string;
+    /** Default 100. */
+    limit?: number;
+    offset?: number;
+}
+/** What `WorkflowSchedules.preview()` takes. */
+export interface WorkflowSchedulePreviewOptions {
+    /** Occurrences after this time. Default: now. */
+    from?: Date | number;
+    /** How many. Default 10, at most 1,000. */
+    count?: number;
+}
+export {};

package/dist/interfaces/workflow-schedule.interface.js

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

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

@@ -0,0 +1,4 @@
+export interface WorkflowStorageRegisterOptions {
+    /** Replace a source that is already registered (tests, a wrapper around it). */
+    replace?: boolean;
+}

package/dist/interfaces/workflow-storage.interface.js

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