@prsm/queue 2.1.1 → 3.0.1

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()
+  group?: 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 })
 })
 ```
@@ -178,15 +178,15 @@ Each tenant gets up to 2 concurrent LLM calls with a 50ms pause between them. To
 
 ## WebSocket Integration with [mesh](https://github.com/nvms/mesh)
 
-Queue events are local-only - only the server that processes a task emits `complete`/`failed`. Use [mesh](https://github.com/nvms/mesh) to push results to connected clients in real time.
+Queue events are local-only - only the server that processes a task emits `complete`/`failed`. Use [@prsm/realtime](https://github.com/nvms/realtime) to push results to connected clients in real time.
 
 Send results to a specific client:
 
 ```js
 import Queue from '@prsm/queue'
-import { MeshServer } from '@mesh-kit/server'
+import { RealtimeServer } from '@prsm/realtime'
 
-const mesh = new MeshServer({ redis: { host: 'localhost', port: 6379 } })
+const realtime = new RealtimeServer({ redis: { host: 'localhost', port: 6379 } })
 const queue = new Queue({ concurrency: 5, groups: { concurrency: 1 } })
 
 queue.process(async (payload) => {
@@ -194,26 +194,26 @@ queue.process(async (payload) => {
 })
 
 queue.on('complete', ({ task, result }) => {
-  mesh.sendTo(task.payload.connectionId, 'job:complete', result)
+  realtime.sendTo(task.payload.connectionId, 'job:complete', result)
 })
 
 queue.on('failed', ({ task, error }) => {
-  mesh.sendTo(task.payload.connectionId, 'job:failed', { error: error.message })
+  realtime.sendTo(task.payload.connectionId, 'job:failed', { error: error.message })
 })
 
-mesh.exposeCommand('generate-report', async (ctx) => {
-  const taskId = await queue.group(ctx.connection.id).push({
+realtime.exposeCommand('generate-report', async (ctx) => {
+  const taskId = await queue.push({
     connectionId: ctx.connection.id,
     ...ctx.payload,
-  })
+  }, { group: ctx.connection.id })
   return { queued: true, taskId }
 })
 
 await queue.ready()
-await mesh.listen(8080)
+await realtime.listen(8080)
 ```
 
-Both queue and mesh use the same Redis instance. No key conflicts (`queue:*` vs `mesh:*`).
+Both queue and realtime use the same Redis instance. No key conflicts (`queue:*` vs `mesh:*`).
 
 ## Horizontal Scaling
 

package/package.json

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

package/src/queue.js

@@ -20,7 +20,7 @@ import ms from "@prsm/ms"
  * @property {string} uuid
  * @property {any} payload
  * @property {number} createdAt
- * @property {string} [groupKey]
+ * @property {string} [group]
  * @property {number} attempts
  */
 
@@ -151,14 +151,17 @@ 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 }
+    const task = group
+      ? { uuid: randomUUID(), payload, createdAt: Date.now(), group, attempts: 0 }
+      : { uuid: randomUUID(), payload, createdAt: Date.now(), attempts: 0 }
     this._pushed++
     try {
-      await this._redis.lPush("queue:tasks", JSON.stringify(task))
+      await this._enqueue(task, group)
     } catch (err) {
       this._pushed--
       throw err
@@ -169,16 +172,18 @@ export default class Queue extends EventEmitter {
 
   /**
    * @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(), 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(() => {
+    return this._enqueue(task, group).then(() => {
       this.emit("new", { task })
       return result
     }, (err) => {
@@ -187,44 +192,17 @@ export default class Queue extends EventEmitter {
     })
   }
 
-  /**
-   * @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.emit("new", { task })
-        if (!this._groupWorkers.has(key)) {
-          this._groupWorkers.set(key, new Map())
-          this._groupInFlight.set(key, 0)
-          await this._startGroupWorkers(key)
-        }
-      }, (err) => {
-        this._pushed--
-        throw err
-      })
-    }
-
-    return {
-      push: async (payload) => {
-        const task = makeTask(payload)
-        this._pushed++
-        await commit(task)
-        return task.uuid
-      },
-      pushAndWait: (payload, timeout = 0) => {
-        const task = makeTask(payload)
-        this._pushed++
-        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))
     }
   }
 
@@ -360,13 +338,13 @@ export default class Queue extends EventEmitter {
       timeout: this._options.groups.timeout,
       maxRetries: this._options.groups.maxRetries,
       retryKey: `queue:groups:${groupKey}`,
-      groupKey,
+      group: groupKey,
     }
     this._runWorkerLoop(workerId, client, `queue:groups:${groupKey}`, groupWorkers, opts)
   }
 
   async _runWorkerLoop(workerId, client, key, activeMap, opts) {
-    const delay = opts.groupKey ? this._options.groups.delay : this._options.delay
+    const delay = opts.group ? this._options.groups.delay : this._options.delay
 
     while (activeMap.get(workerId)) {
       try {
@@ -393,17 +371,17 @@ export default class Queue extends EventEmitter {
           }
 
           this._inFlight++
-          if (opts.groupKey) {
-            this._groupInFlight.set(opts.groupKey, (this._groupInFlight.get(opts.groupKey) || 0) + 1)
+          if (opts.group) {
+            this._groupInFlight.set(opts.group, (this._groupInFlight.get(opts.group) || 0) + 1)
           }
 
           try {
             await this._processTask(task, opts)
           } finally {
-            if (opts.groupKey) {
-              const count = (this._groupInFlight.get(opts.groupKey) || 1) - 1
-              if (count <= 0) this._groupInFlight.delete(opts.groupKey)
-              else this._groupInFlight.set(opts.groupKey, count)
+            if (opts.group) {
+              const count = (this._groupInFlight.get(opts.group) || 1) - 1
+              if (count <= 0) this._groupInFlight.delete(opts.group)
+              else this._groupInFlight.set(opts.group, count)
             }
             if (leaseId) await this._releaseGlobal(leaseId).catch(() => {})
           }

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>} */
@@ -4752,7 +4752,7 @@ export type Task = {
     uuid: string;
     payload: any;
     createdAt: number;
-    groupKey?: string;
+    group?: string;
     attempts: number;
 };
 export type TaskHandler = (payload: any, task: Task) => Promise<any> | any;