@nestjs/workflows 0.0.1

package/dist/postgres/errors/index.d.ts

@@ -0,0 +1 @@
+export * from '../../sql/workflow-schema.error.js';

package/dist/postgres/errors/index.js

@@ -0,0 +1,2 @@
+// The package's one schema error, which both first-party SQL stores fail with.
+export * from '../../sql/workflow-schema.error.js';

package/dist/postgres/index.d.ts

@@ -0,0 +1,5 @@
+export { PostgresWorkflowStore } from './postgres-workflow.store.js';
+export { WorkflowSchemaError } from './errors/index.js';
+export type { PostgresWorkflowStoreOptions } from './interfaces/index.js';
+export { fromDrizzle, fromKysely, fromPg, fromPrisma, fromTypeOrm, type PrismaExecutorOptions } from '@nestjs/store-kit/postgres';
+export type { SqlExecutor, SqlIsolationLevel, SqlTransaction, SqlTransactionOptions } from '@nestjs/store-kit/postgres';

package/dist/postgres/index.js

@@ -0,0 +1,8 @@
+// The `@nestjs/workflows/postgres` entry: the first-party PostgreSQL store. Nothing here imports a driver or an ORM:
+// the executors (from @nestjs/store-kit, which every first-party store builds on) reach the client the application
+// passes them.
+// The store, and the error it fails startup with while its schema is behind
+export { PostgresWorkflowStore } from './postgres-workflow.store.js';
+export { WorkflowSchemaError } from './errors/index.js';
+// Executors: the store's SQL through the application's pool or ORM, and its transactions
+export { fromDrizzle, fromKysely, fromPg, fromPrisma, fromTypeOrm } from '@nestjs/store-kit/postgres';

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

@@ -0,0 +1 @@
+export * from './postgres-workflow-store-options.interface.js';

package/dist/postgres/interfaces/index.js

@@ -0,0 +1 @@
+export * from './postgres-workflow-store-options.interface.js';

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

@@ -0,0 +1,22 @@
+import type { SqlExecutor } from '@nestjs/store-kit/postgres';
+/** What `new PostgresWorkflowStore(options, storage)` takes. */
+export interface PostgresWorkflowStoreOptions {
+    /**
+     * How the store reaches the database: `fromPg(pool)`, `fromDrizzle(db)`, `fromTypeOrm(dataSource)`,
+     * `fromPrisma(prisma)` or `fromKysely(db)`. The store's own transactions run on it, and `start()` and `signal()`
+     * with `{ transaction }` take that client's transaction object.
+     */
+    executor: SqlExecutor<'postgres'>;
+    /**
+     * The schema that holds the store's tables, created by its first migration: keep it for the store alone. Letters,
+     * digits and underscores, not starting with a digit, at most 63 characters. Default: `'nest_workflows'`.
+     */
+    schema?: string;
+    /**
+     * Apply the store's pending migrations at startup, in one transaction under an advisory lock, so processes that
+     * start together migrate once. With `false`, startup fails with a `WorkflowSchemaError` while the schema is behind
+     * this version of the package: apply them with `npx nest-workflows migrate`, or with your own migration tool
+     * (`PostgresWorkflowStore.migrationSql()`). Default: `true`, except when `NODE_ENV` is `production`.
+     */
+    migrate?: boolean;
+}

package/dist/postgres/interfaces/postgres-workflow-store-options.interface.js

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

package/dist/postgres/migrations/index.d.ts

@@ -0,0 +1,6 @@
+import { StoreSchema } from '@nestjs/store-kit/postgres';
+/**
+ * PostgresWorkflowStore's schema: every version of it, in order (a new one goes last, and none ever changes once
+ * released), and what the store, its statics and `nest-workflows` do with them.
+ */
+export declare const workflowStoreSchema: StoreSchema;

package/dist/postgres/migrations/index.js

@@ -0,0 +1,15 @@
+import { StoreSchema } from '@nestjs/store-kit/postgres';
+import { WorkflowSchemaError } from '../../sql/workflow-schema.error.js';
+import { initialMigration } from './initial.migration.js';
+/**
+ * PostgresWorkflowStore's schema: every version of it, in order (a new one goes last, and none ever changes once
+ * released), and what the store, its statics and `nest-workflows` do with them.
+ */
+export const workflowStoreSchema = new StoreSchema({
+    packageName: '@nestjs/workflows',
+    storeName: 'PostgresWorkflowStore',
+    command: 'nest-workflows',
+    defaultSchema: 'nest_workflows',
+    migrations: [initialMigration],
+    createError: (message, details) => new WorkflowSchemaError(message, details),
+});

package/dist/postgres/migrations/initial.migration.d.ts

@@ -0,0 +1,6 @@
+import type { StoreMigration } from '@nestjs/store-kit/postgres';
+/**
+ * The store's tables. Times are epoch milliseconds from the engine's clock (`bigint`); inputs, outputs, errors,
+ * payloads, journal entries and schedule specs are the engine's JSON (`jsonb`).
+ */
+export declare const initialMigration: StoreMigration;

package/dist/postgres/migrations/initial.migration.js

@@ -0,0 +1,106 @@
+/**
+ * The store's tables. Times are epoch milliseconds from the engine's clock (`bigint`); inputs, outputs, errors,
+ * payloads, journal entries and schedule specs are the engine's JSON (`jsonb`).
+ */
+export const initialMigration = {
+    version: 1,
+    name: 'initial',
+    up: (s) => [
+        `CREATE TABLE ${s}.instances (
+  id text PRIMARY KEY,
+  workflow text NOT NULL,
+  version integer NOT NULL,
+  parent_id text,
+  parent_close text,
+  concurrency_key text,
+  rate_limit_key text,
+  priority integer NOT NULL DEFAULT 0,
+  schedule_id text,
+  scheduled_at bigint,
+  status text NOT NULL,
+  input jsonb,
+  output jsonb,
+  error jsonb,
+  wake_at bigint,
+  lease_token text,
+  lease_owner text,
+  lease_until bigint,
+  cancel_requested boolean NOT NULL DEFAULT false,
+  terminate_requested boolean NOT NULL DEFAULT false,
+  cancel_reason text,
+  deadline bigint,
+  custom_status jsonb,
+  signal_cursor bigint NOT NULL,
+  runs integer NOT NULL DEFAULT 0,
+  created_at bigint NOT NULL,
+  updated_at bigint NOT NULL
+)`,
+        // One row per step, sleep, wait or compensation; `seq` keeps them in first-write order.
+        `CREATE TABLE ${s}.journal (
+  seq bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  instance_id text NOT NULL REFERENCES ${s}.instances (id) ON DELETE CASCADE,
+  name text NOT NULL,
+  entry jsonb NOT NULL,
+  CONSTRAINT journal_name UNIQUE (instance_id, name)
+)`,
+        // The signals a suspended instance waits for.
+        `CREATE TABLE ${s}.waits (
+  instance_id text NOT NULL REFERENCES ${s}.instances (id) ON DELETE CASCADE,
+  position integer NOT NULL,
+  signal text NOT NULL,
+  key text,
+  PRIMARY KEY (instance_id, position)
+)`,
+        `CREATE TABLE ${s}.signals (
+  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  name text NOT NULL,
+  key text,
+  dedupe_id text,
+  payload jsonb,
+  created_at bigint NOT NULL,
+  CONSTRAINT signals_dedupe UNIQUE (name, dedupe_id)
+)`,
+        `CREATE TABLE ${s}.schedules (
+  id text PRIMARY KEY,
+  workflow text NOT NULL,
+  declared boolean NOT NULL,
+  spec jsonb NOT NULL,
+  input jsonb,
+  paused boolean NOT NULL,
+  wake_at bigint,
+  state jsonb NOT NULL,
+  revision integer NOT NULL,
+  lease_token text,
+  lease_owner text,
+  lease_until bigint,
+  created_at bigint NOT NULL,
+  updated_at bigint NOT NULL
+)`,
+        // The rate-limit windows claims count: the workflow's own (`key` '', which no instance key is) and one per key.
+        `CREATE TABLE ${s}.rate_limits (
+  workflow text NOT NULL,
+  key text NOT NULL,
+  window_end bigint NOT NULL,
+  count integer NOT NULL,
+  PRIMARY KEY (workflow, key)
+)`,
+        // What claims look for: due instances.
+        `CREATE INDEX instances_due ON ${s}.instances (wake_at) WHERE wake_at IS NOT NULL`,
+        `CREATE INDEX instances_created ON ${s}.instances (created_at, id)`,
+        // What purges and list() by status look for.
+        `CREATE INDEX instances_status ON ${s}.instances (status, updated_at)`,
+        // What a claim counts for a concurrency limit: live leases, by workflow and key.
+        `CREATE INDEX instances_leased ON ${s}.instances (workflow, concurrency_key) WHERE lease_until IS NOT NULL`,
+        // What list({ parentId }) and closing a parent's children look for.
+        `CREATE INDEX instances_parent ON ${s}.instances (parent_id, created_at) WHERE parent_id IS NOT NULL`,
+        // What list({ scheduleId }) and a schedule's overlap check look for.
+        `CREATE INDEX instances_schedule ON ${s}.instances (schedule_id, created_at) WHERE schedule_id IS NOT NULL`,
+        `CREATE INDEX waits_signal ON ${s}.waits (signal, key)`,
+        `CREATE INDEX signals_lookup ON ${s}.signals (name, key, id)`,
+        // What claims look for: due schedules.
+        `CREATE INDEX schedules_due ON ${s}.schedules (wake_at) WHERE wake_at IS NOT NULL`,
+        `CREATE INDEX schedules_workflow ON ${s}.schedules (workflow, id)`,
+        // What purges look for: windows that ended.
+        `CREATE INDEX rate_limits_end ON ${s}.rate_limits (window_end)`,
+    ],
+};

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

@@ -0,0 +1,132 @@
+import { type OnModuleInit } from '@nestjs/common';
+import { type MigrationSqlOptions } from '@nestjs/store-kit/postgres';
+import type { WorkflowInstance, WorkflowStatus } from '../interfaces/workflow-instance.interface.js';
+import type { NewWorkflowInstance, NewWorkflowSignal, WorkflowCancelRequest, WorkflowClaim, WorkflowClaimRequest, WorkflowInstanceDetails, WorkflowListQuery, WorkflowPurgeQuery, WorkflowPurgeResult, WorkflowReopen, WorkflowScheduleClaimRequest, WorkflowScheduleQuery, WorkflowScheduleRecord, WorkflowScheduleSave, WorkflowScheduleWrite, WorkflowSignalQuery, WorkflowSignalRecord, WorkflowSignalResult, WorkflowStore, WorkflowWrite } from '../interfaces/workflow-store.interface.js';
+import type { WorkflowStorage } from '../storage/workflow.storage.js';
+import type { PostgresWorkflowStoreOptions } from './interfaces/postgres-workflow-store-options.interface.js';
+/**
+ * The first-party `WorkflowStore` on PostgreSQL, through the client the application already has (`fromPg()`,
+ * `fromDrizzle()`, `fromTypeOrm()`, `fromPrisma()`, `fromKysely()`). It keeps its tables in a schema of its own
+ * (`nest_workflows` by default), which its migrations create and bring up to date, and it joins the application's
+ * transactions for `start()` and `signal()` with `{ transaction }`.
+ *
+ * ```ts
+ * @Module({
+ *   imports: [WorkflowsModule.forRoot()],
+ *   providers: [
+ *     {
+ *       provide: PostgresWorkflowStore,
+ *       inject: [getDrizzleToken(), WorkflowStorage],
+ *       useFactory: (db: Database, storage: WorkflowStorage) => new PostgresWorkflowStore({ executor: fromDrizzle(db) }, storage),
+ *     },
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * Given `storage`, it registers itself (`storage.registerSource(this)`), as every store does. It checks its schema,
+ * or migrates it (`migrate`), in `onModuleInit` (so before the worker starts), or at its first call outside Nest.
+ */
+export declare class PostgresWorkflowStore implements WorkflowStore, OnModuleInit {
+    /**
+     * The SQL of the store's migrations, for teams that apply migrations with their own tool (drizzle-kit, TypeORM,
+     * Prisma Migrate, Flyway...) and run the store with `migrate: false`: from version `from` (default `0`, a new
+     * database) to `to` (default: the version this version of the package needs), with the bookkeeping that tells the
+     * store which versions a schema has. A schema's version is `SELECT max(version) FROM <schema>.migrations`.
+     * Downgrades aren't supported. From version 0 it starts with `CREATE SCHEMA IF NOT EXISTS`, which needs the CREATE
+     * privilege on the database even when the schema exists: drop that statement if someone created the schema for you.
+     * With `statementBreakpoints`, drizzle-kit's `--> statement-breakpoint` separates the statements, for a custom
+     * drizzle-kit migration: its migrator then runs them one at a time, which PGlite needs.
+     *
+     * ```ts
+     * // drizzle/0003_workflows.sql, created empty by `npx drizzle-kit generate --custom --name=workflows`
+     * writeFileSync('drizzle/0003_workflows.sql', PostgresWorkflowStore.migrationSql({ statementBreakpoints: true }));
+     * ```
+     */
+    static migrationSql(options?: MigrationSqlOptions): string;
+    /** The schema version this version of the package needs: its last migration. */
+    static readonly schemaVersion: number;
+    private readonly logger;
+    private readonly executor;
+    private readonly schema;
+    private readonly t;
+    /**
+     * Serializes signals with each other (exclusive) and with suspensions that register waits (shared), until the
+     * transaction ends: signal ids become visible in id order, and a signal can't slip between a suspension's check for
+     * missed signals and its commit.
+     */
+    private readonly signalLock;
+    /** The schema migrated (`migrate`) or checked before the first statement: see `onModuleInit()`. */
+    private readonly readiness;
+    constructor(options: PostgresWorkflowStoreOptions, storage?: WorkflowStorage);
+    /** Migrates the schema (`migrate`) or checks it, before the worker starts: startup fails if it can't serve. */
+    onModuleInit(): Promise<void>;
+    /**
+     * Applies the migrations the schema hasn't had yet, whatever `migrate` says, in one transaction under an advisory
+     * lock: of processes that migrate together, one applies them. Resolves to the versions it applied (`[]`: none were
+     * pending).
+     */
+    migrate(): Promise<number[]>;
+    create(instance: NewWorkflowInstance): Promise<{
+        instance: WorkflowInstance;
+        created: boolean;
+    }>;
+    /** `start(..., { transaction })`: the instance commits or rolls back with the application's rows. */
+    createInTransaction(transaction: unknown, instance: NewWorkflowInstance): Promise<{
+        instance: WorkflowInstance;
+        created: boolean;
+    }>;
+    get(id: string, options?: {
+        journal?: boolean;
+    }): Promise<WorkflowInstanceDetails | null>;
+    list(query: WorkflowListQuery): Promise<WorkflowInstance[]>;
+    requestCancel(id: string, { reason, now, terminate }: WorkflowCancelRequest): Promise<boolean>;
+    /** `WorkflowClient.retry()`: one conditional update, then the journal, in one transaction. */
+    reopen(id: string, reopen: WorkflowReopen): Promise<boolean>;
+    /** `WorkflowClient.delete()`: its journal and waits go with it (ON DELETE CASCADE). */
+    delete(id: string, statuses: WorkflowStatus[]): Promise<boolean>;
+    signal(signal: NewWorkflowSignal): Promise<WorkflowSignalResult>;
+    /** `signal(..., { transaction })`: the signal and its wake-ups commit with the application's rows. */
+    signalInTransaction(transaction: unknown, signal: NewWorkflowSignal): Promise<WorkflowSignalResult>;
+    signals(query: WorkflowSignalQuery): Promise<WorkflowSignalRecord[]>;
+    purge(query: WorkflowPurgeQuery): Promise<WorkflowPurgeResult>;
+    saveSchedule(save: WorkflowScheduleSave): Promise<WorkflowScheduleRecord | null>;
+    getSchedule(id: string): Promise<WorkflowScheduleRecord | null>;
+    listSchedules(query: WorkflowScheduleQuery): Promise<WorkflowScheduleRecord[]>;
+    deleteSchedule(id: string, revision?: number): Promise<boolean>;
+    claimSchedules(request: WorkflowScheduleClaimRequest): Promise<WorkflowScheduleRecord[]>;
+    writeSchedule(id: string, token: string, write: WorkflowScheduleWrite): Promise<boolean>;
+    claim(request: WorkflowClaimRequest): Promise<WorkflowClaim>;
+    /**
+     * A claim under concurrency or rate limits. Claims of a workflow with a concurrency limit take its lock first (in
+     * name order, so two claims never wait for each other's), so they count the slots live leases hold and lease the
+     * instances that fit one after the other: two never both take the last slot. Rate-limit windows are counted again
+     * under their rows' locks, once the instances are picked (see `takeRoom()`).
+     */
+    private claimWithin;
+    /**
+     * Of `picked` (in claim order), the instances their rate-limit windows have room for, recorded in the windows. Each
+     * window's row is inserted or locked first, in a fixed order: the count read under the lock is exact (a concurrent
+     * claim of the same window waits for this one), and a purge can't delete the row in between.
+     */
+    private takeRoom;
+    /** Leases the instances `due` (a subquery of `p`'s statement) selects and locks. */
+    private lease;
+    renew(id: string, token: string, leaseUntil: number): Promise<{
+        cancelRequested: boolean;
+        terminateRequested: boolean;
+    } | null>;
+    write(id: string, token: string, write: WorkflowWrite): Promise<boolean>;
+    private insertInstance;
+    private insertSignal;
+    /**
+     * Replaces the instance's waits, and says whether a signal committed after the execution read its cursor matches
+     * one of the new ones: then the instance stays due instead of losing it.
+     */
+    private replaceWaits;
+    /** Journal entries by name: a new name goes last (`seq`), a known one is replaced in place. */
+    private upsertEntries;
+    /** Due, unleased instances of the versions the worker runs, as `alias` in a statement of `p`. */
+    private isDue;
+    private lastSignalId;
+}