@prsm/queue 1.0.0 → 1.0.2

package/README.md

@@ -1,101 +1,145 @@
-# Queues
+# @prsm/queue
 
-You must place your queue definitions in `/queues`. For example:
+Redis-backed distributed task queue with grouped concurrency, retries, and rate limiting.
+
+## Installation
 
 ```bash
-src
-└── app
-    └── queues
-        ├── mailer.ts
-        └── llm-processor.ts
+npm install @prsm/queue
 ```
 
-Each queue module is expected to have a default export that is an asynchronous function, which serves as the handler for each queued job. Additionally, a `queue` object must be exported that generates and configures the queue.
+## Quick Start
 
-Here's an example queue definition.
+```ts
+import Queue from '@prsm/queue'
 
-```typescript
-// /src/app/queues/mail.ts
-import Queue from "@prsm/queues";
+const queue = new Queue({
+  concurrency: 2,
+  maxRetries: 3
+})
 
-interface MailPayload {
-  recipient: string;
-  subject: string;
-  body: string;
-}
+queue.process(async (payload) => {
+  return await doWork(payload)
+})
 
-// The task to be executed for each queued job when a worker becomes available.
-export default async function ({ recipient, subject, body }: MailPayload) {
-  // send an email
-}
+queue.on('complete', ({ task, result }) => {
+  console.log('Done:', task.uuid, result)
+})
 
-export const queue = new Queue<MailPayload>({
-  // Number of concurrent queue workers.
-  concurrency: 1,
+queue.on('failed', ({ task, error }) => {
+  console.log('Failed after retries:', task.uuid, error.message)
+})
 
-  // Once a worker becomes available, it will wait delay ms before processing the next job.
-  delay: 0,
+await queue.push({ userId: 123, action: 'sync' })
+```
+
+## Options
 
-  // After it is initiated, a task will fail if it does not resolve within timeout ms.
-  timeout: 0,
+```ts
+const queue = new Queue({
+  concurrency: 2,           // worker count
+  delay: '100ms',           // pause between tasks (string or ms)
+  timeout: '30s',           // max task duration
+  maxRetries: 3,            // attempts before failing
 
-  // Groups enable scoped queues based on a key, such as a recipient's address.
-  // This can be useful, for instance, if we want to restrict the number of emails we send to a particular
-  // recipient during a specific time period.
-  //
-  // By default, a group will inherit the queue's config above, but you can
-  // override that config here.
   groups: {
-    concurrency: 3,
-    delay: "5s",
-    timeout: "1m"
+    concurrency: 1,         // workers per group
+    delay: '50ms',
+    timeout: '10s',
+    maxRetries: 3
   },
-});
-```
 
-## Adding jobs to a queue
+  redisOptions: {
+    host: 'localhost',
+    port: 6379
+  }
+})
+```
 
-To add a job to the queue, import the queue and call `queue.push`.
+## Process Handler
 
-```typescript
-import { queue as mailQueue } from "../queues/mail";
-mailQueue.push({ recipient, subject, body });
+```ts
+queue.process(async (payload, task) => {
+  console.log('Task:', task.uuid, 'Attempt:', task.attempts)
+  return await someWork(payload)
+})
 ```
 
-To track task status, listen for events emitted by the queue. The queue will emit events when:
+Throw an error to trigger retry. After `maxRetries`, the task fails permanently.
 
-1. A job is added to the queue
-2. A job is completed
-3. A job fails
+## Grouped Queues
 
-```typescript
-// /src/app/http/mail/index.ts
-import { queue as mailQueue } from "../queues/mail";
+Isolated concurrency per key - perfect for per-tenant rate limiting.
 
-const onNew = ({ task }) => console.log("Task created:", task.uuid);
-const onFailed = ({ task }) => console.log("Task failed:", task.uuid);
-const onComplete = ({ task }) => console.log("Task complete:", task.uuid);
+```ts
+const queue = new Queue({
+  groups: { concurrency: 1, delay: '50ms' }
+})
 
-mailQueue.on("new", onNew);
-mailQueue.on("failed", onFailed);
-mailQueue.on("complete", onComplete);
+queue.process(async (payload) => {
+  return await callExternalAPI(payload)
+})
 
-// POST /mail
-export async function post(c: Context, { body: { recipient, subject, body } }) {
-  const uuid = mailQueue.push({ recipient, subject, body });
-  return Respond.OK(c, { uuid });
-}
+await queue.group('tenant-123').push({ action: 'sync' })
+await queue.group('tenant-456').push({ action: 'sync' })
+```
+
+Each tenant processes independently. One slow tenant won't block others.
+
+## Events
+
+```ts
+queue.on('new', ({ task }) => {})
+queue.on('complete', ({ task, result }) => {})
+queue.on('retry', ({ task, error, attempt }) => {})
+queue.on('failed', ({ task, error }) => {})
+```
+
+## Task Object
 
-// /src/app/queues/mail.ts
-export default async function({ recipient, subject, body }) {
-  // send a very important email
+```ts
+interface Task<T> {
+  uuid: string
+  payload: T
+  createdAt: number
+  groupKey?: string
+  attempts: number
 }
 ```
 
-You can add a grouped queue like:
+## Rate Limiting Example
+
+20 LLM calls/sec per tenant:
+
+```ts
+const queue = new Queue({
+  groups: { concurrency: 20, delay: '50ms' },
+  maxRetries: 3
+})
+
+queue.process(async ({ prompt }) => {
+  return await llm.complete(prompt)
+})
+
+app.post('/api/generate', async (req, res) => {
+  const { tenantId, prompt } = req.body
+  const taskId = await queue.group(tenantId).push({ prompt })
+  res.json({ queued: true, taskId })
+})
+```
+
+## Horizontal Scaling
+
+Multiple servers can push to the same queue. Redis coordinates via atomic operations - no duplicate processing.
 
-```typescript
-mailQueue.group(recipient).push({ recipient, subject, body });
+Note: events are local. Only the server that processes a task emits `complete`/`failed`. Use Redis pub/sub or WebSockets to broadcast results across servers.
+
+## Cleanup
+
+```ts
+await queue.close()
 ```
 
-As mentioned above, this is a scoped queue. The scoped queue has its own concurrency, delay, and timeout.
+## License
+
+MIT

package/dist/index.cjs

@@ -41,11 +41,15 @@ var import_crypto = require("crypto");
 var import_ms = __toESM(require("@prsm/ms"), 1);
 var Queue = class extends import_events.EventEmitter {
   redis;
+  workerClients = [];
   options;
   handler;
   workers = /* @__PURE__ */ new Map();
   groupWorkers = /* @__PURE__ */ new Map();
   cleanupTimer;
+  _ready;
+  _inFlight = 0;
+  _totalSettled = 0;
   constructor(options = {}) {
     super();
     this.options = {
@@ -65,11 +69,20 @@ var Queue = class extends import_events.EventEmitter {
     this.redis = (0, import_redis.createClient)(this.options.redisOptions);
     this.redis.on("error", () => {
     });
-    this.initializeRedis();
+    this._ready = this.initializeRedis();
   }
+  /** resolves when redis is connected and all workers are ready to accept tasks */
+  ready() {
+    return this._ready;
+  }
+  get inFlight() {
+    return this._inFlight;
+  }
+  /** register the handler that processes each task. only one handler per queue. */
   process(handler) {
     this.handler = handler;
   }
+  /** push a task to the main queue. returns the task uuid. */
   async push(payload) {
     const task = {
       uuid: (0, import_crypto.randomUUID)(),
@@ -81,6 +94,7 @@ var Queue = class extends import_events.EventEmitter {
     this.emit("new", { task });
     return task.uuid;
   }
+  /** returns a scoped pusher for a named group. each group gets its own worker pool, spun up on first push. */
   group(key) {
     return {
       push: async (payload) => {
@@ -96,63 +110,60 @@ var Queue = class extends import_events.EventEmitter {
         if (!this.groupWorkers.has(key)) {
           this.groupWorkers.set(key, /* @__PURE__ */ new Map());
           await this.startGroupWorkers(key);
-          await new Promise((resolve) => setTimeout(resolve, 50));
         }
         return task.uuid;
       }
     };
   }
+  async createWorkerClient() {
+    const client = this.redis.duplicate();
+    client.on("error", () => {
+    });
+    await client.connect();
+    this.workerClients.push(client);
+    return client;
+  }
   async startWorkers() {
+    const ready = [];
     for (let i = 0; i < this.options.concurrency; i++) {
-      this.startWorker(`worker-${i}`);
+      ready.push(this.startWorker(`worker-${i}`));
     }
+    await Promise.all(ready);
   }
   async startGroupWorkers(groupKey) {
     const groupWorkers = this.groupWorkers.get(groupKey);
+    const ready = [];
     for (let i = 0; i < this.options.groups.concurrency; i++) {
       const workerId = `group-${groupKey}-worker-${i}`;
       groupWorkers.set(workerId, true);
-      this.startGroupWorker(workerId, groupKey);
+      ready.push(this.startGroupWorker(workerId, groupKey));
     }
-    await new Promise((resolve) => setTimeout(resolve, 100));
+    await Promise.all(ready);
   }
   async startWorker(workerId) {
     this.workers.set(workerId, true);
-    while (this.workers.get(workerId)) {
-      try {
-        if (!this.redis.isOpen) {
-          break;
-        }
-        const taskData = await this.redis.brPop("queue:tasks", 1);
-        if (taskData) {
-          const task = JSON.parse(taskData.element);
-          await this.processTask(task);
-        }
-        if (this.options.delay > 0) {
-          await new Promise((resolve) => setTimeout(resolve, this.options.delay));
-        }
-      } catch (err) {
-        const error = err;
-        if (error.message?.includes("closed") || error.message?.includes("ClientClosedError")) {
-          break;
-        }
-      }
-    }
+    const client = await this.createWorkerClient();
+    this.runWorkerLoop(workerId, client, "queue:tasks", this.workers, (task) => this.processTask(task));
   }
   async startGroupWorker(workerId, groupKey) {
     const groupWorkers = this.groupWorkers.get(groupKey);
-    while (groupWorkers.get(workerId)) {
+    const client = await this.createWorkerClient();
+    this.runWorkerLoop(workerId, client, `queue:groups:${groupKey}`, groupWorkers, (task) => this.processGroupTask(task));
+  }
+  async runWorkerLoop(workerId, client, key, activeMap, processFn) {
+    const isGrouped = key.startsWith("queue:groups:");
+    const delay = isGrouped ? this.options.groups.delay : this.options.delay;
+    while (activeMap.get(workerId)) {
       try {
-        if (!this.redis.isOpen) {
-          break;
-        }
-        const taskData = await this.redis.brPop(`queue:groups:${groupKey}`, 1);
+        if (!client.isOpen) break;
+        const taskData = await client.brPop(key, 1);
         if (taskData) {
           const task = JSON.parse(taskData.element);
-          await this.processGroupTask(task);
+          this._inFlight++;
+          await processFn(task);
         }
-        if (this.options.groups.delay > 0) {
-          await new Promise((resolve) => setTimeout(resolve, this.options.groups.delay));
+        if (delay > 0) {
+          await new Promise((resolve) => setTimeout(resolve, delay));
         }
       } catch (err) {
         const error = err;
@@ -167,6 +178,7 @@ var Queue = class extends import_events.EventEmitter {
     try {
       if (!this.handler) {
         this.emit("complete", { task, result: void 0 });
+        this.settle();
         return;
       }
       const timeoutPromise = this.options.timeout > 0 ? new Promise(
@@ -175,12 +187,15 @@ var Queue = class extends import_events.EventEmitter {
       const workPromise = Promise.resolve(this.handler(task.payload, task));
       const result = timeoutPromise ? await Promise.race([workPromise, timeoutPromise]) : await workPromise;
       this.emit("complete", { task, result });
+      this.settle();
     } catch (error) {
       if (task.attempts < this.options.maxRetries) {
         this.emit("retry", { task, error, attempt: task.attempts });
+        this._inFlight--;
         await this.redis.lPush("queue:tasks", JSON.stringify(task));
       } else {
         this.emit("failed", { task, error });
+        this.settle();
       }
     }
   }
@@ -189,6 +204,7 @@ var Queue = class extends import_events.EventEmitter {
     try {
       if (!this.handler) {
         this.emit("complete", { task, result: void 0 });
+        this.settle();
         return;
       }
       const timeoutPromise = this.options.groups.timeout > 0 ? new Promise(
@@ -197,18 +213,28 @@ var Queue = class extends import_events.EventEmitter {
       const workPromise = Promise.resolve(this.handler(task.payload, task));
       const result = timeoutPromise ? await Promise.race([workPromise, timeoutPromise]) : await workPromise;
       this.emit("complete", { task, result });
+      this.settle();
     } catch (error) {
       if (task.attempts < this.options.groups.maxRetries) {
         this.emit("retry", { task, error, attempt: task.attempts });
+        this._inFlight--;
         await this.redis.lPush(`queue:groups:${task.groupKey}`, JSON.stringify(task));
       } else {
         this.emit("failed", { task, error });
+        this.settle();
       }
     }
   }
+  settle() {
+    this._inFlight--;
+    this._totalSettled++;
+    if (this._inFlight === 0 && this._totalSettled > 0) {
+      this.emit("drain");
+    }
+  }
   async initializeRedis() {
     await this.redis.connect();
-    this.startWorkers();
+    await this.startWorkers();
     if (this.options.cleanupInterval > 0) {
       this.cleanupTimer = setInterval(() => {
         this.performPeriodicCleanup();
@@ -238,7 +264,10 @@ var Queue = class extends import_events.EventEmitter {
     } catch (error) {
     }
   }
+  /** shuts down all workers and disconnects from redis. waits for initialization to complete first. */
   async close() {
+    await this._ready.catch(() => {
+    });
     if (this.cleanupTimer) {
       clearInterval(this.cleanupTimer);
     }
@@ -247,6 +276,12 @@ var Queue = class extends import_events.EventEmitter {
       groupWorkers.clear();
     }
     this.groupWorkers.clear();
+    for (const client of this.workerClients) {
+      if (client.isOpen) {
+        await client.disconnect();
+      }
+    }
+    this.workerClients = [];
     if (this.redis.isOpen) {
       await this.redis.quit();
     }

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/queue.ts"],"sourcesContent":["export { default } from './queue.js'\nexport type { QueueOptions, Task, TaskHandler } from './queue.js'\n","import { createClient, RedisClientType } from 'redis'\nimport { EventEmitter } from 'events'\nimport { randomUUID } from 'crypto'\nimport ms from '@prsm/ms'\n\nexport interface QueueOptions<T = any> {\n  concurrency?: number\n  delay?: number | string\n  timeout?: number | string\n  maxRetries?: number\n  groups?: {\n    concurrency?: number\n    delay?: number | string\n    timeout?: number | string\n    maxRetries?: number\n  }\n  redisOptions?: {\n    url?: string\n    host?: string\n    port?: number\n    password?: string\n  }\n  cleanupInterval?: number\n}\n\nexport type TaskHandler<T, R = any> = (payload: T, task: Task<T>) => Promise<R> | R\n\nexport interface Task<T = any> {\n  uuid: string\n  payload: T\n  createdAt: number\n  groupKey?: string\n  attempts: number\n}\n\n\nexport default class Queue<T = any, R = any> extends EventEmitter {\n  private redis: RedisClientType\n  private options: {\n    concurrency: number\n    delay: number\n    timeout: number\n    maxRetries: number\n    groups: {\n      concurrency: number\n      delay: number\n      timeout: number\n      maxRetries: number\n    }\n    redisOptions: object\n    cleanupInterval: number\n  }\n  private handler?: TaskHandler<T, R>\n  private workers = new Map<string, boolean>()\n  private groupWorkers = new Map<string, Map<string, boolean>>()\n  private cleanupTimer?: NodeJS.Timeout\n\n  constructor(options: QueueOptions<T> = {}) {\n    super()\n\n    this.options = {\n      concurrency: options.concurrency ?? 1,\n      delay: ms(options.delay ?? 0),\n      timeout: ms(options.timeout ?? 0),\n      maxRetries: options.maxRetries ?? 3,\n      groups: {\n        concurrency: options.groups?.concurrency ?? options.concurrency ?? 1,\n        delay: ms(options.groups?.delay ?? options.delay ?? 0),\n        timeout: ms(options.groups?.timeout ?? options.timeout ?? 0),\n        maxRetries: options.groups?.maxRetries ?? options.maxRetries ?? 3\n      },\n      redisOptions: options.redisOptions ?? {},\n      cleanupInterval: options.cleanupInterval ?? 30000\n    }\n\n    this.redis = createClient(this.options.redisOptions)\n    this.redis.on('error', () => {})\n    this.initializeRedis()\n  }\n\n  process(handler: TaskHandler<T, R>) {\n    this.handler = handler\n  }\n\n  async push(payload: T): Promise<string> {\n    const task: Task<T> = {\n      uuid: randomUUID(),\n      payload,\n      createdAt: Date.now(),\n      attempts: 0\n    }\n\n    await this.redis.lPush('queue:tasks', JSON.stringify(task))\n    this.emit('new', { task })\n\n    return task.uuid\n  }\n\n  group(key: string) {\n    return {\n      push: async (payload: T): Promise<string> => {\n        const task: Task<T> = {\n          uuid: randomUUID(),\n          payload,\n          createdAt: Date.now(),\n          groupKey: key,\n          attempts: 0\n        }\n\n        await this.redis.lPush(`queue:groups:${key}`, JSON.stringify(task))\n        this.emit('new', { task })\n\n        if (!this.groupWorkers.has(key)) {\n          this.groupWorkers.set(key, new Map())\n          await this.startGroupWorkers(key)\n          await new Promise(resolve => setTimeout(resolve, 50))\n        }\n\n        return task.uuid\n      }\n    }\n  }\n\n  private async startWorkers() {\n    for (let i = 0; i < this.options.concurrency; i++) {\n      this.startWorker(`worker-${i}`)\n    }\n  }\n\n  private async startGroupWorkers(groupKey: string) {\n    const groupWorkers = this.groupWorkers.get(groupKey)!\n    for (let i = 0; i < this.options.groups.concurrency; i++) {\n      const workerId = `group-${groupKey}-worker-${i}`\n      groupWorkers.set(workerId, true)\n      this.startGroupWorker(workerId, groupKey)\n    }\n    // give workers more time to start and be ready\n    await new Promise(resolve => setTimeout(resolve, 100))\n  }\n\n  private async startWorker(workerId: string) {\n    this.workers.set(workerId, true)\n\n    while (this.workers.get(workerId)) {\n      try {\n        if (!this.redis.isOpen) {\n          break\n        }\n\n        const taskData = await this.redis.brPop('queue:tasks', 1)\n\n        if (taskData) {\n          const task: Task<T> = JSON.parse(taskData.element)\n          await this.processTask(task)\n        }\n\n        if (this.options.delay > 0) {\n          await new Promise(resolve => setTimeout(resolve, this.options.delay))\n        }\n      } catch (err) {\n        const error = err as Error\n        if (error.message?.includes('closed') || error.message?.includes('ClientClosedError')) {\n          break\n        }\n      }\n    }\n  }\n\n  private async startGroupWorker(workerId: string, groupKey: string) {\n    const groupWorkers = this.groupWorkers.get(groupKey)!\n\n    while (groupWorkers.get(workerId)) {\n      try {\n        if (!this.redis.isOpen) {\n          break\n        }\n\n        const taskData = await this.redis.brPop(`queue:groups:${groupKey}`, 1)\n\n        if (taskData) {\n          const task: Task<T> = JSON.parse(taskData.element)\n          await this.processGroupTask(task)\n        }\n\n        if (this.options.groups.delay > 0) {\n          await new Promise(resolve => setTimeout(resolve, this.options.groups.delay))\n        }\n      } catch (err) {\n        const error = err as Error\n        if (error.message?.includes('closed') || error.message?.includes('ClientClosedError')) {\n          break\n        }\n      }\n    }\n  }\n\n  private async processTask(task: Task<T>) {\n    task.attempts++\n\n    try {\n      if (!this.handler) {\n        this.emit('complete', { task, result: undefined })\n        return\n      }\n\n      const timeoutPromise = this.options.timeout > 0\n        ? new Promise<never>((_, reject) =>\n            setTimeout(() => reject(new Error('Task timeout')), this.options.timeout)\n          )\n        : null\n\n      const workPromise = Promise.resolve(this.handler(task.payload, task))\n\n      const result = timeoutPromise\n        ? await Promise.race([workPromise, timeoutPromise])\n        : await workPromise\n\n      this.emit('complete', { task, result })\n    } catch (error) {\n      if (task.attempts < this.options.maxRetries) {\n        this.emit('retry', { task, error, attempt: task.attempts })\n        await this.redis.lPush('queue:tasks', JSON.stringify(task))\n      } else {\n        this.emit('failed', { task, error })\n      }\n    }\n  }\n\n  private async processGroupTask(task: Task<T>) {\n    task.attempts++\n\n    try {\n      if (!this.handler) {\n        this.emit('complete', { task, result: undefined })\n        return\n      }\n\n      const timeoutPromise = this.options.groups.timeout > 0\n        ? new Promise<never>((_, reject) =>\n            setTimeout(() => reject(new Error('Task timeout')), this.options.groups.timeout)\n          )\n        : null\n\n      const workPromise = Promise.resolve(this.handler(task.payload, task))\n\n      const result = timeoutPromise\n        ? await Promise.race([workPromise, timeoutPromise])\n        : await workPromise\n\n      this.emit('complete', { task, result })\n    } catch (error) {\n      if (task.attempts < this.options.groups.maxRetries) {\n        this.emit('retry', { task, error, attempt: task.attempts })\n        await this.redis.lPush(`queue:groups:${task.groupKey}`, JSON.stringify(task))\n      } else {\n        this.emit('failed', { task, error })\n      }\n    }\n  }\n\n  private async initializeRedis() {\n    await this.redis.connect()\n    this.startWorkers()\n\n    // start periodic cleanup after redis is connected\n    if (this.options.cleanupInterval > 0) {\n      this.cleanupTimer = setInterval(() => {\n        this.performPeriodicCleanup()\n      }, this.options.cleanupInterval)\n    }\n  }\n\n  private async performPeriodicCleanup() {\n    try {\n      if (!this.redis.isOpen) {\n        return\n      }\n\n      const groupKeys = Array.from(this.groupWorkers.keys())\n\n      for (const groupKey of groupKeys) {\n        const length = await this.redis.lLen(`queue:groups:${groupKey}`)\n\n        if (length === 0) {\n          const keyExists = await this.redis.exists(`queue:groups:${groupKey}`)\n          if (keyExists) {\n            await this.redis.del(`queue:groups:${groupKey}`)\n          }\n\n          const groupWorkers = this.groupWorkers.get(groupKey)\n          if (groupWorkers) {\n            groupWorkers.clear()\n            this.groupWorkers.delete(groupKey)\n          }\n        }\n      }\n    } catch (error) {\n      // cleanup error handled silently\n    }\n  }\n\n  async close() {\n    if (this.cleanupTimer) {\n      clearInterval(this.cleanupTimer)\n    }\n    this.workers.clear()\n    for (const groupWorkers of this.groupWorkers.values()) {\n      groupWorkers.clear()\n    }\n    this.groupWorkers.clear()\n\n    if (this.redis.isOpen) {\n      await this.redis.quit()\n    }\n  }\n}\n"],"mappings":"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","names":["ms"]}
+{"version":3,"sources":["../src/index.ts","../src/queue.ts"],"sourcesContent":["export { default } from './queue.js'\nexport type { QueueOptions, Task, TaskHandler } from './queue.js'\n","import { createClient, RedisClientType } from 'redis'\nimport { EventEmitter } from 'events'\nimport { randomUUID } from 'crypto'\nimport ms from '@prsm/ms'\n\nexport interface QueueOptions<T = any> {\n  /** number of tasks to process in parallel. @default 1 */\n  concurrency?: number\n  /** wait time between finishing one task and picking up the next (ms or string like \"500ms\"). @default 0 */\n  delay?: number | string\n  /** max time a single task handler can run before it's killed with a \"Task timeout\" error (ms or string like \"30s\"). 0 = no limit. @default 0 */\n  timeout?: number | string\n  /** how many times to re-attempt a failed task before emitting \"failed\". @default 3 */\n  maxRetries?: number\n  /** overrides for grouped queues, falls back to top-level values */\n  groups?: {\n    concurrency?: number\n    delay?: number | string\n    timeout?: number | string\n    maxRetries?: number\n  }\n  redisOptions?: {\n    url?: string\n    host?: string\n    port?: number\n    password?: string\n  }\n  /** how often to clean up empty group keys in redis (ms). 0 = disabled. @default 30000 */\n  cleanupInterval?: number\n}\n\n/** called for each task, return value is passed to the \"complete\" event */\nexport type TaskHandler<T, R = any> = (payload: T, task: Task<T>) => Promise<R> | R\n\nexport interface Task<T = any> {\n  uuid: string\n  payload: T\n  createdAt: number\n  /** present when the task was pushed via queue.group(key).push() */\n  groupKey?: string\n  /** number of times this task has been attempted so far */\n  attempts: number\n}\n\n\nexport default class Queue<T = any, R = any> extends EventEmitter {\n  private redis: RedisClientType\n  private workerClients: RedisClientType[] = []\n  private options: {\n    concurrency: number\n    delay: number\n    timeout: number\n    maxRetries: number\n    groups: {\n      concurrency: number\n      delay: number\n      timeout: number\n      maxRetries: number\n    }\n    redisOptions: object\n    cleanupInterval: number\n  }\n  private handler?: TaskHandler<T, R>\n  private workers = new Map<string, boolean>()\n  private groupWorkers = new Map<string, Map<string, boolean>>()\n  private cleanupTimer?: NodeJS.Timeout\n  private _ready: Promise<void>\n  private _inFlight = 0\n  private _totalSettled = 0\n\n  constructor(options: QueueOptions<T> = {}) {\n    super()\n\n    this.options = {\n      concurrency: options.concurrency ?? 1,\n      delay: ms(options.delay ?? 0),\n      timeout: ms(options.timeout ?? 0),\n      maxRetries: options.maxRetries ?? 3,\n      groups: {\n        concurrency: options.groups?.concurrency ?? options.concurrency ?? 1,\n        delay: ms(options.groups?.delay ?? options.delay ?? 0),\n        timeout: ms(options.groups?.timeout ?? options.timeout ?? 0),\n        maxRetries: options.groups?.maxRetries ?? options.maxRetries ?? 3\n      },\n      redisOptions: options.redisOptions ?? {},\n      cleanupInterval: options.cleanupInterval ?? 30000\n    }\n\n    this.redis = createClient(this.options.redisOptions)\n    this.redis.on('error', () => {})\n    this._ready = this.initializeRedis()\n  }\n\n  /** resolves when redis is connected and all workers are ready to accept tasks */\n  ready() {\n    return this._ready\n  }\n\n  get inFlight() {\n    return this._inFlight\n  }\n\n  /** register the handler that processes each task. only one handler per queue. */\n  process(handler: TaskHandler<T, R>) {\n    this.handler = handler\n  }\n\n  /** push a task to the main queue. returns the task uuid. */\n  async push(payload: T): Promise<string> {\n    const task: Task<T> = {\n      uuid: randomUUID(),\n      payload,\n      createdAt: Date.now(),\n      attempts: 0\n    }\n\n    await this.redis.lPush('queue:tasks', JSON.stringify(task))\n    this.emit('new', { task })\n\n    return task.uuid\n  }\n\n  /** returns a scoped pusher for a named group. each group gets its own worker pool, spun up on first push. */\n  group(key: string) {\n    return {\n      push: async (payload: T): Promise<string> => {\n        const task: Task<T> = {\n          uuid: randomUUID(),\n          payload,\n          createdAt: Date.now(),\n          groupKey: key,\n          attempts: 0\n        }\n\n        await this.redis.lPush(`queue:groups:${key}`, JSON.stringify(task))\n        this.emit('new', { task })\n\n        if (!this.groupWorkers.has(key)) {\n          this.groupWorkers.set(key, new Map())\n          await this.startGroupWorkers(key)\n        }\n\n        return task.uuid\n      }\n    }\n  }\n\n  private async createWorkerClient(): Promise<RedisClientType> {\n    const client = this.redis.duplicate() as RedisClientType\n    client.on('error', () => {})\n    await client.connect()\n    this.workerClients.push(client)\n    return client\n  }\n\n  private async startWorkers() {\n    const ready = []\n    for (let i = 0; i < this.options.concurrency; i++) {\n      ready.push(this.startWorker(`worker-${i}`))\n    }\n    await Promise.all(ready)\n  }\n\n  private async startGroupWorkers(groupKey: string) {\n    const groupWorkers = this.groupWorkers.get(groupKey)!\n    const ready = []\n    for (let i = 0; i < this.options.groups.concurrency; i++) {\n      const workerId = `group-${groupKey}-worker-${i}`\n      groupWorkers.set(workerId, true)\n      ready.push(this.startGroupWorker(workerId, groupKey))\n    }\n    await Promise.all(ready)\n  }\n\n  private async startWorker(workerId: string) {\n    this.workers.set(workerId, true)\n    const client = await this.createWorkerClient()\n\n    this.runWorkerLoop(workerId, client, 'queue:tasks', this.workers, (task) => this.processTask(task))\n  }\n\n  private async startGroupWorker(workerId: string, groupKey: string) {\n    const groupWorkers = this.groupWorkers.get(groupKey)!\n    const client = await this.createWorkerClient()\n\n    this.runWorkerLoop(workerId, client, `queue:groups:${groupKey}`, groupWorkers, (task) => this.processGroupTask(task))\n  }\n\n  private async runWorkerLoop(\n    workerId: string,\n    client: RedisClientType,\n    key: string,\n    activeMap: Map<string, boolean>,\n    processFn: (task: Task<T>) => Promise<void>\n  ) {\n    const isGrouped = key.startsWith('queue:groups:')\n    const delay = isGrouped ? this.options.groups.delay : this.options.delay\n\n    while (activeMap.get(workerId)) {\n      try {\n        if (!client.isOpen) break\n\n        const taskData = await client.brPop(key, 1)\n\n        if (taskData) {\n          const task: Task<T> = JSON.parse(taskData.element)\n          this._inFlight++\n          await processFn(task)\n        }\n\n        if (delay > 0) {\n          await new Promise(resolve => setTimeout(resolve, delay))\n        }\n      } catch (err) {\n        const error = err as Error\n        if (error.message?.includes('closed') || error.message?.includes('ClientClosedError')) {\n          break\n        }\n      }\n    }\n  }\n\n  private async processTask(task: Task<T>) {\n    task.attempts++\n\n    try {\n      if (!this.handler) {\n        this.emit('complete', { task, result: undefined })\n        this.settle()\n        return\n      }\n\n      const timeoutPromise = this.options.timeout > 0\n        ? new Promise<never>((_, reject) =>\n            setTimeout(() => reject(new Error('Task timeout')), this.options.timeout)\n          )\n        : null\n\n      const workPromise = Promise.resolve(this.handler(task.payload, task))\n\n      const result = timeoutPromise\n        ? await Promise.race([workPromise, timeoutPromise])\n        : await workPromise\n\n      this.emit('complete', { task, result })\n      this.settle()\n    } catch (error) {\n      if (task.attempts < this.options.maxRetries) {\n        this.emit('retry', { task, error, attempt: task.attempts })\n        this._inFlight--\n        await this.redis.lPush('queue:tasks', JSON.stringify(task))\n      } else {\n        this.emit('failed', { task, error })\n        this.settle()\n      }\n    }\n  }\n\n  private async processGroupTask(task: Task<T>) {\n    task.attempts++\n\n    try {\n      if (!this.handler) {\n        this.emit('complete', { task, result: undefined })\n        this.settle()\n        return\n      }\n\n      const timeoutPromise = this.options.groups.timeout > 0\n        ? new Promise<never>((_, reject) =>\n            setTimeout(() => reject(new Error('Task timeout')), this.options.groups.timeout)\n          )\n        : null\n\n      const workPromise = Promise.resolve(this.handler(task.payload, task))\n\n      const result = timeoutPromise\n        ? await Promise.race([workPromise, timeoutPromise])\n        : await workPromise\n\n      this.emit('complete', { task, result })\n      this.settle()\n    } catch (error) {\n      if (task.attempts < this.options.groups.maxRetries) {\n        this.emit('retry', { task, error, attempt: task.attempts })\n        this._inFlight--\n        await this.redis.lPush(`queue:groups:${task.groupKey}`, JSON.stringify(task))\n      } else {\n        this.emit('failed', { task, error })\n        this.settle()\n      }\n    }\n  }\n\n  private settle() {\n    this._inFlight--\n    this._totalSettled++\n    if (this._inFlight === 0 && this._totalSettled > 0) {\n      this.emit('drain')\n    }\n  }\n\n  private async initializeRedis() {\n    await this.redis.connect()\n    await this.startWorkers()\n\n    if (this.options.cleanupInterval > 0) {\n      this.cleanupTimer = setInterval(() => {\n        this.performPeriodicCleanup()\n      }, this.options.cleanupInterval)\n    }\n  }\n\n  private async performPeriodicCleanup() {\n    try {\n      if (!this.redis.isOpen) {\n        return\n      }\n\n      const groupKeys = Array.from(this.groupWorkers.keys())\n\n      for (const groupKey of groupKeys) {\n        const length = await this.redis.lLen(`queue:groups:${groupKey}`)\n\n        if (length === 0) {\n          const keyExists = await this.redis.exists(`queue:groups:${groupKey}`)\n          if (keyExists) {\n            await this.redis.del(`queue:groups:${groupKey}`)\n          }\n\n          const groupWorkers = this.groupWorkers.get(groupKey)\n          if (groupWorkers) {\n            groupWorkers.clear()\n            this.groupWorkers.delete(groupKey)\n          }\n        }\n      }\n    } catch (error) {\n      // cleanup error handled silently\n    }\n  }\n\n  /** shuts down all workers and disconnects from redis. waits for initialization to complete first. */\n  async close() {\n    await this._ready.catch(() => {})\n\n    if (this.cleanupTimer) {\n      clearInterval(this.cleanupTimer)\n    }\n    this.workers.clear()\n    for (const groupWorkers of this.groupWorkers.values()) {\n      groupWorkers.clear()\n    }\n    this.groupWorkers.clear()\n\n    for (const client of this.workerClients) {\n      if (client.isOpen) {\n        await client.disconnect()\n      }\n    }\n    this.workerClients = []\n\n    if (this.redis.isOpen) {\n      await this.redis.quit()\n    }\n  }\n}\n"],"mappings":"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","names":["ms"]}

package/dist/index.d.cts

@@ -1,10 +1,15 @@
 import { EventEmitter } from 'events';
 
 interface QueueOptions<T = any> {
+    /** number of tasks to process in parallel. @default 1 */
     concurrency?: number;
+    /** wait time between finishing one task and picking up the next (ms or string like "500ms"). @default 0 */
     delay?: number | string;
+    /** max time a single task handler can run before it's killed with a "Task timeout" error (ms or string like "30s"). 0 = no limit. @default 0 */
     timeout?: number | string;
+    /** how many times to re-attempt a failed task before emitting "failed". @default 3 */
     maxRetries?: number;
+    /** overrides for grouped queues, falls back to top-level values */
     groups?: {
         concurrency?: number;
         delay?: number | string;
@@ -17,37 +22,55 @@ interface QueueOptions<T = any> {
         port?: number;
         password?: string;
     };
+    /** how often to clean up empty group keys in redis (ms). 0 = disabled. @default 30000 */
     cleanupInterval?: number;
 }
+/** called for each task, return value is passed to the "complete" event */
 type TaskHandler<T, R = any> = (payload: T, task: Task<T>) => Promise<R> | R;
 interface Task<T = any> {
     uuid: string;
     payload: T;
     createdAt: number;
+    /** present when the task was pushed via queue.group(key).push() */
     groupKey?: string;
+    /** number of times this task has been attempted so far */
     attempts: number;
 }
 declare class Queue<T = any, R = any> extends EventEmitter {
     private redis;
+    private workerClients;
     private options;
     private handler?;
     private workers;
     private groupWorkers;
     private cleanupTimer?;
+    private _ready;
+    private _inFlight;
+    private _totalSettled;
     constructor(options?: QueueOptions<T>);
+    /** resolves when redis is connected and all workers are ready to accept tasks */
+    ready(): Promise<void>;
+    get inFlight(): number;
+    /** register the handler that processes each task. only one handler per queue. */
     process(handler: TaskHandler<T, R>): void;
+    /** push a task to the main queue. returns the task uuid. */
     push(payload: T): Promise<string>;
+    /** returns a scoped pusher for a named group. each group gets its own worker pool, spun up on first push. */
     group(key: string): {
         push: (payload: T) => Promise<string>;
     };
+    private createWorkerClient;
     private startWorkers;
     private startGroupWorkers;
     private startWorker;
     private startGroupWorker;
+    private runWorkerLoop;
     private processTask;
     private processGroupTask;
+    private settle;
     private initializeRedis;
     private performPeriodicCleanup;
+    /** shuts down all workers and disconnects from redis. waits for initialization to complete first. */
     close(): Promise<void>;
 }
 

package/dist/index.d.ts

@@ -1,10 +1,15 @@
 import { EventEmitter } from 'events';
 
 interface QueueOptions<T = any> {
+    /** number of tasks to process in parallel. @default 1 */
     concurrency?: number;
+    /** wait time between finishing one task and picking up the next (ms or string like "500ms"). @default 0 */
     delay?: number | string;
+    /** max time a single task handler can run before it's killed with a "Task timeout" error (ms or string like "30s"). 0 = no limit. @default 0 */
     timeout?: number | string;
+    /** how many times to re-attempt a failed task before emitting "failed". @default 3 */
     maxRetries?: number;
+    /** overrides for grouped queues, falls back to top-level values */
     groups?: {
         concurrency?: number;
         delay?: number | string;
@@ -17,37 +22,55 @@ interface QueueOptions<T = any> {
         port?: number;
         password?: string;
     };
+    /** how often to clean up empty group keys in redis (ms). 0 = disabled. @default 30000 */
     cleanupInterval?: number;
 }
+/** called for each task, return value is passed to the "complete" event */
 type TaskHandler<T, R = any> = (payload: T, task: Task<T>) => Promise<R> | R;
 interface Task<T = any> {
     uuid: string;
     payload: T;
     createdAt: number;
+    /** present when the task was pushed via queue.group(key).push() */
     groupKey?: string;
+    /** number of times this task has been attempted so far */
     attempts: number;
 }
 declare class Queue<T = any, R = any> extends EventEmitter {
     private redis;
+    private workerClients;
     private options;
     private handler?;
     private workers;
     private groupWorkers;
     private cleanupTimer?;
+    private _ready;
+    private _inFlight;
+    private _totalSettled;
     constructor(options?: QueueOptions<T>);
+    /** resolves when redis is connected and all workers are ready to accept tasks */
+    ready(): Promise<void>;
+    get inFlight(): number;
+    /** register the handler that processes each task. only one handler per queue. */
     process(handler: TaskHandler<T, R>): void;
+    /** push a task to the main queue. returns the task uuid. */
     push(payload: T): Promise<string>;
+    /** returns a scoped pusher for a named group. each group gets its own worker pool, spun up on first push. */
     group(key: string): {
         push: (payload: T) => Promise<string>;
     };
+    private createWorkerClient;
     private startWorkers;
     private startGroupWorkers;
     private startWorker;
     private startGroupWorker;
+    private runWorkerLoop;
     private processTask;
     private processGroupTask;
+    private settle;
     private initializeRedis;
     private performPeriodicCleanup;
+    /** shuts down all workers and disconnects from redis. waits for initialization to complete first. */
     close(): Promise<void>;
 }
 

package/dist/index.js

@@ -5,11 +5,15 @@ import { randomUUID } from "crypto";
 import ms from "@prsm/ms";
 var Queue = class extends EventEmitter {
   redis;
+  workerClients = [];
   options;
   handler;
   workers = /* @__PURE__ */ new Map();
   groupWorkers = /* @__PURE__ */ new Map();
   cleanupTimer;
+  _ready;
+  _inFlight = 0;
+  _totalSettled = 0;
   constructor(options = {}) {
     super();
     this.options = {
@@ -29,11 +33,20 @@ var Queue = class extends EventEmitter {
     this.redis = createClient(this.options.redisOptions);
     this.redis.on("error", () => {
     });
-    this.initializeRedis();
+    this._ready = this.initializeRedis();
   }
+  /** resolves when redis is connected and all workers are ready to accept tasks */
+  ready() {
+    return this._ready;
+  }
+  get inFlight() {
+    return this._inFlight;
+  }
+  /** register the handler that processes each task. only one handler per queue. */
   process(handler) {
     this.handler = handler;
   }
+  /** push a task to the main queue. returns the task uuid. */
   async push(payload) {
     const task = {
       uuid: randomUUID(),
@@ -45,6 +58,7 @@ var Queue = class extends EventEmitter {
     this.emit("new", { task });
     return task.uuid;
   }
+  /** returns a scoped pusher for a named group. each group gets its own worker pool, spun up on first push. */
   group(key) {
     return {
       push: async (payload) => {
@@ -60,63 +74,60 @@ var Queue = class extends EventEmitter {
         if (!this.groupWorkers.has(key)) {
           this.groupWorkers.set(key, /* @__PURE__ */ new Map());
           await this.startGroupWorkers(key);
-          await new Promise((resolve) => setTimeout(resolve, 50));
         }
         return task.uuid;
       }
     };
   }
+  async createWorkerClient() {
+    const client = this.redis.duplicate();
+    client.on("error", () => {
+    });
+    await client.connect();
+    this.workerClients.push(client);
+    return client;
+  }
   async startWorkers() {
+    const ready = [];
     for (let i = 0; i < this.options.concurrency; i++) {
-      this.startWorker(`worker-${i}`);
+      ready.push(this.startWorker(`worker-${i}`));
     }
+    await Promise.all(ready);
   }
   async startGroupWorkers(groupKey) {
     const groupWorkers = this.groupWorkers.get(groupKey);
+    const ready = [];
     for (let i = 0; i < this.options.groups.concurrency; i++) {
       const workerId = `group-${groupKey}-worker-${i}`;
       groupWorkers.set(workerId, true);
-      this.startGroupWorker(workerId, groupKey);
+      ready.push(this.startGroupWorker(workerId, groupKey));
     }
-    await new Promise((resolve) => setTimeout(resolve, 100));
+    await Promise.all(ready);
   }
   async startWorker(workerId) {
     this.workers.set(workerId, true);
-    while (this.workers.get(workerId)) {
-      try {
-        if (!this.redis.isOpen) {
-          break;
-        }
-        const taskData = await this.redis.brPop("queue:tasks", 1);
-        if (taskData) {
-          const task = JSON.parse(taskData.element);
-          await this.processTask(task);
-        }
-        if (this.options.delay > 0) {
-          await new Promise((resolve) => setTimeout(resolve, this.options.delay));
-        }
-      } catch (err) {
-        const error = err;
-        if (error.message?.includes("closed") || error.message?.includes("ClientClosedError")) {
-          break;
-        }
-      }
-    }
+    const client = await this.createWorkerClient();
+    this.runWorkerLoop(workerId, client, "queue:tasks", this.workers, (task) => this.processTask(task));
   }
   async startGroupWorker(workerId, groupKey) {
     const groupWorkers = this.groupWorkers.get(groupKey);
-    while (groupWorkers.get(workerId)) {
+    const client = await this.createWorkerClient();
+    this.runWorkerLoop(workerId, client, `queue:groups:${groupKey}`, groupWorkers, (task) => this.processGroupTask(task));
+  }
+  async runWorkerLoop(workerId, client, key, activeMap, processFn) {
+    const isGrouped = key.startsWith("queue:groups:");
+    const delay = isGrouped ? this.options.groups.delay : this.options.delay;
+    while (activeMap.get(workerId)) {
       try {
-        if (!this.redis.isOpen) {
-          break;
-        }
-        const taskData = await this.redis.brPop(`queue:groups:${groupKey}`, 1);
+        if (!client.isOpen) break;
+        const taskData = await client.brPop(key, 1);
         if (taskData) {
           const task = JSON.parse(taskData.element);
-          await this.processGroupTask(task);
+          this._inFlight++;
+          await processFn(task);
         }
-        if (this.options.groups.delay > 0) {
-          await new Promise((resolve) => setTimeout(resolve, this.options.groups.delay));
+        if (delay > 0) {
+          await new Promise((resolve) => setTimeout(resolve, delay));
         }
       } catch (err) {
         const error = err;
@@ -131,6 +142,7 @@ var Queue = class extends EventEmitter {
     try {
       if (!this.handler) {
         this.emit("complete", { task, result: void 0 });
+        this.settle();
         return;
       }
       const timeoutPromise = this.options.timeout > 0 ? new Promise(
@@ -139,12 +151,15 @@ var Queue = class extends EventEmitter {
       const workPromise = Promise.resolve(this.handler(task.payload, task));
       const result = timeoutPromise ? await Promise.race([workPromise, timeoutPromise]) : await workPromise;
       this.emit("complete", { task, result });
+      this.settle();
     } catch (error) {
       if (task.attempts < this.options.maxRetries) {
         this.emit("retry", { task, error, attempt: task.attempts });
+        this._inFlight--;
         await this.redis.lPush("queue:tasks", JSON.stringify(task));
       } else {
         this.emit("failed", { task, error });
+        this.settle();
       }
     }
   }
@@ -153,6 +168,7 @@ var Queue = class extends EventEmitter {
     try {
       if (!this.handler) {
         this.emit("complete", { task, result: void 0 });
+        this.settle();
         return;
       }
       const timeoutPromise = this.options.groups.timeout > 0 ? new Promise(
@@ -161,18 +177,28 @@ var Queue = class extends EventEmitter {
       const workPromise = Promise.resolve(this.handler(task.payload, task));
       const result = timeoutPromise ? await Promise.race([workPromise, timeoutPromise]) : await workPromise;
       this.emit("complete", { task, result });
+      this.settle();
     } catch (error) {
       if (task.attempts < this.options.groups.maxRetries) {
         this.emit("retry", { task, error, attempt: task.attempts });
+        this._inFlight--;
         await this.redis.lPush(`queue:groups:${task.groupKey}`, JSON.stringify(task));
       } else {
         this.emit("failed", { task, error });
+        this.settle();
       }
     }
   }
+  settle() {
+    this._inFlight--;
+    this._totalSettled++;
+    if (this._inFlight === 0 && this._totalSettled > 0) {
+      this.emit("drain");
+    }
+  }
   async initializeRedis() {
     await this.redis.connect();
-    this.startWorkers();
+    await this.startWorkers();
     if (this.options.cleanupInterval > 0) {
       this.cleanupTimer = setInterval(() => {
         this.performPeriodicCleanup();
@@ -202,7 +228,10 @@ var Queue = class extends EventEmitter {
     } catch (error) {
     }
   }
+  /** shuts down all workers and disconnects from redis. waits for initialization to complete first. */
   async close() {
+    await this._ready.catch(() => {
+    });
     if (this.cleanupTimer) {
       clearInterval(this.cleanupTimer);
     }
@@ -211,6 +240,12 @@ var Queue = class extends EventEmitter {
       groupWorkers.clear();
     }
     this.groupWorkers.clear();
+    for (const client of this.workerClients) {
+      if (client.isOpen) {
+        await client.disconnect();
+      }
+    }
+    this.workerClients = [];
     if (this.redis.isOpen) {
       await this.redis.quit();
     }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/queue.ts"],"sourcesContent":["import { createClient, RedisClientType } from 'redis'\nimport { EventEmitter } from 'events'\nimport { randomUUID } from 'crypto'\nimport ms from '@prsm/ms'\n\nexport interface QueueOptions<T = any> {\n  concurrency?: number\n  delay?: number | string\n  timeout?: number | string\n  maxRetries?: number\n  groups?: {\n    concurrency?: number\n    delay?: number | string\n    timeout?: number | string\n    maxRetries?: number\n  }\n  redisOptions?: {\n    url?: string\n    host?: string\n    port?: number\n    password?: string\n  }\n  cleanupInterval?: number\n}\n\nexport type TaskHandler<T, R = any> = (payload: T, task: Task<T>) => Promise<R> | R\n\nexport interface Task<T = any> {\n  uuid: string\n  payload: T\n  createdAt: number\n  groupKey?: string\n  attempts: number\n}\n\n\nexport default class Queue<T = any, R = any> extends EventEmitter {\n  private redis: RedisClientType\n  private options: {\n    concurrency: number\n    delay: number\n    timeout: number\n    maxRetries: number\n    groups: {\n      concurrency: number\n      delay: number\n      timeout: number\n      maxRetries: number\n    }\n    redisOptions: object\n    cleanupInterval: number\n  }\n  private handler?: TaskHandler<T, R>\n  private workers = new Map<string, boolean>()\n  private groupWorkers = new Map<string, Map<string, boolean>>()\n  private cleanupTimer?: NodeJS.Timeout\n\n  constructor(options: QueueOptions<T> = {}) {\n    super()\n\n    this.options = {\n      concurrency: options.concurrency ?? 1,\n      delay: ms(options.delay ?? 0),\n      timeout: ms(options.timeout ?? 0),\n      maxRetries: options.maxRetries ?? 3,\n      groups: {\n        concurrency: options.groups?.concurrency ?? options.concurrency ?? 1,\n        delay: ms(options.groups?.delay ?? options.delay ?? 0),\n        timeout: ms(options.groups?.timeout ?? options.timeout ?? 0),\n        maxRetries: options.groups?.maxRetries ?? options.maxRetries ?? 3\n      },\n      redisOptions: options.redisOptions ?? {},\n      cleanupInterval: options.cleanupInterval ?? 30000\n    }\n\n    this.redis = createClient(this.options.redisOptions)\n    this.redis.on('error', () => {})\n    this.initializeRedis()\n  }\n\n  process(handler: TaskHandler<T, R>) {\n    this.handler = handler\n  }\n\n  async push(payload: T): Promise<string> {\n    const task: Task<T> = {\n      uuid: randomUUID(),\n      payload,\n      createdAt: Date.now(),\n      attempts: 0\n    }\n\n    await this.redis.lPush('queue:tasks', JSON.stringify(task))\n    this.emit('new', { task })\n\n    return task.uuid\n  }\n\n  group(key: string) {\n    return {\n      push: async (payload: T): Promise<string> => {\n        const task: Task<T> = {\n          uuid: randomUUID(),\n          payload,\n          createdAt: Date.now(),\n          groupKey: key,\n          attempts: 0\n        }\n\n        await this.redis.lPush(`queue:groups:${key}`, JSON.stringify(task))\n        this.emit('new', { task })\n\n        if (!this.groupWorkers.has(key)) {\n          this.groupWorkers.set(key, new Map())\n          await this.startGroupWorkers(key)\n          await new Promise(resolve => setTimeout(resolve, 50))\n        }\n\n        return task.uuid\n      }\n    }\n  }\n\n  private async startWorkers() {\n    for (let i = 0; i < this.options.concurrency; i++) {\n      this.startWorker(`worker-${i}`)\n    }\n  }\n\n  private async startGroupWorkers(groupKey: string) {\n    const groupWorkers = this.groupWorkers.get(groupKey)!\n    for (let i = 0; i < this.options.groups.concurrency; i++) {\n      const workerId = `group-${groupKey}-worker-${i}`\n      groupWorkers.set(workerId, true)\n      this.startGroupWorker(workerId, groupKey)\n    }\n    // give workers more time to start and be ready\n    await new Promise(resolve => setTimeout(resolve, 100))\n  }\n\n  private async startWorker(workerId: string) {\n    this.workers.set(workerId, true)\n\n    while (this.workers.get(workerId)) {\n      try {\n        if (!this.redis.isOpen) {\n          break\n        }\n\n        const taskData = await this.redis.brPop('queue:tasks', 1)\n\n        if (taskData) {\n          const task: Task<T> = JSON.parse(taskData.element)\n          await this.processTask(task)\n        }\n\n        if (this.options.delay > 0) {\n          await new Promise(resolve => setTimeout(resolve, this.options.delay))\n        }\n      } catch (err) {\n        const error = err as Error\n        if (error.message?.includes('closed') || error.message?.includes('ClientClosedError')) {\n          break\n        }\n      }\n    }\n  }\n\n  private async startGroupWorker(workerId: string, groupKey: string) {\n    const groupWorkers = this.groupWorkers.get(groupKey)!\n\n    while (groupWorkers.get(workerId)) {\n      try {\n        if (!this.redis.isOpen) {\n          break\n        }\n\n        const taskData = await this.redis.brPop(`queue:groups:${groupKey}`, 1)\n\n        if (taskData) {\n          const task: Task<T> = JSON.parse(taskData.element)\n          await this.processGroupTask(task)\n        }\n\n        if (this.options.groups.delay > 0) {\n          await new Promise(resolve => setTimeout(resolve, this.options.groups.delay))\n        }\n      } catch (err) {\n        const error = err as Error\n        if (error.message?.includes('closed') || error.message?.includes('ClientClosedError')) {\n          break\n        }\n      }\n    }\n  }\n\n  private async processTask(task: Task<T>) {\n    task.attempts++\n\n    try {\n      if (!this.handler) {\n        this.emit('complete', { task, result: undefined })\n        return\n      }\n\n      const timeoutPromise = this.options.timeout > 0\n        ? new Promise<never>((_, reject) =>\n            setTimeout(() => reject(new Error('Task timeout')), this.options.timeout)\n          )\n        : null\n\n      const workPromise = Promise.resolve(this.handler(task.payload, task))\n\n      const result = timeoutPromise\n        ? await Promise.race([workPromise, timeoutPromise])\n        : await workPromise\n\n      this.emit('complete', { task, result })\n    } catch (error) {\n      if (task.attempts < this.options.maxRetries) {\n        this.emit('retry', { task, error, attempt: task.attempts })\n        await this.redis.lPush('queue:tasks', JSON.stringify(task))\n      } else {\n        this.emit('failed', { task, error })\n      }\n    }\n  }\n\n  private async processGroupTask(task: Task<T>) {\n    task.attempts++\n\n    try {\n      if (!this.handler) {\n        this.emit('complete', { task, result: undefined })\n        return\n      }\n\n      const timeoutPromise = this.options.groups.timeout > 0\n        ? new Promise<never>((_, reject) =>\n            setTimeout(() => reject(new Error('Task timeout')), this.options.groups.timeout)\n          )\n        : null\n\n      const workPromise = Promise.resolve(this.handler(task.payload, task))\n\n      const result = timeoutPromise\n        ? await Promise.race([workPromise, timeoutPromise])\n        : await workPromise\n\n      this.emit('complete', { task, result })\n    } catch (error) {\n      if (task.attempts < this.options.groups.maxRetries) {\n        this.emit('retry', { task, error, attempt: task.attempts })\n        await this.redis.lPush(`queue:groups:${task.groupKey}`, JSON.stringify(task))\n      } else {\n        this.emit('failed', { task, error })\n      }\n    }\n  }\n\n  private async initializeRedis() {\n    await this.redis.connect()\n    this.startWorkers()\n\n    // start periodic cleanup after redis is connected\n    if (this.options.cleanupInterval > 0) {\n      this.cleanupTimer = setInterval(() => {\n        this.performPeriodicCleanup()\n      }, this.options.cleanupInterval)\n    }\n  }\n\n  private async performPeriodicCleanup() {\n    try {\n      if (!this.redis.isOpen) {\n        return\n      }\n\n      const groupKeys = Array.from(this.groupWorkers.keys())\n\n      for (const groupKey of groupKeys) {\n        const length = await this.redis.lLen(`queue:groups:${groupKey}`)\n\n        if (length === 0) {\n          const keyExists = await this.redis.exists(`queue:groups:${groupKey}`)\n          if (keyExists) {\n            await this.redis.del(`queue:groups:${groupKey}`)\n          }\n\n          const groupWorkers = this.groupWorkers.get(groupKey)\n          if (groupWorkers) {\n            groupWorkers.clear()\n            this.groupWorkers.delete(groupKey)\n          }\n        }\n      }\n    } catch (error) {\n      // cleanup error handled silently\n    }\n  }\n\n  async close() {\n    if (this.cleanupTimer) {\n      clearInterval(this.cleanupTimer)\n    }\n    this.workers.clear()\n    for (const groupWorkers of this.groupWorkers.values()) {\n      groupWorkers.clear()\n    }\n    this.groupWorkers.clear()\n\n    if (this.redis.isOpen) {\n      await this.redis.quit()\n    }\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/queue.ts"],"sourcesContent":["import { createClient, RedisClientType } from 'redis'\nimport { EventEmitter } from 'events'\nimport { randomUUID } from 'crypto'\nimport ms from '@prsm/ms'\n\nexport interface QueueOptions<T = any> {\n  /** number of tasks to process in parallel. @default 1 */\n  concurrency?: number\n  /** wait time between finishing one task and picking up the next (ms or string like \"500ms\"). @default 0 */\n  delay?: number | string\n  /** max time a single task handler can run before it's killed with a \"Task timeout\" error (ms or string like \"30s\"). 0 = no limit. @default 0 */\n  timeout?: number | string\n  /** how many times to re-attempt a failed task before emitting \"failed\". @default 3 */\n  maxRetries?: number\n  /** overrides for grouped queues, falls back to top-level values */\n  groups?: {\n    concurrency?: number\n    delay?: number | string\n    timeout?: number | string\n    maxRetries?: number\n  }\n  redisOptions?: {\n    url?: string\n    host?: string\n    port?: number\n    password?: string\n  }\n  /** how often to clean up empty group keys in redis (ms). 0 = disabled. @default 30000 */\n  cleanupInterval?: number\n}\n\n/** called for each task, return value is passed to the \"complete\" event */\nexport type TaskHandler<T, R = any> = (payload: T, task: Task<T>) => Promise<R> | R\n\nexport interface Task<T = any> {\n  uuid: string\n  payload: T\n  createdAt: number\n  /** present when the task was pushed via queue.group(key).push() */\n  groupKey?: string\n  /** number of times this task has been attempted so far */\n  attempts: number\n}\n\n\nexport default class Queue<T = any, R = any> extends EventEmitter {\n  private redis: RedisClientType\n  private workerClients: RedisClientType[] = []\n  private options: {\n    concurrency: number\n    delay: number\n    timeout: number\n    maxRetries: number\n    groups: {\n      concurrency: number\n      delay: number\n      timeout: number\n      maxRetries: number\n    }\n    redisOptions: object\n    cleanupInterval: number\n  }\n  private handler?: TaskHandler<T, R>\n  private workers = new Map<string, boolean>()\n  private groupWorkers = new Map<string, Map<string, boolean>>()\n  private cleanupTimer?: NodeJS.Timeout\n  private _ready: Promise<void>\n  private _inFlight = 0\n  private _totalSettled = 0\n\n  constructor(options: QueueOptions<T> = {}) {\n    super()\n\n    this.options = {\n      concurrency: options.concurrency ?? 1,\n      delay: ms(options.delay ?? 0),\n      timeout: ms(options.timeout ?? 0),\n      maxRetries: options.maxRetries ?? 3,\n      groups: {\n        concurrency: options.groups?.concurrency ?? options.concurrency ?? 1,\n        delay: ms(options.groups?.delay ?? options.delay ?? 0),\n        timeout: ms(options.groups?.timeout ?? options.timeout ?? 0),\n        maxRetries: options.groups?.maxRetries ?? options.maxRetries ?? 3\n      },\n      redisOptions: options.redisOptions ?? {},\n      cleanupInterval: options.cleanupInterval ?? 30000\n    }\n\n    this.redis = createClient(this.options.redisOptions)\n    this.redis.on('error', () => {})\n    this._ready = this.initializeRedis()\n  }\n\n  /** resolves when redis is connected and all workers are ready to accept tasks */\n  ready() {\n    return this._ready\n  }\n\n  get inFlight() {\n    return this._inFlight\n  }\n\n  /** register the handler that processes each task. only one handler per queue. */\n  process(handler: TaskHandler<T, R>) {\n    this.handler = handler\n  }\n\n  /** push a task to the main queue. returns the task uuid. */\n  async push(payload: T): Promise<string> {\n    const task: Task<T> = {\n      uuid: randomUUID(),\n      payload,\n      createdAt: Date.now(),\n      attempts: 0\n    }\n\n    await this.redis.lPush('queue:tasks', JSON.stringify(task))\n    this.emit('new', { task })\n\n    return task.uuid\n  }\n\n  /** returns a scoped pusher for a named group. each group gets its own worker pool, spun up on first push. */\n  group(key: string) {\n    return {\n      push: async (payload: T): Promise<string> => {\n        const task: Task<T> = {\n          uuid: randomUUID(),\n          payload,\n          createdAt: Date.now(),\n          groupKey: key,\n          attempts: 0\n        }\n\n        await this.redis.lPush(`queue:groups:${key}`, JSON.stringify(task))\n        this.emit('new', { task })\n\n        if (!this.groupWorkers.has(key)) {\n          this.groupWorkers.set(key, new Map())\n          await this.startGroupWorkers(key)\n        }\n\n        return task.uuid\n      }\n    }\n  }\n\n  private async createWorkerClient(): Promise<RedisClientType> {\n    const client = this.redis.duplicate() as RedisClientType\n    client.on('error', () => {})\n    await client.connect()\n    this.workerClients.push(client)\n    return client\n  }\n\n  private async startWorkers() {\n    const ready = []\n    for (let i = 0; i < this.options.concurrency; i++) {\n      ready.push(this.startWorker(`worker-${i}`))\n    }\n    await Promise.all(ready)\n  }\n\n  private async startGroupWorkers(groupKey: string) {\n    const groupWorkers = this.groupWorkers.get(groupKey)!\n    const ready = []\n    for (let i = 0; i < this.options.groups.concurrency; i++) {\n      const workerId = `group-${groupKey}-worker-${i}`\n      groupWorkers.set(workerId, true)\n      ready.push(this.startGroupWorker(workerId, groupKey))\n    }\n    await Promise.all(ready)\n  }\n\n  private async startWorker(workerId: string) {\n    this.workers.set(workerId, true)\n    const client = await this.createWorkerClient()\n\n    this.runWorkerLoop(workerId, client, 'queue:tasks', this.workers, (task) => this.processTask(task))\n  }\n\n  private async startGroupWorker(workerId: string, groupKey: string) {\n    const groupWorkers = this.groupWorkers.get(groupKey)!\n    const client = await this.createWorkerClient()\n\n    this.runWorkerLoop(workerId, client, `queue:groups:${groupKey}`, groupWorkers, (task) => this.processGroupTask(task))\n  }\n\n  private async runWorkerLoop(\n    workerId: string,\n    client: RedisClientType,\n    key: string,\n    activeMap: Map<string, boolean>,\n    processFn: (task: Task<T>) => Promise<void>\n  ) {\n    const isGrouped = key.startsWith('queue:groups:')\n    const delay = isGrouped ? this.options.groups.delay : this.options.delay\n\n    while (activeMap.get(workerId)) {\n      try {\n        if (!client.isOpen) break\n\n        const taskData = await client.brPop(key, 1)\n\n        if (taskData) {\n          const task: Task<T> = JSON.parse(taskData.element)\n          this._inFlight++\n          await processFn(task)\n        }\n\n        if (delay > 0) {\n          await new Promise(resolve => setTimeout(resolve, delay))\n        }\n      } catch (err) {\n        const error = err as Error\n        if (error.message?.includes('closed') || error.message?.includes('ClientClosedError')) {\n          break\n        }\n      }\n    }\n  }\n\n  private async processTask(task: Task<T>) {\n    task.attempts++\n\n    try {\n      if (!this.handler) {\n        this.emit('complete', { task, result: undefined })\n        this.settle()\n        return\n      }\n\n      const timeoutPromise = this.options.timeout > 0\n        ? new Promise<never>((_, reject) =>\n            setTimeout(() => reject(new Error('Task timeout')), this.options.timeout)\n          )\n        : null\n\n      const workPromise = Promise.resolve(this.handler(task.payload, task))\n\n      const result = timeoutPromise\n        ? await Promise.race([workPromise, timeoutPromise])\n        : await workPromise\n\n      this.emit('complete', { task, result })\n      this.settle()\n    } catch (error) {\n      if (task.attempts < this.options.maxRetries) {\n        this.emit('retry', { task, error, attempt: task.attempts })\n        this._inFlight--\n        await this.redis.lPush('queue:tasks', JSON.stringify(task))\n      } else {\n        this.emit('failed', { task, error })\n        this.settle()\n      }\n    }\n  }\n\n  private async processGroupTask(task: Task<T>) {\n    task.attempts++\n\n    try {\n      if (!this.handler) {\n        this.emit('complete', { task, result: undefined })\n        this.settle()\n        return\n      }\n\n      const timeoutPromise = this.options.groups.timeout > 0\n        ? new Promise<never>((_, reject) =>\n            setTimeout(() => reject(new Error('Task timeout')), this.options.groups.timeout)\n          )\n        : null\n\n      const workPromise = Promise.resolve(this.handler(task.payload, task))\n\n      const result = timeoutPromise\n        ? await Promise.race([workPromise, timeoutPromise])\n        : await workPromise\n\n      this.emit('complete', { task, result })\n      this.settle()\n    } catch (error) {\n      if (task.attempts < this.options.groups.maxRetries) {\n        this.emit('retry', { task, error, attempt: task.attempts })\n        this._inFlight--\n        await this.redis.lPush(`queue:groups:${task.groupKey}`, JSON.stringify(task))\n      } else {\n        this.emit('failed', { task, error })\n        this.settle()\n      }\n    }\n  }\n\n  private settle() {\n    this._inFlight--\n    this._totalSettled++\n    if (this._inFlight === 0 && this._totalSettled > 0) {\n      this.emit('drain')\n    }\n  }\n\n  private async initializeRedis() {\n    await this.redis.connect()\n    await this.startWorkers()\n\n    if (this.options.cleanupInterval > 0) {\n      this.cleanupTimer = setInterval(() => {\n        this.performPeriodicCleanup()\n      }, this.options.cleanupInterval)\n    }\n  }\n\n  private async performPeriodicCleanup() {\n    try {\n      if (!this.redis.isOpen) {\n        return\n      }\n\n      const groupKeys = Array.from(this.groupWorkers.keys())\n\n      for (const groupKey of groupKeys) {\n        const length = await this.redis.lLen(`queue:groups:${groupKey}`)\n\n        if (length === 0) {\n          const keyExists = await this.redis.exists(`queue:groups:${groupKey}`)\n          if (keyExists) {\n            await this.redis.del(`queue:groups:${groupKey}`)\n          }\n\n          const groupWorkers = this.groupWorkers.get(groupKey)\n          if (groupWorkers) {\n            groupWorkers.clear()\n            this.groupWorkers.delete(groupKey)\n          }\n        }\n      }\n    } catch (error) {\n      // cleanup error handled silently\n    }\n  }\n\n  /** shuts down all workers and disconnects from redis. waits for initialization to complete first. */\n  async close() {\n    await this._ready.catch(() => {})\n\n    if (this.cleanupTimer) {\n      clearInterval(this.cleanupTimer)\n    }\n    this.workers.clear()\n    for (const groupWorkers of this.groupWorkers.values()) {\n      groupWorkers.clear()\n    }\n    this.groupWorkers.clear()\n\n    for (const client of this.workerClients) {\n      if (client.isOpen) {\n        await client.disconnect()\n      }\n    }\n    this.workerClients = []\n\n    if (this.redis.isOpen) {\n      await this.redis.quit()\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prsm/queue",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Redis-backed distributed task queue with grouped concurrency, retries, and rate limiting",
   "type": "module",
   "main": "./dist/index.cjs",