picovolt 0.7.0 → 0.8.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-0.7.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.8.0-blue.svg)](CHANGELOG.md)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 ![Status: experimental](https://img.shields.io/badge/status-experimental-orange.svg)
 
@@ -143,6 +143,15 @@ For native languages, the `capi` feature builds a shared library exposing a C AB
 (ctypes); both return query results as the same JSON shape as the JavaScript
 binding. The bindings suit embedded use, not a concurrent server's primary store.
 
+All bindings accept positional `?` parameters
+(`db.query("... WHERE id = ?", [1])`), bound as safely-escaped SQL literals. For
+a familiar surface, drop-in adapters are provided: a `better-sqlite3`-style
+JavaScript API (`import Database from "picovolt/sqlite"`), a Python DB-API 2.0
+module (`import picovolt.dbapi2 as sqlite`), and the Go `database/sql` driver
+([`bindings/go/pvsql`](bindings/go/pvsql)). Shared limits across all of them:
+positional `?` only, no SQL transactions, no JOINs, and `CREATE TABLE` takes
+column names only.
+
 ## Extending PicoVolt
 
 There are two extension paths: sandboxed WebAssembly user-defined functions, and

package/package.json

@@ -2,7 +2,7 @@
   "name": "picovolt",
   "type": "module",
   "description": "PicoVolt (PVDB): a polymorphic embedded database engine in Rust.",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -12,7 +12,8 @@
     "picovolt_bg.wasm",
     "picovolt.js",
     "picovolt_bg.js",
-    "picovolt.d.ts"
+    "picovolt.d.ts",
+    "sqlite.js"
   ],
   "main": "picovolt.js",
   "types": "picovolt.d.ts",
@@ -26,5 +27,9 @@
     "storage-engine",
     "mvcc",
     "columnar"
-  ]
-}
+  ],
+  "exports": {
+    ".": "./picovolt.js",
+    "./sqlite": "./sqlite.js"
+  }
+}

package/sqlite.js

@@ -0,0 +1,104 @@
+// A better-sqlite3-style synchronous API over PicoVolt's WebAssembly engine, so
+// code written for better-sqlite3 can use PicoVolt with minimal change:
+//
+//   import Database from "picovolt/sqlite";
+//   const db = new Database();
+//   db.exec("CREATE TABLE t (id, name)");
+//   db.prepare("INSERT INTO t VALUES (?, ?)").run(1, "alice");
+//   const rows = db.prepare("SELECT * FROM t WHERE id = ?").all(1);
+//   // [ { id: 1, name: "alice" } ]
+//
+// Limitations: parameters are positional `?` only (named `:id` params are not
+// supported); there are no transactions; blob parameters are unsupported.
+
+import { Db } from "./picovolt.js";
+
+function rowToObject(columns, row) {
+  const obj = {};
+  for (let i = 0; i < columns.length; i++) obj[columns[i]] = row[i];
+  return obj;
+}
+
+// better-sqlite3 accepts bind values either positionally (`run(1, "a")`) or as a
+// single array (`run([1, "a"])`); normalize both to one array.
+function normalizeParams(args) {
+  if (args.length === 1 && Array.isArray(args[0])) return args[0];
+  return args;
+}
+
+class Statement {
+  constructor(db, sql) {
+    this._db = db;
+    this.source = sql;
+  }
+
+  _exec(args) {
+    const params = normalizeParams(args);
+    const json = params.length ? this._db._db.query(this.source, params) : this._db._db.query(this.source);
+    return JSON.parse(json);
+  }
+
+  run(...args) {
+    const r = this._exec(args);
+    return { changes: typeof r.mutated === "number" ? r.mutated : 0 };
+  }
+
+  get(...args) {
+    const r = this._exec(args);
+    if (!r.columns || !r.rows.length) return undefined;
+    return rowToObject(r.columns, r.rows[0]);
+  }
+
+  all(...args) {
+    const r = this._exec(args);
+    if (!r.columns) return [];
+    return r.rows.map((row) => rowToObject(r.columns, row));
+  }
+
+  *iterate(...args) {
+    yield* this.all(...args);
+  }
+}
+
+class Database {
+  constructor() {
+    this._db = new Db();
+  }
+
+  prepare(sql) {
+    return new Statement(this, sql);
+  }
+
+  // Run one or more `;`-separated statements with no bound parameters.
+  exec(sql) {
+    for (const stmt of sql.split(";").map((s) => s.trim()).filter(Boolean)) {
+      this._db.query(stmt);
+    }
+    return this;
+  }
+
+  // The most recent committed transaction id (upper bound for `... BEFORE tx`).
+  get currentTx() {
+    return this._db.currentTx();
+  }
+
+  // Export the database as a `.pvdb` byte image (Uint8Array).
+  serialize() {
+    return this._db.export();
+  }
+
+  pragma() {
+    throw new Error("picovolt: pragma is not supported");
+  }
+
+  transaction() {
+    throw new Error("picovolt: transactions are not supported");
+  }
+
+  close() {
+    /* the WebAssembly instance is reclaimed by the GC */
+  }
+}
+
+export default Database;
+export { Database, Statement };