@zukhruf/sqlite-data-version 0.7.0 → 0.8.1

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 CHANGED
@@ -50,6 +50,7 @@ no change
50
50
 
51
51
  - `new DataVersion(path)` 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.
52
52
  - `current` gives the data version now. It is the number of `DataVersion`, not the `PRAGMA data_version` of SQLite. Compare it with the value that you read before from the same `DataVersion`. A different value tells that another connection committed, or that the owner replaced the file. The same value tells that no change occurred.
53
+ - `DataVersion` is a `Gauge<number>` of `@zukhruf/async`. Give it to a `ChangeWatcher`, and each check reads `current`. A check after a commit of the owner gives `changed`, and a check with no commit gives `unchanged`.
53
54
  - The number tells only that a change occurred. It does not count the commits, and it does not tell what changed.
54
55
  - `DataVersion` follows the path. The owner can replace the file at the path: it can rename a new file over it, or delete the file and create it again. A replaced file is a change. Then `DataVersion` reads the new file, and each later commit to the new file is a change too. [ADR 0002](./docs/adr/0002-a-replaced-file-is-followed-by-name.md) tells why.
55
56
  - A path that this process cannot see is no change. The path is missing, or the mode of a folder denies this process. The owner can delete the file and create it again a short time later. `DataVersion` keeps the old connection until it can see a file at the path again, and then a replaced file is a change.
@@ -58,6 +59,27 @@ no change
58
59
  - Dispose closes the connection. Use `using`, or call `[Symbol.dispose]()`.
59
60
  - The package throws its own `UnavailableError`. It is the class of `@zukhruf/sqlite-open`, 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.
60
61
 
62
+ ## Watch the data version
63
+
64
+ ```ts
65
+ import { ChangeWatcher } from '@zukhruf/async';
66
+ import { DataVersion } from '@zukhruf/sqlite-data-version';
67
+
68
+ using version = new DataVersion(path);
69
+ // The data version is a local read: a check that takes the whole interval is stuck.
70
+ const watcher = new ChangeWatcher([version], {
71
+ interval: 1_000,
72
+ timeout: 1_000,
73
+ clock: globalThis,
74
+ });
75
+ for await (const outcomes of watcher.watch(signal)) {
76
+ const outcome = outcomes.get(version);
77
+ if (outcome?.state === 'failed') throw outcome.error;
78
+ if (outcome?.state === 'changed')
79
+ console.log('The owner committed. Read again.');
80
+ }
81
+ ```
82
+
61
83
  ## An owner that lets no reader in
62
84
 
63
85
  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)`:
@@ -1,11 +1,13 @@
1
+ import { Gauge } from '@zukhruf/async';
1
2
  type ObservedDatabase = Disposable & {
2
3
  observe(): string;
3
4
  };
4
- export declare class DataVersion implements Disposable {
5
+ export declare class DataVersion extends Gauge<number> implements Disposable {
5
6
  #private;
6
7
  constructor(path: string, database?: ObservedDatabase);
7
8
  static ofExclusiveOwner(path: string): DataVersion;
8
9
  get current(): number;
10
+ protected read(): Promise<number>;
9
11
  [Symbol.dispose](): void;
10
12
  }
11
13
  export {};
@@ -1 +1 @@
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"}
1
+ {"version":3,"file":"data-version.d.ts","sourceRoot":"","sources":["../src/data-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAMvC,KAAK,gBAAgB,GAAG,UAAU,GAAG;IAAE,OAAO,IAAI,MAAM,CAAA;CAAE,CAAC;AAS3D,qBAAa,WAAY,SAAQ,KAAK,CAAC,MAAM,CAAE,YAAW,UAAU;;gBAMhE,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,gBAA6C;IAWzD,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW;IAIlD,IAAI,OAAO,IAAI,MAAM,CAOpB;cAEe,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAIvC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB"}
@@ -1,3 +1,4 @@
1
+ import { Gauge } from '@zukhruf/async';
1
2
  import { FollowedDatabase } from "./followed-database.js";
2
3
  import { StampedDatabase } from "./stamped-database.js";
3
4
  // The owner commits through a WAL it keeps open, and file-change events
@@ -6,11 +7,13 @@ import { StampedDatabase } from "./stamped-database.js";
6
7
  // The owner can also replace the file at the path. A new connection's
7
8
  // data_version starts again and can equal an old value, so current is a
8
9
  // count of the changes seen, not the data_version itself.
9
- export class DataVersion {
10
+ // It exists to tell a change, so it is a gauge: a change watcher reads current.
11
+ export class DataVersion extends Gauge {
10
12
  #database;
11
13
  #seen;
12
14
  #current = 0;
13
15
  constructor(path, database = new FollowedDatabase(path)) {
16
+ super();
14
17
  this.#database = database;
15
18
  this.#seen = this.#database.observe();
16
19
  }
@@ -29,6 +32,9 @@ export class DataVersion {
29
32
  }
30
33
  return this.#current;
31
34
  }
35
+ async read() {
36
+ return this.current;
37
+ }
32
38
  [Symbol.dispose]() {
33
39
  this.#database[Symbol.dispose]();
34
40
  }
@@ -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;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"}
1
+ {"version":3,"file":"data-version.js","sourceRoot":"","sources":["../src/data-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,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,gFAAgF;AAChF,MAAM,OAAO,WAAY,SAAQ,KAAa;IACnC,SAAS,CAAmB;IACrC,KAAK,CAAS;IACd,QAAQ,GAAG,CAAC,CAAC;IAEb,YACE,IAAY,EACZ,WAA6B,IAAI,gBAAgB,CAAC,IAAI,CAAC;QAEvD,KAAK,EAAE,CAAC;QACR,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;IAES,KAAK,CAAC,IAAI;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,CAAC,MAAM,CAAC,OAAO,CAAC;QACd,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;IACnC,CAAC;CACF"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zukhruf/sqlite-data-version",
3
- "version": "0.7.0",
3
+ "version": "0.8.1",
4
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": {
@@ -40,10 +40,11 @@
40
40
  "access": "public"
41
41
  },
42
42
  "dependencies": {
43
- "@zukhruf/fs": "^0.7.0",
44
- "@zukhruf/sqlite-open": "^0.7.0"
43
+ "@zukhruf/async": "^0.8.1",
44
+ "@zukhruf/fs": "^0.8.1",
45
+ "@zukhruf/sqlite-open": "^0.8.1"
45
46
  },
46
47
  "devDependencies": {
47
- "@zukhruf/testing": "^0.7.0"
48
+ "@zukhruf/testing": "^0.8.1"
48
49
  }
49
50
  }