@dotteamdev/sensdb 0.1.0 → 0.2.0

package/README.md

@@ -9,15 +9,18 @@ Node 18+, Bun, Deno, and any runtime with a global `fetch`.
 
 ## Setup
 
-Copy `sens.ts` into your project (an npm package with prebuilds is on the
-roadmap). Start a server:
+```bash
+npm install @dotteamdev/sensdb
+```
+
+Start a server:
 
 ```bash
 sens serve app.db --port 8080 --token "$(openssl rand -hex 16)"
 ```
 
 ```ts
-import { createClient } from "./sens";
+import { createClient } from "@dotteamdev/sensdb";
 
 const db = createClient(process.env.SENS_URL!, { token: process.env.SENS_TOKEN });
 
@@ -79,11 +82,47 @@ export class SensService {
 }
 ```
 
+## Transactions
+
+Group statements into one atomic unit. `transaction()` commits if your callback
+resolves and rolls back if it throws:
+
+```ts
+await db.transaction(async (tx) => {
+  await tx.query("UPDATE accounts SET cents = cents - ? WHERE id = ?", [100, 1]);
+  await tx.query("UPDATE accounts SET cents = cents + ? WHERE id = ?", [100, 2]);
+  // resolves → COMMIT; throws → ROLLBACK (both accounts, atomically)
+});
+```
+
+Manual control, savepoints, and **`PREVIEW`** — a dry-run that returns the exact
+change-set the transaction *would* apply, so an AI agent can inspect before
+committing (no other database offers this as a built-in):
+
+```ts
+const tx = await db.begin();
+await tx.query("DELETE FROM users WHERE last_seen < ?", [cutoff]);
+await tx.savepoint("s1");
+await tx.query("UPDATE orders SET status = 'archived' WHERE user_id IN (SELECT id FROM users)");
+
+const change = await tx.preview();       // or tx.preview(true) for per-row old→new
+// change.rows = what COMMIT would apply, WITHOUT applying it — inspect it, then:
+if (looksRight(change)) await tx.commit();
+else await tx.rollback();
+```
+
+The server serializes write transactions (one at a time); a concurrent write
+while a transaction is open throws `SensError` with `status === 409`. Atomicity
+covers relational rows **and** the vector/semantic index together.
+
 ## API
 
 - `createClient(baseUrl, { token?, fetch? })` → `SensClient`
 - `client.query(sql, params?)` → `Promise<{ columns, rows }>` — throws `SensError` on failure
+- `client.begin()` → `Promise<SensTransaction>` — open a transaction (you must `commit()`/`rollback()`)
+- `client.transaction(fn)` → runs `fn(tx)`, commits on resolve, rolls back on throw
 - `client.health()` → `Promise<{ status, version }>`
+- **`SensTransaction`**: `query`, `preview(full?)`, `savepoint(name)`, `rollbackTo(name)`, `release(name)`, `commit()`, `rollback()`
 
 Value mapping (JSON ↔ Sens): number ↔ INTEGER/REAL, string ↔ TEXT,
 boolean ↔ BOOLEAN, null ↔ NULL, `number[]` ↔ VECTOR.

package/dist/sens.d.ts

@@ -17,9 +17,55 @@ export declare class SensError extends Error {
     readonly status?: number | undefined;
     constructor(message: string, status?: number | undefined);
 }
+/**
+ * An open multi-statement transaction. Every call is routed to the server's
+ * transaction session via the `X-Sens-Txn` token, so the statements form one
+ * atomic unit. Finish with `commit()` or `rollback()`. Prefer `transaction()`,
+ * which does that for you.
+ *
+ * The server allows one write transaction at a time; a concurrent write while a
+ * transaction is open rejects with `SensError` (HTTP 409). An idle transaction
+ * is rolled back by the server after its idle timeout.
+ */
+export interface SensTransaction {
+    /** Run a (parameterized) statement inside the transaction. */
+    query(sql: string, params?: SensValue[]): Promise<SensResult>;
+    /**
+     * Dry-run: return the change-set this transaction WOULD apply, without
+     * committing. `full` (→ `PREVIEW FULL`) adds per-row old→new detail.
+     * Lets an agent inspect the pending changes before deciding to commit.
+     */
+    preview(full?: boolean): Promise<SensResult>;
+    /** Establish a savepoint. */
+    savepoint(name: string): Promise<void>;
+    /** Roll back to a savepoint, discarding work after it (the savepoint stays active). */
+    rollbackTo(name: string): Promise<void>;
+    /** Release a savepoint, merging its work into the parent. */
+    release(name: string): Promise<void>;
+    /** Commit the whole transaction. Durable on success. */
+    commit(): Promise<void>;
+    /** Roll back the whole transaction, discarding everything since it began. */
+    rollback(): Promise<void>;
+}
 export interface SensClient {
-    /** Run a (parameterized) SQL statement. `?` placeholders are filled from `params`. */
+    /** Run a (parameterized) SQL statement (autocommit). `?` placeholders are filled from `params`. */
     query(sql: string, params?: SensValue[]): Promise<SensResult>;
+    /**
+     * Open a multi-statement transaction. Returns a handle whose statements run
+     * atomically; you MUST `commit()` or `rollback()` it. Prefer `transaction()`.
+     */
+    begin(): Promise<SensTransaction>;
+    /**
+     * Run `fn` inside a transaction: commits if it resolves, rolls back if it
+     * throws (then rethrows). The idiomatic way to use transactions.
+     *
+     *   const inserted = await db.transaction(async (tx) => {
+     *     await tx.query("INSERT INTO accounts (id, cents) VALUES (?, ?)", [1, 100]);
+     *     await tx.query("UPDATE ledger SET total = total + ? WHERE id = ?", [100, 1]);
+     *     return 1;
+     *   });
+     */
+    transaction<T>(fn: (tx: SensTransaction) => Promise<T>): Promise<T>;
     /** Server health + version. */
     health(): Promise<{
         status: string;

package/dist/sens.js

@@ -13,6 +13,12 @@ export class SensError extends Error {
         this.name = "SensError";
     }
 }
+/** Savepoint names are SQL identifiers and can't be parameterized, so validate them. */
+function assertIdentifier(name) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new SensError(`invalid savepoint name: ${JSON.stringify(name)}`);
+    }
+}
 /**
  * Create a Sens client bound to a `sens serve` base URL, e.g.
  *   const db = createClient("http://127.0.0.1:8080", { token: process.env.SENS_TOKEN });
@@ -20,30 +26,94 @@ export class SensError extends Error {
 export function createClient(baseUrl, opts = {}) {
     const url = baseUrl.replace(/\/+$/, "");
     const doFetch = opts.fetch ?? fetch;
-    const headers = { "content-type": "application/json" };
+    const baseHeaders = { "content-type": "application/json" };
     if (opts.token) {
-        headers["authorization"] = `Bearer ${opts.token}`;
+        baseHeaders["authorization"] = `Bearer ${opts.token}`;
+    }
+    /** POST /query, optionally within a transaction session (txnToken). Returns the parsed body. */
+    async function request(sql, params, txnToken) {
+        const headers = { ...baseHeaders };
+        if (txnToken) {
+            headers["x-sens-txn"] = txnToken;
+        }
+        const res = await doFetch(`${url}/query`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ sql, params }),
+        });
+        const text = await res.text();
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            throw new SensError(`invalid response from server: ${text.slice(0, 200)}`, res.status);
+        }
+        const obj = data;
+        if (!res.ok || obj.error) {
+            throw new SensError(obj.error ?? `HTTP ${res.status}`, res.status);
+        }
+        return obj;
+    }
+    function toResult(obj) {
+        return { columns: obj.columns ?? [], rows: obj.rows ?? [] };
+    }
+    function makeTransaction(token) {
+        return {
+            async query(sql, params = []) {
+                return toResult(await request(sql, params, token));
+            },
+            async preview(full = false) {
+                return toResult(await request(full ? "PREVIEW FULL" : "PREVIEW", [], token));
+            },
+            async savepoint(name) {
+                assertIdentifier(name);
+                await request(`SAVEPOINT ${name}`, [], token);
+            },
+            async rollbackTo(name) {
+                assertIdentifier(name);
+                await request(`ROLLBACK TO ${name}`, [], token);
+            },
+            async release(name) {
+                assertIdentifier(name);
+                await request(`RELEASE ${name}`, [], token);
+            },
+            async commit() {
+                await request("COMMIT", [], token);
+            },
+            async rollback() {
+                await request("ROLLBACK", [], token);
+            },
+        };
     }
-    return {
+    const client = {
         async query(sql, params = []) {
-            const res = await doFetch(`${url}/query`, {
-                method: "POST",
-                headers,
-                body: JSON.stringify({ sql, params }),
-            });
-            const text = await res.text();
-            let data;
-            try {
-                data = JSON.parse(text);
+            return toResult(await request(sql, params));
+        },
+        async begin() {
+            const obj = await request("BEGIN", []);
+            if (!obj.txn) {
+                throw new SensError("server did not return a transaction token for BEGIN");
             }
-            catch {
-                throw new SensError(`invalid response from server: ${text.slice(0, 200)}`, res.status);
+            return makeTransaction(obj.txn);
+        },
+        async transaction(fn) {
+            const tx = await client.begin();
+            let result;
+            try {
+                result = await fn(tx);
             }
-            const obj = data;
-            if (!res.ok || obj.error) {
-                throw new SensError(obj.error ?? `HTTP ${res.status}`, res.status);
+            catch (err) {
+                try {
+                    await tx.rollback();
+                }
+                catch {
+                    /* keep the original error; the server also idle-reaps an abandoned txn */
+                }
+                throw err;
             }
-            return { columns: obj.columns ?? [], rows: obj.rows ?? [] };
+            await tx.commit();
+            return result;
         },
         async health() {
             const res = await doFetch(`${url}/health`);
@@ -53,4 +123,5 @@ export function createClient(baseUrl, opts = {}) {
             return (await res.json());
         },
     };
+    return client;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotteamdev/sensdb",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Zero-dependency TypeScript client for a Sens (sens serve) HTTP/JSON endpoint — relational + AI-native (vector/semantic search) database.",
   "type": "module",
   "main": "./dist/sens.js",

package/sens.ts

@@ -23,9 +23,56 @@ export class SensError extends Error {
   }
 }
 
+/**
+ * An open multi-statement transaction. Every call is routed to the server's
+ * transaction session via the `X-Sens-Txn` token, so the statements form one
+ * atomic unit. Finish with `commit()` or `rollback()`. Prefer `transaction()`,
+ * which does that for you.
+ *
+ * The server allows one write transaction at a time; a concurrent write while a
+ * transaction is open rejects with `SensError` (HTTP 409). An idle transaction
+ * is rolled back by the server after its idle timeout.
+ */
+export interface SensTransaction {
+  /** Run a (parameterized) statement inside the transaction. */
+  query(sql: string, params?: SensValue[]): Promise<SensResult>;
+  /**
+   * Dry-run: return the change-set this transaction WOULD apply, without
+   * committing. `full` (→ `PREVIEW FULL`) adds per-row old→new detail.
+   * Lets an agent inspect the pending changes before deciding to commit.
+   */
+  preview(full?: boolean): Promise<SensResult>;
+  /** Establish a savepoint. */
+  savepoint(name: string): Promise<void>;
+  /** Roll back to a savepoint, discarding work after it (the savepoint stays active). */
+  rollbackTo(name: string): Promise<void>;
+  /** Release a savepoint, merging its work into the parent. */
+  release(name: string): Promise<void>;
+  /** Commit the whole transaction. Durable on success. */
+  commit(): Promise<void>;
+  /** Roll back the whole transaction, discarding everything since it began. */
+  rollback(): Promise<void>;
+}
+
 export interface SensClient {
-  /** Run a (parameterized) SQL statement. `?` placeholders are filled from `params`. */
+  /** Run a (parameterized) SQL statement (autocommit). `?` placeholders are filled from `params`. */
   query(sql: string, params?: SensValue[]): Promise<SensResult>;
+  /**
+   * Open a multi-statement transaction. Returns a handle whose statements run
+   * atomically; you MUST `commit()` or `rollback()` it. Prefer `transaction()`.
+   */
+  begin(): Promise<SensTransaction>;
+  /**
+   * Run `fn` inside a transaction: commits if it resolves, rolls back if it
+   * throws (then rethrows). The idiomatic way to use transactions.
+   *
+   *   const inserted = await db.transaction(async (tx) => {
+   *     await tx.query("INSERT INTO accounts (id, cents) VALUES (?, ?)", [1, 100]);
+   *     await tx.query("UPDATE ledger SET total = total + ? WHERE id = ?", [100, 1]);
+   *     return 1;
+   *   });
+   */
+  transaction<T>(fn: (tx: SensTransaction) => Promise<T>): Promise<T>;
   /** Server health + version. */
   health(): Promise<{ status: string; version: string }>;
 }
@@ -37,6 +84,13 @@ export interface SensClientOptions {
   fetch?: typeof fetch;
 }
 
+/** Savepoint names are SQL identifiers and can't be parameterized, so validate them. */
+function assertIdentifier(name: string): void {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new SensError(`invalid savepoint name: ${JSON.stringify(name)}`);
+  }
+}
+
 /**
  * Create a Sens client bound to a `sens serve` base URL, e.g.
  *   const db = createClient("http://127.0.0.1:8080", { token: process.env.SENS_TOKEN });
@@ -44,30 +98,101 @@ export interface SensClientOptions {
 export function createClient(baseUrl: string, opts: SensClientOptions = {}): SensClient {
   const url = baseUrl.replace(/\/+$/, "");
   const doFetch = opts.fetch ?? fetch;
-  const headers: Record<string, string> = { "content-type": "application/json" };
+  const baseHeaders: Record<string, string> = { "content-type": "application/json" };
   if (opts.token) {
-    headers["authorization"] = `Bearer ${opts.token}`;
+    baseHeaders["authorization"] = `Bearer ${opts.token}`;
+  }
+
+  /** POST /query, optionally within a transaction session (txnToken). Returns the parsed body. */
+  async function request(
+    sql: string,
+    params: SensValue[],
+    txnToken?: string,
+  ): Promise<{ error?: string; columns?: string[]; rows?: SensValue[][]; txn?: string }> {
+    const headers: Record<string, string> = { ...baseHeaders };
+    if (txnToken) {
+      headers["x-sens-txn"] = txnToken;
+    }
+    const res = await doFetch(`${url}/query`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ sql, params }),
+    });
+    const text = await res.text();
+    let data: unknown;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      throw new SensError(`invalid response from server: ${text.slice(0, 200)}`, res.status);
+    }
+    const obj = data as { error?: string; columns?: string[]; rows?: SensValue[][]; txn?: string };
+    if (!res.ok || obj.error) {
+      throw new SensError(obj.error ?? `HTTP ${res.status}`, res.status);
+    }
+    return obj;
   }
 
-  return {
+  function toResult(obj: { columns?: string[]; rows?: SensValue[][] }): SensResult {
+    return { columns: obj.columns ?? [], rows: obj.rows ?? [] };
+  }
+
+  function makeTransaction(token: string): SensTransaction {
+    return {
+      async query(sql: string, params: SensValue[] = []): Promise<SensResult> {
+        return toResult(await request(sql, params, token));
+      },
+      async preview(full = false): Promise<SensResult> {
+        return toResult(await request(full ? "PREVIEW FULL" : "PREVIEW", [], token));
+      },
+      async savepoint(name: string): Promise<void> {
+        assertIdentifier(name);
+        await request(`SAVEPOINT ${name}`, [], token);
+      },
+      async rollbackTo(name: string): Promise<void> {
+        assertIdentifier(name);
+        await request(`ROLLBACK TO ${name}`, [], token);
+      },
+      async release(name: string): Promise<void> {
+        assertIdentifier(name);
+        await request(`RELEASE ${name}`, [], token);
+      },
+      async commit(): Promise<void> {
+        await request("COMMIT", [], token);
+      },
+      async rollback(): Promise<void> {
+        await request("ROLLBACK", [], token);
+      },
+    };
+  }
+
+  const client: SensClient = {
     async query(sql: string, params: SensValue[] = []): Promise<SensResult> {
-      const res = await doFetch(`${url}/query`, {
-        method: "POST",
-        headers,
-        body: JSON.stringify({ sql, params }),
-      });
-      const text = await res.text();
-      let data: unknown;
-      try {
-        data = JSON.parse(text);
-      } catch {
-        throw new SensError(`invalid response from server: ${text.slice(0, 200)}`, res.status);
+      return toResult(await request(sql, params));
+    },
+
+    async begin(): Promise<SensTransaction> {
+      const obj = await request("BEGIN", []);
+      if (!obj.txn) {
+        throw new SensError("server did not return a transaction token for BEGIN");
       }
-      const obj = data as { error?: string; columns?: string[]; rows?: SensValue[][] };
-      if (!res.ok || obj.error) {
-        throw new SensError(obj.error ?? `HTTP ${res.status}`, res.status);
+      return makeTransaction(obj.txn);
+    },
+
+    async transaction<T>(fn: (tx: SensTransaction) => Promise<T>): Promise<T> {
+      const tx = await client.begin();
+      let result: T;
+      try {
+        result = await fn(tx);
+      } catch (err) {
+        try {
+          await tx.rollback();
+        } catch {
+          /* keep the original error; the server also idle-reaps an abandoned txn */
+        }
+        throw err;
       }
-      return { columns: obj.columns ?? [], rows: obj.rows ?? [] };
+      await tx.commit();
+      return result;
     },
 
     async health(): Promise<{ status: string; version: string }> {
@@ -78,4 +203,6 @@ export function createClient(baseUrl: string, opts: SensClientOptions = {}): Sen
       return (await res.json()) as { status: string; version: string };
     },
   };
+
+  return client;
 }