@lix-js/sdk 0.6.0-preview.2 → 0.6.0-preview.4

package/SKILL.md

@@ -13,6 +13,7 @@ Current `@lix-js/sdk` capabilities:
 
 - Register JSON schemas as tracked entity tables.
 - Read and write entities through generated SQL tables.
+- Group related writes in explicit transactions so they commit once.
 - Create named versions of state and write/read across versions.
 - Merge one version into the active version.
 - Query `lix_change` for history, audit, activity feeds, and undo-style features.
@@ -34,6 +35,7 @@ Use this skill when you need to write or debug consumer code using `@lix-js/sdk`
 - Opening a persistent `.lix` file.
 - Registering schemas.
 - Writing and reading generated SQL entity tables.
+- Grouping imports, migrations, and batch writes into one transaction.
 - Reading `execute()` results.
 - Creating, switching, previewing, and merging versions.
 - Querying history through `lix_change`.
@@ -45,11 +47,12 @@ Do not use this skill for raw SQLite access, private engine/wasm internals, SDK
 
 1. Install `@lix-js/sdk` and `better-sqlite3`.
 2. Open with `createBetterSqlite3Backend({ path })`; do not open `.lix` with raw SQLite.
-3. Register a schema with `x-lix-key`, `x-lix-version`, `x-lix-primary-key`, and `additionalProperties: false`.
+3. Register a schema with `x-lix-key`, `x-lix-primary-key`, and `additionalProperties: false`.
 4. Write rows through the generated table named by `x-lix-key`.
-5. Use `<schema>_by_version` plus `lixcol_version_id` for side-by-side version reads/writes.
-6. Query `lix_change` for audit/history instead of hand-rolling audit tables.
-7. Wrap `mergeVersion()` in `try/catch` whenever conflicts are possible.
+5. Use `beginTransaction()` for imports, migrations, and multi-row writes that should be one commit.
+6. Use `<schema>_by_version` plus `lixcol_version_id` for side-by-side version reads/writes.
+7. Query `lix_change` for audit/history instead of hand-rolling audit tables.
+8. Wrap `mergeVersion()` in `try/catch` whenever conflicts are possible.
 
 ## Core Rules
 
@@ -57,6 +60,9 @@ Do not use this skill for raw SQLite access, private engine/wasm internals, SDK
 - Use `createBetterSqlite3Backend()` for persistent apps, demos, and tests.
 - Use numbered SQL placeholders: `$1`, `$2`, `$3`; bare `?` is rejected.
 - Use `lix_json($1)` when inserting JSON text into JSON-typed columns.
+- Use scalar SQL functions `SELECT lix_uuid_v7()` and `SELECT lix_timestamp()` when consumer code needs Lix-generated UUID v7 ids or ISO timestamps. Do not call them as table functions with `SELECT * FROM ...`.
+- Use `beginTransaction()` for batch writes. One `lix.execute()` write is one transaction and therefore one commit.
+- Do not call `execute()` through the parent `lix` handle while a transaction is active; use the transaction handle for reads and writes until `commit()` or `rollback()`.
 - Use stable, namespaced, lowercase schema keys like `acme_section`, not generic names like `task`.
 - Always include `x-lix-primary-key` and `additionalProperties: false` on app schemas.
 - Use version names from the user's vocabulary, such as `"Marketing edit"` or `"Q3 pricing draft"`.
@@ -134,7 +140,6 @@ await lix.execute(
     JSON.stringify({
       $schema: "https://json-schema.org/draft/2020-12/schema",
       "x-lix-key": "acme_note",
-      "x-lix-version": "1",
       "x-lix-primary-key": ["/id"],
       type: "object",
       required: ["id", "title", "done"],
@@ -203,6 +208,38 @@ Accessors return `undefined` when the cell kind does not match. Branch on `value
 
 `Row` also has convenience methods when native JS values are enough: `get(name)`, `tryGet(name)`, `getAt(index)`, `toObject()`, and `toValueMap()`.
 
+## Transactions
+
+Use `beginTransaction()` whenever several writes belong to one logical operation: CSV imports, seed scripts, migrations, bulk updates, or multi-table changes. A write through `lix.execute()` opens and commits its own transaction, so thousands of separate `execute()` writes become thousands of commits. A transaction handle stages those writes and commits them together.
+
+```ts
+const tx = await lix.beginTransaction();
+
+try {
+  for (const note of notes) {
+    await tx.execute(
+      "INSERT INTO acme_note (id, title, done) VALUES ($1, $2, $3)",
+      [note.id, note.title, false],
+    );
+  }
+
+  await tx.commit();
+} catch (error) {
+  await tx.rollback();
+  throw error;
+}
+```
+
+Transaction rules:
+
+- `tx.execute()` has the same result shape as `lix.execute()`.
+- Writes are visible to later reads on the same transaction before commit.
+- `commit()` makes the whole transaction durable as one commit.
+- `rollback()` drops the staged writes.
+- After `commit()` or `rollback()`, the transaction handle is closed and cannot be reused.
+- A Lix handle allows one active transaction at a time. While it is active, use `tx.execute()` for reads and writes; parent-handle `lix.execute()` is rejected until the transaction closes.
+- Do not use a callback-style transaction helper. The JS SDK mirrors the Rust SDK shape: explicitly `beginTransaction()`, then `commit()` or `rollback()`.
+
 ## Registering Schemas
 
 Register app schemas by inserting JSON into `lix_registered_schema.value`:
@@ -217,7 +254,7 @@ await lix.execute(
 Schema basics:
 
 - `x-lix-key` becomes the generated SQL table name.
-- `x-lix-version` versions your schema contract.
+- Compatible schema amendments are keyed by `x-lix-key`.
 - `x-lix-primary-key` tells Lix how to derive entity identity.
 - Primary-key entries are JSON Pointers with a leading slash, such as `["/id"]` or `["/owner/email"]`.
 - Use `additionalProperties: false` so accidental fields fail fast.
@@ -229,7 +266,6 @@ Uniqueness is not inferred from ordinary JSON Schema fields. If a non-primary-ke
 ```ts
 const companyDomainSchema = {
   "x-lix-key": "crm_company_domain",
-  "x-lix-version": "1",
   "x-lix-primary-key": ["/id"],
   "x-lix-unique": [["/domain"]],
   type: "object",
@@ -389,7 +425,7 @@ Columns consumers usually need:
 
 `lix_change` is an immutable SQL table of changes across registered schemas and versions. Use it for audit logs, blame, history, activity feeds, and undo-style UI.
 
-Important columns include `id`, `entity_id`, `schema_key`, `schema_version`, `snapshot_content`, `created_at`, and `lixcol_*` metadata.
+Important columns include `id`, `entity_id`, `schema_key`, `snapshot_content`, `created_at`, and `lixcol_*` metadata.
 
 ```ts
 // Audit log for one entity, oldest to newest.
@@ -454,6 +490,8 @@ Other UDFs, such as `lix_json_get`, `lix_uuid_v7`, `lix_text_encode`, and `lix_e
 | Use public imports from `@lix-js/sdk` and `@lix-js/sdk/sqlite`. | Importing `engine-wasm` or private internals. |
 | Use `$1`, `$2`, `$3` placeholders. | Bare `?` placeholders. |
 | Use `lix_json($1)` for JSON parameters. | Inlining stringified JSON directly into SQL. |
+| Use `beginTransaction()` for imports and batch writes that should be one commit. | Loops of standalone `lix.execute()` writes for bulk imports. |
+| Use the transaction handle for reads and writes until it commits or rolls back. | Calling parent-handle `execute()` during an active transaction. |
 | Use `_by_version` for cross-version reads/writes. | Switching versions just to render a side-by-side view. |
 | Name versions in user vocabulary. | User-facing words like branch, branch-1, or generic Draft. |
 | Model collaborative data as small rows. | One giant row when multiple reviewers edit different parts. |

package/dist/engine-wasm/wasm/lix_engine.d.ts

@@ -12,6 +12,10 @@ export class Lix {
      * @returns {Promise<string>}
      */
     activeVersionId(): Promise<string>;
+    /**
+     * @returns {Promise<LixTransaction>}
+     */
+    beginTransaction(): Promise<LixTransaction>;
     /**
      * @returns {Promise<void>}
      */
@@ -25,7 +29,7 @@ export class Lix {
      * Executes one DataFusion SQL statement against this Lix session.
      *
      * The SQL dialect is DataFusion SQL, not SQLite SQL. Positional
-     * placeholders use `$1`, `$2`, and so on. SQLite-specific catalog
+     * placeholders use `?` or `$1`, `$2`, and so on. SQLite-specific catalog
      * tables and transaction statements such as `sqlite_master`, `BEGIN`,
      * and `COMMIT` are not part of this contract; use
      * `information_schema` for catalog inspection.
@@ -50,6 +54,26 @@ export class Lix {
      */
     switchVersion(args: any): Promise<any>;
 }
+export class LixTransaction {
+    static __wrap(ptr: any): any;
+    __destroy_into_raw(): number | undefined;
+    __wbg_ptr: number | undefined;
+    free(): void;
+    /**
+     * @returns {Promise<void>}
+     */
+    commit(): Promise<void>;
+    /**
+     * @param {any} sql
+     * @param {any} params
+     * @returns {Promise<any>}
+     */
+    execute(sql: any, params: any): Promise<any>;
+    /**
+     * @returns {Promise<void>}
+     */
+    rollback(): Promise<void>;
+}
 export function initSync(module: any): any;
 declare function __wbg_init(module_or_path: any): Promise<any>;
 export { __wbg_init as default };

package/dist/engine-wasm/wasm/lix_engine.js

@@ -24,6 +24,13 @@ export class Lix {
         const ret = wasm.lix_activeVersionId(this.__wbg_ptr);
         return ret;
     }
+    /**
+     * @returns {Promise<LixTransaction>}
+     */
+    beginTransaction() {
+        const ret = wasm.lix_beginTransaction(this.__wbg_ptr);
+        return ret;
+    }
     /**
      * @returns {Promise<void>}
      */
@@ -43,7 +50,7 @@ export class Lix {
      * Executes one DataFusion SQL statement against this Lix session.
      *
      * The SQL dialect is DataFusion SQL, not SQLite SQL. Positional
-     * placeholders use `$1`, `$2`, and so on. SQLite-specific catalog
+     * placeholders use `?` or `$1`, `$2`, and so on. SQLite-specific catalog
      * tables and transaction statements such as `sqlite_master`, `BEGIN`,
      * and `COMMIT` are not part of this contract; use
      * `information_schema` for catalog inspection.
@@ -82,6 +89,50 @@ export class Lix {
 }
 if (Symbol.dispose)
     Lix.prototype[Symbol.dispose] = Lix.prototype.free;
+export class LixTransaction {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(LixTransaction.prototype);
+        obj.__wbg_ptr = ptr;
+        LixTransactionFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        LixTransactionFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_lixtransaction_free(ptr, 0);
+    }
+    /**
+     * @returns {Promise<void>}
+     */
+    commit() {
+        const ret = wasm.lixtransaction_commit(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @param {any} sql
+     * @param {any} params
+     * @returns {Promise<any>}
+     */
+    execute(sql, params) {
+        const ret = wasm.lixtransaction_execute(this.__wbg_ptr, sql, params);
+        return ret;
+    }
+    /**
+     * @returns {Promise<void>}
+     */
+    rollback() {
+        const ret = wasm.lixtransaction_rollback(this.__wbg_ptr);
+        return ret;
+    }
+}
+if (Symbol.dispose)
+    LixTransaction.prototype[Symbol.dispose] = LixTransaction.prototype.free;
 /**
  * @param {any | null} [args]
  * @returns {Promise<Lix>}
@@ -295,6 +346,10 @@ function __wbg_get_imports() {
             const ret = Lix.__wrap(arg0);
             return ret;
         },
+        __wbg_lixtransaction_new: function (arg0) {
+            const ret = LixTransaction.__wrap(arg0);
+            return ret;
+        },
         __wbg_new_0_73afc35eb544e539: function () {
             const ret = new Date();
             return ret;
@@ -430,7 +485,7 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function (arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 3067, function: Function { arguments: [Externref], shim_idx: 3068, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 3074, function: Function { arguments: [Externref], shim_idx: 3075, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__h259bf120b5b35fc5, wasm_bindgen__convert__closures_____invoke__ha15a27e9815e3c81);
             return ret;
         },
@@ -482,6 +537,9 @@ function wasm_bindgen__convert__closures_____invoke__h14bc79029e3672a5(arg0, arg
 const LixFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => { }, unregister: () => { } }
     : new FinalizationRegistry(ptr => wasm.__wbg_lix_free(ptr >>> 0, 1));
+const LixTransactionFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => { }, unregister: () => { } }
+    : new FinalizationRegistry(ptr => wasm.__wbg_lixtransaction_free(ptr >>> 0, 1));
 function addToExternrefTable0(obj) {
     const idx = wasm.__externref_table_alloc();
     wasm.__wbindgen_externrefs.set(idx, obj);

package/dist/engine-wasm/wasm/lix_engine.wasm.d.ts

@@ -2,13 +2,18 @@
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
 export const __wbg_lix_free: (a: number, b: number) => void;
+export const __wbg_lixtransaction_free: (a: number, b: number) => void;
 export const lix_activeVersionId: (a: number) => any;
+export const lix_beginTransaction: (a: number) => any;
 export const lix_close: (a: number) => any;
 export const lix_createVersion: (a: number, b: any) => any;
 export const lix_execute: (a: number, b: any, c: any) => any;
 export const lix_mergeVersion: (a: number, b: any) => any;
 export const lix_mergeVersionPreview: (a: number, b: any) => any;
 export const lix_switchVersion: (a: number, b: any) => any;
+export const lixtransaction_commit: (a: number) => any;
+export const lixtransaction_execute: (a: number, b: any, c: any) => any;
+export const lixtransaction_rollback: (a: number) => any;
 export const openLix: (a: number) => any;
 export const wasm_bindgen__closure__destroy__h259bf120b5b35fc5: (a: number, b: number) => void;
 export const wasm_bindgen__convert__closures_____invoke__h14bc79029e3672a5: (a: number, b: number, c: any, d: any) => void;