@cutils/sqlite 0.0.0-stage → 0.1.0

package/dist/esm/index.js

@@ -0,0 +1,761 @@
+// @cutils/sqlite — embedded SQLite for chttp/scriptc apps.
+//
+// better-sqlite3 ergonomics, narrowed to what the scriptc subset lowers:
+// `prepare().get/all/run/bind()`, `exec`, `pragma`, `transaction()`,
+// columns metadata, `using` via `[Symbol.dispose]()`. Row typing and
+// validation flow through the Standard-Schema seam: `prepare(sql, schema)`
+// returns `Stmt<InferOutput<typeof schema>>`; the `*Raw` family opts out.
+//
+// Subset notes: non-generic `*Core` classes + `interface X extends XCore` /
+// `const X = XCore` aliases (generic CLASSES degrade to methodless shells,
+// generic METHODS are fine and are what make the interface assignable);
+// `| null` unions only except the documented `get()` divergence; no
+// `?.`/`??`, no Map/Set, no `for...in`, no object/method shorthand.
+import { SqliteError, sqliteCodeName } from "./errors.js";
+import { validateRow } from "./validate.js";
+import { Scratch } from "./internal/buffer.js";
+import { utf8Decode } from "./internal/utf8.js";
+import { nextSavepoint } from "./internal/savepoint.js";
+import { ffiBegin, ffiBindBlob, ffiBindCount, ffiBindDbl, ffiBindIndex, ffiBindInt, ffiBindNull, ffiBindText, ffiChanges, ffiClearBindings, ffiClose, ffiColumnBlob, ffiColumnCount, ffiColumnDbl, ffiColumnInt64, ffiColumnMeta, ffiColumnName, ffiColumnText, ffiColumnType, ffiCommit, ffiErrcode, ffiErrmsg, ffiExec, ffiExpandedSql, ffiFinalize, ffiInTransaction, ffiLastInsertRowid, ffiOpen, ffiPrepare, ffiReset, ffiRollback, ffiSavepoint, ffiStep, ffiStmtReadonly, } from "./internal/ffi.js";
+export { StandardSchemaV1, StdProps } from "./types.js";
+export { SqliteError };
+// SQLITE_OPEN_* flags.
+const OPEN_READONLY = 1;
+const OPEN_READWRITE = 2;
+const OPEN_CREATE = 4;
+// sqlite3_column_type values.
+const COL_INTEGER = 1;
+const COL_FLOAT = 2;
+const COL_TEXT = 3;
+const COL_BLOB = 4;
+// shim_savepoint op codes.
+const SP_SAVE = 0;
+const SP_RELEASE = 1;
+const SP_ROLLBACK = 2;
+const STEP_ROW = 0;
+const STEP_DONE = 101;
+const ERR_CLOSED = "database connection is not open";
+const ERR_FINALIZED = "statement is finalized";
+class StmtCore {
+    _db;
+    _stmt;
+    _source;
+    _schema;
+    _reader;
+    _readonly;
+    _finalized;
+    constructor(db, stmt, source, schema) {
+        this._db = db;
+        this._stmt = stmt;
+        this._source = source;
+        this._schema = schema;
+        this._reader = ffiColumnCount(stmt) > 0;
+        this._readonly = ffiStmtReadonly(stmt) === 1;
+        this._finalized = false;
+    }
+    get source() {
+        return this._source;
+    }
+    get reader() {
+        return this._reader;
+    }
+    get readonly() {
+        return this._readonly;
+    }
+    get database() {
+        return this._db;
+    }
+    get schema() {
+        return this._schema;
+    }
+    _checkLive() {
+        if (this._finalized) {
+            throw new SqliteError("SQLITE_MISUSE", ERR_FINALIZED);
+        }
+    }
+    _bindValue(idx, v) {
+        let rc;
+        if (v === null) {
+            rc = ffiBindNull(this._stmt, idx);
+        }
+        else if (typeof v === "bigint") {
+            rc = ffiBindInt(this._stmt, idx, v);
+        }
+        else if (typeof v === "number") {
+            if (Number.isInteger(v) && v <= 9007199254740991 && v >= -9007199254740991) {
+                rc = ffiBindInt(this._stmt, idx, BigInt(v));
+            }
+            else {
+                rc = ffiBindDbl(this._stmt, idx, v);
+            }
+        }
+        else if (typeof v === "boolean") {
+            rc = ffiBindInt(this._stmt, idx, v ? BigInt(1) : BigInt(0));
+        }
+        else if (typeof v === "string") {
+            rc = ffiBindText(this._stmt, idx, v);
+        }
+        else if (typeof v === "undefined") {
+            // Schema-validated records may carry optional keys as `undefined`
+            // (valibot `optional()`); bind NULL, better-sqlite3 semantics.
+            rc = ffiBindNull(this._stmt, idx);
+        }
+        else {
+            rc = ffiBindBlob(this._stmt, idx, v);
+        }
+        if (rc !== 0) {
+            this._db._throwDb(rc, "bind failed");
+        }
+    }
+    _namedIndex(key) {
+        // Named params may be keyed with or without their sigil: "title",
+        // ":title", "@title", "$title" all resolve against :title/@title/$title
+        // in the prepared SQL.
+        let idx = ffiBindIndex(this._stmt, key);
+        if (idx !== 0) {
+            return idx;
+        }
+        let bare = key;
+        const c0 = key.charAt(0);
+        if (c0 === ":" || c0 === "@" || c0 === "$") {
+            bare = key.slice(1);
+            idx = ffiBindIndex(this._stmt, bare);
+            if (idx !== 0) {
+                return idx;
+            }
+        }
+        idx = ffiBindIndex(this._stmt, ":" + bare);
+        if (idx !== 0) {
+            return idx;
+        }
+        idx = ffiBindIndex(this._stmt, "@" + bare);
+        if (idx !== 0) {
+            return idx;
+        }
+        return ffiBindIndex(this._stmt, "$" + bare);
+    }
+    _bindParams(params) {
+        // Always reset before stepping; an omitted or EMPTY params argument
+        // keeps whatever bindings are currently set (the `stmt.bind()`
+        // permanent-bind path) — a subset-clean stand-in for better-sqlite3's
+        // zero-argument call convention.
+        ffiReset(this._stmt);
+        if (typeof params === "undefined") {
+            return;
+        }
+        if (Array.isArray(params)) {
+            if (params.length === 0) {
+                return;
+            }
+            ffiClearBindings(this._stmt);
+            const count = ffiBindCount(this._stmt);
+            if (params.length > count) {
+                throw new SqliteError("BIND_PARAM", "too many bind parameters: got " +
+                    String(params.length) +
+                    ", statement takes " +
+                    String(count));
+            }
+            for (let i = 0; i < params.length; i++) {
+                this._bindValue(i + 1, params[i]);
+            }
+            return;
+        }
+        if (typeof params !== "object" || params === null) {
+            throw new SqliteError("BIND_PARAM", "bind parameters must be a tuple or a record");
+        }
+        const rec = params;
+        const keys = Object.keys(rec);
+        if (keys.length === 0) {
+            return;
+        }
+        ffiClearBindings(this._stmt);
+        for (let i = 0; i < keys.length; i++) {
+            const key = keys[i];
+            const idx = this._namedIndex(key);
+            if (idx === 0) {
+                throw new SqliteError("BIND_PARAM", "no bind parameter named " + key);
+            }
+            this._bindValue(idx, rec[key]);
+        }
+    }
+    _columnName(idx) {
+        const n = ffiColumnName(this._stmt, idx, this._db._scratch.buf);
+        if (n < 0) {
+            return "";
+        }
+        if (n > this._db._scratch.buf.length) {
+            this._db._scratch.ensure(n);
+            const m = ffiColumnName(this._stmt, idx, this._db._scratch.buf);
+            if (m < 0) {
+                return "";
+            }
+            return utf8Decode(this._db._scratch.buf, m);
+        }
+        return utf8Decode(this._db._scratch.buf, n);
+    }
+    _columnMeta(idx, which) {
+        const n = ffiColumnMeta(this._stmt, idx, which, this._db._scratch.buf);
+        if (n < 0) {
+            return null;
+        }
+        if (n > this._db._scratch.buf.length) {
+            this._db._scratch.ensure(n);
+            const m = ffiColumnMeta(this._stmt, idx, which, this._db._scratch.buf);
+            if (m < 0) {
+                return null;
+            }
+            return utf8Decode(this._db._scratch.buf, m);
+        }
+        return utf8Decode(this._db._scratch.buf, n);
+    }
+    _columnValue(idx) {
+        const t = ffiColumnType(this._stmt, idx);
+        if (t === COL_INTEGER) {
+            const b = ffiColumnInt64(this._stmt, idx);
+            const n = Number(b);
+            if (Number.isSafeInteger(n)) {
+                return n;
+            }
+            return b;
+        }
+        if (t === COL_FLOAT) {
+            return ffiColumnDbl(this._stmt, idx);
+        }
+        if (t === COL_TEXT) {
+            const n = ffiColumnText(this._stmt, idx, this._db._scratch.buf);
+            if (n < 0) {
+                return "";
+            }
+            if (n > this._db._scratch.buf.length) {
+                this._db._scratch.ensure(n);
+                const m = ffiColumnText(this._stmt, idx, this._db._scratch.buf);
+                if (m < 0) {
+                    return "";
+                }
+                return utf8Decode(this._db._scratch.buf, m);
+            }
+            return utf8Decode(this._db._scratch.buf, n);
+        }
+        if (t === COL_BLOB) {
+            const n = ffiColumnBlob(this._stmt, idx, this._db._scratch.buf);
+            if (n < 0) {
+                return new Uint8Array(0);
+            }
+            if (n > this._db._scratch.buf.length) {
+                this._db._scratch.ensure(n);
+                const m = ffiColumnBlob(this._stmt, idx, this._db._scratch.buf);
+                if (m < 0) {
+                    return new Uint8Array(0);
+                }
+                return this._db._scratch.copyOut(m);
+            }
+            return this._db._scratch.copyOut(n);
+        }
+        return null;
+    }
+    _readRow() {
+        const ncols = ffiColumnCount(this._stmt);
+        const row = {};
+        for (let i = 0; i < ncols; i++) {
+            row[this._columnName(i)] = this._columnValue(i);
+        }
+        return row;
+    }
+    _validateOut(row) {
+        if (this._schema === null) {
+            return row;
+        }
+        return validateRow(this._schema, row);
+    }
+    _stepOnce() {
+        const rc = ffiStep(this._stmt);
+        if (rc === STEP_ROW) {
+            const row = this._readRow();
+            ffiReset(this._stmt);
+            return this._validateOut(row);
+        }
+        ffiReset(this._stmt);
+        if (rc === STEP_DONE) {
+            return null;
+        }
+        this._db._throwDb(rc, "step failed");
+        return null;
+    }
+    _allRows() {
+        const out = [];
+        for (;;) {
+            const rc = ffiStep(this._stmt);
+            if (rc === STEP_ROW) {
+                out.push(this._validateOut(this._readRow()));
+                continue;
+            }
+            ffiReset(this._stmt);
+            if (rc === STEP_DONE) {
+                return out;
+            }
+            this._db._throwDb(rc, "step failed");
+            return out;
+        }
+    }
+    _drain() {
+        for (;;) {
+            const rc = ffiStep(this._stmt);
+            if (rc === STEP_ROW) {
+                continue;
+            }
+            ffiReset(this._stmt);
+            if (rc === STEP_DONE) {
+                return;
+            }
+            this._db._throwDb(rc, "step failed");
+            return;
+        }
+    }
+    _runResult() {
+        return {
+            changes: ffiChanges(this._db._db),
+            lastInsertRowid: Number(ffiLastInsertRowid(this._db._db)),
+        };
+    }
+    run(params) {
+        this._checkLive();
+        let bound = params;
+        if (this._schema !== null && typeof params !== "undefined") {
+            bound = validateRow(this._schema, params);
+        }
+        this._bindParams(bound);
+        this._drain();
+        return this._runResult();
+    }
+    runRaw(params) {
+        this._checkLive();
+        this._bindParams(params);
+        this._drain();
+        return this._runResult();
+    }
+    get(params) {
+        this._checkLive();
+        this._bindParams(params);
+        const row = this._stepOnce();
+        if (row === null) {
+            return undefined;
+        }
+        return row;
+    }
+    getOrNull(params) {
+        this._checkLive();
+        this._bindParams(params);
+        return this._stepOnce();
+    }
+    getRaw(params) {
+        this._checkLive();
+        this._bindParams(params);
+        const rc = ffiStep(this._stmt);
+        if (rc === STEP_ROW) {
+            const row = this._readRow();
+            ffiReset(this._stmt);
+            return row;
+        }
+        ffiReset(this._stmt);
+        if (rc === STEP_DONE) {
+            return null;
+        }
+        this._db._throwDb(rc, "step failed");
+        return null;
+    }
+    all(params) {
+        this._checkLive();
+        this._bindParams(params);
+        return this._allRows();
+    }
+    allRaw(params) {
+        this._checkLive();
+        this._bindParams(params);
+        const out = [];
+        for (;;) {
+            const rc = ffiStep(this._stmt);
+            if (rc === STEP_ROW) {
+                out.push(this._readRow());
+                continue;
+            }
+            ffiReset(this._stmt);
+            if (rc === STEP_DONE) {
+                return out;
+            }
+            this._db._throwDb(rc, "step failed");
+            return out;
+        }
+    }
+    bind(params) {
+        this._checkLive();
+        if (typeof params === "undefined") {
+            return this;
+        }
+        if (Array.isArray(params)) {
+            const count = ffiBindCount(this._stmt);
+            if (params.length > count) {
+                throw new SqliteError("BIND_PARAM", "too many bind parameters");
+            }
+            for (let i = 0; i < params.length; i++) {
+                this._bindValue(i + 1, params[i]);
+            }
+            return this;
+        }
+        if (typeof params !== "object" || params === null) {
+            throw new SqliteError("BIND_PARAM", "bind parameters must be a tuple or a record");
+        }
+        const rec = params;
+        const keys = Object.keys(rec);
+        for (let i = 0; i < keys.length; i++) {
+            const key = keys[i];
+            const idx = this._namedIndex(key);
+            if (idx === 0) {
+                throw new SqliteError("BIND_PARAM", "no bind parameter named " + key);
+            }
+            this._bindValue(idx, rec[key]);
+        }
+        return this;
+    }
+    columns() {
+        this._checkLive();
+        const ncols = ffiColumnCount(this._stmt);
+        const out = [];
+        for (let i = 0; i < ncols; i++) {
+            out.push({
+                name: this._columnName(i),
+                column: this._columnMeta(i, 0),
+                table: this._columnMeta(i, 1),
+                database: this._columnMeta(i, 2),
+                type: this._columnMeta(i, 3),
+            });
+        }
+        return out;
+    }
+    toString() {
+        const n = ffiExpandedSql(this._stmt, this._db._scratch.buf);
+        if (n < 0) {
+            return this._source;
+        }
+        if (n > this._db._scratch.buf.length) {
+            this._db._scratch.ensure(n);
+            const m = ffiExpandedSql(this._stmt, this._db._scratch.buf);
+            if (m < 0) {
+                return this._source;
+            }
+            return utf8Decode(this._db._scratch.buf, m);
+        }
+        return utf8Decode(this._db._scratch.buf, n);
+    }
+    finalize() {
+        if (this._finalized) {
+            return;
+        }
+        this._finalized = true;
+        ffiFinalize(this._stmt);
+        this._db._untrack(this);
+    }
+    [Symbol.dispose]() {
+        this.finalize();
+    }
+}
+export const Stmt = StmtCore;
+export class Database {
+    _db;
+    _path;
+    _memory;
+    _readonly;
+    _closed;
+    _scratch;
+    _stmts;
+    _txs;
+    constructor(handle, path, memory, readonly_) {
+        this._db = handle;
+        this._path = path;
+        this._memory = memory;
+        this._readonly = readonly_;
+        this._closed = false;
+        this._scratch = new Scratch();
+        this._stmts = [];
+        this._txs = [];
+    }
+    static open(path, opts) {
+        let flags = OPEN_READWRITE;
+        let ro = false;
+        let mustExist = false;
+        if (typeof opts !== "undefined") {
+            if (opts.readonly === true) {
+                ro = true;
+            }
+            if (opts.fileMustExist === true) {
+                mustExist = true;
+            }
+        }
+        if (ro) {
+            flags = OPEN_READONLY;
+        }
+        else {
+            flags = OPEN_READWRITE;
+            if (!mustExist) {
+                flags = OPEN_READWRITE | OPEN_CREATE;
+            }
+        }
+        const h = ffiOpen(path, flags);
+        if (Number(h) === 0) {
+            throw new SqliteError("SQLITE_NOMEM", "out of memory opening " + path);
+        }
+        const rc = ffiErrcode(h);
+        if (rc !== 0) {
+            const scratch = new Scratch();
+            const n = ffiErrmsg(h, scratch.buf);
+            const msg = n >= 0 ? utf8Decode(scratch.buf, n) : "open failed";
+            ffiClose(h);
+            throw new SqliteError(sqliteCodeName(rc), msg);
+        }
+        return new Database(h, path, path === ":memory:", ro);
+    }
+    static openInMemory() {
+        const db = Database.open(":memory:");
+        db._memory = true;
+        return db;
+    }
+    get path() {
+        return this._path;
+    }
+    get memory() {
+        return this._memory;
+    }
+    get readonly() {
+        return this._readonly;
+    }
+    get inTransaction() {
+        if (this._closed) {
+            return false;
+        }
+        return ffiInTransaction(this._db) === 1;
+    }
+    _checkOpen() {
+        if (this._closed) {
+            throw new SqliteError("SQLITE_MISUSE", ERR_CLOSED);
+        }
+    }
+    _errmsg() {
+        const n = ffiErrmsg(this._db, this._scratch.buf);
+        if (n < 0) {
+            return "sqlite error";
+        }
+        if (n > this._scratch.buf.length) {
+            this._scratch.ensure(n);
+            const m = ffiErrmsg(this._db, this._scratch.buf);
+            if (m < 0) {
+                return "sqlite error";
+            }
+            return utf8Decode(this._scratch.buf, m);
+        }
+        return utf8Decode(this._scratch.buf, n);
+    }
+    _throwDb(rc, fallback) {
+        let msg = this._errmsg();
+        if (msg.length === 0) {
+            msg = fallback;
+        }
+        const txs = this._txs;
+        if (txs.length > 0) {
+            txs[txs.length - 1]._failed = true;
+        }
+        // Prefer the handle's EXTENDED errcode: call-site rcs are the primary
+        // code, so SQLITE_CONSTRAINT_UNIQUE/NOTNULL/... would be lost.
+        const ext = ffiErrcode(this._db);
+        throw new SqliteError(sqliteCodeName(ext !== 0 ? ext : rc), msg);
+    }
+    _untrack(stmt) {
+        const arr = this._stmts;
+        for (let i = 0; i < arr.length; i++) {
+            if (arr[i] === stmt) {
+                arr.splice(i, 1);
+                return;
+            }
+        }
+    }
+    _prepareCore(sql, schema) {
+        this._checkOpen();
+        const st = ffiPrepare(this._db, sql);
+        if (Number(st) === 0) {
+            this._throwDb(ffiErrcode(this._db), "prepare failed");
+        }
+        const stmt = new StmtCore(this, st, sql, schema);
+        this._stmts.push(stmt);
+        return stmt;
+    }
+    exec(sql) {
+        this._checkOpen();
+        const rc = ffiExec(this._db, sql);
+        if (rc !== 0) {
+            this._throwDb(rc, "exec failed");
+        }
+    }
+    execRaw(sql) {
+        this.exec(sql);
+    }
+    pragma(sql) {
+        const stmt = this._prepareCore("PRAGMA " + sql, null);
+        const rows = stmt.allRaw([]);
+        stmt.finalize();
+        const out = [];
+        for (let i = 0; i < rows.length; i++) {
+            out.push(rows[i]);
+        }
+        return { rows: out };
+    }
+    transaction() {
+        this._checkOpen();
+        if (this.inTransaction) {
+            const name = nextSavepoint();
+            const rc = ffiSavepoint(this._db, name, SP_SAVE);
+            if (rc !== 0) {
+                this._throwDb(rc, "savepoint failed");
+            }
+            const parent = this._txs.length > 0 ? this._txs[this._txs.length - 1] : null;
+            const tx = new Transaction(this, parent, name);
+            this._txs.push(tx);
+            return tx;
+        }
+        const rc = ffiBegin(this._db);
+        if (rc !== 0) {
+            this._throwDb(rc, "begin failed");
+        }
+        const tx = new Transaction(this, null, null);
+        this._txs.push(tx);
+        return tx;
+    }
+    prepare(sql, schema) {
+        return this._prepareCore(sql, schema);
+    }
+    prepareRaw(sql) {
+        return this._prepareCore(sql, null);
+    }
+    lastInsertRowid() {
+        this._checkOpen();
+        return Number(ffiLastInsertRowid(this._db));
+    }
+    changes() {
+        this._checkOpen();
+        return ffiChanges(this._db);
+    }
+    close() {
+        if (this._closed) {
+            return;
+        }
+        const stmts = this._stmts;
+        for (let i = stmts.length - 1; i >= 0; i--) {
+            stmts[i].finalize();
+        }
+        this._closed = true;
+        ffiClose(this._db);
+    }
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+export class Transaction {
+    _db;
+    _parent;
+    _savepoint;
+    _done;
+    _failed;
+    constructor(db, parent, savepoint) {
+        this._db = db;
+        this._parent = parent;
+        this._savepoint = savepoint;
+        this._done = false;
+        this._failed = false;
+    }
+    get database() {
+        return this._db;
+    }
+    _checkLive() {
+        if (this._done) {
+            throw new SqliteError("SQLITE_MISUSE", "transaction is already finished");
+        }
+    }
+    _popSelf() {
+        const txs = this._db._txs;
+        for (let i = txs.length - 1; i >= 0; i--) {
+            if (txs[i] === this) {
+                txs.splice(i, 1);
+                return;
+            }
+        }
+    }
+    exec(sql) {
+        this._checkLive();
+        this._db.exec(sql);
+    }
+    execRaw(sql) {
+        this.exec(sql);
+    }
+    prepare(sql, schema) {
+        this._checkLive();
+        return this._db._prepareCore(sql, schema);
+    }
+    prepareRaw(sql) {
+        this._checkLive();
+        return this._db._prepareCore(sql, null);
+    }
+    savepoint(name) {
+        this._checkLive();
+        const rc = ffiSavepoint(this._db._db, name, SP_SAVE);
+        if (rc !== 0) {
+            this._db._throwDb(rc, "savepoint failed");
+        }
+        const tx = new Transaction(this._db, this, name);
+        this._db._txs.push(tx);
+        return tx;
+    }
+    commit() {
+        this._checkLive();
+        if (this._savepoint !== null) {
+            const rc = ffiSavepoint(this._db._db, this._savepoint, SP_RELEASE);
+            if (rc !== 0) {
+                this._db._throwDb(rc, "release savepoint failed");
+            }
+        }
+        else {
+            const rc = ffiCommit(this._db._db);
+            if (rc !== 0) {
+                this._db._throwDb(rc, "commit failed");
+            }
+        }
+        this._done = true;
+        this._popSelf();
+    }
+    rollback() {
+        this._checkLive();
+        if (this._savepoint !== null) {
+            const rc = ffiSavepoint(this._db._db, this._savepoint, SP_ROLLBACK);
+            if (rc !== 0) {
+                this._db._throwDb(rc, "rollback to savepoint failed");
+            }
+        }
+        else {
+            const rc = ffiRollback(this._db._db);
+            if (rc !== 0) {
+                this._db._throwDb(rc, "rollback failed");
+            }
+        }
+        this._done = true;
+        this._popSelf();
+    }
+    [Symbol.dispose]() {
+        if (this._done) {
+            return;
+        }
+        // A SqliteError thrown inside the transaction marks `_failed`;
+        // dispose can't see user-level throws, so clean exits commit and
+        // error exits roll back — documented in docs/subset-quirks.md.
+        if (this._failed) {
+            this.rollback();
+            return;
+        }
+        this.commit();
+    }
+}