@workglow/indexeddb 0.2.28

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

@@ -0,0 +1,167 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MigrationOptions } from "../storage/IndexedDbTable";
+import { JobStatus } from "@workglow/job-queue";
+import type { IQueueStorage, JobStorageFormat, PrefixColumn, QueueChangePayload, QueueStorageOptions, QueueSubscribeOptions } from "@workglow/job-queue";
+export declare const INDEXED_DB_QUEUE_STORAGE: import("@workglow/util").ServiceToken<IQueueStorage<any, any>>;
+/**
+ * Extended options for IndexedDB queue storage including prefix support
+ */
+export interface IndexedDbQueueStorageOptions extends QueueStorageOptions, MigrationOptions {
+    /** Enable BroadcastChannel notifications (default: true) */
+    readonly useBroadcastChannel?: boolean;
+    /** Backup polling interval in ms (default: 5000, 0 to disable) */
+    readonly backupPollingIntervalMs?: number;
+}
+/**
+ * IndexedDB implementation of a job queue storage.
+ * Provides storage and retrieval for job execution states using IndexedDB.
+ */
+export declare class IndexedDbQueueStorage<Input, Output> implements IQueueStorage<Input, Output> {
+    readonly queueName: string;
+    readonly scope: "process";
+    private db;
+    private readonly tableName;
+    private readonly migrationOptions;
+    /** The prefix column definitions */
+    protected readonly prefixes: readonly PrefixColumn[];
+    /** The prefix values for filtering */
+    protected readonly prefixValues: Readonly<Record<string, string | number>>;
+    /** Shared hybrid subscription manager */
+    private hybridManager;
+    /** Hybrid subscription options */
+    private readonly hybridOptions;
+    constructor(queueName: string, options?: IndexedDbQueueStorageOptions);
+    /**
+     * Gets prefix column names for use in indexes
+     */
+    private getPrefixColumnNames;
+    /**
+     * Checks if a job matches the current prefix values
+     */
+    private matchesPrefixes;
+    /**
+     * Gets prefix values as an array in column order for index key construction
+     */
+    private getPrefixKeyValues;
+    private getDb;
+    /**
+     * Sets up the IndexedDB database table with the required schema and indexes.
+     * Must be called before using any other methods.
+     */
+    setupDatabase(): Promise<void>;
+    /**
+     * Adds a job to the queue.
+     * @param job - The job to add to the queue.
+     * @returns A promise that resolves to the job id.
+     */
+    add(job: JobStorageFormat<Input, Output>): Promise<unknown>;
+    /**
+     * Retrieves a job from the queue by its id.
+     * @param id - The id of the job to retrieve.
+     * @returns A promise that resolves to the job or undefined if the job is not found.
+     */
+    get(id: unknown): Promise<JobStorageFormat<Input, Output> | undefined>;
+    /**
+     * Retrieves a slice of jobs from the queue.
+     * @param status - The status of the jobs to retrieve.
+     * @param num - The number of jobs to retrieve.
+     * @returns A promise that resolves to an array of jobs.
+     */
+    peek(status?: JobStatus, num?: number): Promise<JobStorageFormat<Input, Output>[]>;
+    /**
+     * Retrieves the next job from the queue using optimistic locking. In case multiple workers
+     * claim the same job, the first worker to claim it will process it and the other workers will return undefined.
+     * This ONLY happens if workers are running in multiple tabs.
+     *
+     * IndexedDB uses snapshot isolation, so concurrent transactions can both see the same
+     * PENDING job. To prevent processing the same job multiple times, this method:
+     * 1. Claims a job by setting it to PROCESSING with a unique claim token
+     * 2. After the transaction completes, re-reads the job to verify the claim succeeded
+     * 3. If another worker claimed it first (different claim token), returns undefined
+     *
+     * @param workerId - Worker ID to associate with the job (required)
+     * @returns A promise that resolves to the next job or undefined if the queue is empty.
+     */
+    next(workerId: string): Promise<JobStorageFormat<Input, Output> | undefined>;
+    /**
+     * Retrieves the number of jobs in the queue.
+     * Returns the count of jobs in the queue.
+     */
+    size(status?: "PENDING"): Promise<number>;
+    /**
+     * Marks a job as complete with its output or error.
+     */
+    complete(job: JobStorageFormat<Input, Output>): Promise<void>;
+    /**
+     * Releases a claimed job without consuming a retry attempt.
+     */
+    release(id: unknown): Promise<void>;
+    /**
+     * Aborts a job in the queue.
+     */
+    abort(id: unknown): Promise<void>;
+    /**
+     * Gets jobs by their run ID.
+     */
+    getByRunId(job_run_id: string): Promise<JobStorageFormat<Input, Output>[]>;
+    /**
+     * Deletes all jobs from the queue.
+     */
+    deleteAll(): Promise<void>;
+    /**
+     * Gets the output for a given input.
+     */
+    outputForInput(input: Input): Promise<Output | null>;
+    /**
+     * Saves progress updates for a job.
+     */
+    saveProgress(id: unknown, progress: number, message: string, details: Record<string, any> | null): Promise<void>;
+    private put;
+    /**
+     * Deletes a job by its ID.
+     */
+    delete(id: 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>;
+    private getAllJobs;
+    private getAllJobsWithFilter;
+    /**
+     * Checks if a prefix filter is custom (different from instance's prefixes).
+     */
+    private isCustomPrefixFilter;
+    /**
+     * Gets or creates the shared hybrid subscription manager for normal subscriptions.
+     * This ensures all normal subscriptions share a single manager.
+     */
+    private getHybridManager;
+    /**
+     * Creates a dedicated polling subscription for custom prefix filters.
+     * This runs separately from the normal polling manager.
+     */
+    private subscribeWithCustomPrefixFilter;
+    /**
+     * Subscribes to changes in the queue.
+     * Uses polling since IndexedDB has no native cross-tab change notifications.
+     *
+     * 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 polling interval and prefix filter
+     * @returns Unsubscribe function
+     */
+    subscribeToChanges(callback: (change: QueueChangePayload<Input, Output>) => void, options?: QueueSubscribeOptions): () => void;
+    /**
+     * Cleanup method to destroy the hybrid manager
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=IndexedDbQueueStorage.d.ts.map

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

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

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

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MigrationOptions } from "../storage/IndexedDbTable";
+import type { PrefixColumn } from "@workglow/job-queue";
+import type { IRateLimiterStorage, RateLimiterStorageOptions, RateLimiterStorageScope } from "@workglow/job-queue";
+export declare const INDEXED_DB_RATE_LIMITER_STORAGE: import("@workglow/util").ServiceToken<IRateLimiterStorage>;
+/**
+ * Extended options for IndexedDB rate limiter storage including prefix support.
+ */
+export interface IndexedDbRateLimiterStorageOptions extends RateLimiterStorageOptions, MigrationOptions {
+}
+/**
+ * IndexedDB implementation of rate limiter storage.
+ * Manages execution records and next available times for rate limiting.
+ *
+ * Atomicity is `"process"`-scoped (browser tab) and the `next_available_at`
+ * pre-check inside {@link tryReserveExecution} runs in a separate IDB
+ * transaction from the count-and-insert. See {@link tryReserveExecution} for
+ * the full caveat — do not assume cross-store atomicity.
+ */
+export declare class IndexedDbRateLimiterStorage implements IRateLimiterStorage {
+    /**
+     * `"process"` — IndexedDB is per-origin and shared across tabs but not across
+     * processes (different machines, server processes). Within a single tab the
+     * `readwrite` transaction below provides atomicity.
+     */
+    readonly scope: RateLimiterStorageScope;
+    private executionDb;
+    private nextAvailableDb;
+    private readonly executionTableName;
+    private readonly nextAvailableTableName;
+    private readonly migrationOptions;
+    /** The prefix column definitions */
+    protected readonly prefixes: readonly PrefixColumn[];
+    /** The prefix values for filtering */
+    protected readonly prefixValues: Readonly<Record<string, string | number>>;
+    constructor(options?: IndexedDbRateLimiterStorageOptions);
+    /**
+     * Gets prefix column names for use in indexes.
+     */
+    private getPrefixColumnNames;
+    /**
+     * Checks if a record matches the current prefix values.
+     */
+    private matchesPrefixes;
+    /**
+     * Gets prefix values as an array in column order for index key construction.
+     */
+    private getPrefixKeyValues;
+    private getExecutionDb;
+    private getNextAvailableDb;
+    setupDatabase(): Promise<void>;
+    /**
+     * Atomically reserves an execution slot in IndexedDB.
+     *
+     * Atomicity caveat: this implementation only serializes the `count + insert`
+     * pair (under a single `readwrite` IDB transaction over the executions
+     * store). The `next_available_at` lookup is a soft pre-check performed
+     * BEFORE the tx, because the executions and next-available object stores
+     * live in separate `IDBDatabase` instances by design (one
+     * `ensureIndexedDbTable` call each) and IDB transaction scope cannot cross
+     * databases. This is acceptable for IndexedDB's `"process"` scope: rate-
+     * limit overshoot from a stale next-available read is bounded by single-
+     * tab serial execution, and the stricter count check is what protects the
+     * primary maxExecutions invariant.
+     */
+    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=IndexedDbRateLimiterStorage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IndexedDbRateLimiterStorage.d.ts","sourceRoot":"","sources":["../../src/job-queue/IndexedDbRateLimiterStorage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAGL,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EACV,mBAAmB,EACnB,yBAAyB,EACzB,uBAAuB,EACxB,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,+BAA+B,4DAE3C,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,kCACf,SAAQ,yBAAyB,EAAE,gBAAgB;CAAG;AAqBxD;;;;;;;;GAQG;AACH,qBAAa,2BAA4B,YAAW,mBAAmB;IACrE;;;;OAIG;IACH,SAAgB,KAAK,EAAE,uBAAuB,CAAa;IAC3D,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,eAAe,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IACpD,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;IAE3E,YAAY,OAAO,GAAE,kCAAuC,EAc3D;IAED;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;OAEG;IACH,OAAO,CAAC,eAAe;IASvB;;OAEG;IACH,OAAO,CAAC,kBAAkB;YAIZ,cAAc;YAMd,kBAAkB;IAMnB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAqC1C;IAED;;;;;;;;;;;;;OAaG;IACU,mBAAmB,CAC9B,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAqEzB;IAEY,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAc9E;IAEY,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB7D;IAEY,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgC1F;IAEY,0BAA0B,CACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAkC7B;IAEY,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAoBhF;IAEY,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B3F;IAEY,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2CnD;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"}