@mark1russell7/sqlite 0.0.0-bootstrap.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Russell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
 # @mark1russell7/sqlite
 
-This version is a placeholder. The release workflow of https://github.com/mark1russell7/sqlite publishes the real versions. Use a later version.
+Databases on one computer through `node:sqlite`. The package has the connection with its pragmas, the migrations by `user_version`, the write transaction and a typed append-only event log. It has no dependencies.
+
+```sh
+npm install @mark1russell7/sqlite
+```
+
+The package needs Node.js 22.16 or later.
+
+## The connection
+
+`openDatabase` opens a `DatabaseSync` and sets its pragmas. It sets the busy timeout first, because the change to WAL needs the lock of the file.
+
+```ts
+import { openDatabase } from "@mark1russell7/sqlite";
+
+const db = openDatabase("data/app.db", { synchronous: "NORMAL", busyTimeoutMs: 5000, makeFolder: true });
+```
+
+| Option | Default | What it sets |
+| --- | --- | --- |
+| `wal` | `true` | The write-ahead log. Then readers do not stop a writer. |
+| `synchronous` | `FULL` | The pragma `synchronous`. With WAL, `NORMAL` can lose the last commits at a power cut. The file stays good. |
+| `busyTimeoutMs` | `0` | The time that a statement waits for the lock of a different connection. With `0`, the statement fails at once. |
+| `makeFolder` | `false` | The function makes the folder of the file. `folderMode` sets the mode of the new folders. |
+
+Each default other than `wal` is the default of SQLite.
+
+## Migrations
+
+`migrate` does the steps that a file does not have. The `user_version` of the file is the count of steps that it has. A step is SQL text or a function.
+
+```ts
+import { migrate, type Migration } from "@mark1russell7/sqlite";
+
+const steps: Migration[] = [
+  "CREATE TABLE notes (id TEXT PRIMARY KEY, text TEXT NOT NULL) STRICT",
+  (db) => db.exec("CREATE INDEX notes_text ON notes (text)"),
+];
+migrate(db, steps); // { from: 0, to: 2 }
+```
+
+- Each step is one transaction with its new `user_version`. A step that fails rolls back alone.
+- The function reads the version again in each transaction, so two processes can migrate one file at the same time.
+- A file with more steps than the list is from a newer version of the app, and the function throws.
+- Do not change a step that a file can have. Add a new step.
+
+## Transactions
+
+`transaction` does the work in one `BEGIN IMMEDIATE` transaction and gives the result of the work. The write lock comes at the start, so a different writer cannot cause a failure in the middle of the work.
+
+```ts
+import { transaction } from "@mark1russell7/sqlite";
+
+const added = transaction(db, () => {
+  db.prepare("INSERT INTO notes VALUES (?, ?)").run("n1", "first");
+  return 1;
+});
+```
+
+- When the work or the commit throws, the function rolls back and throws the same error.
+- The work is synchronous. A work that gives a promise is an error.
+- A call in a transaction throws, because SQLite refuses a nested `BEGIN`.
+- `onRollbackError` gets the error of a rollback that did not end.
+
+## The event log
+
+`openEventLog` opens a typed append-only log of events in one file. The caller keeps a state, and `accept` changes it before the write. Thus the state and the file stay equal.
+
+```ts
+import { openEventLog, type LogRecord } from "@mark1russell7/sqlite";
+
+interface Added extends LogRecord {
+  readonly type: "added";
+  readonly name: string;
+}
+
+const names = new Set<string>();
+const accept = (event: Added): string | undefined => {
+  if (names.has(event.name)) return "duplicate";
+  names.add(event.name);
+  return undefined;
+};
+
+const log = openEventLog("data/events.db", (value) => value as Added);
+for (const event of log.read()) accept(event);
+log.append({ id: "e1", at: new Date().toISOString(), type: "added", name: "a" }, accept);
+```
+
+- `append` and `appendAll` give the problems of the refused events. A refused event is not written.
+- A failed write or `accept` rolls back and breaks the log. Each later call throws until `recover`. Then the caller replays the log.
+- `recover` throws when the rollback did not end. Then open the log again.
+- The log owns the `user_version` of its file. `EVENT_LOG_SCHEMA_VERSION` is the version that it writes.
+- The third argument has the options of `openDatabase`.
+
+## The experimental warning
+
+Node.js 22 writes "SQLite is an experimental feature" to the standard error at the first load of `node:sqlite`. The entry `@mark1russell7/sqlite/warning` removes only that warning. The entry does not import `node:sqlite`.
+
+```ts
+import { quietSqliteWarning } from "@mark1russell7/sqlite/warning";
+
+quietSqliteWarning();
+const { openDatabase } = await import("@mark1russell7/sqlite");
+```
+
+A static import of `node:sqlite` loads before the code of the module. Thus import the database code after the filter, with `import()`. The function gives a function that removes the filter.

package/build/database.d.ts

@@ -0,0 +1,36 @@
+import { DatabaseSync } from "node:sqlite";
+/** The values of the pragma `synchronous`. */
+export type Synchronous = "OFF" | "NORMAL" | "FULL" | "EXTRA";
+/** The options of `openDatabase`. Each default is the default of SQLite, but the journal is WAL by default. */
+export interface OpenOptions {
+  /**
+   * This value turns on the write-ahead log (WAL). The default is true. Then readers do not stop a writer. A database
+   * with no file keeps its journal in memory.
+   */
+  readonly wal?: boolean | undefined;
+  /**
+   * This value is the pragma `synchronous`. The default is `FULL`: a commit is on the disk when the call ends. With WAL,
+   * `NORMAL` can lose the last commits at a power cut, and the file stays good.
+   */
+  readonly synchronous?: Synchronous | undefined;
+  /**
+   * This value is the time in milliseconds that a statement waits for the lock of a different connection. The default
+   * is 0: then the statement fails at once with "database is locked".
+   */
+  readonly busyTimeoutMs?: number | undefined;
+  /** This value makes the folder of the file when the folder is not there. The default is false. */
+  readonly makeFolder?: boolean | undefined;
+  /** This value is the mode of the folders that `makeFolder` makes, for example `0o700`. */
+  readonly folderMode?: number | undefined;
+}
+/**
+ * This function opens a database, and makes the file when it is not there. `:memory:` gives a database with no file.
+ *
+ * The function sets the busy timeout first, because the change to WAL needs the lock of the file. When a pragma
+ * fails, the function closes the connection and throws the error.
+ *
+ * @param path - The path of the file, or `:memory:`.
+ * @param options - The pragmas and the folder.
+ */
+export declare function openDatabase(path: string, options?: OpenOptions): DatabaseSync;
+//# sourceMappingURL=database.d.ts.map

package/build/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","names":[],"sources":["../src/database.ts"],"mappings":";;YAUY;;iBAKK;;;;;WAKN;;;;;WAKA,cAAc;;;;;WAKd;;WAEA;;WAEA;;;;;;;;;;;wBAYK,aAAa,cAAc,UAAS,cAAmB"}

package/build/database.js

@@ -0,0 +1,47 @@
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+// src/database.ts
+/**
+* The connection to a database on one computer: a `DatabaseSync` of `node:sqlite` with the pragmas set.
+*
+* @packageDocumentation
+*/
+const SYNCHRONOUS = [
+	"OFF",
+	"NORMAL",
+	"FULL",
+	"EXTRA"
+];
+/**
+* This function opens a database, and makes the file when it is not there. `:memory:` gives a database with no file.
+*
+* The function sets the busy timeout first, because the change to WAL needs the lock of the file. When a pragma
+* fails, the function closes the connection and throws the error.
+*
+* @param path - The path of the file, or `:memory:`.
+* @param options - The pragmas and the folder.
+*/
+function openDatabase(path, options = {}) {
+	const synchronous = options.synchronous ?? "FULL";
+	if (!SYNCHRONOUS.includes(synchronous)) throw new RangeError(`The value of synchronous must be one of ${SYNCHRONOUS.join(", ")}, not ${String(synchronous)}.`);
+	const busyTimeoutMs = options.busyTimeoutMs ?? 0;
+	if (!Number.isInteger(busyTimeoutMs) || busyTimeoutMs < 0) throw new RangeError(`The busy timeout must be a whole number of milliseconds of 0 or more, not ${String(busyTimeoutMs)}.`);
+	if (options.makeFolder === true && path !== ":memory:") mkdirSync(dirname(path), options.folderMode === void 0 ? { recursive: true } : {
+		recursive: true,
+		mode: options.folderMode
+	});
+	const db = new DatabaseSync(path);
+	try {
+		db.exec(`PRAGMA busy_timeout = ${String(busyTimeoutMs)}`);
+		if (options.wal ?? true) db.exec("PRAGMA journal_mode = WAL");
+		db.exec(`PRAGMA synchronous = ${synchronous}`);
+	} catch (error) {
+		db.close();
+		throw error;
+	}
+	return db;
+}
+export { openDatabase };
+
+//# sourceMappingURL=database.js.map

package/build/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","names":[],"sources":["../src/database.ts"],"sourcesContent":["/**\n * The connection to a database on one computer: a `DatabaseSync` of `node:sqlite` with the pragmas set.\n *\n * @packageDocumentation\n */\nimport { mkdirSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { DatabaseSync } from \"node:sqlite\";\n\n/** The values of the pragma `synchronous`. */\nexport type Synchronous = \"OFF\" | \"NORMAL\" | \"FULL\" | \"EXTRA\";\n\nconst SYNCHRONOUS: readonly Synchronous[] = [\"OFF\", \"NORMAL\", \"FULL\", \"EXTRA\"];\n\n/** The options of `openDatabase`. Each default is the default of SQLite, but the journal is WAL by default. */\nexport interface OpenOptions {\n  /**\n   * This value turns on the write-ahead log (WAL). The default is true. Then readers do not stop a writer. A database\n   * with no file keeps its journal in memory.\n   */\n  readonly wal?: boolean | undefined;\n  /**\n   * This value is the pragma `synchronous`. The default is `FULL`: a commit is on the disk when the call ends. With WAL,\n   * `NORMAL` can lose the last commits at a power cut, and the file stays good.\n   */\n  readonly synchronous?: Synchronous | undefined;\n  /**\n   * This value is the time in milliseconds that a statement waits for the lock of a different connection. The default\n   * is 0: then the statement fails at once with \"database is locked\".\n   */\n  readonly busyTimeoutMs?: number | undefined;\n  /** This value makes the folder of the file when the folder is not there. The default is false. */\n  readonly makeFolder?: boolean | undefined;\n  /** This value is the mode of the folders that `makeFolder` makes, for example `0o700`. */\n  readonly folderMode?: number | undefined;\n}\n\n/**\n * This function opens a database, and makes the file when it is not there. `:memory:` gives a database with no file.\n *\n * The function sets the busy timeout first, because the change to WAL needs the lock of the file. When a pragma\n * fails, the function closes the connection and throws the error.\n *\n * @param path - The path of the file, or `:memory:`.\n * @param options - The pragmas and the folder.\n */\nexport function openDatabase(path: string, options: OpenOptions = {}): DatabaseSync {\n  const synchronous = options.synchronous ?? \"FULL\";\n  if (!SYNCHRONOUS.includes(synchronous)) {\n    throw new RangeError(`The value of synchronous must be one of ${SYNCHRONOUS.join(\", \")}, not ${String(synchronous)}.`);\n  }\n  const busyTimeoutMs = options.busyTimeoutMs ?? 0;\n  if (!Number.isInteger(busyTimeoutMs) || busyTimeoutMs < 0) {\n    throw new RangeError(`The busy timeout must be a whole number of milliseconds of 0 or more, not ${String(busyTimeoutMs)}.`);\n  }\n  if (options.makeFolder === true && path !== \":memory:\") {\n    mkdirSync(dirname(path), options.folderMode === undefined ? { recursive: true } : { recursive: true, mode: options.folderMode });\n  }\n  const db = new DatabaseSync(path);\n  try {\n    db.exec(`PRAGMA busy_timeout = ${String(busyTimeoutMs)}`);\n    if (options.wal ?? true) db.exec(\"PRAGMA journal_mode = WAL\");\n    db.exec(`PRAGMA synchronous = ${synchronous}`);\n  } catch (error) {\n    db.close();\n    throw error;\n  }\n  return db;\n}\n"],"mappings":";;;;;;;;;AAYA,MAAM,cAAsC;CAAC;CAAO;CAAU;CAAQ;AAAO;;;;;;;;;;AAkC7E,SAAgB,aAAa,MAAc,UAAuB,CAAC,GAAiB;CAClF,MAAM,cAAc,QAAQ,eAAe;CAC3C,IAAI,CAAC,YAAY,SAAS,WAAW,GACnC,MAAM,IAAI,WAAW,2CAA2C,YAAY,KAAK,IAAI,EAAE,QAAQ,OAAO,WAAW,EAAE,EAAE;CAEvH,MAAM,gBAAgB,QAAQ,iBAAiB;CAC/C,IAAI,CAAC,OAAO,UAAU,aAAa,KAAK,gBAAgB,GACtD,MAAM,IAAI,WAAW,6EAA6E,OAAO,aAAa,EAAE,EAAE;CAE5H,IAAI,QAAQ,eAAe,QAAQ,SAAS,YAC1C,UAAU,QAAQ,IAAI,GAAG,QAAQ,eAAe,KAAA,IAAY,EAAE,WAAW,KAAK,IAAI;EAAE,WAAW;EAAM,MAAM,QAAQ;CAAW,CAAC;CAEjI,MAAM,KAAK,IAAI,aAAa,IAAI;CAChC,IAAI;EACF,GAAG,KAAK,yBAAyB,OAAO,aAAa,GAAG;EACxD,IAAI,QAAQ,OAAO,MAAM,GAAG,KAAK,2BAA2B;EAC5D,GAAG,KAAK,wBAAwB,aAAa;CAC/C,SAAS,OAAO;EACd,GAAG,MAAM;EACT,MAAM;CACR;CACA,OAAO;AACT"}

package/build/event-log.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A typed append-only log of events in one SQLite file. The caller keeps a state, and the log keeps the file equal to it.
+ *
+ * @packageDocumentation
+ */
+import { OpenOptions } from "./database.js";
+/** The fields that the log reads from each event. The log keeps the full event as JSON. */
+export interface LogRecord {
+  readonly id: string;
+  readonly at: string;
+  readonly type: string;
+}
+/**
+ * This function accepts an event into the state of the caller, or refuses it. It gives a problem when it refuses the
+ * event, and then it must not change the state.
+ */
+export type Accept<E, P> = (event: E) => P | undefined;
+/** An open log. */
+export interface EventLog<E extends LogRecord> {
+  /** This function gives each event of the log, in the order of the log. */
+  read(): Generator<E>;
+  /** This function accepts the event first, and then writes it. A refused event is not written. */
+  append<P>(event: E, accept: Accept<E, P>): P | undefined;
+  /** This function does `append` for each event, in one transaction. It gives the problems of the refused events. */
+  appendAll<P>(events: Iterable<E>, accept: Accept<E, P>): P[];
+  /** This function gives the count of events in the log. */
+  count(): number;
+  /**
+   * This function makes a broken log usable again. It throws when the rollback of the failed write did not end, and
+   * then the log stays broken. After it, the caller replays the log, so its state is equal to the file again.
+   */
+  recover(): void;
+  /** This function closes the file. */
+  close(): void;
+}
+/** The schema version that `openEventLog` writes: the `user_version` of a log file. */
+export declare const EVENT_LOG_SCHEMA_VERSION: number;
+/**
+ * This function opens a log, and makes the file when it is not there. `:memory:` gives a log with no file.
+ *
+ * The state of the caller and the file stay equal: `accept` comes before the write. A write or an `accept` can fail with an
+ * error. Then the transaction rolls back, and the log is broken. Each later call throws until `recover`. The state of the
+ * caller can keep the events of the failed write, so the caller replays the log after `recover`.
+ *
+ * The log owns the `user_version` of its file. A file of a newer schema version gives an error.
+ *
+ * @param path - The path of the file, or `:memory:`.
+ * @param parse - The function that changes a stored JSON value into an event. It throws on a value that is not an event.
+ * @param options - The pragmas of the connection. The defaults are the defaults of `openDatabase`.
+ */
+export declare function openEventLog<E extends LogRecord>(path: string, parse: (value: unknown) => E, options?: OpenOptions): EventLog<E>;
+//# sourceMappingURL=event-log.d.ts.map

package/build/event-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-log.d.ts","names":[],"sources":["../src/event-log.ts"],"mappings":";;;;;;;iBAUiB;WACN;WACA;WACA;;;;;;YAOC,OAAO,GAAG,MAAM,OAAO,MAAM;;iBAGxB,SAAS,UAAU;;EAElC,QAAQ,UAAU;;EAElB,OAAO,GAAG,OAAO,GAAG,QAAQ,OAAO,GAAG,KAAK;;EAE3C,UAAU,GAAG,QAAQ,SAAS,IAAI,QAAQ,OAAO,GAAG,KAAK;;EAEzD;;;;;EAKA;;EAEA;;;qBAeW;;;;;;;;;;;;;;wBAeG,aAAa,UAAU,WAAW,cAAc,QAAQ,mBAAmB,GAAG,UAAS,cAAmB,SAAS"}

package/build/event-log.js

@@ -0,0 +1,109 @@
+import { openDatabase } from "./database.js";
+import { migrate } from "./migrate.js";
+import { transaction } from "./transaction.js";
+// src/event-log.ts
+/**
+* A typed append-only log of events in one SQLite file. The caller keeps a state, and the log keeps the file equal to it.
+*
+* @packageDocumentation
+*/
+/** Each entry is one step of the schema of the log. */
+const MIGRATIONS = [`CREATE TABLE events (
+     seq INTEGER PRIMARY KEY,
+     id TEXT NOT NULL UNIQUE,
+     at TEXT NOT NULL,
+     type TEXT NOT NULL,
+     body TEXT NOT NULL
+   ) STRICT`];
+/** The schema version that `openEventLog` writes: the `user_version` of a log file. */
+const EVENT_LOG_SCHEMA_VERSION = MIGRATIONS.length;
+/**
+* This function opens a log, and makes the file when it is not there. `:memory:` gives a log with no file.
+*
+* The state of the caller and the file stay equal: `accept` comes before the write. A write or an `accept` can fail with an
+* error. Then the transaction rolls back, and the log is broken. Each later call throws until `recover`. The state of the
+* caller can keep the events of the failed write, so the caller replays the log after `recover`.
+*
+* The log owns the `user_version` of its file. A file of a newer schema version gives an error.
+*
+* @param path - The path of the file, or `:memory:`.
+* @param parse - The function that changes a stored JSON value into an event. It throws on a value that is not an event.
+* @param options - The pragmas of the connection. The defaults are the defaults of `openDatabase`.
+*/
+function openEventLog(path, parse, options = {}) {
+	const db = openDatabase(path, options);
+	try {
+		migrate(db, MIGRATIONS, { name: "log" });
+	} catch (error) {
+		db.close();
+		throw error;
+	}
+	const insert = db.prepare("INSERT INTO events (id, at, type, body) VALUES (?, ?, ?, ?)");
+	/** The error of a failed write. A broken log refuses each call until `recover`. */
+	let broken;
+	/** The error of a rollback that did not end. A log with this error cannot recover. */
+	let stuck;
+	const onRollbackError = (error) => {
+		stuck = error;
+	};
+	function guard() {
+		if (broken !== void 0) throw new Error("The log is broken by an earlier error. Open it again and replay it.", { cause: broken });
+	}
+	function write(event, accept) {
+		const problem = accept(event);
+		if (problem !== void 0) return problem;
+		insert.run(event.id, event.at, event.type, JSON.stringify(event));
+	}
+	/** This function does the work in one transaction. A failure after the `BEGIN` breaks the log. */
+	function inTransaction(work) {
+		guard();
+		let began = false;
+		try {
+			return transaction(db, () => {
+				began = true;
+				return work();
+			}, { onRollbackError });
+		} catch (error) {
+			if (began) broken = error;
+			throw error;
+		}
+	}
+	return {
+		*read() {
+			guard();
+			for (const row of db.prepare("SELECT seq, body FROM events ORDER BY seq").iterate()) try {
+				yield parse(JSON.parse(row.body));
+			} catch (error) {
+				throw new Error(`The event at the position ${String(row.seq)} of the log is not valid.`, { cause: error });
+			}
+		},
+		append(event, accept) {
+			return inTransaction(() => write(event, accept));
+		},
+		appendAll(events, accept) {
+			return inTransaction(() => {
+				const problems = [];
+				for (const event of events) {
+					const problem = write(event, accept);
+					if (problem !== void 0) problems.push(problem);
+				}
+				return problems;
+			});
+		},
+		count() {
+			guard();
+			return db.prepare("SELECT count(*) AS n FROM events").get().n;
+		},
+		recover() {
+			if (broken === void 0) return;
+			if (stuck !== void 0 || db.isTransaction) throw new Error("The rollback of the failed write did not end. Open the log again and replay it.", { cause: stuck ?? broken });
+			broken = void 0;
+		},
+		close() {
+			db.close();
+		}
+	};
+}
+export { EVENT_LOG_SCHEMA_VERSION, openEventLog };
+
+//# sourceMappingURL=event-log.js.map

package/build/event-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-log.js","names":[],"sources":["../src/event-log.ts"],"sourcesContent":["/**\n * A typed append-only log of events in one SQLite file. The caller keeps a state, and the log keeps the file equal to it.\n *\n * @packageDocumentation\n */\nimport { openDatabase, type OpenOptions } from \"./database.ts\";\nimport { migrate, type Migration } from \"./migrate.ts\";\nimport { transaction } from \"./transaction.ts\";\n\n/** The fields that the log reads from each event. The log keeps the full event as JSON. */\nexport interface LogRecord {\n  readonly id: string;\n  readonly at: string;\n  readonly type: string;\n}\n\n/**\n * This function accepts an event into the state of the caller, or refuses it. It gives a problem when it refuses the\n * event, and then it must not change the state.\n */\nexport type Accept<E, P> = (event: E) => P | undefined;\n\n/** An open log. */\nexport interface EventLog<E extends LogRecord> {\n  /** This function gives each event of the log, in the order of the log. */\n  read(): Generator<E>;\n  /** This function accepts the event first, and then writes it. A refused event is not written. */\n  append<P>(event: E, accept: Accept<E, P>): P | undefined;\n  /** This function does `append` for each event, in one transaction. It gives the problems of the refused events. */\n  appendAll<P>(events: Iterable<E>, accept: Accept<E, P>): P[];\n  /** This function gives the count of events in the log. */\n  count(): number;\n  /**\n   * This function makes a broken log usable again. It throws when the rollback of the failed write did not end, and\n   * then the log stays broken. After it, the caller replays the log, so its state is equal to the file again.\n   */\n  recover(): void;\n  /** This function closes the file. */\n  close(): void;\n}\n\n/** Each entry is one step of the schema of the log. */\nconst MIGRATIONS: readonly Migration[] = [\n  `CREATE TABLE events (\n     seq INTEGER PRIMARY KEY,\n     id TEXT NOT NULL UNIQUE,\n     at TEXT NOT NULL,\n     type TEXT NOT NULL,\n     body TEXT NOT NULL\n   ) STRICT`,\n];\n\n/** The schema version that `openEventLog` writes: the `user_version` of a log file. */\nexport const EVENT_LOG_SCHEMA_VERSION: number = MIGRATIONS.length;\n\n/**\n * This function opens a log, and makes the file when it is not there. `:memory:` gives a log with no file.\n *\n * The state of the caller and the file stay equal: `accept` comes before the write. A write or an `accept` can fail with an\n * error. Then the transaction rolls back, and the log is broken. Each later call throws until `recover`. The state of the\n * caller can keep the events of the failed write, so the caller replays the log after `recover`.\n *\n * The log owns the `user_version` of its file. A file of a newer schema version gives an error.\n *\n * @param path - The path of the file, or `:memory:`.\n * @param parse - The function that changes a stored JSON value into an event. It throws on a value that is not an event.\n * @param options - The pragmas of the connection. The defaults are the defaults of `openDatabase`.\n */\nexport function openEventLog<E extends LogRecord>(path: string, parse: (value: unknown) => E, options: OpenOptions = {}): EventLog<E> {\n  const db = openDatabase(path, options);\n  try {\n    migrate(db, MIGRATIONS, { name: \"log\" });\n  } catch (error) {\n    db.close();\n    throw error;\n  }\n  const insert = db.prepare(\"INSERT INTO events (id, at, type, body) VALUES (?, ?, ?, ?)\");\n  /** The error of a failed write. A broken log refuses each call until `recover`. */\n  let broken: unknown;\n  /** The error of a rollback that did not end. A log with this error cannot recover. */\n  let stuck: unknown;\n  const onRollbackError = (error: unknown): void => {\n    stuck = error;\n  };\n\n  function guard(): void {\n    if (broken !== undefined) throw new Error(\"The log is broken by an earlier error. Open it again and replay it.\", { cause: broken });\n  }\n\n  function write<P>(event: E, accept: Accept<E, P>): P | undefined {\n    const problem = accept(event);\n    if (problem !== undefined) return problem;\n    insert.run(event.id, event.at, event.type, JSON.stringify(event));\n    return undefined;\n  }\n\n  /** This function does the work in one transaction. A failure after the `BEGIN` breaks the log. */\n  function inTransaction<T>(work: () => T): T {\n    guard();\n    let began = false;\n    try {\n      return transaction(\n        db,\n        () => {\n          began = true;\n          return work();\n        },\n        { onRollbackError },\n      );\n    } catch (error) {\n      if (began) broken = error;\n      throw error;\n    }\n  }\n\n  return {\n    *read() {\n      guard();\n      for (const row of db.prepare(\"SELECT seq, body FROM events ORDER BY seq\").iterate() as Iterable<{ seq: number; body: string }>) {\n        try {\n          yield parse(JSON.parse(row.body));\n        } catch (error) {\n          throw new Error(`The event at the position ${String(row.seq)} of the log is not valid.`, { cause: error });\n        }\n      }\n    },\n    append(event, accept) {\n      return inTransaction(() => write(event, accept));\n    },\n    appendAll(events, accept) {\n      return inTransaction(() => {\n        const problems = [];\n        for (const event of events) {\n          const problem = write(event, accept);\n          if (problem !== undefined) problems.push(problem);\n        }\n        return problems;\n      });\n    },\n    count() {\n      guard();\n      return (db.prepare(\"SELECT count(*) AS n FROM events\").get() as { n: number }).n;\n    },\n    recover() {\n      if (broken === undefined) return;\n      if (stuck !== undefined || db.isTransaction) {\n        throw new Error(\"The rollback of the failed write did not end. Open the log again and replay it.\", { cause: stuck ?? broken });\n      }\n      broken = undefined;\n    },\n    close() {\n      db.close();\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;AA0CA,MAAM,aAAmC,CACvC;;;;;;YAOF;;AAGA,MAAa,2BAAmC,WAAW;;;;;;;;;;;;;;AAe3D,SAAgB,aAAkC,MAAc,OAA8B,UAAuB,CAAC,GAAgB;CACpI,MAAM,KAAK,aAAa,MAAM,OAAO;CACrC,IAAI;EACF,QAAQ,IAAI,YAAY,EAAE,MAAM,MAAM,CAAC;CACzC,SAAS,OAAO;EACd,GAAG,MAAM;EACT,MAAM;CACR;CACA,MAAM,SAAS,GAAG,QAAQ,6DAA6D;;CAEvF,IAAI;;CAEJ,IAAI;CACJ,MAAM,mBAAmB,UAAyB;EAChD,QAAQ;CACV;CAEA,SAAS,QAAc;EACrB,IAAI,WAAW,KAAA,GAAW,MAAM,IAAI,MAAM,uEAAuE,EAAE,OAAO,OAAO,CAAC;CACpI;CAEA,SAAS,MAAS,OAAU,QAAqC;EAC/D,MAAM,UAAU,OAAO,KAAK;EAC5B,IAAI,YAAY,KAAA,GAAW,OAAO;EAClC,OAAO,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,MAAM,KAAK,UAAU,KAAK,CAAC;CAElE;;CAGA,SAAS,cAAiB,MAAkB;EAC1C,MAAM;EACN,IAAI,QAAQ;EACZ,IAAI;GACF,OAAO,YACL,UACM;IACJ,QAAQ;IACR,OAAO,KAAK;GACd,GACA,EAAE,gBAAgB,CACpB;EACF,SAAS,OAAO;GACd,IAAI,OAAO,SAAS;GACpB,MAAM;EACR;CACF;CAEA,OAAO;EACL,CAAC,OAAO;GACN,MAAM;GACN,KAAK,MAAM,OAAO,GAAG,QAAQ,2CAA2C,CAAC,CAAC,QAAQ,GAChF,IAAI;IACF,MAAM,MAAM,KAAK,MAAM,IAAI,IAAI,CAAC;GAClC,SAAS,OAAO;IACd,MAAM,IAAI,MAAM,6BAA6B,OAAO,IAAI,GAAG,EAAE,4BAA4B,EAAE,OAAO,MAAM,CAAC;GAC3G;EAEJ;EACA,OAAO,OAAO,QAAQ;GACpB,OAAO,oBAAoB,MAAM,OAAO,MAAM,CAAC;EACjD;EACA,UAAU,QAAQ,QAAQ;GACxB,OAAO,oBAAoB;IACzB,MAAM,WAAW,CAAC;IAClB,KAAK,MAAM,SAAS,QAAQ;KAC1B,MAAM,UAAU,MAAM,OAAO,MAAM;KACnC,IAAI,YAAY,KAAA,GAAW,SAAS,KAAK,OAAO;IAClD;IACA,OAAO;GACT,CAAC;EACH;EACA,QAAQ;GACN,MAAM;GACN,OAAQ,GAAG,QAAQ,kCAAkC,CAAC,CAAC,IAAI,CAAC,CAAmB;EACjF;EACA,UAAU;GACR,IAAI,WAAW,KAAA,GAAW;GAC1B,IAAI,UAAU,KAAA,KAAa,GAAG,eAC5B,MAAM,IAAI,MAAM,mFAAmF,EAAE,OAAO,SAAS,OAAO,CAAC;GAE/H,SAAS,KAAA;EACX;EACA,QAAQ;GACN,GAAG,MAAM;EACX;CACF;AACF"}

package/build/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Databases on one computer through `node:sqlite`: the connection with its pragmas, the migrations by `user_version`,
+ * the write transaction and a typed append-only event log. The entry `@mark1russell7/sqlite/warning` has the filter of
+ * the experimental warning.
+ *
+ * @packageDocumentation
+ */
+import { OpenOptions, Synchronous, openDatabase } from "./database.js";
+import { MigrateOptions, Migrated, Migration, migrate, userVersion } from "./migrate.js";
+import { TransactionDatabase, TransactionOptions, transaction } from "./transaction.js";
+import { Accept, EVENT_LOG_SCHEMA_VERSION, EventLog, LogRecord, openEventLog } from "./event-log.js";
+export { type Accept, EVENT_LOG_SCHEMA_VERSION, type EventLog, type LogRecord, type MigrateOptions, type Migrated, type Migration, type OpenOptions, type Synchronous, type TransactionDatabase, type TransactionOptions, migrate, openDatabase, openEventLog, transaction, userVersion };

package/build/index.js

@@ -0,0 +1,5 @@
+import { openDatabase } from "./database.js";
+import { migrate, userVersion } from "./migrate.js";
+import { transaction } from "./transaction.js";
+import { EVENT_LOG_SCHEMA_VERSION, openEventLog } from "./event-log.js";
+export { EVENT_LOG_SCHEMA_VERSION, migrate, openDatabase, openEventLog, transaction, userVersion };

package/build/migrate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The migrations of a schema by the pragma `user_version`: the version of a file is the count of steps that it has.
+ *
+ * @packageDocumentation
+ */
+import { DatabaseSync } from "node:sqlite";
+/**
+ * One step of a schema: SQL statements, or a function that changes the database. A step operates in the transaction of
+ * its migration, so it does not start a transaction.
+ */
+export type Migration = string | ((db: DatabaseSync) => void);
+/** The options of `migrate`. */
+export interface MigrateOptions {
+  /** This value is the name of the database in the error for a newer file, for example `log`. The default is `database`. */
+  readonly name?: string | undefined;
+}
+/** The versions of a file before and after `migrate`. */
+export interface Migrated {
+  readonly from: number;
+  readonly to: number;
+}
+/** This function gives the pragma `user_version` of a database. */
+export declare function userVersion(db: DatabaseSync): number;
+/**
+ * This function does the steps that a database does not have, in order. The `user_version` of the file is the count of
+ * steps that it has.
+ *
+ * Each step is one `BEGIN IMMEDIATE` transaction with its new `user_version`. A step that fails rolls back alone, and
+ * the steps before it stay. In the transaction, the function reads the version again, so two processes can migrate
+ * one file at the same time. A file with more steps than `migrations` is from a newer version of the app, and the
+ * function throws.
+ *
+ * @param db - The connection.
+ * @param migrations - The steps of the schema. Do not change a step that a file can have: add a new step.
+ * @param options - The name of the database in the errors.
+ */
+export declare function migrate(db: DatabaseSync, migrations: readonly Migration[], options?: MigrateOptions): Migrated;
+//# sourceMappingURL=migrate.d.ts.map

package/build/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","names":[],"sources":["../src/migrate.ts"],"mappings":";;;;;;;;;;YAYY,uBAAuB,IAAI;;iBAGtB;;WAEN;;;iBAIM;WACN;WACA;;;wBAIK,YAAY,IAAI;;;;;;;;;;;;;;wBAkBhB,QAAQ,IAAI,cAAc,qBAAqB,aAAa,UAAS,iBAAsB"}

package/build/migrate.js

@@ -0,0 +1,46 @@
+import { transaction } from "./transaction.js";
+// src/migrate.ts
+/** This function gives the pragma `user_version` of a database. */
+function userVersion(db) {
+	return db.prepare("PRAGMA user_version").get().user_version;
+}
+/**
+* This function does the steps that a database does not have, in order. The `user_version` of the file is the count of
+* steps that it has.
+*
+* Each step is one `BEGIN IMMEDIATE` transaction with its new `user_version`. A step that fails rolls back alone, and
+* the steps before it stay. In the transaction, the function reads the version again, so two processes can migrate
+* one file at the same time. A file with more steps than `migrations` is from a newer version of the app, and the
+* function throws.
+*
+* @param db - The connection.
+* @param migrations - The steps of the schema. Do not change a step that a file can have: add a new step.
+* @param options - The name of the database in the errors.
+*/
+function migrate(db, migrations, options = {}) {
+	const name = options.name ?? "database";
+	const known = migrations.length;
+	const refuseNewer = (version) => {
+		if (version > known) throw new Error(`The ${name} has the schema version ${String(version)}, and this code knows only ${String(known)}. Use a newer version of the app.`);
+	};
+	const from = userVersion(db);
+	refuseNewer(from);
+	let version = from;
+	while (version < known) version = transaction(db, () => {
+		const current = userVersion(db);
+		refuseNewer(current);
+		if (current === known) return current;
+		const step = migrations[current];
+		if (typeof step === "string") db.exec(step);
+		else step(db);
+		db.exec(`PRAGMA user_version = ${String(current + 1)}`);
+		return current + 1;
+	});
+	return {
+		from,
+		to: version
+	};
+}
+export { migrate, userVersion };
+
+//# sourceMappingURL=migrate.js.map

package/build/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","names":[],"sources":["../src/migrate.ts"],"sourcesContent":["/**\n * The migrations of a schema by the pragma `user_version`: the version of a file is the count of steps that it has.\n *\n * @packageDocumentation\n */\nimport type { DatabaseSync } from \"node:sqlite\";\nimport { transaction } from \"./transaction.ts\";\n\n/**\n * One step of a schema: SQL statements, or a function that changes the database. A step operates in the transaction of\n * its migration, so it does not start a transaction.\n */\nexport type Migration = string | ((db: DatabaseSync) => void);\n\n/** The options of `migrate`. */\nexport interface MigrateOptions {\n  /** This value is the name of the database in the error for a newer file, for example `log`. The default is `database`. */\n  readonly name?: string | undefined;\n}\n\n/** The versions of a file before and after `migrate`. */\nexport interface Migrated {\n  readonly from: number;\n  readonly to: number;\n}\n\n/** This function gives the pragma `user_version` of a database. */\nexport function userVersion(db: DatabaseSync): number {\n  const row = db.prepare(\"PRAGMA user_version\").get() as { user_version: number };\n  return row.user_version;\n}\n\n/**\n * This function does the steps that a database does not have, in order. The `user_version` of the file is the count of\n * steps that it has.\n *\n * Each step is one `BEGIN IMMEDIATE` transaction with its new `user_version`. A step that fails rolls back alone, and\n * the steps before it stay. In the transaction, the function reads the version again, so two processes can migrate\n * one file at the same time. A file with more steps than `migrations` is from a newer version of the app, and the\n * function throws.\n *\n * @param db - The connection.\n * @param migrations - The steps of the schema. Do not change a step that a file can have: add a new step.\n * @param options - The name of the database in the errors.\n */\nexport function migrate(db: DatabaseSync, migrations: readonly Migration[], options: MigrateOptions = {}): Migrated {\n  const name = options.name ?? \"database\";\n  const known = migrations.length;\n  const refuseNewer = (version: number): void => {\n    if (version > known) {\n      throw new Error(`The ${name} has the schema version ${String(version)}, and this code knows only ${String(known)}. Use a newer version of the app.`);\n    }\n  };\n  const from = userVersion(db);\n  refuseNewer(from);\n  let version = from;\n  while (version < known) {\n    version = transaction(db, () => {\n      const current = userVersion(db);\n      refuseNewer(current);\n      if (current === known) return current;\n      const step = migrations[current] as Migration;\n      if (typeof step === \"string\") db.exec(step);\n      else step(db);\n      db.exec(`PRAGMA user_version = ${String(current + 1)}`);\n      return current + 1;\n    });\n  }\n  return { from, to: version };\n}\n"],"mappings":";;;AA2BA,SAAgB,YAAY,IAA0B;CAEpD,OADY,GAAG,QAAQ,qBAAqB,CAAC,CAAC,IACrC,CAAC,CAAC;AACb;;;;;;;;;;;;;;AAeA,SAAgB,QAAQ,IAAkB,YAAkC,UAA0B,CAAC,GAAa;CAClH,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,QAAQ,WAAW;CACzB,MAAM,eAAe,YAA0B;EAC7C,IAAI,UAAU,OACZ,MAAM,IAAI,MAAM,OAAO,KAAK,0BAA0B,OAAO,OAAO,EAAE,6BAA6B,OAAO,KAAK,EAAE,kCAAkC;CAEvJ;CACA,MAAM,OAAO,YAAY,EAAE;CAC3B,YAAY,IAAI;CAChB,IAAI,UAAU;CACd,OAAO,UAAU,OACf,UAAU,YAAY,UAAU;EAC9B,MAAM,UAAU,YAAY,EAAE;EAC9B,YAAY,OAAO;EACnB,IAAI,YAAY,OAAO,OAAO;EAC9B,MAAM,OAAO,WAAW;EACxB,IAAI,OAAO,SAAS,UAAU,GAAG,KAAK,IAAI;OACrC,KAAK,EAAE;EACZ,GAAG,KAAK,yBAAyB,OAAO,UAAU,CAAC,GAAG;EACtD,OAAO,UAAU;CACnB,CAAC;CAEH,OAAO;EAAE;EAAM,IAAI;CAAQ;AAC7B"}

package/build/transaction.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The write transaction: `BEGIN IMMEDIATE`, the work, and `COMMIT`, or a `ROLLBACK` after an error.
+ *
+ * @packageDocumentation
+ */
+import { DatabaseSync } from "node:sqlite";
+/** The part of a connection that a transaction uses. A test can give a fake. */
+export type TransactionDatabase = Pick<DatabaseSync, "exec" | "isTransaction">;
+/** The options of `transaction`. */
+export interface TransactionOptions {
+  /**
+   * This function gets the error of a rollback that did not end. Then the connection can stay in the transaction, and
+   * each later `BEGIN` throws. The work error stays the error that `transaction` throws.
+   */
+  readonly onRollbackError?: ((error: unknown) => void) | undefined;
+}
+/**
+ * This function does the work in one write transaction, and gives the result of the work.
+ *
+ * `BEGIN IMMEDIATE` takes the write lock at the start, so a different writer cannot cause a failure in the middle of
+ * the work. The busy timeout of the connection sets the wait for that lock. When the work or the commit throws, the
+ * function rolls back and throws the same error. The work is synchronous: a work that gives a promise is an error.
+ * A call in a transaction throws, because SQLite refuses a `BEGIN` there.
+ *
+ * @param db - The connection.
+ * @param work - The work. Its writes are part of the transaction.
+ * @param options - The function that gets a failed rollback.
+ */
+export declare function transaction<T>(db: TransactionDatabase, work: () => T, options?: TransactionOptions): T;
+//# sourceMappingURL=transaction.d.ts.map

package/build/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","names":[],"sources":["../src/transaction.ts"],"mappings":";;;;;;;YAQY,sBAAsB,KAAK;;iBAGtB;;;;;WAKN,oBAAoB;;;;;;;;;;;;;;wBAoBf,YAAY,GAAG,IAAI,qBAAqB,YAAY,GAAG,UAAS,qBAA0B"}

package/build/transaction.js

@@ -0,0 +1,36 @@
+// src/transaction.ts
+/** This function tells if a value is a promise or a different thenable. */
+function isThenable(value) {
+	return (typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function";
+}
+/**
+* This function does the work in one write transaction, and gives the result of the work.
+*
+* `BEGIN IMMEDIATE` takes the write lock at the start, so a different writer cannot cause a failure in the middle of
+* the work. The busy timeout of the connection sets the wait for that lock. When the work or the commit throws, the
+* function rolls back and throws the same error. The work is synchronous: a work that gives a promise is an error.
+* A call in a transaction throws, because SQLite refuses a `BEGIN` there.
+*
+* @param db - The connection.
+* @param work - The work. Its writes are part of the transaction.
+* @param options - The function that gets a failed rollback.
+*/
+function transaction(db, work, options = {}) {
+	db.exec("BEGIN IMMEDIATE");
+	try {
+		const result = work();
+		if (isThenable(result)) throw new TypeError("The work of a transaction must be synchronous. The transaction rolled back.");
+		db.exec("COMMIT");
+		return result;
+	} catch (error) {
+		try {
+			if (db.isTransaction) db.exec("ROLLBACK");
+		} catch (rollback) {
+			options.onRollbackError?.(rollback);
+		}
+		throw error;
+	}
+}
+export { transaction };
+
+//# sourceMappingURL=transaction.js.map

package/build/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","names":[],"sources":["../src/transaction.ts"],"sourcesContent":["/**\n * The write transaction: `BEGIN IMMEDIATE`, the work, and `COMMIT`, or a `ROLLBACK` after an error.\n *\n * @packageDocumentation\n */\nimport type { DatabaseSync } from \"node:sqlite\";\n\n/** The part of a connection that a transaction uses. A test can give a fake. */\nexport type TransactionDatabase = Pick<DatabaseSync, \"exec\" | \"isTransaction\">;\n\n/** The options of `transaction`. */\nexport interface TransactionOptions {\n  /**\n   * This function gets the error of a rollback that did not end. Then the connection can stay in the transaction, and\n   * each later `BEGIN` throws. The work error stays the error that `transaction` throws.\n   */\n  readonly onRollbackError?: ((error: unknown) => void) | undefined;\n}\n\n/** This function tells if a value is a promise or a different thenable. */\nfunction isThenable(value: unknown): boolean {\n  return (typeof value === \"object\" || typeof value === \"function\") && value !== null && typeof (value as { then?: unknown }).then === \"function\";\n}\n\n/**\n * This function does the work in one write transaction, and gives the result of the work.\n *\n * `BEGIN IMMEDIATE` takes the write lock at the start, so a different writer cannot cause a failure in the middle of\n * the work. The busy timeout of the connection sets the wait for that lock. When the work or the commit throws, the\n * function rolls back and throws the same error. The work is synchronous: a work that gives a promise is an error.\n * A call in a transaction throws, because SQLite refuses a `BEGIN` there.\n *\n * @param db - The connection.\n * @param work - The work. Its writes are part of the transaction.\n * @param options - The function that gets a failed rollback.\n */\nexport function transaction<T>(db: TransactionDatabase, work: () => T, options: TransactionOptions = {}): T {\n  db.exec(\"BEGIN IMMEDIATE\");\n  try {\n    const result = work();\n    if (isThenable(result)) {\n      throw new TypeError(\"The work of a transaction must be synchronous. The transaction rolled back.\");\n    }\n    db.exec(\"COMMIT\");\n    return result;\n  } catch (error) {\n    try {\n      if (db.isTransaction) db.exec(\"ROLLBACK\");\n    } catch (rollback) {\n      options.onRollbackError?.(rollback);\n    }\n    throw error;\n  }\n}\n"],"mappings":";;AAoBA,SAAS,WAAW,OAAyB;CAC3C,QAAQ,OAAO,UAAU,YAAY,OAAO,UAAU,eAAe,UAAU,QAAQ,OAAQ,MAA6B,SAAS;AACvI;;;;;;;;;;;;;AAcA,SAAgB,YAAe,IAAyB,MAAe,UAA8B,CAAC,GAAM;CAC1G,GAAG,KAAK,iBAAiB;CACzB,IAAI;EACF,MAAM,SAAS,KAAK;EACpB,IAAI,WAAW,MAAM,GACnB,MAAM,IAAI,UAAU,6EAA6E;EAEnG,GAAG,KAAK,QAAQ;EAChB,OAAO;CACT,SAAS,OAAO;EACd,IAAI;GACF,IAAI,GAAG,eAAe,GAAG,KAAK,UAAU;EAC1C,SAAS,UAAU;GACjB,QAAQ,kBAAkB,QAAQ;EACpC;EACA,MAAM;CACR;AACF"}

package/build/warning.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A filter of the experimental warning of `node:sqlite`. Node.js 22 writes the warning to the standard error at the
+ * first load of `node:sqlite`. This file does not import `node:sqlite`, so a command loads it first.
+ *
+ * ```ts
+ * import { quietSqliteWarning } from "@mark1russell7/sqlite/warning";
+ *
+ * quietSqliteWarning();
+ * const { openDatabase } = await import("@mark1russell7/sqlite");
+ * ```
+ *
+ * @packageDocumentation
+ */
+/** The start of the text of the experimental warning of `node:sqlite`. */
+export declare const SQLITE_WARNING = "SQLite is an experimental feature";
+/** The part of `process` that the filter changes. A test can give a fake. */
+export interface WarningTarget {
+  emitWarning(warning: string | Error, ...rest: unknown[]): void;
+}
+/**
+ * This function tells if the arguments of `process.emitWarning` give the experimental warning of `node:sqlite`. The
+ * type of the warning is the second argument, the field `type` of the options, or the name of an `Error`.
+ */
+export declare function isSqliteWarning(warning: string | Error, ...rest: unknown[]): boolean;
+/**
+ * This function removes only the experimental warning of `node:sqlite` from `emitWarning`. Each other warning stays.
+ * Use it before the first import of `node:sqlite`. It gives a function that puts the earlier `emitWarning` back.
+ *
+ * @param target - The object with `emitWarning`. The default is `process`.
+ */
+export declare function quietSqliteWarning(target?: WarningTarget): () => void;
+//# sourceMappingURL=warning.d.ts.map

package/build/warning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warning.d.ts","names":[],"sources":["../src/warning.ts"],"mappings":";;;;;;;;;;;;;;qBAea;;iBAGI;EACf,YAAY,kBAAkB,UAAU;;;;;;wBAO1B,gBAAgB,kBAAkB,UAAU;;;;;;;wBAgB5C,mBAAmB,SAAQ"}

package/build/warning.js

@@ -0,0 +1,49 @@
+// src/warning.ts
+/**
+* A filter of the experimental warning of `node:sqlite`. Node.js 22 writes the warning to the standard error at the
+* first load of `node:sqlite`. This file does not import `node:sqlite`, so a command loads it first.
+*
+* ```ts
+* import { quietSqliteWarning } from "@mark1russell7/sqlite/warning";
+*
+* quietSqliteWarning();
+* const { openDatabase } = await import("@mark1russell7/sqlite");
+* ```
+*
+* @packageDocumentation
+*/
+/** The start of the text of the experimental warning of `node:sqlite`. */
+const SQLITE_WARNING = "SQLite is an experimental feature";
+/**
+* This function tells if the arguments of `process.emitWarning` give the experimental warning of `node:sqlite`. The
+* type of the warning is the second argument, the field `type` of the options, or the name of an `Error`.
+*/
+function isSqliteWarning(warning, ...rest) {
+	const first = rest[0];
+	let kind;
+	if (typeof first === "string") kind = first;
+	else if (typeof first === "object" && first !== null && "type" in first) kind = first.type;
+	else if (warning instanceof Error) kind = warning.name;
+	const text = typeof warning === "string" ? warning : warning.message;
+	return kind === "ExperimentalWarning" && text.startsWith("SQLite is an experimental feature");
+}
+/**
+* This function removes only the experimental warning of `node:sqlite` from `emitWarning`. Each other warning stays.
+* Use it before the first import of `node:sqlite`. It gives a function that puts the earlier `emitWarning` back.
+*
+* @param target - The object with `emitWarning`. The default is `process`.
+*/
+function quietSqliteWarning(target = process) {
+	const earlier = target.emitWarning;
+	const filtered = (warning, ...rest) => {
+		if (isSqliteWarning(warning, ...rest)) return;
+		earlier.call(target, warning, ...rest);
+	};
+	target.emitWarning = filtered;
+	return () => {
+		if (target.emitWarning === filtered) target.emitWarning = earlier;
+	};
+}
+export { SQLITE_WARNING, isSqliteWarning, quietSqliteWarning };
+
+//# sourceMappingURL=warning.js.map

package/build/warning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warning.js","names":[],"sources":["../src/warning.ts"],"sourcesContent":["/**\n * A filter of the experimental warning of `node:sqlite`. Node.js 22 writes the warning to the standard error at the\n * first load of `node:sqlite`. This file does not import `node:sqlite`, so a command loads it first.\n *\n * ```ts\n * import { quietSqliteWarning } from \"@mark1russell7/sqlite/warning\";\n *\n * quietSqliteWarning();\n * const { openDatabase } = await import(\"@mark1russell7/sqlite\");\n * ```\n *\n * @packageDocumentation\n */\n\n/** The start of the text of the experimental warning of `node:sqlite`. */\nexport const SQLITE_WARNING = \"SQLite is an experimental feature\";\n\n/** The part of `process` that the filter changes. A test can give a fake. */\nexport interface WarningTarget {\n  emitWarning(warning: string | Error, ...rest: unknown[]): void;\n}\n\n/**\n * This function tells if the arguments of `process.emitWarning` give the experimental warning of `node:sqlite`. The\n * type of the warning is the second argument, the field `type` of the options, or the name of an `Error`.\n */\nexport function isSqliteWarning(warning: string | Error, ...rest: unknown[]): boolean {\n  const first = rest[0];\n  let kind: unknown;\n  if (typeof first === \"string\") kind = first;\n  else if (typeof first === \"object\" && first !== null && \"type\" in first) kind = first.type;\n  else if (warning instanceof Error) kind = warning.name;\n  const text = typeof warning === \"string\" ? warning : warning.message;\n  return kind === \"ExperimentalWarning\" && text.startsWith(SQLITE_WARNING);\n}\n\n/**\n * This function removes only the experimental warning of `node:sqlite` from `emitWarning`. Each other warning stays.\n * Use it before the first import of `node:sqlite`. It gives a function that puts the earlier `emitWarning` back.\n *\n * @param target - The object with `emitWarning`. The default is `process`.\n */\nexport function quietSqliteWarning(target: WarningTarget = process): () => void {\n  const earlier = target.emitWarning;\n  const filtered = (warning: string | Error, ...rest: unknown[]): void => {\n    if (isSqliteWarning(warning, ...rest)) return;\n    earlier.call(target, warning, ...rest);\n  };\n  target.emitWarning = filtered;\n  return () => {\n    if (target.emitWarning === filtered) target.emitWarning = earlier;\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;AAeA,MAAa,iBAAiB;;;;;AAW9B,SAAgB,gBAAgB,SAAyB,GAAG,MAA0B;CACpF,MAAM,QAAQ,KAAK;CACnB,IAAI;CACJ,IAAI,OAAO,UAAU,UAAU,OAAO;MACjC,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,UAAU,OAAO,OAAO,MAAM;MACjF,IAAI,mBAAmB,OAAO,OAAO,QAAQ;CAClD,MAAM,OAAO,OAAO,YAAY,WAAW,UAAU,QAAQ;CAC7D,OAAO,SAAS,yBAAyB,KAAK,WAAA,mCAAyB;AACzE;;;;;;;AAQA,SAAgB,mBAAmB,SAAwB,SAAqB;CAC9E,MAAM,UAAU,OAAO;CACvB,MAAM,YAAY,SAAyB,GAAG,SAA0B;EACtE,IAAI,gBAAgB,SAAS,GAAG,IAAI,GAAG;EACvC,QAAQ,KAAK,QAAQ,SAAS,GAAG,IAAI;CACvC;CACA,OAAO,cAAc;CACrB,aAAa;EACX,IAAI,OAAO,gBAAgB,UAAU,OAAO,cAAc;CAC5D;AACF"}

package/package.json

@@ -1,13 +1,70 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/sqlite",
-  "version": "0.0.0-bootstrap.0",
-  "description": "A placeholder that lets npm trust the release workflow of mark1russell7/sqlite. Use a later version.",
+  "version": "0.1.0",
+  "description": "Databases on one computer through node:sqlite: the pragmas, migrations by user_version, BEGIN IMMEDIATE transactions, a typed append-only event log and a filter of the experimental warning.",
+  "keywords": [
+    "sqlite",
+    "node:sqlite",
+    "wal",
+    "migrations",
+    "user_version",
+    "transaction",
+    "event-log",
+    "append-only",
+    "event-sourcing",
+    "typescript"
+  ],
+  "homepage": "https://github.com/mark1russell7/sqlite/tree/main/packages/sqlite#readme",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/sqlite/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mark1russell7/sqlite.git"
+    "url": "git+https://github.com/mark1russell7/sqlite.git",
+    "directory": "packages/sqlite"
   },
   "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./build/index.js",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.js",
+      "default": "./build/index.js"
+    },
+    "./warning": {
+      "types": "./build/warning.d.ts",
+      "import": "./build/warning.js",
+      "default": "./build/warning.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "build"
+  ],
   "publishConfig": {
     "access": "public"
-  }
-}
+  },
+  "engines": {
+    "node": ">=22.16"
+  },
+  "devDependencies": {
+    "@mark1russell7/cue": "^2.0.0",
+    "@types/node": "^26.6.5",
+    "@vitest/coverage-v8": "^5.0.3",
+    "esbuild": "^0.28.2",
+    "tsdown": "^0.23.7",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json"
+  },
+  "types": "./build/index.d.ts"
+}