@zukhruf/sqlite-snapshot 0.0.0-stage → 0.3.32

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ezzabuzaid
+
+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,119 @@
-# Temporary Holding Version
+# @zukhruf/sqlite-snapshot
 
-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.
+Some programs keep their data in a SQLite database, and write it while they run. Another program can read that database, but the reader must not see half of a change. For example, it must not read a row from one table before a commit and a row from another table after it. Also, the newest rows can be in the WAL file, not in the database file. This package opens such a database read-only, and holds one moment with a read transaction. Thus each query of the snapshot sees the same moment, and the tables agree. This is also known as snapshot isolation of a WAL reader.
+
+The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
+
+## Use it
+
+This project is an experiment. It uses only `node:sqlite`.
+
+```sh
+npm install @zukhruf/sqlite-snapshot
+```
+
+```ts
+import { mkdtempDisposable } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+import { Snapshot } from '@zukhruf/sqlite-snapshot';
+
+class Unavailable extends Error {
+  constructor(path: string, cause: unknown) {
+    super(`Cannot read ${path}`, { cause });
+  }
+}
+
+class MissingColumns extends Error {
+  constructor(path: string, missing: readonly string[]) {
+    super(`${path} has no ${missing.join(', ')}`);
+  }
+}
+
+await using scratch = await mkdtempDisposable(join(tmpdir(), 'snapshot-'));
+const path = join(scratch.path, 'notes.sqlite');
+
+// The owner: another connection that writes the database through a WAL.
+using owner = new DatabaseSync(path);
+owner.exec(`PRAGMA journal_mode = WAL;
+  CREATE TABLE notes (id INTEGER PRIMARY KEY, title TEXT);
+  INSERT INTO notes (title) VALUES ('first')`);
+
+{
+  using snapshot = new Snapshot(path, Unavailable);
+  snapshot.requireColumns({ notes: ['id', 'title'] }, MissingColumns);
+  owner.exec("INSERT INTO notes (title) VALUES ('second')");
+  console.log(snapshot.all('SELECT title FROM notes'));
+}
+
+using next = new Snapshot(path, Unavailable);
+console.log(next.missingColumns({ notes: ['title', 'body'] }));
+console.log(next.all('SELECT count(*) AS notes FROM notes'));
+
+try {
+  new Snapshot(join(scratch.path, 'missing', 'notes.sqlite'), Unavailable);
+} catch (error) {
+  console.log(error instanceof Unavailable);
+}
+```
+
+Output:
+
+```
+[ [Object: null prototype] { title: 'first' } ]
+[ 'notes.body' ]
+[ [Object: null prototype] { notes: 2 } ]
+true
+```
+
+## The rules
+
+- `new Snapshot(path, unavailable)` opens the database read-only. It runs `BEGIN` and a first read at once, so the snapshot holds the moment when it opens, not the moment of the first query of the caller.
+- The snapshot never opens the file with `immutable`. The owner keeps a persistent WAL, and the newest rows are in it. [ADR 0001](./docs/adr/0001-never-immutable-and-held-only-while-reading.md) tells why.
+- Hold a snapshot only while you read. An open read transaction stops the checkpoint of the owner, and then the WAL of the owner grows. Dispose the snapshot with `using`, or call `[Symbol.dispose]()`.
+- `all(sql, ...parameters)` gives all rows. `iterate(sql, ...parameters)` gives the rows one at a time, for a table that is too large to hold in memory.
+- `requireColumns(columns, schema)` checks the columns that the reader needs, as `{ table: [column, ...] }`. When one is missing, it disposes the snapshot and throws `new schema(path, missing)`.
+- `missingColumns(columns)` gives the missing columns as `table.column`, and keeps the snapshot open. A reader whose queries use different tables checks each query with it.
+- The caller gives the error classes. Thus each error names what the caller needs, for example the access that the user must give.
+- Dispose commits the read transaction and closes the connection. A second dispose does nothing.
+
+## Errors
+
+| Error                          | When                                                                                                                            |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `new unavailable(path, cause)` | SQLite cannot open the file: `SQLITE_CANTOPEN` (14), for a missing file or a file that the system denies, a privacy denial too. |
+| `new schema(path, missing)`    | `requireColumns` finds a missing column. The snapshot is closed.                                                                |
+| The error of SQLite            | All other failures, for example a file that is not a database. The constructor closes the connection before it throws.          |
+
+## The same concepts in other systems
+
+| System                     | What it does                                                                                                                                                                                             |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SQLite WAL readers         | A read transaction sees the database as it was at its first read, also while a writer commits. An open read stops the checkpoint at its end mark. See "Write-Ahead Logging" in the SQLite documentation. |
+| Datasette `immutable` mode | It opens a file with `immutable=1`, for a file that nobody writes. SQLite then skips the locks and the WAL. This package is the opposite case: the owner writes the file.                                |
+| `sqlite3 -readonly`        | It opens a database read-only. Each statement outside a transaction can see a different moment.                                                                                                          |
+
+## Documentation
+
+- [0001 Never immutable, and held only while reading](./docs/adr/0001-never-immutable-and-held-only-while-reading.md)
+- [Code copied into this package](./docs/copied-code.md)
+
+## Development
+
+This package is part of the [zukhruf](../../../README.md) workspace. Run the commands from the workspace root.
+
+```sh
+npm install
+npx nx run sqlite-snapshot:test        # builds, then runs the tests in src/
+npx nx run sqlite-snapshot:typecheck   # formats, lints, then type checks
+npx nx run sqlite-snapshot:build       # compiles src/ to dist/
+```
+
+```
+src/
+  index.ts            the exports
+  snapshot.ts         Snapshot, SnapshotColumns, UnavailableError and SchemaError
+  snapshot.test.ts    the tests, on real SQLite files
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { type SchemaError, Snapshot, type SnapshotColumns, type UnavailableError, } from './snapshot.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Snapshot, } from "./snapshot.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,QAAQ,GAGT,MAAM,eAAe,CAAC"}

package/dist/snapshot.d.ts

@@ -0,0 +1,15 @@
+import { type SQLInputValue, type SQLOutputValue } from 'node:sqlite';
+export type UnavailableError = new (path: string, cause: unknown) => Error;
+export type SchemaError = new (path: string, missing: readonly string[]) => Error;
+export type SnapshotColumns = Readonly<Record<string, readonly string[]>>;
+export declare class Snapshot implements Disposable {
+    #private;
+    readonly path: string;
+    constructor(path: string, unavailable: UnavailableError);
+    requireColumns(columns: SnapshotColumns, schema: SchemaError): void;
+    missingColumns(columns: SnapshotColumns): string[];
+    all(sql: string, ...parameters: SQLInputValue[]): Record<string, SQLOutputValue>[];
+    iterate(sql: string, ...parameters: SQLInputValue[]): IteratorObject<Record<string, SQLOutputValue>, undefined>;
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAIrB,MAAM,MAAM,gBAAgB,GAAG,KAAK,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,KAAK,CAAC;AAI3E,MAAM,MAAM,WAAW,GAAG,KACxB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,MAAM,EAAE,KACvB,KAAK,CAAC;AAGX,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;AAyB1E,qBAAa,QAAS,YAAW,UAAU;;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAGV,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,gBAAgB;IAgBvD,cAAc,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IAUnE,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,EAAE;IAalD,GAAG,CACD,GAAG,EAAE,MAAM,EACX,GAAG,UAAU,EAAE,aAAa,EAAE,GAC7B,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE;IAKnC,OAAO,CACL,GAAG,EAAE,MAAM,EACX,GAAG,UAAU,EAAE,aAAa,EAAE,GAC7B,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,SAAS,CAAC;IAI5D,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAKzB"}

package/dist/snapshot.js

@@ -0,0 +1,75 @@
+import { DatabaseSync, } from 'node:sqlite';
+function open(path, unavailable) {
+    try {
+        return new DatabaseSync(path, { readOnly: true });
+    }
+    catch (cause) {
+        if (cause instanceof Error &&
+            'errcode' in cause &&
+            // SQLite's CANTOPEN (14). A missing or denied file fails the open()
+            // syscall, and SQLite reports that as CANTOPEN, a privacy denial too.
+            // SQLite gives AUTH only for an authorizer, and this private connection
+            // has none. Any other failure is not one that access can fix.
+            cause.errcode === 14)
+            throw new unavailable(path, cause);
+        throw cause;
+    }
+}
+// A SQLite database another process owns and writes while it runs, read
+// read-only and pinned to one moment by a read transaction, so its tables
+// agree. Never opened immutable: the owner keeps a persistent WAL, where the
+// newest rows live. Hold it only while reading: an open read stops the owner
+// checkpointing its WAL.
+export class Snapshot {
+    path;
+    #database;
+    constructor(path, unavailable) {
+        this.path = path;
+        this.#database = open(path, unavailable);
+        try {
+            // The first read pins the snapshot, so it is taken now rather than at
+            // the caller's first query; a file that is no database fails here.
+            this.#database.exec('BEGIN');
+            this.#database.prepare('SELECT 1 FROM sqlite_schema LIMIT 1').get();
+        }
+        catch (cause) {
+            this.#database.close();
+            throw cause;
+        }
+    }
+    // Refuses a layout without these columns, and closes the database: the
+    // check a reader makes while it opens the snapshot.
+    requireColumns(columns, schema) {
+        const missing = this.missingColumns(columns);
+        if (missing.length === 0)
+            return;
+        this[Symbol.dispose]();
+        throw new schema(this.path, missing);
+    }
+    // The columns, as table.column, that this layout lacks. A reader whose
+    // reads use different tables checks each read with it and keeps the
+    // snapshot open for the others.
+    missingColumns(columns) {
+        return Object.entries(columns).flatMap(([table, names]) => {
+            const present = new Set(this.all('SELECT name FROM pragma_table_info(?)', table).map((column) => column.name));
+            return names
+                .filter((name) => !present.has(name))
+                .map((name) => `${table}.${name}`);
+        });
+    }
+    all(sql, ...parameters) {
+        return this.#database.prepare(sql).all(...parameters);
+    }
+    // Rows one at a time, for a table too large to hold whole.
+    iterate(sql, ...parameters) {
+        return this.#database.prepare(sql).iterate(...parameters);
+    }
+    [Symbol.dispose]() {
+        if (!this.#database.isOpen)
+            return;
+        if (this.#database.isTransaction)
+            this.#database.exec('COMMIT');
+        this.#database.close();
+    }
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@zukhruf/sqlite-snapshot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.32",
+  "description": "A read-only snapshot of a SQLite database that another process owns and writes. It pins one moment with a read transaction, so the tables agree, and it never opens the file immutable, so it sees the newest rows in the WAL. It checks the columns that a reader needs, and gives the caller's own errors for a missing file or a missing column.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JanuaryLabs/zukhruf",
+    "directory": "packages/sqlite/snapshot"
+  },
+  "bugs": {
+    "url": "https://github.com/JanuaryLabs/zukhruf/issues"
+  },
+  "homepage": "https://github.com/JanuaryLabs/zukhruf/tree/main/packages/sqlite/snapshot#readme",
+  "keywords": [
+    "sqlite",
+    "node-sqlite",
+    "snapshot",
+    "read-transaction",
+    "wal",
+    "read-only"
+  ],
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@zukhruf/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/spec/**",
+    "!**/*.tsbuildinfo",
+    "!**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}