@reddb-io/client-bun 1.23.2 → 1.24.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @reddb-io/client-bun
 
+## 1.24.0
+
+## 1.23.4
+
+## 1.23.3
+
 ## 1.23.2
 
 ## 1.23.1

package/README.md

@@ -0,0 +1,64 @@
+# Bun RedWire client
+
+```ts
+import { connect } from '@reddb-io/client-bun'
+
+const db = await connect('127.0.0.1:6380')
+try {
+  const result = await db.queryParsed('SELECT id,name FROM users WHERE id=$1', [1])
+  console.log(result.result.records.map(record => record.values))
+} finally {
+  db.close()
+}
+```
+
+On servers advertising `FEATURE_PARAMS`, bound and unbound queries both return
+the canonical query envelope: records are at `result.records`, write counts at
+`affected_rows` (when nonzero), and the command at `statement_type` (for writes).
+`query()` returns its JSON string; `queryParsed()` parses it. This also applies
+to `query(sql, [])`. Previously unbound queries returned only a summary, which
+omitted records; consumers of that summary must update their field paths.
+
+Older servers without `FEATURE_PARAMS` retain the legacy summary response for
+unbound queries. Binding values to such servers raises `PARAMS_UNSUPPORTED`.
+
+Run the shared SDK smoke test and this package's actual TCP-client regression:
+
+```sh
+REDDB_BINARY_PATH=/absolute/path/to/red bun run test
+```
+
+<!-- contract-matrix:begin -->
+## Public-surface support
+
+> Generated from [`docs/conformance/public-surface-contract-matrix.json`](/docs/conformance/public-surface-contract-matrix.json) by `scripts/gen-docs-from-matrix.mjs`. Do not edit between the markers by hand — run `node scripts/gen-docs-from-matrix.mjs --write`. The matrix is the source of truth; this block can never claim more than it, and CI (`docs-matrix`) fails on drift.
+>
+> Driver-helper (SDK Helper Spec v1.0) support for every public promise. A helper not marked supported here is not promised by this driver.
+
+| Promise | driver_helpers |
+| --- | --- |
+| **PSC-001** — RedDB is one multi-model database (tables, graph, KV, timeseries, probabilistic, vector, queue, documents) backed by a single file. | ✅ supported |
+| **PSC-002** — MATCH supports node, edge, label, property, and LIMIT projections. | ✅ supported |
+| **PSC-003** — GRAPH algorithms accept semantic identifiers, limits, ordering, and return stable rich rows. | ❌ unsupported |
+| **PSC-004** — INSERT creates rows, documents, and native timeseries points. | ✅ supported |
+| **PSC-005** — HLL/SKETCH/FILTER expose write and read commands for cardinality, frequency, and membership. | ⚠️ partial |
+| **PSC-006** — Timeseries stores timestamped metrics with tags and supports query/readback. | ⚠️ partial |
+| **PSC-007** — Documents are first-class: create, read, update, delete, and SQL analytics over JSON. | ✅ supported |
+| **PSC-008** — KV helpers expose get/put/delete; get of a missing key returns null, delete reports affected. | ✅ supported |
+| **PSC-009** — Queue helpers expose create/push/peek/pop/len/purge with FIFO semantics; empty pop is not an error. | ✅ supported |
+| **PSC-010** — Transactions are imperative (begin/commit/rollback) plus a run(callback) form; empty SQL rejects with INVALID_ARGUMENT. | ✅ supported |
+| **PSC-011** — SQL aggregate, projection, expression, and mutation behaviour matches ordinary SQL expectations where advertised. | ✅ supported |
+| **PSC-012** — Server transports expose the same query contract as embedded (HTTP, RedWire, gRPC parity). | ✅ supported |
+| **PSC-013** — Official drivers implement the SDK Helper Spec v1.0 conformance suite (all 22 §12 case IDs). | ✅ supported |
+| **PSC-014** — ASK / SEARCH semantic surfaces return ranked results with stable shape. | ⚠️ partial |
+
+_Status legend: ✅ supported · ⚠️ partial (known gaps) · ❌ unsupported._
+<!-- contract-matrix:end -->
+
+## SQL quotation compatibility
+
+SQL double quotes delimit identifiers; single quotes delimit text. For example,
+`SELECT "title" FROM articles WHERE author = 'alice'` reads the `title` column.
+Bind application values as parameters. JSON object/array strings keep double
+quotes. See the [SQL quotation migration guide](../../docs/query/sql-quoting.md)
+before upgrading applications that used double-quoted SQL text literals.

package/index.ts

@@ -144,15 +144,18 @@ export class RedDBConnection {
   async query(sql: string, ...params: unknown[]): Promise<string> {
     const wireParams = normalizeQueryParams(params)
     const hasParams = wireParams.length > 0
-    if (hasParams && !this.supportsParams()) {
+    const fullResult = this.supportsParams()
+    if (hasParams && !fullResult) {
       throw new RedDBError(
         'PARAMS_UNSUPPORTED',
         'server did not advertise FEATURE_PARAMS; upgrade the server',
       )
     }
+    // Legacy Query returns a summary only. Capable servers return rows via
+    // QueryWithParams even when the parameter vector is empty.
     const resp = await this._send(
-      hasParams ? MSG_QUERY_WITH_PARAMS : MSG_QUERY,
-      hasParams
+      fullResult ? MSG_QUERY_WITH_PARAMS : MSG_QUERY,
+      fullResult
         ? encodeQueryWithParams(sql, wireParams)
         : Buffer.from(sql, 'utf8'),
     )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reddb-io/client-bun",
-  "version": "1.23.2",
+  "version": "1.24.0",
   "description": "RedDB wire protocol client for Bun — ultra-fast native TCP",
   "main": "index.ts",
   "license": "MIT",
@@ -12,6 +12,6 @@
     "wire-protocol"
   ],
   "scripts": {
-    "test": "bun run params.test.ts"
+    "test": "bun run params.test.ts && bun run wire-legacy.test.ts && bun run wire.test.ts"
   }
 }

package/params.test.ts

@@ -55,6 +55,17 @@ try {
   assert(Array.isArray(similar.rows), 'SEARCH rows should be an array')
   assertEqual(similar.rows.length, 1, 'SEARCH should match one vector row')
   assertEqual(similar.rows[0].score, 1, 'SEARCH should bind Float32Array vector')
+
+  const fractional = new Float32Array([0.8, 0.6])
+  await db.query('INSERT INTO fractional_vectors VECTOR (dense, content) VALUES ($1, $2)',
+    [fractional, 'fractional embedding'])
+  const fractionalMatch = await db.query('SEARCH SIMILAR $1 COLLECTION fractional_vectors LIMIT 1',
+    [fractional])
+  assertEqual(fractionalMatch.rows.length, 1, 'fractional vector should remain searchable')
+  assert(Math.abs(fractionalMatch.rows[0].score - 1) < 1e-6, 'identical fractional vectors should match')
+  const axisMatch = await db.query('SEARCH SIMILAR $1 COLLECTION fractional_vectors LIMIT 1',
+    [new Float32Array([1, 0])])
+  assert(Math.abs(axisMatch.rows[0].score - 0.8) < 1e-6, 'fractional coordinates survive binding')
 } finally {
   await db.close()
 }

package/wire-legacy.test.ts

@@ -0,0 +1,66 @@
+import { strict as assert } from 'node:assert'
+import { createServer } from 'node:net'
+import { connect, RedDBError } from './index'
+
+// The old protocol is intentionally summary-only. A small protocol peer lets
+// us exercise capability negotiation without installing an obsolete engine.
+const queries: number[] = []
+const server = createServer((socket) => {
+  socket.setTimeout(5_000, () => socket.destroy())
+  let input = Buffer.alloc(0)
+  let magicReceived = false
+  socket.on('data', (chunk) => {
+    input = Buffer.concat([input, chunk])
+    if (!magicReceived) {
+      if (input.length < 2) return
+      assert.deepEqual([...input.subarray(0, 2)], [0xfe, 1])
+      input = input.subarray(2)
+      magicReceived = true
+    }
+    while (input.length >= 16) {
+      const length = input.readUInt32LE(0)
+      assert(length >= 16 && length <= 16 * 1024 * 1024)
+      if (input.length < length) return
+      const frame = input.subarray(0, length)
+      input = input.subarray(length)
+      const kind = frame[4]
+      if (kind === 0x16) { socket.end(); return }
+      let responseKind: number
+      let body: object
+      if (kind === 0x10) {
+        responseKind = 0x11
+        body = { auth: 'anonymous', features: 0 }
+      } else if (kind === 0x13) {
+        responseKind = 0x14
+        body = { features: 0 }
+      } else {
+        queries.push(kind)
+        responseKind = 0x02
+        body = { ok: true, affected: 0, statement: 'select' }
+      }
+      const payload = Buffer.from(JSON.stringify(body))
+      const response = Buffer.alloc(16 + payload.length)
+      response.writeUInt32LE(response.length, 0)
+      response[4] = responseKind
+      frame.copy(response, 8, 8, 16)
+      payload.copy(response, 16)
+      socket.write(response)
+    }
+  })
+})
+await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+const address = server.address()
+assert(address && typeof address === 'object')
+let db: Awaited<ReturnType<typeof connect>> | undefined
+try {
+  db = await connect(`127.0.0.1:${address.port}`)
+  assert.equal(db.supportsParams(), false)
+  assert.deepEqual(await db.queryParsed('SELECT 42'), { ok: true, affected: 0, statement: 'select' })
+  await assert.rejects(db.query('SELECT $1', [42]),
+    (error) => error instanceof RedDBError && error.code === 'PARAMS_UNSUPPORTED')
+  assert.deepEqual(queries, [0x01])
+  console.log('ok Bun legacy capability fallback')
+} finally {
+  db?.close()
+  await new Promise<void>((resolve) => server.close(() => resolve()))
+}

package/wire.test.ts

@@ -0,0 +1,58 @@
+import { strict as assert } from 'node:assert'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { createServer } from 'node:net'
+import { connect } from './index'
+
+// Exercise this package's TCP client against a real server. An absent binary
+// is a test failure: silently skipping hid the unbound-query regression.
+const binary = process.env.REDDB_BINARY_PATH || resolve(import.meta.dir, '../../target/debug/red')
+const reservation = createServer()
+await new Promise<void>((resolve, reject) => {
+  reservation.once('error', reject)
+  reservation.listen(0, '127.0.0.1', resolve)
+})
+const address = reservation.address()
+assert(address && typeof address === 'object')
+const endpoint = `127.0.0.1:${address.port}`
+await new Promise<void>((resolve) => reservation.close(() => resolve()))
+const directory = mkdtempSync(join(tmpdir(), 'reddb-bun-wire-'))
+const server = Bun.spawn([binary, 'server', '--path', join(directory, 'db.rdb'),
+  '--bind', endpoint, '--no-auth', '--no-log-file'], { stdout: 'ignore', stderr: 'inherit' })
+let db: Awaited<ReturnType<typeof connect>> | undefined
+try {
+  const deadline = Date.now() + 30_000
+  while (Date.now() < deadline) {
+    if (server.exitCode !== null) throw new Error(`server exited ${server.exitCode}`)
+    try {
+      const response = await fetch(`http://${endpoint}/health`, { signal: AbortSignal.timeout(500) })
+      if (response.ok) break
+    } catch {}
+    await Bun.sleep(100)
+  }
+  db = await connect(endpoint)
+  assert(db.supportsParams())
+  await db.query('CREATE TABLE wire_rows (id INTEGER, name TEXT)')
+  const inserted = await db.queryParsed("INSERT INTO wire_rows (id,name) VALUES (1,'Bun')")
+  assert.equal(inserted.affected_rows, 1)
+  const unbound = await db.queryParsed('SELECT id,name FROM wire_rows')
+  const bound = await db.queryParsed('SELECT id,name FROM wire_rows WHERE id=$1', [1])
+  assert.deepEqual(unbound.result.records.map((record: any) => record.values), [{ id: 1, name: 'Bun' }])
+  assert.deepEqual(unbound.result.records.map((record: any) => record.values), bound.result.records.map((record: any) => record.values))
+  assert.deepEqual((await db.queryParsed('SELECT id,name FROM wire_rows', [])).result.records.map((record: any) => record.values), bound.result.records.map((record: any) => record.values))
+  assert.deepEqual((await db.queryParsed('SELECT id FROM wire_rows WHERE id=2')).result.records, [])
+  await assert.rejects(db.query('SELECT * FROM absent_wire_table'))
+  const cli = Bun.spawnSync([binary, 'query', '--bind', endpoint, '--json',
+    "INSERT INTO wire_rows (id,name) VALUES (2,'CLI')"])
+  assert.equal(cli.exitCode, 0, cli.stderr.toString())
+  const insertedByCli = JSON.parse(cli.stdout.toString()).data
+  assert.equal(insertedByCli.affected, 1)
+  assert.equal(insertedByCli.statement, 'insert')
+  console.log('ok Bun wire bound/unbound result contract')
+} finally {
+  db?.close()
+  server.kill()
+  await server.exited
+  rmSync(directory, { recursive: true, force: true })
+}