@reddb-io/cli 1.0.7 → 1.1.0

package/README.md

@@ -597,12 +597,14 @@ npx @reddb-io/cli@latest server --wire-bind 127.0.0.1:5050 --http-bind 127.0.0.1
 Or via Docker:
 
 ```bash
+echo "$GITHUB_TOKEN" | docker login ghcr.io -u "$GITHUB_USER" --password-stdin # if GHCR requires auth
 docker run --rm -p 5050:5050 -p 5055:5055 -p 8080:8080 ghcr.io/reddb-io/reddb:latest
 ```
 
 Or, if you only need the thin remote-only client (~7 MB image):
 
 ```bash
+echo "$GITHUB_TOKEN" | docker login ghcr.io -u "$GITHUB_USER" --password-stdin # if GHCR requires auth
 docker run --rm ghcr.io/reddb-io/reddb-client:latest red://reddb.example.com:5050 -c "SELECT 1"
 ```
 

package/drivers/js/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@reddb-io/sdk",
-  "version": "1.0.7",
-  "description": "Official RedDB driver — talks the native RedWire TCP protocol (mTLS), HTTP, gRPC bridge, or embedded stdio JSON-RPC. Works in Node 18+, Bun and Deno.",
+  "version": "1.1.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",
   "exports": {
@@ -20,7 +20,7 @@
   ],
   "scripts": {
     "postinstall": "node postinstall.js",
-    "test": "node --test test/cache.test.mjs && node test/smoke.test.mjs"
+    "test": "node --test test/ask.test.mjs test/cache.test.mjs test/db-helpers.test.mjs test/embedded-only.test.mjs test/insert-ids.test.mjs test/kv.test.mjs test/params.test.mjs test/postinstall.test.mjs test/queue.test.mjs test/redwire.params.test.mjs && node test/smoke.test.mjs"
   },
   "engines": {
     "node": ">=18"

package/drivers/js/src/cache.js

@@ -6,13 +6,37 @@
  * flushNamespace routes to the existing POST /admin/blob_cache/flush_namespace.
  * All others target endpoints planned for a future server release.
  *
+ * Requires an HTTP or gRPC transport. On embedded (stdio JSON-RPC), every
+ * method throws `UNSUPPORTED_TRANSPORT` before issuing the RPC call —
+ * the engine's stdio handler doesn't implement `cache.*`.
+ *
  * Values are base64-encoded in transit so binary payloads survive JSON.
  */
 
+import { RedDBError } from './protocol.js'
+
+const UNSUPPORTED_TRANSPORTS = new Set(['embedded'])
+
 export class CacheClient {
-  /** @param {{ call: Function }} client */
-  constructor(client) {
+  /**
+   * @param {{ call: Function }} client
+   * @param {string} [transport] Underlying transport label (e.g. 'http',
+   *   'grpc', 'embedded'). When the transport doesn't serve `cache.*`,
+   *   every method throws `UNSUPPORTED_TRANSPORT` before any RPC call.
+   */
+  constructor(client, transport) {
     this._client = client
+    this._transport = transport ?? null
+  }
+
+  _guard(method) {
+    if (this._transport && UNSUPPORTED_TRANSPORTS.has(this._transport)) {
+      throw new RedDBError(
+        'UNSUPPORTED_TRANSPORT',
+        `cache.${method} is not available on '${this._transport}' transport; `
+          + 'use @reddb-io/client for remote cache endpoints.',
+      )
+    }
   }
 
   /**
@@ -22,6 +46,7 @@ export class CacheClient {
    * @returns {Promise<Uint8Array | null>}
    */
   async get(namespace, key) {
+    this._guard('get')
     const result = await this._client.call('cache.get', { namespace, key })
     if (result == null || result.value == null) return null
     return base64ToBytes(result.value)
@@ -39,6 +64,7 @@ export class CacheClient {
    * @returns {Promise<void>}
    */
   async put(namespace, key, value, opts = {}) {
+    this._guard('put')
     const encoded = bytesToBase64(value)
     await this._client.call('cache.put', {
       namespace,
@@ -55,6 +81,7 @@ export class CacheClient {
    * @returns {Promise<'present' | 'absent' | 'maybe'>}
    */
   async exists(namespace, key) {
+    this._guard('exists')
     const result = await this._client.call('cache.exists', { namespace, key })
     return result?.status ?? 'maybe'
   }
@@ -66,6 +93,7 @@ export class CacheClient {
    * @returns {Promise<void>}
    */
   async invalidate(namespace, key) {
+    this._guard('invalidate')
     await this._client.call('cache.invalidate', { namespace, key })
   }
 
@@ -76,6 +104,7 @@ export class CacheClient {
    * @returns {Promise<number>} Number of entries removed.
    */
   async invalidatePrefix(namespace, prefix) {
+    this._guard('invalidatePrefix')
     const result = await this._client.call('cache.invalidate_prefix', { namespace, prefix })
     return result?.removed ?? 0
   }
@@ -87,6 +116,7 @@ export class CacheClient {
    * @returns {Promise<number>} Number of entries removed.
    */
   async invalidateTags(namespace, tags) {
+    this._guard('invalidateTags')
     const result = await this._client.call('cache.invalidate_tags', { namespace, tags })
     return result?.removed ?? 0
   }
@@ -98,6 +128,7 @@ export class CacheClient {
    * @returns {Promise<void>}
    */
   async flushNamespace(namespace) {
+    this._guard('flushNamespace')
     await this._client.call('cache.flush_namespace', { namespace })
   }
 }

package/drivers/js/src/db-helpers.js

@@ -0,0 +1,95 @@
+import { RedDBError } from './protocol.js'
+
+export async function listCollections(db) {
+  const result = await db.query('SHOW COLLECTIONS')
+  return (result.rows ?? []).map(collectionMeta)
+}
+
+export async function collectionExists(db, collection) {
+  const result = await db.query(`SHOW COLLECTIONS WHERE name = ${sqlString(collection)}`)
+  return (result.rows ?? []).some((row) => row.name === String(collection))
+}
+
+export class TypedQueryBuilder {
+  constructor(db, collection, columns = null, whereClauses = [], params = []) {
+    this.db = db
+    this.collection = collection
+    this.columns = columns
+    this.whereClauses = whereClauses
+    this.params = params
+  }
+
+  select(...columns) {
+    const selected = columns.length === 1 && Array.isArray(columns[0]) ? columns[0] : columns
+    const projection = selected.length === 1 && selected[0] === '*' ? null : selected
+    return new TypedQueryBuilder(
+      this.db,
+      this.collection,
+      projection != null && projection.length > 0 ? projection : null,
+      this.whereClauses,
+      this.params,
+    )
+  }
+
+  where(condition, ...params) {
+    if (typeof condition !== 'string' || condition.trim().length === 0) {
+      throw new RedDBError('INVALID_QUERY_BUILDER', 'where() requires a non-empty SQL condition')
+    }
+    const nextParams = params.length === 1 && Array.isArray(params[0]) ? params[0] : params
+    return new TypedQueryBuilder(
+      this.db,
+      this.collection,
+      this.columns,
+      [...this.whereClauses, condition.trim()],
+      [...this.params, ...nextParams],
+    )
+  }
+
+  async run() {
+    const projection = this.columns == null
+      ? '*'
+      : this.columns.map(sqlIdentifierPath).join(', ')
+    const where = this.whereClauses.length > 0
+      ? ` WHERE ${this.whereClauses.map((clause) => `(${clause})`).join(' AND ')}`
+      : ''
+    const sql = `SELECT ${projection} FROM ${sqlIdentifierPath(this.collection)}${where}`
+    const result = this.params.length > 0
+      ? await this.db.query(sql, this.params)
+      : await this.db.query(sql)
+    const rows = result.rows ?? []
+    if (this.columns == null) return rows
+    return rows.map((row) => {
+      const selected = {}
+      for (const column of this.columns) selected[column] = row[column]
+      return selected
+    })
+  }
+}
+
+function collectionMeta(row) {
+  return {
+    ...row,
+    name: String(row.name),
+    model: String(row.model),
+    capabilities: Array.isArray(row.capabilities) ? row.capabilities : [],
+  }
+}
+
+function sqlIdentifierPath(value) {
+  return String(value).split('.').map(sqlIdentifier).join('.')
+}
+
+function sqlIdentifier(value) {
+  const ident = String(value)
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(ident)) {
+    throw new RedDBError(
+      'INVALID_IDENTIFIER',
+      `invalid SQL identifier "${ident}"`,
+    )
+  }
+  return ident
+}
+
+function sqlString(value) {
+  return `'${String(value).replace(/'/g, "''")}'`
+}

package/drivers/js/src/http.js

@@ -123,9 +123,14 @@ async function parseResponse(response) {
 const ROUTES = {
   health: (base) => ({ url: `${base}/health`, init: { method: 'GET' } }),
   version: (base) => ({ url: `${base}/admin/version`, init: { method: 'GET' } }),
-  query: (base, { sql }) => ({
+  query: (base, { sql, params }) => ({
     url: `${base}/query`,
-    init: { method: 'POST', body: JSON.stringify({ query: sql }) },
+    init: {
+      method: 'POST',
+      body: JSON.stringify(
+        Array.isArray(params) ? { query: sql, params } : { query: sql },
+      ),
+    },
   }),
   insert: (base, { collection, payload }) => ({
     url: `${base}/collections/${encodeURIComponent(collection)}/rows`,

package/drivers/js/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/drivers/js/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/drivers/js/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) : []
+}

package/drivers/js/src/redwire.js

@@ -45,6 +45,14 @@ export const MessageKind = Object.freeze({
   BulkInsertBinary: 0x06,
   QueryBinary: 0x07,
   BulkInsertPrevalidated: 0x08,
+  QueryWithParams: 0x28,
+})
+
+export const Features = Object.freeze({ PARAMS: 0x0000_0001 })
+
+export const ValueTag = Object.freeze({
+  Null: 0x00, Bool: 0x01, Int: 0x02, Float: 0x03, Text: 0x04,
+  Bytes: 0x05, Vector: 0x06, Json: 0x07, Timestamp: 0x08, Uuid: 0x09,
 })
 
 /**
@@ -201,8 +209,13 @@ export async function connectRedwire(opts) {
     )
   }
   const session = jsonOf(final.payload) ?? {}
+  const features = numberOr(session.features, numberOr(ackParsed?.features, 0))
 
-  return new RedWireClient(socket, reader, session)
+  return new RedWireClient(socket, reader, session, features)
+}
+
+function numberOr(v, fallback) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : fallback
 }
 
 /**
@@ -211,16 +224,27 @@ export async function connectRedwire(opts) {
  * transports so the surface above this is uniform.
  */
 export class RedWireClient {
-  constructor(socket, reader, session) {
+  constructor(socket, reader, session, serverFeatures = 0) {
     this.socket = socket
     this.reader = reader
     this.session = session
+    this.serverFeatures = serverFeatures >>> 0
     this.nextCorr = 1n
     this.closed = false
   }
 
+  /** Raw advertised server feature bitmask. */
+  features() {
+    return this.serverFeatures
+  }
+
+  /** True when server advertised `FEATURE_PARAMS` (#357). */
+  supportsParams() {
+    return (this.serverFeatures & Features.PARAMS) === Features.PARAMS
+  }
+
   async call(method, params = {}) {
-    if (method === 'query') return this.#query(params.sql ?? '')
+    if (method === 'query') return this.#query(params.sql ?? '', params.params)
     if (method === 'insert') return this.#insert({ collection: params.collection, payload: params.payload })
     if (method === 'bulk_insert') return this.#insert({ collection: params.collection, payloads: params.payloads })
     if (method === 'bulk_insert_binary') {
@@ -308,10 +332,26 @@ export class RedWireClient {
     )
   }
 
-  async #query(sql) {
+  async #query(sql, params) {
     const corr = this.#corr()
-    const payload = new TextEncoder().encode(sql)
-    await writeFrame(this.socket, MessageKind.Query, corr, payload)
+    const hasParams = Array.isArray(params) && params.length > 0
+    let kind
+    let payload
+    if (hasParams) {
+      if (!this.supportsParams()) {
+        throw new RedDBError(
+          'PARAMS_UNSUPPORTED',
+          'server did not advertise FEATURE_PARAMS — upgrade the server '
+            + 'to one that supports parameterized queries.',
+        )
+      }
+      kind = MessageKind.QueryWithParams
+      payload = encodeQueryWithParams(sql, params)
+    } else {
+      kind = MessageKind.Query
+      payload = new TextEncoder().encode(sql)
+    }
+    await writeFrame(this.socket, kind, corr, payload)
     const resp = await this.reader.next()
     if (resp.kind === MessageKind.Result) {
       return jsonOf(resp.payload) ?? {}
@@ -714,6 +754,181 @@ function writeBinaryCell(buf, view, pos, cell, enc) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// QueryWithParams payload codec — mirrors `reddb_wire::query_with_params`
+// ---------------------------------------------------------------------------
+
+const MAX_VALUE_PAYLOAD_LEN = MAX_FRAME_SIZE
+const MAX_PARAM_COUNT = 65_536
+
+/**
+ * Encode the `QueryWithParams` payload body.
+ * Layout: `[u32 sql_len LE][utf-8 sql][u32 param_count LE][N encoded values]`
+ */
+export function encodeQueryWithParams(sql, params) {
+  if (typeof sql !== 'string') throw new TypeError('encodeQueryWithParams: sql must be a string')
+  if (!Array.isArray(params)) throw new TypeError('encodeQueryWithParams: params must be an array')
+  if (params.length > MAX_PARAM_COUNT) {
+    throw new RedDBError('PARAM_COUNT_OVER_LIMIT', `param_count ${params.length} > ${MAX_PARAM_COUNT}`)
+  }
+  const sqlBytes = new TextEncoder().encode(sql)
+  if (sqlBytes.length > MAX_VALUE_PAYLOAD_LEN) {
+    throw new RedDBError('PAYLOAD_TOO_LARGE', `sql_len ${sqlBytes.length} > ${MAX_VALUE_PAYLOAD_LEN}`)
+  }
+  const valueBlobs = params.map(encodeValue)
+  let total = 4 + sqlBytes.length + 4
+  for (const vb of valueBlobs) total += vb.length
+  const buf = new Uint8Array(total)
+  const view = new DataView(buf.buffer)
+  let pos = 0
+  view.setUint32(pos, sqlBytes.length, true); pos += 4
+  buf.set(sqlBytes, pos); pos += sqlBytes.length
+  view.setUint32(pos, valueBlobs.length, true); pos += 4
+  for (const vb of valueBlobs) { buf.set(vb, pos); pos += vb.length }
+  return buf
+}
+
+/**
+ * Encode a single wire `Value`. Mirrors `reddb_wire::value::encode`.
+ *
+ * Accepts native JS values + the JSON envelopes produced by
+ * `serializeParam` so the SDK can pass through a single shape:
+ *   - `null` / `undefined`               → Null
+ *   - `boolean`                          → Bool
+ *   - `bigint`                           → Int (i64)
+ *   - `number` integer (safe range)      → Int; otherwise → Float
+ *   - `string`                           → Text
+ *   - `Uint8Array` / `Buffer`            → Bytes
+ *   - `Float32Array` / `Array<number>`   → Vector (f32)
+ *   - `{ $bytes: <base64> }`             → Bytes
+ *   - `{ $ts: <unix-seconds> }`          → Timestamp
+ *   - `{ $uuid: <hyphenated> }`          → Uuid
+ *   - other plain object/array           → Json (canonical bytes)
+ */
+export function encodeValue(v) {
+  if (v === null || v === undefined) return Uint8Array.of(ValueTag.Null)
+  if (typeof v === 'boolean') return Uint8Array.of(ValueTag.Bool, v ? 1 : 0)
+  if (typeof v === 'bigint') {
+    const out = new Uint8Array(1 + 8)
+    out[0] = ValueTag.Int
+    new DataView(out.buffer).setBigInt64(1, v, true)
+    return out
+  }
+  if (typeof v === 'number') {
+    if (Number.isInteger(v) && v >= -(2 ** 53) && v <= 2 ** 53) {
+      const out = new Uint8Array(1 + 8)
+      out[0] = ValueTag.Int
+      new DataView(out.buffer).setBigInt64(1, BigInt(v), true)
+      return out
+    }
+    const out = new Uint8Array(1 + 8)
+    out[0] = ValueTag.Float
+    new DataView(out.buffer).setFloat64(1, v, true)
+    return out
+  }
+  if (typeof v === 'string') return encodeLenPrefixed(ValueTag.Text, new TextEncoder().encode(v))
+  if (v instanceof Uint8Array) return encodeLenPrefixed(ValueTag.Bytes, v)
+  if (typeof Buffer !== 'undefined' && v instanceof Buffer) {
+    return encodeLenPrefixed(ValueTag.Bytes, new Uint8Array(v.buffer, v.byteOffset, v.byteLength))
+  }
+  if (v instanceof Float32Array) return encodeVector(v)
+  if (v instanceof Float64Array) return encodeVector(Float32Array.from(v))
+  if (Array.isArray(v) && v.every((x) => typeof x === 'number')) {
+    return encodeVector(Float32Array.from(v))
+  }
+  if (typeof v === 'object') {
+    const keys = Object.keys(v)
+    if (keys.length === 1) {
+      const k = keys[0]
+      if (k === '$bytes' && typeof v.$bytes === 'string') {
+        return encodeLenPrefixed(ValueTag.Bytes, base64ToBytes(v.$bytes))
+      }
+      if (k === '$ts' && (
+        (typeof v.$ts === 'number' && Number.isFinite(v.$ts))
+        || typeof v.$ts === 'string'
+      )) {
+        const out = new Uint8Array(1 + 8)
+        out[0] = ValueTag.Timestamp
+        const raw = typeof v.$ts === 'string' ? BigInt(v.$ts) : BigInt(Math.trunc(v.$ts))
+        new DataView(out.buffer).setBigInt64(1, raw, true)
+        return out
+      }
+      if (k === '$uuid' && typeof v.$uuid === 'string') {
+        const bytes = parseUuidHyphenated(v.$uuid)
+        const out = new Uint8Array(1 + 16)
+        out[0] = ValueTag.Uuid
+        out.set(bytes, 1)
+        return out
+      }
+    }
+    return encodeLenPrefixed(ValueTag.Json, new TextEncoder().encode(canonicalJson(v)))
+  }
+  throw new RedDBError('UNSUPPORTED_PARAM', `cannot encode param of type ${typeof v}`)
+}
+
+function encodeLenPrefixed(tag, bytes) {
+  if (bytes.length > MAX_VALUE_PAYLOAD_LEN) {
+    throw new RedDBError('PAYLOAD_TOO_LARGE', `value len ${bytes.length} > ${MAX_VALUE_PAYLOAD_LEN}`)
+  }
+  const out = new Uint8Array(1 + 4 + bytes.length)
+  out[0] = tag
+  new DataView(out.buffer).setUint32(1, bytes.length, true)
+  out.set(bytes, 5)
+  return out
+}
+
+function encodeVector(f32) {
+  if (f32.length * 4 > MAX_VALUE_PAYLOAD_LEN) {
+    throw new RedDBError('PAYLOAD_TOO_LARGE', `vector bytes ${f32.length * 4} > ${MAX_VALUE_PAYLOAD_LEN}`)
+  }
+  const out = new Uint8Array(1 + 4 + f32.length * 4)
+  out[0] = ValueTag.Vector
+  const view = new DataView(out.buffer)
+  view.setUint32(1, f32.length, true)
+  for (let i = 0; i < f32.length; i++) {
+    view.setFloat32(5 + i * 4, f32[i], true)
+  }
+  return out
+}
+
+function base64ToBytes(s) {
+  if (typeof Buffer !== 'undefined') {
+    const b = Buffer.from(s, 'base64')
+    return new Uint8Array(b.buffer, b.byteOffset, b.byteLength)
+  }
+  // eslint-disable-next-line no-undef
+  const bin = atob(s)
+  const out = new Uint8Array(bin.length)
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+  return out
+}
+
+function parseUuidHyphenated(s) {
+  const hex = s.replace(/-/g, '')
+  if (hex.length !== 32 || /[^0-9a-fA-F]/.test(hex)) {
+    throw new RedDBError('UUID_INVALID', `bad uuid: ${s}`)
+  }
+  const out = new Uint8Array(16)
+  for (let i = 0; i < 16; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
+  return out
+}
+
+/** Stable JSON serialization with sorted keys — matches the server's
+ * canonical `crate::json` output so round-tripped Json values compare
+ * byte-equal. */
+function canonicalJson(v) {
+  if (v === null) return 'null'
+  if (typeof v === 'number') return Number.isFinite(v) ? String(v) : 'null'
+  if (typeof v === 'string') return JSON.stringify(v)
+  if (typeof v === 'boolean') return v ? 'true' : 'false'
+  if (Array.isArray(v)) return '[' + v.map(canonicalJson).join(',') + ']'
+  if (typeof v === 'object') {
+    const keys = Object.keys(v).sort()
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(v[k])).join(',') + '}'
+  }
+  return 'null'
+}
+
 function jsonReason(bytes) {
   const v = jsonOf(bytes)
   if (v && typeof v === 'object' && typeof v.reason === 'string') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reddb-io/cli",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "CLI launcher for RedDB. The JS/TS app driver is published as @reddb-io/sdk.",
   "type": "commonjs",
   "bin": {