@workglow/supabase 0.2.28

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

@@ -0,0 +1,196 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { SupabaseClient } from "@supabase/supabase-js";
+import { JobStatus } from "@workglow/job-queue";
+import type { IQueueStorage, JobStorageFormat, PrefixColumn, QueueChangePayload, QueueStorageOptions, QueueSubscribeOptions } from "@workglow/job-queue";
+export declare const SUPABASE_QUEUE_STORAGE: import("@workglow/util").ServiceToken<IQueueStorage<any, any>>;
+/**
+ * Supabase implementation of a job queue.
+ * Provides storage and retrieval for job execution states using Supabase.
+ */
+export declare class SupabaseQueueStorage<Input, Output> implements IQueueStorage<Input, Output> {
+    protected readonly queueName: string;
+    readonly scope: "cluster";
+    protected readonly client: SupabaseClient;
+    protected readonly prefixes: readonly PrefixColumn[];
+    protected readonly prefixValues: Readonly<Record<string, string | number>>;
+    protected readonly tableName: string;
+    private realtimeChannel;
+    private pollingManager;
+    constructor(client: SupabaseClient, queueName: string, options?: QueueStorageOptions);
+    /**
+     * Gets the SQL column type for a prefix column (Supabase supports UUID natively)
+     */
+    private getPrefixColumnType;
+    /**
+     * Builds the prefix columns SQL for CREATE TABLE
+     */
+    private buildPrefixColumnsSql;
+    /**
+     * Builds prefix column names for use in queries
+     */
+    private getPrefixColumnNames;
+    /**
+     * Applies prefix filters to a Supabase query builder
+     */
+    private applyPrefixFilters;
+    /**
+     * Gets prefix values as an object for inserts
+     */
+    private getPrefixInsertValues;
+    /**
+     * Builds WHERE clause conditions for prefix filtering with inline values (for raw SQL)
+     * @returns SQL conditions string with values inlined
+     */
+    private buildPrefixWhereSql;
+    /**
+     * Regex for validating SQL literal-safe strings.
+     * Used for quoted values (e.g. queue names/IDs) and only allows alphanumeric
+     * characters, underscores, hyphens, colons, and periods.
+     */
+    private static readonly SAFE_SQL_VALUE_RE;
+    /**
+     * Validates that a string value is safe for use as a quoted SQL literal.
+     * Throws an error if the value contains characters outside SAFE_SQL_VALUE_RE.
+     */
+    private validateSqlValue;
+    /**
+     * Escapes a string value for use in SQL
+     */
+    private escapeSqlString;
+    setupDatabase(): Promise<void>;
+    /**
+     * 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 status - The status to filter by
+     * @param num - Maximum number of jobs to return
+     * @returns An array of jobs
+     */
+    peek(status?: JobStatus, num?: number): Promise<JobStorageFormat<Input, Output>[]>;
+    /**
+     * Retrieves the next available job that is ready to be processed.
+     * Uses atomic UPDATE with subquery SELECT FOR UPDATE SKIP LOCKED to prevent race conditions.
+     * @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>;
+    private getAllJobs;
+    /**
+     * 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>;
+    /**
+     * Releases a claimed job without consuming a retry attempt.
+     */
+    release(jobId: unknown): 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>;
+    /**
+     * 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 saveProgress method
+     */
+    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>;
+    /**
+     * Checks if a job from a realtime payload matches the specified prefix filter
+     * @param job - The job record from the realtime payload
+     * @param prefixFilter - The prefix filter to match against (undefined = use instance prefixes, {} = no filter)
+     */
+    private matchesPrefixFilter;
+    /**
+     * Checks if a prefix filter is custom (different from instance's prefixes).
+     */
+    private isCustomPrefixFilter;
+    private getAllJobsWithFilter;
+    /**
+     * Subscribes to changes in the queue.
+     * Uses Supabase realtime by default.
+     *
+     * @param callback - Function called when a change occurs
+     * @param options - Subscription options including prefix filter
+     * @returns Unsubscribe function
+     */
+    subscribeToChanges(callback: (change: QueueChangePayload<Input, Output>) => void, options?: QueueSubscribeOptions): () => void;
+    /**
+     * Subscribe using Supabase realtime (protected).
+     *
+     * @param callback - Function called when a change occurs
+     * @param prefixFilter - Optional prefix filter (undefined = use instance prefixes, {} = no filter)
+     * @returns Unsubscribe function
+     */
+    protected subscribeToChangesWithRealtime(callback: (change: QueueChangePayload<Input, Output>) => void, prefixFilter?: Readonly<Record<string, string | number>>): () => void;
+    /**
+     * Gets or creates the shared polling subscription manager for normal subscriptions (fallback).
+     * This ensures all normal subscriptions share a single polling loop per interval.
+     */
+    private getPollingManager;
+    /**
+     * Creates a dedicated polling subscription for custom prefix filters (fallback).
+     * This runs separately from the normal polling manager with DB-level filtering.
+     */
+    private subscribeWithCustomPrefixFilterPolling;
+    /**
+     * Subscribe using polling (protected, available as fallback).
+     *
+     * Normal subscriptions (no custom prefix filter) share a single polling loop for efficiency.
+     * Custom prefix filter subscriptions get their own dedicated polling loop with DB-level filtering.
+     *
+     * @param callback - Function called when a change occurs
+     * @param options - Subscription options including interval and prefix filter
+     * @returns Unsubscribe function
+     */
+    protected subscribeToChangesWithPolling(callback: (change: QueueChangePayload<Input, Output>) => void, options?: QueueSubscribeOptions): () => void;
+}
+//# sourceMappingURL=SupabaseQueueStorage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SupabaseQueueStorage.d.ts","sourceRoot":"","sources":["../../src/job-queue/SupabaseQueueStorage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAmB,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG7E,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAElB,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,sBAAsB,gEAElC,CAAC;AAEF;;;GAGG;AACH,qBAAa,oBAAoB,CAAC,KAAK,EAAE,MAAM,CAAE,YAAW,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC;IAepF,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM;IAdtC,SAAgB,KAAK,EAAG,SAAS,CAAU;IAC3C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAC1C,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IACrD,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;IAC3E,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IACrC,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,cAAc,CAIN;IAEhB,YACE,MAAM,EAAE,cAAc,EACH,SAAS,EAAE,MAAM,EACpC,OAAO,CAAC,EAAE,mBAAmB,EAY9B;IAED;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAS7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAQ7B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAqB3B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAyB;IAElE;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IASxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAIV,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CA8D1C;IAED;;;;OAIG;IACU,GAAG,CAAC,GAAG,EAAE,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAsCvE;IAED;;;;OAIG;IACU,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,CAiBlF;IAED;;;;;OAKG;IACU,IAAI,CACf,MAAM,GAAE,SAA6B,EACrC,GAAG,GAAE,MAAY,GAChB,OAAO,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,CAe5C;IAED;;;;;OAKG;IACU,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,CAkCxF;IAED;;;;OAIG;IACU,IAAI,CAAC,MAAM,YAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAa7D;YAQa,UAAU;IAWxB;;;;;OAKG;IACU,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CA0HhF;IAED;;OAEG;IACU,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBlD;IAED;;OAEG;IACU,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAMtC;IAED;;;;OAIG;IACU,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoBhE;IAED;;;;;OAKG;IACU,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAWhD;IAED;;;;OAIG;IACU,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAY3F;IAED;;OAEG;IACU,YAAY,CACvB,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CAef;IAED;;OAEG;IACU,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAWjD;IAED;;;;OAIG;IACU,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe3F;IAED;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAiC3B;;OAEG;IACH,OAAO,CAAC,oBAAoB;YA8Bd,oBAAoB;IAgBlC;;;;;;;OAOG;IACI,kBAAkB,CACvB,QAAQ,EAAE,CAAC,MAAM,EAAE,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAC7D,OAAO,CAAC,EAAE,qBAAqB,GAC9B,MAAM,IAAI,CAEZ;IAED;;;;;;OAMG;IACH,SAAS,CAAC,8BAA8B,CACtC,QAAQ,EAAE,CAAC,MAAM,EAAE,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAC7D,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,GACvD,MAAM,IAAI,CA+CZ;IAED;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IA2BzB;;;OAGG;IACH,OAAO,CAAC,sCAAsC;IA8C9C;;;;;;;;;OASG;IACH,SAAS,CAAC,6BAA6B,CACrC,QAAQ,EAAE,CAAC,MAAM,EAAE,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAC7D,OAAO,CAAC,EAAE,qBAAqB,GAC9B,MAAM,IAAI,CAgBZ;CACF"}

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

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { SupabaseClient } from "@supabase/supabase-js";
+import type { PrefixColumn } from "@workglow/job-queue";
+import type { IRateLimiterStorage, RateLimiterStorageOptions, RateLimiterStorageScope } from "@workglow/job-queue";
+export declare const SUPABASE_RATE_LIMITER_STORAGE: import("@workglow/util").ServiceToken<IRateLimiterStorage>;
+/**
+ * Supabase implementation of rate limiter storage.
+ * Manages execution records and next available times for rate limiting.
+ */
+export declare class SupabaseRateLimiterStorage implements IRateLimiterStorage {
+    readonly scope: RateLimiterStorageScope;
+    protected readonly client: SupabaseClient;
+    protected readonly prefixes: readonly PrefixColumn[];
+    protected readonly prefixValues: Readonly<Record<string, string | number>>;
+    protected readonly executionTableName: string;
+    protected readonly nextAvailableTableName: string;
+    constructor(client: unknown, options?: RateLimiterStorageOptions);
+    /**
+     * Gets the SQL column type for a prefix column (Supabase supports UUID natively).
+     */
+    private getPrefixColumnType;
+    /**
+     * Builds the prefix columns SQL for CREATE TABLE.
+     */
+    private buildPrefixColumnsSql;
+    /**
+     * Builds prefix column names for use in queries.
+     */
+    private getPrefixColumnNames;
+    /**
+     * Applies prefix filters to a Supabase query builder.
+     */
+    private applyPrefixFilters;
+    /**
+     * Gets prefix values as an object for inserts.
+     */
+    private getPrefixInsertValues;
+    setupDatabase(): Promise<void>;
+    /** Stable function name derived from table name (Postgres identifiers ≤63 chars). */
+    private atomicReserveFunctionName;
+    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=SupabaseRateLimiterStorage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SupabaseRateLimiterStorage.d.ts","sourceRoot":"","sources":["../../src/job-queue/SupabaseRateLimiterStorage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,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;IACpE,SAAgB,KAAK,EAAE,uBAAuB,CAAa;IAC3D,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAC1C,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IACrD,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;IAC3E,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IAC9C,SAAS,CAAC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IAElD,YAAY,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,yBAAyB,EAc/D;IAED;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAS7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAQhB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAqG1C;IAED,qFAAqF;IACrF,OAAO,CAAC,yBAAyB;IAIpB,mBAAmB,CAC9B,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CA0BzB;IAEY,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa9E;IAEY,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS7D;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,CAe7B;IAEY,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAiBhF;IAEY,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB3F;IAEY,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAanD;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"}