@zukhruf/sqlite-reader 0.0.0-stage → 0.3.54

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,94 @@
-# Temporary Holding Version
+# @zukhruf/sqlite-reader
 
-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. It opens a read-only connection, a reader. The open can fail because the file is missing, or because the system denies access to it. The caller can fix these failures, so the reader must name them. This package opens the reader, and throws `UnavailableError` for these failures.
+
+`@zukhruf/sqlite-snapshot` and `@zukhruf/sqlite-data-version` open their connections with this package. Each of them exports the same `UnavailableError`, so a catch with `instanceof` works with the package that the caller imports.
+
+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-reader
+```
+
+```ts
+import { mkdtempDisposable } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+import { UnavailableError, openReader } from '@zukhruf/sqlite-reader';
+
+await using scratch = await mkdtempDisposable(join(tmpdir(), 'reader-'));
+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 (title TEXT);
+  INSERT INTO notes VALUES ('first')`);
+
+using reader = openReader(path);
+console.log(reader.prepare('SELECT title FROM notes').all());
+
+try {
+  openReader(join(scratch.path, 'missing', 'notes.sqlite'));
+} catch (error) {
+  console.log(error instanceof UnavailableError);
+}
+```
+
+Output:
+
+```
+[ [Object: null prototype] { title: 'first' } ]
+true
+```
+
+## The rules
+
+- `openReader(path)` gives a `DatabaseSync` of `node:sqlite`, opened with `readOnly: true`. The caller owns the connection, and closes it.
+- The reader never writes. A write fails with 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`.
+
+## Errors
+
+| Error               | When                                                                                                                                                                                |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `UnavailableError`  | SQLite cannot open the file: `SQLITE_CANTOPEN` (14), for a missing file or a file that the system denies, a privacy denial too. `path` is the path. `cause` is the error of SQLite. |
+| The error of SQLite | All other failures.                                                                                                                                                                 |
+
+`UnavailableError` takes `(path, cause)`. Another package can throw it for the same failure from a different source. For example, `lastWrite` of `@zukhruf/sqlite-data-version` throws it when the file system cannot give the times of the file.
+
+## The same concepts in other systems
+
+| System              | What it does                                                                                                   |
+| ------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `sqlite3 -readonly` | It opens a database read-only. A missing file fails with "unable to open database file", the text of CANTOPEN. |
+| Python `sqlite3`    | `sqlite3.connect('file:path?mode=ro', uri=True)` opens a database read-only, and raises `OperationalError`.    |
+
+## Documentation
+
+- [0001 One package opens the reader and owns UnavailableError](./docs/adr/0001-one-package-opens-the-reader-and-owns-unavailable-error.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-reader:test        # builds, then runs the tests in src/
+npx nx run sqlite-reader:typecheck   # formats, lints, then type checks
+npx nx run sqlite-reader:build       # compiles src/ to dist/
+```
+
+```
+src/
+  index.ts                the exports
+  open-reader.ts          openReader
+  unavailable-error.ts    UnavailableError
+  open-reader.test.ts     the tests, on real SQLite files
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { openReader } from './open-reader.ts';
+export { UnavailableError } from './unavailable-error.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,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { openReader } from "./open-reader.js";
+export { UnavailableError } from "./unavailable-error.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,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/open-reader.d.ts

@@ -0,0 +1,3 @@
+import { DatabaseSync } from 'node:sqlite';
+export declare function openReader(path: string): DatabaseSync;
+//# sourceMappingURL=open-reader.d.ts.map

package/dist/open-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-reader.d.ts","sourceRoot":"","sources":["../src/open-reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAK3C,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAgBrD"}

package/dist/open-reader.js

@@ -0,0 +1,20 @@
+import { DatabaseSync } from 'node:sqlite';
+import { UnavailableError } from "./unavailable-error.js";
+// A read-only connection to a database that another process owns.
+export function openReader(path) {
+    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 UnavailableError(path, cause);
+        throw cause;
+    }
+}
+//# sourceMappingURL=open-reader.js.map

package/dist/open-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-reader.js","sourceRoot":"","sources":["../src/open-reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,kEAAkE;AAClE,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,CAAC;QACH,OAAO,IAAI,YAAY,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IACE,KAAK,YAAY,KAAK;YACtB,SAAS,IAAI,KAAK;YAClB,oEAAoE;YACpE,sEAAsE;YACtE,wEAAwE;YACxE,8DAA8D;YAC9D,KAAK,CAAC,OAAO,KAAK,EAAE;YAEpB,MAAM,IAAI,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC1C,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/unavailable-error.d.ts

@@ -0,0 +1,6 @@
+/** 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);
+}
+//# 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;CAQzC"}

package/dist/unavailable-error.js

@@ -0,0 +1,10 @@
+/** 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;
+    }
+}
+//# 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,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;CACF"}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@zukhruf/sqlite-reader",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.54",
+  "description": "A read-only connection to a SQLite database that another process owns and writes. It opens the database with node:sqlite, and gives UnavailableError when the file is missing or the system denies access, a failure that the caller can fix.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JanuaryLabs/zukhruf",
+    "directory": "packages/sqlite/reader"
+  },
+  "bugs": {
+    "url": "https://github.com/JanuaryLabs/zukhruf/issues"
+  },
+  "homepage": "https://github.com/JanuaryLabs/zukhruf/tree/main/packages/sqlite/reader#readme",
+  "keywords": [
+    "sqlite",
+    "node-sqlite",
+    "read-only",
+    "reader",
+    "wal"
+  ],
+  "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"
+  },
+  "devDependencies": {
+    "@zukhruf/testing": "^0.3.54"
+  }
+}