@workglow/postgres 0.2.28

package/dist/job-queue/PostgresQueueStorage.d.ts

@@ -0,0 +1,155 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Pool } from "@workglow/postgres/storage";
+import { JobStatus } from "@workglow/job-queue";
+import type { IQueueStorage, JobStorageFormat, PrefixColumn, QueueChangePayload, QueueStorageOptions, QueueSubscribeOptions } from "@workglow/job-queue";
+export declare const POSTGRES_QUEUE_STORAGE: import("@workglow/util").ServiceToken<IQueueStorage<any, any>>;
+/**
+ * PostgreSQL implementation of a job queue.
+ * Provides storage and retrieval for job execution states using PostgreSQL.
+ */
+export declare class PostgresQueueStorage<Input, Output> implements IQueueStorage<Input, Output> {
+    protected readonly db: Pool;
+    protected readonly queueName: string;
+    readonly scope: "cluster";
+    /** The prefix column definitions */
+    protected readonly prefixes: readonly PrefixColumn[];
+    /** The prefix values for filtering */
+    protected readonly prefixValues: Readonly<Record<string, string | number>>;
+    /** The table name for the job queue */
+    protected readonly tableName: string;
+    constructor(db: Pool, queueName: string, options?: QueueStorageOptions);
+    /**
+     * Gets the SQL column type for a prefix column
+     */
+    private getPrefixColumnType;
+    /**
+     * Builds the prefix columns SQL for CREATE TABLE
+     */
+    private buildPrefixColumnsSql;
+    /**
+     * Builds prefix column names for use in queries
+     */
+    private getPrefixColumnNames;
+    /**
+     * Builds WHERE clause conditions for prefix filtering
+     * @param startParam - The starting parameter number for parameterized queries
+     * @returns Object with conditions string and parameter values
+     */
+    private buildPrefixWhereClause;
+    /**
+     * Gets prefix values as an array in column order
+     */
+    private getPrefixParamValues;
+    setupDatabase(): Promise<void>;
+    /**
+     * Channel name for this storage's LISTEN/NOTIFY. Mirrors the trigger's
+     * computation so subscriber and notifier agree.
+     */
+    private notifyChannelName;
+    /**
+     * Adds a new job to the queue.
+     * @param job - The job to add
+     * @returns The ID of the added job
+     */
+    add(job: JobStorageFormat<Input, Output>): Promise<unknown>;
+    /**
+     * Retrieves a job by its ID.
+     * @param id - The ID of the job to retrieve
+     * @returns The job if found, undefined otherwise
+     */
+    get(id: unknown): Promise<JobStorageFormat<Input, Output> | undefined>;
+    /**
+     * Retrieves a slice of jobs from the queue.
+     * @param num - Maximum number of jobs to return
+     * @returns An array of jobs
+     */
+    peek(status?: JobStatus, num?: number): Promise<Array<JobStorageFormat<Input, Output>>>;
+    /**
+     * Retrieves the next available job that is ready to be processed.
+     * @param workerId - Worker ID to associate with the job (required)
+     * @returns The next job or undefined if no job is available
+     */
+    next(workerId: string): Promise<JobStorageFormat<Input, Output> | undefined>;
+    /**
+     * Retrieves the number of jobs in the queue with a specific status.
+     * @param status - The status of the jobs to count
+     * @returns The count of jobs with the specified status
+     */
+    size(status?: "PENDING"): Promise<number>;
+    /**
+     * Marks a job as complete with its output or error.
+     * Enhanced error handling:
+     * - For a retryable error, increments run_attempts and updates run_after.
+     * - Marks a job as FAILED immediately for permanent or generic errors.
+     */
+    complete(jobDetails: JobStorageFormat<Input, Output>): Promise<void>;
+    /**
+     * Clears all jobs from the queue.
+     */
+    deleteAll(): Promise<void>;
+    /**
+     * Looks up cached output for a given input
+     * Uses input fingerprinting for efficient matching
+     * @returns The cached output or null if not found
+     */
+    outputForInput(input: Input): Promise<Output | null>;
+    /**
+     * Aborts a job by setting its status to "ABORTING".
+     * This method will signal the corresponding AbortController so that
+     * the job's execute() method (if it supports an AbortSignal parameter)
+     * can clean up and exit.
+     */
+    abort(jobId: unknown): Promise<void>;
+    /**
+     * Releases a claimed job back to PENDING without incrementing run_attempts.
+     * @param jobId - The id of the claimed job to release.
+     */
+    release(jobId: unknown): Promise<void>;
+    /**
+     * Retrieves all jobs for a given job run ID.
+     * @param job_run_id - The ID of the job run to retrieve
+     * @returns An array of jobs
+     */
+    getByRunId(job_run_id: string): Promise<Array<JobStorageFormat<Input, Output>>>;
+    /**
+     * Implements the abstract saveProgress method from JobQueue
+     */
+    saveProgress(jobId: unknown, progress: number, message: string, details: Record<string, any>): Promise<void>;
+    /**
+     * Deletes a job by its ID
+     */
+    delete(jobId: unknown): Promise<void>;
+    /**
+     * Delete jobs with a specific status older than a cutoff date
+     * @param status - Status of jobs to delete
+     * @param olderThanMs - Delete jobs completed more than this many milliseconds ago
+     */
+    deleteJobsByStatusAndAge(status: JobStatus, olderThanMs: number): Promise<void>;
+    /**
+     * Subscribe to INSERT/UPDATE notifications via PostgreSQL LISTEN/NOTIFY.
+     * Replaces 100ms-poll fallback for cluster Postgres deployments — workers
+     * wake within network-latency of an actual change rather than on a timer.
+     *
+     * Acquires a dedicated client from the pool (LISTEN occupies a connection
+     * for its lifetime). On unsubscribe, runs UNLISTEN and releases the client.
+     * On connection loss, attempts to reconnect with bounded backoff and
+     * re-LISTEN. After every successful (re)connect — including the initial
+     * one — emits a synthetic `{ type: "RESYNC" }` event so subscribers can
+     * re-poll state and pick up any rows inserted during the disconnect window
+     * (or between subscribe and the first NOTIFY landing).
+     *
+     * Throws synchronously when the underlying pool lacks `connect()`
+     * (single-connection wrappers like PGLite) so the caller's try/catch can
+     * fall back to polling. JobQueueServer.start does this and logs at debug.
+     *
+     * `options.prefixFilter` follows {@link QueueSubscribeOptions.prefixFilter}:
+     * `undefined` means "use the storage instance's configured prefixValues",
+     * `{}` means "receive all changes regardless of prefix".
+     */
+    subscribeToChanges(callback: (change: QueueChangePayload<Input, Output>) => void, options?: QueueSubscribeOptions): () => void;
+}
+//# sourceMappingURL=PostgresQueueStorage.d.ts.map

package/dist/job-queue/PostgresQueueStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostgresQueueStorage.d.ts","sourceRoot":"","sources":["../../src/job-queue/PostgresQueueStorage.ts"],"names":[],"mappings":"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"}

package/dist/job-queue/PostgresRateLimiterStorage.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Pool } from "@workglow/postgres/storage";
+import type { PrefixColumn } from "@workglow/job-queue";
+import type { IRateLimiterStorage, RateLimiterStorageOptions, RateLimiterStorageScope } from "@workglow/job-queue";
+export declare const POSTGRES_RATE_LIMITER_STORAGE: import("@workglow/util").ServiceToken<IRateLimiterStorage>;
+/**
+ * PostgreSQL implementation of rate limiter storage.
+ * Manages execution records and next available times for rate limiting.
+ */
+export declare class PostgresRateLimiterStorage implements IRateLimiterStorage {
+    protected readonly db: Pool;
+    readonly scope: RateLimiterStorageScope;
+    /** The prefix column definitions */
+    protected readonly prefixes: readonly PrefixColumn[];
+    /** The prefix values for filtering */
+    protected readonly prefixValues: Readonly<Record<string, string | number>>;
+    /** The table name for execution tracking */
+    protected readonly executionTableName: string;
+    /** The table name for next available times */
+    protected readonly nextAvailableTableName: string;
+    constructor(db: Pool, options?: RateLimiterStorageOptions);
+    /**
+     * Gets the SQL column type for a prefix column.
+     */
+    private getPrefixColumnType;
+    /**
+     * Builds the prefix columns SQL for CREATE TABLE.
+     */
+    private buildPrefixColumnsSql;
+    /**
+     * Builds prefix column names for use in queries.
+     */
+    private getPrefixColumnNames;
+    /**
+     * Builds WHERE clause conditions for prefix filtering.
+     * @param startParam - The starting parameter number for parameterized queries
+     */
+    private buildPrefixWhereClause;
+    /**
+     * Gets prefix values as an array in column order.
+     */
+    private getPrefixParamValues;
+    setupDatabase(): Promise<void>;
+    tryReserveExecution(queueName: string, maxExecutions: number, windowMs: number): Promise<unknown | null>;
+    releaseExecution(queueName: string, token: unknown): Promise<void>;
+    recordExecution(queueName: string): Promise<void>;
+    getExecutionCount(queueName: string, windowStartTime: string): Promise<number>;
+    getOldestExecutionAtOffset(queueName: string, offset: number): Promise<string | undefined>;
+    getNextAvailableTime(queueName: string): Promise<string | undefined>;
+    setNextAvailableTime(queueName: string, nextAvailableAt: string): Promise<void>;
+    clear(queueName: string): Promise<void>;
+}
+//# sourceMappingURL=PostgresRateLimiterStorage.d.ts.map

package/dist/job-queue/PostgresRateLimiterStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostgresRateLimiterStorage.d.ts","sourceRoot":"","sources":["../../src/job-queue/PostgresRateLimiterStorage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EACV,mBAAmB,EACnB,yBAAyB,EACzB,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,6BAA6B,4DAEzC,CAAC;AAEF;;;GAGG;AACH,qBAAa,0BAA2B,YAAW,mBAAmB;IAYlE,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,IAAI;IAX7B,SAAgB,KAAK,EAAE,uBAAuB,CAAa;IAC3D,oCAAoC;IACpC,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IACrD,sCAAsC;IACtC,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;IAC3E,4CAA4C;IAC5C,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IAC9C,8CAA8C;IAC9C,SAAS,CAAC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IAElD,YACqB,EAAE,EAAE,IAAI,EAC3B,OAAO,CAAC,EAAE,yBAAyB,EAcpC;IAED;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAS7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAY9B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAIf,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CA+B1C;IAEY,mBAAmB,CAC9B,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsIzB;IAEY,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAU9E;IAEY,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB7D;IAEY,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAa1F;IAEY,0BAA0B,CACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAiB7B;IAEY,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAehF;IAEY,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB3F;IAEY,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWnD;CACF"}

package/dist/job-queue/browser.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from "./common";
+//# sourceMappingURL=browser.d.ts.map

package/dist/job-queue/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/job-queue/browser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,UAAU,CAAC"}