@zukhruf/sqlite-data-version 0.6.13 → 0.6.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +30 -6
- package/dist/data-version.d.ts +6 -1
- package/dist/data-version.d.ts.map +1 -1
- package/dist/data-version.js +10 -2
- package/dist/data-version.js.map +1 -1
- package/dist/stamped-database.d.ts +7 -0
- package/dist/stamped-database.d.ts.map +1 -0
- package/dist/stamped-database.js +42 -0
- package/dist/stamped-database.js.map +1 -0
- package/package.json +5 -4
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @zukhruf/sqlite-data-version
|
|
2
2
|
|
|
3
|
-
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.
|
|
3
|
+
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. Some owners let no reader in, so `DataVersion.ofExclusiveOwner` observes the file stamp of the database file in its place.
|
|
4
4
|
|
|
5
5
|
The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
|
|
6
6
|
|
|
@@ -59,6 +59,27 @@ no change
|
|
|
59
59
|
- Dispose closes the connection. Use `using`, or call `[Symbol.dispose]()`.
|
|
60
60
|
- The package throws its own `UnavailableError`. It is the class of `@zukhruf/sqlite-reader`, which opens the connection. The package exports it, so a catch with `instanceof` works with either package. 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`. [ADR 0003](./docs/adr/0003-the-package-throws-its-own-errors.md) tells why.
|
|
61
61
|
|
|
62
|
+
## An owner that lets no reader in
|
|
63
|
+
|
|
64
|
+
An exclusive owner holds SQLite's exclusive locking mode, as Chromium holds its History. `new DataVersion(path)` then fails with `SQLITE_BUSY` (5). Observe the database with `DataVersion.ofExclusiveOwner(path)`:
|
|
65
|
+
|
|
66
|
+
```ts
|
|
67
|
+
import { DataVersion } from '@zukhruf/sqlite-data-version';
|
|
68
|
+
|
|
69
|
+
using version = DataVersion.ofExclusiveOwner(historyPath);
|
|
70
|
+
const seen = version.current;
|
|
71
|
+
// ... later
|
|
72
|
+
if (version.current !== seen) console.log('The owner committed. Read again.');
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
- It observes the file stamp of the database file (`@zukhruf/fs`). Each commit of the owner writes that file, so each commit is a change.
|
|
76
|
+
- A write to the journal alone is a transaction that the owner did not commit. It is no change.
|
|
77
|
+
- An open transaction that spills its pages into the database file is a change. A reader then reads the last commit again.
|
|
78
|
+
- A path that this process cannot see is no change, as for `new DataVersion`. When a file is at the path again, that is a change.
|
|
79
|
+
- It opens no connection, so it never waits for the lock of the owner.
|
|
80
|
+
|
|
81
|
+
[ADR 0004](./docs/adr/0004-the-version-of-an-exclusive-owner-is-the-stamp-of-its-database-file.md) tells why.
|
|
82
|
+
|
|
62
83
|
## The last write
|
|
63
84
|
|
|
64
85
|
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.
|
|
@@ -81,11 +102,11 @@ console.log(`The owner last wrote at ${written.toISOString()}`);
|
|
|
81
102
|
|
|
82
103
|
## Errors
|
|
83
104
|
|
|
84
|
-
| Error | When
|
|
85
|
-
| ---------------------------- |
|
|
86
|
-
| `UnavailableError` | SQLite cannot open the file: `SQLITE_CANTOPEN` (14), for a missing file or a file that the system denies, a privacy denial too. `new DataVersion` throws it, and `current` throws it when it cannot open a replaced file. `cause` is the error of SQLite. |
|
|
87
|
-
| The error of SQLite | All other failures.
|
|
88
|
-
| The error of the file system | `current` cannot read the status of the path, for a cause other than a missing path or a folder that denies this process.
|
|
105
|
+
| Error | When |
|
|
106
|
+
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
107
|
+
| `UnavailableError` | SQLite cannot open the file: `SQLITE_CANTOPEN` (14), for a missing file or a file that the system denies, a privacy denial too. `new DataVersion` throws it, and `current` throws it when it cannot open a replaced file. `cause` is the error of SQLite. `ofExclusiveOwner` throws it when the file is missing (`ENOENT`) or a folder denies this process (`EACCES`); then `cause` is the error of the file system. |
|
|
108
|
+
| The error of SQLite | All other failures. |
|
|
109
|
+
| The error of the file system | `current` cannot read the status of the path, for a cause other than a missing path or a folder that denies this process. |
|
|
89
110
|
|
|
90
111
|
`UnavailableError` has the `path`. `lastWrite` throws `UnavailableError` when the file is missing (`ENOENT`) or the mode of its folder denies this process (`EACCES`). Then `cause` is the error of the file system. `lastWrite` throws the error of the file system for all other failures.
|
|
91
112
|
|
|
@@ -105,6 +126,7 @@ console.log(`The owner last wrote at ${written.toISOString()}`);
|
|
|
105
126
|
- [0001 Poll data_version](./docs/adr/0001-poll-data-version.md)
|
|
106
127
|
- [0002 A replaced file is followed by name](./docs/adr/0002-a-replaced-file-is-followed-by-name.md)
|
|
107
128
|
- [0003 The package throws its own errors](./docs/adr/0003-the-package-throws-its-own-errors.md)
|
|
129
|
+
- [0004 The version of an exclusive owner is the stamp of its database file](./docs/adr/0004-the-version-of-an-exclusive-owner-is-the-stamp-of-its-database-file.md)
|
|
108
130
|
|
|
109
131
|
## Development
|
|
110
132
|
|
|
@@ -122,7 +144,9 @@ src/
|
|
|
122
144
|
index.ts the exports
|
|
123
145
|
data-version.ts DataVersion
|
|
124
146
|
followed-database.ts the connection that follows the path to a replaced file
|
|
147
|
+
stamped-database.ts the file stamp of the database of an exclusive owner
|
|
125
148
|
data-version.test.ts the tests, on real SQLite files
|
|
149
|
+
exclusive-owner.test.ts the tests, with an owner in another process
|
|
126
150
|
last-write.ts lastWrite
|
|
127
151
|
last-write.test.ts the tests, on real SQLite files
|
|
128
152
|
```
|
package/dist/data-version.d.ts
CHANGED
|
@@ -1,7 +1,12 @@
|
|
|
1
|
+
type ObservedDatabase = Disposable & {
|
|
2
|
+
observe(): string;
|
|
3
|
+
};
|
|
1
4
|
export declare class DataVersion implements Disposable {
|
|
2
5
|
#private;
|
|
3
|
-
constructor(path: string);
|
|
6
|
+
constructor(path: string, database?: ObservedDatabase);
|
|
7
|
+
static ofExclusiveOwner(path: string): DataVersion;
|
|
4
8
|
get current(): number;
|
|
5
9
|
[Symbol.dispose](): void;
|
|
6
10
|
}
|
|
11
|
+
export {};
|
|
7
12
|
//# sourceMappingURL=data-version.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"data-version.d.ts","sourceRoot":"","sources":["../src/data-version.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"data-version.d.ts","sourceRoot":"","sources":["../src/data-version.ts"],"names":[],"mappings":"AAIA,KAAK,gBAAgB,GAAG,UAAU,GAAG;IAAE,OAAO,IAAI,MAAM,CAAA;CAAE,CAAC;AAQ3D,qBAAa,WAAY,YAAW,UAAU;;gBAM1C,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,gBAA6C;IAUzD,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW;IAIlD,IAAI,OAAO,IAAI,MAAM,CAOpB;IAED,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB"}
|
package/dist/data-version.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { FollowedDatabase } from "./followed-database.js";
|
|
2
|
+
import { StampedDatabase } from "./stamped-database.js";
|
|
2
3
|
// The owner commits through a WAL it keeps open, and file-change events
|
|
3
4
|
// report a write only when the file closes. SQLite's data_version changes on
|
|
4
5
|
// every commit by another connection, so polling current sees each one.
|
|
@@ -9,10 +10,17 @@ export class DataVersion {
|
|
|
9
10
|
#database;
|
|
10
11
|
#seen;
|
|
11
12
|
#current = 0;
|
|
12
|
-
constructor(path) {
|
|
13
|
-
this.#database =
|
|
13
|
+
constructor(path, database = new FollowedDatabase(path)) {
|
|
14
|
+
this.#database = database;
|
|
14
15
|
this.#seen = this.#database.observe();
|
|
15
16
|
}
|
|
17
|
+
// The version of a database whose owner holds SQLite's exclusive locking
|
|
18
|
+
// mode, as Chromium holds its History: the owner lets no reader read
|
|
19
|
+
// data_version, so the file stamp of the database file tells its commits
|
|
20
|
+
// apart.
|
|
21
|
+
static ofExclusiveOwner(path) {
|
|
22
|
+
return new DataVersion(path, new StampedDatabase(path));
|
|
23
|
+
}
|
|
16
24
|
get current() {
|
|
17
25
|
const observed = this.#database.observe();
|
|
18
26
|
if (observed !== this.#seen) {
|
package/dist/data-version.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"data-version.js","sourceRoot":"","sources":["../src/data-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;
|
|
1
|
+
{"version":3,"file":"data-version.js","sourceRoot":"","sources":["../src/data-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAKxD,wEAAwE;AACxE,6EAA6E;AAC7E,wEAAwE;AACxE,sEAAsE;AACtE,wEAAwE;AACxE,0DAA0D;AAC1D,MAAM,OAAO,WAAW;IACb,SAAS,CAAmB;IACrC,KAAK,CAAS;IACd,QAAQ,GAAG,CAAC,CAAC;IAEb,YACE,IAAY,EACZ,WAA6B,IAAI,gBAAgB,CAAC,IAAI,CAAC;QAEvD,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;IACxC,CAAC;IAED,yEAAyE;IACzE,qEAAqE;IACrE,yEAAyE;IACzE,SAAS;IACT,MAAM,CAAC,gBAAgB,CAAC,IAAY;QAClC,OAAO,IAAI,WAAW,CAAC,IAAI,EAAE,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,OAAO;QACT,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;QAC1C,IAAI,QAAQ,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YAC5B,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;YACtB,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,CAAC,MAAM,CAAC,OAAO,CAAC;QACd,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;IACnC,CAAC;CACF"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"stamped-database.d.ts","sourceRoot":"","sources":["../src/stamped-database.ts"],"names":[],"mappings":"AAWA,qBAAa,eAAgB,YAAW,UAAU;;gBAIpC,IAAI,EAAE,MAAM;IAYxB,OAAO,IAAI,MAAM;IAajB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CACzB"}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import { statSync } from 'node:fs';
|
|
2
|
+
import { FileStamp, isErrno } from '@zukhruf/fs';
|
|
3
|
+
import { UnavailableError } from '@zukhruf/sqlite-reader';
|
|
4
|
+
// A database whose owner holds SQLite's exclusive locking mode, as Chromium
|
|
5
|
+
// holds its History. The owner lets no reader read data_version, but each
|
|
6
|
+
// commit writes the database file, so its file stamp changes. A write to the
|
|
7
|
+
// journal alone is a transaction the owner did not commit, and no change. A
|
|
8
|
+
// path this process cannot see keeps the last observation: the owner may be
|
|
9
|
+
// about to create the file again.
|
|
10
|
+
export class StampedDatabase {
|
|
11
|
+
#path;
|
|
12
|
+
#observation;
|
|
13
|
+
constructor(path) {
|
|
14
|
+
try {
|
|
15
|
+
statSync(path);
|
|
16
|
+
}
|
|
17
|
+
catch (cause) {
|
|
18
|
+
if (isErrno(cause, 'ENOENT') || isErrno(cause, 'EACCES'))
|
|
19
|
+
throw new UnavailableError(path, cause);
|
|
20
|
+
throw cause;
|
|
21
|
+
}
|
|
22
|
+
this.#path = path;
|
|
23
|
+
this.#observation = String(FileStamp.readSync(path));
|
|
24
|
+
}
|
|
25
|
+
observe() {
|
|
26
|
+
let stamp;
|
|
27
|
+
try {
|
|
28
|
+
stamp = FileStamp.readSync(this.#path);
|
|
29
|
+
}
|
|
30
|
+
catch (error) {
|
|
31
|
+
if (isErrno(error, 'EACCES'))
|
|
32
|
+
return this.#observation;
|
|
33
|
+
throw error;
|
|
34
|
+
}
|
|
35
|
+
if (stamp.modifiedAt !== undefined)
|
|
36
|
+
this.#observation = String(stamp);
|
|
37
|
+
return this.#observation;
|
|
38
|
+
}
|
|
39
|
+
// A stat holds nothing open.
|
|
40
|
+
[Symbol.dispose]() { }
|
|
41
|
+
}
|
|
42
|
+
//# sourceMappingURL=stamped-database.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"stamped-database.js","sourceRoot":"","sources":["../src/stamped-database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,4EAA4E;AAC5E,0EAA0E;AAC1E,6EAA6E;AAC7E,4EAA4E;AAC5E,4EAA4E;AAC5E,kCAAkC;AAClC,MAAM,OAAO,eAAe;IACjB,KAAK,CAAS;IACvB,YAAY,CAAS;IAErB,YAAY,IAAY;QACtB,IAAI,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC;gBACtD,MAAM,IAAI,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC1C,MAAM,KAAK,CAAC;QACd,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,OAAO;QACL,IAAI,KAAgB,CAAC;QACrB,IAAI,CAAC;YACH,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC;gBAAE,OAAO,IAAI,CAAC,YAAY,CAAC;YACvD,MAAM,KAAK,CAAC;QACd,CAAC;QACD,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;YAAE,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,6BAA6B;IAC7B,CAAC,MAAM,CAAC,OAAO,CAAC,KAAU,CAAC;CAC5B"}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zukhruf/sqlite-data-version",
|
|
3
|
-
"version": "0.6.
|
|
4
|
-
"description": "The data version of a SQLite database that another process owns and writes
|
|
3
|
+
"version": "0.6.15",
|
|
4
|
+
"description": "The data version of a SQLite database that another process owns and writes: PRAGMA data_version on its own read-only connection, or the file stamp of the database when the owner holds the exclusive lock.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -40,9 +40,10 @@
|
|
|
40
40
|
"access": "public"
|
|
41
41
|
},
|
|
42
42
|
"dependencies": {
|
|
43
|
-
"@zukhruf/
|
|
43
|
+
"@zukhruf/fs": "^0.6.15",
|
|
44
|
+
"@zukhruf/sqlite-reader": "^0.6.15"
|
|
44
45
|
},
|
|
45
46
|
"devDependencies": {
|
|
46
|
-
"@zukhruf/testing": "^0.6.
|
|
47
|
+
"@zukhruf/testing": "^0.6.15"
|
|
47
48
|
}
|
|
48
49
|
}
|