@reddb-io/client 1.1.2 → 1.2.3

package/README.md

@@ -50,6 +50,14 @@ await db.insert('users', { name: 'Alice' })
 const result = await db.query('SELECT * FROM users WHERE name = $1', 'Alice')
 console.log(result.rows)
 
+const doc = await db.documents.insert('events', { event_type: 'login' })
+await db.documents.patch('events', doc.rid, { reviewed: true })
+
+await db.query('CREATE KV settings')
+const kv = db.kv('settings')
+await kv.put('characters:hansel', 'crumbs')
+console.log(await kv.get('characters:hansel'))
+
 await db.close()
 ```
 
@@ -61,6 +69,40 @@ For `http://` and `https://` connections, `connect()` verifies readiness with
 a lightweight `SELECT 1` round-trip. `/health` states such as `degraded` are
 transient during boot and are not fatal as long as queries succeed.
 
+## 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`.
+
+```js
+const userId = await db.transaction(async (tx) => {
+  const inserted = await tx.insert('users', { name: 'Ada' })
+  await tx.query('INSERT INTO audit (action) VALUES ($1)', 'created user')
+  return inserted.rid
+})
+```
+
+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.
+
+## Rich Helpers
+
+The client follows the SDK Helper Spec for the shared JS/TS surface:
+
+- `db.insert(collection, payload)` returns `{ affected, rid, id }`; `id` is a
+  legacy alias for `rid`.
+- `db.bulkInsert(collection, payloads)` returns `{ affected, rids, ids }`; `ids`
+  is a legacy alias for `rids`.
+- `db.documents.insert/get/list/patch/delete` covers document CRUD. Insert
+  creates the document collection when needed; patch currently accepts top-level
+  fields.
+- `db.kv(collection?)` preserves exact keys, including namespaced keys such as
+  `characters:hansel`, and exposes `put/get/exists/delete/list`.
+- `db.queue` exposes `push/pop/peek/len/purge`.
+
 ## Accepted URI schemes
 
 | Scheme         | Transport                     | Default port |

package/index.d.ts

@@ -43,8 +43,12 @@ export type QueryParam =
   | number[]
   | Record<string, unknown>
 
-export interface InsertResult { affected: number; id: string | number }
-export interface BulkInsertResult { affected: number; ids: Array<string | number> }
+export interface InsertResult { affected: number; rid: string | number; id: string | number }
+export interface BulkInsertResult {
+  affected: number
+  rids: Array<string | number>
+  ids: Array<string | number>
+}
 export interface GetResult { entity: Record<string, unknown> | null }
 export interface DeleteResult { affected: number }
 export interface CollectionMeta {
@@ -126,6 +130,11 @@ export class KvClient {
   ): 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 }>
+  delete(key: string, options?: { collection?: string }): Promise<DeleteResult>
+  list(options?: { collection?: string; prefix?: string; limit?: number }): Promise<{
+    items: Array<{ key: string; value: unknown }>
+  }>
   invalidateTags(tags: string[], options?: { collection?: string }): Promise<number>
   watch(
     key: string,
@@ -137,6 +146,33 @@ export class KvClient {
   ): AsyncIterable<KvWatchEvent>
 }
 
+export interface DocumentInsertResult<T extends Record<string, unknown> = Record<string, unknown>> {
+  affected: number
+  rid: string | number
+  item: T & { rid: string | number }
+}
+
+export class DocumentClient {
+  insert<T extends Record<string, unknown> = Record<string, unknown>>(
+    collection: string,
+    document: Record<string, unknown>,
+  ): Promise<DocumentInsertResult<T>>
+  get<T extends Record<string, unknown> = Record<string, unknown>>(
+    collection: string,
+    rid: string | number,
+  ): Promise<T & { rid: string | number }>
+  list<T extends Record<string, unknown> = Record<string, unknown>>(
+    collection: string,
+    options?: { filter?: string; orderBy?: string; order_by?: string; limit?: number },
+  ): Promise<{ items: Array<T & { rid: string | number }> }>
+  patch<T extends Record<string, unknown> = Record<string, unknown>>(
+    collection: string,
+    rid: string | number,
+    patch: Record<string, unknown>,
+  ): Promise<T & { rid: string | number }>
+  delete(collection: string, rid: string | number): Promise<DeleteResult>
+}
+
 export class QueueClient {
   push(
     queue: string,
@@ -204,9 +240,27 @@ export const EMBEDDED_REJECTION_MESSAGE: string
 /** Returns true when `uri` selects the embedded engine. */
 export function isEmbeddedUri(uri: string): boolean
 
+export interface RedDBTransaction {
+  query(sql: string): Promise<QueryResult>
+  query(sql: string, params: QueryParam[]): Promise<QueryResult>
+  query(sql: string, ...params: QueryParam[]): Promise<QueryResult>
+  execute(sql: string): Promise<QueryResult>
+  execute(sql: string, params: QueryParam[]): Promise<QueryResult>
+  execute(sql: string, ...params: QueryParam[]): Promise<QueryResult>
+  insert(collection: string, payload: Record<string, unknown>): Promise<InsertResult>
+  bulkInsert(
+    collection: string,
+    payloads: Array<Record<string, unknown>>,
+  ): Promise<BulkInsertResult>
+  transaction<T>(
+    callback: (tx: RedDBTransaction) => T | Promise<T>,
+  ): Promise<T>
+}
+
 export class RedDB {
   readonly cache: CacheClient
   readonly queue: QueueClient
+  readonly documents: DocumentClient
   readonly kv: KvClient & ((collection?: string) => KvClient)
   readonly config: (collection?: string) => ConfigClient
   readonly vault: (collection?: string) => VaultClient
@@ -222,6 +276,9 @@ export class RedDB {
     collection: string,
     payloads: Array<Record<string, unknown>>,
   ): Promise<BulkInsertResult>
+  transaction<T>(
+    callback: (tx: RedDBTransaction) => T | Promise<T>,
+  ): Promise<T>
   exists(collection: string): Promise<boolean>
   list(): Promise<CollectionMeta[]>
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reddb-io/client",
-  "version": "1.1.2",
+  "version": "1.2.3",
   "description": "Thin remote-only RedDB driver. Downloads the `red_client` binary on install. Speaks RedWire/gRPC/HTTP. Embedded URIs (memory://, file://, red:///path) are rejected — use @reddb-io/sdk for those.",
   "type": "module",
   "main": "src/index.js",

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.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/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/src/grpc.js

@@ -165,19 +165,23 @@ function normalizeQueryReply(reply) {
 }
 
 function normalizeEntityReply(reply) {
+  const rid = safeBigIntToJs(reply.id)
   return {
     ok: reply.ok,
     affected: reply.ok ? 1 : 0,
-    id: safeBigIntToJs(reply.id),
+    rid,
+    id: rid,
     entity: parseJsonOrNull(reply.entity_json),
   }
 }
 
 function normalizeBulkEntityReply(reply) {
+  const rids = reply.items.map((item) => safeBigIntToJs(item.id))
   return {
     ok: reply.ok,
     affected: safeBigIntToJs(reply.count),
-    ids: reply.items.map((item) => safeBigIntToJs(item.id)),
+    rids,
+    ids: rids,
   }
 }
 

package/src/index.js

@@ -40,6 +40,7 @@ import {
 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'
@@ -48,12 +49,14 @@ export { RedDBError, EmbeddedNotSupported, EMBEDDED_REJECTION_MESSAGE, isEmbedde
 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'
 export { parseUri, deriveLoginUrl } from './url.js'
 
 const MIN_INSERT_ID_ENGINE_VERSION = '1.0.9'
+const NESTED_TX_NOT_SUPPORTED = 'NESTED_TX_NOT_SUPPORTED'
 
 /**
  * Connect to a remote RedDB instance.
@@ -353,12 +356,39 @@ export async function login(loginUrl, { username, password }) {
  * Identical surface to `@reddb-io/sdk`'s `RedDB`, minus the local-spawn
  * lifecycle.
  */
+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 {HttpRpcClient | import('./redwire.js').RedWireClient} client */
   constructor(client) {
     this.client = client
     this.cache = new CacheClient(client)
     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),
@@ -368,6 +398,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
   }
 
   /** Execute a SQL query. Returns `{ statement, affected, columns, rows }`. */
@@ -384,26 +415,56 @@ 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 for `rid`. */
   async insert(collection, payload) {
     let result = await this.client.call('insert', { collection, payload })
     if (
       result &&
       typeof result === 'object' &&
       !('affected' in result) &&
-      'id' in result
+      ('rid' in result || 'id' in result)
     ) {
       result = { ...result, affected: 1 }
     }
     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)
@@ -473,27 +534,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/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, "''")}'`
 }