@reddb-io/cli 1.1.1 → 1.2.0

package/README.md

@@ -44,7 +44,7 @@ INSERT INTO users (name, email) VALUES ('Alice', 'alice@co.com')
 INSERT INTO logs DOCUMENT (body) VALUES ({"level":"info","msg":"login"})
 
 -- Graph edges
-INSERT INTO network EDGE (label, from, to) VALUES ('CONNECTS', 1, 2)
+INSERT INTO network EDGE (label, from_rid, to_rid) VALUES ('CONNECTS', 102, 103)
 
 -- Vector similarity search
 SEARCH SIMILAR TEXT 'anomaly detected' COLLECTION events
@@ -372,7 +372,7 @@ Same storage format across all three. Start embedded, scale to server, expose to
 RedDB uses multiple optimization techniques for fast queries at scale:
 
 - **Result Cache** -- identical SELECT queries return in <1ms; auto-invalidated on INSERT/UPDATE/DELETE (30s TTL, max 1000 entries)
-- **Hot Entity Cache** -- `get_any(id)` lookups served from an LRU cache (10K entries), O(1) instead of scanning all collections
+- **Hot Item Cache** -- `get_any(rid)` lookups served from an LRU cache (10K entries), O(1) instead of scanning all collections
 - **Binary Bulk Insert** -- gRPC `BulkInsertBinary` with zero JSON overhead, protobuf native types -- 241K ops/sec
 - **Concurrent HTTP** -- thread-per-connection model; each request handled in its own OS thread
 - **Parallel Segment Scanning** -- sealed segments scanned in parallel via `std::thread::scope`; auto-detects single-core and skips parallelism

package/drivers/js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reddb-io/sdk",
-  "version": "1.1.1",
+  "version": "1.2.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 && 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 test/transaction.test.mjs && node test/smoke.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.map((clause) => `(${clause})`).join(' AND ')}`
+      ? ` WHERE ${this.whereClauses.join(' AND ')}`
       : ''
     const sql = `SELECT ${projection} FROM ${sqlIdentifierPath(this.collection)}${where}`
     const result = this.params.length > 0

package/drivers/js/src/documents.js

@@ -0,0 +1,121 @@
+import { RedDBError } from './protocol.js'
+
+export class DocumentClient {
+  constructor(db) {
+    this.db = db
+  }
+
+  async insert(collection, document) {
+    validateObject(document, 'documents.insert document')
+    await this.ensureCollection(collection)
+    const result = await this.db.query(
+      `INSERT INTO ${sqlIdentifierPath(collection)} DOCUMENT (body) VALUES (${sqlJsonLiteral(document)}) RETURNING *`,
+    )
+    const item = result.rows?.[0]
+    if (!item || item.rid == null) {
+      throw new RedDBError('INVALID_RESPONSE', 'documents.insert expected one returned item with rid')
+    }
+    return { affected: result.affected ?? 1, rid: item.rid, item }
+  }
+
+  async get(collection, rid) {
+    const result = await this.db.get(collection, rid)
+    if (!result.entity) {
+      throw new RedDBError('NOT_FOUND', `document ${String(rid)} was not found`)
+    }
+    return result.entity
+  }
+
+  async list(collection, options = {}) {
+    const limit = normalizeLimit(options.limit)
+    const orderBy = options.orderBy ?? options.order_by ?? 'rid ASC'
+    const where = options.filter ? ` WHERE ${String(options.filter)}` : ''
+    const result = await this.db.query(
+      `SELECT * FROM ${sqlIdentifierPath(collection)}${where} ORDER BY ${orderBy} LIMIT ${limit}`,
+    )
+    return { items: result.rows ?? [] }
+  }
+
+  async patch(collection, rid, patch) {
+    validateObject(patch, 'documents.patch patch')
+    const entries = Object.entries(patch)
+    if (entries.length === 0) {
+      return this.get(collection, rid)
+    }
+    for (const [field] of entries) {
+      if (field.includes('/')) {
+        throw new RedDBError(
+          'INVALID_ARGUMENT',
+          'documents.patch currently accepts top-level document fields',
+        )
+      }
+    }
+    const assignments = entries
+      .map(([field, value]) => `${sqlIdentifier(field)} = ${sqlValueLiteral(value)}`)
+      .join(', ')
+    const result = await this.db.query(
+      `UPDATE ${sqlIdentifierPath(collection)} DOCUMENTS SET ${assignments} WHERE rid = $1 RETURNING *`,
+      rid,
+    )
+    const item = result.rows?.[0]
+    if (!item) {
+      throw new RedDBError('NOT_FOUND', `document ${String(rid)} was not found`)
+    }
+    return item
+  }
+
+  async delete(collection, rid) {
+    const result = await this.db.delete(collection, rid)
+    return { affected: result.affected ?? 0 }
+  }
+
+  async ensureCollection(collection) {
+    try {
+      await this.db.query(`CREATE DOCUMENT ${sqlIdentifierPath(collection)}`)
+    } catch (err) {
+      const message = String(err?.message ?? '')
+      if (!message.includes('already exists')) throw err
+    }
+  }
+}
+
+function validateObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new RedDBError('INVALID_ARGUMENT', `${label} must be an object`)
+  }
+}
+
+function normalizeLimit(value) {
+  if (value == null) return 100
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new RedDBError('INVALID_ARGUMENT', 'limit must be a positive integer')
+  }
+  return value
+}
+
+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_ARGUMENT', `invalid SQL identifier "${ident}"`)
+  }
+  return ident
+}
+
+function sqlJsonLiteral(value) {
+  return sqlString(JSON.stringify(value))
+}
+
+function sqlValueLiteral(value) {
+  if (value == null) return 'NULL'
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  if (typeof value === 'object') return sqlJsonLiteral(value)
+  return sqlString(value)
+}
+
+function sqlString(value) {
+  return `'${String(value).replace(/'/g, "''")}'`
+}

package/drivers/js/src/index.js

@@ -25,6 +25,7 @@ import { parseUri } from './url.js'
 import { CacheClient } from './cache.js'
 import { KvClient } from './kv.js'
 import { QueueClient } from './queue.js'
+import { DocumentClient } from './documents.js'
 import { ConfigClient } from './config.js'
 import { VaultClient } from './vault.js'
 import { TypedQueryBuilder, collectionExists, listCollections } from './db-helpers.js'
@@ -33,6 +34,7 @@ export { RedDBError }
 export { CacheClient } from './cache.js'
 export { KvClient } from './kv.js'
 export { QueueClient } from './queue.js'
+export { DocumentClient } from './documents.js'
 export { ConfigClient } from './config.js'
 export { VaultClient } from './vault.js'
 export { TypedQueryBuilder } from './db-helpers.js'
@@ -42,6 +44,7 @@ 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'
+const NESTED_TX_NOT_SUPPORTED = 'NESTED_TX_NOT_SUPPORTED'
 
 /**
  * Connect to a RedDB instance.
@@ -275,6 +278,32 @@ function rejectRemoteUri(parsed) {
 /**
  * Connection handle. Methods map 1:1 to JSON-RPC methods on the binary.
  */
+class TransactionHandle {
+  constructor(db) {
+    this.db = db
+  }
+
+  query(sql, ...params) {
+    return this.db.query(sql, ...params)
+  }
+
+  execute(sql, ...params) {
+    return this.db.execute(sql, ...params)
+  }
+
+  insert(collection, payload) {
+    return this.db.insert(collection, payload)
+  }
+
+  bulkInsert(collection, payloads) {
+    return this.db.bulkInsert(collection, payloads)
+  }
+
+  async transaction() {
+    throw nestedTransactionError()
+  }
+}
+
 export class RedDB {
   /**
    * @param {RpcClient} client
@@ -288,6 +317,7 @@ export class RedDB {
     this.transport = opts.transport ?? null
     this.cache = new CacheClient(client, this.transport)
     this.queue = new QueueClient(client)
+    this.documents = new DocumentClient(this)
     const defaultKv = new KvClient(client)
     this.kv = Object.assign((collection = 'kv_default') => new KvClient(client, collection), {
       put: defaultKv.put.bind(defaultKv),
@@ -297,6 +327,7 @@ export class RedDB {
     })
     this.config = (collection = 'red.config') => new ConfigClient(client, collection)
     this.vault = (collection = 'red.vault') => new VaultClient(client, collection)
+    this.inTransaction = false
   }
 
   /**
@@ -322,18 +353,48 @@ export class RedDB {
     return this.query(sql, ...params)
   }
 
-  /** Insert one row. Returns `{ affected, id }`. */
+  /** Insert one row. Returns `{ affected, rid, id }`; `id` is a legacy alias. */
   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 }`. */
+  /** Insert many rows in one call. Returns `{ affected, rids, ids }`; `ids` is a legacy alias. */
   async bulkInsert(collection, payloads) {
     const result = await this.client.call('bulk_insert', { collection, payloads })
     return requireInsertIds(result, payloads.length)
   }
 
+  async transaction(callback) {
+    if (this.inTransaction) {
+      throw nestedTransactionError()
+    }
+    if (typeof callback !== 'function') {
+      throw new TypeError('transaction(callback) requires a function')
+    }
+
+    this.inTransaction = true
+    let began = false
+    try {
+      await this.query('BEGIN')
+      began = true
+      const result = await callback(new TransactionHandle(this))
+      await this.query('COMMIT')
+      return result
+    } catch (err) {
+      if (began) {
+        try {
+          await this.query('ROLLBACK')
+        } catch (rollbackErr) {
+          attachRollbackError(err, rollbackErr)
+        }
+      }
+      throw err
+    } finally {
+      this.inTransaction = false
+    }
+  }
+
   /** Return true when a collection is visible in the catalog. */
   exists(collection) {
     return collectionExists(this, collection)
@@ -417,27 +478,52 @@ export class RedDB {
   }
 }
 
+function nestedTransactionError() {
+  return new RedDBError(
+    NESTED_TX_NOT_SUPPORTED,
+    `${NESTED_TX_NOT_SUPPORTED}: nested transactions are not supported on one connection`,
+  )
+}
+
+function attachRollbackError(err, rollbackErr) {
+  if (err && typeof err === 'object') {
+    try {
+      err.rollbackError = rollbackErr
+    } catch {
+      // Preserve the original callback/query error even for frozen errors.
+    }
+  }
+}
+
 function requireInsertId(result, method) {
-  if (!result || typeof result !== 'object' || result.id == null) {
+  if (!result || typeof result !== 'object' || (result.rid == null && result.id == null)) {
     throw new RedDBError(
       'ENGINE_TOO_OLD',
       `${method}() requires RedDB engine >= ${MIN_INSERT_ID_ENGINE_VERSION} with insert id support`,
     )
   }
+  if (result.rid == null) result.rid = result.id
+  if (result.id == null) result.id = result.rid
   return result
 }
 
 function requireInsertIds(result, expected) {
-  if (!result || typeof result !== 'object' || !Array.isArray(result.ids)) {
+  if (
+    !result ||
+    typeof result !== 'object' ||
+    (!Array.isArray(result.rids) && !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) {
+  if (!Array.isArray(result.rids)) result.rids = result.ids
+  if (!Array.isArray(result.ids)) result.ids = result.rids
+  if (result.rids.length !== expected) {
     throw new RedDBError(
       'INVALID_RESPONSE',
-      `bulkInsert() expected ${expected} ids, got ${result.ids.length}`,
+      `bulkInsert() expected ${expected} rids, got ${result.rids.length}`,
     )
   }
   return result

package/drivers/js/src/kv.js

@@ -31,6 +31,35 @@ export class KvClient {
     return values
   }
 
+  async exists(key, options = {}) {
+    return { exists: (await this.get(key, options)) !== null }
+  }
+
+  async delete(key, options = {}) {
+    const collection = options.collection ?? this.collection
+    const result = await this.client.call('query', {
+      sql: `KV DELETE ${kvPath(collection, key)}`,
+    })
+    return { affected: result.affected ?? result.affected_rows ?? 0 }
+  }
+
+  async list(options = {}) {
+    const collection = options.collection ?? this.collection
+    const limit = options.limit == null ? 100 : Number(options.limit)
+    if (!Number.isInteger(limit) || limit <= 0) {
+      throw new RedDBError('INVALID_ARGUMENT', 'kv.list limit must be a positive integer')
+    }
+    const prefix = options.prefix == null ? '' : String(options.prefix)
+    const result = await this.client.call('query', {
+      sql: `SELECT key, value FROM ${kvIdentifier(collection)} ORDER BY key ASC LIMIT ${limit}`,
+    })
+    const rows = result.rows ?? []
+    const items = prefix.length > 0
+      ? rows.filter((row) => String(row.key).startsWith(prefix))
+      : rows
+    return { items }
+  }
+
   async invalidateTags(tags, options = {}) {
     const collection = options.collection ?? this.collection
     const result = await this.client.call('query', {
@@ -66,7 +95,7 @@ export class KvClient {
 }
 
 function kvPath(collection, key) {
-  return `${kvIdentifier(collection)}.${kvIdentifier(key)}`
+  return `${kvIdentifier(collection)}.${kvKeySegment(key)}`
 }
 
 function kvIdentifier(value) {
@@ -81,9 +110,16 @@ function kvIdentifier(value) {
   return ident
 }
 
+function kvKeySegment(value) {
+  const key = String(value)
+  if (/^[A-Za-z0-9_]+$/.test(key)) return key
+  return `'${key.replace(/'/g, "''")}'`
+}
+
 function kvValueLiteral(value) {
   if (typeof value === 'number' || typeof value === 'boolean') return String(value)
   if (value == null) return 'NULL'
+  if (typeof value === 'object') return `'${JSON.stringify(value).replace(/'/g, "''")}'`
   return `'${String(value).replace(/'/g, "''")}'`
 }
 

package/package.json

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