@reddb-io/client 1.7.0 → 1.9.0

package/src/index.browser.js

@@ -0,0 +1,156 @@
+/**
+ * @reddb-io/client — browser entrypoint.
+ *
+ * The browser counterpart to `./index.js`. It builds `connect()` on the
+ * transport-agnostic core (`./core/index.js`), dispatching only the
+ * browser-reachable wires:
+ *
+ *   - 'http://host:port'   — HTTP JSON-RPC over `fetch`
+ *   - 'https://host:port'  — HTTPS JSON-RPC over `fetch`
+ *
+ * Streaming is the Web-streams implementation (`./streaming-web.js`), so the
+ * full transport-agnostic surface works client-side: query, execute, insert,
+ * bulkInsert, transactions, the kv/documents/queue/cache/config/vault clients,
+ * the typed query builder, and streaming (`stream()` / `inputStream()`).
+ *
+ * This module imports **neither** the gRPC transport (`./grpc.js`, which pulls
+ * `node:http2`) **nor** the RedWire transport (`./redwire.js`) **nor** the
+ * `node:stream` streaming impl (`./streaming.js`). No `node:` built-in enters
+ * the browser bundle graph through it. A portability guard test
+ * (`test/browser-portability.test.mjs`) is the regression net for that.
+ *
+ * Schemes that need a raw TCP socket or HTTP/2 — `grpc://`, `grpcs://`,
+ * `red://`, `reds://`, and `pg` — are not reachable from a browser sandbox.
+ * `connect()` rejects them with an actionable error (see
+ * `BROWSER_TRANSPORT_UNSUPPORTED` below) instead of crashing the bundler or
+ * runtime. Embedded URIs (`memory://`, `file://`, `red:///path`) are rejected
+ * with the same wording as the Node entry.
+ */
+
+import {
+  RedDBError,
+  RedDB as CoreRedDB,
+  Collection,
+  EmbeddedNotSupported,
+  EMBEDDED_REJECTION_MESSAGE,
+  isEmbeddedUri,
+  rejectEmbeddedUri,
+  parseUri,
+  login,
+  mergeAuthFromUri,
+} from './core/index.js'
+import { HttpRpcClient } from './http.js'
+import { createSelectStream, createInputStream } from './streaming-web.js'
+
+export { RedDBError, EmbeddedNotSupported, EMBEDDED_REJECTION_MESSAGE, isEmbeddedUri }
+export { RowReadable, RowWritable } from './streaming-web.js'
+export { CacheClient } from './cache.js'
+export { KvClient } from './kv.js'
+export { QueueClient } from './queue.js'
+export { DocumentClient } from './documents.js'
+export { ConfigClient } from './config.js'
+export { VaultClient } from './vault.js'
+export { TypedQueryBuilder } from './db-helpers.js'
+export { parseUri, deriveLoginUrl } from './url.js'
+export { login }
+
+// The Web-streams streaming implementation, injected into the core `RedDB` so
+// its `stream()` / `inputStream()` return Web-streams-backed row wrappers. The
+// core itself never statically references Web (or `node:`) streams.
+const WEB_STREAMING = { createSelectStream, createInputStream }
+
+/**
+ * Shared wording for schemes a browser sandbox cannot reach: they need a raw
+ * TCP socket (`red(s)://`, `pg`) or HTTP/2 (`grpc(s)://`), neither of which a
+ * browser exposes to JavaScript. The remedy is the same in every case — point
+ * the client at an HTTP(S) endpoint or gateway in front of the server.
+ */
+function browserTransportError(scheme) {
+  return new RedDBError(
+    'BROWSER_TRANSPORT_UNSUPPORTED',
+    `'${scheme}' connections are not available in the browser: the `
+      + `browser sandbox exposes no raw TCP socket (red://, reds://, pg) or `
+      + `HTTP/2 client (grpc://, grpcs://) to JavaScript. Connect to an `
+      + `HTTP(S) endpoint instead — e.g. 'http://host:port' / `
+      + `'https://host:port' — by running RedDB's HTTP JSON-RPC listener or `
+      + `an HTTP gateway in front of the server, then call `
+      + `connect('https://…').`,
+  )
+}
+
+/**
+ * Connect to a remote RedDB instance from a browser.
+ *
+ * @param {string} uri Connection URI. Only `http(s)://` is reachable from a
+ *   browser; other schemes raise `BROWSER_TRANSPORT_UNSUPPORTED`.
+ * @param {object} [options]
+ * @param {object} [options.auth] Authentication credentials.
+ * @param {string} [options.auth.token] Bearer / API-key token.
+ * @param {string} [options.auth.apiKey] Alias for `token`.
+ * @param {string} [options.auth.username] Username for password login.
+ * @param {string} [options.auth.password] Password for password login.
+ * @param {string} [options.auth.loginUrl] Override URL for the password
+ *   exchange (defaults to deriving `/auth/login` from `uri`).
+ * @returns {Promise<RedDB>}
+ */
+export async function connect(uri, options = {}) {
+  // Reject embedded shapes upfront with the same wording the Node entry and
+  // the Rust binary use, before the URL parser would map them to kind=embedded.
+  rejectEmbeddedUri(uri)
+
+  const parsed = parseUri(uri)
+
+  // Belt-and-braces: if the parser still produced an embedded kind, reject it.
+  if (parsed.kind === 'embedded') {
+    throw new EmbeddedNotSupported(uri)
+  }
+
+  if (parsed.kind === 'http' || parsed.kind === 'https') {
+    const merged = mergeAuthFromUri(parsed, options.auth)
+    const baseUrl = `${parsed.kind}://${parsed.host}:${parsed.port}`
+    let token = merged.token
+    if (!token && merged.username && merged.password) {
+      const loginUrl = merged.loginUrl ?? `${baseUrl}/auth/login`
+      const session = await login(loginUrl, {
+        username: merged.username,
+        password: merged.password,
+      })
+      token = session.token
+    }
+    const client = new HttpRpcClient({ baseUrl, token })
+    await client.call('query', { sql: 'SELECT 1' })
+    return new RedDB(client)
+  }
+
+  if (
+    parsed.kind === 'grpc'
+    || parsed.kind === 'grpcs'
+    || parsed.kind === 'red'
+    || parsed.kind === 'reds'
+    || parsed.kind === 'pg'
+  ) {
+    throw browserTransportError(parsed.kind)
+  }
+
+  throw new RedDBError(
+    'UNSUPPORTED_KIND',
+    `internal: parsed kind '${parsed.kind}' has no browser transport`,
+  )
+}
+
+/**
+ * Browser connection handle. The full request-shaping surface lives in the
+ * transport-agnostic core `RedDB`; this subclass exists only to inject the
+ * Web-streams streaming implementation so `stream()` / `inputStream()` return
+ * Web-streams-backed row wrappers. The public surface — every method, the
+ * `kv`/`config`/`vault` factory shapes, the `cache`/`queue`/`documents`
+ * clients — is the core's, unchanged.
+ */
+export class RedDB extends CoreRedDB {
+  /** @param {HttpRpcClient} client */
+  constructor(client) {
+    super(client, WEB_STREAMING)
+  }
+}
+
+export { Collection }

package/src/index.js

@@ -26,26 +26,26 @@
  * need an embedded engine, install `@reddb-io/sdk` instead.
  */
 
-import { RedDBError } from './protocol.js'
-import { HttpRpcClient } from './http.js'
-import { GrpcRpcClient } from './grpc.js'
-import { connectRedwire } from './redwire.js'
-import { parseUri, deriveLoginUrl } from './url.js'
 import {
+  RedDBError,
+  RedDB as CoreRedDB,
+  Collection,
   EmbeddedNotSupported,
   EMBEDDED_REJECTION_MESSAGE,
   isEmbeddedUri,
   rejectEmbeddedUri,
-} from './embedded-rejection.js'
-import { CacheClient } from './cache.js'
-import { KvClient } from './kv.js'
-import { QueueClient } from './queue.js'
-import { DocumentClient } from './documents.js'
-import { ConfigClient } from './config.js'
-import { VaultClient } from './vault.js'
-import { TypedQueryBuilder, collectionExists, listCollections } from './db-helpers.js'
+  parseUri,
+  deriveLoginUrl,
+  login,
+  mergeAuthFromUri,
+} from './core/index.js'
+import { HttpRpcClient } from './http.js'
+import { GrpcRpcClient } from './grpc.js'
+import { connectRedwire } from './redwire.js'
+import { createSelectStream, createInputStream } from './streaming.js'
 
 export { RedDBError, EmbeddedNotSupported, EMBEDDED_REJECTION_MESSAGE, isEmbeddedUri }
+export { splitNdjson, RowReadable, RowWritable } from './streaming.js'
 export { CacheClient } from './cache.js'
 export { KvClient } from './kv.js'
 export { QueueClient } from './queue.js'
@@ -54,9 +54,12 @@ export { ConfigClient } from './config.js'
 export { VaultClient } from './vault.js'
 export { TypedQueryBuilder } from './db-helpers.js'
 export { parseUri, deriveLoginUrl } from './url.js'
+export { login }
 
-const MIN_INSERT_ID_ENGINE_VERSION = '1.0.9'
-const NESTED_TX_NOT_SUPPORTED = 'NESTED_TX_NOT_SUPPORTED'
+// The `node:stream`-based streaming implementation, injected into the core
+// `RedDB` so its `stream()` / `inputStream()` return Node streams. The core
+// itself never statically references `node:stream`.
+const NODE_STREAMING = { createSelectStream, createInputStream }
 
 /**
  * Connect to a remote RedDB instance.
@@ -158,89 +161,6 @@ export async function connect(uri, options = {}) {
   )
 }
 
-function serializeParam(value) {
-  assertSupportedParam(value)
-  if (value instanceof Float32Array || value instanceof Float64Array) {
-    return Array.from(value)
-  }
-  if (value instanceof Date) {
-    return { $ts: String(BigInt(value.getTime()) * 1_000_000n) }
-  }
-  if (value instanceof Uint8Array || (typeof Buffer !== 'undefined' && value instanceof Buffer)) {
-    return { $bytes: bytesToBase64(value) }
-  }
-  if (typeof value === 'number' && !Number.isFinite(value)) {
-    if (Number.isNaN(value)) return { $float: 'NaN' }
-    return { $float: value > 0 ? 'Infinity' : '-Infinity' }
-  }
-  if (typeof value === 'string' && isUuidString(value)) {
-    return { $uuid: value }
-  }
-  return value
-}
-
-function assertSupportedParam(value) {
-  if (value == null) return
-  if (
-    typeof value === 'boolean'
-    || typeof value === 'number'
-    || typeof value === 'string'
-  ) {
-    return
-  }
-  if (value instanceof Date) {
-    if (Number.isNaN(value.getTime())) {
-      throw new RedDBError('UNSUPPORTED_PARAM', 'cannot encode invalid Date query parameter')
-    }
-    return
-  }
-  if (
-    value instanceof Uint8Array
-    || value instanceof Float32Array
-    || value instanceof Float64Array
-    || (typeof Buffer !== 'undefined' && value instanceof Buffer)
-  ) {
-    return
-  }
-  if (Array.isArray(value)) {
-    if (value.every((item) => typeof item === 'number')) return
-    throw new RedDBError(
-      'UNSUPPORTED_PARAM',
-      'array query parameters must contain only numbers',
-    )
-  }
-  if (typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
-    return
-  }
-  throw new RedDBError(
-    'UNSUPPORTED_PARAM',
-    `cannot encode query parameter of type ${typeof value}`,
-  )
-}
-
-function normalizeQueryParams(args) {
-  if (args.length === 0) return null
-  if (args.length === 1 && Array.isArray(args[0])) return args[0].map(serializeParam)
-  return args.map(serializeParam)
-}
-
-function bytesToBase64(value) {
-  const bytes = value instanceof Uint8Array
-    ? value
-    : new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
-  if (typeof Buffer !== 'undefined') {
-    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64')
-  }
-  let text = ''
-  for (const byte of bytes) text += String.fromCharCode(byte)
-  // eslint-disable-next-line no-undef
-  return btoa(text)
-}
-
-function isUuidString(value) {
-  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)
-}
-
 /**
  * Resolve TLS options for a redwire(s) connection. Source order:
  *   1. caller-supplied `options.tls` object.
@@ -270,317 +190,22 @@ function buildTlsOpts(parsed, callerTls) {
   }
 }
 
-function mergeAuthFromUri(parsed, optionAuth) {
-  const out = {
-    token: parsed.token ?? parsed.apiKey ?? null,
-    username: parsed.username ?? null,
-    password: parsed.password ?? null,
-    loginUrl: parsed.loginUrl ?? null,
-  }
-  if (optionAuth == null) return out
-  if (typeof optionAuth !== 'object') {
-    throw new TypeError('options.auth must be an object')
-  }
-  if (optionAuth.token != null) {
-    if (typeof optionAuth.token !== 'string' || optionAuth.token.length === 0) {
-      throw new TypeError('options.auth.token must be a non-empty string')
-    }
-    out.token = optionAuth.token
-  }
-  if (optionAuth.apiKey != null) {
-    if (typeof optionAuth.apiKey !== 'string' || optionAuth.apiKey.length === 0) {
-      throw new TypeError('options.auth.apiKey must be a non-empty string')
-    }
-    out.token = optionAuth.apiKey
-  }
-  if (optionAuth.username != null) {
-    if (typeof optionAuth.username !== 'string' || optionAuth.username.length === 0) {
-      throw new TypeError('options.auth.username must be a non-empty string')
-    }
-    out.username = optionAuth.username
-  }
-  if (optionAuth.password != null) {
-    if (typeof optionAuth.password !== 'string' || optionAuth.password.length === 0) {
-      throw new TypeError('options.auth.password must be a non-empty string')
-    }
-    out.password = optionAuth.password
-  }
-  if (optionAuth.loginUrl != null) {
-    out.loginUrl = optionAuth.loginUrl
-  }
-  return out
-}
-
 /**
- * Exchange username + password for a bearer token via the server's
- * `POST /auth/login` HTTP endpoint. Same flow used by `connect()` when
- * the caller passes `auth: { username, password }`.
+ * Node connection handle. The full request-shaping surface lives in the
+ * transport-agnostic core `RedDB`; this subclass exists only to inject the
+ * `node:stream`-based streaming implementation so `stream()` / `inputStream()`
+ * return Node streams. The public surface — every method, the `kv`/`config`/
+ * `vault` factory shapes, the `cache`/`queue`/`documents` clients — is the
+ * core's, unchanged.
  *
- * @param {string} loginUrl Full URL of the server's auth endpoint.
- * @param {{ username: string, password: string }} credentials
- * @returns {Promise<{ token: string, username: string, role: string, expires_at: number }>}
+ * The `Collection` handle (`db.collection(name)`) is re-exported from the
+ * core verbatim.
  */
-export async function login(loginUrl, { username, password }) {
-  if (typeof loginUrl !== 'string' || !loginUrl.startsWith('http')) {
-    throw new TypeError("login() requires an http(s):// URL pointing at /auth/login")
-  }
-  if (typeof username !== 'string' || username.length === 0) {
-    throw new TypeError('login() requires a non-empty username')
-  }
-  if (typeof password !== 'string' || password.length === 0) {
-    throw new TypeError('login() requires a non-empty password')
-  }
-  const response = await fetch(loginUrl, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ username, password }),
-  })
-  const body = await response.json().catch(() => ({}))
-  if (!response.ok || body.ok === false) {
-    const code = body.error_code || `HTTP_${response.status}`
-    const message = body.error || `auth/login returned ${response.status}`
-    throw new RedDBError(code, message, body)
-  }
-  if (typeof body.token !== 'string') {
-    throw new RedDBError(
-      'AUTH_LOGIN_BAD_RESPONSE',
-      'auth/login response missing string token',
-      body,
-    )
-  }
-  return body
-}
-
-/**
- * Connection handle. Methods map 1:1 to JSON-RPC methods on the server.
- * Identical surface to `@reddb-io/sdk`'s `RedDB`, minus the local-spawn
- * lifecycle.
- */
-class TransactionHandle {
-  constructor(db) {
-    this.db = db
-  }
-
-  query(sql, ...params) {
-    return this.db.query(sql, ...params)
-  }
-
-  execute(sql, ...params) {
-    return this.db.execute(sql, ...params)
-  }
-
-  insert(collection, payload) {
-    return this.db.insert(collection, payload)
-  }
-
-  bulkInsert(collection, payloads) {
-    return this.db.bulkInsert(collection, payloads)
-  }
-
-  async transaction() {
-    throw nestedTransactionError()
-  }
-}
-
-export class RedDB {
+export class RedDB extends CoreRedDB {
   /** @param {HttpRpcClient | import('./redwire.js').RedWireClient} client */
   constructor(client) {
-    this.client = client
-    this.cache = new CacheClient(client)
-    this.queue = new QueueClient(client)
-    this.documents = new DocumentClient(this)
-    const defaultKv = new KvClient(client)
-    this.kv = Object.assign((collection = 'kv_default') => new KvClient(client, collection), {
-      put: defaultKv.put.bind(defaultKv),
-      invalidateTags: defaultKv.invalidateTags.bind(defaultKv),
-      watch: defaultKv.watch.bind(defaultKv),
-      watchPrefix: defaultKv.watchPrefix.bind(defaultKv),
-    })
-    this.config = (collection = 'red.config') => new ConfigClient(client, collection)
-    this.vault = (collection = 'red.vault') => new VaultClient(client, collection)
-    this.inTransaction = false
-  }
-
-  /** Execute a SQL query. Returns `{ statement, affected, columns, rows }`. */
-  query(sql, ...params) {
-    const wireParams = normalizeQueryParams(params)
-    if (wireParams == null) {
-      return this.client.call('query', { sql })
-    }
-    return this.client.call('query', { sql, params: wireParams })
-  }
-
-  /** Execute a SQL statement. Alias for `query`, including parameter binding. */
-  execute(sql, ...params) {
-    return this.query(sql, ...params)
-  }
-
-  /** Insert one row. Returns `{ affected, rid, id }`; `id` is a legacy alias for `rid`. */
-  async insert(collection, payload) {
-    let result = await this.client.call('insert', { collection, payload })
-    if (
-      result &&
-      typeof result === 'object' &&
-      !('affected' in result) &&
-      ('rid' in result || 'id' in result)
-    ) {
-      result = { ...result, affected: 1 }
-    }
-    return requireInsertId(result, 'insert')
-  }
-
-  /** Insert many rows in one call. Returns `{ affected, rids, ids }`; `ids` is a legacy alias. */
-  async bulkInsert(collection, payloads) {
-    const result = await this.client.call('bulk_insert', { collection, payloads })
-    return requireInsertIds(result, payloads.length)
-  }
-
-  async transaction(callback) {
-    if (this.inTransaction) {
-      throw nestedTransactionError()
-    }
-    if (typeof callback !== 'function') {
-      throw new TypeError('transaction(callback) requires a function')
-    }
-
-    this.inTransaction = true
-    let began = false
-    try {
-      await this.query('BEGIN')
-      began = true
-      const result = await callback(new TransactionHandle(this))
-      await this.query('COMMIT')
-      return result
-    } catch (err) {
-      if (began) {
-        try {
-          await this.query('ROLLBACK')
-        } catch (rollbackErr) {
-          attachRollbackError(err, rollbackErr)
-        }
-      }
-      throw err
-    } finally {
-      this.inTransaction = false
-    }
-  }
-
-  /** Return true when a collection is visible in the catalog. */
-  exists(collection) {
-    return collectionExists(this, collection)
-  }
-
-  /** List visible collections using SHOW COLLECTIONS. */
-  list() {
-    return listCollections(this)
-  }
-
-  /** Return a caller-typed query builder for a collection. */
-  from(collection) {
-    return new TypedQueryBuilder(this, collection)
-  }
-
-  /** Get an entity by id. Returns `{ entity }` (entity is `null` if not found). */
-  get(collection, id) {
-    return this.client.call('get', { collection, id: String(id) })
-  }
-
-  /** Delete an entity by id. Returns `{ affected }`. */
-  delete(collection, id) {
-    return this.client.call('delete', { collection, id: String(id) })
-  }
-
-  /** Probe the server. Returns `{ ok: true, version }`. */
-  health() {
-    return this.client.call('health', {})
-  }
-
-  /** Server version + protocol version. */
-  version() {
-    return this.client.call('version', {})
-  }
-
-  /** Exchange username + password for a bearer token. */
-  login(username, password) {
-    return this.client.call('auth.login', { username, password })
-  }
-
-  /** Identify the current caller. */
-  whoami() {
-    return this.client.call('auth.whoami', {})
+    super(client, NODE_STREAMING)
   }
-
-  /** Change the current caller's password. */
-  changePassword(currentPassword, newPassword) {
-    return this.client.call('auth.change_password', {
-      current_password: currentPassword,
-      new_password: newPassword,
-    })
-  }
-
-  /** Mint a long-lived API key. */
-  createApiKey({ username, role } = {}) {
-    return this.client.call('auth.create_api_key', { username, role })
-  }
-
-  /** Revoke an API key by its public id. */
-  revokeApiKey(key) {
-    return this.client.call('auth.revoke_api_key', { key })
-  }
-
-  /** Close the underlying transport. */
-  close() {
-    return this.client.close()
-  }
-}
-
-function nestedTransactionError() {
-  return new RedDBError(
-    NESTED_TX_NOT_SUPPORTED,
-    `${NESTED_TX_NOT_SUPPORTED}: nested transactions are not supported on one connection`,
-  )
 }
 
-function attachRollbackError(err, rollbackErr) {
-  if (err && typeof err === 'object') {
-    try {
-      err.rollbackError = rollbackErr
-    } catch {
-      // Preserve the original callback/query error even for frozen errors.
-    }
-  }
-}
-
-function requireInsertId(result, method) {
-  if (!result || typeof result !== 'object' || (result.rid == null && result.id == null)) {
-    throw new RedDBError(
-      'ENGINE_TOO_OLD',
-      `${method}() requires RedDB engine >= ${MIN_INSERT_ID_ENGINE_VERSION} with insert id support`,
-    )
-  }
-  if (result.rid == null) result.rid = result.id
-  if (result.id == null) result.id = result.rid
-  return result
-}
-
-function requireInsertIds(result, expected) {
-  if (
-    !result ||
-    typeof result !== 'object' ||
-    (!Array.isArray(result.rids) && !Array.isArray(result.ids))
-  ) {
-    throw new RedDBError(
-      'ENGINE_TOO_OLD',
-      `bulkInsert() requires RedDB engine >= ${MIN_INSERT_ID_ENGINE_VERSION} with bulk insert id support`,
-    )
-  }
-  if (!Array.isArray(result.rids)) result.rids = result.ids
-  if (!Array.isArray(result.ids)) result.ids = result.rids
-  if (result.rids.length !== expected) {
-    throw new RedDBError(
-      'INVALID_RESPONSE',
-      `bulkInsert() expected ${expected} rids, got ${result.rids.length}`,
-    )
-  }
-  return result
-}
+export { Collection }

package/src/protocol.js

@@ -8,23 +8,16 @@
  * Spec: PLAN_DRIVERS.md, "Spec do protocolo stdio".
  */
 
+import { RedDBError } from './core/errors.js'
+
+// Re-exported from the transport-agnostic core so existing
+// `import { RedDBError } from './protocol.js'` call sites keep working.
+export { RedDBError }
+
 const NEWLINE = 0x0a // '\n'
 const encoder = new TextEncoder()
 const decoder = new TextDecoder('utf-8')
 
-/**
- * RedDB-shaped error. Drivers in other languages should expose an
- * equivalent class with the same `code` field.
- */
-export class RedDBError extends Error {
-  constructor(code, message, data) {
-    super(message)
-    this.name = 'RedDBError'
-    this.code = code
-    this.data = data ?? null
-  }
-}
-
 export class RpcClient {
   /** @param {import('./spawn.js').RedProcess} child */
   constructor(child) {

package/src/queue.js

@@ -38,6 +38,30 @@ export class QueueClient {
       sql: `QUEUE PURGE ${queueIdentifier(queue)}`,
     })
   }
+
+  // Live `QUEUE READ … WAIT <ms>` helper (PRD #718 / #725). Same
+  // contract as drivers/js: required `waitMs`, timeout returns empty
+  // array, cancellation/cap rejection surface as transport errors.
+  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) {