@mark1russell7/sqlite 0.0.0-stage → 0.2.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,188 @@
-# Temporary Holding Version
+# @mark1russell7/sqlite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Databases on one computer through `node:sqlite`. The package has the connection with its pragmas, the migrations by schema version and the write transaction. It also has a typed append-only event log and the faults of SQLite. 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.
+
+### A version for each part of a file
+
+A library and the app can keep their tables in one file. Each part then has its own list of steps and its own version. The option `part` names the part.
+
+```ts
+import { migrate, schemaVersion } from "@mark1russell7/sqlite";
+
+migrate(db, appSteps, { part: "app" });
+schemaVersion(db, "app"); // the count of steps of the part app
+```
+
+- The versions of the parts are in the table `schema_versions`. The `user_version` of the file does not change.
+- A migration without `part` uses the `user_version`, as before.
+- The option `name` sets the name of the database in the error of a newer file.
+
+## 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
+
+The event log is a typed append-only list of events, and a grow-only set: an event that the log has already changes nothing. Thus two copies that exchange their events get the same set, in each order of arrival.
+
+```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 "the name is in use";
+  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); // { kind: "added", seq: 1 }
+log.append({ id: "e1", at: "2026-11-14T00:00:00Z", type: "added", name: "b" }); // { kind: "conflict", seq: 1, stored: ... }
+```
+
+`append` gives one result, and `appendAll` gives one result for each event, in one transaction:
+
+| Result | When | What changes |
+| --- | --- | --- |
+| `added` | The log does not have the id, and `accept` accepts the event. | The log writes the event at the position `seq`. |
+| `duplicate` | The log has an equal event with the same id. | Nothing. `accept` does not get the event. |
+| `conflict` | The log has a different event with the same id. | Nothing. The result has the stored event. |
+| `refused` | `accept` gives a problem. | Nothing. The result has the problem. |
+
+- The default equality compares the JSON text of the two events. The option `equal` sets a different equality.
+- Give each event an id from its content, for example a hash. Then a second report of the same fact is a duplicate.
+- `accept` is optional. It gets only an event with a new id, before the write. Then the state of the caller and the file stay equal.
+
+### Reads
+
+- `read()` gives the events in the order of the log. `entries()` gives each event with its position `seq`.
+- The option `after` gives only the events after a position. `types` gives only the events of some types. `limit` sets the highest count.
+- `head()` gives the position of the last event. A read with `after: head` later gives only the new events.
+- `get(id)` gives the event with an id and its position.
+
+### A log in the file of the app
+
+`eventLog` opens a log in a table of a connection of the caller. The app keeps its own tables in the same file, and one file can have many logs.
+
+```ts
+import { eventLog, migrate, openDatabase } from "@mark1russell7/sqlite";
+
+const db = openDatabase("data/app.db", { busyTimeoutMs: 5000 });
+migrate(db, appSteps, { part: "app" });
+const reports = eventLog(db, { parse: parseReport, table: "reports" });
+```
+
+- The log keeps its version in the part `event-log:<table>`. `EVENT_LOG_SCHEMA_VERSION` is the version that it writes.
+- The log does not close the connection. A call of the log in a transaction of the caller throws.
+- `openEventLog` opens a log in its own file, with the table `events`. That log owns the `user_version` of its file.
+
+### A failed write
+
+- A failed write or `accept` rolls back and breaks the log. Each later call throws a `BrokenLogError` until `recover`.
+- After `recover`, the caller replays the log, because its state can have the events of the failed write.
+- `recover` throws when the rollback did not end. Then the error has `stuck: true`. Open the log again.
+- A lock that is not free at the start does not break the log. The call throws, and nothing changes.
+
+## The faults of SQLite
+
+`sqliteFault` gives the kind of an error of SQLite and the action that it needs. The function reads the result code, not the text of the message.
+
+```ts
+import { sqliteFault } from "@mark1russell7/sqlite";
+
+try {
+  log.append(event);
+} catch (error) {
+  const fault = sqliteFault(error);
+  if (fault?.action === "retry") schedule(event);
+  else throw error;
+}
+```
+
+| Action | Kinds | What to do |
+| --- | --- | --- |
+| `retry` | `busy`, `locked`, `aborted`, `interrupted`, `protocol`, `schema` | Do the work again later. |
+| `quarantine` | `corrupt`, `not-a-database` | Move the file away. Make the data again from its source or from a copy. |
+| `operator` | `full`, `io`, `read-only`, `cannot-open`, `permission`, `no-memory`, `no-lfs`, `other` | Tell a person: the computer needs more disk space, an access, a path or memory. |
+| `bug` | `sql`, `constraint`, `mismatch`, `misuse`, `range`, `too-big`, `not-found`, `internal`, `authorization` | Correct the program. The same work fails again. |
+
+- The function reads the error and then its chain of causes. Thus it finds the fault in a `BrokenLogError`.
+- It gives `undefined` for an error that is not of SQLite.
+- `SQLITE_FAULT_ACTIONS` is the table of the action of each kind.
+
+## 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,135 @@
+/**
+ * A typed append-only log of events in SQLite. The log is a grow-only set of events with an order: an event that the log
+ * has already changes nothing. The caller keeps a state, and the log keeps the file equal to it.
+ *
+ * @packageDocumentation
+ */
+import { OpenOptions } from "./database.js";
+import { DatabaseSync } from "node:sqlite";
+/** 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;
+/** This function tells if a new event is equal to the stored event with the same id. */
+export type Equal<E> = (stored: E, event: E) => boolean;
+/**
+ * The result of the append of one event.
+ *
+ * - `added`: the log did not have the id, `accept` accepted the event, and the log wrote it at the position `seq`.
+ * - `duplicate`: the log has an equal event at the position `seq`. Nothing changed, and `accept` did not get the event.
+ * - `conflict`: the log has a different event with the same id at the position `seq`. Nothing changed.
+ * - `refused`: `accept` refused the event with the problem `problem`. Nothing changed.
+ */
+export type Appended<E, P> = {
+  readonly kind: "added";
+  readonly seq: number;
+} | {
+  readonly kind: "duplicate";
+  readonly seq: number;
+} | {
+  readonly kind: "conflict";
+  readonly seq: number;
+  readonly stored: E;
+} | {
+  readonly kind: "refused";
+  readonly problem: P;
+};
+/** One event of a log and its position. The first position is 1, and each new event gets a higher position. */
+export interface LogEntry<E> {
+  readonly seq: number;
+  readonly event: E;
+}
+/** The options of a read of a log. */
+export interface ReadOptions {
+  /** This value is a position. The read gives only the events after it. The default is 0, so the read starts at the first event. */
+  readonly after?: number | undefined;
+  /** This value is a list of types. The read gives only the events of these types. The default is each type. */
+  readonly types?: readonly string[] | undefined;
+  /** This value is the highest count of events that the read gives. The default is no limit. */
+  readonly limit?: number | undefined;
+}
+/** An open log. */
+export interface EventLog<E extends LogRecord> {
+  /** This function gives the events of the log, in the order of the log. */
+  read(options?: ReadOptions): Generator<E>;
+  /** This function gives the events of the log with their positions, in the order of the log. */
+  entries(options?: ReadOptions): Generator<LogEntry<E>>;
+  /** This function gives the event with an id and its position, or `undefined` when the log does not have the id. */
+  get(id: string): LogEntry<E> | undefined;
+  /** This function gives the position of the last event, or 0 for an empty log. A read after it gives only new events. */
+  head(): number;
+  /**
+   * This function appends one event. An event that the log has already changes nothing. `accept` gets only an event with
+   * a new id, before the write. The default `accept` accepts each event.
+   */
+  append<P = never>(event: E, accept?: Accept<E, P>): Appended<E, P>;
+  /** This function does `append` for each event, in one transaction, and gives the result of each event in order. */
+  appendAll<P = never>(events: Iterable<E>, accept?: Accept<E, P>): Appended<E, P>[];
+  /** This function gives the count of events in the log. */
+  count(): number;
+  /**
+   * This function makes a broken log usable again. It throws a `BrokenLogError` 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;
+}
+/** A log that owns its connection: `openEventLog` gives it. */
+export interface EventLogFile<E extends LogRecord> extends EventLog<E> {
+  /** This function closes the connection of the log. */
+  close(): void;
+}
+/** The error of a call to a broken log. `stuck` is true when the rollback of the failed write did not end. */
+export declare class BrokenLogError extends Error {
+  override readonly name = "BrokenLogError";
+  readonly stuck: boolean;
+  constructor(message: string, stuck: boolean, cause: unknown);
+}
+/** The options of `eventLog`. */
+export interface EventLogOptions<E> {
+  /** This function changes a stored JSON value into an event. It throws on a value that is not an event. */
+  readonly parse: (value: unknown) => E;
+  /** This value is the name of the table of the log. The default is `events`. A file can have many logs in different tables. */
+  readonly table?: string | undefined;
+  /** This function tells if a new event is equal to the stored event with its id. The default compares the JSON text. */
+  readonly equal?: Equal<E> | undefined;
+}
+/** The options of `openEventLog`: the options of the connection, and the equality of events. */
+export interface EventLogFileOptions<E> extends OpenOptions {
+  /** This function tells if a new event is equal to the stored event with its id. The default compares the JSON text. */
+  readonly equal?: Equal<E> | undefined;
+}
+/** The schema version of a log: the `user_version` of a file of `openEventLog`, or the version of the part `event-log:<table>`. */
+export declare const EVENT_LOG_SCHEMA_VERSION: number;
+/**
+ * This function opens a log in a table of a connection of the caller. The log does not close the connection.
+ *
+ * The log keeps its schema version in the part `event-log:<table>` of the file (refer to `migrate`). Thus the app keeps its own
+ * tables and its own steps in the same file. A call of the log in a transaction of the caller throws, and the log does not break.
+ *
+ * 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 a `BrokenLogError` until `recover`.
+ * The state of the caller can keep the events of the failed write, so the caller replays the log after `recover`.
+ *
+ * @param db - The connection. Set its pragmas with `openDatabase`.
+ * @param options - The parse of the events, the table and the equality of events.
+ */
+export declare function eventLog<E extends LogRecord>(db: DatabaseSync, options: EventLogOptions<E>): EventLog<E>;
+/**
+ * This function opens a log in its own file, and makes the file when it is not there. `:memory:` gives a log with no file.
+ *
+ * The log owns the connection and the `user_version` of its file, and its table is `events`. A file of a newer schema
+ * version gives an error. The rules of `eventLog` apply.
+ *
+ * @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, and the equality of events. The defaults are the defaults of `openDatabase`.
+ */
+export declare function openEventLog<E extends LogRecord>(path: string, parse: (value: unknown) => E, options?: EventLogFileOptions<E>): EventLogFile<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":";;;;;;;;;iBAYiB;WACN;WACA;WACA;;;;;;YAOC,OAAO,GAAG,MAAM,OAAO,MAAM;;YAG7B,MAAM,MAAM,QAAQ,GAAG,OAAO;;;;;;;;;YAU9B,SAAS,GAAG;WACT;WAAwB;;WACxB;WAA4B;;WAC5B;WAA2B;WAAsB,QAAQ;;WACzD;WAA0B,SAAS;;;iBAGjC,SAAS;WACf;WACA,OAAO;;;iBAID;;WAEN;;WAEA;;WAEA;;;iBAIM,SAAS,UAAU;;EAElC,KAAK,UAAU,cAAc,UAAU;;EAEvC,QAAQ,UAAU,cAAc,UAAU,SAAS;;EAEnD,IAAI,aAAa,SAAS;;EAE1B;;;;;EAKA,OAAO,WAAW,OAAO,GAAG,SAAS,OAAO,GAAG,KAAK,SAAS,GAAG;;EAEhE,UAAU,WAAW,QAAQ,SAAS,IAAI,SAAS,OAAO,GAAG,KAAK,SAAS,GAAG;;EAE9E;;;;;EAKA;;;iBAIe,aAAa,UAAU,mBAAmB,SAAS;;EAElE;;;qBAIW,uBAAuB;oBAChB;WACT;EAET,YAAY,iBAAiB,gBAAgB;;;iBAO9B,gBAAgB;;WAEtB,QAAQ,mBAAmB;;WAE3B;;WAEA,QAAQ,MAAM;;;iBAIR,oBAAoB,WAAW;;WAErC,QAAQ,MAAM;;;qBAkBZ;;;;;;;;;;;;;;wBA8BG,SAAS,UAAU,WAAW,IAAI,cAAc,SAAS,gBAAgB,KAAK,SAAS;;;;;;;;;;;wBAiBvF,aAAa,UAAU,WAAW,cAAc,QAAQ,mBAAmB,GAAG,UAAS,oBAAoB,KAAU,aAAa"}

package/build/event-log.js

@@ -0,0 +1,201 @@
+import { openDatabase } from "./database.js";
+import { SCHEMA_VERSIONS_TABLE, migrate } from "./migrate.js";
+import { transaction } from "./transaction.js";
+// src/event-log.ts
+/** The error of a call to a broken log. `stuck` is true when the rollback of the failed write did not end. */
+var BrokenLogError = class extends Error {
+	name = "BrokenLogError";
+	stuck;
+	constructor(message, stuck, cause) {
+		super(message, { cause });
+		this.stuck = stuck;
+	}
+};
+/** The steps of the schema of a log in a table. Do not change a step: add a new step. */
+function logSteps(table) {
+	return [`CREATE TABLE ${table} (
+       seq INTEGER PRIMARY KEY,
+       id TEXT NOT NULL UNIQUE,
+       at TEXT NOT NULL,
+       type TEXT NOT NULL,
+       body TEXT NOT NULL
+     ) STRICT`, `CREATE INDEX ${table}_type ON ${table} (type, seq)`];
+}
+/** The schema version of a log: the `user_version` of a file of `openEventLog`, or the version of the part `event-log:<table>`. */
+const EVENT_LOG_SCHEMA_VERSION = logSteps("events").length;
+/** The default name of the table of a log. */
+const DEFAULT_TABLE = "events";
+/** This function throws when a name cannot be the table of a log. */
+function checkTable(table) {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table) || table.toLowerCase().startsWith("sqlite_") || table === "schema_versions") throw new RangeError(`The table of a log must be a name of letters, digits and underscores, and not ${SCHEMA_VERSIONS_TABLE} or sqlite_*, not ${JSON.stringify(table)}.`);
+}
+/** This function throws when a value is not a whole number at or above a lowest value. */
+function checkWhole(what, value, lowest) {
+	if (!Number.isInteger(value) || value < lowest) throw new RangeError(`${what} must be a whole number of ${String(lowest)} or more, not ${String(value)}.`);
+}
+/**
+* This function opens a log in a table of a connection of the caller. The log does not close the connection.
+*
+* The log keeps its schema version in the part `event-log:<table>` of the file (refer to `migrate`). Thus the app keeps its own
+* tables and its own steps in the same file. A call of the log in a transaction of the caller throws, and the log does not break.
+*
+* 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 a `BrokenLogError` until `recover`.
+* The state of the caller can keep the events of the failed write, so the caller replays the log after `recover`.
+*
+* @param db - The connection. Set its pragmas with `openDatabase`.
+* @param options - The parse of the events, the table and the equality of events.
+*/
+function eventLog(db, options) {
+	const table = options.table ?? DEFAULT_TABLE;
+	checkTable(table);
+	migrate(db, logSteps(table), {
+		part: `event-log:${table}`,
+		name: `log ${table}`
+	});
+	return attach(db, table, options.parse, options.equal);
+}
+/**
+* This function opens a log in its own file, and makes the file when it is not there. `:memory:` gives a log with no file.
+*
+* The log owns the connection and the `user_version` of its file, and its table is `events`. A file of a newer schema
+* version gives an error. The rules of `eventLog` apply.
+*
+* @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, and the equality of events. The defaults are the defaults of `openDatabase`.
+*/
+function openEventLog(path, parse, options = {}) {
+	const db = openDatabase(path, options);
+	try {
+		migrate(db, logSteps(DEFAULT_TABLE), { name: "log" });
+		return {
+			...attach(db, DEFAULT_TABLE, parse, options.equal),
+			close() {
+				db.close();
+			}
+		};
+	} catch (error) {
+		db.close();
+		throw error;
+	}
+}
+/** This function makes the log object on a table with a current schema. */
+function attach(db, table, parse, equal) {
+	const insert = db.prepare(`INSERT INTO ${table} (id, at, type, body) VALUES (?, ?, ?, ?)`);
+	const byId = db.prepare(`SELECT seq, body FROM ${table} WHERE id = ?`);
+	const readSql = `SELECT seq, body FROM ${table} WHERE seq > ? AND (? IS NULL OR type IN (SELECT value FROM json_each(?))) ORDER BY seq LIMIT ?`;
+	/** 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 BrokenLogError("The log is broken by an earlier error. Open it again and replay it.", stuck !== void 0, broken);
+	}
+	function decode(row) {
+		try {
+			return 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 });
+		}
+	}
+	function write(event, accept) {
+		const body = JSON.stringify(event);
+		const row = byId.get(event.id);
+		if (row !== void 0) {
+			if (equal === void 0 && row.body === body) return {
+				kind: "duplicate",
+				seq: row.seq
+			};
+			const stored = decode(row);
+			if (equal?.(stored, event) === true) return {
+				kind: "duplicate",
+				seq: row.seq
+			};
+			return {
+				kind: "conflict",
+				seq: row.seq,
+				stored
+			};
+		}
+		const problem = accept?.(event);
+		if (problem !== void 0) return {
+			kind: "refused",
+			problem
+		};
+		const result = insert.run(event.id, event.at, event.type, body);
+		return {
+			kind: "added",
+			seq: Number(result.lastInsertRowid)
+		};
+	}
+	/** 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;
+		}
+	}
+	function* entries(options = {}) {
+		guard();
+		const after = options.after ?? 0;
+		checkWhole("The position after", after, 0);
+		if (options.limit !== void 0) checkWhole("The limit of a read", options.limit, 1);
+		const types = options.types === void 0 ? null : JSON.stringify(options.types);
+		const rows = db.prepare(readSql).iterate(after, types, types, options.limit ?? -1);
+		for (const row of rows) yield {
+			seq: row.seq,
+			event: decode(row)
+		};
+	}
+	return {
+		*read(options) {
+			for (const entry of entries(options)) yield entry.event;
+		},
+		entries,
+		get(id) {
+			guard();
+			const row = byId.get(id);
+			return row === void 0 ? void 0 : {
+				seq: row.seq,
+				event: decode(row)
+			};
+		},
+		head() {
+			guard();
+			return db.prepare(`SELECT COALESCE(MAX(seq), 0) AS head FROM ${table}`).get().head;
+		},
+		append(event, accept) {
+			return inTransaction(() => write(event, accept));
+		},
+		appendAll(events, accept) {
+			return inTransaction(() => {
+				const results = [];
+				for (const event of events) results.push(write(event, accept));
+				return results;
+			});
+		},
+		count() {
+			guard();
+			return db.prepare(`SELECT count(*) AS n FROM ${table}`).get().n;
+		},
+		recover() {
+			if (broken === void 0) return;
+			if (stuck !== void 0 || db.isTransaction) throw new BrokenLogError("The rollback of the failed write did not end. Open the log again and replay it.", true, stuck ?? broken);
+			broken = void 0;
+		}
+	};
+}
+export { BrokenLogError, EVENT_LOG_SCHEMA_VERSION, eventLog, openEventLog };
+
+//# sourceMappingURL=event-log.js.map