@reddb-io/sdk 1.0.7 → 1.1.0

package/src/index.js

@@ -14,46 +14,35 @@
  * Connection URIs:
  *   - 'memory://'                — ephemeral in-memory database (embedded)
  *   - 'file:///absolute/path'    — embedded, persisted to disk
- *   - 'grpc://host:port'         — remote server via gRPC
  *
- * Authentication (only meaningful for `grpc://`; embedded modes ignore
- * auth options because the spawned binary inherits the caller's
- * filesystem privileges):
- *
- *   await connect('grpc://host:5051', {
- *     auth: { token: 'sk-...' }                     // raw bearer / api key
- *   })
- *   await connect('grpc://host:5051', {
- *     auth: { apiKey: 'ak-...' }                    // alias for token
- *   })
- *   await connect('grpc://host:5051', {
- *     auth: { username: 'admin', password: 'x' }    // login flow — driver
- *                                                   // calls /auth/login,
- *                                                   // caches the bearer
- *   })
- *
- * Username/password requires the server to expose the `auth.login`
- * JSON-RPC method (proxied through the gRPC bridge).
+ * Remote URIs belong to @reddb-io/client. This SDK is embedded-only.
  */
 
 import { spawnRed } from './spawn.js'
 import { resolveSdkBinary } from './binary.js'
 import { RpcClient, RedDBError } from './protocol.js'
-import { HttpRpcClient } from './http.js'
-import { connectRedwire } from './redwire.js'
-import { parseUri, deriveLoginUrl } from './url.js'
+import { parseUri } from './url.js'
 import { CacheClient } from './cache.js'
 import { KvClient } from './kv.js'
+import { QueueClient } from './queue.js'
 import { ConfigClient } from './config.js'
 import { VaultClient } from './vault.js'
+import { TypedQueryBuilder, collectionExists, listCollections } from './db-helpers.js'
 
 export { RedDBError }
 export { CacheClient } from './cache.js'
 export { KvClient } from './kv.js'
+export { QueueClient } from './queue.js'
 export { ConfigClient } from './config.js'
 export { VaultClient } from './vault.js'
+export { TypedQueryBuilder } from './db-helpers.js'
 export { parseUri, deriveLoginUrl } from './url.js'
 
+export const EMBEDDED_ONLY_MESSAGE =
+  'remote URIs are not supported in @reddb-io/sdk; install @reddb-io/client for grpc/http/red transports'
+
+const MIN_INSERT_ID_ENGINE_VERSION = '1.0.9'
+
 /**
  * Connect to a RedDB instance.
  *
@@ -69,11 +58,12 @@ export { parseUri, deriveLoginUrl } from './url.js'
  */
 export async function connect(uri, options = {}) {
   const parsed = parseUri(uri)
-  const merged = mergeAuthFromUri(parsed, options.auth)
+  rejectRemoteUri(parsed)
 
   // Embedded modes: spawn the binary with stdio JSON-RPC. Auth is
   // not applicable (caller already has filesystem privileges).
   if (parsed.kind === 'embedded') {
+    const merged = mergeAuthFromUri(parsed, options.auth)
     if (merged.token || merged.username) {
       throw new RedDBError(
         'AUTH_NOT_APPLICABLE',
@@ -85,95 +75,130 @@ export async function connect(uri, options = {}) {
     const child = await spawnRed(binary, args)
     const client = new RpcClient(child)
     await client.call('version', {})
-    return new RedDB(client)
-  }
-
-  // HTTP / HTTPS: speak directly to the server via fetch().
-  if (parsed.kind === 'http' || parsed.kind === 'https') {
-    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 })
-    // Sanity check before returning the handle.
-    await client.call('health', {})
-    return new RedDB(client)
-  }
-
-  // gRPC / gRPCs / RedWire (default for grpc-shaped URIs):
-  // speak the RedWire binary protocol natively via TCP. No spawn, no
-  // gRPC bridge. Resolves bearer auth from username/password via
-  // HTTP /auth/login first when needed.
-  //
-  // The server multiplexes RedWire on the same port as gRPC and HTTP
-  // via the service router's 0xFE detector, so pure grpc:// URLs
-  // still flow through RedWire because it wins on perf and parity.
-  if (parsed.kind === 'grpc' || parsed.kind === 'grpcs') {
-    let token = merged.token
-    if (!token && merged.username && merged.password) {
-      const loginUrl = merged.loginUrl ?? deriveLoginUrl(parsed)
-      const session = await login(loginUrl, {
-        username: merged.username,
-        password: merged.password,
-      })
-      token = session.token
-    }
-
-    // Honour `proto=spawn-grpc` as an escape hatch for callers that
-    // explicitly want the legacy stdio→gRPC bridge. Default is the
-    // RedWire transport.
-    const protoOverride = parsed.params?.get?.('proto') ?? ''
-    if (protoOverride === 'spawn-grpc') {
-      const args = grpcArgs(parsed, token)
-      const binary = options.binary ?? resolveSdkBinary()
-      const child = await spawnRed(binary, args)
-      const legacy = new RpcClient(child)
-      await legacy.call('version', {})
-      return new RedDB(legacy)
-    }
+    return new RedDB(client, { transport: 'embedded' })
+  }
+}
 
-    const auth = token ? { kind: 'bearer', token } : { kind: 'anonymous' }
-    const tls = buildTlsOpts(parsed, options.tls)
-    const client = await connectRedwire({
-      host: parsed.host,
-      port: parsed.port,
-      auth,
-      ...(tls ? { tls } : {}),
-    })
-    return new RedDB(client)
+// Coerce a JS query parameter to a JSON-serializable shape the server
+// understands. Values JSON cannot represent losslessly use the
+// stdio/HTTP query parameter envelopes.
+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
+}
 
-  // Postgres wire: not yet wired in the driver. Document the gap
-  // so users get a clear actionable error instead of a silent
-  // unsupported transport.
-  if (parsed.kind === 'pg') {
+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(
-      'PG_TRANSPORT_NOT_WIRED',
-      "PostgreSQL wire (proto=pg) requires a node-pg-style client; "
-        + "the JS driver doesn't bundle one yet. Use a separate `pg` package "
-        + 'against the same host:port for now, or open an issue if you want it built in.',
+      'UNSUPPORTED_PARAM',
+      'array query parameters must contain only numbers',
     )
   }
-
+  if (typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+    return
+  }
   throw new RedDBError(
-    'UNSUPPORTED_KIND',
-    `internal: parsed kind '${parsed.kind}' has no transport`,
+    'UNSUPPORTED_PARAM',
+    `cannot encode query parameter of type ${typeof value}`,
   )
 }
 
-// Coerce a JS query parameter to a JSON-serializable shape the server
-// understands. The tracer scope (#355) lifts vector params: `Float32Array`
-// and `Float64Array` round-trip as plain JSON arrays of numbers, which
-// the embedded stdio handler maps to `Value::Vector`.
-function serializeParam(value) {
-  if (value instanceof Float32Array || value instanceof Float64Array) {
-    return Array.from(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 base64ToBytes(value) {
+  if (typeof Buffer !== 'undefined') {
+    const buf = Buffer.from(value, 'base64')
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength)
+  }
+  // eslint-disable-next-line no-undef
+  const text = atob(value)
+  const out = new Uint8Array(text.length)
+  for (let i = 0; i < text.length; i++) out[i] = text.charCodeAt(i)
+  return out
+}
+
+function isUuidString(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)
+}
+
+function normalizeResult(value) {
+  if (Array.isArray(value)) return value.map(normalizeResult)
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value)
+    if (keys.length === 1) {
+      if (typeof value.$bytes === 'string') return base64ToBytes(value.$bytes)
+      if (typeof value.$uuid === 'string') return value.$uuid
+      if (typeof value.$float === 'string') {
+        if (value.$float === 'NaN') return Number.NaN
+        if (value.$float === 'Infinity' || value.$float === '+Infinity') return Infinity
+        if (value.$float === '-Infinity') return -Infinity
+      }
+      if (typeof value.$ts === 'string' || typeof value.$ts === 'number') {
+        const raw = typeof value.$ts === 'string'
+          ? BigInt(value.$ts)
+          : BigInt(Math.trunc(value.$ts))
+        return new Date(Number(raw / 1_000_000n))
+      }
+    }
+    const out = {}
+    for (const [key, item] of Object.entries(value)) out[key] = normalizeResult(item)
+    return out
   }
   return value
 }
@@ -183,51 +208,11 @@ function embeddedArgs(parsed) {
   return ['rpc', '--stdio']
 }
 
-function grpcArgs(parsed, token) {
-  const scheme = parsed.kind === 'grpcs' ? 'grpcs' : 'grpc'
-  const url = `${scheme}://${parsed.host}:${parsed.port}${parsed.path ?? ''}`
-  const args = ['rpc', '--stdio', '--connect', url]
-  if (token) args.push('--token', token)
-  return args
-}
-
 /**
  * Merge `options.auth` (legacy `{ token, apiKey, username, password }`
  * shape) with credentials lifted from the URI itself. Explicit
  * `options.auth` always wins to keep behaviour predictable.
  */
-/**
- * Resolve TLS options for a redwire(s) connection.
- *
- * Sources, in priority order:
- *   - `options.tls` from the caller (object form), wins everything
- *   - `parsed.kind === 'grpcs'` (i.e. `redwires://` or `?proto=grpcs`)
- *   - `?tls=true` in the URL params
- *   - `?ca=`, `?cert=`, `?key=`, `?servername=`,
- *     `?rejectUnauthorized=false` URL params (paths or PEM strings)
- *
- * Returns `null` when TLS isn't requested.
- */
-function buildTlsOpts(parsed, callerTls) {
-  if (callerTls && typeof callerTls === 'object') {
-    return callerTls
-  }
-  const params = parsed.params
-  const wantsTls =
-    parsed.kind === 'grpcs'
-    || params?.get?.('tls') === 'true'
-    || params?.get?.('tls') === '1'
-  if (!wantsTls) return null
-  return {
-    ca: params?.get?.('ca') ?? undefined,
-    cert: params?.get?.('cert') ?? undefined,
-    key: params?.get?.('key') ?? undefined,
-    servername: params?.get?.('servername') ?? undefined,
-    rejectUnauthorized:
-      params?.get?.('rejectUnauthorized') === 'false' ? false : true,
-  }
-}
-
 function mergeAuthFromUri(parsed, optionAuth) {
   const out = {
     token: parsed.token ?? parsed.apiKey ?? null,
@@ -269,53 +254,6 @@ function mergeAuthFromUri(parsed, optionAuth) {
   return out
 }
 
-/**
- * Exchange username + password for a bearer token by hitting the
- * server's `POST /auth/login` HTTP endpoint, then return that token
- * for use with subsequent `connect({ auth: { token } })` calls.
- *
- * Why a separate function: the gRPC surface does not currently
- * expose `auth.login` as an RPC, so the driver can't piggyback on
- * the binary spawn for password auth. The HTTP listener does
- * expose it, and is the canonical login site (the same endpoint
- * the dashboard uses).
- *
- * @param {string} loginUrl Full URL of the server's auth endpoint
- *                          (e.g. `https://reddb.example.com/auth/login`).
- * @param {{ username: string, password: string }} credentials
- * @returns {Promise<{ token: string, username: string, role: string, expires_at: number }>}
- */
-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
-}
-
 /**
  * Backwards-compatible shim: translate a URI into argv for
  * `red rpc --stdio`. New code should call `parseUri` directly and
@@ -325,14 +263,12 @@ export async function login(loginUrl, { username, password }) {
 export function uriToArgs(uri, auth = null) {
   const parsed = parseUri(uri)
   if (parsed.kind === 'embedded') return embeddedArgs(parsed)
-  if (parsed.kind === 'grpc' || parsed.kind === 'grpcs') {
-    const token = auth?.kind === 'token' ? auth.token : (parsed.token ?? parsed.apiKey ?? null)
-    return grpcArgs(parsed, token)
-  }
-  throw new RedDBError(
-    'UNSUPPORTED_SCHEME',
-    `uriToArgs() supports embedded + grpc kinds; for '${parsed.kind}' use connect() directly.`,
-  )
+  rejectRemoteUri(parsed)
+}
+
+function rejectRemoteUri(parsed) {
+  if (parsed.kind === 'embedded') return
+  throw new RedDBError('EMBEDDED_ONLY', EMBEDDED_ONLY_MESSAGE)
 }
 
 
@@ -340,10 +276,18 @@ export function uriToArgs(uri, auth = null) {
  * Connection handle. Methods map 1:1 to JSON-RPC methods on the binary.
  */
 export class RedDB {
-  /** @param {RpcClient} client */
-  constructor(client) {
+  /**
+   * @param {RpcClient} client
+   * @param {object} [opts]
+   * @param {string} [opts.transport] Underlying transport label
+   *   (normally 'embedded'). Used to gate calls that the embedded
+   *   stdio bridge does not serve, like `cache.*`.
+   */
+  constructor(client, opts = {}) {
     this.client = client
-    this.cache = new CacheClient(client)
+    this.transport = opts.transport ?? null
+    this.cache = new CacheClient(client, this.transport)
+    this.queue = new QueueClient(client)
     const defaultKv = new KvClient(client)
     this.kv = Object.assign((collection = 'kv_default') => new KvClient(client, collection), {
       put: defaultKv.put.bind(defaultKv),
@@ -360,32 +304,49 @@ export class RedDB {
    *
    * Two signatures:
    *   - `query(sql)` — legacy single-arg form.
-   *   - `query(sql, params)` — positional `$N` bind values. `params` is
-   *     an array (JS scalars: number | string | null map to engine
-   *     int/float / text / null). Indices in the SQL are 1-based
-   *     (`$1`, `$2`, ...), `params` is 0-based JS-style.
+   *   - `query(sql, ...params)` — positional `$N` bind values.
+   *   - `query(sql, paramsArray)` — legacy array form.
    *
    * Returns `{ statement, affected, columns, rows }`.
    */
-  query(sql, params) {
-    if (params === undefined) {
-      return this.client.call('query', { sql })
+  query(sql, ...params) {
+    const wireParams = normalizeQueryParams(params)
+    if (wireParams == null) {
+      return this.client.call('query', { sql }).then(normalizeResult)
     }
-    if (!Array.isArray(params)) {
-      throw new TypeError('query: `params` must be an array')
-    }
-    const wireParams = params.map(serializeParam)
-    return this.client.call('query', { sql, params: wireParams })
+    return this.client.call('query', { sql, params: wireParams }).then(normalizeResult)
   }
 
-  /** Insert one row. Returns `{ affected, id? }`. */
-  insert(collection, payload) {
-    return this.client.call('insert', { collection, payload })
+  /** Execute a SQL statement. Alias for `query`, including parameter binding. */
+  execute(sql, ...params) {
+    return this.query(sql, ...params)
   }
 
-  /** Insert many rows in one call. Returns `{ affected }`. */
-  bulkInsert(collection, payloads) {
-    return this.client.call('bulk_insert', { collection, payloads })
+  /** Insert one row. Returns `{ affected, id }`. */
+  async insert(collection, payload) {
+    const result = await this.client.call('insert', { collection, payload })
+    return requireInsertId(result, 'insert')
+  }
+
+  /** Insert many rows in one call. Returns `{ affected, ids }`. */
+  async bulkInsert(collection, payloads) {
+    const result = await this.client.call('bulk_insert', { collection, payloads })
+    return requireInsertIds(result, payloads.length)
+  }
+
+  /** 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). */
@@ -409,18 +370,14 @@ export class RedDB {
   }
 
   // ---------------------------------------------------------------
-  // Auth surface — these are no-ops in embedded mode because the
+  // Auth surface — these are not available in embedded mode because the
   // bridge layer doesn't expose `auth.*` JSON-RPC methods locally.
-  // They forward to the server when the connection is grpc://.
+  // Use @reddb-io/client for remote authenticated servers.
   // ---------------------------------------------------------------
 
   /**
-   * Exchange username + password for a bearer token. Returns
-   * `{ token, username, role, expires_at }`. Server-side this
-   * routes to `POST /auth/login`.
-   *
-   * Prefer the `auth: { username, password }` form on `connect()`
-   * — it does the same exchange + caches the token transparently.
+   * Exchange username + password for a bearer token when the underlying
+   * client supports auth RPCs. Embedded SDK connections do not.
    */
   login(username, password) {
     return this.client.call('auth.login', { username, password })
@@ -459,3 +416,29 @@ export class RedDB {
     return this.client.close()
   }
 }
+
+function requireInsertId(result, method) {
+  if (!result || typeof result !== 'object' || result.id == null) {
+    throw new RedDBError(
+      'ENGINE_TOO_OLD',
+      `${method}() requires RedDB engine >= ${MIN_INSERT_ID_ENGINE_VERSION} with insert id support`,
+    )
+  }
+  return result
+}
+
+function requireInsertIds(result, expected) {
+  if (!result || typeof result !== 'object' || !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 (result.ids.length !== expected) {
+    throw new RedDBError(
+      'INVALID_RESPONSE',
+      `bulkInsert() expected ${expected} ids, got ${result.ids.length}`,
+    )
+  }
+  return result
+}

package/src/kv.js

@@ -17,6 +17,20 @@ export class KvClient {
     })
   }
 
+  async get(key, options = {}) {
+    const collection = options.collection ?? this.collection
+    const result = await this.client.call('query', {
+      sql: `KV GET ${kvPath(collection, key)}`,
+    })
+    return result?.rows?.[0]?.value ?? null
+  }
+
+  async getMany(keys, options = {}) {
+    const values = []
+    for (const key of keys) values.push(await this.get(key, options))
+    return values
+  }
+
   async invalidateTags(tags, options = {}) {
     const collection = options.collection ?? this.collection
     const result = await this.client.call('query', {
@@ -56,7 +70,15 @@ function kvPath(collection, key) {
 }
 
 function kvIdentifier(value) {
-  return String(value).replace(/[^A-Za-z0-9_]/g, '_')
+  const ident = String(value)
+  const invalid = ident.match(/[^A-Za-z0-9_]/)
+  if (invalid) {
+    throw new RedDBError(
+      'INVALID_KV_KEY',
+      `invalid KV key "${ident}": character "${invalid[0]}" is not supported`,
+    )
+  }
+  return ident
 }
 
 function kvValueLiteral(value) {

package/src/queue.js

@@ -0,0 +1,78 @@
+import { RedDBError } from './protocol.js'
+
+export class QueueClient {
+  constructor(client) {
+    this.client = client
+  }
+
+  push(queue, value, options = {}) {
+    const priority = options.priority != null ? ` PRIORITY ${queuePriority(options.priority)}` : ''
+    return this.client.call('query', {
+      sql: `QUEUE PUSH ${queueIdentifier(queue)} ${queueValueLiteral(value)}${priority}`,
+    })
+  }
+
+  async pop(queue, count) {
+    const result = await this.client.call('query', {
+      sql: `QUEUE POP ${queueIdentifier(queue)}${queueCount(count)}`,
+    })
+    return queuePayloads(result)
+  }
+
+  async peek(queue, count) {
+    const result = await this.client.call('query', {
+      sql: `QUEUE PEEK ${queueIdentifier(queue)}${queueCount(count)}`,
+    })
+    return queuePayloads(result)
+  }
+
+  async len(queue) {
+    const result = await this.client.call('query', {
+      sql: `QUEUE LEN ${queueIdentifier(queue)}`,
+    })
+    return Number(result?.rows?.[0]?.len ?? 0)
+  }
+
+  purge(queue) {
+    return this.client.call('query', {
+      sql: `QUEUE PURGE ${queueIdentifier(queue)}`,
+    })
+  }
+}
+
+function queueIdentifier(value) {
+  const ident = String(value)
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(ident)) {
+    throw new RedDBError(
+      'INVALID_QUEUE_NAME',
+      `invalid queue name "${ident}": expected an SQL identifier`,
+    )
+  }
+  return ident
+}
+
+function queueCount(count) {
+  if (count == null) return ''
+  if (!Number.isInteger(count) || count < 0) {
+    throw new RedDBError('INVALID_QUEUE_COUNT', 'queue count must be a non-negative integer')
+  }
+  return ` COUNT ${count}`
+}
+
+function queuePriority(priority) {
+  if (!Number.isInteger(priority)) {
+    throw new RedDBError('INVALID_QUEUE_PRIORITY', 'queue priority must be an integer')
+  }
+  return String(priority)
+}
+
+function queueValueLiteral(value) {
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  if (value == null) return 'NULL'
+  if (typeof value === 'string') return `'${value.replace(/'/g, "''")}'`
+  return JSON.stringify(value)
+}
+
+function queuePayloads(result) {
+  return Array.isArray(result?.rows) ? result.rows.map((row) => row.payload) : []
+}