@odunlamizo/node-river 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Odunlami Zacchaeus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# node-river
+
+A Node.js job queue and workflow engine with PostgreSQL support.
+
+## Installation
+
+```bash
+npm install node-river
+```
+
+## Usage
+
+### 1. Setup
+
+```ts
+import { RiverClient } from 'node-river';
+import { PgDriver } from 'node-river/drivers/pg';
+
+const driver = new PgDriver({ connectionString: process.env.DATABASE_URL! });
+const client = new RiverClient(driver, {
+  defaultQueue: 'default',
+  maxAttempts: 1,
+});
+```
+
+### 2. Verify Connection
+
+```ts
+await client.verifyConnection();
+```
+
+### 3. Insert a Job
+
+```ts
+const result = await client.insert({ kind: 'sort_args', strings: ['banana', 'apple', 'cherry'] });
+console.log(result.job); // Job details
+```
+
+### 4. Insert Unique Job
+
+```ts
+const result = await client.insert(
+  { kind: 'sort_args', strings: ['banana', 'apple', 'cherry'] },
+  { uniqueOpts: { byArgs: ['strings'] } }
+);
+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
+```
+
+### 6. Use Transactions
+
+```ts
+const tx = await driver.getTx();
+try {
+  await tx.query('BEGIN');
+  const result = await client.insertTx(tx, { kind: 'sort_args', strings: ['x', 'y', 'z'] });
+  await tx.query('COMMIT');
+} catch (e) {
+  await tx.query('ROLLBACK');
+  throw e;
+} finally {
+  tx.release();
+}
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,105 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  RiverClient: () => RiverClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var RiverClient = class {
+  /**
+   * Creates a new RiverClient instance.
+   * @param driver - The queue driver implementation.
+   * @param configuration - Client configuration options.
+   */
+  constructor(driver, configuration) {
+    this.driver = driver;
+    this.configuration = configuration;
+  }
+  /**
+   * Checks if the driver can connect to the database. Throws on failure.
+   */
+  verifyConnection() {
+    return this.driver.verifyConnection();
+  }
+  /**
+   * Closes all database connections and cleans up resources.
+   */
+  close() {
+    return this.driver.close();
+  }
+  /**
+   * Inserts a job into the queue with the specified arguments and options.
+   * @param args - The job arguments to insert.
+   * @param opts - Optional insertion options.
+   * @returns A promise that resolves to the result of the insertion operation,
+   *          including the job and whether the insert was skipped due to uniqueness.
+   */
+  insert(args, opts = {}) {
+    const defaultOpts = {
+      queue: this.configuration.defaultQueue,
+      maxAttempts: this.configuration.maxAttempts,
+      ...opts
+    };
+    return this.driver.insert(args, defaultOpts);
+  }
+  /**
+   * Inserts a job into the queue within an existing transaction or session.
+   * The transaction type (Tx) is determined by the driver implementation.
+   *
+   * @param tx - The transaction or session object to use for the insert.
+   * @param args - The job arguments to insert.
+   * @param opts - Optional insertion options.
+   * @returns A promise that resolves to the result of the insertion operation,
+   *          including the job and whether the insert was skipped due to uniqueness.
+   */
+  insertTx(tx, args, opts = {}) {
+    const defaultOpts = {
+      queue: this.configuration.defaultQueue,
+      maxAttempts: this.configuration.maxAttempts,
+      ...opts
+    };
+    return this.driver.insertTx(tx, args, defaultOpts);
+  }
+  /**
+   * Inserts multiple jobs in sequence within a single transaction.
+   * If any insert fails, all previous inserts in the batch are rolled back.
+   *
+   * @param jobs - Array of job argument and option pairs to insert.
+   * @returns A promise that resolves to an array of InsertResult objects for each job.
+   */
+  async insertMany(jobs) {
+    const jobsWithDefaults = jobs.map((job) => ({
+      args: job.args,
+      opts: {
+        queue: this.configuration.defaultQueue,
+        maxAttempts: this.configuration.maxAttempts,
+        ...job.opts
+      }
+    }));
+    return this.driver.insertMany(jobsWithDefaults);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RiverClient
+});

package/dist/index.d.cts

@@ -0,0 +1,355 @@
+import { Buffer } from 'buffer';
+
+/**
+ * Configuration options for the RiverQueue client.
+ */
+interface ClientConfiguration {
+    /**
+     * Default queue name for job insertion
+     */
+    defaultQueue?: string;
+    /**
+     * Maximum number of attempts for jobs
+     */
+    maxAttempts?: number;
+}
+
+/**
+ * Represents the lifecycle state of a job, such as available, running, completed, or scheduled.
+ */
+declare enum JobState {
+    /**
+     * Immediately eligible to be worked
+     */
+    Available = "available",
+    /**
+     * Manually cancelled by user; cleaned after a period
+     */
+    Cancelled = "cancelled",
+    /**
+     * Successfully run to completion; cleaned after a period
+     */
+    Completed = "completed",
+    /**
+     * Errored too many times; needs manual intervention
+     */
+    Discarded = "discarded",
+    /**
+     * Waiting for external action; not worked or deleted until moved
+     */
+    Pending = "pending",
+    /**
+     * Errored but will be retried; becomes Available when ready
+     */
+    Retryable = "retryable",
+    /**
+     * Actively running; may need rescue if stuck
+     */
+    Running = "running",
+    /**
+     * Scheduled for future execution; becomes Available when due
+     */
+    Scheduled = "scheduled"
+}
+
+/**
+ * Represents a failed job attempt, including error details and stack trace.
+ */
+interface AttemptError {
+    /**
+     * Time the error occurred
+     */
+    at: string;
+    /**
+     * Attempt number when the error occurred
+     */
+    attempt: number;
+    /**
+     * Stringified error or panic value
+     */
+    error: string;
+    /**
+     * Stack trace from a job that panicked
+     */
+    trace: string;
+}
+
+/**
+ * Options for enforcing uniqueness constraints on jobs.
+ */
+interface UniqueOpts {
+    /**
+     * Enforce uniqueness based on job arguments.
+     * True for all args, or specify keys to include.
+     */
+    byArgs?: true | string[];
+    /**
+     * Enforce uniqueness within a time period (seconds).
+     */
+    byPeriod?: number;
+    /**
+     * Enforce uniqueness within each queue.
+     */
+    byQueue?: true;
+    /**
+     * Enforce uniqueness across specified job states.
+     */
+    byState?: string[];
+    /**
+     * Exclude job kind from uniqueness computation.
+     */
+    excludeKind?: true;
+}
+
+/**
+ * Options for job insertion, such as queue, priority, scheduling, and metadata.
+ */
+interface InsertOpts {
+    /**
+     * List of tags for grouping and categorizing jobs
+     */
+    tags?: string[];
+    /**
+     * Name of the job queue to insert into
+     */
+    queue?: string;
+    /**
+     * Job priority (1 = highest, 4 = lowest)
+     */
+    priority?: number;
+    /**
+     * Arbitrary metadata for the job
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Maximum number of attempts before discarding the job
+     */
+    maxAttempts?: number;
+    /**
+     * Schedule the job for future execution
+     */
+    scheduledAt?: Date;
+    /**
+     * Options relating to job uniqueness.
+     * If not set, the job is never treated as unique.
+     */
+    uniqueOpts?: UniqueOpts;
+}
+
+/**
+ * Interface for job argument objects passed to job handlers.
+ *
+ * Every job must specify a `kind` to identify its type, and can include
+ * any number of additional properties relevant to the job's execution.
+ */
+interface JobArgs {
+    /**
+     * Identifies the job type for routing and processing.
+     */
+    kind: string;
+    /**
+     * Arbitrary job parameters, allowing for flexible job payloads.
+     * All values should be JSON-compatible.
+     */
+    [key: string]: unknown;
+}
+
+/**
+ * Represents a job persisted in the database, including its state, metadata, and scheduling information.
+ */
+interface Job<T extends JobArgs = JobArgs> {
+    /**
+     * Unique job ID, generated by the database
+     */
+    id: number;
+    /**
+     * Current state of the job (e.g., available, completed)
+     */
+    state: JobState;
+    /**
+     * Current attempt number, incremented each time the job is worked
+     */
+    attempt: number;
+    /**
+     * Maximum number of attempts before the job stops retrying
+     */
+    maxAttempts: number;
+    /**
+     * Last time the job was worked, null if never
+     */
+    attemptedAt: Date | null;
+    /**
+     * When the job record was created
+     */
+    createdAt: Date;
+    /**
+     * When the job was finalized (completed or errored for last time), null if not finalized
+     */
+    finalizedAt: Date | null;
+    /**
+     * When the job is scheduled to become available
+     */
+    scheduledAt: Date;
+    /**
+     * Job priority (1 = highest, 4 = lowest)
+     */
+    priority: number;
+    /**
+     * Job arguments, decoded from JSON
+     */
+    args: T;
+    /**
+     * Worker IDs that have worked this job, null if never
+     */
+    attemptedBy: string[] | null;
+    /**
+     * Errors for each attempt, ordered earliest to latest, null if none
+     */
+    errors: AttemptError[] | null;
+    /**
+     * Job type identifier, set at insertion
+     */
+    kind: string;
+    /**
+     * Arbitrary metadata associated with the job
+     */
+    metadata: Record<string, unknown>;
+    /**
+     * Name of the queue where the job will be worked
+     */
+    queue: string;
+    /**
+     * List of tags for grouping and categorizing jobs
+     */
+    tags: string[];
+    /**
+     * Unique key for job within its kind, used for unique insertions, null if not set
+     */
+    uniqueKey: Buffer | null;
+    /**
+     * States required for uniqueness, null if not set
+     */
+    uniqueStates: JobState[] | null;
+}
+
+/**
+ * Result of a job insertion operation.
+ *
+ * - If a unique job already exists, `job` is the existing job and `skipped` is true.
+ * - If the job was inserted, `job` is the new job and `skipped` is false.
+ */
+interface InsertResult<T extends JobArgs = JobArgs> {
+    /**
+     * The inserted job, or the existing job if insertion was skipped due to uniqueness.
+     */
+    job: Job<T>;
+    /**
+     * True if insertion was skipped because a unique job already exists.
+     */
+    skipped: boolean;
+}
+
+/**
+ * Common interface for all RiverQueue drivers (e.g., Postgres, Prisma, Sequelize, etc.).
+ * The generic parameter Tx must be set to the driver's transaction/session type.
+ */
+interface Driver<Tx> {
+    /**
+     * Checks if the driver can connect to the database. Throws on failure.
+     */
+    verifyConnection(): Promise<void>;
+    /**
+     * Closes all database connections and cleans up resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Inserts a new job into the queue using the provided arguments and options.
+     * @param args - The job arguments to insert.
+     * @param opts - Options for job insertion.
+     * @returns A promise that resolves to the result of the insertion operation,
+     *          including the job and whether the insert was skipped due to uniqueness.
+     */
+    insert<T extends JobArgs>(args: T, opts: InsertOpts): Promise<InsertResult<T>>;
+    /**
+     * Inserts a new job into the queue within an existing transaction or session.
+     * The type of `tx` is driver-specific and should match the transaction/session type for the driver.
+     *
+     * @param tx - The transaction or session object to use for the insert.
+     * @param args - The job arguments to insert.
+     * @param opts - Options for job insertion.
+     * @returns A promise that resolves to the result of the insertion operation.
+     */
+    insertTx<T extends JobArgs>(tx: Tx, args: T, opts: InsertOpts): Promise<InsertResult<T>>;
+    /**
+     * Inserts multiple jobs in sequence within a single transaction.
+     * If any insert fails, all previous inserts in the batch are rolled back.
+     *
+     * @param jobs - Array of job argument and option pairs to insert.
+     * @returns Array of InsertResult objects for each job.
+     */
+    insertMany<T extends JobArgs>(jobs: {
+        args: T;
+        opts: InsertOpts;
+    }[]): Promise<InsertResult<T>[]>;
+    /**
+     * Starts and returns a new transaction or session object for the driver.
+     * The returned object should be used for transactional operations such as insertTx.
+     *
+     * @returns A promise that resolves to the driver's transaction/session object.
+     */
+    getTx(): Promise<Tx>;
+}
+
+/**
+ * Provides methods to enqueue jobs and manage queue operations.
+ */
+declare class RiverClient<D extends Driver<Tx>, Tx> {
+    private readonly driver;
+    private readonly configuration;
+    /**
+     * Creates a new RiverClient instance.
+     * @param driver - The queue driver implementation.
+     * @param configuration - Client configuration options.
+     */
+    constructor(driver: D, configuration: ClientConfiguration);
+    /**
+     * Checks if the driver can connect to the database. Throws on failure.
+     */
+    verifyConnection(): Promise<void>;
+    /**
+     * Closes all database connections and cleans up resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Inserts a job into the queue with the specified arguments and options.
+     * @param args - The job arguments to insert.
+     * @param opts - Optional insertion options.
+     * @returns A promise that resolves to the result of the insertion operation,
+     *          including the job and whether the insert was skipped due to uniqueness.
+     */
+    insert<T extends JobArgs>(args: T, opts?: InsertOpts): Promise<InsertResult<T>>;
+    /**
+     * Inserts a job into the queue within an existing transaction or session.
+     * The transaction type (Tx) is determined by the driver implementation.
+     *
+     * @param tx - The transaction or session object to use for the insert.
+     * @param args - The job arguments to insert.
+     * @param opts - Optional insertion options.
+     * @returns A promise that resolves to the result of the insertion operation,
+     *          including the job and whether the insert was skipped due to uniqueness.
+     */
+    insertTx<T extends JobArgs>(tx: Tx, args: T, opts?: InsertOpts): Promise<InsertResult<T>>;
+    /**
+     * Inserts multiple jobs in sequence within a single transaction.
+     * If any insert fails, all previous inserts in the batch are rolled back.
+     *
+     * @param jobs - Array of job argument and option pairs to insert.
+     * @returns A promise that resolves to an array of InsertResult objects for each job.
+     */
+    insertMany<T extends JobArgs>(jobs: {
+        args: T;
+        opts: InsertOpts;
+    }[]): Promise<InsertResult<T>[]>;
+}
+
+export { RiverClient };

package/dist/index.d.ts

@@ -0,0 +1,355 @@
+import { Buffer } from 'buffer';
+
+/**
+ * Configuration options for the RiverQueue client.
+ */
+interface ClientConfiguration {
+    /**
+     * Default queue name for job insertion
+     */
+    defaultQueue?: string;
+    /**
+     * Maximum number of attempts for jobs
+     */
+    maxAttempts?: number;
+}
+
+/**
+ * Represents the lifecycle state of a job, such as available, running, completed, or scheduled.
+ */
+declare enum JobState {
+    /**
+     * Immediately eligible to be worked
+     */
+    Available = "available",
+    /**
+     * Manually cancelled by user; cleaned after a period
+     */
+    Cancelled = "cancelled",
+    /**
+     * Successfully run to completion; cleaned after a period
+     */
+    Completed = "completed",
+    /**
+     * Errored too many times; needs manual intervention
+     */
+    Discarded = "discarded",
+    /**
+     * Waiting for external action; not worked or deleted until moved
+     */
+    Pending = "pending",
+    /**
+     * Errored but will be retried; becomes Available when ready
+     */
+    Retryable = "retryable",
+    /**
+     * Actively running; may need rescue if stuck
+     */
+    Running = "running",
+    /**
+     * Scheduled for future execution; becomes Available when due
+     */
+    Scheduled = "scheduled"
+}
+
+/**
+ * Represents a failed job attempt, including error details and stack trace.
+ */
+interface AttemptError {
+    /**
+     * Time the error occurred
+     */
+    at: string;
+    /**
+     * Attempt number when the error occurred
+     */
+    attempt: number;
+    /**
+     * Stringified error or panic value
+     */
+    error: string;
+    /**
+     * Stack trace from a job that panicked
+     */
+    trace: string;
+}
+
+/**
+ * Options for enforcing uniqueness constraints on jobs.
+ */
+interface UniqueOpts {
+    /**
+     * Enforce uniqueness based on job arguments.
+     * True for all args, or specify keys to include.
+     */
+    byArgs?: true | string[];
+    /**
+     * Enforce uniqueness within a time period (seconds).
+     */
+    byPeriod?: number;
+    /**
+     * Enforce uniqueness within each queue.
+     */
+    byQueue?: true;
+    /**
+     * Enforce uniqueness across specified job states.
+     */
+    byState?: string[];
+    /**
+     * Exclude job kind from uniqueness computation.
+     */
+    excludeKind?: true;
+}
+
+/**
+ * Options for job insertion, such as queue, priority, scheduling, and metadata.
+ */
+interface InsertOpts {
+    /**
+     * List of tags for grouping and categorizing jobs
+     */
+    tags?: string[];
+    /**
+     * Name of the job queue to insert into
+     */
+    queue?: string;
+    /**
+     * Job priority (1 = highest, 4 = lowest)
+     */
+    priority?: number;
+    /**
+     * Arbitrary metadata for the job
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Maximum number of attempts before discarding the job
+     */
+    maxAttempts?: number;
+    /**
+     * Schedule the job for future execution
+     */
+    scheduledAt?: Date;
+    /**
+     * Options relating to job uniqueness.
+     * If not set, the job is never treated as unique.
+     */
+    uniqueOpts?: UniqueOpts;
+}
+
+/**
+ * Interface for job argument objects passed to job handlers.
+ *
+ * Every job must specify a `kind` to identify its type, and can include
+ * any number of additional properties relevant to the job's execution.
+ */
+interface JobArgs {
+    /**
+     * Identifies the job type for routing and processing.
+     */
+    kind: string;
+    /**
+     * Arbitrary job parameters, allowing for flexible job payloads.
+     * All values should be JSON-compatible.
+     */
+    [key: string]: unknown;
+}
+
+/**
+ * Represents a job persisted in the database, including its state, metadata, and scheduling information.
+ */
+interface Job<T extends JobArgs = JobArgs> {
+    /**
+     * Unique job ID, generated by the database
+     */
+    id: number;
+    /**
+     * Current state of the job (e.g., available, completed)
+     */
+    state: JobState;
+    /**
+     * Current attempt number, incremented each time the job is worked
+     */
+    attempt: number;
+    /**
+     * Maximum number of attempts before the job stops retrying
+     */
+    maxAttempts: number;
+    /**
+     * Last time the job was worked, null if never
+     */
+    attemptedAt: Date | null;
+    /**
+     * When the job record was created
+     */
+    createdAt: Date;
+    /**
+     * When the job was finalized (completed or errored for last time), null if not finalized
+     */
+    finalizedAt: Date | null;
+    /**
+     * When the job is scheduled to become available
+     */
+    scheduledAt: Date;
+    /**
+     * Job priority (1 = highest, 4 = lowest)
+     */
+    priority: number;
+    /**
+     * Job arguments, decoded from JSON
+     */
+    args: T;
+    /**
+     * Worker IDs that have worked this job, null if never
+     */
+    attemptedBy: string[] | null;
+    /**
+     * Errors for each attempt, ordered earliest to latest, null if none
+     */
+    errors: AttemptError[] | null;
+    /**
+     * Job type identifier, set at insertion
+     */
+    kind: string;
+    /**
+     * Arbitrary metadata associated with the job
+     */
+    metadata: Record<string, unknown>;
+    /**
+     * Name of the queue where the job will be worked
+     */
+    queue: string;
+    /**
+     * List of tags for grouping and categorizing jobs
+     */
+    tags: string[];
+    /**
+     * Unique key for job within its kind, used for unique insertions, null if not set
+     */
+    uniqueKey: Buffer | null;
+    /**
+     * States required for uniqueness, null if not set
+     */
+    uniqueStates: JobState[] | null;
+}
+
+/**
+ * Result of a job insertion operation.
+ *
+ * - If a unique job already exists, `job` is the existing job and `skipped` is true.
+ * - If the job was inserted, `job` is the new job and `skipped` is false.
+ */
+interface InsertResult<T extends JobArgs = JobArgs> {
+    /**
+     * The inserted job, or the existing job if insertion was skipped due to uniqueness.
+     */
+    job: Job<T>;
+    /**
+     * True if insertion was skipped because a unique job already exists.
+     */
+    skipped: boolean;
+}
+
+/**
+ * Common interface for all RiverQueue drivers (e.g., Postgres, Prisma, Sequelize, etc.).
+ * The generic parameter Tx must be set to the driver's transaction/session type.
+ */
+interface Driver<Tx> {
+    /**
+     * Checks if the driver can connect to the database. Throws on failure.
+     */
+    verifyConnection(): Promise<void>;
+    /**
+     * Closes all database connections and cleans up resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Inserts a new job into the queue using the provided arguments and options.
+     * @param args - The job arguments to insert.
+     * @param opts - Options for job insertion.
+     * @returns A promise that resolves to the result of the insertion operation,
+     *          including the job and whether the insert was skipped due to uniqueness.
+     */
+    insert<T extends JobArgs>(args: T, opts: InsertOpts): Promise<InsertResult<T>>;
+    /**
+     * Inserts a new job into the queue within an existing transaction or session.
+     * The type of `tx` is driver-specific and should match the transaction/session type for the driver.
+     *
+     * @param tx - The transaction or session object to use for the insert.
+     * @param args - The job arguments to insert.
+     * @param opts - Options for job insertion.
+     * @returns A promise that resolves to the result of the insertion operation.
+     */
+    insertTx<T extends JobArgs>(tx: Tx, args: T, opts: InsertOpts): Promise<InsertResult<T>>;
+    /**
+     * Inserts multiple jobs in sequence within a single transaction.
+     * If any insert fails, all previous inserts in the batch are rolled back.
+     *
+     * @param jobs - Array of job argument and option pairs to insert.
+     * @returns Array of InsertResult objects for each job.
+     */
+    insertMany<T extends JobArgs>(jobs: {
+        args: T;
+        opts: InsertOpts;
+    }[]): Promise<InsertResult<T>[]>;
+    /**
+     * Starts and returns a new transaction or session object for the driver.
+     * The returned object should be used for transactional operations such as insertTx.
+     *
+     * @returns A promise that resolves to the driver's transaction/session object.
+     */
+    getTx(): Promise<Tx>;
+}
+
+/**
+ * Provides methods to enqueue jobs and manage queue operations.
+ */
+declare class RiverClient<D extends Driver<Tx>, Tx> {
+    private readonly driver;
+    private readonly configuration;
+    /**
+     * Creates a new RiverClient instance.
+     * @param driver - The queue driver implementation.
+     * @param configuration - Client configuration options.
+     */
+    constructor(driver: D, configuration: ClientConfiguration);
+    /**
+     * Checks if the driver can connect to the database. Throws on failure.
+     */
+    verifyConnection(): Promise<void>;
+    /**
+     * Closes all database connections and cleans up resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Inserts a job into the queue with the specified arguments and options.
+     * @param args - The job arguments to insert.
+     * @param opts - Optional insertion options.
+     * @returns A promise that resolves to the result of the insertion operation,
+     *          including the job and whether the insert was skipped due to uniqueness.
+     */
+    insert<T extends JobArgs>(args: T, opts?: InsertOpts): Promise<InsertResult<T>>;
+    /**
+     * Inserts a job into the queue within an existing transaction or session.
+     * The transaction type (Tx) is determined by the driver implementation.
+     *
+     * @param tx - The transaction or session object to use for the insert.
+     * @param args - The job arguments to insert.
+     * @param opts - Optional insertion options.
+     * @returns A promise that resolves to the result of the insertion operation,
+     *          including the job and whether the insert was skipped due to uniqueness.
+     */
+    insertTx<T extends JobArgs>(tx: Tx, args: T, opts?: InsertOpts): Promise<InsertResult<T>>;
+    /**
+     * Inserts multiple jobs in sequence within a single transaction.
+     * If any insert fails, all previous inserts in the batch are rolled back.
+     *
+     * @param jobs - Array of job argument and option pairs to insert.
+     * @returns A promise that resolves to an array of InsertResult objects for each job.
+     */
+    insertMany<T extends JobArgs>(jobs: {
+        args: T;
+        opts: InsertOpts;
+    }[]): Promise<InsertResult<T>[]>;
+}
+
+export { RiverClient };

package/dist/index.js

@@ -0,0 +1,78 @@
+// src/client.ts
+var RiverClient = class {
+  /**
+   * Creates a new RiverClient instance.
+   * @param driver - The queue driver implementation.
+   * @param configuration - Client configuration options.
+   */
+  constructor(driver, configuration) {
+    this.driver = driver;
+    this.configuration = configuration;
+  }
+  /**
+   * Checks if the driver can connect to the database. Throws on failure.
+   */
+  verifyConnection() {
+    return this.driver.verifyConnection();
+  }
+  /**
+   * Closes all database connections and cleans up resources.
+   */
+  close() {
+    return this.driver.close();
+  }
+  /**
+   * Inserts a job into the queue with the specified arguments and options.
+   * @param args - The job arguments to insert.
+   * @param opts - Optional insertion options.
+   * @returns A promise that resolves to the result of the insertion operation,
+   *          including the job and whether the insert was skipped due to uniqueness.
+   */
+  insert(args, opts = {}) {
+    const defaultOpts = {
+      queue: this.configuration.defaultQueue,
+      maxAttempts: this.configuration.maxAttempts,
+      ...opts
+    };
+    return this.driver.insert(args, defaultOpts);
+  }
+  /**
+   * Inserts a job into the queue within an existing transaction or session.
+   * The transaction type (Tx) is determined by the driver implementation.
+   *
+   * @param tx - The transaction or session object to use for the insert.
+   * @param args - The job arguments to insert.
+   * @param opts - Optional insertion options.
+   * @returns A promise that resolves to the result of the insertion operation,
+   *          including the job and whether the insert was skipped due to uniqueness.
+   */
+  insertTx(tx, args, opts = {}) {
+    const defaultOpts = {
+      queue: this.configuration.defaultQueue,
+      maxAttempts: this.configuration.maxAttempts,
+      ...opts
+    };
+    return this.driver.insertTx(tx, args, defaultOpts);
+  }
+  /**
+   * Inserts multiple jobs in sequence within a single transaction.
+   * If any insert fails, all previous inserts in the batch are rolled back.
+   *
+   * @param jobs - Array of job argument and option pairs to insert.
+   * @returns A promise that resolves to an array of InsertResult objects for each job.
+   */
+  async insertMany(jobs) {
+    const jobsWithDefaults = jobs.map((job) => ({
+      args: job.args,
+      opts: {
+        queue: this.configuration.defaultQueue,
+        maxAttempts: this.configuration.maxAttempts,
+        ...job.opts
+      }
+    }));
+    return this.driver.insertMany(jobsWithDefaults);
+  }
+};
+export {
+  RiverClient
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@odunlamizo/node-river",
+  "version": "1.0.0",
+  "description": "Node.js library to support riverqueue integration.",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --dts --format cjs,esm",
+    "dev": "tsup src/index.ts --watch --dts --format cjs,esm",
+    "test": "jest --runInBand",
+    "lint": "eslint . --ext .ts,.js --ignore-pattern eslint.config.js",
+    "format": "prettier --write .",
+    "prepare": "husky install"
+  },
+  "lint-staged": {
+    "**/*.{js,ts}": [
+      "eslint --fix --ignore-pattern eslint.config.js",
+      "prettier --write"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OdunlamiZO/node-river.git"
+  },
+  "keywords": [
+    "riverqueue",
+    "queue",
+    "node",
+    "library"
+  ],
+  "author": "Odunlami Zacchaeus",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/OdunlamiZO/node-river/issues"
+  },
+  "homepage": "https://github.com/OdunlamiZO/node-river#readme",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.2.3",
+    "@types/pg": "^8.16.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "husky": "^8.0.0",
+    "jest": "^29.7.0",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.8.1",
+    "prettier-plugin-organize-imports": "^4.3.0",
+    "ts-jest": "^29.4.6",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "pg": ">=8.0.0"
+  }
+}