picovolt 1.6.0 → 1.7.0

package/README.md

@@ -1,7 +1,7 @@
 # PicoVolt (PVDB)
 
 [![CI](https://github.com/MiniJe/picovolt/actions/workflows/ci.yml/badge.svg)](https://github.com/MiniJe/picovolt/actions/workflows/ci.yml)
-[![Version](https://img.shields.io/badge/version-1.6.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.7.0-blue.svg)](CHANGELOG.md)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 ![Status: 1.0 stable](https://img.shields.io/badge/status-1.0%20stable-brightgreen.svg)
 [![GitHub stars](https://img.shields.io/github/stars/MiniJe/picovolt?style=social)](https://github.com/MiniJe/picovolt)
@@ -122,20 +122,18 @@ Install the first-class CLI with `cargo install picovolt`, then use `pv query`,
 Rust, Python, Go, Node, and browser projects are in [`starters/`](starters/README.md); supported adapters
 are catalogued in [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md).
 
-SQL supported: `CREATE TABLE [IF NOT EXISTS]` with `PRIMARY KEY`, `UNIQUE`, and `NOT NULL`,
-`CREATE [UNIQUE] INDEX ON t (col)`, single- and multi-row `INSERT`,
-`UPDATE ... SET ... WHERE`, `DELETE ... WHERE`, `DROP TABLE [IF EXISTS]`, and
-`SELECT [DISTINCT] {* | col [AS alias], ... | COUNT/SUM/MIN/MAX/AVG(...) [AS alias]}
-FROM t [WHERE <pred>] [GROUP BY cols] [HAVING <pred>] [BEFORE tx]
-[ORDER BY col [ASC|DESC], ...] [LIMIT n] [OFFSET n]`, where `<pred>` combines
-`col <op> value` (`=`, `!=`, `<`, `<=`, `>`, `>=`, `LIKE`, `NOT LIKE`),
-`col [NOT] IN (...)`, `col [NOT] BETWEEN a AND b`, and `col IS [NOT] NULL` with
-`AND`, `OR`, and parentheses. Integer and decimal values compare by magnitude.
-Two-table equality `INNER`/`LEFT JOIN` queries support qualified references,
-projection, aliases, `DISTINCT`, filters, ordering, and pagination. Rust callers
-can cache `Database::prepare(...)` templates and use explicit transaction
-lifecycle methods or atomic `Database::transaction(...)` closures with both
-filesystem and in-memory databases.
+SQL supports the normal PicoVolt CRUD and schema statements plus projection,
+filters, aggregates, grouping, time travel, ordering, and pagination. The 1.7
+query surface adds `AS`/bare table aliases, N-table equality `INNER`/`LEFT`
+joins, searched `CASE WHEN`, and the focused `LOWER`, `UPPER`, `TRIM`, `LENGTH`,
+`ABS`, `COALESCE`, and `NULLIF` scalar functions. Schema-light types, literal
+defaults, named inserts, and persisted `CHECK` constraints cover common adapter
+DDL. See the precise syntax, examples, type behavior, and deliberate limits in
+[`docs/SQL.md`](docs/SQL.md). Rust callers can cache `Database::prepare(...)`
+templates; C, WebAssembly, JavaScript, Python, and Go expose the same reusable
+prepared-statement lifecycle. Callers can use explicit transactions or atomic
+`Database::transaction(...)` closures with both filesystem and in-memory
+databases.
 Durability is selectable via `Database::set_durability` (`Fast` OS-cache default,
 or crash-safe `Sync` with fsync and an atomic manifest).
 
@@ -147,8 +145,8 @@ lookups roughly 11,000 times faster than a scan, plus range predicates), MVCC
 time-travel, opt-in crash-safe durability (`Durability::Sync`), and a fast
 compile-and-publish path (CAS dedup, columnar compression, memory-mappable
 single-file artifacts). Current limits include full-workspace transaction
-backups rather than an incremental WAL, only basic two-table equality joins,
-and no concurrent writers.
+backups rather than an incremental WAL, left-deep equality joins rather than a
+general SQL planner, and no concurrent writers.
 
 ## Install and distribution
 

package/browser.js

@@ -1,10 +1,40 @@
 // Durable browser helper backed by the Origin Private File System (OPFS).
 import { Db } from "./picovolt.js";
 
+export class PersistentStatement {
+  constructor(database, source) {
+    this.database = database;
+    this.source = source;
+    this._prepared = database.db.prepare(source);
+    this.parameterCount = this._prepared.parameterCount;
+  }
+
+  query(params = []) {
+    if (!this._prepared) throw new Error("PicoVolt prepared statement is closed");
+    this.database._assertOpen();
+    return JSON.parse(this._prepared.execute(this.database.db, params));
+  }
+
+  close() {
+    if (!this._prepared) return false;
+    const prepared = this._prepared;
+    this._prepared = undefined;
+    this.database._statements.delete(this);
+    prepared.free();
+    return true;
+  }
+
+  finalize() {
+    return this.close();
+  }
+}
+
 export class PersistentDb {
   constructor(name, db) {
     this.name = name;
     this.db = db;
+    this._closed = false;
+    this._statements = new Set();
   }
 
   static async open(name = "picovolt.pvdb") {
@@ -20,11 +50,20 @@ export class PersistentDb {
   }
 
   query(sql, params) {
+    this._assertOpen();
     const json = params === undefined ? this.db.query(sql) : this.db.query(sql, params);
     return JSON.parse(json);
   }
 
+  prepare(sql) {
+    this._assertOpen();
+    const statement = new PersistentStatement(this, sql);
+    this._statements.add(statement);
+    return statement;
+  }
+
   async save() {
+    this._assertOpen();
     const root = await navigator.storage.getDirectory();
     const handle = await root.getFileHandle(this.name, { create: true });
     const writable = await handle.createWritable();
@@ -33,7 +72,15 @@ export class PersistentDb {
   }
 
   async close() {
+    if (this._closed) return;
     await this.save();
+    for (const statement of [...this._statements]) statement.close();
+    this.db.free();
+    this._closed = true;
+  }
+
+  _assertOpen() {
+    if (this._closed) throw new Error("PicoVolt database is closed");
   }
 }
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "picovolt",
   "type": "module",
   "description": "PicoVolt (PVDB): a polymorphic embedded database engine in Rust.",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/picovolt.d.ts

@@ -44,6 +44,12 @@ export class Db {
      * as queries touch them. `totalSize` is the image's byte length.
      */
     static openRemote(read: Function, total_size: number): Db;
+    /**
+     * Validate and retain a reusable SQL template. Preparation verifies the
+     * syntax and records the exact positional-parameter count without running
+     * the statement.
+     */
+    prepare(sql: string): PreparedStatement;
     /**
      * Run one SQL statement, optionally binding `?` placeholders to `params` (a
      * JS array, e.g. `db.query("SELECT * FROM t WHERE id = ?", [1])`). Returns a
@@ -62,3 +68,21 @@ export class Db {
      */
     tables(): string;
 }
+
+/**
+ * A validated, reusable SQL template for the raw WebAssembly API.
+ */
+export class PreparedStatement {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Execute this statement against `db`, returning the same JSON string as
+     * [`Db::query`]. The statement can be reused with different parameters.
+     */
+    execute(db: Db, params: any): string;
+    /**
+     * Number of positional `?` values required by this statement.
+     */
+    readonly parameterCount: number;
+}

package/picovolt.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./picovolt_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    Db
+    Db, PreparedStatement
 } from "./picovolt_bg.js";

package/picovolt_bg.js

@@ -106,6 +106,22 @@ export class Db {
         }
         return Db.__wrap(ret[0]);
     }
+    /**
+     * Validate and retain a reusable SQL template. Preparation verifies the
+     * syntax and records the exact positional-parameter count without running
+     * the statement.
+     * @param {string} sql
+     * @returns {PreparedStatement}
+     */
+    prepare(sql) {
+        const ptr0 = passStringToWasm0(sql, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.db_prepare(this.__wbg_ptr, ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return PreparedStatement.__wrap(ret[0]);
+    }
     /**
      * Run one SQL statement, optionally binding `?` placeholders to `params` (a
      * JS array, e.g. `db.query("SELECT * FROM t WHERE id = ?", [1])`). Returns a
@@ -170,6 +186,63 @@ export class Db {
     }
 }
 if (Symbol.dispose) Db.prototype[Symbol.dispose] = Db.prototype.free;
+
+/**
+ * A validated, reusable SQL template for the raw WebAssembly API.
+ */
+export class PreparedStatement {
+    static __wrap(ptr) {
+        const obj = Object.create(PreparedStatement.prototype);
+        obj.__wbg_ptr = ptr;
+        PreparedStatementFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        PreparedStatementFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_preparedstatement_free(ptr, 0);
+    }
+    /**
+     * Execute this statement against `db`, returning the same JSON string as
+     * [`Db::query`]. The statement can be reused with different parameters.
+     * @param {Db} db
+     * @param {any} params
+     * @returns {string}
+     */
+    execute(db, params) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            _assertClass(db, Db);
+            const ret = wasm.preparedstatement_execute(this.__wbg_ptr, db.__wbg_ptr, params);
+            var ptr1 = ret[0];
+            var len1 = ret[1];
+            if (ret[3]) {
+                ptr1 = 0; len1 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
+    /**
+     * Number of positional `?` values required by this statement.
+     * @returns {number}
+     */
+    get parameterCount() {
+        const ret = wasm.preparedstatement_parameterCount(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+}
+if (Symbol.dispose) PreparedStatement.prototype[Symbol.dispose] = PreparedStatement.prototype.free;
 export function __wbg___wbindgen_boolean_get_c9c83ebd41b34df3(arg0) {
     const v = arg0;
     const ret = typeof(v) === 'boolean' ? v : undefined;
@@ -240,6 +313,10 @@ export function __wbg_instanceof_Uint8Array_f935dbb0aa7cdeed(arg0) {
     const ret = result;
     return ret;
 }
+export function __wbg_isArray_6339f732981044bf(arg0) {
+    const ret = Array.isArray(arg0);
+    return ret;
+}
 export function __wbg_length_36bd29c6848c2144(arg0) {
     const ret = arg0.length;
     return ret;
@@ -284,6 +361,9 @@ export function __wbindgen_init_externref_table() {
 const DbFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_db_free(ptr, 1));
+const PreparedStatementFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_preparedstatement_free(ptr, 1));
 
 function addToExternrefTable0(obj) {
     const idx = wasm.__externref_table_alloc();
@@ -291,6 +371,12 @@ function addToExternrefTable0(obj) {
     return idx;
 }
 
+function _assertClass(instance, klass) {
+    if (!(instance instanceof klass)) {
+        throw new Error(`expected instance of ${klass.name}`);
+    }
+}
+
 function debugString(val) {
     // primitive types
     const type = typeof val;

package/sqlite.js

@@ -30,13 +30,19 @@ function normalizeParams(args) {
 
 class Statement {
   constructor(db, sql) {
+    db._assertOpen();
     this._db = db;
     this.source = sql;
+    this._prepared = db._db.prepare(sql);
+    this.parameterCount = this._prepared.parameterCount;
+    db._statements.add(this);
   }
 
   _exec(args) {
+    if (!this._prepared) throw new Error("PicoVolt prepared statement is closed");
+    this._db._assertOpen();
     const params = normalizeParams(args);
-    const json = params.length ? this._db._db.query(this.source, params) : this._db._db.query(this.source);
+    const json = this._prepared.execute(this._db._db, params);
     return JSON.parse(json);
   }
 
@@ -60,12 +66,27 @@ class Statement {
   *iterate(...args) {
     yield* this.all(...args);
   }
+
+  close() {
+    if (!this._prepared) return false;
+    const prepared = this._prepared;
+    this._prepared = undefined;
+    this._db._statements.delete(this);
+    prepared.free();
+    return true;
+  }
+
+  finalize() {
+    return this.close();
+  }
 }
 
 class Database {
   constructor() {
     this._db = new Db();
     this._inTransaction = false;
+    this._closed = false;
+    this._statements = new Set();
   }
 
   prepare(sql) {
@@ -74,6 +95,7 @@ class Database {
 
   // Run one or more `;`-separated statements with no bound parameters.
   exec(sql) {
+    this._assertOpen();
     for (const stmt of sql.split(";").map((s) => s.trim()).filter(Boolean)) {
       this._db.query(stmt);
     }
@@ -82,11 +104,13 @@ class Database {
 
   // The most recent committed transaction id (upper bound for `... BEFORE tx`).
   get currentTx() {
+    this._assertOpen();
     return this._db.currentTx();
   }
 
   // Export the database as a `.pvdb` byte image (Uint8Array).
   serialize() {
+    this._assertOpen();
     return this._db.export();
   }
 
@@ -98,8 +122,10 @@ class Database {
   // better-sqlite3's common pattern.
   transaction(fn) {
     if (typeof fn !== "function") throw new TypeError("transaction expects a function");
+    this._assertOpen();
     const db = this;
     function wrapped(...args) {
+      db._assertOpen();
       if (db._inTransaction) return fn(...args);
       db._db.beginTransaction();
       db._inTransaction = true;
@@ -121,7 +147,14 @@ class Database {
   }
 
   close() {
-    /* the WebAssembly instance is reclaimed by the GC */
+    if (this._closed) return;
+    for (const statement of [...this._statements]) statement.close();
+    this._db.free();
+    this._closed = true;
+  }
+
+  _assertOpen() {
+    if (this._closed) throw new Error("PicoVolt database is closed");
   }
 }
 

package/worker.js

@@ -3,6 +3,8 @@
 import { PersistentDb } from "./browser.js";
 
 let database;
+let nextStatementId = 1;
+const statements = new Map();
 
 self.addEventListener("message", async ({ data }) => {
   const { id, method } = data ?? {};
@@ -10,6 +12,9 @@ self.addEventListener("message", async ({ data }) => {
     let result;
     switch (method) {
       case "open":
+        if (database) await database.close();
+        database = undefined;
+        statements.clear();
         database = await PersistentDb.open(data.name);
         result = true;
         break;
@@ -17,6 +22,26 @@ self.addEventListener("message", async ({ data }) => {
         if (!database) throw new Error("open the database first");
         result = database.query(data.sql, data.params);
         break;
+      case "prepare": {
+        if (!database) throw new Error("open the database first");
+        const statement = database.prepare(data.sql);
+        const statementId = nextStatementId++;
+        statements.set(statementId, statement);
+        result = { statementId, parameterCount: statement.parameterCount };
+        break;
+      }
+      case "execute": {
+        const statement = statements.get(data.statementId);
+        if (!statement) throw new Error("unknown PicoVolt prepared statement");
+        result = statement.query(data.params ?? []);
+        break;
+      }
+      case "finalize": {
+        const statement = statements.get(data.statementId);
+        result = statement ? statement.close() : false;
+        statements.delete(data.statementId);
+        break;
+      }
       case "save":
         if (!database) throw new Error("open the database first");
         await database.save();
@@ -25,6 +50,7 @@ self.addEventListener("message", async ({ data }) => {
       case "close":
         if (database) await database.close();
         database = undefined;
+        statements.clear();
         result = true;
         break;
       default: