@zukhruf/sqlite-data-version 0.0.0-stage → 0.3.31

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,101 @@
-# Temporary Holding Version
+# @zukhruf/sqlite-data-version
 
-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 wants to know when the data changes, so that it reads again. A file-change event does not tell it: the owner keeps the file open and commits through a WAL, and the event comes only when the file closes. SQLite gives a number for this: `PRAGMA data_version`. It changes on each commit by another connection. This package keeps its own read-only connection to the database, and gives that number. Poll it, and read again when it changes.
+
+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-data-version
+```
+
+```ts
+import { mkdtempDisposable } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+import { DataVersion } from '@zukhruf/sqlite-data-version';
+
+class Unavailable extends Error {
+  constructor(path: string, cause: unknown) {
+    super(`Cannot read ${path}`, { cause });
+  }
+}
+
+await using scratch = await mkdtempDisposable(join(tmpdir(), 'data-version-'));
+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)`);
+
+using version = new DataVersion(path, Unavailable);
+let seen = version.current;
+for (const title of ['first', 'second']) {
+  owner.prepare('INSERT INTO notes (title) VALUES (?)').run(title);
+  const now = version.current;
+  console.log(now !== seen ? `changed after ${title}` : 'no change');
+  seen = now;
+}
+console.log(version.current === seen ? 'no change' : 'changed');
+```
+
+Output:
+
+```
+changed after first
+changed after second
+no change
+```
+
+## The rules
+
+- `new DataVersion(path, unavailable)` opens its own read-only connection to the database. It does not share a connection with a reader. [ADR 0001](./docs/adr/0001-poll-data-version.md) tells why.
+- `current` gives the data version now. Compare it with the value that you read before. A different value tells that another connection committed. The same value tells that no other connection committed.
+- The number tells only that a change occurred. It does not count the commits, and it does not tell what changed.
+- A commit by the same connection does not change the number. The `DataVersion` connection never writes, so each commit that it sees comes from another connection.
+- Dispose closes the connection. Use `using`, or call `[Symbol.dispose]()`.
+- The caller gives the error class. Thus the error names what the caller needs, for example the access that the user must give.
+
+## 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. |
+| The error of SQLite            | All other failures.                                                                                                             |
+
+## The same concepts in other systems
+
+| System                                 | What it does                                                                                                                                   |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| SQLite `PRAGMA data_version`           | It gives a number that changes when another connection commits. The SQLite documentation tells to use it to find out when to read again.       |
+| File-change events (FSEvents, inotify) | They tell that a file changed. A process that keeps the file open and writes a WAL can commit many times before a write that an event reports. |
+| Datasette `immutable` mode             | It opens a file that nobody writes, so the data never changes. This package is the opposite case: the owner writes the file.                   |
+
+## Documentation
+
+- [0001 Poll data_version](./docs/adr/0001-poll-data-version.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-data-version:test        # builds, then runs the tests in src/
+npx nx run sqlite-data-version:typecheck   # formats, lints, then type checks
+npx nx run sqlite-data-version:build       # compiles src/ to dist/
+```
+
+```
+src/
+  index.ts                the exports
+  data-version.ts         DataVersion and UnavailableError
+  data-version.test.ts    the tests, on real SQLite files
+```

package/dist/data-version.d.ts

@@ -0,0 +1,8 @@
+export type UnavailableError = new (path: string, cause: unknown) => Error;
+export declare class DataVersion implements Disposable {
+    #private;
+    constructor(path: string, unavailable: UnavailableError);
+    get current(): number;
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=data-version.d.ts.map

package/dist/data-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-version.d.ts","sourceRoot":"","sources":["../src/data-version.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,gBAAgB,GAAG,KAAK,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,KAAK,CAAC;AAuB3E,qBAAa,WAAY,YAAW,UAAU;;gBAIhC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,gBAAgB;IAKvD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB"}

package/dist/data-version.js

@@ -0,0 +1,35 @@
+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;
+    }
+}
+// The owner commits through a WAL it keeps open, and file-change events
+// report a write only when the file closes. SQLite's data_version changes on
+// every commit by another connection, so polling current sees each one.
+export class DataVersion {
+    #database;
+    #version;
+    constructor(path, unavailable) {
+        this.#database = open(path, unavailable);
+        this.#version = this.#database.prepare('PRAGMA data_version');
+    }
+    get current() {
+        return Number(this.#version.get()?.data_version);
+    }
+    [Symbol.dispose]() {
+        this.#database.close();
+    }
+}
+//# sourceMappingURL=data-version.js.map

package/dist/data-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-version.js","sourceRoot":"","sources":["../src/data-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAsB,MAAM,aAAa,CAAC;AAM/D,SAAS,IAAI,CAAC,IAAY,EAAE,WAA6B;IACvD,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,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACrC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,wEAAwE;AACxE,6EAA6E;AAC7E,wEAAwE;AACxE,MAAM,OAAO,WAAW;IACb,SAAS,CAAe;IACxB,QAAQ,CAAgB;IAEjC,YAAY,IAAY,EAAE,WAA6B;QACrD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QACzC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,OAAO;QACT,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,YAAY,CAAC,CAAC;IACnD,CAAC;IAED,CAAC,MAAM,CAAC,OAAO,CAAC;QACd,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { DataVersion, type UnavailableError } from './data-version.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,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { DataVersion } from "./data-version.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,WAAW,EAAyB,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@zukhruf/sqlite-data-version",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.31",
+  "description": "The data version of a SQLite database that another process owns and writes. It polls PRAGMA data_version on its own read-only connection, which changes on each commit by another connection, also while the owner keeps the file open.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JanuaryLabs/zukhruf",
+    "directory": "packages/sqlite/data-version"
+  },
+  "bugs": {
+    "url": "https://github.com/JanuaryLabs/zukhruf/issues"
+  },
+  "homepage": "https://github.com/JanuaryLabs/zukhruf/tree/main/packages/sqlite/data-version#readme",
+  "keywords": [
+    "sqlite",
+    "node-sqlite",
+    "data-version",
+    "pragma",
+    "wal",
+    "change-detection"
+  ],
+  "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"
+  }
+}