@velarscript-labs/sqlite 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.2.0 — 2026-08-23
+
+- Publish the companion package as `@velarscript-labs/sqlite`, outside the
+  Standard/toolchain scope.
+- Replace the historical ORM-shaped adapter with a parameterized SQL capability.
+- Add a bounded Worker queue, runtime-typed rows, automatic transaction scope,
+  reentrancy rejection, safe-integer handling, and idempotent cleanup.
+
+Version 0.1.0 was published from the VelarScript main repository and is not the
+implementation restored here.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,47 @@
+# @velarscript-labs/sqlite
+
+A bounded asynchronous SQLite capability for VelarScript Node applications,
+backed by Node's built-in SQLite driver on one owned Worker thread.
+
+The API deliberately stops at parameterized SQL. It does not provide models,
+repositories, schema inference, an ORM, or application migrations. Those are
+application data and policy, not a reusable driver concern.
+
+```velar
+import {SqliteTransaction, openSqlite} from "@velarscript-labs/sqlite"
+
+type User:
+    id: number
+    name: string
+
+using database = await openSqlite("app.sqlite")
+await database.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)")
+
+async def create(transaction: SqliteTransaction) -> User:
+    await transaction.execute("INSERT INTO users (id, name) VALUES (?, ?)", [1, "Ada"])
+    return (await transaction.one("SELECT id, name FROM users WHERE id = ?", User, [1]))!
+
+const user = await database.transaction(create)
+```
+
+## Bounds and concurrency
+
+- One Worker owns one SQLite connection; all connection operations are queued
+  and serialized.
+- `queueCapacity` bounds admitted operations. Default 64, maximum 1,024.
+- One statement accepts at most 999 parameters and 1 MiB of SQL text.
+- `maxRows` defaults to 10,000 and is capped at 1,000,000.
+- `maxResultBytes` defaults to 64 MiB and is capped at 128 MiB. It also bounds
+  parameter bytes for one operation.
+- Numbers must be finite; integer parameters and results must fit JavaScript's
+  safe integer range. BLOB values use `Bytes`.
+- A transaction callback is the exclusive connection owner. Use the supplied
+  `SqliteTransaction`; calling the connection from that callback fails with
+  `SqliteConcurrencyError` instead of waiting on itself.
+- The callback commits on success and rolls back on failure. Transactions do
+  not expose manual commit/rollback handles.
+- `close` is idempotent, joins concurrent callers, drains admitted work, rolls
+  back an active transaction, closes the driver, and waits for the Worker.
+
+Cancellation and streaming are intentionally absent from version 0.2. They
+will not be claimed until their cleanup and backpressure contracts are proven.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@velarscript-labs/sqlite",
+  "version": "0.2.0",
+  "description": "Bounded asynchronous SQLite capability for VelarScript Node applications.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "src/index.vel",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "velar format --check && velar check",
+    "test": "velar test"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VelarOS-AI/VelarScript-Libraries.git",
+    "directory": "packages/sqlite"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "velar": {
+    "entry": "src/index.vel",
+    "targets": ["node"],
+    "requires": {"capabilities": ["node"], "language": ">=0.13 <0.14"}
+  },
+  "dependencies": {
+    "@velarscript-labs/database": "0.2.0"
+  }
+}

package/src/index.vel

@@ -0,0 +1,634 @@
+/// Per-connection bounds. Every operation is serialized through one Worker;
+/// queueCapacity bounds admitted operations waiting for that connection.
+import {DatabaseExecutor} from "@velarscript-labs/database"
+
+export type SqliteOptions:
+    busyTimeoutMilliseconds: number?
+    queueCapacity: number?
+    maxRows: number?
+    maxResultBytes: number?
+
+extern js()`
+    import { AsyncLocalStorage } from "node:async_hooks";
+    import { Worker } from "node:worker_threads";
+
+    const TOKEN = Object.freeze({});
+    const connectionStates = new WeakMap();
+    const transactionStates = new WeakMap();
+    const transactionContext = new AsyncLocalStorage();
+
+    export class NativeSqliteError extends Error {
+      constructor(message = "SQLite operation failed", sqliteCode = null, operation = "unknown", retryable = false) {
+        super(message);
+        this.name = "NativeSqliteError";
+        this.sqliteCode = sqliteCode;
+        this.operation = operation;
+        this.retryable = retryable;
+      }
+    }
+
+    export class NativeSqliteBackpressureError extends NativeSqliteError {
+      constructor(message = "SQLite queue is full") {
+        super(message, "SQLITE_BACKPRESSURE", "queue", true);
+        this.name = "NativeSqliteBackpressureError";
+      }
+    }
+
+    export class NativeSqliteConcurrencyError extends NativeSqliteError {
+      constructor(message = "SQLite connection cannot be used from its transaction callback") {
+        super(message, "SQLITE_CONCURRENCY", "transaction", true);
+        this.name = "NativeSqliteConcurrencyError";
+      }
+    }
+
+    function integer(value, fallback, minimum, maximum, label) {
+      const selected = value == null ? fallback : value;
+      if (!Number.isSafeInteger(selected) || selected < minimum || selected > maximum) {
+        throw new TypeError(label + " must be an integer from " + minimum + " through " + maximum);
+      }
+      return selected;
+    }
+
+    function checkedOptions(value) {
+      if (value === null || typeof value !== "object" || Array.isArray(value)) throw new TypeError("SQLite options must be a record");
+      const allowed = new Set(["busyTimeoutMilliseconds", "queueCapacity", "maxRows", "maxResultBytes"]);
+      for (const key of Object.keys(value)) if (!allowed.has(key)) throw new TypeError("Unknown SQLite option " + key);
+      return {
+        busyTimeoutMilliseconds: integer(value.busyTimeoutMilliseconds, 2000, 1, 60000, "SQLite busy timeout"),
+        queueCapacity: integer(value.queueCapacity, 64, 1, 1024, "SQLite queue capacity"),
+        maxRows: integer(value.maxRows, 10000, 1, 1000000, "SQLite row limit"),
+        maxResultBytes: integer(value.maxResultBytes, 64 * 1024 * 1024, 1, 128 * 1024 * 1024, "SQLite result byte limit"),
+      };
+    }
+
+    function workerMain() {
+      const { Buffer } = require("node:buffer");
+      const { parentPort, workerData } = require("node:worker_threads");
+      const { DatabaseSync } = require("node:sqlite");
+      let database = null;
+      let closed = false;
+
+      function failure(message, code, operation, retryable = false) {
+        const error = new Error(message);
+        error.code = code;
+        error.operation = operation;
+        error.retryable = retryable;
+        return error;
+      }
+
+      function errorData(error, operation) {
+        const message = error instanceof Error ? error.message : String(error);
+        const rawCode = error && typeof error === "object" ? error.errstr ?? error.code ?? null : null;
+        const code = rawCode == null ? null : String(rawCode);
+        const upper = code == null ? "" : code.toUpperCase();
+        return {
+          message,
+          sqliteCode: code,
+          operation: error && typeof error.operation === "string" ? error.operation : operation,
+          retryable: error && error.retryable === true || upper.includes("BUSY") || upper.includes("LOCKED"),
+        };
+      }
+
+      function sqlText(value, operation) {
+        if (typeof value !== "string" || value.length === 0 || value.length > 1024 * 1024 || value.includes("\0")) {
+          throw failure("SQLite SQL must be non-empty text no longer than 1 MiB", "SQLITE_INPUT", operation);
+        }
+        return value;
+      }
+
+      function parameter(value, budget) {
+        if (value === null) return null;
+        if (typeof value === "boolean") return value ? 1 : 0;
+        if (typeof value === "string") {
+          budget.value += Buffer.byteLength(value, "utf8");
+          return value;
+        }
+        if (typeof value === "number") {
+          if (!Number.isFinite(value)) throw failure("SQLite number parameters must be finite", "SQLITE_INPUT", "params");
+          if (Number.isInteger(value) && !Number.isSafeInteger(value)) throw failure("SQLite integer parameters must be safe integers", "SQLITE_INPUT", "params");
+          budget.value += 8;
+          return value;
+        }
+        if (value instanceof Uint8Array) {
+          budget.value += value.byteLength;
+          return value;
+        }
+        throw failure("SQLite parameters support only null, bool, string, finite number, and Bytes", "SQLITE_INPUT", "params");
+      }
+
+      function parameters(value) {
+        if (!Array.isArray(value) || value.length > 999) throw failure("SQLite parameters must be a List with at most 999 values", "SQLITE_INPUT", "params");
+        const budget = { value: 0 };
+        const output = value.map(item => parameter(item, budget));
+        if (budget.value > workerData.maxResultBytes) throw failure("SQLite parameters exceed the connection byte limit", "SQLITE_INPUT", "params");
+        return output;
+      }
+
+      function count(value, label) {
+        const number = typeof value === "bigint" ? Number(value) : value;
+        if (!Number.isSafeInteger(number) || number < 0) throw failure(label + " is outside VelarScript's safe integer range", "SQLITE_INTEGER_RANGE", "result");
+        return number;
+      }
+
+      function resultValue(value, budget, field) {
+        if (value === null) return null;
+        if (typeof value === "string") {
+          budget.value += Buffer.byteLength(value, "utf8");
+          return value;
+        }
+        if (typeof value === "number") {
+          if (!Number.isFinite(value)) throw failure("SQLite returned a non-finite number in " + field, "SQLITE_RESULT", "result");
+          budget.value += 8;
+          return value;
+        }
+        if (typeof value === "bigint") {
+          const number = Number(value);
+          if (!Number.isSafeInteger(number)) throw failure("SQLite returned an integer outside VelarScript's safe range in " + field, "SQLITE_INTEGER_RANGE", "result");
+          budget.value += 8;
+          return number;
+        }
+        if (value instanceof Uint8Array) {
+          budget.value += value.byteLength;
+          return value;
+        }
+        throw failure("SQLite returned an unsupported value in " + field, "SQLITE_RESULT", "result");
+      }
+
+      function resultRow(value, budget) {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) throw failure("SQLite returned a non-record row", "SQLITE_RESULT", "result");
+        const output = Object.create(null);
+        for (const key of Object.keys(value)) {
+          budget.value += Buffer.byteLength(key, "utf8");
+          output[key] = resultValue(value[key], budget, key);
+          if (budget.value > workerData.maxResultBytes) throw failure("SQLite result exceeds the connection byte limit", "SQLITE_RESULT_LIMIT", "result");
+        }
+        return output;
+      }
+
+      function statement(sql, operation) {
+        const prepared = database.prepare(sqlText(sql, operation));
+        if (typeof prepared.setReadBigInts === "function") prepared.setReadBigInts(true);
+        return prepared;
+      }
+
+      function execute(message) {
+        const prepared = statement(message.sql, "execute");
+        const result = prepared.run(...parameters(message.params));
+        return count(result.changes, "SQLite affected row count");
+      }
+
+      function one(message) {
+        const prepared = statement(message.sql, "one");
+        const row = prepared.get(...parameters(message.params));
+        if (row === undefined) return null;
+        return resultRow(row, { value: 0 });
+      }
+
+      function all(message) {
+        const prepared = statement(message.sql, "all");
+        const rows = [];
+        const budget = { value: 0 };
+        for (const row of prepared.iterate(...parameters(message.params))) {
+          if (rows.length >= workerData.maxRows) throw failure("SQLite result exceeds the connection row limit", "SQLITE_ROW_LIMIT", "all");
+          rows.push(resultRow(row, budget));
+        }
+        return rows;
+      }
+
+      function dispatch(message) {
+        if (closed) throw failure("SQLite connection is closed", "SQLITE_CLOSED", message.operation);
+        if (message.operation === "execute") return execute(message);
+        if (message.operation === "one") return one(message);
+        if (message.operation === "all") return all(message);
+        if (message.operation === "begin") {
+          if (database.isTransaction) throw failure("SQLite transaction is already active", "SQLITE_TRANSACTION", "begin", true);
+          database.exec("BEGIN IMMEDIATE");
+          return null;
+        }
+        if (message.operation === "commit") {
+          if (!database.isTransaction) throw failure("SQLite transaction is not active", "SQLITE_TRANSACTION", "commit");
+          database.exec("COMMIT");
+          return null;
+        }
+        if (message.operation === "rollback") {
+          if (database.isTransaction) database.exec("ROLLBACK");
+          return null;
+        }
+        if (message.operation === "close") {
+          try {
+            if (database.isTransaction) database.exec("ROLLBACK");
+          } finally {
+            database.close();
+            closed = true;
+          }
+          return null;
+        }
+        throw failure("Unknown SQLite operation", "SQLITE_PROTOCOL", String(message.operation));
+      }
+
+      try {
+        database = new DatabaseSync(workerData.path, { timeout: workerData.busyTimeoutMilliseconds });
+        database.exec("PRAGMA foreign_keys = ON");
+        parentPort.postMessage({ kind: "ready" });
+      } catch (error) {
+        parentPort.postMessage({ kind: "ready", error: errorData(error, "open") });
+        parentPort.close();
+        return;
+      }
+
+      parentPort.on("message", message => {
+        try {
+          const value = dispatch(message);
+          parentPort.postMessage({ kind: "response", id: message.id, value });
+          if (message.operation === "close") parentPort.close();
+        } catch (error) {
+          parentPort.postMessage({ kind: "response", id: message.id, error: errorData(error, message.operation) });
+        }
+      });
+    }
+
+    function nativeError(value) {
+      return new NativeSqliteError(value.message, value.sqliteCode, value.operation, value.retryable);
+    }
+
+    function failPending(state, error) {
+      if (state.readyReject !== null) {
+        state.readyReject(error);
+        state.readyReject = null;
+        state.readyResolve = null;
+      }
+      for (const pending of state.pending.values()) pending.reject(error);
+      state.pending.clear();
+    }
+
+    function request(state, operation, sql = "", params = []) {
+      if (state.closed) return Promise.reject(new NativeSqliteError("SQLite connection is closed", "SQLITE_CLOSED", operation));
+      const id = state.nextId++;
+      return new Promise((resolve, reject) => {
+        state.pending.set(id, { resolve, reject });
+        try {
+          state.worker.postMessage({ id, operation, sql, params });
+        } catch (error) {
+          state.pending.delete(id);
+          reject(error);
+        }
+      });
+    }
+
+    function stateOf(connection) {
+      const state = connectionStates.get(connection);
+      if (!state) throw new TypeError("Invalid SQLite connection");
+      return state;
+    }
+
+    function transactionStateOf(transaction) {
+      const state = transactionStates.get(transaction);
+      if (!state || !state.active) throw new NativeSqliteConcurrencyError("SQLite transaction is no longer active");
+      return state;
+    }
+
+    function transactionRequest(transaction, operation, sql = "", params = []) {
+      const state = transactionStateOf(transaction);
+      if (state.busy) return Promise.reject(new NativeSqliteConcurrencyError("SQLite transaction operations must be awaited one at a time"));
+      state.busy = true;
+      return request(state.connection, operation, sql, params).finally(() => { state.busy = false; });
+    }
+
+    function enqueue(state, operation) {
+      if (state.closed || state.closing) return Promise.reject(new NativeSqliteError("SQLite connection is closed", "SQLITE_CLOSED", "queue"));
+      if (transactionContext.getStore() === state) return Promise.reject(new NativeSqliteConcurrencyError());
+      if (state.queued >= state.queueCapacity) return Promise.reject(new NativeSqliteBackpressureError());
+      state.queued += 1;
+      const running = state.tail.then(operation, operation);
+      state.tail = running.then(() => null, () => null);
+      return running.finally(() => { state.queued -= 1; });
+    }
+
+    export class NativeSqliteTransaction {
+      constructor(token, state) {
+        if (token !== TOKEN) throw new TypeError("SQLite transactions are created by connection.transaction");
+        transactionStates.set(this, state);
+      }
+
+      execute(sql, params = []) { return transactionRequest(this, "execute", sql, params); }
+      one(sql, params = []) { return transactionRequest(this, "one", sql, params); }
+      all(sql, params = []) { return transactionRequest(this, "all", sql, params); }
+    }
+
+    export class NativeSqliteConnection {
+      constructor(token, state) {
+        if (token !== TOKEN) throw new TypeError("Use openSqlite to create a SQLite connection");
+        connectionStates.set(this, state);
+      }
+
+      execute(sql, params = []) {
+        const state = stateOf(this);
+        return enqueue(state, () => request(state, "execute", sql, params));
+      }
+
+      one(sql, params = []) {
+        const state = stateOf(this);
+        return enqueue(state, () => request(state, "one", sql, params));
+      }
+
+      all(sql, params = []) {
+        const state = stateOf(this);
+        return enqueue(state, () => request(state, "all", sql, params));
+      }
+
+      transaction(operation) {
+        if (typeof operation !== "function") return Promise.reject(new TypeError("SQLite transaction requires an async operation"));
+        const state = stateOf(this);
+        return enqueue(state, async () => {
+          await request(state, "begin");
+          const transactionState = { connection: state, active: true, busy: false };
+          const transaction = new NativeSqliteTransaction(TOKEN, transactionState);
+          try {
+            await transactionContext.run(state, () => operation(transaction));
+            await transactionRequest(transaction, "commit");
+            transactionState.active = false;
+            return null;
+          } catch (error) {
+            try {
+              if (transactionState.active) await transactionRequest(transaction, "rollback");
+            } catch {
+              state.closing = true;
+              state.worker.terminate();
+            } finally {
+              transactionState.active = false;
+            }
+            throw error;
+          }
+        });
+      }
+
+      close() {
+        const state = stateOf(this);
+        if (state.closePromise !== null) return state.closePromise;
+        if (transactionContext.getStore() === state) return Promise.reject(new NativeSqliteConcurrencyError("SQLite connection cannot close inside its transaction callback"));
+        state.closing = true;
+        state.closePromise = state.tail.then(async () => {
+          try {
+            if (!state.closed) await request(state, "close");
+            await state.exited;
+          } finally {
+            state.closed = true;
+          }
+        });
+        return state.closePromise;
+      }
+    }
+
+    export async function openNativeSqlite(path, options = {}) {
+      if (typeof path !== "string" || path.trim() === "" || path.length > 4096 || path.includes("\0")) throw new TypeError("SQLite path must be non-empty bounded text");
+      const checked = checkedOptions(options);
+      const source = "(" + workerMain.toString() + ")()";
+      const worker = new Worker(source, { eval: true, workerData: { path, ...checked } });
+      let readyResolve;
+      let readyReject;
+      let exitResolve;
+      const ready = new Promise((resolve, reject) => { readyResolve = resolve; readyReject = reject; });
+      const exited = new Promise(resolve => { exitResolve = resolve; });
+      const state = {
+        worker,
+        readyResolve,
+        readyReject,
+        exited,
+        pending: new Map(),
+        nextId: 1,
+        queueCapacity: checked.queueCapacity,
+        queued: 0,
+        tail: Promise.resolve(),
+        closing: false,
+        closed: false,
+        closePromise: null,
+      };
+      worker.on("message", message => {
+        if (message.kind === "ready") {
+          const resolve = state.readyResolve;
+          const reject = state.readyReject;
+          state.readyResolve = null;
+          state.readyReject = null;
+          if (message.error) reject(nativeError(message.error));
+          else resolve();
+          return;
+        }
+        if (message.kind !== "response") return;
+        const pending = state.pending.get(message.id);
+        if (!pending) return;
+        state.pending.delete(message.id);
+        if (message.error) pending.reject(nativeError(message.error));
+        else pending.resolve(message.value);
+      });
+      worker.on("error", error => {
+        state.closed = true;
+        failPending(state, new NativeSqliteError(error.message, "SQLITE_WORKER", "worker"));
+      });
+      worker.on("exit", code => {
+        exitResolve(code);
+        if (code !== 0 && !state.closed) {
+          state.closed = true;
+          failPending(state, new NativeSqliteError("SQLite Worker exited with code " + code, "SQLITE_WORKER", "worker"));
+        }
+      });
+      await ready;
+      return new NativeSqliteConnection(TOKEN, state);
+    }
+`:
+    export class NativeSqliteError:
+        const message: string
+        const sqliteCode: string?
+        const operation: string
+        const retryable: bool
+
+    export class NativeSqliteBackpressureError:
+        const message: string
+
+    export class NativeSqliteConcurrencyError:
+        const message: string
+
+    export class NativeSqliteTransaction:
+        async def execute(sql: string, params: List<unknown> = []) -> number
+        async def one(sql: string, params: List<unknown> = []) -> unknown
+        async def all(sql: string, params: List<unknown> = []) -> List<unknown>
+
+    export class NativeSqliteConnection:
+        async def execute(sql: string, params: List<unknown> = []) -> number
+        async def one(sql: string, params: List<unknown> = []) -> unknown
+        async def all(sql: string, params: List<unknown> = []) -> List<unknown>
+        async def transaction(operation: (NativeSqliteTransaction) -> Promise<null>) -> null
+        async def close() -> null
+
+    export async def openNativeSqlite(path: string, options: SqliteOptions = {}) -> NativeSqliteConnection
+
+/// A checked SQLite failure. sqliteCode preserves the driver result code when
+/// Node exposes one; retryable is true for busy, locked, and queue pressure.
+export class SqliteError extends Error:
+    const sqliteCode: string?
+    const operation: string
+    const retryable: bool
+
+    constructor(message: string, sqliteCode: string? = null, operation: string = "unknown", retryable: bool = false):
+        super(message)
+        self.sqliteCode = sqliteCode
+        self.operation = operation
+        self.retryable = retryable
+
+export class SqliteBackpressureError extends SqliteError:
+    constructor(message: string = "SQLite queue is full"):
+        super(message, "SQLITE_BACKPRESSURE", "queue", true)
+
+export class SqliteConcurrencyError extends SqliteError:
+    constructor(message: string = "SQLite connection cannot be used from its transaction callback"):
+        super(message, "SQLITE_CONCURRENCY", "transaction", true)
+
+def sqliteFailure(error: NativeSqliteError) -> SqliteError:
+    if error is NativeSqliteBackpressureError:
+        return SqliteBackpressureError(error.message)
+    if error is NativeSqliteConcurrencyError:
+        return SqliteConcurrencyError(error.message)
+    if error is NativeSqliteError:
+        return SqliteError(error.message, error.sqliteCode, error.operation, error.retryable)
+    return SqliteError(error.message)
+
+export class SqliteTransaction:
+    constructor(private const native: NativeSqliteTransaction):
+        pass
+
+    async def execute(sql: string, params: List<unknown> = []) -> number:
+        try:
+            return await self.native.execute(sql, params)
+        catch error:
+            if error is NativeSqliteError:
+                throw sqliteFailure(error)
+            throw SqliteError(error.message)
+
+    /// Projects this transaction into the engine-neutral functional operation layer.
+    def executor() -> DatabaseExecutor:
+        async def executeStatement(text: string, parameters: List<unknown>) -> number:
+            return await self.execute(text, parameters)
+
+        async def oneRow(text: string, parameters: List<unknown>) -> unknown:
+            try:
+                return await self.native.one(text, parameters)
+            catch error:
+                if error is NativeSqliteError:
+                    throw sqliteFailure(error)
+                throw SqliteError(error.message)
+
+        async def allRows(text: string, parameters: List<unknown>) -> List<unknown>:
+            try:
+                return await self.native.all(text, parameters)
+            catch error:
+                if error is NativeSqliteError:
+                    throw sqliteFailure(error)
+                throw SqliteError(error.message)
+
+        return {execute: executeStatement, one: oneRow, all: allRows}
+
+    async def one<T>(sql: string, RowType: Type<T>, params: List<unknown> = []) -> T?:
+        try:
+            const row = await self.native.one(sql, params)
+            if row == null:
+                return null
+            return RowType.parse(row)
+        catch error:
+            if error is NativeSqliteError:
+                throw sqliteFailure(error)
+            throw SqliteError(error.message)
+
+    async def all<T>(sql: string, RowType: Type<T>, params: List<unknown> = []) -> List<T>:
+        try:
+            const rows = await self.native.all(sql, params)
+            return rows.map(row => RowType.parse(row))
+        catch error:
+            if error is NativeSqliteError:
+                throw sqliteFailure(error)
+            throw SqliteError(error.message)
+
+export class SqliteConnection:
+    constructor(private const native: NativeSqliteConnection):
+        pass
+
+    async def execute(sql: string, params: List<unknown> = []) -> number:
+        try:
+            return await self.native.execute(sql, params)
+        catch error:
+            if error is NativeSqliteError:
+                throw sqliteFailure(error)
+            throw SqliteError(error.message)
+
+    /// Projects this connection into the engine-neutral functional operation layer.
+    def executor() -> DatabaseExecutor:
+        async def executeStatement(text: string, parameters: List<unknown>) -> number:
+            return await self.execute(text, parameters)
+
+        async def oneRow(text: string, parameters: List<unknown>) -> unknown:
+            try:
+                return await self.native.one(text, parameters)
+            catch error:
+                if error is NativeSqliteError:
+                    throw sqliteFailure(error)
+                throw SqliteError(error.message)
+
+        async def allRows(text: string, parameters: List<unknown>) -> List<unknown>:
+            try:
+                return await self.native.all(text, parameters)
+            catch error:
+                if error is NativeSqliteError:
+                    throw sqliteFailure(error)
+                throw SqliteError(error.message)
+
+        return {execute: executeStatement, one: oneRow, all: allRows}
+
+    async def one<T>(sql: string, RowType: Type<T>, params: List<unknown> = []) -> T?:
+        try:
+            const row = await self.native.one(sql, params)
+            if row == null:
+                return null
+            return RowType.parse(row)
+        catch error:
+            if error is NativeSqliteError:
+                throw sqliteFailure(error)
+            throw SqliteError(error.message)
+
+    async def all<T>(sql: string, RowType: Type<T>, params: List<unknown> = []) -> List<T>:
+        try:
+            const rows = await self.native.all(sql, params)
+            return rows.map(row => RowType.parse(row))
+        catch error:
+            if error is NativeSqliteError:
+                throw sqliteFailure(error)
+            throw SqliteError(error.message)
+
+    async def transaction<T>(operation: (SqliteTransaction) -> Promise<T>) -> T:
+        const results: List<T> = []
+        async def run<T>(native: NativeSqliteTransaction):
+            results.append(await operation(SqliteTransaction(native)))
+        try:
+            await self.native.transaction(run)
+            assert results.size == 1 else "SQLite transaction did not return exactly one result"
+            return results[0]
+        catch error:
+            if error is NativeSqliteError:
+                throw sqliteFailure(error)
+            throw error
+
+    async def close():
+        try:
+            await self.native.close()
+        catch error:
+            if error is NativeSqliteError:
+                throw sqliteFailure(error)
+            throw SqliteError(error.message)
+
+    @dispose:
+        await self.close()
+
+export async def openSqlite(path: string, options: SqliteOptions = {}) -> SqliteConnection:
+    try:
+        return SqliteConnection(await openNativeSqlite(path, options))
+    catch error:
+        if error is NativeSqliteError:
+            throw sqliteFailure(error)
+        throw SqliteError(error.message)