@reddb-io/sdk 1.2.5 → 1.4.0

package/README.md

@@ -87,9 +87,11 @@ For the SQL/RQL grammar that `db.query()` accepts, see
 
 ## Transactions
 
-Use `db.transaction()` when a group of writes must commit or roll back together.
-The callback receives a transaction handle with the same `query`, `insert`, and
-`bulkInsert` methods as `db`.
+This driver supports **both** transaction forms from the SDK Helper Spec
+(§7): the imperative `begin` / `commit` / `rollback` trio and the callback
+form.
+
+**Callback form** — `db.transaction(callback)` (or `db.tx().run(callback)`):
 
 ```js
 const userId = await db.transaction(async (tx) => {
@@ -100,9 +102,28 @@ const userId = await db.transaction(async (tx) => {
 ```
 
 The wrapper sends `BEGIN`, commits when the callback resolves, and rolls back
-when the callback or a `tx.query()` / `tx.insert()` call throws. Nested
-transactions on the same connection are rejected with `NESTED_TX_NOT_SUPPORTED`;
-open another `connect()` handle for independent concurrent transactions.
+when the callback or a `tx.query()` / `tx.insert()` call throws.
+
+**Imperative form** — `db.tx()` returns a transaction handle:
+
+```js
+const tx = db.tx()
+await tx.begin()
+try {
+  await db.query("INSERT INTO audit (action) VALUES ('created user')")
+  await tx.commit()
+} catch (err) {
+  await tx.rollback()
+  throw err
+}
+```
+
+`begin` / `commit` / `rollback` each resolve to a `QueryResult`. A nested
+`tx.run()` (or `db.transaction()`) on the same connection is rejected with
+`INVALID_ARGUMENT` (`NESTED_TX_NOT_SUPPORTED` for the legacy
+`db.transaction()` shortcut) — callers wanting savepoints issue them
+directly via `tx.query()`. Open another `connect()` handle for independent
+concurrent transactions.
 
 ## Connection URIs
 
@@ -201,8 +222,10 @@ const updated = await db.documents.patch('events', inserted.rid, {
 await db.documents.delete('events', inserted.rid)
 ```
 
-`documents.insert()` creates the document collection when needed. Patch support
-currently accepts top-level document fields.
+`documents.insert()` creates the document collection when needed. Patch is a
+top-level merge: unrelated fields survive. An empty patch raises
+`INVALID_ARGUMENT`. `documents.delete` returns `{ affected, deleted }` and
+NEVER raises on a missing rid (returns `{ affected: 0, deleted: false }`).
 
 ### `db.kv(collection?)`
 
@@ -212,26 +235,104 @@ KV helpers preserve exact keys, including namespaced keys with `:`.
 await db.query('CREATE KV settings')
 const kv = db.kv('settings')
 
-await kv.put('characters:hansel', 'crumbs')
-await kv.get('characters:hansel')        // 'crumbs'
+await kv.set('characters:hansel', 'crumbs')  // `put` is a back-compat alias
+await kv.get('characters:hansel')        // 'crumbs'   (null when missing)
 await kv.exists('characters:hansel')     // { exists: true }
 await kv.list({ prefix: 'characters:' }) // { items: [{ key, value }] }
-await kv.delete('characters:hansel')     // { affected }
+await kv.delete('characters:hansel')     // { affected, deleted }
 ```
 
-### `db.queue`
+A `kv.get` of a missing key returns `null` (never `NOT_FOUND`). `kv.delete`
+returns the `{ affected, deleted }` envelope; deleting a missing key is not an
+error and returns `{ affected: 0, deleted: false }`.
 
-Queue helpers cover the embedded FIFO workflow:
+### `db.queues` (alias `db.queue`)
+
+Queue helpers cover the embedded FIFO workflow. The spec-canonical namespace
+is the plural `db.queues`; `db.queue` remains as an alias.
+
+```js
+await db.queues.create('jobs')           // CREATE QUEUE IF NOT EXISTS (idempotent)
+await db.queues.push('jobs', { task: 'ship' })
+await db.queues.peek('jobs')             // does NOT decrement length
+await db.queues.pop('jobs')              // empty queue → [] (never NOT_FOUND)
+await db.queues.len('jobs')
+await db.queues.purge('jobs')
+```
+
+## SDK Helper Spec conformance
+
+This driver implements **SDK Helper Spec v1.0**
+([`docs/spec/sdk-helpers.md`](../../docs/spec/sdk-helpers.md)). The version is
+exposed for cross-driver CI dashboards:
 
 ```js
-await db.query('CREATE QUEUE jobs')
-await db.queue.push('jobs', { task: 'ship' })
-await db.queue.peek('jobs')
-await db.queue.pop('jobs')
-await db.queue.len('jobs')
-await db.queue.purge('jobs')
+import { HELPER_SPEC_VERSION } from '@reddb-io/sdk'
+HELPER_SPEC_VERSION   // '1.0'
+db.helperSpecVersion  // '1.0'
+```
+
+**Return envelopes** (wire field names preserved when serialised to JSON):
+
+| Envelope            | Fields                                            |
+|---------------------|---------------------------------------------------|
+| `QueryResult`       | `statement`, `affected`, `columns`, `rows`        |
+| `InsertResult`      | `affected` (1), `rid` (`id` legacy alias)         |
+| `BulkInsertResult`  | `affected`, `rids` in input order (`ids` alias)   |
+| `DeleteResult`      | `affected`, `deleted` (= `affected > 0`)          |
+| `ExistsResult`      | `exists`                                          |
+
+**Transaction support:** imperative (`db.tx().begin/commit/rollback`) **and**
+callback (`db.transaction(cb)` / `db.tx().run(cb)`). Nested callbacks reject
+with `INVALID_ARGUMENT`.
+
+**Case matrix** (spec §12 — ported verbatim in
+`test/conformance.test.mjs`):
+
+| Case ID                              | Status      |
+|--------------------------------------|-------------|
+| `meta.spec_version`                  | supported   |
+| `generic.query.no_params`            | supported   |
+| `generic.query_with.params`          | supported   |
+| `generic.insert.rid`                 | supported   |
+| `generic.bulk_insert.rids`           | supported   |
+| `generic.delete`                     | supported   |
+| `documents.crud_nested_patch`        | supported   |
+| `documents.delete_missing_no_error`  | supported   |
+| `documents.patch_empty_rejects`      | supported   |
+| `kv.exact_key_round_trip`            | supported   |
+| `kv.missing_get_returns_none`        | supported   |
+| `kv.delete_returns_envelope`         | supported   |
+| `queues.fifo_peek_pop_len`           | supported   |
+| `queues.empty_pop_returns_empty`     | supported   |
+| `queues.purge_resets_len`            | supported   |
+| `tx.commit_persists`                 | supported   |
+| `tx.rollback_discards`               | supported   |
+| `errors.invalid_argument.empty_sql`  | supported   |
+| `errors.not_found.document_get`      | supported   |
+| `wire.probabilistic.hll_round_trip`  | provisional (SQL via `db.query`) |
+| `wire.vectors.sql_round_trip`        | reachable via `db.query` (no v1.0 case) |
+| `wire.graph.sql_round_trip`          | reachable via `db.query` (no v1.0 case) |
+| `wire.timeseries.sql_round_trip`     | reachable via `db.query` (no v1.0 case) |
+
+**Out-of-scope in v1.0** (reach via raw `db.query` until v1.1, per spec):
+first-class `vectors.*`, `graph.*`, `timeseries.*`, and `probabilistic.*`
+helpers; KV TTL (`kv.expire`) and gRPC watch; priority queues, consumer
+groups, dead-letter routing; transaction isolation-level arguments and
+cross-shard transactions; JSON Patch / nested / array-positional document
+patches (top-level merge only).
+
+Run the conformance harness against a locally built binary:
+
+```sh
+cargo build                                   # produces target/debug/red
+node drivers/js/test/conformance.test.mjs
+# or: REDDB_BINARY_PATH=/path/to/red node drivers/js/test/conformance.test.mjs
 ```
 
+The harness (and the README-examples test) self-skip with exit 0 when no
+binary is present, so `pnpm test` stays green on machines without a build.
+
 ### `db.health() → Promise<{ ok, version }>`
 
 ### `db.version() → Promise<{ version, protocol }>`
@@ -318,3 +419,30 @@ remote URIs.
 - **TLS posture, mTLS, OAuth/JWT and reverse-proxy patterns** are
   covered in [`docs/security/transport-tls.md`](../../docs/security/transport-tls.md).
 - See [Policies](../../docs/security/policies.md) for IAM-style authorization.
+
+<!-- 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 -->

package/index.d.ts

@@ -105,6 +105,8 @@ export interface GetResult {
 
 export interface DeleteResult {
   affected: number
+  /** `affected > 0`. Present on `documents.delete` / `kv.delete` (spec §2.4). */
+  deleted?: boolean
 }
 
 export interface CollectionMeta {
@@ -233,6 +235,12 @@ export class KvClient {
     value: unknown,
     options?: { collection?: string; expireMs?: number; tags?: string[] },
   ): Promise<QueryResult>
+  /** Spec-canonical alias for `put` (spec §5.1 `kv.set`). */
+  set(
+    key: string,
+    value: unknown,
+    options?: { collection?: string; expireMs?: number; tags?: string[] },
+  ): Promise<QueryResult>
   get(key: string, options?: { collection?: string }): Promise<unknown | null>
   getMany(keys: string[], options?: { collection?: string }): Promise<Array<unknown | null>>
   exists(key: string, options?: { collection?: string }): Promise<{ exists: boolean }>
@@ -279,6 +287,8 @@ export class DocumentClient {
 }
 
 export class QueueClient {
+  /** Idempotent CREATE QUEUE IF NOT EXISTS (spec §6.1). */
+  create(queue: string): Promise<QueryResult>
   push(
     queue: string,
     value: unknown,
@@ -290,6 +300,19 @@ export class QueueClient {
   purge(queue: string): Promise<QueryResult>
 }
 
+/**
+ * Spec §7 transaction client returned by `db.tx()`. Imperative
+ * `begin`/`commit`/`rollback` each resolve to a `QueryResult`; `run` is the
+ * callback form (commit on success, rollback + re-throw on failure). Nested
+ * `run` rejects with `INVALID_ARGUMENT`.
+ */
+export class TxClient {
+  begin(): Promise<QueryResult>
+  commit(): Promise<QueryResult>
+  rollback(): Promise<QueryResult>
+  run<T>(callback: (tx: RedDBTransaction) => T | Promise<T>): Promise<T>
+}
+
 /**
  * Caller-typed SELECT builder. RedDB does not infer `T`; provide it
  * explicitly with `db.from<T>('collection')`.
@@ -349,8 +372,12 @@ export interface RedDBTransaction {
 export class RedDB {
   /** Underlying transport label. connect() returns 'embedded'. */
   readonly transport: string | null
+  /** SDK Helper Spec version this driver implements (spec §14). */
+  readonly helperSpecVersion: string
   readonly cache: CacheClient
   readonly queue: QueueClient
+  /** Spec-canonical plural alias for `queue` (spec §6). */
+  readonly queues: QueueClient
   readonly documents: DocumentClient
   readonly kv: KvClient & ((collection?: string) => KvClient)
   readonly config: (collection?: string) => ConfigClient
@@ -371,6 +398,8 @@ export class RedDB {
   transaction<T>(
     callback: (tx: RedDBTransaction) => T | Promise<T>,
   ): Promise<T>
+  /** Spec §7 transaction handle: imperative begin/commit/rollback + run(). */
+  tx(): TxClient
   exists(collection: string): Promise<boolean>
   list(): Promise<CollectionMeta[]>
   /**
@@ -409,6 +438,9 @@ export function connect(uri: string, options?: ConnectOptions): Promise<RedDB>
 
 export const EMBEDDED_ONLY_MESSAGE: string
 
+/** SDK Helper Spec version implemented by this driver (spec §14). */
+export const HELPER_SPEC_VERSION: string
+
 /**
  * Translate a connection URI + (optional) auth into argv for
  * `red rpc --stdio`. Remote URI schemes throw `EMBEDDED_ONLY`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reddb-io/sdk",
-  "version": "1.2.5",
+  "version": "1.4.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",
@@ -45,6 +45,6 @@
   },
   "scripts": {
     "postinstall": "node postinstall.js",
-    "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 test/transaction.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/helpers.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 test/transaction.test.mjs && node test/smoke.test.mjs && node test/conformance.test.mjs && node test/readme-examples.test.mjs"
   }
 }

package/src/db-helpers.js

@@ -50,7 +50,7 @@ export class TypedQueryBuilder {
       ? '*'
       : this.columns.map(sqlIdentifierPath).join(', ')
     const where = this.whereClauses.length > 0
-      ? ` WHERE ${this.whereClauses.join(' AND ')}`
+      ? ` WHERE ${this.whereClauses.map((clause) => `(${clause})`).join(' AND ')}`
       : ''
     const sql = `SELECT ${projection} FROM ${sqlIdentifierPath(this.collection)}${where}`
     const result = this.params.length > 0

package/src/documents.js

@@ -40,7 +40,10 @@ export class DocumentClient {
     validateObject(patch, 'documents.patch patch')
     const entries = Object.entries(patch)
     if (entries.length === 0) {
-      return this.get(collection, rid)
+      throw new RedDBError(
+        'INVALID_ARGUMENT',
+        'documents.patch patch must be a non-empty object',
+      )
     }
     for (const [field] of entries) {
       if (field.includes('/')) {
@@ -66,7 +69,8 @@ export class DocumentClient {
 
   async delete(collection, rid) {
     const result = await this.db.delete(collection, rid)
-    return { affected: result.affected ?? 0 }
+    const affected = result.affected ?? 0
+    return { affected, deleted: affected > 0 }
   }
 
   async ensureCollection(collection) {

package/src/index.js

@@ -43,6 +43,13 @@ 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'
 
+/**
+ * SDK Helper Spec version this driver implements. See
+ * `docs/spec/sdk-helpers.md` §14 — every official driver exposes this so
+ * cross-driver CI dashboards can assert against it.
+ */
+export const HELPER_SPEC_VERSION = '1.0'
+
 const MIN_INSERT_ID_ENGINE_VERSION = '1.0.9'
 const NESTED_TX_NOT_SUPPORTED = 'NESTED_TX_NOT_SUPPORTED'
 
@@ -304,6 +311,92 @@ class TransactionHandle {
   }
 }
 
+/**
+ * Spec §7 transaction client. Returned by `db.tx()`. Exposes the imperative
+ * `begin` / `commit` / `rollback` trio (each resolves to a `QueryResult`) plus
+ * the optional `run(callback)` form. Transaction state is tracked on the parent
+ * `RedDB` so it serialises with `db.transaction()` and nested opens are
+ * rejected rather than silently interleaved.
+ */
+export class TxClient {
+  constructor(db) {
+    this.db = db
+    this.active = false
+  }
+
+  async begin() {
+    if (this.db.inTransaction) {
+      throw nestedTransactionError()
+    }
+    this.db.inTransaction = true
+    this.active = true
+    try {
+      return await this.db.query('BEGIN')
+    } catch (err) {
+      this.db.inTransaction = false
+      this.active = false
+      throw err
+    }
+  }
+
+  async commit() {
+    if (!this.active) {
+      throw new RedDBError('INVALID_ARGUMENT', 'tx.commit() called without an open transaction')
+    }
+    try {
+      return await this.db.query('COMMIT')
+    } finally {
+      this.active = false
+      this.db.inTransaction = false
+    }
+  }
+
+  async rollback() {
+    if (!this.active) {
+      throw new RedDBError('INVALID_ARGUMENT', 'tx.rollback() called without an open transaction')
+    }
+    try {
+      return await this.db.query('ROLLBACK')
+    } finally {
+      this.active = false
+      this.db.inTransaction = false
+    }
+  }
+
+  /**
+   * Callback form: commit on success, roll back and re-throw on failure.
+   * Nested `tx.run` rejects with `INVALID_ARGUMENT` — callers wanting
+   * savepoints issue them directly via `tx.query()` (spec §7.2; the README
+   * records this choice).
+   */
+  async run(callback) {
+    if (typeof callback !== 'function') {
+      throw new TypeError('tx.run(callback) requires a function')
+    }
+    if (this.db.inTransaction) {
+      throw new RedDBError(
+        'INVALID_ARGUMENT',
+        'nested tx.run() is not supported; issue savepoints via tx.query() instead',
+      )
+    }
+    await this.begin()
+    try {
+      const result = await callback(new TransactionHandle(this.db))
+      await this.commit()
+      return result
+    } catch (err) {
+      if (this.active) {
+        try {
+          await this.rollback()
+        } catch (rollbackErr) {
+          attachRollbackError(err, rollbackErr)
+        }
+      }
+      throw err
+    }
+  }
+}
+
 export class RedDB {
   /**
    * @param {RpcClient} client
@@ -315,8 +408,12 @@ export class RedDB {
   constructor(client, opts = {}) {
     this.client = client
     this.transport = opts.transport ?? null
+    this.helperSpecVersion = HELPER_SPEC_VERSION
     this.cache = new CacheClient(client, this.transport)
     this.queue = new QueueClient(client)
+    // Spec §6: the canonical namespace is the plural `queues`. `queue` is kept
+    // as a back-compat alias to the same handle.
+    this.queues = this.queue
     this.documents = new DocumentClient(this)
     const defaultKv = new KvClient(client)
     this.kv = Object.assign((collection = 'kv_default') => new KvClient(client, collection), {
@@ -341,6 +438,13 @@ export class RedDB {
    * Returns `{ statement, affected, columns, rows }`.
    */
   query(sql, ...params) {
+    // Spec §3.1 / §2.5: empty SQL is a caller bug; reject locally before
+    // touching the wire.
+    if (typeof sql !== 'string' || sql.trim().length === 0) {
+      return Promise.reject(
+        new RedDBError('INVALID_ARGUMENT', 'query() requires a non-empty SQL string'),
+      )
+    }
     const wireParams = normalizeQueryParams(params)
     if (wireParams == null) {
       return this.client.call('query', { sql }).then(normalizeResult)
@@ -361,10 +465,23 @@ export class RedDB {
 
   /** Insert many rows in one call. Returns `{ affected, rids, ids }`; `ids` is a legacy alias. */
   async bulkInsert(collection, payloads) {
+    // Spec §3.4: empty payloads is a no-op returning `{ affected: 0, rids: [] }`.
+    if (Array.isArray(payloads) && payloads.length === 0) {
+      return { affected: 0, rids: [], ids: [] }
+    }
     const result = await this.client.call('bulk_insert', { collection, payloads })
     return requireInsertIds(result, payloads.length)
   }
 
+  /**
+   * Spec §7 transaction handle. `db.tx()` returns a {@link TxClient} exposing
+   * imperative `begin` / `commit` / `rollback` plus a `run(callback)` form.
+   * `db.transaction(callback)` remains as the original callback-only shortcut.
+   */
+  tx() {
+    return new TxClient(this)
+  }
+
   async transaction(callback) {
     if (this.inTransaction) {
       throw nestedTransactionError()

package/src/kv.js

@@ -17,6 +17,11 @@ export class KvClient {
     })
   }
 
+  // Spec-canonical alias for `put` (SDK Helper Spec §5.1 `kv.set`).
+  set(key, value, options = {}) {
+    return this.put(key, value, options)
+  }
+
   async get(key, options = {}) {
     const collection = options.collection ?? this.collection
     const result = await this.client.call('query', {
@@ -40,7 +45,9 @@ export class KvClient {
     const result = await this.client.call('query', {
       sql: `KV DELETE ${kvPath(collection, key)}`,
     })
-    return { affected: result.affected ?? result.affected_rows ?? 0 }
+    const affected = result.affected ?? result.affected_rows ?? 0
+    // Spec §5.4 / §2.4 DeleteResult: `deleted` is `affected > 0`.
+    return { affected, deleted: affected > 0 }
   }
 
   async list(options = {}) {

package/src/queue.js

@@ -5,6 +5,14 @@ export class QueueClient {
     this.client = client
   }
 
+  // Spec §6.1 `queues.create`: idempotent (CREATE QUEUE IF NOT EXISTS) so
+  // conformance fixtures can prime a queue the same way the Rust/Go harnesses do.
+  create(queue) {
+    return this.client.call('query', {
+      sql: `CREATE QUEUE IF NOT EXISTS ${queueIdentifier(queue)}`,
+    })
+  }
+
   push(queue, value, options = {}) {
     const priority = options.priority != null ? ` PRIORITY ${queuePriority(options.priority)}` : ''
     return this.client.call('query', {