@zukhruf/sqlite-data-version 0.3.33 → 0.3.34

package/README.md

@@ -62,6 +62,25 @@ no change
 - 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.
 
+## The last write
+
+The data version tells that the owner committed after you read it before. It does not tell when. A new process has no earlier value, so it cannot use the data version to find how old the data is.
+
+`lastWrite(path, unavailable)` gives the time when the owner last wrote the database. Use it when the owner writes only while it runs: a time in the past tells that the data has not changed since then.
+
+```ts
+import { lastWrite } from '@zukhruf/sqlite-data-version';
+
+const written = lastWrite(path, Unavailable);
+console.log(`The owner last wrote at ${written.toISOString()}`);
+```
+
+- The owner writes through the file and its WAL (`-wal`). The last write is the later of their modification times.
+- The shared-memory index (`-shm`) does not count. A read-only reader writes it too, so its time can be later than the last write of the owner.
+- The owner can remove the WAL when it closes. Then the last write is the time of the file.
+- The function reads only the file system. It does not open the database.
+- The macOS privacy controls do not stop it. They stop a process that has no access from reading the file, but not from reading the times of the file.
+
 ## Errors
 
 | Error                          | When                                                                                                                            |
@@ -69,6 +88,8 @@ no change
 | `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.                                                                                                             |
 
+`lastWrite` gives `new unavailable(path, cause)` when the file is missing (`ENOENT`) or the mode of its folder denies this process (`EACCES`). It gives the error of the file system for all other failures.
+
 ## The same concepts in other systems
 
 | System                                 | What it does                                                                                                                                   |
@@ -98,4 +119,6 @@ src/
   index.ts                the exports
   data-version.ts         DataVersion and UnavailableError
   data-version.test.ts    the tests, on real SQLite files
+  last-write.ts           lastWrite
+  last-write.test.ts      the tests, on real SQLite files
 ```

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { DataVersion, type UnavailableError } from './data-version.ts';
+export { lastWrite } from './last-write.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export { DataVersion } from "./data-version.js";
+export { lastWrite } from "./last-write.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAyB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAyB,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/last-write.d.ts

@@ -0,0 +1,3 @@
+import type { UnavailableError } from './data-version.ts';
+export declare function lastWrite(path: string, unavailable: UnavailableError): Date;
+//# sourceMappingURL=last-write.d.ts.map

package/dist/last-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"last-write.d.ts","sourceRoot":"","sources":["../src/last-write.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAW1D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAe3E"}

package/dist/last-write.js

@@ -0,0 +1,24 @@
+import { statSync } from 'node:fs';
+// A missing file, or one in a folder whose mode denies this process. macOS
+// privacy controls do not deny it: they stop a read of the file and a list of
+// its folder with EPERM, but not stat of the file.
+const unreadable = new Set(['ENOENT', 'EACCES']);
+// The owner writes a database through its file and its WAL, so the later of
+// their times is when it last wrote. A reader writes the shared-memory index
+// (-shm) too, so its time does not count. The owner may remove the WAL when
+// it closes; the file stays.
+export function lastWrite(path, unavailable) {
+    try {
+        const file = statSync(path).mtimeMs;
+        const wal = statSync(`${path}-wal`, { throwIfNoEntry: false })?.mtimeMs ?? file;
+        return new Date(Math.max(file, wal));
+    }
+    catch (cause) {
+        if (cause instanceof Error &&
+            'code' in cause &&
+            unreadable.has(String(cause.code)))
+            throw new unavailable(path, cause);
+        throw cause;
+    }
+}
+//# sourceMappingURL=last-write.js.map

package/dist/last-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"last-write.js","sourceRoot":"","sources":["../src/last-write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAInC,2EAA2E;AAC3E,8EAA8E;AAC9E,mDAAmD;AACnD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEjD,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,6BAA6B;AAC7B,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,WAA6B;IACnE,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC;QACpC,MAAM,GAAG,GACP,QAAQ,CAAC,GAAG,IAAI,MAAM,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC;QACtE,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IACE,KAAK,YAAY,KAAK;YACtB,MAAM,IAAI,KAAK;YACf,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAElC,MAAM,IAAI,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACrC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zukhruf/sqlite-data-version",
-  "version": "0.3.33",
+  "version": "0.3.34",
   "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": {