@reddb-io/sdk 1.0.5 → 1.0.8

package/index.d.ts

@@ -224,6 +224,7 @@ export class RedDB {
   readonly vault: (collection?: string) => VaultClient
 
   query(sql: string): Promise<QueryResult>
+  query(sql: string, params: Array<number | string | null>): Promise<QueryResult>
   insert(collection: string, payload: Record<string, unknown>): Promise<InsertResult>
   bulkInsert(
     collection: string,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reddb-io/sdk",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "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.",
   "type": "module",
   "main": "src/index.js",
@@ -45,6 +45,6 @@
   },
   "scripts": {
     "postinstall": "node postinstall.js",
-    "test": "node --test test/cache.test.mjs && node test/smoke.test.mjs"
+    "test": "node --test test/cache.test.mjs test/params.test.mjs test/redwire.params.test.mjs && node test/smoke.test.mjs"
   }
 }

package/postinstall.js

@@ -18,7 +18,7 @@
 
 import { createRequire } from 'node:module'
 import { fileURLToPath } from 'node:url'
-import { dirname, join } from 'node:path'
+import { dirname, join, sep } from 'node:path'
 import { existsSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs'
 
 import { fetchReleaseAsset } from './src/internal/asset-fetcher/index.js'
@@ -34,16 +34,66 @@ if (process.env.REDDB_SKIP_POSTINSTALL === '1') {
   process.exit(0)
 }
 
-main().catch((err) => {
-  process.stderr.write(
-    `reddb: postinstall could not download the binary (${err.message}).\n` +
-      `       The package will still install. To use the driver you can:\n` +
-      `         - set REDDB_BINARY_PATH=/path/to/red\n` +
-      `         - or install the binary manually from https://github.com/${DEFAULT_REPO}/releases\n`,
+// Workspace-local install detection. When this file's resolved path is not
+// inside a `node_modules` tree we're running from a fresh checkout of the
+// reddb monorepo (or a fork), where `package.json` may already carry a
+// version whose GitHub Release has not been built yet — and where the
+// developer typically builds `red` with `cargo build` anyway. Skip the
+// download with a clear pointer; release flows still work because the npm
+// tarball, when installed, lives under `node_modules/`.
+if (!HERE.includes(`${sep}node_modules${sep}`)) {
+  process.stdout.write(
+    'reddb: skipping postinstall — running from a workspace checkout (no node_modules/).\n' +
+    '       If you need the binary, either:\n' +
+    '         - cargo build --release --bin red  &&  export REDDB_BIN="$PWD/target/release/red"\n' +
+    '         - or:  curl -fsSL https://raw.githubusercontent.com/reddb-io/reddb/main/install.sh | bash\n' +
+    '       Set REDDB_SKIP_POSTINSTALL=1 to silence this message.\n',
   )
   process.exit(0)
+}
+
+main().catch((err) => {
+  process.stderr.write(formatFailure(err))
+  process.exit(0)
 })
 
+function formatFailure(err) {
+  const repo = process.env.REDDB_POSTINSTALL_REPO || DEFAULT_REPO
+  if (err && err.code === 'UNSUPPORTED_PLATFORM') {
+    return (
+      `reddb: no prebuilt red binary for ${process.platform}/${process.arch}.\n` +
+      `       Options:\n` +
+      `         - build from source: https://github.com/${repo}#build-from-source\n` +
+      `         - or set REDDB_BIN=/path/to/red to point at one you compiled.\n`
+    )
+  }
+  if (err && err.code === 'ASSET_NOT_FOUND') {
+    return (
+      `reddb: release asset not found at ${err.url}\n` +
+      `       Common cause: the GitHub Release for this SDK version has not\n` +
+      `       been published yet (or your platform's binary was not produced\n` +
+      `       for that release). To unblock without reinstalling:\n` +
+      `         1. Install the latest stable red via the official installer\n` +
+      `            and point the SDK at it:\n` +
+      `              curl -fsSL https://raw.githubusercontent.com/${repo}/main/install.sh | bash\n` +
+      `              export REDDB_BIN="$(command -v red)"\n` +
+      `         2. Or pull a specific tag explicitly and re-run postinstall:\n` +
+      `              REDDB_POSTINSTALL_VERSION=v1.0.5 npm rebuild @reddb-io/sdk\n` +
+      `         3. Or skip the download entirely and provide the binary yourself:\n` +
+      `              REDDB_SKIP_POSTINSTALL=1 (re-install), then export REDDB_BIN=…\n` +
+      `       Releases: https://github.com/${repo}/releases\n`
+    )
+  }
+  return (
+    `reddb: postinstall could not download the binary (${err && err.message}).\n` +
+    `       The package itself still installs. To use the driver:\n` +
+    `         - run the installer: curl -fsSL https://raw.githubusercontent.com/${repo}/main/install.sh | bash\n` +
+    `           then: export REDDB_BIN="$(command -v red)"\n` +
+    `         - or download manually from https://github.com/${repo}/releases\n` +
+    `         - or set REDDB_BIN=/path/to/red.\n`
+  )
+}
+
 async function main() {
   const repo = process.env.REDDB_POSTINSTALL_REPO || DEFAULT_REPO
   const tag = process.env.REDDB_POSTINSTALL_VERSION

package/src/index.js

@@ -167,6 +167,17 @@ export async function connect(uri, options = {}) {
   )
 }
 
+// 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)
+  }
+  return value
+}
+
 function embeddedArgs(parsed) {
   if (parsed.path) return ['rpc', '--stdio', '--path', parsed.path]
   return ['rpc', '--stdio']
@@ -344,9 +355,27 @@ export class RedDB {
     this.vault = (collection = 'red.vault') => new VaultClient(client, collection)
   }
 
-  /** Execute a SQL query. Returns `{ statement, affected, columns, rows }`. */
-  query(sql) {
-    return this.client.call('query', { sql })
+  /**
+   * Execute a SQL query.
+   *
+   * 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.
+   *
+   * Returns `{ statement, affected, columns, rows }`.
+   */
+  query(sql, params) {
+    if (params === undefined) {
+      return this.client.call('query', { sql })
+    }
+    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 })
   }
 
   /** Insert one row. Returns `{ affected, id? }`. */

package/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,177 @@ 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)) {
+        const out = new Uint8Array(1 + 8)
+        out[0] = ValueTag.Timestamp
+        new DataView(out.buffer).setBigInt64(1, BigInt(Math.trunc(v.$ts)), 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') {