@reddb-io/sdk 1.7.0 → 1.8.0

package/index.d.ts

@@ -298,6 +298,18 @@ export class QueueClient {
   peek(queue: string, count?: number): Promise<unknown[]>
   len(queue: string): Promise<number>
   purge(queue: string): Promise<QueryResult>
+  /**
+   * Live `QUEUE READ … WAIT <ms>` helper (PRD #718 / #725). Blocks
+   * until a message is available, the wait budget elapses, or the
+   * server cancels. Timeout returns an empty array — same shape as
+   * an empty pop, never throws. `waitMs` is required; there is no
+   * infinite-wait default.
+   */
+  readWait(
+    queue: string,
+    consumer: string,
+    options: { waitMs: number; group?: string; count?: number },
+  ): Promise<unknown[]>
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reddb-io/sdk",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Official embedded RedDB SDK — launches a local red binary over stdio JSON-RPC. Use @reddb-io/client for remote HTTP, gRPC, and RedWire.",
   "type": "module",
   "main": "src/index.js",

package/src/queue.js

@@ -46,6 +46,35 @@ export class QueueClient {
       sql: `QUEUE PURGE ${queueIdentifier(queue)}`,
     })
   }
+
+  // Live `QUEUE READ … WAIT <ms>` helper (PRD #718 / #725). Blocks until
+  // a message is available for `consumer` on `queue` (optionally scoped
+  // to `group`), the wait budget elapses, or the server cancels.
+  //
+  // Timeout returns the same empty array as a non-waiting empty pop —
+  // never an exception. `waitMs` is required; there is no infinite-wait
+  // default. Server-side cancellation, transport cancellation, and cap
+  // rejection surface as RedDBErrors from the transport path.
+  async readWait(queue, consumer, options = {}) {
+    const sql = buildQueueReadWaitSql(queue, consumer, options)
+    const result = await this.client.call('query', { sql })
+    return queuePayloads(result)
+  }
+}
+
+function buildQueueReadWaitSql(queue, consumer, options) {
+  const { waitMs, group = null, count = null } = options ?? {}
+  if (!Number.isInteger(waitMs) || waitMs < 0) {
+    throw new RedDBError(
+      'INVALID_QUEUE_WAIT',
+      'queue readWait requires an explicit non-negative integer waitMs (no infinite wait)',
+    )
+  }
+  const q = queueIdentifier(queue)
+  const c = queueIdentifier(consumer)
+  const g = group != null ? ` GROUP ${queueIdentifier(group)}` : ''
+  const n = count != null ? queueCount(count) : ''
+  return `QUEUE READ ${q}${g} CONSUMER ${c}${n} WAIT ${waitMs}ms`
 }
 
 function queueIdentifier(value) {