@zukhruf/sqlite-open 0.0.0-stage → 0.7.0

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,166 @@
-# Temporary Holding Version
+# @zukhruf/sqlite-open
 
-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.
+Programs keep their data in SQLite databases. One program, the owner, writes a database. Other programs read it, sometimes while the owner runs. Each program opens its connection with `new DatabaseSync` of `node:sqlite`, and then does the same setup again: it selects the journal, sets how long to wait for the lock of another connection, and finds which errors mean "the file is missing, or the system denies access". This package does that setup in one function, `open`.
+
+Some readers cannot write the folder of the database, for example an agent that runs `sqlite3 -readonly` in a sandbox. In a write-ahead log, such a reader cannot open the database after the owner closes it, because SQLite deletes the `-wal` and `-shm` files at the last close, and the reader cannot make them again. Persistent WAL keeps the two files. `node:sqlite` has no API to turn it on, so this package loads a small native library that does it.
+
+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 `node:sqlite`, and one native library for persistent WAL.
+
+```sh
+npm install @zukhruf/sqlite-open
+```
+
+```ts
+import { existsSync } from 'node:fs';
+import { mkdtempDisposable } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  PersistentWriteAheadLog,
+  UnavailableError,
+  open,
+} from '@zukhruf/sqlite-open';
+
+await using scratch = await mkdtempDisposable(join(tmpdir(), 'open-'));
+const path = join(scratch.path, 'notes.sqlite');
+
+{
+  // The owner writes the database, and then closes it.
+  using owner = open(path, { journal: new PersistentWriteAheadLog() });
+  owner.exec(`CREATE TABLE notes (title TEXT);
+    INSERT INTO notes VALUES ('first')`);
+}
+
+// The -shm file stays, so a reader that cannot write the folder can open the database.
+console.log(existsSync(`${path}-shm`));
+
+using reader = open(path, { readOnly: true });
+console.log(reader.prepare('SELECT title FROM notes').all());
+console.log(reader.prepare('PRAGMA journal_mode').get());
+
+try {
+  open(join(scratch.path, 'missing', 'notes.sqlite'), { readOnly: true });
+} catch (error) {
+  console.log(error instanceof UnavailableError);
+}
+```
+
+Output:
+
+```
+true
+[ [Object: null prototype] { title: 'first' } ]
+[Object: null prototype] { journal_mode: 'wal' }
+true
+```
+
+## The rules
+
+- `open(path, options)` takes the options of `new DatabaseSync` of `node:sqlite`, except `open`, and gives a `DatabaseSync`. The caller owns the connection, and closes it.
+- `readOnly: true` opens a reader. The package does no other step. A reader never writes to the database, and never changes its journal.
+- Without `readOnly`, `open` opens the connection of an owner, and the `journal` option sets the journal. The default is `WriteAheadLog`. A reader cannot have a `journal` option. TypeScript refuses it.
+- A database in memory (`:memory:`, `''`, or a `file::memory:` URI) has no file, so it gets no journal.
+- The busy timeout is 5000 milliseconds, unless the caller gives `timeout`. With `timeout: 0`, a lock of another connection fails at once with `SQLITE_BUSY` (5).
+- The owner opens with extension loading on, so that a journal can load the native library. After the journal step, extension loading is as the caller asked with `allowExtension`. The default is off.
+- When the open or the journal step fails, `open` closes the connection and throws. An unavailable file throws `UnavailableError`. All other failures throw the error of SQLite.
+- The package throws its own `UnavailableError`. A host that needs its own error translates the error of the package at its boundary, and keeps the error of the package as `cause`.
+
+`open` replaces `new DatabaseSync` at the call site, with three differences:
+
+- It has no `open` option. `open` always opens the connection, because the journal step needs an open file.
+- The busy timeout is 5000 milliseconds when the caller gives no `timeout`. `node:sqlite` uses 0.
+- An owner opens with extension loading on for the journal step. After that step, extension loading is as the caller asked.
+
+## Journals
+
+Each journal is a strategy object: the caller gives an instance, for example `open(path, { journal: new RollbackJournal() })`. A new journal is a class that implements `Journal`, with one method: `apply(database)`.
+
+| Journal                   | What it does                                                                                                                         | Use it for                                                                                                    |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `WriteAheadLog` (default) | `PRAGMA journal_mode = WAL` and `PRAGMA journal_size_limit = 67108864` (64 MiB). SQLite deletes `-wal` and `-shm` at the last close. | An owner whose readers can write the folder.                                                                  |
+| `PersistentWriteAheadLog` | The same steps, after the native library turns on persistent WAL. `-wal` and `-shm` stay after the last close.                       | An owner whose readers cannot write the folder, for example agents that run `sqlite3 -readonly` in a sandbox. |
+| `RollbackJournal`         | `PRAGMA journal_mode = DELETE`. The first access rolls back a hot journal.                                                           | A file that the owner builds and then renames or deletes. A copy that must lose a hot journal.                |
+| `UnchangedJournal`        | Nothing.                                                                                                                             | An owner that sets its own journal, for example a lock file whose `PRAGMA` must wait for the lock.            |
+
+The size limit keeps a write-ahead log small after a large commit. Without it, the `-wal` file of a 20 MB commit stays 20 MB.
+
+`WriteAheadLog` and `PersistentWriteAheadLog` take an optional page size, for example `new WriteAheadLog({ pageSize: 32768 })`. SQLite sets the page size of a file only before its first write, and never in a write-ahead log. The write-ahead log step is that first write, so the journal sets the page size just before it. An existing file keeps its own page size.
+
+## Errors
+
+| Error               | When                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `UnavailableError`  | The file is missing, or the system denies access to it: `SQLITE_CANTOPEN` (14) from the open, a privacy denial too, or `SQLITE_READONLY_DIRECTORY` (1544) from the journal step, when the folder denies the write of the journal. `path` is the path. `cause` is the error of SQLite. `UnavailableError.from(path, error)` also accepts `ENOENT`, `ENOTDIR`, `EACCES` and `EPERM` from the file system. |
+| `Error`             | `PersistentWriteAheadLog` runs on a platform that has no native library. The message names the platform, and the platforms that have one.                                                                                                                                                                                                                                                               |
+| `Error`             | SQLite did not change the journal to a write-ahead log. The message gives the journal that SQLite kept.                                                                                                                                                                                                                                                                                                 |
+| The error of SQLite | All other failures, for example a file that is not a database.                                                                                                                                                                                                                                                                                                                                          |
+
+## Platforms
+
+The native library is in `lib/<platform>-<arch>/` of the package, for `darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64` (glibc and musl), `win32-x64` and `win32-arm64`. Only `PersistentWriteAheadLog` loads it, at its first open.
+
+A bundler that bundles this package does not copy the `lib` folder. A bundle that uses `PersistentWriteAheadLog` keeps `@zukhruf/sqlite-open` external, and ships it in `node_modules`. An Electron app also unpacks `lib` from its `asar` archive.
+
+## Why not a package from npm
+
+| Candidate                | Why it does not do the job                                                                     |
+| ------------------------ | ---------------------------------------------------------------------------------------------- |
+| `node:sqlite`            | It has no file control, so it cannot turn on persistent WAL. Its busy timeout is 0 by default. |
+| `better-sqlite3`         | It has no file control. Issues #1029 and #1101 ask for persistent WAL. They are open.          |
+| `@photostructure/sqlite` | A copy of the `node:sqlite` API. It has no file control.                                       |
+| `libsql`                 | The `better-sqlite3` API. It has no file control.                                              |
+| Bun's `bun:sqlite`       | `db.fileControl(SQLITE_FCNTL_PERSIST_WAL, 1)` turns it on, but only in Bun.                    |
+
+## The same concepts in other systems
+
+| System                | What it does                                                                                                                            |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Lix (a fork of Nix)   | `LocalStore::openDB` turns on persistent WAL after it sets WAL, so users without write permission can read the store (NixOS/nix#10300). |
+| Apple's system SQLite | It keeps persistent WAL by default. Its `sqlite3` leaves `-wal` and `-shm` after it closes.                                             |
+| `better-sqlite3`      | Its busy timeout is 5000 milliseconds by default.                                                                                       |
+| Python `sqlite3`      | `sqlite3.connect(path, timeout=5.0)`: its busy timeout is 5 seconds by default.                                                         |
+| Rails 8               | A SQLite database gets a write-ahead log and `journal_size_limit = 67108864` by default.                                                |
+| `sqlite3 -readonly`   | It opens a reader. A missing file fails with "unable to open database file", the text of CANTOPEN.                                      |
+
+## Documentation
+
+- [0001 One package opens the reader and owns UnavailableError](./docs/adr/0001-one-package-opens-the-reader-and-owns-unavailable-error.md)
+- [0002 One open for readers and owners](./docs/adr/0002-one-open-for-readers-and-owners.md)
+- [0003 Persistent WAL through a native library](./docs/adr/0003-persistent-wal-through-a-native-library.md)
+- [0004 The journal is a strategy](./docs/adr/0004-the-journal-is-a-strategy.md)
+- [0005 One map of failures and a busy timeout of 5 seconds](./docs/adr/0005-one-map-of-failures-and-a-busy-timeout-of-5-seconds.md)
+- [0006 Zig builds every native library in one Linux job](./docs/adr/0006-zig-builds-every-native-library-in-one-linux-job.md)
+
+## Development
+
+This package is part of the [zukhruf](../../../README.md) workspace. Run the commands from the workspace root. The `native` target needs `zig` 0.16.
+
+```sh
+npm install
+npx nx run sqlite-open:test        # builds the native libraries and dist, then runs the tests in src/
+npx nx run sqlite-open:typecheck   # formats, lints, then type checks
+npx nx run sqlite-open:build       # builds lib/ with zig, then compiles src/ to dist/
+```
+
+```
+src/
+  index.ts                          the exports
+  open.ts                           open
+  journal.ts                        the Journal interface
+  write-ahead-log.ts                WriteAheadLog
+  persistent-write-ahead-log.ts     PersistentWriteAheadLog
+  rollback-journal.ts               RollbackJournal
+  unchanged-journal.ts              UnchangedJournal
+  unavailable-error.ts              UnavailableError
+  open.test.ts                      the tests, on real SQLite files and processes
+  native/
+    persist_wal.c                   the native library
+    sqlite3.h, sqlite3ext.h         the SQLite 3.54.0 headers
+    build.ts                        builds lib/ for each platform with zig
+lib/                                built by the native target, not in git
+```

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { Journal } from './journal.ts';
+export { open, type OwnerOptions, type ReaderOptions } from './open.ts';
+export { PersistentWriteAheadLog } from './persistent-write-ahead-log.ts';
+export { RollbackJournal } from './rollback-journal.ts';
+export { UnavailableError } from './unavailable-error.ts';
+export { UnchangedJournal } from './unchanged-journal.ts';
+export { type PageSize, WriteAheadLog } from './write-ahead-log.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,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,KAAK,QAAQ,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { open } from "./open.js";
+export { PersistentWriteAheadLog } from "./persistent-write-ahead-log.js";
+export { RollbackJournal } from "./rollback-journal.js";
+export { UnavailableError } from "./unavailable-error.js";
+export { UnchangedJournal } from "./unchanged-journal.js";
+export { WriteAheadLog } from "./write-ahead-log.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":"AACA,OAAO,EAAE,IAAI,EAAyC,MAAM,WAAW,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAiB,aAAa,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/journal.d.ts

@@ -0,0 +1,10 @@
+import type { DatabaseSync } from 'node:sqlite';
+/**
+ * How SQLite keeps a commit safe. `open` gives the connection of an owner to
+ * its journal, which sets it up (ADR 0004). A new journal is a class that
+ * implements this interface.
+ */
+export interface Journal {
+    apply(database: DatabaseSync): void;
+}
+//# sourceMappingURL=journal.d.ts.map

package/dist/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;CACrC"}

package/dist/journal.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=journal.js.map

package/dist/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":""}

package/dist/open.d.ts

@@ -0,0 +1,18 @@
+import { DatabaseSync, type DatabaseSyncOptions } from 'node:sqlite';
+import type { Journal } from './journal.ts';
+type Path = ConstructorParameters<typeof DatabaseSync>[0];
+type Settings = Omit<DatabaseSyncOptions, 'open' | 'readOnly'>;
+/** A reader: a read-only connection that never changes the database. */
+export type ReaderOptions = Settings & {
+    readonly readOnly: true;
+    readonly journal?: never;
+};
+/** The connection of the owner, which writes the database and sets its journal. */
+export type OwnerOptions = Settings & {
+    readonly readOnly?: false;
+    readonly journal?: Journal;
+};
+/** Opens a connection: a reader with `readOnly: true`, else an owner (ADR 0002). */
+export declare function open(path: Path, options?: ReaderOptions | OwnerOptions): DatabaseSync;
+export {};
+//# sourceMappingURL=open.d.ts.map

package/dist/open.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open.d.ts","sourceRoot":"","sources":["../src/open.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAErE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAI5C,KAAK,IAAI,GAAG,qBAAqB,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1D,KAAK,QAAQ,GAAG,IAAI,CAAC,mBAAmB,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC;AAE/D,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG;IACrC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC;CAC1B,CAAC;AAEF,mFAAmF;AACnF,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,oFAAoF;AACpF,wBAAgB,IAAI,CAClB,IAAI,EAAE,IAAI,EACV,OAAO,GAAE,aAAa,GAAG,YAAiB,GACzC,YAAY,CAgBd"}

package/dist/open.js

@@ -0,0 +1,36 @@
+import { DatabaseSync } from 'node:sqlite';
+import { UnavailableError } from "./unavailable-error.js";
+import { WriteAheadLog } from "./write-ahead-log.js";
+/** Opens a connection: a reader with `readOnly: true`, else an owner (ADR 0002). */
+export function open(path, options = {}) {
+    if (options.readOnly)
+        return connect(path, options);
+    const { journal = new WriteAheadLog(), ...settings } = options;
+    // The owner opens with extension loading on, so that a journal can load the
+    // native library; the step after the journal sets it as the caller asked.
+    const database = connect(path, { ...settings, allowExtension: true });
+    try {
+        // A database in memory (':memory:', '', a file::memory: URI) has no file,
+        // so it has no journal to set.
+        if (database.location() !== null)
+            journal.apply(database);
+        database.enableLoadExtension(settings.allowExtension ?? false);
+        return database;
+    }
+    catch (error) {
+        database.close();
+        throw UnavailableError.from(String(path), error) ?? error;
+    }
+}
+// The busy timeout when the caller gives none, in milliseconds, as
+// better-sqlite3, Python's sqlite3 and Rails have it (ADR 0005).
+const busyTimeout = 5000;
+function connect(path, options) {
+    try {
+        return new DatabaseSync(path, { timeout: busyTimeout, ...options });
+    }
+    catch (error) {
+        throw UnavailableError.from(String(path), error) ?? error;
+    }
+}
+//# sourceMappingURL=open.js.map

package/dist/open.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open.js","sourceRoot":"","sources":["../src/open.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA4B,MAAM,aAAa,CAAC;AAGrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAiBrD,oFAAoF;AACpF,MAAM,UAAU,IAAI,CAClB,IAAU,EACV,UAAwC,EAAE;IAE1C,IAAI,OAAO,CAAC,QAAQ;QAAE,OAAO,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACpD,MAAM,EAAE,OAAO,GAAG,IAAI,aAAa,EAAE,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC/D,4EAA4E;IAC5E,0EAA0E;IAC1E,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,EAAE,EAAE,GAAG,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC;IACtE,IAAI,CAAC;QACH,0EAA0E;QAC1E,+BAA+B;QAC/B,IAAI,QAAQ,CAAC,QAAQ,EAAE,KAAK,IAAI;YAAE,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC1D,QAAQ,CAAC,mBAAmB,CAAC,QAAQ,CAAC,cAAc,IAAI,KAAK,CAAC,CAAC;QAC/D,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjB,MAAM,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC;IAC5D,CAAC;AACH,CAAC;AAED,mEAAmE;AACnE,iEAAiE;AACjE,MAAM,WAAW,GAAG,IAAI,CAAC;AAEzB,SAAS,OAAO,CAAC,IAAU,EAAE,OAA4B;IACvD,IAAI,CAAC;QACH,OAAO,IAAI,YAAY,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACtE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC;IAC5D,CAAC;AACH,CAAC"}

package/dist/persistent-write-ahead-log.d.ts

@@ -0,0 +1,15 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { Journal } from './journal.ts';
+import { type PageSize } from './write-ahead-log.ts';
+/**
+ * A write-ahead log whose -wal and -shm files stay after the last connection
+ * closes, for readers that cannot write the folder (ADR 0003).
+ */
+export declare class PersistentWriteAheadLog implements Journal {
+    #private;
+    constructor(options?: {
+        readonly pageSize?: PageSize;
+    });
+    apply(database: DatabaseSync): void;
+}
+//# sourceMappingURL=persistent-write-ahead-log.d.ts.map

package/dist/persistent-write-ahead-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistent-write-ahead-log.d.ts","sourceRoot":"","sources":["../src/persistent-write-ahead-log.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,KAAK,QAAQ,EAAiB,MAAM,sBAAsB,CAAC;AAWpE;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,OAAO;;gBAGzC,OAAO,GAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;KAAO;IAI1D,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;CAsBpC"}

package/dist/persistent-write-ahead-log.js

@@ -0,0 +1,37 @@
+import { readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { WriteAheadLog } from "./write-ahead-log.js";
+// The native libraries are at the package root, so this file finds them from
+// src/ in the tests and from dist/ in the package (ADR 0006).
+const lib = new URL('../lib/', import.meta.url);
+const suffixes = {
+    darwin: 'dylib',
+    linux: 'so',
+    win32: 'dll',
+};
+/**
+ * A write-ahead log whose -wal and -shm files stay after the last connection
+ * closes, for readers that cannot write the folder (ADR 0003).
+ */
+export class PersistentWriteAheadLog {
+    #log;
+    constructor(options = {}) {
+        this.#log = new WriteAheadLog(options);
+    }
+    apply(database) {
+        const platform = `${process.platform}-${process.arch}`;
+        const library = new URL(`${platform}/persist_wal.${suffixes[process.platform]}`, lib);
+        try {
+            database.loadExtension(fileURLToPath(library));
+        }
+        catch (cause) {
+            if (!(cause instanceof Error) ||
+                !('code' in cause) ||
+                cause.code !== 'ERR_LOAD_SQLITE_EXTENSION')
+                throw cause;
+            throw new Error(`@zukhruf/sqlite-open has no native library for ${platform}. It has one for ${readdirSync(lib).join(', ')}.`, { cause });
+        }
+        this.#log.apply(database);
+    }
+}
+//# sourceMappingURL=persistent-write-ahead-log.js.map

package/dist/persistent-write-ahead-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistent-write-ahead-log.js","sourceRoot":"","sources":["../src/persistent-write-ahead-log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,OAAO,EAAiB,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAEpE,6EAA6E;AAC7E,8DAA8D;AAC9D,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChD,MAAM,QAAQ,GAA6C;IACzD,MAAM,EAAE,OAAO;IACf,KAAK,EAAE,IAAI;IACX,KAAK,EAAE,KAAK;CACb,CAAC;AAEF;;;GAGG;AACH,MAAM,OAAO,uBAAuB;IACzB,IAAI,CAAgB;IAE7B,YAAY,UAA4C,EAAE;QACxD,IAAI,CAAC,IAAI,GAAG,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,QAAsB;QAC1B,MAAM,QAAQ,GAAG,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACvD,MAAM,OAAO,GAAG,IAAI,GAAG,CACrB,GAAG,QAAQ,gBAAgB,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EACvD,GAAG,CACJ,CAAC;QACF,IAAI,CAAC;YACH,QAAQ,CAAC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;QACjD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IACE,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;gBACzB,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC;gBAClB,KAAK,CAAC,IAAI,KAAK,2BAA2B;gBAE1C,MAAM,KAAK,CAAC;YACd,MAAM,IAAI,KAAK,CACb,kDAAkD,QAAQ,oBAAoB,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAC5G,EAAE,KAAK,EAAE,CACV,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;CACF"}

package/dist/rollback-journal.d.ts

@@ -0,0 +1,12 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { Journal } from './journal.ts';
+/**
+ * The rollback journal: SQLite copies each page to the -journal file before a
+ * commit changes it. Its first access rolls back a hot journal. For a copy
+ * that must lose a hot journal, and for a file that its owner builds and then
+ * renames or deletes, which must leave no -wal file behind (ADR 0004).
+ */
+export declare class RollbackJournal implements Journal {
+    apply(database: DatabaseSync): void;
+}
+//# sourceMappingURL=rollback-journal.d.ts.map

package/dist/rollback-journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback-journal.d.ts","sourceRoot":"","sources":["../src/rollback-journal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,OAAO;IAC7C,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;CAGpC"}

package/dist/rollback-journal.js

@@ -0,0 +1,12 @@
+/**
+ * The rollback journal: SQLite copies each page to the -journal file before a
+ * commit changes it. Its first access rolls back a hot journal. For a copy
+ * that must lose a hot journal, and for a file that its owner builds and then
+ * renames or deletes, which must leave no -wal file behind (ADR 0004).
+ */
+export class RollbackJournal {
+    apply(database) {
+        database.exec('PRAGMA journal_mode = DELETE');
+    }
+}
+//# sourceMappingURL=rollback-journal.js.map

package/dist/rollback-journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback-journal.js","sourceRoot":"","sources":["../src/rollback-journal.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,OAAO,eAAe;IAC1B,KAAK,CAAC,QAAsB;QAC1B,QAAQ,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAChD,CAAC;CACF"}

package/dist/unavailable-error.d.ts

@@ -0,0 +1,11 @@
+/** The database file is missing, or this process has no access to it. */
+export declare class UnavailableError extends Error {
+    readonly path: string;
+    constructor(path: string, cause: unknown);
+    /**
+     * The UnavailableError for an error of SQLite or of the file system that
+     * means the file is missing or denied (ADR 0005), else undefined.
+     */
+    static from(path: string, error: unknown): UnavailableError | undefined;
+}
+//# sourceMappingURL=unavailable-error.d.ts.map

package/dist/unavailable-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unavailable-error.d.ts","sourceRoot":"","sources":["../src/unavailable-error.ts"],"names":[],"mappings":"AAaA,yEAAyE;AACzE,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;IASxC;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS;CAiBxE"}

package/dist/unavailable-error.js

@@ -0,0 +1,39 @@
+// The file system codes for a file that is missing, or that the system denies.
+const unavailableCodes = new Set(['ENOENT', 'ENOTDIR', 'EACCES', 'EPERM']);
+// SQLite's CANTOPEN (14). A missing or denied file fails the open() syscall,
+// and SQLite reports that as CANTOPEN, a privacy denial of macOS too (probed:
+// a missing file or folder, chmod 000, a symlink loop and a TCC denial all
+// give exactly 14).
+const SQLITE_CANTOPEN = 14;
+// SQLite's READONLY_DIRECTORY (1544): the folder denies the write that makes
+// the journal, for example for an owner in a folder it cannot write. A plain
+// READONLY (8), a reader that tries to write, is not unavailable.
+const SQLITE_READONLY_DIRECTORY = 1544;
+/** The database file is missing, or this process has no access to it. */
+export class UnavailableError extends Error {
+    path;
+    constructor(path, cause) {
+        super(`The database at ${JSON.stringify(path)} cannot be opened: the file is missing, or this process has no access to it. Give the process access, or check the path.`, { cause });
+        this.name = 'UnavailableError';
+        this.path = path;
+    }
+    /**
+     * The UnavailableError for an error of SQLite or of the file system that
+     * means the file is missing or denied (ADR 0005), else undefined.
+     */
+    static from(path, error) {
+        if (!(error instanceof Error))
+            return undefined;
+        if ('errcode' in error &&
+            typeof error.errcode === 'number' &&
+            (error.errcode === SQLITE_CANTOPEN ||
+                error.errcode === SQLITE_READONLY_DIRECTORY))
+            return new UnavailableError(path, error);
+        if ('code' in error &&
+            typeof error.code === 'string' &&
+            unavailableCodes.has(error.code))
+            return new UnavailableError(path, error);
+        return undefined;
+    }
+}
+//# sourceMappingURL=unavailable-error.js.map

package/dist/unavailable-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unavailable-error.js","sourceRoot":"","sources":["../src/unavailable-error.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AAE3E,6EAA6E;AAC7E,8EAA8E;AAC9E,2EAA2E;AAC3E,oBAAoB;AACpB,MAAM,eAAe,GAAG,EAAE,CAAC;AAC3B,6EAA6E;AAC7E,6EAA6E;AAC7E,kEAAkE;AAClE,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAEvC,yEAAyE;AACzE,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,KAAc;QACtC,KAAK,CACH,mBAAmB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,0HAA0H,EACjK,EAAE,KAAK,EAAE,CACV,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,IAAY,EAAE,KAAc;QACtC,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAChD,IACE,SAAS,IAAI,KAAK;YAClB,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;YACjC,CAAC,KAAK,CAAC,OAAO,KAAK,eAAe;gBAChC,KAAK,CAAC,OAAO,KAAK,yBAAyB,CAAC;YAE9C,OAAO,IAAI,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC3C,IACE,MAAM,IAAI,KAAK;YACf,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;YAC9B,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAEhC,OAAO,IAAI,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC3C,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/unchanged-journal.d.ts

@@ -0,0 +1,10 @@
+import type { Journal } from './journal.ts';
+/**
+ * A journal that changes nothing, for an owner that sets its own journal: a
+ * lock file whose PRAGMA must wait for the lock, so it cannot run at the open
+ * (ADR 0004).
+ */
+export declare class UnchangedJournal implements Journal {
+    apply(): void;
+}
+//# sourceMappingURL=unchanged-journal.d.ts.map

package/dist/unchanged-journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unchanged-journal.d.ts","sourceRoot":"","sources":["../src/unchanged-journal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,OAAO;IAC9C,KAAK,IAAI,IAAI;CACd"}

package/dist/unchanged-journal.js

@@ -0,0 +1,9 @@
+/**
+ * A journal that changes nothing, for an owner that sets its own journal: a
+ * lock file whose PRAGMA must wait for the lock, so it cannot run at the open
+ * (ADR 0004).
+ */
+export class UnchangedJournal {
+    apply() { }
+}
+//# sourceMappingURL=unchanged-journal.js.map

package/dist/unchanged-journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unchanged-journal.js","sourceRoot":"","sources":["../src/unchanged-journal.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,OAAO,gBAAgB;IAC3B,KAAK,KAAU,CAAC;CACjB"}

package/dist/write-ahead-log.d.ts

@@ -0,0 +1,13 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { Journal } from './journal.ts';
+/** A page size that SQLite accepts: a power of two from 512 to 65536. */
+export type PageSize = 512 | 1024 | 2048 | 4096 | 8192 | 16384 | 32768 | 65536;
+/** The default journal of an owner: readers and the owner do not wait for each other. */
+export declare class WriteAheadLog implements Journal {
+    #private;
+    constructor(options?: {
+        readonly pageSize?: PageSize;
+    });
+    apply(database: DatabaseSync): void;
+}
+//# sourceMappingURL=write-ahead-log.d.ts.map

package/dist/write-ahead-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-ahead-log.d.ts","sourceRoot":"","sources":["../src/write-ahead-log.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAK5C,yEAAyE;AACzE,MAAM,MAAM,QAAQ,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAE/E,yFAAyF;AACzF,qBAAa,aAAc,YAAW,OAAO;;gBAG/B,OAAO,GAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;KAAO;IAI1D,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;CAiBpC"}

package/dist/write-ahead-log.js

@@ -0,0 +1,25 @@
+// Keeps the -wal file small after a large commit, as Rails 8 does: 64 MiB.
+const sizeLimit = 64 * 1024 * 1024;
+/** The default journal of an owner: readers and the owner do not wait for each other. */
+export class WriteAheadLog {
+    #pageSize;
+    constructor(options = {}) {
+        this.#pageSize = options.pageSize;
+    }
+    apply(database) {
+        // SQLite takes the page size of a file only before its first write, and
+        // never in a write-ahead log. The WAL step writes the header of a new
+        // file, so the page size comes first. An existing file keeps its own.
+        if (this.#pageSize !== undefined)
+            database.exec(`PRAGMA page_size = ${this.#pageSize}`);
+        // The statement sets its own row shape: the caller's returnArrays and
+        // readBigInts apply to the connection, and must not change this read.
+        const statement = database.prepare('PRAGMA journal_mode = WAL');
+        statement.setReturnArrays(false);
+        const journal = statement.get()?.journal_mode;
+        if (journal !== 'wal')
+            throw new Error(`SQLite kept the journal ${JSON.stringify(journal)} of ${JSON.stringify(database.location())}, not a write-ahead log.`);
+        database.exec(`PRAGMA journal_size_limit = ${sizeLimit}`);
+    }
+}
+//# sourceMappingURL=write-ahead-log.js.map

package/dist/write-ahead-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-ahead-log.js","sourceRoot":"","sources":["../src/write-ahead-log.ts"],"names":[],"mappings":"AAIA,2EAA2E;AAC3E,MAAM,SAAS,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAKnC,yFAAyF;AACzF,MAAM,OAAO,aAAa;IACf,SAAS,CAAuB;IAEzC,YAAY,UAA4C,EAAE;QACxD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,QAAsB;QAC1B,wEAAwE;QACxE,sEAAsE;QACtE,sEAAsE;QACtE,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;YAC9B,QAAQ,CAAC,IAAI,CAAC,sBAAsB,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QACxD,sEAAsE;QACtE,sEAAsE;QACtE,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,2BAA2B,CAAC,CAAC;QAChE,SAAS,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QACjC,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,EAAE,EAAE,YAAY,CAAC;QAC9C,IAAI,OAAO,KAAK,KAAK;YACnB,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,0BAA0B,CACvH,CAAC;QACJ,QAAQ,CAAC,IAAI,CAAC,+BAA+B,SAAS,EAAE,CAAC,CAAC;IAC5D,CAAC;CACF"}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@zukhruf/sqlite-open",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.0",
+  "description": "One open for every node:sqlite connection: a reader, or an owner whose journal is a strategy (WAL by default, persistent WAL for readers that cannot write the folder), a 5 s busy timeout, and UnavailableError.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JanuaryLabs/zukhruf",
+    "directory": "packages/sqlite/open"
+  },
+  "bugs": {
+    "url": "https://github.com/JanuaryLabs/zukhruf/issues"
+  },
+  "homepage": "https://github.com/JanuaryLabs/zukhruf/tree/main/packages/sqlite/open#readme",
+  "keywords": [
+    "sqlite",
+    "node-sqlite",
+    "wal",
+    "persistent-wal",
+    "read-only",
+    "busy-timeout"
+  ],
+  "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",
+    "lib",
+    "!dist/spec/**",
+    "!**/*.tsbuildinfo",
+    "!**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@zukhruf/testing": "^0.7.0"
+  }
+}