latticesql 0.16.2 → 0.17.0

package/README.md

@@ -35,6 +35,7 @@ Lattice has no opinions about your schema, your agents, or your file format. You
   - [defineEntityContext()](#defineentitycontext-v05)
   - [defineWriteback()](#definewriteback)
   - [init() / close()](#init--close)
+  - [migrate()](#migrate-v017)
   - [CRUD operations](#crud-operations)
   - [Query operators](#query-operators)
   - [Render, sync, watch, and reconcile](#render-sync-watch-and-reconcile)
@@ -202,11 +203,12 @@ interface TableDefinition {
    * - A render function: (rows: Row[]) => string
    * - A built-in template name: 'default-list' | 'default-table' | 'default-detail' | 'default-json'
    * - A template spec with hooks: { template: BuiltinTemplateName, hooks?: RenderHooks }
+   * Optional (v0.17+) — omit render and outputFile for schema-only tables.
    */
-  render: RenderSpec;
+  render?: RenderSpec;
 
-  /** Output file path, relative to the outputDir passed to render()/watch() */
-  outputFile: string;
+  /** Output file path, relative to the outputDir passed to render()/watch(). Optional (v0.17+). */
+  outputFile?: string;
 
   /** Optional row filter applied before rendering */
   filter?: (rows: Row[]) => Row[];
@@ -215,10 +217,12 @@ interface TableDefinition {
    * Primary key column name or [col1, col2] for composite PKs.
    * Defaults to 'id'. When 'id' is the PK and the field is absent on insert,
    * a UUID v4 is generated automatically.
+   * Composite PKs (v0.17+): auto-generates a PRIMARY KEY(...) constraint —
+   * no need to add it manually via tableConstraints.
    */
   primaryKey?: string | string[];
 
-  /** Additional SQL constraints (required for composite PKs) */
+  /** Additional SQL constraints (e.g., UNIQUE, CHECK). No longer required for composite PKs (v0.17+). */
   tableConstraints?: string[];
 
   /** Declared relationships used by template rendering */
@@ -267,6 +271,22 @@ await db.update('pages', 'about-us', { title: 'About' });
 await db.delete('pages', 'about-us');
 ```
 
+**Schema-only table (v0.17+):**
+
+Tables without `render` and `outputFile` get full schema support (columns, indexes, constraints, CRUD) but produce no output files during `render()` or `watch()`. Useful for junction tables, internal tracking tables, or any table that doesn't need a context file.
+
+```typescript
+db.define('agent_skills', {
+  columns: {
+    agent_id: 'TEXT NOT NULL',
+    skill_id: 'TEXT NOT NULL',
+    proficiency: 'TEXT DEFAULT "basic"',
+  },
+  primaryKey: ['agent_id', 'skill_id'],
+  // No render, no outputFile — schema-only
+});
+```
+
 **Composite primary key:**
 
 ```typescript
@@ -276,7 +296,6 @@ db.define('event_seats', {
     seat_no: 'INTEGER NOT NULL',
     holder: 'TEXT',
   },
-  tableConstraints: ['PRIMARY KEY (event_id, seat_no)'],
   primaryKey: ['event_id', 'seat_no'],
   render: 'default-table',
   outputFile: 'seats.md',
@@ -835,6 +854,26 @@ Migrations are idempotent — each `version` number is applied exactly once, tra
 
 `close()` closes the SQLite connection. Call it when the process shuts down.
 
+### `migrate()` (v0.17+)
+
+```typescript
+await db.migrate(migrations: Migration[]): Promise<void>
+```
+
+Run migrations after `init()`. Works exactly like `init({ migrations })` but callable any time — useful when migrations are loaded dynamically or added by plugins after startup.
+
+```typescript
+await db.init();
+
+// Later — e.g., after loading a plugin that needs new columns
+await db.migrate([
+  { version: 'plugin-v1', sql: 'ALTER TABLE tasks ADD COLUMN tags TEXT' },
+  { version: 'plugin-v2', sql: 'CREATE INDEX IF NOT EXISTS idx_tasks_tags ON tasks (tags)' },
+]);
+```
+
+`Migration.version` accepts `number | string` — use numbers for sequential migrations, or strings for named/namespaced versions (e.g., `'plugin-v1'`). Each version is applied at most once, tracked in the same `__lattice_migrations` table used by `init()`.
+
 ---
 
 ### CRUD operations
@@ -860,6 +899,24 @@ await db.insert('pages', { slug: 'about', title: 'About Us' });
 await db.insert('tasks', { id: 'task-001', title: 'Specific task' });
 ```
 
+#### `insertReturning()` (v0.17+)
+
+```typescript
+await db.insertReturning(table: string, row: Row): Promise<Row>
+```
+
+Insert a row and get the full row back — including the auto-generated `id`, defaults, and any other columns. Equivalent to `insert()` + `get()` in a single call.
+
+```typescript
+const task = await db.insertReturning('tasks', { title: 'Write docs', status: 'open' });
+// task → { id: 'f47ac10b-...', title: 'Write docs', status: 'open', priority: 0, ... }
+
+// Useful when you need the generated id or default values immediately
+const agent = await db.insertReturning('agents', { name: 'Gamma' });
+console.log(agent.id); // auto-generated UUID
+console.log(agent.active); // default value from schema
+```
+
 #### `upsert()`
 
 ```typescript
@@ -899,6 +956,23 @@ await db.update('tasks', 'task-001', { status: 'done' });
 await db.update('event_seats', { event_id: 'e-1', seat_no: 3 }, { holder: 'Bob' });
 ```
 
+#### `updateReturning()` (v0.17+)
+
+```typescript
+await db.updateReturning(table: string, id: PkLookup, row: Partial<Row>): Promise<Row>
+```
+
+Update specific columns and get the full updated row back. Equivalent to `update()` + `get()` in a single call.
+
+```typescript
+const task = await db.updateReturning('tasks', 'task-001', { status: 'done' });
+// task → { id: 'task-001', title: 'Write docs', status: 'done', priority: 3, ... }
+
+// Composite PK
+const seat = await db.updateReturning('event_seats', { event_id: 'e-1', seat_no: 3 }, { holder: 'Bob' });
+// seat → { event_id: 'e-1', seat_no: 3, holder: 'Bob' }
+```
+
 #### `delete()`
 
 ```typescript

package/dist/cli.js

@@ -492,24 +492,37 @@ var SchemaManager = class {
    */
   applySchema(adapter) {
     for (const [name, def] of this._tables) {
-      this._ensureTable(adapter, name, def.columns, def.tableConstraints);
+      const pkCols = this._tablePK.get(name) ?? ["id"];
+      let constraints = def.tableConstraints ? [...def.tableConstraints] : [];
+      if (pkCols.length > 1) {
+        const alreadyHasPK = constraints.some((c) => c.toUpperCase().startsWith("PRIMARY KEY"));
+        if (!alreadyHasPK) {
+          constraints.unshift(`PRIMARY KEY (${pkCols.map((c) => `"${c}"`).join(", ")})`);
+        }
+      }
+      this._ensureTable(adapter, name, def.columns, constraints.length ? constraints : void 0);
     }
     this._ensureTable(adapter, "__lattice_migrations", {
-      version: "INTEGER PRIMARY KEY",
+      version: "TEXT PRIMARY KEY",
       applied_at: "TEXT NOT NULL"
     });
   }
   /** Run explicit versioned migrations in order, idempotently */
   applyMigrations(adapter, migrations) {
-    const sorted = [...migrations].sort((a, b) => a.version - b.version);
+    const sorted = [...migrations].sort((a, b) => {
+      const va = String(a.version);
+      const vb = String(b.version);
+      return va.localeCompare(vb, void 0, { numeric: true });
+    });
     for (const m of sorted) {
+      const versionStr = String(m.version);
       const exists = adapter.get("SELECT 1 FROM __lattice_migrations WHERE version = ?", [
-        m.version
+        versionStr
       ]);
       if (!exists) {
         adapter.run(m.sql);
         adapter.run("INSERT INTO __lattice_migrations (version, applied_at) VALUES (?, ?)", [
-          m.version,
+          versionStr,
           (/* @__PURE__ */ new Date()).toISOString()
         ]);
       }
@@ -1612,7 +1625,8 @@ var Lattice = class {
     this._assertNotInit("define");
     const compiledDef = {
       ...def,
-      render: compileRender(def, table, this._schema, this._adapter)
+      render: def.render ? compileRender(def, table, this._schema, this._adapter) : () => "",
+      outputFile: def.outputFile ?? `.schema-only/${table}.md`
     };
     this._schema.define(table, compiledDef);
     return this;
@@ -1654,6 +1668,23 @@ var Lattice = class {
     this._initialized = true;
     return Promise.resolve();
   }
+  /**
+   * Run additional migrations after init(). Useful for package-level schema
+   * changes applied at runtime (e.g. update hooks that add columns).
+   *
+   * @since 0.17.0
+   */
+  migrate(migrations) {
+    if (!this._initialized) {
+      return Promise.reject(new Error("Lattice: not initialized \u2014 call init() first"));
+    }
+    this._schema.applyMigrations(this._adapter, migrations);
+    for (const tableName of this._schema.getTables().keys()) {
+      const rows = this._adapter.all(`PRAGMA table_info("${tableName}")`);
+      this._columnCache.set(tableName, new Set(rows.map((r) => r.name)));
+    }
+    return Promise.resolve();
+  }
   close() {
     this._adapter.close();
     this._columnCache.clear();
@@ -1686,6 +1717,17 @@ var Lattice = class {
     this._fireWriteHooks(table, "insert", rowWithPk, pkValue);
     return Promise.resolve(pkValue);
   }
+  /**
+   * Insert a row and return the full inserted row (including auto-generated
+   * fields and defaults). Equivalent to `insert()` followed by `get()`.
+   *
+   * @since 0.17.0
+   */
+  insertReturning(table, row) {
+    return this.insert(table, row).then(
+      (pk) => this.get(table, pk).then((result) => result ?? { ...row, id: pk })
+    );
+  }
   upsert(table, row) {
     const notInit = this._notInitError();
     if (notInit) return notInit;
@@ -1740,6 +1782,17 @@ var Lattice = class {
     this._fireWriteHooks(table, "update", sanitized, auditId, Object.keys(sanitized));
     return Promise.resolve();
   }
+  /**
+   * Update a row and return the full updated row. Equivalent to `update()`
+   * followed by `get()`.
+   *
+   * @since 0.17.0
+   */
+  updateReturning(table, id, row) {
+    return this.update(table, id, row).then(
+      () => this.get(table, id).then((result) => result ?? row)
+    );
+  }
   delete(table, id) {
     const notInit = this._notInitError();
     if (notInit) return notInit;

package/dist/index.cjs

@@ -240,24 +240,37 @@ var SchemaManager = class {
    */
   applySchema(adapter) {
     for (const [name, def] of this._tables) {
-      this._ensureTable(adapter, name, def.columns, def.tableConstraints);
+      const pkCols = this._tablePK.get(name) ?? ["id"];
+      let constraints = def.tableConstraints ? [...def.tableConstraints] : [];
+      if (pkCols.length > 1) {
+        const alreadyHasPK = constraints.some((c) => c.toUpperCase().startsWith("PRIMARY KEY"));
+        if (!alreadyHasPK) {
+          constraints.unshift(`PRIMARY KEY (${pkCols.map((c) => `"${c}"`).join(", ")})`);
+        }
+      }
+      this._ensureTable(adapter, name, def.columns, constraints.length ? constraints : void 0);
     }
     this._ensureTable(adapter, "__lattice_migrations", {
-      version: "INTEGER PRIMARY KEY",
+      version: "TEXT PRIMARY KEY",
       applied_at: "TEXT NOT NULL"
     });
   }
   /** Run explicit versioned migrations in order, idempotently */
   applyMigrations(adapter, migrations) {
-    const sorted = [...migrations].sort((a, b) => a.version - b.version);
+    const sorted = [...migrations].sort((a, b) => {
+      const va = String(a.version);
+      const vb = String(b.version);
+      return va.localeCompare(vb, void 0, { numeric: true });
+    });
     for (const m of sorted) {
+      const versionStr = String(m.version);
       const exists = adapter.get("SELECT 1 FROM __lattice_migrations WHERE version = ?", [
-        m.version
+        versionStr
       ]);
       if (!exists) {
         adapter.run(m.sql);
         adapter.run("INSERT INTO __lattice_migrations (version, applied_at) VALUES (?, ?)", [
-          m.version,
+          versionStr,
           (/* @__PURE__ */ new Date()).toISOString()
         ]);
       }
@@ -1648,7 +1661,8 @@ var Lattice = class {
     this._assertNotInit("define");
     const compiledDef = {
       ...def,
-      render: compileRender(def, table, this._schema, this._adapter)
+      render: def.render ? compileRender(def, table, this._schema, this._adapter) : () => "",
+      outputFile: def.outputFile ?? `.schema-only/${table}.md`
     };
     this._schema.define(table, compiledDef);
     return this;
@@ -1690,6 +1704,23 @@ var Lattice = class {
     this._initialized = true;
     return Promise.resolve();
   }
+  /**
+   * Run additional migrations after init(). Useful for package-level schema
+   * changes applied at runtime (e.g. update hooks that add columns).
+   *
+   * @since 0.17.0
+   */
+  migrate(migrations) {
+    if (!this._initialized) {
+      return Promise.reject(new Error("Lattice: not initialized \u2014 call init() first"));
+    }
+    this._schema.applyMigrations(this._adapter, migrations);
+    for (const tableName of this._schema.getTables().keys()) {
+      const rows = this._adapter.all(`PRAGMA table_info("${tableName}")`);
+      this._columnCache.set(tableName, new Set(rows.map((r) => r.name)));
+    }
+    return Promise.resolve();
+  }
   close() {
     this._adapter.close();
     this._columnCache.clear();
@@ -1722,6 +1753,17 @@ var Lattice = class {
     this._fireWriteHooks(table, "insert", rowWithPk, pkValue);
     return Promise.resolve(pkValue);
   }
+  /**
+   * Insert a row and return the full inserted row (including auto-generated
+   * fields and defaults). Equivalent to `insert()` followed by `get()`.
+   *
+   * @since 0.17.0
+   */
+  insertReturning(table, row) {
+    return this.insert(table, row).then(
+      (pk) => this.get(table, pk).then((result) => result ?? { ...row, id: pk })
+    );
+  }
   upsert(table, row) {
     const notInit = this._notInitError();
     if (notInit) return notInit;
@@ -1776,6 +1818,17 @@ var Lattice = class {
     this._fireWriteHooks(table, "update", sanitized, auditId, Object.keys(sanitized));
     return Promise.resolve();
   }
+  /**
+   * Update a row and return the full updated row. Equivalent to `update()`
+   * followed by `get()`.
+   *
+   * @since 0.17.0
+   */
+  updateReturning(table, id, row) {
+    return this.update(table, id, row).then(
+      () => this.get(table, id).then((result) => result ?? row)
+    );
+  }
   delete(table, id) {
     const notInit = this._notInitError();
     if (notInit) return notInit;

package/dist/index.d.cts

@@ -714,9 +714,9 @@ interface TableDefinition {
      *   `'default-detail'`, `'default-json'`) to use a built-in template.
      * - Pass a `TemplateRenderSpec` to use a built-in template with lifecycle hooks.
      */
-    render: RenderSpec;
+    render?: RenderSpec;
     /** Output path relative to the outputDir passed to render/watch */
-    outputFile: string;
+    outputFile?: string;
     /** Optional pre-filter applied before render */
     filter?: (rows: Row[]) => Row[];
     /**
@@ -825,7 +825,7 @@ interface InitOptions {
     migrations?: Migration[];
 }
 interface Migration {
-    version: number;
+    version: number | string;
     sql: string;
 }
 interface WatchOptions {
@@ -1110,11 +1110,32 @@ declare class Lattice {
     defineWriteHook(hook: WriteHook): this;
     defineWriteback(def: WritebackDefinition): this;
     init(options?: InitOptions): Promise<void>;
+    /**
+     * Run additional migrations after init(). Useful for package-level schema
+     * changes applied at runtime (e.g. update hooks that add columns).
+     *
+     * @since 0.17.0
+     */
+    migrate(migrations: Migration[]): Promise<void>;
     close(): void;
     insert(table: string, row: Row): Promise<string>;
+    /**
+     * Insert a row and return the full inserted row (including auto-generated
+     * fields and defaults). Equivalent to `insert()` followed by `get()`.
+     *
+     * @since 0.17.0
+     */
+    insertReturning(table: string, row: Row): Promise<Row>;
     upsert(table: string, row: Row): Promise<string>;
     upsertBy(table: string, col: string, val: unknown, row: Row): Promise<string>;
     update(table: string, id: PkLookup, row: Partial<Row>): Promise<void>;
+    /**
+     * Update a row and return the full updated row. Equivalent to `update()`
+     * followed by `get()`.
+     *
+     * @since 0.17.0
+     */
+    updateReturning(table: string, id: PkLookup, row: Partial<Row>): Promise<Row>;
     delete(table: string, id: PkLookup): Promise<void>;
     get(table: string, id: PkLookup): Promise<Row | null>;
     /**

package/dist/index.d.ts

@@ -714,9 +714,9 @@ interface TableDefinition {
      *   `'default-detail'`, `'default-json'`) to use a built-in template.
      * - Pass a `TemplateRenderSpec` to use a built-in template with lifecycle hooks.
      */
-    render: RenderSpec;
+    render?: RenderSpec;
     /** Output path relative to the outputDir passed to render/watch */
-    outputFile: string;
+    outputFile?: string;
     /** Optional pre-filter applied before render */
     filter?: (rows: Row[]) => Row[];
     /**
@@ -825,7 +825,7 @@ interface InitOptions {
     migrations?: Migration[];
 }
 interface Migration {
-    version: number;
+    version: number | string;
     sql: string;
 }
 interface WatchOptions {
@@ -1110,11 +1110,32 @@ declare class Lattice {
     defineWriteHook(hook: WriteHook): this;
     defineWriteback(def: WritebackDefinition): this;
     init(options?: InitOptions): Promise<void>;
+    /**
+     * Run additional migrations after init(). Useful for package-level schema
+     * changes applied at runtime (e.g. update hooks that add columns).
+     *
+     * @since 0.17.0
+     */
+    migrate(migrations: Migration[]): Promise<void>;
     close(): void;
     insert(table: string, row: Row): Promise<string>;
+    /**
+     * Insert a row and return the full inserted row (including auto-generated
+     * fields and defaults). Equivalent to `insert()` followed by `get()`.
+     *
+     * @since 0.17.0
+     */
+    insertReturning(table: string, row: Row): Promise<Row>;
     upsert(table: string, row: Row): Promise<string>;
     upsertBy(table: string, col: string, val: unknown, row: Row): Promise<string>;
     update(table: string, id: PkLookup, row: Partial<Row>): Promise<void>;
+    /**
+     * Update a row and return the full updated row. Equivalent to `update()`
+     * followed by `get()`.
+     *
+     * @since 0.17.0
+     */
+    updateReturning(table: string, id: PkLookup, row: Partial<Row>): Promise<Row>;
     delete(table: string, id: PkLookup): Promise<void>;
     get(table: string, id: PkLookup): Promise<Row | null>;
     /**

package/dist/index.js

@@ -178,24 +178,37 @@ var SchemaManager = class {
    */
   applySchema(adapter) {
     for (const [name, def] of this._tables) {
-      this._ensureTable(adapter, name, def.columns, def.tableConstraints);
+      const pkCols = this._tablePK.get(name) ?? ["id"];
+      let constraints = def.tableConstraints ? [...def.tableConstraints] : [];
+      if (pkCols.length > 1) {
+        const alreadyHasPK = constraints.some((c) => c.toUpperCase().startsWith("PRIMARY KEY"));
+        if (!alreadyHasPK) {
+          constraints.unshift(`PRIMARY KEY (${pkCols.map((c) => `"${c}"`).join(", ")})`);
+        }
+      }
+      this._ensureTable(adapter, name, def.columns, constraints.length ? constraints : void 0);
     }
     this._ensureTable(adapter, "__lattice_migrations", {
-      version: "INTEGER PRIMARY KEY",
+      version: "TEXT PRIMARY KEY",
       applied_at: "TEXT NOT NULL"
     });
   }
   /** Run explicit versioned migrations in order, idempotently */
   applyMigrations(adapter, migrations) {
-    const sorted = [...migrations].sort((a, b) => a.version - b.version);
+    const sorted = [...migrations].sort((a, b) => {
+      const va = String(a.version);
+      const vb = String(b.version);
+      return va.localeCompare(vb, void 0, { numeric: true });
+    });
     for (const m of sorted) {
+      const versionStr = String(m.version);
       const exists = adapter.get("SELECT 1 FROM __lattice_migrations WHERE version = ?", [
-        m.version
+        versionStr
       ]);
       if (!exists) {
         adapter.run(m.sql);
         adapter.run("INSERT INTO __lattice_migrations (version, applied_at) VALUES (?, ?)", [
-          m.version,
+          versionStr,
           (/* @__PURE__ */ new Date()).toISOString()
         ]);
       }
@@ -1586,7 +1599,8 @@ var Lattice = class {
     this._assertNotInit("define");
     const compiledDef = {
       ...def,
-      render: compileRender(def, table, this._schema, this._adapter)
+      render: def.render ? compileRender(def, table, this._schema, this._adapter) : () => "",
+      outputFile: def.outputFile ?? `.schema-only/${table}.md`
     };
     this._schema.define(table, compiledDef);
     return this;
@@ -1628,6 +1642,23 @@ var Lattice = class {
     this._initialized = true;
     return Promise.resolve();
   }
+  /**
+   * Run additional migrations after init(). Useful for package-level schema
+   * changes applied at runtime (e.g. update hooks that add columns).
+   *
+   * @since 0.17.0
+   */
+  migrate(migrations) {
+    if (!this._initialized) {
+      return Promise.reject(new Error("Lattice: not initialized \u2014 call init() first"));
+    }
+    this._schema.applyMigrations(this._adapter, migrations);
+    for (const tableName of this._schema.getTables().keys()) {
+      const rows = this._adapter.all(`PRAGMA table_info("${tableName}")`);
+      this._columnCache.set(tableName, new Set(rows.map((r) => r.name)));
+    }
+    return Promise.resolve();
+  }
   close() {
     this._adapter.close();
     this._columnCache.clear();
@@ -1660,6 +1691,17 @@ var Lattice = class {
     this._fireWriteHooks(table, "insert", rowWithPk, pkValue);
     return Promise.resolve(pkValue);
   }
+  /**
+   * Insert a row and return the full inserted row (including auto-generated
+   * fields and defaults). Equivalent to `insert()` followed by `get()`.
+   *
+   * @since 0.17.0
+   */
+  insertReturning(table, row) {
+    return this.insert(table, row).then(
+      (pk) => this.get(table, pk).then((result) => result ?? { ...row, id: pk })
+    );
+  }
   upsert(table, row) {
     const notInit = this._notInitError();
     if (notInit) return notInit;
@@ -1714,6 +1756,17 @@ var Lattice = class {
     this._fireWriteHooks(table, "update", sanitized, auditId, Object.keys(sanitized));
     return Promise.resolve();
   }
+  /**
+   * Update a row and return the full updated row. Equivalent to `update()`
+   * followed by `get()`.
+   *
+   * @since 0.17.0
+   */
+  updateReturning(table, id, row) {
+    return this.update(table, id, row).then(
+      () => this.get(table, id).then((result) => result ?? row)
+    );
+  }
   delete(table, id) {
     const notInit = this._notInitError();
     if (notInit) return notInit;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "latticesql",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "Persistent structured memory for AI agent systems — SQLite ↔ LLM context bridge",
   "type": "module",
   "main": "./dist/index.js",