@odunlamizo/node-river 1.0.8 → 1.1.1

package/dist/index.js

@@ -1,77 +1,149 @@
+import os from 'os';
+import process from 'process';
+import { clearTimeout, setTimeout } from 'timers';
+
+// src/client.ts
+
+// src/utils/constants.ts
+var CLIENT_CONFIGURATION_DEFAULTS = {
+  pollInterval: 1e3
+};
+
 // src/client.ts
 var RiverClient = class {
   /**
    * Creates a new RiverClient instance.
-   * @param driver - The queue driver implementation.
-   * @param configuration - Client configuration options.
+   * @param driver - The driver implementation (e.g. PgDriver).
+   * @param configuration - Client options: queues, max attempts, poll interval, and client ID.
    */
   constructor(driver, configuration) {
+    this.running = /* @__PURE__ */ new Map();
+    this.stopped = false;
+    this.pollTimer = null;
+    this.workers = /* @__PURE__ */ new Map();
     this.driver = driver;
     this.configuration = configuration;
+    this.clientId = configuration.clientId ?? `${os.hostname()}-${process.pid}`;
   }
   /**
-   * Checks if the driver can connect to the database. Throws on failure.
+   * Verifies the driver can reach the database. Throws if the connection fails.
    */
-  verifyConnection() {
+  async verifyConnection() {
     return this.driver.verifyConnection();
   }
   /**
-   * Closes all database connections and cleans up resources.
+   * Stops the polling loop (if running) and closes all database connections.
+   * Always call this on shutdown to avoid resource leaks.
    */
-  close() {
-    return this.driver.close();
+  async close() {
+    this.stopped = true;
+    if (this.pollTimer) clearTimeout(this.pollTimer);
+    await 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.
+   * Inserts a single job into the specified queue.
+   * @param args - Job arguments including `kind` and any job-specific fields.
+   * @param opts - Insertion options. `queue` is required; `maxAttempts` defaults to the client configuration value.
+   * @returns The inserted job and a `skipped` flag indicating if it was deduplicated.
    */
-  insert(args, opts = {}) {
+  async 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.
+   * Inserts a single job within an existing transaction. Use this when the job
+   * should only be enqueued if the surrounding transaction commits.
+   * @param tx - The active transaction object (type is driver-specific).
+   * @param args - Job arguments including `kind` and any job-specific fields.
+   * @param opts - Insertion options. `queue` is required; `maxAttempts` defaults to the client configuration value.
+   * @returns The inserted job and a `skipped` flag indicating if it was deduplicated.
    */
-  insertTx(tx, args, opts = {}) {
+  async 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.
+   * Inserts multiple jobs in a single transaction. If any insert fails, all are rolled back.
+   * @param jobs - Array of `{ args, opts }` pairs. Each `opts` must include a `queue`.
+   * @returns An array of InsertResult objects in the same order as the input.
    */
   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);
   }
+  /**
+   * Registers a worker for a specific job kind. When a job of this kind is claimed
+   * from the queue, the worker's `work()` method will be called with the job.
+   * Must be called before `work()` for the worker to receive jobs.
+   * @param kind - The job kind string that this worker handles (e.g. `"send_email"`).
+   * @param worker - The worker instance that implements the `Worker<T>` interface.
+   */
+  addWorker(kind, worker) {
+    this.workers.set(kind, worker);
+  }
+  /**
+   * Begins polling all configured queues and dispatching jobs to registered workers.
+   * Each queue is polled independently with its own concurrency limit.
+   * No-op if `queues` is not configured.
+   */
+  work() {
+    this.stopped = false;
+    this.poll();
+  }
+  poll() {
+    if (this.stopped) return;
+    this.fetchAndWork().finally(() => {
+      this.pollTimer = setTimeout(
+        () => this.poll(),
+        this.configuration.pollInterval ?? CLIENT_CONFIGURATION_DEFAULTS.pollInterval
+      );
+    });
+  }
+  async fetchAndWork() {
+    const queues = Object.entries(this.configuration.queues ?? {});
+    for (const [queue, queueConfig] of queues) {
+      const running = this.running.get(queue) ?? 0;
+      const slots = queueConfig.concurrency - running;
+      if (slots <= 0) continue;
+      const jobs = await this.driver.getAvailableJobs(queue, slots, this.clientId);
+      for (const job of jobs) {
+        this.running.set(job.queue, (this.running.get(job.queue) ?? 0) + 1);
+        this.processJob(job).finally(() => {
+          this.running.set(job.queue, Math.max(0, (this.running.get(job.queue) ?? 0) - 1));
+        });
+      }
+    }
+  }
+  async processJob(job) {
+    const worker = this.workers.get(job.kind);
+    if (!worker) {
+      await this.driver.failJob(
+        job.id,
+        new Error(`No worker registered for kind: ${job.kind}`),
+        job.attempt,
+        job.maxAttempts
+      );
+      return;
+    }
+    try {
+      await worker.work(job);
+      await this.driver.completeJob(job.id);
+    } catch (error) {
+      await this.driver.failJob(job.id, error, job.attempt, job.maxAttempts);
+    }
+  }
 };
 
 export { RiverClient };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts"],"names":[],"mappings":";AAMA,IAAqB,cAArB,MAA2D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASzD,WAAA,CAAY,QAAW,aAAA,EAAoC;AACzD,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,aAAA,GAAgB,aAAA;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA,EAKA,gBAAA,GAAkC;AAChC,IAAA,OAAO,IAAA,CAAK,OAAO,gBAAA,EAAiB;AAAA,EACtC;AAAA;AAAA;AAAA;AAAA,EAKA,KAAA,GAAuB;AACrB,IAAA,OAAO,IAAA,CAAK,OAAO,KAAA,EAAM;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAA,CAA0B,IAAA,EAAS,IAAA,GAAmB,EAAC,EAA6B;AAClF,IAAA,MAAM,WAAA,GAA0B;AAAA,MAC9B,KAAA,EAAO,KAAK,aAAA,CAAc,YAAA;AAAA,MAC1B,WAAA,EAAa,KAAK,aAAA,CAAc,WAAA;AAAA,MAChC,GAAG;AAAA,KACL;AAEA,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,MAAA,CAAO,IAAA,EAAM,WAAW,CAAA;AAAA,EAC7C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,QAAA,CAA4B,EAAA,EAAQ,IAAA,EAAS,IAAA,GAAmB,EAAC,EAA6B;AAC5F,IAAA,MAAM,WAAA,GAA0B;AAAA,MAC9B,KAAA,EAAO,KAAK,aAAA,CAAc,YAAA;AAAA,MAC1B,WAAA,EAAa,KAAK,aAAA,CAAc,WAAA;AAAA,MAChC,GAAG;AAAA,KACL;AAEA,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,QAAA,CAAS,EAAA,EAAI,MAAM,WAAW,CAAA;AAAA,EACnD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,WACJ,IAAA,EAC4B;AAC5B,IAAA,MAAM,gBAAA,GAAmB,IAAA,CAAK,GAAA,CAAI,CAAC,GAAA,MAAS;AAAA,MAC1C,MAAM,GAAA,CAAI,IAAA;AAAA,MACV,IAAA,EAAM;AAAA,QACJ,KAAA,EAAO,KAAK,aAAA,CAAc,YAAA;AAAA,QAC1B,WAAA,EAAa,KAAK,aAAA,CAAc,WAAA;AAAA,QAChC,GAAG,GAAA,CAAI;AAAA;AACT,KACF,CAAE,CAAA;AAEF,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,UAAA,CAAW,gBAAgB,CAAA;AAAA,EAChD;AACF","file":"index.js","sourcesContent":["import { Driver } from './drivers';\nimport { ClientConfiguration, InsertOpts, InsertResult, JobArgs } from './types';\n\n/**\n * Provides methods to enqueue jobs and manage queue operations.\n */\nexport default class RiverClient<D extends Driver<Tx>, Tx> {\n  private readonly driver: D;\n  private readonly configuration: ClientConfiguration;\n\n  /**\n   * Creates a new RiverClient instance.\n   * @param driver - The queue driver implementation.\n   * @param configuration - Client configuration options.\n   */\n  constructor(driver: D, configuration: ClientConfiguration) {\n    this.driver = driver;\n    this.configuration = configuration;\n  }\n\n  /**\n   * Checks if the driver can connect to the database. Throws on failure.\n   */\n  verifyConnection(): Promise<void> {\n    return this.driver.verifyConnection();\n  }\n\n  /**\n   * Closes all database connections and cleans up resources.\n   */\n  close(): Promise<void> {\n    return this.driver.close();\n  }\n\n  /**\n   * Inserts a job into the queue with the specified arguments and options.\n   * @param args - The job arguments to insert.\n   * @param opts - Optional insertion options.\n   * @returns A promise that resolves to the result of the insertion operation,\n   *          including the job and whether the insert was skipped due to uniqueness.\n   */\n  insert<T extends JobArgs>(args: T, opts: InsertOpts = {}): Promise<InsertResult<T>> {\n    const defaultOpts: InsertOpts = {\n      queue: this.configuration.defaultQueue,\n      maxAttempts: this.configuration.maxAttempts,\n      ...opts,\n    };\n\n    return this.driver.insert(args, defaultOpts);\n  }\n\n  /**\n   * Inserts a job into the queue within an existing transaction or session.\n   * The transaction type (Tx) is determined by the driver implementation.\n   *\n   * @param tx - The transaction or session object to use for the insert.\n   * @param args - The job arguments to insert.\n   * @param opts - Optional insertion options.\n   * @returns A promise that resolves to the result of the insertion operation,\n   *          including the job and whether the insert was skipped due to uniqueness.\n   */\n  insertTx<T extends JobArgs>(tx: Tx, args: T, opts: InsertOpts = {}): Promise<InsertResult<T>> {\n    const defaultOpts: InsertOpts = {\n      queue: this.configuration.defaultQueue,\n      maxAttempts: this.configuration.maxAttempts,\n      ...opts,\n    };\n\n    return this.driver.insertTx(tx, args, defaultOpts);\n  }\n\n  /**\n   * Inserts multiple jobs in sequence within a single transaction.\n   * If any insert fails, all previous inserts in the batch are rolled back.\n   *\n   * @param jobs - Array of job argument and option pairs to insert.\n   * @returns A promise that resolves to an array of InsertResult objects for each job.\n   */\n  async insertMany<T extends JobArgs>(\n    jobs: { args: T; opts: InsertOpts }[],\n  ): Promise<InsertResult<T>[]> {\n    const jobsWithDefaults = jobs.map((job) => ({\n      args: job.args,\n      opts: {\n        queue: this.configuration.defaultQueue,\n        maxAttempts: this.configuration.maxAttempts,\n        ...job.opts,\n      },\n    }));\n\n    return this.driver.insertMany(jobsWithDefaults);\n  }\n}\n"]}
+{"version":3,"sources":["../src/utils/constants.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Default values applied when optional fields are not provided in ClientConfiguration.\n */\nexport const CLIENT_CONFIGURATION_DEFAULTS = {\n  pollInterval: 1000,\n};\n","import os from 'os';\nimport process from 'process';\nimport { clearTimeout, setTimeout } from 'timers';\nimport { Driver } from './drivers';\nimport { ClientConfiguration, InsertOpts, InsertResult, Job, JobArgs, Worker } from './types';\nimport { CLIENT_CONFIGURATION_DEFAULTS } from './utils';\n\n/**\n * RiverClient is the main entry point for interacting with the River job queue.\n * It supports two usage modes:\n * - Insertion only: enqueue jobs without processing them.\n * - Worker mode: register workers and call `work()` to start polling and processing jobs.\n */\nexport default class RiverClient<D extends Driver<Tx>, Tx> {\n  private readonly running: Map<string, number> = new Map();\n  private stopped = false;\n  private pollTimer: ReturnType<typeof setTimeout> | null = null;\n  private readonly driver: D;\n  private readonly configuration: ClientConfiguration;\n  private readonly workers: Map<string, Worker> = new Map();\n  private readonly clientId: string;\n\n  /**\n   * Creates a new RiverClient instance.\n   * @param driver - The driver implementation (e.g. PgDriver).\n   * @param configuration - Client options: queues, max attempts, poll interval, and client ID.\n   */\n  constructor(driver: D, configuration: ClientConfiguration) {\n    this.driver = driver;\n    this.configuration = configuration;\n    this.clientId = configuration.clientId ?? `${os.hostname()}-${process.pid}`;\n  }\n\n  /**\n   * Verifies the driver can reach the database. Throws if the connection fails.\n   */\n  async verifyConnection(): Promise<void> {\n    return this.driver.verifyConnection();\n  }\n\n  /**\n   * Stops the polling loop (if running) and closes all database connections.\n   * Always call this on shutdown to avoid resource leaks.\n   */\n  async close(): Promise<void> {\n    this.stopped = true;\n    if (this.pollTimer) clearTimeout(this.pollTimer);\n    await this.driver.close();\n  }\n\n  /**\n   * Inserts a single job into the specified queue.\n   * @param args - Job arguments including `kind` and any job-specific fields.\n   * @param opts - Insertion options. `queue` is required; `maxAttempts` defaults to the client configuration value.\n   * @returns The inserted job and a `skipped` flag indicating if it was deduplicated.\n   */\n  async insert<T extends JobArgs>(args: T, opts: InsertOpts): Promise<InsertResult<T>> {\n    const defaultOpts: InsertOpts = {\n      maxAttempts: this.configuration.maxAttempts,\n      ...opts,\n    };\n\n    return this.driver.insert(args, defaultOpts);\n  }\n\n  /**\n   * Inserts a single job within an existing transaction. Use this when the job\n   * should only be enqueued if the surrounding transaction commits.\n   * @param tx - The active transaction object (type is driver-specific).\n   * @param args - Job arguments including `kind` and any job-specific fields.\n   * @param opts - Insertion options. `queue` is required; `maxAttempts` defaults to the client configuration value.\n   * @returns The inserted job and a `skipped` flag indicating if it was deduplicated.\n   */\n  async insertTx<T extends JobArgs>(tx: Tx, args: T, opts: InsertOpts): Promise<InsertResult<T>> {\n    const defaultOpts: InsertOpts = {\n      maxAttempts: this.configuration.maxAttempts,\n      ...opts,\n    };\n\n    return this.driver.insertTx(tx, args, defaultOpts);\n  }\n\n  /**\n   * Inserts multiple jobs in a single transaction. If any insert fails, all are rolled back.\n   * @param jobs - Array of `{ args, opts }` pairs. Each `opts` must include a `queue`.\n   * @returns An array of InsertResult objects in the same order as the input.\n   */\n  async insertMany<T extends JobArgs>(\n    jobs: { args: T; opts: InsertOpts }[],\n  ): Promise<InsertResult<T>[]> {\n    const jobsWithDefaults = jobs.map((job) => ({\n      args: job.args,\n      opts: {\n        maxAttempts: this.configuration.maxAttempts,\n        ...job.opts,\n      },\n    }));\n\n    return this.driver.insertMany(jobsWithDefaults);\n  }\n\n  /**\n   * Registers a worker for a specific job kind. When a job of this kind is claimed\n   * from the queue, the worker's `work()` method will be called with the job.\n   * Must be called before `work()` for the worker to receive jobs.\n   * @param kind - The job kind string that this worker handles (e.g. `\"send_email\"`).\n   * @param worker - The worker instance that implements the `Worker<T>` interface.\n   */\n  addWorker<T extends JobArgs>(kind: string, worker: Worker<T>): void {\n    this.workers.set(kind, worker);\n  }\n\n  /**\n   * Begins polling all configured queues and dispatching jobs to registered workers.\n   * Each queue is polled independently with its own concurrency limit.\n   * No-op if `queues` is not configured.\n   */\n  work(): void {\n    this.stopped = false;\n    this.poll();\n  }\n\n  private poll(): void {\n    if (this.stopped) return;\n\n    this.fetchAndWork().finally(() => {\n      this.pollTimer = setTimeout(\n        () => this.poll(),\n        this.configuration.pollInterval ?? CLIENT_CONFIGURATION_DEFAULTS.pollInterval,\n      );\n    });\n  }\n\n  private async fetchAndWork(): Promise<void> {\n    const queues = Object.entries(this.configuration.queues ?? {});\n\n    for (const [queue, queueConfig] of queues) {\n      const running = this.running.get(queue) ?? 0;\n      const slots = queueConfig.concurrency - running;\n      if (slots <= 0) continue;\n\n      const jobs = await this.driver.getAvailableJobs(queue, slots, this.clientId);\n\n      for (const job of jobs) {\n        this.running.set(job.queue, (this.running.get(job.queue) ?? 0) + 1);\n        this.processJob(job).finally(() => {\n          this.running.set(job.queue, Math.max(0, (this.running.get(job.queue) ?? 0) - 1));\n        });\n      }\n    }\n  }\n\n  private async processJob(job: Job): Promise<void> {\n    const worker = this.workers.get(job.kind);\n\n    if (!worker) {\n      await this.driver.failJob(\n        job.id,\n        new Error(`No worker registered for kind: ${job.kind}`),\n        job.attempt,\n        job.maxAttempts,\n      );\n      return;\n    }\n\n    try {\n      await worker.work(job);\n      await this.driver.completeJob(job.id);\n    } catch (error) {\n      await this.driver.failJob(job.id, error as Error, job.attempt, job.maxAttempts);\n    }\n  }\n}\n"]}

package/dist/{insert-result-Bf0bAFvJ.d.cts → insert-result-DWZkRtk9.d.cts}

@@ -39,23 +39,23 @@ declare enum JobState {
 }
 
 /**
- * Represents a failed job attempt, including error details and stack trace.
+ * Represents the error details recorded for a single failed job attempt.
  */
 interface AttemptError {
     /**
-     * Time the error occurred
+     * ISO timestamp of when the error occurred.
      */
     at: string;
     /**
-     * Attempt number when the error occurred
+     * The attempt number that produced this error.
      */
     attempt: number;
     /**
-     * Stringified error or panic value
+     * The error message thrown by the worker.
      */
     error: string;
     /**
-     * Stack trace from a job that panicked
+     * Stack trace of the thrown error, if available.
      */
     trace: string;
 }
@@ -96,9 +96,9 @@ interface InsertOpts {
      */
     tags?: string[];
     /**
-     * Name of the job queue to insert into
+     * Name of the queue to insert the job into.
      */
-    queue?: string;
+    queue: string;
     /**
      * Job priority (1 = highest, 4 = lowest)
      */
@@ -141,79 +141,80 @@ interface JobArgs {
 }
 
 /**
- * Represents a job persisted in the database, including its state, metadata, and scheduling information.
+ * A job record as stored in the database.
+ * @template T - The shape of the job's arguments.
  */
 interface Job<T extends JobArgs = JobArgs> {
     /**
-     * Unique job ID, generated by the database
+     * Auto-generated unique job ID.
      */
     id: number;
     /**
-     * Current state of the job (e.g., available, completed)
+     * Current lifecycle state (e.g. available, running, completed).
      */
     state: JobState;
     /**
-     * Current attempt number, incremented each time the job is worked
+     * How many times this job has been attempted so far.
      */
     attempt: number;
     /**
-     * Maximum number of attempts before the job stops retrying
+     * Maximum attempts allowed before the job is discarded.
      */
     maxAttempts: number;
     /**
-     * Last time the job was worked, null if never
+     * Timestamp of the most recent attempt, null if never attempted.
      */
     attemptedAt: Date | null;
     /**
-     * When the job record was created
+     * Timestamp of when the job record was created.
      */
     createdAt: Date;
     /**
-     * When the job was finalized (completed or errored for last time), null if not finalized
+     * Timestamp of when the job was finalized (completed or discarded), null if still active.
      */
     finalizedAt: Date | null;
     /**
-     * When the job is scheduled to become available
+     * Timestamp of when the job becomes eligible for processing.
      */
     scheduledAt: Date;
     /**
-     * Job priority (1 = highest, 4 = lowest)
+     * Processing priority. Lower numbers run first (1 = highest, 4 = lowest).
      */
     priority: number;
     /**
-     * Job arguments, decoded from JSON
+     * Typed job arguments, decoded from the JSON stored in the database.
      */
     args: T;
     /**
-     * Worker IDs that have worked this job, null if never
+     * List of client IDs that have attempted this job, in order. Null if never attempted.
      */
     attemptedBy: string[] | null;
     /**
-     * Errors for each attempt, ordered earliest to latest, null if none
+     * Error details for each failed attempt, ordered earliest to latest. Null if no failures.
      */
     errors: AttemptError[] | null;
     /**
-     * Job type identifier, set at insertion
+     * The job kind string used to route it to the correct worker (e.g. `"send_email"`).
      */
     kind: string;
     /**
-     * Arbitrary metadata associated with the job
+     * Arbitrary key-value metadata attached to the job at insertion.
      */
     metadata: Record<string, unknown>;
     /**
-     * Name of the queue where the job will be worked
+     * The queue this job belongs to.
      */
     queue: string;
     /**
-     * List of tags for grouping and categorizing jobs
+     * Tags for grouping or filtering jobs.
      */
     tags: string[];
     /**
-     * Unique key for job within its kind, used for unique insertions, null if not set
+     * Hashed uniqueness key. Null if the job was not inserted with uniqueness options.
      */
     uniqueKey: Buffer | null;
     /**
-     * States required for uniqueness, null if not set
+     * The job states considered when enforcing uniqueness. Null if not set.
      */
     uniqueStates: JobState[] | null;
 }

package/dist/{insert-result-Bf0bAFvJ.d.ts → insert-result-DWZkRtk9.d.ts}

@@ -39,23 +39,23 @@ declare enum JobState {
 }
 
 /**
- * Represents a failed job attempt, including error details and stack trace.
+ * Represents the error details recorded for a single failed job attempt.
  */
 interface AttemptError {
     /**
-     * Time the error occurred
+     * ISO timestamp of when the error occurred.
      */
     at: string;
     /**
-     * Attempt number when the error occurred
+     * The attempt number that produced this error.
      */
     attempt: number;
     /**
-     * Stringified error or panic value
+     * The error message thrown by the worker.
      */
     error: string;
     /**
-     * Stack trace from a job that panicked
+     * Stack trace of the thrown error, if available.
      */
     trace: string;
 }
@@ -96,9 +96,9 @@ interface InsertOpts {
      */
     tags?: string[];
     /**
-     * Name of the job queue to insert into
+     * Name of the queue to insert the job into.
      */
-    queue?: string;
+    queue: string;
     /**
      * Job priority (1 = highest, 4 = lowest)
      */
@@ -141,79 +141,80 @@ interface JobArgs {
 }
 
 /**
- * Represents a job persisted in the database, including its state, metadata, and scheduling information.
+ * A job record as stored in the database.
+ * @template T - The shape of the job's arguments.
  */
 interface Job<T extends JobArgs = JobArgs> {
     /**
-     * Unique job ID, generated by the database
+     * Auto-generated unique job ID.
      */
     id: number;
     /**
-     * Current state of the job (e.g., available, completed)
+     * Current lifecycle state (e.g. available, running, completed).
      */
     state: JobState;
     /**
-     * Current attempt number, incremented each time the job is worked
+     * How many times this job has been attempted so far.
      */
     attempt: number;
     /**
-     * Maximum number of attempts before the job stops retrying
+     * Maximum attempts allowed before the job is discarded.
      */
     maxAttempts: number;
     /**
-     * Last time the job was worked, null if never
+     * Timestamp of the most recent attempt, null if never attempted.
      */
     attemptedAt: Date | null;
     /**
-     * When the job record was created
+     * Timestamp of when the job record was created.
      */
     createdAt: Date;
     /**
-     * When the job was finalized (completed or errored for last time), null if not finalized
+     * Timestamp of when the job was finalized (completed or discarded), null if still active.
      */
     finalizedAt: Date | null;
     /**
-     * When the job is scheduled to become available
+     * Timestamp of when the job becomes eligible for processing.
      */
     scheduledAt: Date;
     /**
-     * Job priority (1 = highest, 4 = lowest)
+     * Processing priority. Lower numbers run first (1 = highest, 4 = lowest).
      */
     priority: number;
     /**
-     * Job arguments, decoded from JSON
+     * Typed job arguments, decoded from the JSON stored in the database.
      */
     args: T;
     /**
-     * Worker IDs that have worked this job, null if never
+     * List of client IDs that have attempted this job, in order. Null if never attempted.
      */
     attemptedBy: string[] | null;
     /**
-     * Errors for each attempt, ordered earliest to latest, null if none
+     * Error details for each failed attempt, ordered earliest to latest. Null if no failures.
      */
     errors: AttemptError[] | null;
     /**
-     * Job type identifier, set at insertion
+     * The job kind string used to route it to the correct worker (e.g. `"send_email"`).
      */
     kind: string;
     /**
-     * Arbitrary metadata associated with the job
+     * Arbitrary key-value metadata attached to the job at insertion.
      */
     metadata: Record<string, unknown>;
     /**
-     * Name of the queue where the job will be worked
+     * The queue this job belongs to.
      */
     queue: string;
     /**
-     * List of tags for grouping and categorizing jobs
+     * Tags for grouping or filtering jobs.
      */
     tags: string[];
     /**
-     * Unique key for job within its kind, used for unique insertions, null if not set
+     * Hashed uniqueness key. Null if the job was not inserted with uniqueness options.
      */
     uniqueKey: Buffer | null;
     /**
-     * States required for uniqueness, null if not set
+     * The job states considered when enforcing uniqueness. Null if not set.
      */
     uniqueStates: JobState[] | null;
 }

package/dist/types.d.cts

@@ -1,18 +1,54 @@
-export { A as AttemptError, I as InsertOpts, a as InsertResult, b as Job, J as JobArgs, c as JobState, U as UniqueOpts } from './insert-result-Bf0bAFvJ.cjs';
+import { J as JobArgs, b as Job } from './insert-result-DWZkRtk9.cjs';
+export { A as AttemptError, I as InsertOpts, a as InsertResult, c as JobState, U as UniqueOpts } from './insert-result-DWZkRtk9.cjs';
 import 'buffer';
 
 /**
- * Configuration options for the RiverQueue client.
+ * Configuration for a single queue.
+ */
+interface QueueConfiguration {
+    /**
+     * Maximum number of jobs that can be processed simultaneously for this queue.
+     */
+    concurrency: number;
+}
+
+/**
+ * Configuration options for the RiverClient.
  */
 interface ClientConfiguration {
     /**
-     * Default queue name for job insertion
+     * Queues to poll and their per-queue configuration (e.g. concurrency).
+     * Only used when `work()` is called. Keys are queue names.
      */
-    defaultQueue?: string;
+    queues?: Record<string, QueueConfiguration>;
     /**
-     * Maximum number of attempts for jobs
+     * Default maximum number of attempts for inserted jobs before they are discarded.
      */
     maxAttempts?: number;
+    /**
+     * How often (in milliseconds) the client polls the database for available jobs.
+     * Only applies when `work()` is called.
+     */
+    pollInterval?: number;
+    /**
+     * Unique identifier for this client instance, recorded in each job's `attemptedBy` list.
+     * Defaults to `hostname-pid` (e.g. `"web-server-12345"`).
+     */
+    clientId?: string;
+}
+
+/**
+ * Interface for job workers. Implement this for each job kind you want to process.
+ * Register instances with `client.addWorker(kind, worker)` before calling `client.work()`.
+ * @template T - The shape of the job's arguments.
+ */
+interface Worker<T extends JobArgs = JobArgs> {
+    /**
+     * Called by the client when a job of the registered kind is claimed from the queue.
+     * Throw an error to mark the job as failed; return normally to mark it as completed.
+     * @param job - The claimed job including its args, metadata, and attempt info.
+     */
+    work(job: Job<T>): Promise<void>;
 }
 
-export type { ClientConfiguration };
+export { type ClientConfiguration, Job, JobArgs, type QueueConfiguration, type Worker };

package/dist/types.d.ts

@@ -1,18 +1,54 @@
-export { A as AttemptError, I as InsertOpts, a as InsertResult, b as Job, J as JobArgs, c as JobState, U as UniqueOpts } from './insert-result-Bf0bAFvJ.js';
+import { J as JobArgs, b as Job } from './insert-result-DWZkRtk9.js';
+export { A as AttemptError, I as InsertOpts, a as InsertResult, c as JobState, U as UniqueOpts } from './insert-result-DWZkRtk9.js';
 import 'buffer';
 
 /**
- * Configuration options for the RiverQueue client.
+ * Configuration for a single queue.
+ */
+interface QueueConfiguration {
+    /**
+     * Maximum number of jobs that can be processed simultaneously for this queue.
+     */
+    concurrency: number;
+}
+
+/**
+ * Configuration options for the RiverClient.
  */
 interface ClientConfiguration {
     /**
-     * Default queue name for job insertion
+     * Queues to poll and their per-queue configuration (e.g. concurrency).
+     * Only used when `work()` is called. Keys are queue names.
      */
-    defaultQueue?: string;
+    queues?: Record<string, QueueConfiguration>;
     /**
-     * Maximum number of attempts for jobs
+     * Default maximum number of attempts for inserted jobs before they are discarded.
      */
     maxAttempts?: number;
+    /**
+     * How often (in milliseconds) the client polls the database for available jobs.
+     * Only applies when `work()` is called.
+     */
+    pollInterval?: number;
+    /**
+     * Unique identifier for this client instance, recorded in each job's `attemptedBy` list.
+     * Defaults to `hostname-pid` (e.g. `"web-server-12345"`).
+     */
+    clientId?: string;
+}
+
+/**
+ * Interface for job workers. Implement this for each job kind you want to process.
+ * Register instances with `client.addWorker(kind, worker)` before calling `client.work()`.
+ * @template T - The shape of the job's arguments.
+ */
+interface Worker<T extends JobArgs = JobArgs> {
+    /**
+     * Called by the client when a job of the registered kind is claimed from the queue.
+     * Throw an error to mark the job as failed; return normally to mark it as completed.
+     * @param job - The claimed job including its args, metadata, and attempt info.
+     */
+    work(job: Job<T>): Promise<void>;
 }
 
-export type { ClientConfiguration };
+export { type ClientConfiguration, Job, JobArgs, type QueueConfiguration, type Worker };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odunlamizo/node-river",
-  "version": "1.0.8",
+  "version": "1.1.1",
   "description": "Node.js library to support River integration.",
   "type": "module",
   "main": "dist/index.cjs",