@reddb-io/cli 1.2.5 → 1.4.0

package/README.md

@@ -635,3 +635,30 @@ RedDB from another Rust project.
 ---
 
 **AGPL-3.0 License** -- Built by [RedDB.io](https://github.com/reddb-io)
+
+<!-- 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.
+>
+> Every public RedDB promise and the status of each public surface that offers it.
+
+| Promise | sql | http | redwire | grpc | driver_helpers |
+| --- | --- | --- | --- | --- | --- |
+| **PSC-001** — RedDB is one multi-model database (tables, graph, KV, timeseries, probabilistic, vector, queue, documents) backed by a single file. | ✅ supported | ✅ supported | ✅ supported | ✅ supported | ✅ supported |
+| **PSC-002** — MATCH supports node, edge, label, property, and LIMIT projections. | ✅ supported | ✅ supported | ⚠️ partial | ⚠️ partial | ✅ supported |
+| **PSC-003** — GRAPH algorithms accept semantic identifiers, limits, ordering, and return stable rich rows. | ✅ supported | ✅ supported | ❌ unsupported | ❌ unsupported | ❌ unsupported |
+| **PSC-004** — INSERT creates rows, documents, and native timeseries points. | ✅ supported | ✅ supported | ⚠️ partial | ✅ supported | ✅ supported |
+| **PSC-005** — HLL/SKETCH/FILTER expose write and read commands for cardinality, frequency, and membership. | ⚠️ partial | ❌ unsupported | ❌ unsupported | ❌ unsupported | ⚠️ partial |
+| **PSC-006** — Timeseries stores timestamped metrics with tags and supports query/readback. | ✅ supported | ⚠️ partial | ❌ unsupported | ❌ unsupported | ⚠️ partial |
+| **PSC-007** — Documents are first-class: create, read, update, delete, and SQL analytics over JSON. | ✅ supported | ✅ supported | ❌ unsupported | ✅ supported | ✅ supported |
+| **PSC-008** — KV helpers expose get/put/delete; get of a missing key returns null, delete reports affected. | ✅ supported | ❌ unsupported | ❌ unsupported | ✅ supported | ✅ supported |
+| **PSC-009** — Queue helpers expose create/push/peek/pop/len/purge with FIFO semantics; empty pop is not an error. | ✅ supported | ❌ unsupported | ❌ unsupported | ❌ unsupported | ✅ supported |
+| **PSC-010** — Transactions are imperative (begin/commit/rollback) plus a run(callback) form; empty SQL rejects with INVALID_ARGUMENT. | ✅ supported | ❌ unsupported | ❌ unsupported | ✅ supported | ✅ supported |
+| **PSC-011** — SQL aggregate, projection, expression, and mutation behaviour matches ordinary SQL expectations where advertised. | ✅ supported | ✅ supported | ⚠️ partial | ⚠️ partial | ✅ supported |
+| **PSC-012** — Server transports expose the same query contract as embedded (HTTP, RedWire, gRPC parity). | ✅ supported | ✅ supported | ✅ supported | ✅ supported | ✅ supported |
+| **PSC-013** — Official drivers implement the SDK Helper Spec v1.0 conformance suite (all 22 §12 case IDs). | ❌ unsupported | ❌ unsupported | ❌ unsupported | ✅ supported | ✅ supported |
+| **PSC-014** — ASK / SEARCH semantic surfaces return ranked results with stable shape. | ✅ supported | ⚠️ partial | ❌ unsupported | ❌ unsupported | ⚠️ partial |
+
+_Status legend: ✅ supported · ⚠️ partial (known gaps) · ❌ unsupported._
+<!-- contract-matrix:end -->

package/drivers/js/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",
@@ -20,7 +20,7 @@
   ],
   "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"
   },
   "engines": {
     "node": ">=18"

package/drivers/js/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/drivers/js/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/drivers/js/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/drivers/js/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/drivers/js/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', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reddb-io/cli",
-  "version": "1.2.5",
+  "version": "1.4.0",
   "description": "CLI launcher for RedDB. The JS/TS app driver is published as @reddb-io/sdk.",
   "type": "commonjs",
   "bin": {
@@ -37,6 +37,9 @@
   "scripts": {
     "postinstall": "node drivers/js/cli-postinstall.js",
     "test": "node drivers/js/test/smoke.test.mjs",
+    "typecheck": "cargo check --workspace --locked",
+    "lint": "cargo fmt --all -- --check && cargo clippy --workspace --locked -- -D warnings",
+    "build": "cargo test --workspace --locked",
     "changeset": "changeset",
     "release:version": "changeset version && node scripts/sync-version.js",
     "release:publish": "changeset publish",