@zukhruf/fs 0.3.45 → 0.3.47
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 +23 -0
- package/dist/atomic-write.d.ts +8 -2
- package/dist/atomic-write.d.ts.map +1 -1
- package/dist/atomic-write.js +7 -3
- package/dist/atomic-write.js.map +1 -1
- package/dist/durable-write.d.ts +3 -1
- package/dist/durable-write.d.ts.map +1 -1
- package/dist/durable-write.js +5 -4
- package/dist/durable-write.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -32,6 +32,29 @@ Use `durableWrite` when a value must never go back after a crash, for example a
|
|
|
32
32
|
|
|
33
33
|
On Windows, a process cannot open a directory to sync it. Some file systems refuse a sync of a directory with `EINVAL` or `ENOTSUP`. In these cases, the rename is as durable as that system makes it. Each other error of the sync reaches the caller.
|
|
34
34
|
|
|
35
|
+
## Write bytes, and set the mode of the file
|
|
36
|
+
|
|
37
|
+
`atomicWrite` and `durableWrite` take the same arguments:
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
atomicWrite(path: string, content: string | Uint8Array, options?: { mode?: number })
|
|
41
|
+
durableWrite(path: string, content: string | Uint8Array, options?: { mode?: number })
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
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
|
+
|
|
46
|
+
`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.
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
import { randomBytes } from 'node:crypto';
|
|
50
|
+
|
|
51
|
+
import { atomicWrite } from '@zukhruf/fs';
|
|
52
|
+
|
|
53
|
+
await atomicWrite('/var/lib/app/key', randomBytes(32), { mode: 0o600 });
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
On Windows, a file has no POSIX mode. Node.js uses only the write bit of `mode` there, to make the file read-only.
|
|
57
|
+
|
|
35
58
|
## Create a file only when it is absent
|
|
36
59
|
|
|
37
60
|
`createExclusive` creates the file when no file is at the path, and returns `true`. When a file is there, it changes nothing and returns `false`. It fills a draft first and then links the draft to the path. Thus the file is never empty: a reader of the new file sees all of its content.
|
package/dist/atomic-write.d.ts
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
|
-
/**
|
|
2
|
-
|
|
1
|
+
/**
|
|
2
|
+
* Replaces `path` in one step, so readers see the old or the new content, never a partial write.
|
|
3
|
+
* `mode` is set when the draft is created: the rename keeps the draft's mode,
|
|
4
|
+
* so the file never has another mode at the path.
|
|
5
|
+
*/
|
|
6
|
+
export declare function atomicWrite(path: string, content: string | Uint8Array, options?: {
|
|
7
|
+
mode?: number;
|
|
8
|
+
}): Promise<void>;
|
|
3
9
|
//# 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
|
|
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"}
|
package/dist/atomic-write.js
CHANGED
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
import { rm, writeFile } from 'node:fs/promises';
|
|
2
2
|
import { draftOf } from "./draft.js";
|
|
3
3
|
import { replaceFile } from "./replace-file.js";
|
|
4
|
-
/**
|
|
5
|
-
|
|
4
|
+
/**
|
|
5
|
+
* Replaces `path` in one step, so readers see the old or the new content, never a partial write.
|
|
6
|
+
* `mode` is set when the draft is created: the rename keeps the draft's mode,
|
|
7
|
+
* so the file never has another mode at the path.
|
|
8
|
+
*/
|
|
9
|
+
export async function atomicWrite(path, content, options) {
|
|
6
10
|
const draft = draftOf(path);
|
|
7
11
|
try {
|
|
8
|
-
await writeFile(draft, content);
|
|
12
|
+
await writeFile(draft, content, { mode: options?.mode });
|
|
9
13
|
await replaceFile(draft, path);
|
|
10
14
|
}
|
|
11
15
|
catch (error) {
|
package/dist/atomic-write.js.map
CHANGED
|
@@ -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
|
|
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"}
|
package/dist/durable-write.d.ts
CHANGED
|
@@ -3,5 +3,7 @@
|
|
|
3
3
|
* the new content and the replacement survive a power loss: a counter that
|
|
4
4
|
* goes back after a crash would hand out a token twice.
|
|
5
5
|
*/
|
|
6
|
-
export declare function durableWrite(path: string, content: string
|
|
6
|
+
export declare function durableWrite(path: string, content: string | Uint8Array, options?: {
|
|
7
|
+
mode?: number;
|
|
8
|
+
}): Promise<void>;
|
|
7
9
|
//# 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,
|
|
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"}
|
package/dist/durable-write.js
CHANGED
|
@@ -8,10 +8,11 @@ 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) {
|
|
11
|
+
export async function durableWrite(path, content, options) {
|
|
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);
|
|
15
16
|
await replaceFile(draft, path);
|
|
16
17
|
}
|
|
17
18
|
catch (error) {
|
|
@@ -21,8 +22,8 @@ export async function durableWrite(path, content) {
|
|
|
21
22
|
}
|
|
22
23
|
await syncDirectory(dirname(path));
|
|
23
24
|
}
|
|
24
|
-
async function writeSynced(path, content) {
|
|
25
|
-
await using handle = await open(path, 'wx');
|
|
25
|
+
async function writeSynced(path, content, mode) {
|
|
26
|
+
await using handle = await open(path, 'wx', mode);
|
|
26
27
|
await handle.writeFile(content);
|
|
27
28
|
await handle.sync();
|
|
28
29
|
}
|
|
@@ -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,
|
|
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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zukhruf/fs",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.47",
|
|
4
4
|
"description": "File writes that a reader never sees half done: replace a file in one step, with or without a sync to the disk, or create it only when it is absent. A lock on a file that the kernel frees when its holder dies. Also retries the short refusals of Windows, and names a file after any key.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -47,6 +47,6 @@
|
|
|
47
47
|
"access": "public"
|
|
48
48
|
},
|
|
49
49
|
"devDependencies": {
|
|
50
|
-
"@zukhruf/testing": "^0.3.
|
|
50
|
+
"@zukhruf/testing": "^0.3.47"
|
|
51
51
|
}
|
|
52
52
|
}
|