@zukhruf/fs 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 CHANGED
@@ -1,6 +1,6 @@
1
1
  # @zukhruf/fs
2
2
 
3
- Helpers that write files, and a lock on a file that the kernel frees when its holder dies. A reader never sees a part of a write. `@zukhruf/mutex` uses them for its lock files, `@zukhruf/fencing` for its fencing counters, and `@zukhruf/election` for the claim and the epoch of each election. `@zukhruf/single-flight` keeps no lock files of its own: its election claims a `FileLock` through `@zukhruf/election`.
3
+ Helpers that write files, a lock on a file that the kernel frees when its holder dies, and a stamp that tells that a file changed. A reader never sees a part of a write. `@zukhruf/mutex` uses them for its lock files, `@zukhruf/fencing` for its fencing counters, and `@zukhruf/election` for the claim and the epoch of each election. `@zukhruf/single-flight` keeps no lock files of its own: its election claims a `FileLock` through `@zukhruf/election`.
4
4
 
5
5
  The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
6
6
 
@@ -11,7 +11,9 @@ A write that changes a file in place can stop halfway. Then a reader sees a part
11
11
  ```ts
12
12
  import { atomicWrite } from '@zukhruf/fs';
13
13
 
14
- await atomicWrite('/var/lib/app/queue', 'first\nsecond\n');
14
+ await atomicWrite('/var/lib/app/queue', 'first\nsecond\n', {
15
+ clock: globalThis,
16
+ });
15
17
  ```
16
18
 
17
19
  ## Make the replacement durable
@@ -25,7 +27,7 @@ After a rename, the operating system can keep the new content in memory for some
25
27
  ```ts
26
28
  import { durableWrite } from '@zukhruf/fs';
27
29
 
28
- await durableWrite('/var/lib/app/counter', '42');
30
+ await durableWrite('/var/lib/app/counter', '42', { clock: globalThis });
29
31
  ```
30
32
 
31
33
  Use `durableWrite` when a value must never go back after a crash, for example a counter that gives out fencing tokens. A counter that goes back gives the same token two times.
@@ -37,10 +39,12 @@ On Windows, a process cannot open a directory to sync it. Some file systems refu
37
39
  `atomicWrite` and `durableWrite` take the same arguments:
38
40
 
39
41
  ```ts
40
- atomicWrite(path: string, content: string | Uint8Array, options?: { mode?: number })
41
- durableWrite(path: string, content: string | Uint8Array, options?: { mode?: number })
42
+ atomicWrite(path: string, content: string | Uint8Array, options: { clock: Clock; mode?: number })
43
+ durableWrite(path: string, content: string | Uint8Array, options: { clock: Clock; mode?: number })
42
44
  ```
43
45
 
46
+ `clock` is the clock that the waits of the write run on. Give `globalThis` in production, and a fake clock in a test. A write waits only on Windows, between two tries of a rename that Windows refuses for now (see "Try again while Windows refuses a file for a moment"). `Clock` is the type of `@zukhruf/async`.
47
+
44
48
  The content is a string or bytes. A `Buffer` is a `Uint8Array`, so a `Buffer` is bytes too. The write puts the bytes at the path with no change.
45
49
 
46
50
  `mode` sets the POSIX file mode of the new file, for example `0o600` for a file that only its owner can read. The process umask applies to `mode`, as it does for `writeFile`. The write sets `mode` when it creates the draft, because the rename keeps the mode of the draft. Thus the file at the path never has a different mode, not even for a moment. When you do not give `mode`, the file gets the mode that `writeFile` gives a new file. A write never keeps the mode of the file that it replaces.
@@ -50,7 +54,10 @@ import { randomBytes } from 'node:crypto';
50
54
 
51
55
  import { atomicWrite } from '@zukhruf/fs';
52
56
 
53
- await atomicWrite('/var/lib/app/key', randomBytes(32), { mode: 0o600 });
57
+ await atomicWrite('/var/lib/app/key', randomBytes(32), {
58
+ clock: globalThis,
59
+ mode: 0o600,
60
+ });
54
61
  ```
55
62
 
56
63
  On Windows, a file has no POSIX mode. Node.js uses only the write bit of `mode` there, to make the file read-only.
@@ -62,7 +69,9 @@ On Windows, a file has no POSIX mode. Node.js uses only the write bit of `mode`
62
69
  ```ts
63
70
  import { createExclusive } from '@zukhruf/fs';
64
71
 
65
- const created = await createExclusive('/var/lib/app/job.lock', 'pid 4242');
72
+ const created = await createExclusive('/var/lib/app/job.lock', 'pid 4242', {
73
+ clock: globalThis,
74
+ });
66
75
  if (!created) console.log('Another process holds the job.');
67
76
  ```
68
77
 
@@ -84,7 +93,9 @@ import { join } from 'node:path';
84
93
  import { createExclusive, draftSuffixLength, safeFileName } from '@zukhruf/fs';
85
94
 
86
95
  const name = safeFileName('orders/2026', '.lock'.length + draftSuffixLength);
87
- await createExclusive(join('/var/lib/app/locks', `${name}.lock`), 'pid 4242');
96
+ await createExclusive(join('/var/lib/app/locks', `${name}.lock`), 'pid 4242', {
97
+ clock: globalThis,
98
+ });
88
99
  // The file is orders%2F2026.lock
89
100
  ```
90
101
 
@@ -102,12 +113,15 @@ import { readFile } from 'node:fs/promises';
102
113
 
103
114
  import { patiently } from '@zukhruf/fs';
104
115
 
105
- const content = await patiently(() =>
106
- readFile('/var/lib/app/job.lock', 'utf8'),
116
+ const content = await patiently(
117
+ () => readFile('/var/lib/app/job.lock', 'utf8'),
118
+ { clock: globalThis },
107
119
  );
108
120
  ```
109
121
 
110
- Each write of this package uses `patiently` for its rename or link.
122
+ Each wait between two tries runs on the clock that you give. The 1 second is a time on that clock too. A test gives a fake clock and moves the time, so that the test does not wait. See [ADR 0005](./docs/adr/0005-a-write-waits-on-the-clock-that-the-caller-gives.md).
123
+
124
+ Each write of this package uses `patiently` for its rename or link, with the clock of the write.
111
125
 
112
126
  ## Lock a file
113
127
 
@@ -169,6 +183,45 @@ try {
169
183
 
170
184
  `@zukhruf/mutex` and `@zukhruf/single-flight` give this same `NetworkDirectoryError` class. A catch with `instanceof` works for each of them.
171
185
 
186
+ ## Tell that a file changed
187
+
188
+ A program that watches a file reads it again after each write. A read of the whole file on each check costs too much, and a file-change event can come late or not at all. Git has the same problem for each file in a working tree. Git compares the stat data of the file with the stat data that it kept: when they are equal, the file did not change. A `FileStamp` is that stat data.
189
+
190
+ ```ts
191
+ import { FileStamp } from '@zukhruf/fs';
192
+
193
+ const before = await FileStamp.read('/var/lib/app/store.json');
194
+ // ... later
195
+ const now = await FileStamp.read('/var/lib/app/store.json');
196
+ if (!now.equals(before)) console.log('The store changed. Read it again.');
197
+ ```
198
+
199
+ - A file stamp holds the device, the inode, the size, the time of the last write and the time of the last change of the file. Each time is to the nanosecond.
200
+ - A write changes the stamp. This is also true when the writer gives back the old write time, as `rsync -t` and `tar` do, because the kernel sets the time of the change. The writer cannot set that time.
201
+ - A new file at the path changes the stamp, also with the same size and write time. A program that replaces its file with a rename makes a new file.
202
+ - A missing file has a stamp of its own. Two missing stamps of one path are equal. When the file comes back, the stamp changes.
203
+ - A path through a file, for example `file/store`, is missing too (`ENOTDIR`).
204
+ - Each other error of `stat` reaches the caller, for example `EACCES` for a folder that the process may not search. A file that the process may not see is not a missing file.
205
+ - `modifiedAt` is the time of the last write. It is `undefined` for a missing file.
206
+ - `FileStamp.read(path)` reads the stamp. `FileStamp.readSync(path)` reads it and blocks.
207
+ - `toString()` gives the stamp as text, so that you can keep it.
208
+
209
+ `FileStamps` holds the stamps of several files that change together, for example a database and its journal, or the files of one store. A write of any file changes the whole. A missing file is a part of it.
210
+
211
+ ```ts
212
+ import { FileStamps } from '@zukhruf/fs';
213
+
214
+ const stamps = await FileStamps.read([
215
+ '/var/lib/app/History',
216
+ '/var/lib/app/History-journal',
217
+ ]);
218
+ console.log(stamps.modifiedAt); // the newest write of the files that are present
219
+ ```
220
+
221
+ `modifiedAt` of `FileStamps` is the newest write of the files that are present. It is `undefined` when no file is present.
222
+
223
+ No package on npm does this job. [ADR 0004](./docs/adr/0004-a-file-stamp-is-the-stat-data-that-git-compares.md) tells why each candidate failed.
224
+
172
225
  ## Check the error code
173
226
 
174
227
  `isErrno(error, code)` tells if `error` is a Node.js system error with that error code.
@@ -1,9 +1,11 @@
1
+ import type { Clock } from '@zukhruf/async';
1
2
  /**
2
3
  * Replaces `path` in one step, so readers see the old or the new content, never a partial write.
3
4
  * `mode` is set when the draft is created: the rename keeps the draft's mode,
4
5
  * so the file never has another mode at the path.
5
6
  */
6
- export declare function atomicWrite(path: string, content: string | Uint8Array, options?: {
7
+ export declare function atomicWrite(path: string, content: string | Uint8Array, { clock, mode }: {
8
+ clock: Clock;
7
9
  mode?: number;
8
10
  }): Promise<void>;
9
11
  //# sourceMappingURL=atomic-write.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,iBAW5B"}
1
+ {"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAK5C;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,iBAWjD"}
@@ -6,11 +6,11 @@ import { replaceFile } from "./replace-file.js";
6
6
  * `mode` is set when the draft is created: the rename keeps the draft's mode,
7
7
  * so the file never has another mode at the path.
8
8
  */
9
- export async function atomicWrite(path, content, options) {
9
+ export async function atomicWrite(path, content, { clock, mode }) {
10
10
  const draft = draftOf(path);
11
11
  try {
12
- await writeFile(draft, content, { mode: options?.mode });
13
- await replaceFile(draft, path);
12
+ await writeFile(draft, content, { mode });
13
+ await replaceFile(draft, path, clock);
14
14
  }
15
15
  catch (error) {
16
16
  // A draft that never replaced `path` would only pile up, one per failed write.
@@ -1 +1 @@
1
- {"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAY,EACZ,OAA4B,EAC5B,OAA2B;IAE3B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,MAAM,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,+EAA+E;QAC/E,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAIjD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAY,EACZ,OAA4B,EAC5B,EAAE,KAAK,EAAE,IAAI,EAAmC;IAEhD,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,MAAM,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,+EAA+E;QAC/E,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}
@@ -1,6 +1,9 @@
1
+ import type { Clock } from '@zukhruf/async';
1
2
  /**
2
3
  * Creates `path` holding `content` unless it already exists. Linking a fully
3
4
  * written file makes creation atomic, so the file is never seen empty.
4
5
  */
5
- export declare function createExclusive(path: string, content: string): Promise<boolean>;
6
+ export declare function createExclusive(path: string, content: string, { clock }: {
7
+ clock: Clock;
8
+ }): Promise<boolean>;
6
9
  //# sourceMappingURL=create-exclusive.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"create-exclusive.d.ts","sourceRoot":"","sources":["../src/create-exclusive.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,oBAYlE"}
1
+ {"version":3,"file":"create-exclusive.d.ts","sourceRoot":"","sources":["../src/create-exclusive.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAM5C;;;GAGG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,oBAa5B"}
@@ -6,11 +6,11 @@ import { patiently } from "./patiently.js";
6
6
  * Creates `path` holding `content` unless it already exists. Linking a fully
7
7
  * written file makes creation atomic, so the file is never seen empty.
8
8
  */
9
- export async function createExclusive(path, content) {
9
+ export async function createExclusive(path, content, { clock }) {
10
10
  const draft = draftOf(path);
11
11
  try {
12
12
  await writeFile(draft, content);
13
- await patiently(() => link(draft, path));
13
+ await patiently(() => link(draft, path), { clock });
14
14
  return true;
15
15
  }
16
16
  catch (error) {
@@ -19,11 +19,11 @@ export async function createExclusive(path, content) {
19
19
  throw error;
20
20
  }
21
21
  finally {
22
- await removeDraft(draft);
22
+ await removeDraft(draft, clock);
23
23
  }
24
24
  }
25
25
  /** A draft left behind has a unique name, so it never blocks a key; failing to remove it must not change whether `path` was created. */
26
- async function removeDraft(draft) {
27
- await patiently(() => unlink(draft)).catch(() => { });
26
+ async function removeDraft(draft, clock) {
27
+ await patiently(() => unlink(draft), { clock }).catch(() => { });
28
28
  }
29
29
  //# sourceMappingURL=create-exclusive.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"create-exclusive.js","sourceRoot":"","sources":["../src/create-exclusive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,OAAe;IACjE,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAChC,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3C,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,MAAM,WAAW,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,wIAAwI;AACxI,KAAK,UAAU,WAAW,CAAC,KAAa;IACtC,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AACvD,CAAC"}
1
+ {"version":3,"file":"create-exclusive.js","sourceRoot":"","sources":["../src/create-exclusive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAI3D,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAY,EACZ,OAAe,EACf,EAAE,KAAK,EAAoB;IAE3B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAChC,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3C,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,MAAM,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;AACH,CAAC;AAED,wIAAwI;AACxI,KAAK,UAAU,WAAW,CAAC,KAAa,EAAE,KAAY;IACpD,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AAClE,CAAC"}
@@ -1,9 +1,11 @@
1
+ import type { Clock } from '@zukhruf/async';
1
2
  /**
2
3
  * Replaces `path` in one step like `atomicWrite`, and returns only once both
3
4
  * the new content and the replacement survive a power loss: a counter that
4
5
  * goes back after a crash would hand out a token twice.
5
6
  */
6
- export declare function durableWrite(path: string, content: string | Uint8Array, options?: {
7
+ export declare function durableWrite(path: string, content: string | Uint8Array, { clock, mode }: {
8
+ clock: Clock;
7
9
  mode?: number;
8
10
  }): Promise<void>;
9
11
  //# sourceMappingURL=durable-write.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"durable-write.d.ts","sourceRoot":"","sources":["../src/durable-write.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,iBAa5B"}
1
+ {"version":3,"file":"durable-write.d.ts","sourceRoot":"","sources":["../src/durable-write.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAM5C;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,iBAajD"}
@@ -8,12 +8,12 @@ import { replaceFile } from "./replace-file.js";
8
8
  * the new content and the replacement survive a power loss: a counter that
9
9
  * goes back after a crash would hand out a token twice.
10
10
  */
11
- export async function durableWrite(path, content, options) {
11
+ export async function durableWrite(path, content, { clock, mode }) {
12
12
  const draft = draftOf(path);
13
13
  try {
14
14
  // The rename keeps the draft's mode, so `mode` is set when the draft is created.
15
- await writeSynced(draft, content, options?.mode);
16
- await replaceFile(draft, path);
15
+ await writeSynced(draft, content, mode);
16
+ await replaceFile(draft, path, clock);
17
17
  }
18
18
  catch (error) {
19
19
  // A draft that never replaced `path` would only pile up, one per failed write.
@@ -1 +1 @@
1
- {"version":3,"file":"durable-write.js","sourceRoot":"","sources":["../src/durable-write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,OAA4B,EAC5B,OAA2B;IAE3B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC;QACH,iFAAiF;QACjF,MAAM,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QACjD,MAAM,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,+EAA+E;QAC/E,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjC,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,KAAK,UAAU,WAAW,CACxB,IAAY,EACZ,OAA4B,EAC5B,IAAwB;IAExB,YAAY,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAClD,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAChC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,aAAa,CAAC,SAAiB;IAC5C,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO;IACzC,YAAY,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAChD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC;YAAE,MAAM,KAAK,CAAC;IAC3E,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"durable-write.js","sourceRoot":"","sources":["../src/durable-write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAY,EACZ,OAA4B,EAC5B,EAAE,KAAK,EAAE,IAAI,EAAmC;IAEhD,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC;QACH,iFAAiF;QACjF,MAAM,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QACxC,MAAM,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,+EAA+E;QAC/E,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjC,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,KAAK,UAAU,WAAW,CACxB,IAAY,EACZ,OAA4B,EAC5B,IAAwB;IAExB,YAAY,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAClD,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAChC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,aAAa,CAAC,SAAiB;IAC5C,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO;IACzC,YAAY,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAChD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC;YAAE,MAAM,KAAK,CAAC;IAC3E,CAAC;AACH,CAAC"}
@@ -0,0 +1,21 @@
1
+ /**
2
+ * What the file system says about the file at a path: its device, inode,
3
+ * size, and the times of its last write and its last change, to the
4
+ * nanosecond. A write of the file changes its stamp, also when the writer
5
+ * gives back the old write time, because the kernel sets the change time. A
6
+ * new file at the path changes it too. A missing file has a stamp of its own.
7
+ * Git compares the same stat data to know that a file is unchanged without a
8
+ * read of its content.
9
+ */
10
+ export declare class FileStamp {
11
+ #private;
12
+ readonly path: string;
13
+ /** When the file was last written; undefined when no file is at the path. */
14
+ readonly modifiedAt: Date | undefined;
15
+ private constructor();
16
+ static read(path: string): Promise<FileStamp>;
17
+ static readSync(path: string): FileStamp;
18
+ equals(other: FileStamp): boolean;
19
+ toString(): string;
20
+ }
21
+ //# sourceMappingURL=file-stamp.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"file-stamp.d.ts","sourceRoot":"","sources":["../src/file-stamp.ts"],"names":[],"mappings":"AAWA;;;;;;;;GAQG;AACH,qBAAa,SAAS;;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,IAAI,GAAG,SAAS,CAAC;IAGtC,OAAO;WAYM,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IASnD,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS;IASxC,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;IAIjC,QAAQ,IAAI,MAAM;CAGnB"}
@@ -0,0 +1,60 @@
1
+ import { statSync } from 'node:fs';
2
+ import { stat } from 'node:fs/promises';
3
+ import { isErrno } from "./errno.js";
4
+ // Absence: no file at the path, or a part of the path that is a file and not
5
+ // a folder. A folder that the process may not search is not absence: stat
6
+ // fails with EACCES, and that error reaches the caller.
7
+ const absent = (error) => isErrno(error, 'ENOENT') || isErrno(error, 'ENOTDIR');
8
+ /**
9
+ * What the file system says about the file at a path: its device, inode,
10
+ * size, and the times of its last write and its last change, to the
11
+ * nanosecond. A write of the file changes its stamp, also when the writer
12
+ * gives back the old write time, because the kernel sets the change time. A
13
+ * new file at the path changes it too. A missing file has a stamp of its own.
14
+ * Git compares the same stat data to know that a file is unchanged without a
15
+ * read of its content.
16
+ */
17
+ export class FileStamp {
18
+ path;
19
+ /** When the file was last written; undefined when no file is at the path. */
20
+ modifiedAt;
21
+ #value;
22
+ constructor(path, stats) {
23
+ this.path = path;
24
+ this.modifiedAt =
25
+ stats === undefined
26
+ ? undefined
27
+ : new Date(Number(stats.mtimeNs / 1000000n));
28
+ this.#value =
29
+ stats === undefined
30
+ ? 'missing'
31
+ : `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeNs}:${stats.ctimeNs}`;
32
+ }
33
+ static async read(path) {
34
+ try {
35
+ return new FileStamp(path, await stat(path, { bigint: true }));
36
+ }
37
+ catch (error) {
38
+ if (absent(error))
39
+ return new FileStamp(path, undefined);
40
+ throw error;
41
+ }
42
+ }
43
+ static readSync(path) {
44
+ try {
45
+ return new FileStamp(path, statSync(path, { bigint: true }));
46
+ }
47
+ catch (error) {
48
+ if (absent(error))
49
+ return new FileStamp(path, undefined);
50
+ throw error;
51
+ }
52
+ }
53
+ equals(other) {
54
+ return this.path === other.path && this.#value === other.#value;
55
+ }
56
+ toString() {
57
+ return this.#value;
58
+ }
59
+ }
60
+ //# sourceMappingURL=file-stamp.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"file-stamp.js","sourceRoot":"","sources":["../src/file-stamp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,QAAQ,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAExC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC,6EAA6E;AAC7E,0EAA0E;AAC1E,wDAAwD;AACxD,MAAM,MAAM,GAAG,CAAC,KAAc,EAAE,EAAE,CAChC,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AAExD;;;;;;;;GAQG;AACH,MAAM,OAAO,SAAS;IACX,IAAI,CAAS;IACtB,6EAA6E;IACpE,UAAU,CAAmB;IAC7B,MAAM,CAAS;IAExB,YAAoB,IAAY,EAAE,KAA8B;QAC9D,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU;YACb,KAAK,KAAK,SAAS;gBACjB,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,QAAU,CAAC,CAAC,CAAC;QACnD,IAAI,CAAC,MAAM;YACT,KAAK,KAAK,SAAS;gBACjB,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;IACpF,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAY;QAC5B,IAAI,CAAC;YACH,OAAO,IAAI,SAAS,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QACjE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,MAAM,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YACzD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,IAAY;QAC1B,IAAI,CAAC;YACH,OAAO,IAAI,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,MAAM,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YACzD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,MAAM,CAAC,KAAgB;QACrB,OAAO,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC;IAClE,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF"}
@@ -0,0 +1,17 @@
1
+ import { FileStamp } from './file-stamp.ts';
2
+ /**
3
+ * The stamps of several files that change together, such as a database and
4
+ * its journal, or the files of one store. A write of any of them changes the
5
+ * whole. A missing file is a part of it, so its return is a change too.
6
+ */
7
+ export declare class FileStamps {
8
+ readonly stamps: readonly FileStamp[];
9
+ private constructor();
10
+ static read(paths: readonly string[]): Promise<FileStamps>;
11
+ static readSync(paths: readonly string[]): FileStamps;
12
+ /** When the newest of the files was written; undefined when none is present. */
13
+ get modifiedAt(): Date | undefined;
14
+ equals(other: FileStamps): boolean;
15
+ toString(): string;
16
+ }
17
+ //# sourceMappingURL=file-stamps.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"file-stamps.d.ts","sourceRoot":"","sources":["../src/file-stamps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;GAIG;AACH,qBAAa,UAAU;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IAEtC,OAAO;WAIM,IAAI,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAIhE,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU;IAIrD,gFAAgF;IAChF,IAAI,UAAU,IAAI,IAAI,GAAG,SAAS,CAKjC;IAED,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO;IAIlC,QAAQ,IAAI,MAAM;CAGnB"}
@@ -0,0 +1,30 @@
1
+ import { FileStamp } from "./file-stamp.js";
2
+ /**
3
+ * The stamps of several files that change together, such as a database and
4
+ * its journal, or the files of one store. A write of any of them changes the
5
+ * whole. A missing file is a part of it, so its return is a change too.
6
+ */
7
+ export class FileStamps {
8
+ stamps;
9
+ constructor(stamps) {
10
+ this.stamps = stamps;
11
+ }
12
+ static async read(paths) {
13
+ return new FileStamps(await Promise.all(paths.map(FileStamp.read)));
14
+ }
15
+ static readSync(paths) {
16
+ return new FileStamps(paths.map(FileStamp.readSync));
17
+ }
18
+ /** When the newest of the files was written; undefined when none is present. */
19
+ get modifiedAt() {
20
+ const times = this.stamps.flatMap(({ modifiedAt }) => modifiedAt === undefined ? [] : [modifiedAt.getTime()]);
21
+ return times.length === 0 ? undefined : new Date(Math.max(...times));
22
+ }
23
+ equals(other) {
24
+ return this.toString() === other.toString();
25
+ }
26
+ toString() {
27
+ return this.stamps.map((stamp) => `${stamp.path}=${stamp}`).join('\n');
28
+ }
29
+ }
30
+ //# sourceMappingURL=file-stamps.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"file-stamps.js","sourceRoot":"","sources":["../src/file-stamps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;GAIG;AACH,MAAM,OAAO,UAAU;IACZ,MAAM,CAAuB;IAEtC,YAAoB,MAA4B;QAC9C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAwB;QACxC,OAAO,IAAI,UAAU,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,KAAwB;QACtC,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,gFAAgF;IAChF,IAAI,UAAU;QACZ,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CACnD,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CACvD,CAAC;QACF,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,CAAC,KAAiB;QACtB,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC9C,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzE,CAAC;CACF"}
package/dist/index.d.ts CHANGED
@@ -2,6 +2,8 @@ export { atomicWrite } from './atomic-write.ts';
2
2
  export { createExclusive } from './create-exclusive.ts';
3
3
  export { draftSuffixLength } from './draft.ts';
4
4
  export { durableWrite } from './durable-write.ts';
5
+ export { FileStamp } from './file-stamp.ts';
6
+ export { FileStamps } from './file-stamps.ts';
5
7
  export { isErrno } from './errno.ts';
6
8
  export { FileLock } from './file-lock.ts';
7
9
  export { assertLocalDirectory } from './local-directory.ts';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}
package/dist/index.js CHANGED
@@ -2,6 +2,8 @@ export { atomicWrite } from "./atomic-write.js";
2
2
  export { createExclusive } from "./create-exclusive.js";
3
3
  export { draftSuffixLength } from "./draft.js";
4
4
  export { durableWrite } from "./durable-write.js";
5
+ export { FileStamp } from "./file-stamp.js";
6
+ export { FileStamps } from "./file-stamps.js";
5
7
  export { isErrno } from "./errno.js";
6
8
  export { FileLock } from "./file-lock.js";
7
9
  export { assertLocalDirectory } from "./local-directory.js";
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}
@@ -1,3 +1,10 @@
1
- /** Runs `operation`, and runs it again while Windows refuses the file for a moment; after that, the error reaches the caller. */
2
- export declare function patiently<T>(operation: () => Promise<T>): Promise<T>;
1
+ import { type Clock } from '@zukhruf/async';
2
+ /**
3
+ * Runs `operation`, and runs it again while Windows refuses the file for a
4
+ * moment; after that, the error reaches the caller. Each wait, and the time
5
+ * that it allows, run on the clock.
6
+ */
7
+ export declare function patiently<T>(operation: () => Promise<T>, { clock }: {
8
+ clock: Clock;
9
+ }): Promise<T>;
3
10
  //# sourceMappingURL=patiently.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"patiently.d.ts","sourceRoot":"","sources":["../src/patiently.ts"],"names":[],"mappings":"AAoBA,iIAAiI;AACjI,wBAAsB,SAAS,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAc1E"}
1
+ {"version":3,"file":"patiently.d.ts","sourceRoot":"","sources":["../src/patiently.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAS,MAAM,gBAAgB,CAAC;AAoBnD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,GAC1B,OAAO,CAAC,CAAC,CAAC,CAiBZ"}
package/dist/patiently.js CHANGED
@@ -1,4 +1,4 @@
1
- import { setTimeout as delay } from 'node:timers/promises';
1
+ import { delay } from '@zukhruf/async';
2
2
  import { isErrno } from "./errno.js";
3
3
  /** How long to retry a file operation that Windows refuses for a moment. */
4
4
  const WINDOWS_PATIENCE = 1000;
@@ -12,18 +12,25 @@ function isRefusedForNow(error) {
12
12
  return (process.platform === 'win32' &&
13
13
  ['EPERM', 'EACCES', 'EBUSY'].some((code) => isErrno(error, code)));
14
14
  }
15
- /** Runs `operation`, and runs it again while Windows refuses the file for a moment; after that, the error reaches the caller. */
16
- export async function patiently(operation) {
17
- const started = performance.now();
15
+ /**
16
+ * Runs `operation`, and runs it again while Windows refuses the file for a
17
+ * moment; after that, the error reaches the caller. Each wait, and the time
18
+ * that it allows, run on the clock.
19
+ */
20
+ export async function patiently(operation, { clock }) {
21
+ const started = clock.performance.now();
18
22
  for (let attempt = 0;; attempt++) {
19
23
  try {
20
24
  return await operation();
21
25
  }
22
26
  catch (error) {
23
27
  if (!isRefusedForNow(error) ||
24
- performance.now() - started > WINDOWS_PATIENCE)
28
+ clock.performance.now() - started > WINDOWS_PATIENCE)
25
29
  throw error;
26
- await delay(Math.min(5 * 2 ** attempt, 100));
30
+ await delay(Math.min(5 * 2 ** attempt, 100), {
31
+ clock,
32
+ signal: undefined,
33
+ });
27
34
  }
28
35
  }
29
36
  }
@@ -1 +1 @@
1
- {"version":3,"file":"patiently.js","sourceRoot":"","sources":["../src/patiently.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC,4EAA4E;AAC5E,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAE9B;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,CACL,OAAO,CAAC,QAAQ,KAAK,OAAO;QAC5B,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAClE,CAAC;AACJ,CAAC;AAED,iIAAiI;AACjI,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,SAA2B;IAC5D,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAClC,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,OAAO,MAAM,SAAS,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IACE,CAAC,eAAe,CAAC,KAAK,CAAC;gBACvB,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,gBAAgB;gBAE9C,MAAM,KAAK,CAAC;YACd,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"patiently.js","sourceRoot":"","sources":["../src/patiently.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC,4EAA4E;AAC5E,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAE9B;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,CACL,OAAO,CAAC,QAAQ,KAAK,OAAO;QAC5B,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAClE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,SAA2B,EAC3B,EAAE,KAAK,EAAoB;IAE3B,MAAM,OAAO,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;IACxC,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,OAAO,MAAM,SAAS,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IACE,CAAC,eAAe,CAAC,KAAK,CAAC;gBACvB,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,gBAAgB;gBAEpD,MAAM,KAAK,CAAC;YACd,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,OAAO,EAAE,GAAG,CAAC,EAAE;gBAC3C,KAAK;gBACL,MAAM,EAAE,SAAS;aAClB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;AACH,CAAC"}
@@ -1,8 +1,9 @@
1
+ import type { Clock } from '@zukhruf/async';
1
2
  /**
2
3
  * Moves `draft` over `path` in one step. On Windows, a rename over a file
3
4
  * fails while another process has that file open, for example a waiter that
4
5
  * reads it at that moment. The refusal is brief, so the rename is tried again;
5
6
  * it stays the single commit point.
6
7
  */
7
- export declare function replaceFile(draft: string, path: string): Promise<void>;
8
+ export declare function replaceFile(draft: string, path: string, clock: Clock): Promise<void>;
8
9
  //# sourceMappingURL=replace-file.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"replace-file.d.ts","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,iBAEtD"}
1
+ {"version":3,"file":"replace-file.d.ts","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAI5C;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,iBAEpE"}
@@ -6,7 +6,7 @@ import { patiently } from "./patiently.js";
6
6
  * reads it at that moment. The refusal is brief, so the rename is tried again;
7
7
  * it stays the single commit point.
8
8
  */
9
- export function replaceFile(draft, path) {
10
- return patiently(() => rename(draft, path));
9
+ export function replaceFile(draft, path, clock) {
10
+ return patiently(() => rename(draft, path), { clock });
11
11
  }
12
12
  //# sourceMappingURL=replace-file.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"replace-file.js","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,IAAY;IACrD,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAC9C,CAAC"}
1
+ {"version":3,"file":"replace-file.js","sourceRoot":"","sources":["../src/replace-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAI1C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,IAAY,EAAE,KAAY;IACnE,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;AACzD,CAAC"}
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@zukhruf/fs",
3
- "version": "0.6.13",
4
- "description": "File writes that a reader never sees half done: replace a file in one step, with or without a sync to disk, or create it only when absent. A file lock that the kernel frees when its holder dies. Retries Windows' short refusals. Names a file after any key.",
3
+ "version": "0.6.15",
4
+ "description": "File writes a reader never sees half done, a file lock the kernel frees when its holder dies, and a file stamp that tells that a file changed, as git does. Retries Windows' short refusals. Names a file after any key.",
5
5
  "license": "MIT",
6
6
  "repository": {
7
7
  "type": "git",
@@ -25,7 +25,10 @@
25
25
  "flock",
26
26
  "sqlite",
27
27
  "windows",
28
- "eperm"
28
+ "eperm",
29
+ "stat",
30
+ "file-stamp",
31
+ "change-detection"
29
32
  ],
30
33
  "type": "module",
31
34
  "exports": {
@@ -46,7 +49,10 @@
46
49
  "publishConfig": {
47
50
  "access": "public"
48
51
  },
52
+ "dependencies": {
53
+ "@zukhruf/async": "^0.6.15"
54
+ },
49
55
  "devDependencies": {
50
- "@zukhruf/testing": "^0.6.13"
56
+ "@zukhruf/testing": "^0.6.15"
51
57
  }
52
58
  }