@zukhruf/fs 0.8.20 → 0.8.22
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/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/temporary-files.d.ts +23 -0
- package/dist/temporary-files.d.ts.map +1 -0
- package/dist/temporary-files.js +35 -0
- package/dist/temporary-files.js.map +1 -0
- package/package.json +4 -7
package/README.md
CHANGED
|
@@ -222,6 +222,29 @@ console.log(stamps.modifiedAt); // the newest write of the files that are presen
|
|
|
222
222
|
|
|
223
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
224
|
|
|
225
|
+
## Make a temporary directory
|
|
226
|
+
|
|
227
|
+
`new TemporaryFiles().directory(prefix)` makes an empty directory in `os.tmpdir()`. Its name starts with `prefix`. The handle has `path` and `cleanup`. Disposal removes the directory and all that it holds.
|
|
228
|
+
|
|
229
|
+
```ts
|
|
230
|
+
import { join } from 'node:path';
|
|
231
|
+
|
|
232
|
+
import { TemporaryFiles } from '@zukhruf/fs';
|
|
233
|
+
|
|
234
|
+
await using scratch = await new TemporaryFiles().directory('report-');
|
|
235
|
+
await writeReport(join(scratch.path, 'report.json'));
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
`directorySync(prefix)` does the same for code that cannot wait, such as a synchronous `Symbol.dispose`. Its handle is `Disposable`, so it goes with `using`.
|
|
239
|
+
|
|
240
|
+
`path` is the real path: the acquisition resolves symbolic links. On macOS, `os.tmpdir()` is below `/var`, and `/var` is a link to `/private/var`. git, a child process and a bind mount give the resolved path. Thus code can compare their output with `path` directly.
|
|
241
|
+
|
|
242
|
+
On Windows, a process that still holds a file open stops its removal for a short time. Thus disposal retries the removal on `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY` and `EPERM`. It retries 8 times, and it waits 50 ms longer before each retry: 50 + 100 + … + 400 = 1.8 s at most. A removal that does not fail does not wait. When the last retry fails, disposal rejects (or, for `directorySync`, throws) with the error. Node's own `mkdtempDisposable` does not retry, and it gives the path as you wrote it.
|
|
243
|
+
|
|
244
|
+
The only option is `parent`, the directory that holds the new directory. The default is `os.tmpdir()`. Give a parent on the disk of a file that you rename out of the directory, because a rename across two disks fails with `EXDEV`. A Unix socket path has a limit of 104 bytes on macOS and 108 bytes on Linux. On macOS, the real path of `os.tmpdir()` uses 56 of them. Thus give a short parent, such as `/tmp`, for a socket. Node resolves a package from the parent directories of the file that imports it. Thus give a parent in the repository when a file in the directory imports a package of the repository.
|
|
245
|
+
|
|
246
|
+
[ADR 0006](./docs/adr/0006-a-temporary-directory-retries-its-removal-and-gives-its-real-path.md) records why the directory retries its removal and gives its real path. [Root ADR 0006](../../docs/adr/0006-production-code-and-tests-make-a-temporary-directory-with-temporaryfiles-of-zukhruf-fs.md) records why production code uses it too, and why it has a synchronous form.
|
|
247
|
+
|
|
225
248
|
## Check the error code
|
|
226
249
|
|
|
227
250
|
`isErrno(error, code)` tells if `error` is a Node.js system error with that error code.
|
package/dist/index.d.ts
CHANGED
|
@@ -10,4 +10,5 @@ export { assertLocalDirectory } from './local-directory.ts';
|
|
|
10
10
|
export { NetworkDirectoryError } from './network-directory-error.ts';
|
|
11
11
|
export { patiently } from './patiently.ts';
|
|
12
12
|
export { safeFileName } from './safe-file-name.ts';
|
|
13
|
+
export { type TemporaryDirectory, type TemporaryDirectoryOptions, type TemporaryDirectorySync, TemporaryFiles, } from './temporary-files.ts';
|
|
13
14
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -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,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
|
+
{"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;AACnD,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,cAAc,GACf,MAAM,sBAAsB,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -10,4 +10,5 @@ export { assertLocalDirectory } from "./local-directory.js";
|
|
|
10
10
|
export { NetworkDirectoryError } from "./network-directory-error.js";
|
|
11
11
|
export { patiently } from "./patiently.js";
|
|
12
12
|
export { safeFileName } from "./safe-file-name.js";
|
|
13
|
+
export { TemporaryFiles, } from "./temporary-files.js";
|
|
13
14
|
//# sourceMappingURL=index.js.map
|
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,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
|
+
{"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;AACnD,OAAO,EAIL,cAAc,GACf,MAAM,sBAAsB,CAAC"}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
export interface TemporaryDirectory extends AsyncDisposable {
|
|
2
|
+
/** The real path: symbolic links are resolved. */
|
|
3
|
+
path: string;
|
|
4
|
+
/** Remove the directory and its contents, with retries for a file that is held open. */
|
|
5
|
+
cleanup: () => Promise<void>;
|
|
6
|
+
}
|
|
7
|
+
export interface TemporaryDirectorySync extends Disposable {
|
|
8
|
+
/** The real path: symbolic links are resolved. */
|
|
9
|
+
path: string;
|
|
10
|
+
/** Remove the directory and its contents, with retries for a file that is held open. */
|
|
11
|
+
cleanup: () => void;
|
|
12
|
+
}
|
|
13
|
+
export interface TemporaryDirectoryOptions {
|
|
14
|
+
/** The directory that holds the new directory. Default: `os.tmpdir()`. */
|
|
15
|
+
parent?: string;
|
|
16
|
+
}
|
|
17
|
+
/** Each acquisition owns an empty directory, removed with all that it holds. */
|
|
18
|
+
export declare class TemporaryFiles {
|
|
19
|
+
directory(prefix: string, { parent }?: TemporaryDirectoryOptions): Promise<TemporaryDirectory>;
|
|
20
|
+
/** For code that cannot wait, such as a synchronous `Symbol.dispose`. */
|
|
21
|
+
directorySync(prefix: string, { parent }?: TemporaryDirectoryOptions): TemporaryDirectorySync;
|
|
22
|
+
}
|
|
23
|
+
//# sourceMappingURL=temporary-files.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"temporary-files.d.ts","sourceRoot":"","sources":["../src/temporary-files.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,wFAAwF;IACxF,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,sBAAuB,SAAQ,UAAU;IACxD,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,wFAAwF;IACxF,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,yBAAyB;IACxC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAWD,gFAAgF;AAChF,qBAAa,cAAc;IACnB,SAAS,CACb,MAAM,EAAE,MAAM,EACd,EAAE,MAAiB,EAAE,GAAE,yBAA8B,GACpD,OAAO,CAAC,kBAAkB,CAAC;IAW9B,yEAAyE;IACzE,aAAa,CACX,MAAM,EAAE,MAAM,EACd,EAAE,MAAiB,EAAE,GAAE,yBAA8B,GACpD,sBAAsB;CAU1B"}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { mkdtempSync, realpathSync, rmSync } from 'node:fs';
|
|
2
|
+
import { mkdtemp, realpath, rm } from 'node:fs/promises';
|
|
3
|
+
import { tmpdir } from 'node:os';
|
|
4
|
+
import { join } from 'node:path';
|
|
5
|
+
// Windows refuses to remove a file that another process still holds open, for
|
|
6
|
+
// a short time. rm retries those refusals; Node's own mkdtempDisposable does not.
|
|
7
|
+
const removal = {
|
|
8
|
+
recursive: true,
|
|
9
|
+
force: true,
|
|
10
|
+
maxRetries: 8,
|
|
11
|
+
retryDelay: 50,
|
|
12
|
+
};
|
|
13
|
+
/** Each acquisition owns an empty directory, removed with all that it holds. */
|
|
14
|
+
export class TemporaryFiles {
|
|
15
|
+
async directory(prefix, { parent = tmpdir() } = {}) {
|
|
16
|
+
await using resources = new AsyncDisposableStack();
|
|
17
|
+
const created = await mkdtemp(join(parent, prefix));
|
|
18
|
+
resources.defer(() => rm(created, removal));
|
|
19
|
+
const path = await realpath(created);
|
|
20
|
+
const owned = resources.move();
|
|
21
|
+
const cleanup = () => owned.disposeAsync();
|
|
22
|
+
return { path, cleanup, [Symbol.asyncDispose]: cleanup };
|
|
23
|
+
}
|
|
24
|
+
/** For code that cannot wait, such as a synchronous `Symbol.dispose`. */
|
|
25
|
+
directorySync(prefix, { parent = tmpdir() } = {}) {
|
|
26
|
+
using resources = new DisposableStack();
|
|
27
|
+
const created = mkdtempSync(join(parent, prefix));
|
|
28
|
+
resources.defer(() => rmSync(created, removal));
|
|
29
|
+
const path = realpathSync(created);
|
|
30
|
+
const owned = resources.move();
|
|
31
|
+
const cleanup = () => owned.dispose();
|
|
32
|
+
return { path, cleanup, [Symbol.dispose]: cleanup };
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
//# sourceMappingURL=temporary-files.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"temporary-files.js","sourceRoot":"","sources":["../src/temporary-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAqBjC,8EAA8E;AAC9E,kFAAkF;AAClF,MAAM,OAAO,GAAG;IACd,SAAS,EAAE,IAAI;IACf,KAAK,EAAE,IAAI;IACX,UAAU,EAAE,CAAC;IACb,UAAU,EAAE,EAAE;CACN,CAAC;AAEX,gFAAgF;AAChF,MAAM,OAAO,cAAc;IACzB,KAAK,CAAC,SAAS,CACb,MAAc,EACd,EAAE,MAAM,GAAG,MAAM,EAAE,KAAgC,EAAE;QAErD,YAAY,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QACnD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QACpD,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;QACrC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;QAE3C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC;IAC3D,CAAC;IAED,yEAAyE;IACzE,aAAa,CACX,MAAc,EACd,EAAE,MAAM,GAAG,MAAM,EAAE,KAAgC,EAAE;QAErD,MAAM,SAAS,GAAG,IAAI,eAAe,EAAE,CAAC;QACxC,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAClD,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QAChD,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QACnC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QAEtC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACtD,CAAC;CACF"}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zukhruf/fs",
|
|
3
|
-
"version": "0.8.
|
|
4
|
-
"description": "File writes a reader never sees half done, a file lock the kernel frees when its holder dies,
|
|
3
|
+
"version": "0.8.22",
|
|
4
|
+
"description": "File writes a reader never sees half done, a file lock the kernel frees when its holder dies, a file stamp that tells that a file changed, as git does, and a temporary directory at its real path. Retries Windows' short refusals. Names a file by any key.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -50,10 +50,7 @@
|
|
|
50
50
|
"access": "public"
|
|
51
51
|
},
|
|
52
52
|
"dependencies": {
|
|
53
|
-
"@zukhruf/async": "^0.8.
|
|
54
|
-
"@zukhruf/sqlite-open": "^0.8.
|
|
55
|
-
},
|
|
56
|
-
"devDependencies": {
|
|
57
|
-
"@zukhruf/testing": "^0.8.20"
|
|
53
|
+
"@zukhruf/async": "^0.8.22",
|
|
54
|
+
"@zukhruf/sqlite-open": "^0.8.22"
|
|
58
55
|
}
|
|
59
56
|
}
|