@reddb-io/sdk 1.1.2 → 1.2.3

package/README.md

@@ -49,6 +49,17 @@ await db.bulkInsert('users', [{ name: 'Bob' }, { name: 'Carol' }])
 const result = await db.query('SELECT * FROM users')
 console.log(result.rows)
 
+const doc = await db.documents.insert('events', {
+  event_type: 'login',
+  attempts: 1,
+})
+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()
 ```
 
@@ -71,6 +82,28 @@ try {
 await db.close()
 ```
 
+For the SQL/RQL grammar that `db.query()` accepts, see
+[`docs/reference/sql-1-0-x.md`](../../docs/reference/sql-1-0-x.md).
+
+## 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.
+
 ## Connection URIs
 
 | URI                        | Mode                                 |
@@ -135,13 +168,69 @@ client yet. Use the HTTP streaming API for incremental ASK frames; stdio
 currently supports materialised cursor batching through `query.open` /
 `query.next`, which is separate from ASK token streaming.
 
-### `db.insert(collection, payload) → Promise<{ affected, id? }>`
+### `db.insert(collection, payload) → Promise<{ affected, rid, id }>`
+
+`id` is a legacy alias for `rid`.
+
+### `db.bulkInsert(collection, payloads) → Promise<{ affected, rids, ids }>`
+
+`ids` is a legacy alias for `rids`.
+
+### `db.get(collection, rid) → Promise<{ entity }>`
+
+### `db.delete(collection, rid) → Promise<{ affected }>`
 
-### `db.bulkInsert(collection, payloads) → Promise<{ affected }>`
+### `db.documents`
 
-### `db.get(collection, id) → Promise<{ entity }>`
+Document helpers follow the SDK Helper Spec:
 
-### `db.delete(collection, id) → Promise<{ affected }>`
+```js
+const inserted = await db.documents.insert('events', {
+  event_type: 'login',
+  details: { ip: '10.0.0.7' },
+})
+
+const event = await db.documents.get('events', inserted.rid)
+const page = await db.documents.list('events', {
+  filter: "event_type = 'login'",
+  limit: 10,
+})
+const updated = await db.documents.patch('events', inserted.rid, {
+  reviewed: true,
+})
+await db.documents.delete('events', inserted.rid)
+```
+
+`documents.insert()` creates the document collection when needed. Patch support
+currently accepts top-level document fields.
+
+### `db.kv(collection?)`
+
+KV helpers preserve exact keys, including namespaced keys with `:`.
+
+```js
+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.exists('characters:hansel')     // { exists: true }
+await kv.list({ prefix: 'characters:' }) // { items: [{ key, value }] }
+await kv.delete('characters:hansel')     // { affected }
+```
+
+### `db.queue`
+
+Queue helpers cover the embedded FIFO workflow:
+
+```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')
+```
 
 ### `db.health() → Promise<{ ok, version }>`
 

package/index.d.ts

@@ -89,11 +89,13 @@ export interface AskQueryResult {
 
 export interface InsertResult {
   affected: number
+  rid: string | number
   id: string | number
 }
 
 export interface BulkInsertResult {
   affected: number
+  rids: Array<string | number>
   ids: Array<string | number>
 }
 
@@ -233,6 +235,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,
@@ -244,6 +251,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,
@@ -294,11 +328,30 @@ export class VaultClient {
   unseal(key: string, options?: { collection?: string }): Promise<QueryResult>
 }
 
+export interface RedDBTransaction {
+  query(sql: `ASK ${string}`): Promise<AskQueryResult>
+  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 {
   /** Underlying transport label. connect() returns 'embedded'. */
   readonly transport: string | null
   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
@@ -315,6 +368,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/sdk",
-  "version": "1.1.2",
+  "version": "1.2.3",
   "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 && 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"
   }
 }

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/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/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, "''")}'`
 }