@prsm/queue 1.0.2 → 2.1.0

package/README.md

@@ -1,4 +1,8 @@
-# @prsm/queue
+<p align="center">
+  <img src=".github/logo.svg" width="80" height="80" alt="queue logo">
+</p>
+
+<h1 align="center">@prsm/queue</h1>
 
 Redis-backed distributed task queue with grouped concurrency, retries, and rate limiting.
 
@@ -10,7 +14,7 @@ npm install @prsm/queue
 
 ## Quick Start
 
-```ts
+```js
 import Queue from '@prsm/queue'
 
 const queue = new Queue({
@@ -30,20 +34,22 @@ queue.on('failed', ({ task, error }) => {
   console.log('Failed after retries:', task.uuid, error.message)
 })
 
+await queue.ready()
 await queue.push({ userId: 123, action: 'sync' })
 ```
 
 ## Options
 
-```ts
+```js
 const queue = new Queue({
-  concurrency: 2,           // worker count
+  concurrency: 2,           // max concurrent tasks per instance
+  globalConcurrency: 10,    // max concurrent tasks across all instances (Redis-backed)
   delay: '100ms',           // pause between tasks (string or ms)
   timeout: '30s',           // max task duration
   maxRetries: 3,            // attempts before failing
 
   groups: {
-    concurrency: 1,         // workers per group
+    concurrency: 1,         // max concurrent tasks per group
     delay: '50ms',
     timeout: '10s',
     maxRetries: 3
@@ -56,9 +62,44 @@ const queue = new Queue({
 })
 ```
 
+## Concurrency
+
+Three independent limits compose together. A task must pass all applicable gates before processing.
+
+**`concurrency`** - per-instance limit. Controls how many tasks this server can process simultaneously. This is the number of worker loops created for the main queue, and also caps total active tasks (including grouped) on this instance via an in-memory semaphore. Default: `1`.
+
+**`globalConcurrency`** - cross-instance limit. Controls how many tasks can run across all servers sharing the same Redis. Uses a Redis-backed semaphore with automatic lease expiry for crash safety. If an instance crashes, its slots are reclaimed after 60 seconds. Default: `0` (disabled).
+
+**`groups.concurrency`** - per-group limit. Controls how many tasks can run concurrently within a single group. Default: `1`.
+
+### Examples
+
+Protect local resources (CPU/memory bound):
+
+```js
+const queue = new Queue({
+  concurrency: 5,
+  groups: { concurrency: 1 }
+})
+```
+
+100 groups each with 1 task - only 5 run at a time on this server.
+
+Protect an external API (shared rate across servers):
+
+```js
+const queue = new Queue({
+  concurrency: 10,
+  globalConcurrency: 20,
+  groups: { concurrency: 2 }
+})
+```
+
+3 servers, each can handle 10 concurrent tasks, but only 20 total across all servers. Each group (tenant) gets up to 2 concurrent slots.
+
 ## Process Handler
 
-```ts
+```js
 queue.process(async (payload, task) => {
   console.log('Task:', task.uuid, 'Attempt:', task.attempts)
   return await someWork(payload)
@@ -69,10 +110,11 @@ Throw an error to trigger retry. After `maxRetries`, the task fails permanently.
 
 ## Grouped Queues
 
-Isolated concurrency per key - perfect for per-tenant rate limiting.
+Isolated concurrency per key - perfect for per-tenant throttling.
 
-```ts
+```js
 const queue = new Queue({
+  concurrency: 5,
   groups: { concurrency: 1, delay: '50ms' }
 })
 
@@ -80,40 +122,44 @@ queue.process(async (payload) => {
   return await callExternalAPI(payload)
 })
 
+await queue.ready()
+
 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.
+Each tenant processes independently. One slow tenant won't block others. Total concurrent tasks across all tenants is capped by `concurrency`.
 
 ## Events
 
-```ts
+```js
 queue.on('new', ({ task }) => {})
 queue.on('complete', ({ task, result }) => {})
 queue.on('retry', ({ task, error, attempt }) => {})
 queue.on('failed', ({ task, error }) => {})
+queue.on('drain', () => {})
 ```
 
 ## Task Object
 
-```ts
-interface Task<T> {
-  uuid: string
-  payload: T
-  createdAt: number
-  groupKey?: string
+```js
+{
+  uuid: string,
+  payload: any,
+  createdAt: number,
+  groupKey?: string,  // present when pushed via group()
   attempts: number
 }
 ```
 
-## Rate Limiting Example
+## Throttling Example
 
-20 LLM calls/sec per tenant:
+Throttle LLM calls to external providers per tenant:
 
-```ts
+```js
 const queue = new Queue({
-  groups: { concurrency: 20, delay: '50ms' },
+  concurrency: 20,
+  groups: { concurrency: 2, delay: '50ms' },
   maxRetries: 3
 })
 
@@ -128,15 +174,54 @@ app.post('/api/generate', async (req, res) => {
 })
 ```
 
-## Horizontal Scaling
+Each tenant gets up to 2 concurrent LLM calls with a 50ms pause between them. Total concurrent calls across all tenants is capped at 20, protecting your server and API budget from any single tenant overwhelming the system.
 
-Multiple servers can push to the same queue. Redis coordinates via atomic operations - no duplicate processing.
+## 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.
+
+Send results to a specific client:
+
+```js
+import Queue from '@prsm/queue'
+import { MeshServer } from '@mesh-kit/server'
+
+const mesh = new MeshServer({ redis: { host: 'localhost', port: 6379 } })
+const queue = new Queue({ concurrency: 5, groups: { concurrency: 1 } })
+
+queue.process(async (payload) => {
+  return await generateReport(payload)
+})
+
+queue.on('complete', ({ task, result }) => {
+  mesh.sendTo(task.payload.connectionId, 'job:complete', result)
+})
+
+queue.on('failed', ({ task, error }) => {
+  mesh.sendTo(task.payload.connectionId, 'job:failed', { error: error.message })
+})
+
+mesh.exposeCommand('generate-report', async (ctx) => {
+  const taskId = await queue.group(ctx.connection.id).push({
+    connectionId: ctx.connection.id,
+    ...ctx.payload,
+  })
+  return { queued: true, taskId }
+})
+
+await queue.ready()
+await mesh.listen(8080)
+```
+
+Both queue and mesh use the same Redis instance. No key conflicts (`queue:*` vs `mesh:*`).
+
+## Horizontal Scaling
 
-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.
+Multiple servers can push to the same queue. Redis coordinates via atomic operations - no duplicate processing. Use `globalConcurrency` to enforce a hard limit across all instances.
 
 ## Cleanup
 
-```ts
+```js
 await queue.close()
 ```
 

package/package.json

@@ -1,31 +1,23 @@
 {
   "name": "@prsm/queue",
-  "version": "1.0.2",
+  "version": "2.1.0",
   "description": "Redis-backed distributed task queue with grouped concurrency, retries, and rate limiting",
   "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
     }
   },
+  "types": "./types/index.d.ts",
   "files": [
-    "dist"
+    "src",
+    "types"
   ],
   "scripts": {
-    "build": "tsup",
-    "test": "vitest",
-    "test:run": "vitest run",
-    "prepublishOnly": "npm run build"
+    "test": "vitest --reporter=verbose --run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npx tsc --declaration --allowJs --emitDeclarationOnly --skipLibCheck --target es2020 --module nodenext --moduleResolution nodenext --strict false --esModuleInterop true --outDir ./types src/index.js"
   },
   "keywords": [
     "queue",
@@ -38,7 +30,6 @@
     "concurrency",
     "retry"
   ],
-  "author": "",
   "license": "MIT",
   "dependencies": {
     "@prsm/ms": "^1.0.1",
@@ -46,9 +37,8 @@
   },
   "devDependencies": {
     "@types/node": "^22.15.29",
-    "tsup": "^8.5.0",
-    "typescript": "^5.8.3",
-    "vitest": "^3.1.4"
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
   },
   "engines": {
     "node": ">=18"

package/src/index.js

@@ -0,0 +1 @@
+export { default } from "./queue.js"