@prsm/queue 2.1.0 → 3.0.0

package/README.md

@@ -110,7 +110,7 @@ Throw an error to trigger retry. After `maxRetries`, the task fails permanently.
 
 ## Grouped Queues
 
-Isolated concurrency per key - perfect for per-tenant throttling.
+Isolated concurrency per key - perfect for per-tenant throttling. Pass `{ group }` as the second argument to `push` or `pushAndWait`.
 
 ```js
 const queue = new Queue({
@@ -124,11 +124,11 @@ queue.process(async (payload) => {
 
 await queue.ready()
 
-await queue.group('tenant-123').push({ action: 'sync' })
-await queue.group('tenant-456').push({ action: 'sync' })
+await queue.push({ action: 'sync' }, { group: 'tenant-123' })
+await queue.push({ action: 'sync' }, { group: 'tenant-456' })
 ```
 
-Each tenant processes independently. One slow tenant won't block others. Total concurrent tasks across all tenants is capped by `concurrency`.
+Each tenant processes independently. One slow tenant won't block others. Total concurrent tasks across all tenants is capped by `concurrency`. When the group is conditional, just omit the option - no branching needed.
 
 ## Events
 
@@ -147,7 +147,7 @@ queue.on('drain', () => {})
   uuid: string,
   payload: any,
   createdAt: number,
-  groupKey?: string,  // present when pushed via group()
+  groupKey?: string,  // present when pushed with { group }
   attempts: number
 }
 ```
@@ -169,7 +169,7 @@ queue.process(async ({ prompt }) => {
 
 app.post('/api/generate', async (req, res) => {
   const { tenantId, prompt } = req.body
-  const taskId = await queue.group(tenantId).push({ prompt })
+  const taskId = await queue.push({ prompt }, { group: tenantId })
   res.json({ queued: true, taskId })
 })
 ```
@@ -202,10 +202,10 @@ queue.on('failed', ({ task, error }) => {
 })
 
 mesh.exposeCommand('generate-report', async (ctx) => {
-  const taskId = await queue.group(ctx.connection.id).push({
+  const taskId = await queue.push({
     connectionId: ctx.connection.id,
     ...ctx.payload,
-  })
+  }, { group: ctx.connection.id })
   return { queued: true, taskId }
 })
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prsm/queue",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "Redis-backed distributed task queue with grouped concurrency, retries, and rate limiting",
   "type": "module",
   "exports": {

package/src/queue.js

@@ -151,68 +151,58 @@ export default class Queue extends EventEmitter {
 
   /**
    * @param {any} payload
+   * @param {{ group?: string }} [options]
    * @returns {Promise<string>}
    */
-  async push(payload) {
+  async push(payload, { group } = {}) {
     if (this._closed) throw new Error("Queue is closed")
-    const task = { uuid: randomUUID(), payload, createdAt: Date.now(), attempts: 0 }
-    await this._redis.lPush("queue:tasks", JSON.stringify(task))
+    const task = group
+      ? { uuid: randomUUID(), payload, createdAt: Date.now(), groupKey: group, attempts: 0 }
+      : { uuid: randomUUID(), payload, createdAt: Date.now(), attempts: 0 }
     this._pushed++
+    try {
+      await this._enqueue(task, group)
+    } catch (err) {
+      this._pushed--
+      throw err
+    }
     this.emit("new", { task })
     return task.uuid
   }
 
   /**
    * @param {any} payload
-   * @param {number|string} [timeout] - max time to wait for result, ms or string like "30s" (default 0, no limit)
+   * @param {{ group?: string, timeout?: number|string }} [options]
    * @returns {Promise<any>}
    */
-  pushAndWait(payload, timeout = 0) {
+  pushAndWait(payload, { group, timeout = 0 } = {}) {
     if (this._closed) return Promise.reject(new Error("Queue is closed"))
-    const task = { uuid: randomUUID(), payload, createdAt: Date.now(), attempts: 0 }
+    const task = group
+      ? { uuid: randomUUID(), payload, createdAt: Date.now(), groupKey: group, attempts: 0 }
+      : { uuid: randomUUID(), payload, createdAt: Date.now(), attempts: 0 }
+    this._pushed++
     const result = this._awaitTask(task.uuid, timeout)
     result.catch(() => {})
-    return this._redis.lPush("queue:tasks", JSON.stringify(task)).then(() => {
-      this._pushed++
+    return this._enqueue(task, group).then(() => {
       this.emit("new", { task })
       return result
+    }, (err) => {
+      this._pushed--
+      throw err
     })
   }
 
-  /**
-   * @param {string} key
-   * @returns {{ push: (payload: any) => Promise<string>, pushAndWait: (payload: any, timeout?: number|string) => Promise<any> }}
-   */
-  group(key) {
-    const makeTask = (payload) => {
-      if (this._closed) throw new Error("Queue is closed")
-      return { uuid: randomUUID(), payload, createdAt: Date.now(), groupKey: key, attempts: 0 }
-    }
-
-    const commit = (task) => {
-      return this._redis.lPush(`queue:groups:${key}`, JSON.stringify(task)).then(async () => {
-        this._pushed++
-        this.emit("new", { task })
-        if (!this._groupWorkers.has(key)) {
-          this._groupWorkers.set(key, new Map())
-          this._groupInFlight.set(key, 0)
-          await this._startGroupWorkers(key)
-        }
-      })
-    }
-
-    return {
-      push: async (payload) => {
-        const task = makeTask(payload)
-        await commit(task)
-        return task.uuid
-      },
-      pushAndWait: (payload, timeout = 0) => {
-        const task = makeTask(payload)
-        const result = this._awaitTask(task.uuid, timeout)
-        result.catch(() => {})
-        return commit(task).then(() => result)
-      },
+  /** @private */
+  async _enqueue(task, group) {
+    if (group) {
+      await this._redis.lPush(`queue:groups:${group}`, JSON.stringify(task))
+      if (!this._groupWorkers.has(group)) {
+        this._groupWorkers.set(group, new Map())
+        this._groupInFlight.set(group, 0)
+        await this._startGroupWorkers(group)
+      }
+    } else {
+      await this._redis.lPush("queue:tasks", JSON.stringify(task))
     }
   }
 
@@ -259,6 +249,7 @@ export default class Queue extends EventEmitter {
     await this._readyPromise.catch(() => {})
 
     if (this._cleanupTimer) clearInterval(this._cleanupTimer)
+    clearTimeout(this._drainTimer)
 
     this._workers.clear()
     for (const groupWorkers of this._groupWorkers.values()) groupWorkers.clear()
@@ -502,7 +493,10 @@ export default class Queue extends EventEmitter {
   }
 
   _emitDrain() {
-    if (this._inFlight === 0 && this._totalSettled >= this._pushed) this.emit("drain")
+    clearTimeout(this._drainTimer)
+    this._drainTimer = setTimeout(() => {
+      if (this._inFlight === 0 && this._totalSettled >= this._pushed) this.emit("drain")
+    }, 0)
   }
 
   async _periodicCleanup() {

package/types/queue.d.ts

@@ -2357,23 +2357,23 @@ export default class Queue extends EventEmitter<[never]> {
     process(handler: TaskHandler): void;
     /**
      * @param {any} payload
+     * @param {{ group?: string }} [options]
      * @returns {Promise<string>}
      */
-    push(payload: any): Promise<string>;
+    push(payload: any, { group }?: {
+        group?: string;
+    }): Promise<string>;
     /**
      * @param {any} payload
-     * @param {number|string} [timeout] - max time to wait for result, ms or string like "30s" (default 0, no limit)
+     * @param {{ group?: string, timeout?: number|string }} [options]
      * @returns {Promise<any>}
      */
-    pushAndWait(payload: any, timeout?: number | string): Promise<any>;
-    /**
-     * @param {string} key
-     * @returns {{ push: (payload: any) => Promise<string>, pushAndWait: (payload: any, timeout?: number|string) => Promise<any> }}
-     */
-    group(key: string): {
-        push: (payload: any) => Promise<string>;
-        pushAndWait: (payload: any, timeout?: number | string) => Promise<any>;
-    };
+    pushAndWait(payload: any, { group, timeout }?: {
+        group?: string;
+        timeout?: number | string;
+    }): Promise<any>;
+    /** @private */
+    private _enqueue;
     /** @private */
     private _awaitTask;
     /** @returns {Promise<void>} */
@@ -4704,6 +4704,7 @@ export default class Queue extends EventEmitter<[never]> {
     _processTask(task: any, opts: any): Promise<void>;
     _settle(): void;
     _emitDrain(): void;
+    _drainTimer: NodeJS.Timeout;
     _periodicCleanup(): Promise<void>;
 }
 export type QueueOptions = {