@prsm/queue 2.0.0 → 2.1.1

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.
 
@@ -38,13 +42,14 @@ await queue.push({ userId: 123, action: 'sync' })
 
 ```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
@@ -57,6 +62,41 @@ 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
 
 ```js
@@ -70,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.
 
 ```js
 const queue = new Queue({
+  concurrency: 5,
   groups: { concurrency: 1, delay: '50ms' }
 })
 
@@ -87,7 +128,7 @@ 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
 
@@ -111,13 +152,14 @@ queue.on('drain', () => {})
 }
 ```
 
-## Rate Limiting Example
+## Throttling Example
 
-20 LLM calls/sec per tenant:
+Throttle LLM calls to external providers per tenant:
 
 ```js
 const queue = new Queue({
-  groups: { concurrency: 20, delay: '50ms' },
+  concurrency: 20,
+  groups: { concurrency: 2, delay: '50ms' },
   maxRetries: 3
 })
 
@@ -132,6 +174,8 @@ app.post('/api/generate', async (req, res) => {
 })
 ```
 
+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.
+
 ## 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.
@@ -143,7 +187,7 @@ import Queue from '@prsm/queue'
 import { MeshServer } from '@mesh-kit/server'
 
 const mesh = new MeshServer({ redis: { host: 'localhost', port: 6379 } })
-const queue = new Queue({ groups: { concurrency: 1 } })
+const queue = new Queue({ concurrency: 5, groups: { concurrency: 1 } })
 
 queue.process(async (payload) => {
   return await generateReport(payload)
@@ -173,7 +217,7 @@ Both queue and mesh use the same Redis instance. No key conflicts (`queue:*` vs
 
 ## Horizontal Scaling
 
-Multiple servers can push to the same queue. Redis coordinates via atomic operations - no duplicate processing.
+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
 

package/package.json

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

package/src/queue.js

@@ -5,7 +5,8 @@ import ms from "@prsm/ms"
 
 /**
  * @typedef {Object} QueueOptions
- * @property {number} [concurrency] - worker count (default 1)
+ * @property {number} [concurrency] - max concurrent tasks per instance (default 1)
+ * @property {number} [globalConcurrency] - max concurrent tasks across all instances, Redis-backed (default 0, disabled)
  * @property {number|string} [delay] - pause between tasks, ms or string like "100ms" (default 0)
  * @property {number|string} [timeout] - max task duration, ms or string like "30s" (default 0, no limit)
  * @property {number} [maxRetries] - attempts before failing (default 3)
@@ -30,6 +31,69 @@ import ms from "@prsm/ms"
  * @returns {Promise<any>|any}
  */
 
+const ACQUIRE_SCRIPT = `
+local key = KEYS[1]
+local max = tonumber(ARGV[1])
+local id = ARGV[2]
+local ttl = tonumber(ARGV[3])
+local time = redis.call('TIME')
+local now = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
+redis.call('ZREMRANGEBYSCORE', key, '-inf', now - ttl)
+if redis.call('ZCARD', key) < max then
+  redis.call('ZADD', key, now, id)
+  return 1
+end
+return 0
+`
+
+const RELEASE_SCRIPT = `
+redis.call('ZREM', KEYS[1], ARGV[1])
+return 1
+`
+
+const RENEW_SCRIPT = `
+local time = redis.call('TIME')
+local now = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
+if redis.call('ZSCORE', KEYS[1], ARGV[1]) then
+  redis.call('ZADD', KEYS[1], now, ARGV[1])
+  return 1
+end
+return 0
+`
+
+const LEASE_TTL = 60000
+const HEARTBEAT_INTERVAL = 15000
+const CLOSE_TIMEOUT = 5000
+
+class LocalSemaphore {
+  constructor(max) {
+    this._max = max
+    this._current = 0
+    this._waiting = []
+  }
+
+  acquire() {
+    if (this._current < this._max) {
+      this._current++
+      return Promise.resolve(true)
+    }
+    return new Promise((resolve) => this._waiting.push(resolve))
+  }
+
+  release() {
+    if (this._waiting.length > 0) {
+      this._waiting.shift()(true)
+    } else if (this._current > 0) {
+      this._current--
+    }
+  }
+
+  releaseAll() {
+    for (const resolve of this._waiting) resolve(false)
+    this._waiting = []
+  }
+}
+
 export default class Queue extends EventEmitter {
   /** @param {QueueOptions} [options] */
   constructor(options = {}) {
@@ -37,11 +101,12 @@ export default class Queue extends EventEmitter {
 
     this._options = {
       concurrency: options.concurrency ?? 1,
+      globalConcurrency: options.globalConcurrency ?? 0,
       delay: ms(options.delay ?? 0),
       timeout: ms(options.timeout ?? 0),
       maxRetries: options.maxRetries ?? 3,
       groups: {
-        concurrency: options.groups?.concurrency ?? options.concurrency ?? 1,
+        concurrency: options.groups?.concurrency ?? 1,
         delay: ms(options.groups?.delay ?? options.delay ?? 0),
         timeout: ms(options.groups?.timeout ?? options.timeout ?? 0),
         maxRetries: options.groups?.maxRetries ?? options.maxRetries ?? 3,
@@ -53,10 +118,16 @@ export default class Queue extends EventEmitter {
     this._handler = null
     this._workers = new Map()
     this._groupWorkers = new Map()
+    this._groupInFlight = new Map()
     this._workerClients = []
     this._cleanupTimer = null
     this._inFlight = 0
+    this._pushed = 0
     this._totalSettled = 0
+    this._closed = false
+    this._localSemaphore = new LocalSemaphore(this._options.concurrency)
+    this._activeLeases = new Set()
+    this._heartbeats = new Map()
 
     this._redis = createClient(this._options.redisOptions)
     this._redis.on("error", () => {})
@@ -83,38 +154,151 @@ export default class Queue extends EventEmitter {
    * @returns {Promise<string>}
    */
   async push(payload) {
+    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))
+    this._pushed++
+    try {
+      await this._redis.lPush("queue:tasks", JSON.stringify(task))
+    } 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)
+   * @returns {Promise<any>}
+   */
+  pushAndWait(payload, timeout = 0) {
+    if (this._closed) return Promise.reject(new Error("Queue is closed"))
+    const task = { 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.emit("new", { task })
+      return result
+    }, (err) => {
+      this._pushed--
+      throw err
+    })
+  }
+
   /**
    * @param {string} key
-   * @returns {{ push: (payload: any) => Promise<string> }}
+   * @returns {{ push: (payload: any) => Promise<string>, pushAndWait: (payload: any, timeout?: number|string) => Promise<any> }}
    */
   group(key) {
-    return {
-      push: async (payload) => {
-        const task = { uuid: randomUUID(), payload, createdAt: Date.now(), groupKey: key, attempts: 0 }
-        await this._redis.lPush(`queue:groups:${key}`, JSON.stringify(task))
+    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 */
+  _awaitTask(uuid, timeout = 0) {
+    const ms_ = ms(timeout)
+    return new Promise((resolve, reject) => {
+      let timer
+
+      const onComplete = ({ task, result }) => {
+        if (task.uuid !== uuid) return
+        cleanup()
+        resolve(result)
+      }
+
+      const onFailed = ({ task, error }) => {
+        if (task.uuid !== uuid) return
+        cleanup()
+        reject(error)
+      }
+
+      const cleanup = () => {
+        if (timer) clearTimeout(timer)
+        this.off("complete", onComplete)
+        this.off("failed", onFailed)
+      }
+
+      if (ms_ > 0) {
+        timer = setTimeout(() => {
+          cleanup()
+          reject(new Error("pushAndWait timed out"))
+        }, ms_)
+        timer.unref?.()
+      }
+
+      this.on("complete", onComplete)
+      this.on("failed", onFailed)
+    })
+  }
+
   /** @returns {Promise<void>} */
   async close() {
+    this._closed = true
     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()
     this._groupWorkers.clear()
+
+    this._localSemaphore.releaseAll()
+
+    if (this._inFlight > 0) {
+      await Promise.race([
+        new Promise((resolve) => {
+          const check = () => { if (this._inFlight <= 0) resolve() }
+          this.on("complete", check)
+          this.on("failed", check)
+        }),
+        new Promise((resolve) => setTimeout(resolve, CLOSE_TIMEOUT)),
+      ])
+    }
+
+    for (const [, interval] of this._heartbeats) clearInterval(interval)
+    if (this._redis.isOpen && this._activeLeases.size > 0) {
+      await Promise.all(
+        Array.from(this._activeLeases).map((id) => this._releaseGlobal(id).catch(() => {}))
+      )
+    }
+    this._heartbeats.clear()
+    this._activeLeases.clear()
+
     for (const client of this._workerClients) {
       if (client.isOpen) await client.disconnect()
     }
@@ -161,110 +345,196 @@ export default class Queue extends EventEmitter {
   async _startWorker(workerId) {
     this._workers.set(workerId, true)
     const client = await this._createWorkerClient()
-    this._runWorkerLoop(workerId, client, "queue:tasks", this._workers, (task) => this._processTask(task))
+    const opts = {
+      timeout: this._options.timeout,
+      maxRetries: this._options.maxRetries,
+      retryKey: "queue:tasks",
+    }
+    this._runWorkerLoop(workerId, client, "queue:tasks", this._workers, opts)
   }
 
   async _startGroupWorker(workerId, groupKey) {
     const groupWorkers = this._groupWorkers.get(groupKey)
     const client = await this._createWorkerClient()
-    this._runWorkerLoop(workerId, client, `queue:groups:${groupKey}`, groupWorkers, (task) => this._processGroupTask(task))
+    const opts = {
+      timeout: this._options.groups.timeout,
+      maxRetries: this._options.groups.maxRetries,
+      retryKey: `queue:groups:${groupKey}`,
+      groupKey,
+    }
+    this._runWorkerLoop(workerId, client, `queue:groups:${groupKey}`, groupWorkers, opts)
   }
 
-  async _runWorkerLoop(workerId, client, key, activeMap, processFn) {
-    const isGrouped = key.startsWith("queue:groups:")
-    const delay = isGrouped ? this._options.groups.delay : this._options.delay
+  async _runWorkerLoop(workerId, client, key, activeMap, opts) {
+    const delay = opts.groupKey ? this._options.groups.delay : this._options.delay
 
     while (activeMap.get(workerId)) {
       try {
         if (!client.isOpen) break
         const taskData = await client.brPop(key, 1)
-        if (taskData) {
-          const task = JSON.parse(taskData.element)
+        if (!taskData) continue
+
+        const task = JSON.parse(taskData.element)
+
+        const localAcquired = await this._localSemaphore.acquire()
+        if (!localAcquired) {
+          await this._redis.lPush(key, taskData.element).catch(() => {})
+          break
+        }
+
+        try {
+          let leaseId = null
+          if (this._options.globalConcurrency > 0) {
+            leaseId = await this._acquireGlobal(workerId, activeMap)
+            if (!leaseId) {
+              await this._redis.lPush(key, taskData.element).catch(() => {})
+              break
+            }
+          }
+
           this._inFlight++
-          await processFn(task)
+          if (opts.groupKey) {
+            this._groupInFlight.set(opts.groupKey, (this._groupInFlight.get(opts.groupKey) || 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 (leaseId) await this._releaseGlobal(leaseId).catch(() => {})
+          }
+        } finally {
+          this._localSemaphore.release()
         }
+
         if (delay > 0) await new Promise((resolve) => setTimeout(resolve, delay))
-      } catch (err) {
-        if (err.message?.includes("closed") || err.message?.includes("ClientClosedError")) break
+      } catch {
+        if (this._closed || !client.isOpen) break
       }
     }
+    if (client.isOpen) await client.disconnect().catch(() => {})
   }
 
-  async _processTask(task) {
-    task.attempts++
-    try {
-      if (!this._handler) {
-        this.emit("complete", { task, result: undefined })
-        this._settle()
-        return
-      }
-      const timeoutPromise = this._options.timeout > 0
-        ? new Promise((_, reject) => setTimeout(() => reject(new Error("Task timeout")), this._options.timeout))
-        : null
-      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()
+  async _acquireGlobal(workerId, activeMap) {
+    const leaseId = randomUUID()
+    while (activeMap.get(workerId) && !this._closed) {
+      if (!this._redis.isOpen) return null
+      const acquired = await this._redis.eval(ACQUIRE_SCRIPT, {
+        keys: ["queue:active"],
+        arguments: [String(this._options.globalConcurrency), leaseId, String(LEASE_TTL)],
+      })
+      if (acquired) {
+        this._activeLeases.add(leaseId)
+        const heartbeat = setInterval(() => this._renewGlobal(leaseId).catch(() => {}), HEARTBEAT_INTERVAL)
+        heartbeat.unref()
+        this._heartbeats.set(leaseId, heartbeat)
+        return leaseId
       }
+      await new Promise((r) => setTimeout(r, 50))
     }
+    return null
   }
 
-  async _processGroupTask(task) {
+  async _releaseGlobal(leaseId) {
+    this._activeLeases.delete(leaseId)
+    const heartbeat = this._heartbeats.get(leaseId)
+    if (heartbeat) {
+      clearInterval(heartbeat)
+      this._heartbeats.delete(leaseId)
+    }
+    if (this._redis.isOpen) {
+      await this._redis.eval(RELEASE_SCRIPT, {
+        keys: ["queue:active"],
+        arguments: [leaseId],
+      })
+    }
+  }
+
+  async _renewGlobal(leaseId) {
+    if (this._redis.isOpen) {
+      await this._redis.eval(RENEW_SCRIPT, {
+        keys: ["queue:active"],
+        arguments: [leaseId],
+      })
+    }
+  }
+
+  async _processTask(task, opts) {
     task.attempts++
-    try {
-      if (!this._handler) {
-        this.emit("complete", { task, result: undefined })
-        this._settle()
-        return
+    let timer
+    let result
+    let handlerError
+    let succeeded = false
+
+    if (this._handler) {
+      try {
+        const timeoutPromise = opts.timeout > 0
+          ? new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("Task timeout")), opts.timeout) })
+          : null
+        const workPromise = Promise.resolve(this._handler(task.payload, task))
+        result = timeoutPromise ? await Promise.race([workPromise, timeoutPromise]) : await workPromise
+        succeeded = true
+      } catch (err) {
+        handlerError = err
+      } finally {
+        if (timer) clearTimeout(timer)
       }
-      const timeoutPromise = this._options.groups.timeout > 0
-        ? new Promise((_, reject) => setTimeout(() => reject(new Error("Task timeout")), this._options.groups.timeout))
-        : null
-      const workPromise = Promise.resolve(this._handler(task.payload, task))
-      const result = timeoutPromise ? await Promise.race([workPromise, timeoutPromise]) : await workPromise
-      this.emit("complete", { task, result })
+    } else {
+      succeeded = true
+    }
+
+    if (succeeded) {
       this._settle()
-    } catch (error) {
-      if (task.attempts < this._options.groups.maxRetries) {
-        this.emit("retry", { task, error, attempt: task.attempts })
+      try { this.emit("complete", { task, result }) } finally { this._emitDrain() }
+    } else if (task.attempts < opts.maxRetries && !this._closed) {
+      let retried = false
+      try {
+        await this._redis.lPush(opts.retryKey, JSON.stringify(task))
+        retried = true
+      } catch {}
+      if (retried) {
         this._inFlight--
-        await this._redis.lPush(`queue:groups:${task.groupKey}`, JSON.stringify(task))
+        this.emit("retry", { task, error: handlerError, attempt: task.attempts })
       } else {
-        this.emit("failed", { task, error })
         this._settle()
+        try { this.emit("failed", { task, error: handlerError }) } finally { this._emitDrain() }
       }
+    } else {
+      this._settle()
+      try { this.emit("failed", { task, error: handlerError }) } finally { this._emitDrain() }
     }
   }
 
   _settle() {
     this._inFlight--
     this._totalSettled++
-    if (this._inFlight === 0 && this._totalSettled > 0) this.emit("drain")
+  }
+
+  _emitDrain() {
+    clearTimeout(this._drainTimer)
+    this._drainTimer = setTimeout(() => {
+      if (this._inFlight === 0 && this._totalSettled >= this._pushed) this.emit("drain")
+    }, 0)
   }
 
   async _periodicCleanup() {
     try {
       if (!this._redis.isOpen) return
-      const groupKeys = Array.from(this._groupWorkers.keys())
-      for (const groupKey of groupKeys) {
+      for (const groupKey of Array.from(this._groupWorkers.keys())) {
+        if ((this._groupInFlight.get(groupKey) || 0) > 0) continue
         const length = await this._redis.lLen(`queue:groups:${groupKey}`)
-        if (length === 0) {
-          const keyExists = await this._redis.exists(`queue:groups:${groupKey}`)
-          if (keyExists) await this._redis.del(`queue:groups:${groupKey}`)
-          const groupWorkers = this._groupWorkers.get(groupKey)
-          if (groupWorkers) {
-            groupWorkers.clear()
-            this._groupWorkers.delete(groupKey)
-          }
+        if (length > 0) continue
+        if ((this._groupInFlight.get(groupKey) || 0) > 0) continue
+        const groupWorkers = this._groupWorkers.get(groupKey)
+        if (groupWorkers) {
+          groupWorkers.clear()
+          this._groupWorkers.delete(groupKey)
         }
+        this._groupInFlight.delete(groupKey)
       }
     } catch {}
   }

package/types/queue.d.ts

@@ -1,32 +1,9 @@
-/**
- * @typedef {Object} QueueOptions
- * @property {number} [concurrency] - worker count (default 1)
- * @property {number|string} [delay] - pause between tasks, ms or string like "100ms" (default 0)
- * @property {number|string} [timeout] - max task duration, ms or string like "30s" (default 0, no limit)
- * @property {number} [maxRetries] - attempts before failing (default 3)
- * @property {{concurrency?: number, delay?: number|string, timeout?: number|string, maxRetries?: number}} [groups] - overrides for grouped queues
- * @property {{url?: string, host?: string, port?: number, password?: string}} [redisOptions]
- * @property {number} [cleanupInterval] - ms between empty group cleanup (default 30000, 0 to disable)
- */
-/**
- * @typedef {Object} Task
- * @property {string} uuid
- * @property {any} payload
- * @property {number} createdAt
- * @property {string} [groupKey]
- * @property {number} attempts
- */
-/**
- * @callback TaskHandler
- * @param {any} payload
- * @param {Task} task
- * @returns {Promise<any>|any}
- */
 export default class Queue extends EventEmitter<[never]> {
     /** @param {QueueOptions} [options] */
     constructor(options?: QueueOptions);
     _options: {
         concurrency: number;
+        globalConcurrency: number;
         delay: any;
         timeout: any;
         maxRetries: number;
@@ -47,10 +24,16 @@ export default class Queue extends EventEmitter<[never]> {
     _handler: TaskHandler;
     _workers: Map<any, any>;
     _groupWorkers: Map<any, any>;
+    _groupInFlight: Map<any, any>;
     _workerClients: any[];
     _cleanupTimer: NodeJS.Timeout;
     _inFlight: number;
+    _pushed: number;
     _totalSettled: number;
+    _closed: boolean;
+    _localSemaphore: LocalSemaphore;
+    _activeLeases: Set<any>;
+    _heartbeats: Map<any, any>;
     _redis: import("@redis/client").RedisClientType<{
         json: {
             ARRAPPEND: {
@@ -2377,13 +2360,22 @@ export default class Queue extends EventEmitter<[never]> {
      * @returns {Promise<string>}
      */
     push(payload: any): Promise<string>;
+    /**
+     * @param {any} payload
+     * @param {number|string} [timeout] - max time to wait for result, ms or string like "30s" (default 0, no limit)
+     * @returns {Promise<any>}
+     */
+    pushAndWait(payload: any, timeout?: number | string): Promise<any>;
     /**
      * @param {string} key
-     * @returns {{ push: (payload: any) => Promise<string> }}
+     * @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>;
     };
+    /** @private */
+    private _awaitTask;
     /** @returns {Promise<void>} */
     close(): Promise<void>;
     _initialize(): Promise<void>;
@@ -4705,17 +4697,25 @@ export default class Queue extends EventEmitter<[never]> {
     _startGroupWorkers(groupKey: any): Promise<void>;
     _startWorker(workerId: any): Promise<void>;
     _startGroupWorker(workerId: any, groupKey: any): Promise<void>;
-    _runWorkerLoop(workerId: any, client: any, key: any, activeMap: any, processFn: any): Promise<void>;
-    _processTask(task: any): Promise<void>;
-    _processGroupTask(task: any): Promise<void>;
+    _runWorkerLoop(workerId: any, client: any, key: any, activeMap: any, opts: any): Promise<void>;
+    _acquireGlobal(workerId: any, activeMap: any): Promise<`${string}-${string}-${string}-${string}-${string}`>;
+    _releaseGlobal(leaseId: any): Promise<void>;
+    _renewGlobal(leaseId: any): Promise<void>;
+    _processTask(task: any, opts: any): Promise<void>;
     _settle(): void;
+    _emitDrain(): void;
+    _drainTimer: NodeJS.Timeout;
     _periodicCleanup(): Promise<void>;
 }
 export type QueueOptions = {
     /**
-     * - worker count (default 1)
+     * - max concurrent tasks per instance (default 1)
      */
     concurrency?: number;
+    /**
+     * - max concurrent tasks across all instances, Redis-backed (default 0, disabled)
+     */
+    globalConcurrency?: number;
     /**
      * - pause between tasks, ms or string like "100ms" (default 0)
      */
@@ -4757,3 +4757,13 @@ export type Task = {
 };
 export type TaskHandler = (payload: any, task: Task) => Promise<any> | any;
 import { EventEmitter } from "events";
+declare class LocalSemaphore {
+    constructor(max: any);
+    _max: any;
+    _current: number;
+    _waiting: any[];
+    acquire(): Promise<any>;
+    release(): void;
+    releaseAll(): void;
+}
+export {};