@odunlamizo/node-river 1.0.8 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # node-river
 
-Node.js library to support River integration.
+Node.js client for [River](https://riverqueue.com), a Postgres-backed job queue. Supports job insertion and worker-based processing with per-queue concurrency control.
 
 ## Installation
 
@@ -8,62 +8,49 @@ Node.js library to support River integration.
 npm install @odunlamizo/node-river
 ```
 
-## Usage
-
-### 1. Setup
+## Setup
 
 ```ts
-import { RiverClient } from 'node-river';
-import { PgDriver } from 'node-river/drivers/pg';
+import { RiverClient } from '@odunlamizo/node-river';
+import { PgDriver } from '@odunlamizo/node-river/drivers/pg';
 
 const driver = new PgDriver({ connectionString: process.env.DATABASE_URL! });
+
 const client = new RiverClient(driver, {
-  defaultQueue: 'default',
-  maxAttempts: 1,
+  queues: {
+    default: { concurrency: 10 },
+    emails: { concurrency: 50 },
+  },
+  maxAttempts: 3,
 });
-```
 
-### 2. Verify Connection
-
-```ts
 await client.verifyConnection();
 ```
 
-### 3. Insert a Job
+## Inserting Jobs
 
-```ts
-const result = await client.insert({ kind: 'sort_args', strings: ['banana', 'apple', 'cherry'] });
-console.log(result.job); // Job details
-```
-
-### 4. Insert Unique Job
+`queue` is required on every insert — there is no default fallback.
 
 ```ts
+// Single job
 const result = await client.insert(
-  { kind: 'sort_args', strings: ['banana', 'apple', 'cherry'] },
-  { uniqueOpts: { byArgs: ['strings'] } },
+  { kind: 'send_email', to: 'user@example.com' },
+  { queue: 'emails' },
 );
-console.log(result.skipped); // true if duplicate
-```
-
-### 5. Insert Many Jobs Transactionally
-
-```ts
-const jobs = [
-  { args: { kind: 'sort_args', strings: ['a', 'b'] }, opts: {} },
-  { args: { kind: 'sort_args', strings: ['c', 'd'] }, opts: {} },
-];
-const results = await client.insertMany(jobs);
-console.log(results.length); // 2
-```
+console.log(result.job); // inserted Job record
+console.log(result.skipped); // true if deduplicated
 
-### 6. Use Transactions
+// Multiple jobs in one transaction (all succeed or all roll back)
+const results = await client.insertMany([
+  { args: { kind: 'send_email', to: 'a@example.com' }, opts: { queue: 'emails' } },
+  { args: { kind: 'send_email', to: 'b@example.com' }, opts: { queue: 'emails' } },
+]);
 
-```ts
+// Inside an existing transaction
 const tx = await driver.getTx();
 try {
   await tx.query('BEGIN');
-  const result = await client.insertTx(tx, { kind: 'sort_args', strings: ['x', 'y', 'z'] });
+  await client.insertTx(tx, { kind: 'send_email', to: 'c@example.com' }, { queue: 'emails' });
   await tx.query('COMMIT');
 } catch (e) {
   await tx.query('ROLLBACK');
@@ -73,6 +60,73 @@ try {
 }
 ```
 
+## Unique Jobs
+
+Use `uniqueOpts` to prevent duplicate jobs from being enqueued.
+
+```ts
+// Deduplicate by specific args
+await client.insert(
+  { kind: 'send_email', to: 'user@example.com' },
+  { queue: 'emails', uniqueOpts: { byArgs: ['to'] } },
+);
+
+// Deduplicate by queue + args
+await client.insert(
+  { kind: 'send_email', to: 'user@example.com' },
+  { queue: 'emails', uniqueOpts: { byQueue: true, byArgs: ['to'] } },
+);
+
+// Deduplicate within a time window (e.g. one per 60-second period)
+await client.insert(
+  { kind: 'send_email', to: 'user@example.com' },
+  { queue: 'emails', uniqueOpts: { byPeriod: 60 }, scheduledAt: new Date() },
+);
+```
+
+## Processing Jobs (Workers)
+
+Implement the `Worker<T>` interface for each job kind, register it with `addWorker`, then call `work()`. Each queue is polled independently at the configured concurrency limit.
+
+```ts
+import { Worker, Job } from '@odunlamizo/node-river/types';
+
+interface SendEmailArgs {
+  kind: 'send_email';
+  to: string;
+}
+
+class SendEmailWorker implements Worker<SendEmailArgs> {
+  async work(job: Job<SendEmailArgs>): Promise<void> {
+    await sendEmail(job.args.to);
+  }
+}
+
+client.addWorker('send_email', new SendEmailWorker());
+client.work(); // starts polling all configured queues
+```
+
+Throwing inside `work()` marks the job as failed. If `attempt < maxAttempts` it is retried with exponential backoff; otherwise it is discarded.
+
+## Shutdown
+
+Always call `close()` on shutdown to drain the poll timer and release database connections.
+
+```ts
+process.on('SIGTERM', async () => {
+  await client.close();
+});
+```
+
+## Configuration
+
+| Option         | Type                                      | Description                                                         |
+| -------------- | ----------------------------------------- | ------------------------------------------------------------------- |
+| `queues`       | `Record<string, { concurrency: number }>` | Queues to poll and their concurrency limits. Required for `work()`. |
+| `maxAttempts`  | `number`                                  | Default max attempts for inserted jobs.                             |
+| `pollInterval` | `number`                                  | Milliseconds between polls. Defaults to `1000`.                     |
+| `clientId`     | `string`                                  | Unique ID for this client instance. Defaults to `hostname-pid`.     |
+
 ## License
 
 MIT

package/dist/driver-BhanG0yg.d.cts

@@ -0,0 +1,70 @@
+import { J as JobArgs, I as InsertOpts, a as InsertResult, b as Job } from './insert-result-DWZkRtk9.cjs';
+
+/**
+ * Common interface all River drivers must implement (e.g. PgDriver).
+ * `Tx` is the driver-specific transaction type (e.g. `PoolClient` for pg).
+ */
+interface Driver<Tx> {
+    /**
+     * Verifies the driver can reach the database. Throws if the connection fails.
+     */
+    verifyConnection(): Promise<void>;
+    /**
+     * Closes all database connections and frees resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Inserts a single job into the queue.
+     * @param args - Job arguments including `kind` and any job-specific fields.
+     * @param opts - Insertion options: queue, maxAttempts, priority, tags, etc.
+     * @returns The inserted job and a `skipped` flag if deduplicated by uniqueness.
+     */
+    insert<T extends JobArgs>(args: T, opts: InsertOpts): Promise<InsertResult<T>>;
+    /**
+     * Inserts a single job within an existing transaction.
+     * @param tx - The active transaction (type is driver-specific).
+     * @param args - Job arguments including `kind` and any job-specific fields.
+     * @param opts - Insertion options: queue, maxAttempts, priority, tags, etc.
+     * @returns The inserted job and a `skipped` flag if deduplicated by uniqueness.
+     */
+    insertTx<T extends JobArgs>(tx: Tx, args: T, opts: InsertOpts): Promise<InsertResult<T>>;
+    /**
+     * Inserts multiple jobs in a single transaction. Rolls back all if any fail.
+     * @param jobs - Array of `{ args, opts }` pairs, one per job.
+     * @returns An array of InsertResult objects in the same order as the input.
+     */
+    insertMany<T extends JobArgs>(jobs: {
+        args: T;
+        opts: InsertOpts;
+    }[]): Promise<InsertResult<T>[]>;
+    /**
+     * Returns a new transaction object for use with `insertTx`.
+     * Caller is responsible for committing or rolling back.
+     */
+    getTx(): Promise<Tx>;
+    /**
+     * Atomically claims up to `limit` available jobs and marks them as running.
+     * Uses `FOR UPDATE SKIP LOCKED` to prevent concurrent workers from double-claiming.
+     * @param queue - The queue to fetch jobs from.
+     * @param limit - Max number of jobs to claim, based on available concurrency slots.
+     * @param clientId - This client's ID, appended to the job's `attemptedBy` list.
+     * @returns Array of claimed jobs ready to be worked.
+     */
+    getAvailableJobs(queue: string, limit: number, clientId: string): Promise<Job[]>;
+    /**
+     * Marks a job as `completed` and stamps `finalizedAt`.
+     * @param id - The ID of the job to complete.
+     */
+    completeJob(id: number): Promise<void>;
+    /**
+     * Marks a job as `retryable` (with exponential backoff) or `discarded` (if max attempts reached).
+     * Appends the error details to the job's `errors` array.
+     * @param id - The ID of the job that failed.
+     * @param error - The error thrown by the worker.
+     * @param attempt - The attempt number that failed.
+     * @param maxAttempts - The job's maximum allowed attempts.
+     */
+    failJob(id: number, error: Error, attempt: number, maxAttempts: number): Promise<void>;
+}
+
+export type { Driver as D };

package/dist/driver-DQ6PVYVO.d.ts

@@ -0,0 +1,70 @@
+import { J as JobArgs, I as InsertOpts, a as InsertResult, b as Job } from './insert-result-DWZkRtk9.js';
+
+/**
+ * Common interface all River drivers must implement (e.g. PgDriver).
+ * `Tx` is the driver-specific transaction type (e.g. `PoolClient` for pg).
+ */
+interface Driver<Tx> {
+    /**
+     * Verifies the driver can reach the database. Throws if the connection fails.
+     */
+    verifyConnection(): Promise<void>;
+    /**
+     * Closes all database connections and frees resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Inserts a single job into the queue.
+     * @param args - Job arguments including `kind` and any job-specific fields.
+     * @param opts - Insertion options: queue, maxAttempts, priority, tags, etc.
+     * @returns The inserted job and a `skipped` flag if deduplicated by uniqueness.
+     */
+    insert<T extends JobArgs>(args: T, opts: InsertOpts): Promise<InsertResult<T>>;
+    /**
+     * Inserts a single job within an existing transaction.
+     * @param tx - The active transaction (type is driver-specific).
+     * @param args - Job arguments including `kind` and any job-specific fields.
+     * @param opts - Insertion options: queue, maxAttempts, priority, tags, etc.
+     * @returns The inserted job and a `skipped` flag if deduplicated by uniqueness.
+     */
+    insertTx<T extends JobArgs>(tx: Tx, args: T, opts: InsertOpts): Promise<InsertResult<T>>;
+    /**
+     * Inserts multiple jobs in a single transaction. Rolls back all if any fail.
+     * @param jobs - Array of `{ args, opts }` pairs, one per job.
+     * @returns An array of InsertResult objects in the same order as the input.
+     */
+    insertMany<T extends JobArgs>(jobs: {
+        args: T;
+        opts: InsertOpts;
+    }[]): Promise<InsertResult<T>[]>;
+    /**
+     * Returns a new transaction object for use with `insertTx`.
+     * Caller is responsible for committing or rolling back.
+     */
+    getTx(): Promise<Tx>;
+    /**
+     * Atomically claims up to `limit` available jobs and marks them as running.
+     * Uses `FOR UPDATE SKIP LOCKED` to prevent concurrent workers from double-claiming.
+     * @param queue - The queue to fetch jobs from.
+     * @param limit - Max number of jobs to claim, based on available concurrency slots.
+     * @param clientId - This client's ID, appended to the job's `attemptedBy` list.
+     * @returns Array of claimed jobs ready to be worked.
+     */
+    getAvailableJobs(queue: string, limit: number, clientId: string): Promise<Job[]>;
+    /**
+     * Marks a job as `completed` and stamps `finalizedAt`.
+     * @param id - The ID of the job to complete.
+     */
+    completeJob(id: number): Promise<void>;
+    /**
+     * Marks a job as `retryable` (with exponential backoff) or `discarded` (if max attempts reached).
+     * Appends the error details to the job's `errors` array.
+     * @param id - The ID of the job that failed.
+     * @param error - The error thrown by the worker.
+     * @param attempt - The attempt number that failed.
+     * @param maxAttempts - The job's maximum allowed attempts.
+     */
+    failJob(id: number, error: Error, attempt: number, maxAttempts: number): Promise<void>;
+}
+
+export type { Driver as D };

package/dist/drivers/pg/index.cjs

@@ -98,9 +98,6 @@ var PgDriver = class {
     }
   }
   async insertTx(tx, args, opts) {
-    if (!opts.queue) {
-      throw new Error("Queue name is required in InsertOpts");
-    }
     if (!opts.maxAttempts) {
       throw new Error("maxAttempts is required in InsertOpts");
     }
@@ -204,6 +201,80 @@ var PgDriver = class {
   async getTx() {
     return this.pool.connect();
   }
+  async getAvailableJobs(queue, limit, clientId) {
+    const result = await this.pool.query(
+      `
+      UPDATE river_job
+      SET state = 'running',
+          attempt = attempt + 1,
+          attempted_at = NOW(),
+          attempted_by = array_append(COALESCE(attempted_by, '{}'), $1)
+      WHERE id IN (
+        SELECT id FROM river_job
+        WHERE state = 'available'
+          AND queue = $2
+          AND scheduled_at <= NOW()
+        ORDER BY priority, scheduled_at, id
+        LIMIT $3
+        FOR UPDATE SKIP LOCKED
+      )
+      RETURNING
+        id,
+        state,
+        attempt,
+        max_attempts as "maxAttempts",
+        attempted_at as "attemptedAt",
+        created_at as "createdAt",
+        finalized_at as "finalizedAt",
+        scheduled_at as "scheduledAt",
+        priority,
+        args,
+        attempted_by as "attemptedBy",
+        errors,
+        kind,
+        metadata,
+        queue,
+        tags,
+        unique_key as "uniqueKey",
+        unique_states as "uniqueStates"
+    `,
+      [clientId, queue, limit]
+    );
+    return result.rows;
+  }
+  async completeJob(id) {
+    await this.pool.query(
+      `
+      UPDATE river_job
+      SET state = $1,
+          finalized_at = NOW()
+      WHERE id = $2
+    `,
+      ["completed" /* Completed */, id]
+    );
+  }
+  async failJob(id, error, attempt, maxAttempts) {
+    const isDiscarded = attempt >= maxAttempts;
+    const backoffSeconds = Math.pow(2, attempt);
+    const errorEntry = JSON.stringify({ error: error.message, attempt });
+    await this.pool.query(
+      `
+      UPDATE river_job
+      SET state = $1,
+          finalized_at = CASE WHEN $2 THEN NOW() ELSE NULL END,
+          scheduled_at = CASE WHEN $2 THEN scheduled_at ELSE NOW() + ($3 || ' seconds')::interval END,
+          errors = array_append(COALESCE(errors, '{}'), $4::jsonb)
+      WHERE id = $5
+    `,
+      [
+        isDiscarded ? "discarded" /* Discarded */ : "retryable" /* Retryable */,
+        isDiscarded,
+        backoffSeconds,
+        errorEntry,
+        id
+      ]
+    );
+  }
   /**
    * Helper to map a DB row to a Job<T> and InsertResult.
    */

package/dist/drivers/pg/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/utils/mappers.ts","../../../src/drivers/pg/pg-driver.ts"],"names":["crypto","Buffer","Pool","query","values","result","row"],"mappings":"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","file":"index.cjs","sourcesContent":["import { Buffer } from 'buffer';\nimport crypto from 'crypto';\nimport { InsertOpts, JobArgs, JobState } from '../types';\n\n/**\n * Converts a bit(8) Buffer to an array of JobState values using the bit order from river_job_state_in_bitmask.\n *\n * @param bitmask - The Buffer representing the job state bitmask.\n * @returns An array of JobState values corresponding to the set bits, or null if the bitmask is null.\n */\nexport const bitmaskToJobStates = (bitmask: Buffer | null): JobState[] | null => {\n  if (!bitmask || bitmask.length === 0) return null;\n  // Bit order: 7=available, 6=cancelled, 5=completed, 4=discarded, 3=pending, 2=retryable, 1=running, 0=scheduled\n  const allStates: JobState[] = [\n    JobState.Available, // 7\n    JobState.Cancelled, // 6\n    JobState.Completed, // 5\n    JobState.Discarded, // 4\n    JobState.Pending, // 3\n    JobState.Retryable, // 2\n    JobState.Running, // 1\n    JobState.Scheduled, // 0\n  ];\n  const byte = bitmask[0];\n  // Map bits 7..0 to allStates\n  return allStates.filter((_, i) => (byte & (1 << (7 - i))) !== 0);\n};\n\n/**\n * Maps job args and unique options to a unique key buffer.\n *\n * @param args - The job arguments to use for uniqueness computation.\n * @param opts - The insertion options, including unique options.\n * @returns A Buffer containing the unique key, or undefined if no unique options are set.\n */\nexport const mapToUniqueKey = (args: JobArgs, opts: InsertOpts): Buffer | undefined => {\n  const uniqueOpts = opts.uniqueOpts;\n  if (!uniqueOpts) return undefined;\n\n  const keyParts: Record<string, unknown> = {};\n\n  if (!uniqueOpts.excludeKind) {\n    keyParts.kind = args.kind;\n  }\n\n  if (uniqueOpts.byArgs === true) {\n    keyParts.args = args;\n  } else if (Array.isArray(uniqueOpts.byArgs)) {\n    keyParts.args = Object.fromEntries(uniqueOpts.byArgs.sort().map((k) => [k, args[k]]));\n  }\n\n  if (uniqueOpts.byQueue) {\n    keyParts.queue = opts.queue;\n  }\n\n  if (uniqueOpts.byPeriod && opts.scheduledAt) {\n    const date = new Date(opts.scheduledAt);\n    const period = uniqueOpts.byPeriod;\n    const timestamp = Math.floor(date.getTime() / 1000);\n    const rounded = timestamp - (timestamp % period);\n    keyParts.period = rounded;\n  }\n\n  const hash = crypto.createHash('sha256').update(JSON.stringify(keyParts)).digest();\n\n  return Buffer.from(hash);\n};\n","// RiverQueue driver implementation using the 'pg' library.\nimport { Buffer } from 'buffer';\nimport { Pool, PoolClient, PoolConfig } from 'pg';\nimport { InsertOpts, InsertResult, Job, JobArgs } from '../../types';\nimport { bitmaskToJobStates, mapToUniqueKey } from '../../utils';\nimport Driver from '../driver';\nimport Options from './pg-options';\n\n// Implements the RiverQueue Driver interface using the 'pg' library.\nexport default class PgDriver implements Driver<PoolClient> {\n  private readonly pool: Pool;\n\n  /**\n   * Creates a new PgDriver instance.\n   * @param options - Options for configuring the RiverQueue pg driver connection pool. Fields include:\n   *   - connectionString: Database connection string\n   *   - connectionTimeoutMillis: Optional, connection timeout in milliseconds\n   *   - idleTimeoutMillis: Optional, idle timeout in milliseconds\n   *   - max: Optional, maximum number of clients in the pool\n   */\n  constructor(options: Options) {\n    const config: PoolConfig = { ...options };\n    this.pool = new Pool(config);\n  }\n\n  async verifyConnection(): Promise<void> {\n    try {\n      const client = await this.pool.connect();\n      try {\n        await client.query('SELECT 1');\n      } finally {\n        client.release();\n      }\n    } catch (error) {\n      throw new Error(\n        `Database connection failed: ${error instanceof Error ? error.message : String(error)}`,\n      );\n    }\n  }\n\n  async close(): Promise<void> {\n    await this.pool.end();\n  }\n\n  async insert<T extends JobArgs>(args: T, opts: InsertOpts): Promise<InsertResult<T>> {\n    const client = await this.pool.connect();\n    try {\n      return await this.insertTx(client, args, opts);\n    } finally {\n      client.release();\n    }\n  }\n\n  async insertTx<T extends JobArgs>(\n    tx: PoolClient,\n    args: T,\n    opts: InsertOpts,\n  ): Promise<InsertResult<T>> {\n    if (!opts.queue) {\n      throw new Error('Queue name is required in InsertOpts');\n    }\n\n    if (!opts.maxAttempts) {\n      throw new Error('maxAttempts is required in InsertOpts');\n    }\n\n    let uniqueKey: Buffer | undefined;\n    if (opts.uniqueOpts) {\n      uniqueKey = mapToUniqueKey(args, opts);\n    }\n\n    if (uniqueKey) {\n      const stateList = opts.uniqueOpts?.byState || [];\n\n      let query = 'SELECT * FROM river_job WHERE unique_key = $1';\n      let values: (Buffer | string[])[] = [uniqueKey];\n\n      if (stateList.length > 0) {\n        query += ' AND state = ANY($2)';\n        values.push(stateList);\n      }\n\n      query += ' LIMIT 1';\n\n      const result = await tx.query<Omit<Job, 'uniqueStates'> & { uniqueStates: Buffer | null }>(\n        query,\n        values,\n      );\n\n      if (result.rows.length > 0) {\n        const row = result.rows[0];\n\n        return this.mapRowToInsertResult(row, true);\n      }\n    }\n\n    const { kind, ...restArgs } = args;\n    const columns = ['kind', 'args', 'queue', 'max_attempts'];\n    const values: (string | number | Buffer)[] = [\n      kind,\n      JSON.stringify(restArgs),\n      opts.queue,\n      opts.maxAttempts,\n    ];\n\n    if (opts.tags) {\n      columns.push('tags');\n      values.push(JSON.stringify(opts.tags));\n    }\n\n    if (opts.priority) {\n      columns.push('priority');\n      values.push(opts.priority);\n    }\n\n    if (opts.metadata) {\n      columns.push('metadata');\n      values.push(JSON.stringify(opts.metadata));\n    }\n\n    if (opts.scheduledAt) {\n      columns.push('scheduled_at');\n      values.push(\n        opts.scheduledAt instanceof Date ? opts.scheduledAt.toISOString() : opts.scheduledAt,\n      );\n    }\n\n    if (uniqueKey) {\n      columns.push('unique_key');\n      values.push(uniqueKey);\n    }\n\n    const placeholders = columns.map((_, i) => `$${i + 1}`);\n    const query = `INSERT INTO river_job (${columns.join(', ')}) VALUES (${placeholders.join(', ')}) RETURNING\n      id,\n      state,\n      attempt,\n      max_attempts as \"maxAttempts\",\n      attempted_at as \"attemptedAt\",\n      created_at as \"createdAt\",\n      finalized_at as \"finalizedAt\",\n      scheduled_at as \"scheduledAt\",\n      priority,\n      args,\n      attempted_by as \"attemptedBy\",\n      errors,\n      kind,\n      metadata,\n      queue,\n      tags,\n      unique_key as \"uniqueKey\",\n      unique_states as \"uniqueStates\"`;\n    const result = await tx.query<Omit<Job, 'uniqueStates'> & { uniqueStates: Buffer | null }>(\n      query,\n      values,\n    );\n\n    const row = result.rows[0];\n    if (!row) return row;\n\n    return this.mapRowToInsertResult(row, false);\n  }\n\n  async insertMany<T extends JobArgs>(\n    jobs: { args: T; opts: InsertOpts }[],\n  ): Promise<InsertResult<T>[]> {\n    const client = await this.pool.connect();\n    try {\n      await client.query('BEGIN');\n\n      const results: InsertResult<T>[] = [];\n      for (const job of jobs) {\n        results.push(await this.insertTx(client, job.args, job.opts));\n      }\n\n      await client.query('COMMIT');\n\n      return results;\n    } catch (error) {\n      await client.query('ROLLBACK');\n\n      throw error;\n    } finally {\n      client.release();\n    }\n  }\n\n  async getTx(): Promise<PoolClient> {\n    return this.pool.connect();\n  }\n\n  /**\n   * Helper to map a DB row to a Job<T> and InsertResult.\n   */\n  private mapRowToInsertResult<T extends JobArgs>(\n    row: Omit<Job, 'uniqueStates'> & { uniqueStates: Buffer | null },\n    skipped: boolean,\n  ): InsertResult<T> {\n    return {\n      job: {\n        ...row,\n        args: { ...row.args, kind: row.kind } as T,\n        uniqueStates: bitmaskToJobStates(row.uniqueStates),\n      },\n      skipped,\n    };\n  }\n}\n"]}
+{"version":3,"sources":["../../../src/utils/mappers.ts","../../../src/drivers/pg/pg-driver.ts"],"names":["crypto","Buffer","Pool","query","values","result","row"],"mappings":"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","file":"index.cjs","sourcesContent":["import { Buffer } from 'buffer';\nimport crypto from 'crypto';\nimport { InsertOpts, JobArgs, JobState } from '../types';\n\n/**\n * Converts a bit(8) Buffer to an array of JobState values using the bit order from river_job_state_in_bitmask.\n *\n * @param bitmask - The Buffer representing the job state bitmask.\n * @returns An array of JobState values corresponding to the set bits, or null if the bitmask is null.\n */\nexport const bitmaskToJobStates = (bitmask: Buffer | null): JobState[] | null => {\n  if (!bitmask || bitmask.length === 0) return null;\n  // Bit order: 7=available, 6=cancelled, 5=completed, 4=discarded, 3=pending, 2=retryable, 1=running, 0=scheduled\n  const allStates: JobState[] = [\n    JobState.Available, // 7\n    JobState.Cancelled, // 6\n    JobState.Completed, // 5\n    JobState.Discarded, // 4\n    JobState.Pending, // 3\n    JobState.Retryable, // 2\n    JobState.Running, // 1\n    JobState.Scheduled, // 0\n  ];\n  const byte = bitmask[0];\n  // Map bits 7..0 to allStates\n  return allStates.filter((_, i) => (byte & (1 << (7 - i))) !== 0);\n};\n\n/**\n * Maps job args and unique options to a unique key buffer.\n *\n * @param args - The job arguments to use for uniqueness computation.\n * @param opts - The insertion options, including unique options.\n * @returns A Buffer containing the unique key, or undefined if no unique options are set.\n */\nexport const mapToUniqueKey = (args: JobArgs, opts: InsertOpts): Buffer | undefined => {\n  const uniqueOpts = opts.uniqueOpts;\n  if (!uniqueOpts) return undefined;\n\n  const keyParts: Record<string, unknown> = {};\n\n  if (!uniqueOpts.excludeKind) {\n    keyParts.kind = args.kind;\n  }\n\n  if (uniqueOpts.byArgs === true) {\n    keyParts.args = args;\n  } else if (Array.isArray(uniqueOpts.byArgs)) {\n    keyParts.args = Object.fromEntries(uniqueOpts.byArgs.sort().map((k) => [k, args[k]]));\n  }\n\n  if (uniqueOpts.byQueue) {\n    keyParts.queue = opts.queue;\n  }\n\n  if (uniqueOpts.byPeriod && opts.scheduledAt) {\n    const date = new Date(opts.scheduledAt);\n    const period = uniqueOpts.byPeriod;\n    const timestamp = Math.floor(date.getTime() / 1000);\n    const rounded = timestamp - (timestamp % period);\n    keyParts.period = rounded;\n  }\n\n  const hash = crypto.createHash('sha256').update(JSON.stringify(keyParts)).digest();\n\n  return Buffer.from(hash);\n};\n","// RiverQueue driver implementation using the 'pg' library.\nimport { Buffer } from 'buffer';\nimport { Pool, PoolClient, PoolConfig } from 'pg';\nimport { InsertOpts, InsertResult, Job, JobArgs, JobState } from '../../types';\nimport { bitmaskToJobStates, mapToUniqueKey } from '../../utils';\nimport Driver from '../driver';\nimport Options from './pg-options';\n\n// Implements the RiverQueue Driver interface using the 'pg' library.\nexport default class PgDriver implements Driver<PoolClient> {\n  private readonly pool: Pool;\n\n  /**\n   * Creates a new PgDriver instance.\n   * @param options - Options for configuring the RiverQueue pg driver connection pool. Fields include:\n   *   - connectionString: Database connection string\n   *   - connectionTimeoutMillis: Optional, connection timeout in milliseconds\n   *   - idleTimeoutMillis: Optional, idle timeout in milliseconds\n   *   - max: Optional, maximum number of clients in the pool\n   */\n  constructor(options: Options) {\n    const config: PoolConfig = { ...options };\n    this.pool = new Pool(config);\n  }\n\n  async verifyConnection(): Promise<void> {\n    try {\n      const client = await this.pool.connect();\n      try {\n        await client.query('SELECT 1');\n      } finally {\n        client.release();\n      }\n    } catch (error) {\n      throw new Error(\n        `Database connection failed: ${error instanceof Error ? error.message : String(error)}`,\n      );\n    }\n  }\n\n  async close(): Promise<void> {\n    await this.pool.end();\n  }\n\n  async insert<T extends JobArgs>(args: T, opts: InsertOpts): Promise<InsertResult<T>> {\n    const client = await this.pool.connect();\n    try {\n      return await this.insertTx(client, args, opts);\n    } finally {\n      client.release();\n    }\n  }\n\n  async insertTx<T extends JobArgs>(\n    tx: PoolClient,\n    args: T,\n    opts: InsertOpts,\n  ): Promise<InsertResult<T>> {\n    if (!opts.maxAttempts) {\n      throw new Error('maxAttempts is required in InsertOpts');\n    }\n\n    let uniqueKey: Buffer | undefined;\n    if (opts.uniqueOpts) {\n      uniqueKey = mapToUniqueKey(args, opts);\n    }\n\n    if (uniqueKey) {\n      const stateList = opts.uniqueOpts?.byState || [];\n\n      let query = 'SELECT * FROM river_job WHERE unique_key = $1';\n      let values: (Buffer | string[])[] = [uniqueKey];\n\n      if (stateList.length > 0) {\n        query += ' AND state = ANY($2)';\n        values.push(stateList);\n      }\n\n      query += ' LIMIT 1';\n\n      const result = await tx.query<Omit<Job, 'uniqueStates'> & { uniqueStates: Buffer | null }>(\n        query,\n        values,\n      );\n\n      if (result.rows.length > 0) {\n        const row = result.rows[0];\n\n        return this.mapRowToInsertResult(row, true);\n      }\n    }\n\n    const { kind, ...restArgs } = args;\n    const columns = ['kind', 'args', 'queue', 'max_attempts'];\n    const values: (string | number | Buffer)[] = [\n      kind,\n      JSON.stringify(restArgs),\n      opts.queue,\n      opts.maxAttempts,\n    ];\n\n    if (opts.tags) {\n      columns.push('tags');\n      values.push(JSON.stringify(opts.tags));\n    }\n\n    if (opts.priority) {\n      columns.push('priority');\n      values.push(opts.priority);\n    }\n\n    if (opts.metadata) {\n      columns.push('metadata');\n      values.push(JSON.stringify(opts.metadata));\n    }\n\n    if (opts.scheduledAt) {\n      columns.push('scheduled_at');\n      values.push(\n        opts.scheduledAt instanceof Date ? opts.scheduledAt.toISOString() : opts.scheduledAt,\n      );\n    }\n\n    if (uniqueKey) {\n      columns.push('unique_key');\n      values.push(uniqueKey);\n    }\n\n    const placeholders = columns.map((_, i) => `$${i + 1}`);\n    const query = `INSERT INTO river_job (${columns.join(', ')}) VALUES (${placeholders.join(', ')}) RETURNING\n      id,\n      state,\n      attempt,\n      max_attempts as \"maxAttempts\",\n      attempted_at as \"attemptedAt\",\n      created_at as \"createdAt\",\n      finalized_at as \"finalizedAt\",\n      scheduled_at as \"scheduledAt\",\n      priority,\n      args,\n      attempted_by as \"attemptedBy\",\n      errors,\n      kind,\n      metadata,\n      queue,\n      tags,\n      unique_key as \"uniqueKey\",\n      unique_states as \"uniqueStates\"`;\n    const result = await tx.query<Omit<Job, 'uniqueStates'> & { uniqueStates: Buffer | null }>(\n      query,\n      values,\n    );\n\n    const row = result.rows[0];\n    if (!row) return row;\n\n    return this.mapRowToInsertResult(row, false);\n  }\n\n  async insertMany<T extends JobArgs>(\n    jobs: { args: T; opts: InsertOpts }[],\n  ): Promise<InsertResult<T>[]> {\n    const client = await this.pool.connect();\n    try {\n      await client.query('BEGIN');\n\n      const results: InsertResult<T>[] = [];\n      for (const job of jobs) {\n        results.push(await this.insertTx(client, job.args, job.opts));\n      }\n\n      await client.query('COMMIT');\n\n      return results;\n    } catch (error) {\n      await client.query('ROLLBACK');\n\n      throw error;\n    } finally {\n      client.release();\n    }\n  }\n\n  async getTx(): Promise<PoolClient> {\n    return this.pool.connect();\n  }\n\n  async getAvailableJobs(queue: string, limit: number, clientId: string): Promise<Job[]> {\n    const result = await this.pool.query<Job>(\n      `\n      UPDATE river_job\n      SET state = 'running',\n          attempt = attempt + 1,\n          attempted_at = NOW(),\n          attempted_by = array_append(COALESCE(attempted_by, '{}'), $1)\n      WHERE id IN (\n        SELECT id FROM river_job\n        WHERE state = 'available'\n          AND queue = $2\n          AND scheduled_at <= NOW()\n        ORDER BY priority, scheduled_at, id\n        LIMIT $3\n        FOR UPDATE SKIP LOCKED\n      )\n      RETURNING\n        id,\n        state,\n        attempt,\n        max_attempts as \"maxAttempts\",\n        attempted_at as \"attemptedAt\",\n        created_at as \"createdAt\",\n        finalized_at as \"finalizedAt\",\n        scheduled_at as \"scheduledAt\",\n        priority,\n        args,\n        attempted_by as \"attemptedBy\",\n        errors,\n        kind,\n        metadata,\n        queue,\n        tags,\n        unique_key as \"uniqueKey\",\n        unique_states as \"uniqueStates\"\n    `,\n      [clientId, queue, limit],\n    );\n\n    return result.rows;\n  }\n\n  async completeJob(id: number): Promise<void> {\n    await this.pool.query(\n      `\n      UPDATE river_job\n      SET state = $1,\n          finalized_at = NOW()\n      WHERE id = $2\n    `,\n      [JobState.Completed, id],\n    );\n  }\n\n  async failJob(id: number, error: Error, attempt: number, maxAttempts: number): Promise<void> {\n    const isDiscarded = attempt >= maxAttempts;\n    const backoffSeconds = Math.pow(2, attempt);\n    const errorEntry = JSON.stringify({ error: error.message, attempt });\n\n    await this.pool.query(\n      `\n      UPDATE river_job\n      SET state = $1,\n          finalized_at = CASE WHEN $2 THEN NOW() ELSE NULL END,\n          scheduled_at = CASE WHEN $2 THEN scheduled_at ELSE NOW() + ($3 || ' seconds')::interval END,\n          errors = array_append(COALESCE(errors, '{}'), $4::jsonb)\n      WHERE id = $5\n    `,\n      [\n        isDiscarded ? JobState.Discarded : JobState.Retryable,\n        isDiscarded,\n        backoffSeconds,\n        errorEntry,\n        id,\n      ],\n    );\n  }\n\n  /**\n   * Helper to map a DB row to a Job<T> and InsertResult.\n   */\n  private mapRowToInsertResult<T extends JobArgs>(\n    row: Omit<Job, 'uniqueStates'> & { uniqueStates: Buffer | null },\n    skipped: boolean,\n  ): InsertResult<T> {\n    return {\n      job: {\n        ...row,\n        args: { ...row.args, kind: row.kind } as T,\n        uniqueStates: bitmaskToJobStates(row.uniqueStates),\n      },\n      skipped,\n    };\n  }\n}\n"]}

package/dist/drivers/pg/index.d.cts

@@ -1,6 +1,6 @@
 import { PoolClient } from 'pg';
-import { J as JobArgs, I as InsertOpts, a as InsertResult } from '../../insert-result-Bf0bAFvJ.cjs';
-import { D as Driver } from '../../driver-vSyPLsFq.cjs';
+import { J as JobArgs, I as InsertOpts, a as InsertResult, b as Job } from '../../insert-result-DWZkRtk9.cjs';
+import { D as Driver } from '../../driver-BhanG0yg.cjs';
 import 'buffer';
 
 /**
@@ -37,6 +37,9 @@ declare class PgDriver implements Driver<PoolClient> {
         opts: InsertOpts;
     }[]): Promise<InsertResult<T>[]>;
     getTx(): Promise<PoolClient>;
+    getAvailableJobs(queue: string, limit: number, clientId: string): Promise<Job[]>;
+    completeJob(id: number): Promise<void>;
+    failJob(id: number, error: Error, attempt: number, maxAttempts: number): Promise<void>;
     /**
      * Helper to map a DB row to a Job<T> and InsertResult.
      */

package/dist/drivers/pg/index.d.ts

@@ -1,6 +1,6 @@
 import { PoolClient } from 'pg';
-import { J as JobArgs, I as InsertOpts, a as InsertResult } from '../../insert-result-Bf0bAFvJ.js';
-import { D as Driver } from '../../driver-okKFbSrB.js';
+import { J as JobArgs, I as InsertOpts, a as InsertResult, b as Job } from '../../insert-result-DWZkRtk9.js';
+import { D as Driver } from '../../driver-DQ6PVYVO.js';
 import 'buffer';
 
 /**
@@ -37,6 +37,9 @@ declare class PgDriver implements Driver<PoolClient> {
         opts: InsertOpts;
     }[]): Promise<InsertResult<T>[]>;
     getTx(): Promise<PoolClient>;
+    getAvailableJobs(queue: string, limit: number, clientId: string): Promise<Job[]>;
+    completeJob(id: number): Promise<void>;
+    failJob(id: number, error: Error, attempt: number, maxAttempts: number): Promise<void>;
     /**
      * Helper to map a DB row to a Job<T> and InsertResult.
      */

package/dist/drivers/pg/index.js

@@ -92,9 +92,6 @@ var PgDriver = class {
     }
   }
   async insertTx(tx, args, opts) {
-    if (!opts.queue) {
-      throw new Error("Queue name is required in InsertOpts");
-    }
     if (!opts.maxAttempts) {
       throw new Error("maxAttempts is required in InsertOpts");
     }
@@ -198,6 +195,80 @@ var PgDriver = class {
   async getTx() {
     return this.pool.connect();
   }
+  async getAvailableJobs(queue, limit, clientId) {
+    const result = await this.pool.query(
+      `
+      UPDATE river_job
+      SET state = 'running',
+          attempt = attempt + 1,
+          attempted_at = NOW(),
+          attempted_by = array_append(COALESCE(attempted_by, '{}'), $1)
+      WHERE id IN (
+        SELECT id FROM river_job
+        WHERE state = 'available'
+          AND queue = $2
+          AND scheduled_at <= NOW()
+        ORDER BY priority, scheduled_at, id
+        LIMIT $3
+        FOR UPDATE SKIP LOCKED
+      )
+      RETURNING
+        id,
+        state,
+        attempt,
+        max_attempts as "maxAttempts",
+        attempted_at as "attemptedAt",
+        created_at as "createdAt",
+        finalized_at as "finalizedAt",
+        scheduled_at as "scheduledAt",
+        priority,
+        args,
+        attempted_by as "attemptedBy",
+        errors,
+        kind,
+        metadata,
+        queue,
+        tags,
+        unique_key as "uniqueKey",
+        unique_states as "uniqueStates"
+    `,
+      [clientId, queue, limit]
+    );
+    return result.rows;
+  }
+  async completeJob(id) {
+    await this.pool.query(
+      `
+      UPDATE river_job
+      SET state = $1,
+          finalized_at = NOW()
+      WHERE id = $2
+    `,
+      ["completed" /* Completed */, id]
+    );
+  }
+  async failJob(id, error, attempt, maxAttempts) {
+    const isDiscarded = attempt >= maxAttempts;
+    const backoffSeconds = Math.pow(2, attempt);
+    const errorEntry = JSON.stringify({ error: error.message, attempt });
+    await this.pool.query(
+      `
+      UPDATE river_job
+      SET state = $1,
+          finalized_at = CASE WHEN $2 THEN NOW() ELSE NULL END,
+          scheduled_at = CASE WHEN $2 THEN scheduled_at ELSE NOW() + ($3 || ' seconds')::interval END,
+          errors = array_append(COALESCE(errors, '{}'), $4::jsonb)
+      WHERE id = $5
+    `,
+      [
+        isDiscarded ? "discarded" /* Discarded */ : "retryable" /* Retryable */,
+        isDiscarded,
+        backoffSeconds,
+        errorEntry,
+        id
+      ]
+    );
+  }
   /**
    * Helper to map a DB row to a Job<T> and InsertResult.
    */