@intellectual-frontiers/system 0.0.0-stage → 0.1.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/src/fs.ts ADDED
@@ -0,0 +1,967 @@
1
+ // Spec: 0001-system FR-002
2
+ /**
3
+ * Files and folders (commons 0005-typescript-runtime FR-020), on `node:fs` alone, so the same code runs on Bun and Node. The functions
4
+ * have short, plain names and shapes (`readTextFile`, `writeTextFile`, `remove`, `mkdir`, `stat`, `readDir`,
5
+ * `makeTempDir`, ...); every failure is thrown as an error of `./errors.ts` (`NotFound`, `AlreadyExists`, ...).
6
+ * The helpers Stolos wrote over them (`exists`, `readTextOr`, `ensureDir`, `writeIfChanged`, `listDirs`, `listFiles`, `walkFiles`) and the
7
+ * setup's `sha256File` are here too.
8
+ *
9
+ * `readDir` is an async iterable, with `chown` and `symlinkSync` (FR-048); `open` and `openSync` give an `FsFile`
10
+ * with no lock, which is `./lock.ts`'s (FR-049); `copy` and `walk` are `@std/fs`'s (FR-050), and `expandGlob` gives the
11
+ * entries a glob of `../kernel/glob.ts` matches, in byte order (FR-058).
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * import { makeTempDir, readTextFile, remove, writeTextFile } from "./fs.ts";
16
+ * const dir = await makeTempDir({ prefix: "example-" });
17
+ * await writeTextFile(`${dir}/a.txt`, "hello");
18
+ * await readTextFile(`${dir}/a.txt`); // "hello"
19
+ * await remove(dir, { recursive: true });
20
+ * ```
21
+ *
22
+ * @module
23
+ */
24
+ import { Buffer } from "node:buffer";
25
+ import { createHash } from "node:crypto";
26
+ import * as nfs from "node:fs";
27
+ import * as fsp from "node:fs/promises";
28
+ import { tmpdir } from "node:os";
29
+ import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
30
+ import process from "node:process";
31
+ import { fileURLToPath } from "node:url";
32
+ import { absurd } from "@intellectual-frontiers/core";
33
+ import { formatGlobError, globRoot, globToRegExp, type GlobOptions } from "@intellectual-frontiers/formats/glob";
34
+ import type { Sha256 } from "@intellectual-frontiers/crypto/sha256";
35
+ import { AlreadyExists, hostCall, hostCallSync, InvalidData, NotADirectory, NotFound } from "./errors.ts";
36
+
37
+ /** A path, as a string or a `file:` URL. */
38
+ export type PathLike = string | URL;
39
+
40
+ const p = (path: PathLike): string => (typeof path === "string" ? path : fileURLToPath(path));
41
+
42
+ /** What `stat` knows of a file, by these names. A time the file system does not keep is `null`. */
43
+ export type FileInfo = {
44
+ readonly isFile: boolean;
45
+ readonly isDirectory: boolean;
46
+ readonly isSymlink: boolean;
47
+ readonly size: number;
48
+ readonly mtime: Date | null;
49
+ readonly atime: Date | null;
50
+ readonly birthtime: Date | null;
51
+ readonly ctime: Date | null;
52
+ readonly mode: number | null;
53
+ readonly uid: number | null;
54
+ readonly gid: number | null;
55
+ readonly dev: number;
56
+ readonly ino: number | null;
57
+ readonly nlink: number | null;
58
+ };
59
+
60
+ const time = (ms: number): Date | null => (Number.isFinite(ms) && ms > 0 ? new Date(ms) : null);
61
+
62
+ function info(s: nfs.Stats): FileInfo {
63
+ return {
64
+ isFile: s.isFile(),
65
+ isDirectory: s.isDirectory(),
66
+ isSymlink: s.isSymbolicLink(),
67
+ size: s.size,
68
+ mtime: time(s.mtimeMs),
69
+ atime: time(s.atimeMs),
70
+ birthtime: time(s.birthtimeMs),
71
+ ctime: time(s.ctimeMs),
72
+ mode: process.platform === "win32" ? null : s.mode,
73
+ uid: process.platform === "win32" ? null : s.uid,
74
+ gid: process.platform === "win32" ? null : s.gid,
75
+ dev: s.dev,
76
+ ino: process.platform === "win32" ? null : s.ino,
77
+ nlink: process.platform === "win32" ? null : s.nlink,
78
+ };
79
+ }
80
+
81
+ /** One entry of a folder, by these names. */
82
+ export type DirEntry = { readonly name: string; readonly isFile: boolean; readonly isDirectory: boolean; readonly isSymlink: boolean };
83
+
84
+ const entry = (d: nfs.Dirent): DirEntry => ({
85
+ name: d.name,
86
+ isFile: d.isFile(),
87
+ isDirectory: d.isDirectory(),
88
+ isSymlink: d.isSymbolicLink(),
89
+ });
90
+
91
+ /** How to write a file: append instead of replacing, refuse to make it (`create: false`), refuse where it exists (`createNew`), its mode. */
92
+ export type WriteFileOptions = {
93
+ readonly append?: boolean;
94
+ readonly create?: boolean;
95
+ readonly createNew?: boolean;
96
+ readonly mode?: number;
97
+ };
98
+
99
+ function flag(o: WriteFileOptions): string {
100
+ if (o.createNew === true) return o.append === true ? "ax" : "wx";
101
+ return o.append === true ? "a" : "w";
102
+ }
103
+
104
+ const modeOf = (o: WriteFileOptions): { mode?: number } => (o.mode === undefined ? {} : { mode: o.mode });
105
+
106
+ async function write(path: PathLike, data: string | Uint8Array, o: WriteFileOptions): Promise<void> {
107
+ const file = p(path);
108
+ await hostCall(file, async () => {
109
+ if (o.create === false) await fsp.access(file);
110
+ await fsp.writeFile(file, data, { flag: flag(o), ...modeOf(o) });
111
+ if (o.mode !== undefined && process.platform !== "win32") await fsp.chmod(file, o.mode);
112
+ });
113
+ }
114
+
115
+ function writeSync(path: PathLike, data: string | Uint8Array, o: WriteFileOptions): void {
116
+ const file = p(path);
117
+ hostCallSync(file, () => {
118
+ if (o.create === false) nfs.accessSync(file);
119
+ nfs.writeFileSync(file, data, { flag: flag(o), ...modeOf(o) });
120
+ if (o.mode !== undefined && process.platform !== "win32") nfs.chmodSync(file, o.mode);
121
+ });
122
+ }
123
+
124
+ /** A file's text, read as UTF-8. */
125
+ export function readTextFile(path: PathLike): Promise<string> {
126
+ return hostCall(p(path), () => fsp.readFile(p(path), "utf8"));
127
+ }
128
+
129
+ /** A file's text, read as UTF-8, without waiting. */
130
+ export function readTextFileSync(path: PathLike): string {
131
+ return hostCallSync(p(path), () => nfs.readFileSync(p(path), "utf8"));
132
+ }
133
+
134
+ /** A file's bytes. */
135
+ export async function readFile(path: PathLike): Promise<Uint8Array> {
136
+ const b = await hostCall(p(path), () => fsp.readFile(p(path)));
137
+ return new Uint8Array(b.buffer, b.byteOffset, b.byteLength);
138
+ }
139
+
140
+ /** A file's bytes, without waiting. */
141
+ export function readFileSync(path: PathLike): Uint8Array {
142
+ const b = hostCallSync(p(path), () => nfs.readFileSync(p(path)));
143
+ return new Uint8Array(b.buffer, b.byteOffset, b.byteLength);
144
+ }
145
+
146
+ /** Text written to a file as UTF-8, replacing it unless `append`. */
147
+ export function writeTextFile(path: PathLike, data: string, options: WriteFileOptions = {}): Promise<void> {
148
+ return write(path, data, options);
149
+ }
150
+
151
+ /** Text written to a file as UTF-8, without waiting. */
152
+ export function writeTextFileSync(path: PathLike, data: string, options: WriteFileOptions = {}): void {
153
+ writeSync(path, data, options);
154
+ }
155
+
156
+ /** Bytes written to a file, replacing it unless `append`. */
157
+ export function writeFile(path: PathLike, data: Uint8Array, options: WriteFileOptions = {}): Promise<void> {
158
+ return write(path, data, options);
159
+ }
160
+
161
+ /** Bytes written to a file, without waiting. */
162
+ export function writeFileSync(path: PathLike, data: Uint8Array, options: WriteFileOptions = {}): void {
163
+ writeSync(path, data, options);
164
+ }
165
+
166
+ /** How to remove: a folder and everything in it only with `recursive`. */
167
+ export type RemoveOptions = { readonly recursive?: boolean };
168
+
169
+ /** A file, a link or an empty folder removed; with `recursive`, a folder and everything in it. `NotFound` where nothing is there; the error is of `./errors.ts`. */
170
+ export async function remove(path: PathLike, options: RemoveOptions = {}): Promise<void> {
171
+ const file = p(path);
172
+ await hostCall(file, async () => {
173
+ const s = await fsp.lstat(file);
174
+ if (s.isDirectory()) await (options.recursive === true ? fsp.rm(file, { recursive: true }) : fsp.rmdir(file));
175
+ else await fsp.unlink(file);
176
+ });
177
+ }
178
+
179
+ /** The same, without waiting. */
180
+ export function removeSync(path: PathLike, options: RemoveOptions = {}): void {
181
+ const file = p(path);
182
+ hostCallSync(file, () => {
183
+ const s = nfs.lstatSync(file);
184
+ if (s.isDirectory()) {
185
+ if (options.recursive === true) nfs.rmSync(file, { recursive: true });
186
+ else nfs.rmdirSync(file);
187
+ } else nfs.unlinkSync(file);
188
+ });
189
+ }
190
+
191
+ /** How to make a folder: its parents too (and no error where it exists) with `recursive`, and its mode. */
192
+ export type MkdirOptions = { readonly recursive?: boolean; readonly mode?: number };
193
+
194
+ /** A folder made. */
195
+ export async function mkdir(path: PathLike, options: MkdirOptions = {}): Promise<void> {
196
+ const file = p(path);
197
+ await hostCall(file, () =>
198
+ fsp.mkdir(file, { recursive: options.recursive === true, ...(options.mode === undefined ? {} : { mode: options.mode }) }),
199
+ );
200
+ }
201
+
202
+ /** A folder made, without waiting. */
203
+ export function mkdirSync(path: PathLike, options: MkdirOptions = {}): void {
204
+ const file = p(path);
205
+ hostCallSync(file, () =>
206
+ nfs.mkdirSync(file, { recursive: options.recursive === true, ...(options.mode === undefined ? {} : { mode: options.mode }) }),
207
+ );
208
+ }
209
+
210
+ /** What is at a path, following links. */
211
+ export async function stat(path: PathLike): Promise<FileInfo> {
212
+ return info(await hostCall(p(path), () => fsp.stat(p(path))));
213
+ }
214
+
215
+ /** What is at a path, following links, without waiting. */
216
+ export function statSync(path: PathLike): FileInfo {
217
+ return info(hostCallSync(p(path), () => nfs.statSync(p(path))));
218
+ }
219
+
220
+ /** What is at a path; a link is described, not followed. */
221
+ export async function lstat(path: PathLike): Promise<FileInfo> {
222
+ return info(await hostCall(p(path), () => fsp.lstat(p(path))));
223
+ }
224
+
225
+ /** What is at a path; a link is described, not followed; without waiting. */
226
+ export function lstatSync(path: PathLike): FileInfo {
227
+ return info(hostCallSync(p(path), () => nfs.lstatSync(p(path))));
228
+ }
229
+
230
+ /** The entries of a folder, in the order the file system gives them (FR-048); `NotFound` at the first step where it is not there. */
231
+ export async function* readDir(path: PathLike): AsyncIterable<DirEntry> {
232
+ const dir = p(path);
233
+ const entries = await hostCall(dir, () => fsp.readdir(dir, { withFileTypes: true }));
234
+ for (const d of entries) yield entry(d);
235
+ }
236
+
237
+ /** The entries of a folder, without waiting. */
238
+ export function readDirSync(path: PathLike): DirEntry[] {
239
+ const dir = p(path);
240
+ return hostCallSync(dir, () => nfs.readdirSync(dir, { withFileTypes: true })).map(entry);
241
+ }
242
+
243
+ /** Where and how a temporary file or folder is named: in `dir` (the system's by default), with a `prefix` and `suffix`. */
244
+ export type MakeTempOptions = { readonly dir?: string; readonly prefix?: string; readonly suffix?: string };
245
+
246
+ /** What `mkdtemp` is given: the folder with a separator, then the prefix, so that the random part is added inside the folder and not to its name. */
247
+ const tempBase = (options: MakeTempOptions): string => {
248
+ const dir = options.dir ?? tmpdir();
249
+ return `${dir.endsWith(sep) ? dir : `${dir}${sep}`}${options.prefix ?? ""}`;
250
+ };
251
+
252
+ /** A new, empty, private folder, and its path. */
253
+ export async function makeTempDir(options: MakeTempOptions = {}): Promise<string> {
254
+ const base = tempBase(options);
255
+ const made = await hostCall(base, () => fsp.mkdtemp(base));
256
+ if (options.suffix === undefined || options.suffix === "") return made;
257
+ await hostCall(made, () => fsp.rename(made, `${made}${options.suffix}`));
258
+ return `${made}${options.suffix}`;
259
+ }
260
+
261
+ /** A new, empty, private folder, without waiting. */
262
+ export function makeTempDirSync(options: MakeTempOptions = {}): string {
263
+ const base = tempBase(options);
264
+ return hostCallSync(base, () => nfs.mkdtempSync(base));
265
+ }
266
+
267
+ /** A new, empty, private file, and its path. */
268
+ export async function makeTempFile(options: MakeTempOptions = {}): Promise<string> {
269
+ const dir = options.dir ?? tmpdir();
270
+ for (let i = 0; i < 100; i++) {
271
+ const name = join(dir, `${options.prefix ?? ""}${crypto.randomUUID().slice(0, 12)}${options.suffix ?? ""}`);
272
+ try {
273
+ await hostCall(name, () => fsp.writeFile(name, "", { flag: "wx", mode: 0o600 }));
274
+ return name;
275
+ } catch (e) {
276
+ if (!(e instanceof Error && "code" in e && e.code === "EEXIST")) throw e;
277
+ }
278
+ }
279
+ throw new Error(`no free temporary file name in ${dir}`);
280
+ }
281
+
282
+ /** A file or folder moved to a new path, replacing a file there. */
283
+ export function rename(from: PathLike, to: PathLike): Promise<void> {
284
+ return hostCall(p(from), () => fsp.rename(p(from), p(to)));
285
+ }
286
+
287
+ /** The same, without waiting. */
288
+ export function renameSync(from: PathLike, to: PathLike): void {
289
+ hostCallSync(p(from), () => nfs.renameSync(p(from), p(to)));
290
+ }
291
+
292
+ /** A file's bytes copied to a new path, replacing a file there. */
293
+ export function copyFile(from: PathLike, to: PathLike): Promise<void> {
294
+ return hostCall(p(from), () => fsp.copyFile(p(from), p(to)));
295
+ }
296
+
297
+ /** A file's mode changed (ignored on Windows, which has none). */
298
+ export async function chmod(path: PathLike, mode: number): Promise<void> {
299
+ if (process.platform === "win32") return;
300
+ await hostCall(p(path), () => fsp.chmod(p(path), mode));
301
+ }
302
+
303
+ /** A second name, `to`, for the file at `from` (a hard link), refused with `AlreadyExists` where `to` is taken: a file put in place whole, or not at all. */
304
+ export function link(from: PathLike, to: PathLike): Promise<void> {
305
+ return hostCall(p(to), () => fsp.link(p(from), p(to)));
306
+ }
307
+
308
+ /**
309
+ * A link at `path` that points at `target`; `type` matters on Windows only. `junction` (a folder, FR-073) is the Windows link any account
310
+ * may make (a symbolic link needs administrator rights or Developer Mode there): its target is made absolute, as Windows requires; on
311
+ * Linux and macOS it is an ordinary symbolic link.
312
+ */
313
+ export function symlink(target: PathLike, path: PathLike, options: { readonly type?: "file" | "dir" | "junction" } = {}): Promise<void> {
314
+ return hostCall(p(path), () => fsp.symlink(p(target), p(path), options.type));
315
+ }
316
+
317
+ /** Where a link points, as it was written. */
318
+ export function readLink(path: PathLike): Promise<string> {
319
+ return hostCall(p(path), () => fsp.readlink(p(path)));
320
+ }
321
+
322
+ /** The absolute path with every link followed. */
323
+ export function realPath(path: PathLike): Promise<string> {
324
+ return hostCall(p(path), () => fsp.realpath(p(path)));
325
+ }
326
+
327
+ /** A file cut (or extended with zeros) to `length` bytes, 0 by default. */
328
+ export function truncate(path: PathLike, length = 0): Promise<void> {
329
+ return hostCall(p(path), () => fsp.truncate(p(path), length));
330
+ }
331
+
332
+ /** A file's access and modification times set. */
333
+ export function utime(path: PathLike, atime: Date | number, mtime: Date | number): Promise<void> {
334
+ return hostCall(p(path), () => fsp.utimes(p(path), atime, mtime));
335
+ }
336
+
337
+ /** Whether something is at `path` (a file, folder or link; a broken link counts). An error other than `NotFound` is thrown. */
338
+ export async function exists(path: PathLike): Promise<boolean> {
339
+ try {
340
+ await lstat(path);
341
+ return true;
342
+ } catch (e) {
343
+ if (e instanceof NotFound) return false;
344
+ throw e;
345
+ }
346
+ }
347
+
348
+ /** The same, without waiting. */
349
+ export function existsSync(path: PathLike): boolean {
350
+ try {
351
+ lstatSync(path);
352
+ return true;
353
+ } catch (e) {
354
+ if (e instanceof NotFound) return false;
355
+ throw e;
356
+ }
357
+ }
358
+
359
+ /** A text file's content, or `fallback` (undefined unless given) where nothing is there. Other errors are thrown. */
360
+ export async function readTextOr<F extends string | undefined = undefined>(path: PathLike, fallback?: F): Promise<string | F> {
361
+ try {
362
+ return await readTextFile(path);
363
+ } catch (e) {
364
+ if (e instanceof NotFound) return fallback as F;
365
+ throw e;
366
+ }
367
+ }
368
+
369
+ /** A folder and its parents made, where missing. */
370
+ export function ensureDir(path: PathLike): Promise<void> {
371
+ return mkdir(path, { recursive: true });
372
+ }
373
+
374
+ /**
375
+ * A text file written only where its content changed, in one step (a file beside it renamed over it, so a reader never sees half of it),
376
+ * its folder made where missing. Whether it was written.
377
+ */
378
+ export async function writeIfChanged(path: PathLike, content: string): Promise<boolean> {
379
+ const file = p(path);
380
+ if ((await readTextOr(file)) === content) return false;
381
+ await ensureDir(dirname(file));
382
+ const tmp = `${file}.${crypto.randomUUID().slice(0, 8)}.tmp`;
383
+ await writeTextFile(tmp, content);
384
+ try {
385
+ await rename(tmp, file);
386
+ } catch (e) {
387
+ await remove(tmp).catch(() => {});
388
+ throw e;
389
+ }
390
+ return true;
391
+ }
392
+
393
+ async function namesIn(path: PathLike, keep: (e: DirEntry) => boolean): Promise<string[]> {
394
+ const out: string[] = [];
395
+ try {
396
+ for await (const e of readDir(path)) if (keep(e)) out.push(e.name);
397
+ } catch (e) {
398
+ if (!(e instanceof NotFound)) throw e;
399
+ }
400
+ return out.sort();
401
+ }
402
+
403
+ /** The names of the folders directly in `path`, sorted; none where it does not exist. */
404
+ export function listDirs(path: PathLike): Promise<string[]> {
405
+ return namesIn(path, (e) => e.isDirectory);
406
+ }
407
+
408
+ /** The names of the files directly in `path` that end in `suffix`, sorted; none where it does not exist. */
409
+ export function listFiles(path: PathLike, suffix = ""): Promise<string[]> {
410
+ return namesIn(path, (e) => e.isFile && e.name.endsWith(suffix));
411
+ }
412
+
413
+ /** Every file under a folder (links included, not followed), by its path relative to it with `/` between parts, sorted; none where it does not exist. */
414
+ export async function walkFiles(root: PathLike, rel = ""): Promise<string[]> {
415
+ const out: string[] = [];
416
+ const base = p(root);
417
+ try {
418
+ for await (const e of readDir(rel === "" ? base : join(base, rel))) {
419
+ const r = rel === "" ? e.name : `${rel}/${e.name}`;
420
+ if (e.isDirectory) out.push(...(await walkFiles(base, r)));
421
+ else out.push(r);
422
+ }
423
+ } catch (e) {
424
+ if (!(e instanceof NotFound)) throw e;
425
+ }
426
+ return out.sort();
427
+ }
428
+
429
+ /** The SHA-256 of a file, read as a stream so a large file is not held in memory. */
430
+ export async function sha256File(path: PathLike): Promise<Sha256> {
431
+ const file = p(path);
432
+ return await hostCall(
433
+ file,
434
+ () =>
435
+ new Promise<Sha256>((resolve, reject) => {
436
+ const hash = createHash("sha256");
437
+ nfs
438
+ .createReadStream(file)
439
+ .on("error", reject)
440
+ .on("data", (chunk) => hash.update(chunk))
441
+ .on("end", () => resolve(hash.digest("hex") as Sha256));
442
+ }),
443
+ );
444
+ }
445
+
446
+ /** A temporary folder for the length of `f`, removed with everything in it afterwards, whatever `f` does. */
447
+ export async function withTempDir<T>(f: (dir: string) => Promise<T>, options: MakeTempOptions = {}): Promise<T> {
448
+ const dir = await makeTempDir(options);
449
+ try {
450
+ return await f(dir);
451
+ } finally {
452
+ await remove(dir, { recursive: true }).catch(() => {});
453
+ }
454
+ }
455
+
456
+ // FR-048: the rest of the folder calls.
457
+
458
+ /** A file's owner and group changed; `null` keeps one as it is. Ignored on Windows, which has no POSIX owners (FR-018). */
459
+ export async function chown(path: PathLike, uid: number | null, gid: number | null): Promise<void> {
460
+ if (process.platform === "win32") return;
461
+ await hostCall(p(path), () => fsp.chown(p(path), uid ?? -1, gid ?? -1));
462
+ }
463
+
464
+ /** A link at `path` that points at `target`, without waiting; `type` matters on Windows only (`junction`: see `symlink`). */
465
+ export function symlinkSync(target: PathLike, path: PathLike, options: { readonly type?: "file" | "dir" | "junction" } = {}): void {
466
+ hostCallSync(p(path), () => nfs.symlinkSync(p(target), p(path), options.type));
467
+ }
468
+
469
+ // FR-049: a file handle.
470
+
471
+ /** How to open a file, by these names: `read` alone where none is given. `append` writes at the end and implies `write`. */
472
+ export type OpenOptions = {
473
+ readonly read?: boolean;
474
+ readonly write?: boolean;
475
+ readonly append?: boolean;
476
+ readonly truncate?: boolean;
477
+ readonly create?: boolean;
478
+ readonly createNew?: boolean;
479
+ readonly mode?: number;
480
+ };
481
+
482
+ /** Where `seek` counts from: the start of the file, the handle's position, or the end (`start`, `current`, `end`). */
483
+ export type SeekWhence = "start" | "current" | "end";
484
+
485
+ function openFlags(path: string, o: OpenOptions): number {
486
+ const c = nfs.constants;
487
+ const write = o.write === true || o.append === true;
488
+ if (o.read !== true && !write) throw new InvalidData(`open ${path}: none of read, write and append was asked for`, "EINVAL", path);
489
+ if ((o.create === true || o.createNew === true) && !write)
490
+ throw new InvalidData(`open ${path}: create needs write or append`, "EINVAL", path);
491
+ if (o.truncate === true && o.write !== true) throw new InvalidData(`open ${path}: truncate needs write`, "EINVAL", path);
492
+ let f = o.read === true && write ? c.O_RDWR : write ? c.O_WRONLY : c.O_RDONLY;
493
+ if (o.append === true) f |= c.O_APPEND;
494
+ if (o.create === true || o.createNew === true) f |= c.O_CREAT;
495
+ if (o.createNew === true) f |= c.O_EXCL;
496
+ // No O_TRUNC: Bun on Windows refuses O_TRUNC without O_CREAT with EINVAL, so `truncate` cuts the file once it is open (see `cutIfAsked`),
497
+ // the same on every runtime and system.
498
+ return f;
499
+ }
500
+
501
+ /** The file just opened cut to nothing where `truncate` was asked: what O_TRUNC does, done after the open (see {@link openFlags}). */
502
+ async function cutIfAsked(fd: number, path: string, o: OpenOptions): Promise<void> {
503
+ if (o.truncate !== true) return;
504
+ try {
505
+ await hostCall(path, () => new Promise<void>((res, rej) => nfs.ftruncate(fd, 0, (e) => (e === null ? res() : rej(e)))));
506
+ } catch (e) {
507
+ nfs.closeSync(fd);
508
+ throw e;
509
+ }
510
+ }
511
+
512
+ /** The same, without waiting. */
513
+ function cutIfAskedSync(fd: number, path: string, o: OpenOptions): void {
514
+ if (o.truncate !== true) return;
515
+ try {
516
+ hostCallSync(path, () => nfs.ftruncateSync(fd, 0));
517
+ } catch (e) {
518
+ nfs.closeSync(fd);
519
+ throw e;
520
+ }
521
+ }
522
+
523
+ const CHUNK = 64 * 1024;
524
+
525
+ /**
526
+ * An open file: it reads and writes at its position (a handle opened with `append` always writes at the end), `seek`s,
527
+ * `truncate`s, `stat`s and `sync`s, gives its bytes as a web `ReadableStream` and takes them as a `WritableStream` (each closes the file
528
+ * when it ends), and is closed by `close`, `using` or `await using`. It has no lock: one run at a time is `./lock.ts` (FR-039, FR-049).
529
+ * Made by {@link open} and {@link openSync}.
530
+ */
531
+ export class FsFile implements Disposable, AsyncDisposable {
532
+ readonly #fd: number;
533
+ readonly #path: string;
534
+ readonly #append: boolean;
535
+ #pos = 0;
536
+ #closed = false;
537
+ #readable: ReadableStream<Uint8Array> | undefined;
538
+ #writable: WritableStream<Uint8Array> | undefined;
539
+
540
+ /** A handle over an open descriptor; use {@link open} or {@link openSync}. */
541
+ constructor(fd: number, path: string, append: boolean) {
542
+ this.#fd = fd;
543
+ this.#path = path;
544
+ this.#append = append;
545
+ }
546
+
547
+ #fdOpen(): number {
548
+ if (this.#closed) throw new InvalidData(`${this.#path}: the file is closed`, "EBADF", this.#path);
549
+ return this.#fd;
550
+ }
551
+
552
+ /** Bytes read into `buffer` from the position, which moves past them: how many, or `null` at the end of the file. */
553
+ async read(buffer: Uint8Array): Promise<number | null> {
554
+ const fd = this.#fdOpen();
555
+ if (buffer.byteLength === 0) return 0;
556
+ const at = this.#pos;
557
+ const n = await hostCall(
558
+ this.#path,
559
+ () => new Promise<number>((res, rej) => nfs.read(fd, buffer, 0, buffer.byteLength, at, (e, got) => (e === null ? res(got) : rej(e)))),
560
+ );
561
+ if (n === 0) return null;
562
+ this.#pos = at + n;
563
+ return n;
564
+ }
565
+
566
+ /** The same, without waiting. */
567
+ readSync(buffer: Uint8Array): number | null {
568
+ const fd = this.#fdOpen();
569
+ if (buffer.byteLength === 0) return 0;
570
+ const n = hostCallSync(this.#path, () => nfs.readSync(fd, buffer, 0, buffer.byteLength, this.#pos));
571
+ if (n === 0) return null;
572
+ this.#pos += n;
573
+ return n;
574
+ }
575
+
576
+ /** Bytes written at the position (at the end with `append`), which moves past them: how many, which may be fewer than given. */
577
+ async write(data: Uint8Array): Promise<number> {
578
+ const fd = this.#fdOpen();
579
+ // With `append`, no position is given: Linux ignores one on an append handle, but Windows would write there (FR-018).
580
+ const at = this.#append ? null : this.#pos;
581
+ const n = await hostCall(
582
+ this.#path,
583
+ () => new Promise<number>((res, rej) => nfs.write(fd, data, 0, data.byteLength, at, (e, put) => (e === null ? res(put) : rej(e)))),
584
+ );
585
+ this.#pos =
586
+ at === null
587
+ ? (await hostCall(this.#path, () => new Promise<nfs.Stats>((res, rej) => nfs.fstat(fd, (e, s) => (e === null ? res(s) : rej(e))))))
588
+ .size
589
+ : at + n;
590
+ return n;
591
+ }
592
+
593
+ /** The same, without waiting. */
594
+ writeSync(data: Uint8Array): number {
595
+ const fd = this.#fdOpen();
596
+ const at = this.#append ? null : this.#pos;
597
+ const n = hostCallSync(this.#path, () => nfs.writeSync(fd, data, 0, data.byteLength, at));
598
+ this.#pos = at === null ? hostCallSync(this.#path, () => nfs.fstatSync(fd)).size : at + n;
599
+ return n;
600
+ }
601
+
602
+ #seekTo(offset: number, base: number): number {
603
+ const to = base + offset;
604
+ if (!Number.isSafeInteger(to) || to < 0) throw new InvalidData(`${this.#path}: cannot seek to ${String(to)}`, "EINVAL", this.#path);
605
+ this.#pos = to;
606
+ return to;
607
+ }
608
+
609
+ /** The position moved by `offset` from the start, the position or the end; the new position, from the start. */
610
+ async seek(offset: number, whence: SeekWhence = "start"): Promise<number> {
611
+ const fd = this.#fdOpen();
612
+ if (whence !== "end") return this.seekSync(offset, whence);
613
+ const s = await hostCall(
614
+ this.#path,
615
+ () => new Promise<nfs.Stats>((res, rej) => nfs.fstat(fd, (e, st) => (e === null ? res(st) : rej(e)))),
616
+ );
617
+ return this.#seekTo(offset, s.size);
618
+ }
619
+
620
+ /** The same, without waiting. */
621
+ seekSync(offset: number, whence: SeekWhence = "start"): number {
622
+ const fd = this.#fdOpen();
623
+ switch (whence) {
624
+ case "start":
625
+ return this.#seekTo(offset, 0);
626
+ case "current":
627
+ return this.#seekTo(offset, this.#pos);
628
+ case "end":
629
+ return this.#seekTo(offset, hostCallSync(this.#path, () => nfs.fstatSync(fd)).size);
630
+ default:
631
+ return absurd(whence);
632
+ }
633
+ }
634
+
635
+ /** The file cut (or extended with zeros) to `length` bytes, 0 by default; the position is kept. */
636
+ async truncate(length = 0): Promise<void> {
637
+ const fd = this.#fdOpen();
638
+ await hostCall(this.#path, () => new Promise<void>((res, rej) => nfs.ftruncate(fd, length, (e) => (e === null ? res() : rej(e)))));
639
+ }
640
+
641
+ /** The same, without waiting. */
642
+ truncateSync(length = 0): void {
643
+ const fd = this.#fdOpen();
644
+ hostCallSync(this.#path, () => nfs.ftruncateSync(fd, length));
645
+ }
646
+
647
+ /** What the open file is. */
648
+ async stat(): Promise<FileInfo> {
649
+ const fd = this.#fdOpen();
650
+ return info(
651
+ await hostCall(this.#path, () => new Promise<nfs.Stats>((res, rej) => nfs.fstat(fd, (e, s) => (e === null ? res(s) : rej(e))))),
652
+ );
653
+ }
654
+
655
+ /** The same, without waiting. */
656
+ statSync(): FileInfo {
657
+ const fd = this.#fdOpen();
658
+ return info(hostCallSync(this.#path, () => nfs.fstatSync(fd)));
659
+ }
660
+
661
+ /** The file's data and metadata written through to the disk. */
662
+ async sync(): Promise<void> {
663
+ const fd = this.#fdOpen();
664
+ await hostCall(this.#path, () => new Promise<void>((res, rej) => nfs.fsync(fd, (e) => (e === null ? res() : rej(e)))));
665
+ }
666
+
667
+ /** The same, without waiting. */
668
+ syncSync(): void {
669
+ const fd = this.#fdOpen();
670
+ hostCallSync(this.#path, () => nfs.fsyncSync(fd));
671
+ }
672
+
673
+ /** The file's bytes from the position to the end, as a stream that closes the file when it ends or is cancelled. */
674
+ get readable(): ReadableStream<Uint8Array> {
675
+ this.#readable ??= new ReadableStream<Uint8Array>({
676
+ pull: async (controller): Promise<void> => {
677
+ const buffer = new Uint8Array(CHUNK);
678
+ const n = await this.read(buffer);
679
+ if (n === null) {
680
+ this.close();
681
+ controller.close();
682
+ } else controller.enqueue(buffer.subarray(0, n));
683
+ },
684
+ cancel: (): void => this.close(),
685
+ });
686
+ return this.#readable;
687
+ }
688
+
689
+ /** A stream whose chunks are written whole at the position, closing the file when it is closed or aborted. */
690
+ get writable(): WritableStream<Uint8Array> {
691
+ this.#writable ??= new WritableStream<Uint8Array>({
692
+ write: async (chunk): Promise<void> => {
693
+ for (let done = 0; done < chunk.byteLength;) done += await this.write(chunk.subarray(done));
694
+ },
695
+ close: (): void => this.close(),
696
+ abort: (): void => this.close(),
697
+ });
698
+ return this.#writable;
699
+ }
700
+
701
+ /** The file closed; closing it again does nothing. */
702
+ close(): void {
703
+ if (this.#closed) return;
704
+ this.#closed = true;
705
+ hostCallSync(this.#path, () => nfs.closeSync(this.#fd));
706
+ }
707
+
708
+ /** Closed at the end of a `using` block. */
709
+ [Symbol.dispose](): void {
710
+ this.close();
711
+ }
712
+
713
+ /** Closed at the end of an `await using` block. */
714
+ [Symbol.asyncDispose](): Promise<void> {
715
+ this.close();
716
+ return Promise.resolve();
717
+ }
718
+ }
719
+
720
+ const modeArg = (o: OpenOptions): number => (o.mode === undefined ? 0o666 : o.mode);
721
+
722
+ /** A file opened for reading where no options are given. `AlreadyExists` with `createNew`, `NotFound` without `create`. */
723
+ export async function open(path: PathLike, options: OpenOptions = { read: true }): Promise<FsFile> {
724
+ const file = p(path);
725
+ const flags = openFlags(file, options);
726
+ const fd = await hostCall(
727
+ file,
728
+ () => new Promise<number>((res, rej) => nfs.open(file, flags, modeArg(options), (e, d) => (e === null ? res(d) : rej(e)))),
729
+ );
730
+ await cutIfAsked(fd, file, options);
731
+ return new FsFile(fd, file, options.append === true);
732
+ }
733
+
734
+ /** The same, without waiting. */
735
+ export function openSync(path: PathLike, options: OpenOptions = { read: true }): FsFile {
736
+ const file = p(path);
737
+ const flags = openFlags(file, options);
738
+ const fd = hostCallSync(file, () => nfs.openSync(file, flags, modeArg(options)));
739
+ cutIfAskedSync(fd, file, options);
740
+ return new FsFile(fd, file, options.append === true);
741
+ }
742
+
743
+ // FR-050: copy and walk.
744
+
745
+ /** Names in the byte order of their UTF-8, so that an order is the same on every platform and runtime. */
746
+ const byBytes = (a: string, b: string): number => Buffer.compare(Buffer.from(a), Buffer.from(b));
747
+
748
+ /** How to copy: replace what is at the destination (`overwrite`), keep the access and modification times (`preserveTimestamps`). */
749
+ export type CopyOptions = { readonly overwrite?: boolean; readonly preserveTimestamps?: boolean };
750
+
751
+ const lstatOr = async (path: string): Promise<nfs.Stats | undefined> => {
752
+ try {
753
+ return await hostCall(path, () => fsp.lstat(path));
754
+ } catch (e) {
755
+ if (e instanceof NotFound) return undefined;
756
+ throw e;
757
+ }
758
+ };
759
+
760
+ async function copyAny(from: string, to: string, s: nfs.Stats, o: CopyOptions): Promise<void> {
761
+ const there = await lstatOr(to);
762
+ if (there !== undefined && o.overwrite !== true) throw new AlreadyExists(`copy: ${to} already exists`, "EEXIST", to);
763
+ if (s.isDirectory()) {
764
+ if (there !== undefined && !there.isDirectory()) throw new NotADirectory(`copy: ${to} is not a folder, and ${from} is`, "ENOTDIR", to);
765
+ if (there === undefined) await hostCall(to, () => fsp.mkdir(to));
766
+ const names = (await hostCall(from, () => fsp.readdir(from))).sort(byBytes);
767
+ for (const name of names) {
768
+ const child = join(from, name);
769
+ await copyAny(child, join(to, name), await hostCall(child, () => fsp.lstat(child)), o);
770
+ }
771
+ } else if (s.isSymbolicLink()) {
772
+ if (there !== undefined) await hostCall(to, () => fsp.rm(to, { recursive: true }));
773
+ const target = await hostCall(from, () => fsp.readlink(from));
774
+ // Windows makes a link to a folder and to a file differently; elsewhere the type is ignored (FR-018).
775
+ const pointsAtDir = await fsp.stat(from).then(
776
+ (t) => t.isDirectory(),
777
+ () => false,
778
+ );
779
+ await hostCall(to, () => fsp.symlink(target, to, pointsAtDir ? "dir" : "file"));
780
+ if (o.preserveTimestamps === true) await hostCall(to, () => fsp.lutimes(to, s.atime, s.mtime));
781
+ return;
782
+ } else {
783
+ if (there?.isSymbolicLink() === true) await hostCall(to, () => fsp.unlink(to));
784
+ await hostCall(from, () => fsp.copyFile(from, to));
785
+ }
786
+ if (process.platform !== "win32") await hostCall(to, () => fsp.chmod(to, s.mode & 0o7777));
787
+ if (o.preserveTimestamps === true) await hostCall(to, () => fsp.utimes(to, s.atime, s.mtime));
788
+ }
789
+
790
+ /**
791
+ * A file, a link or a folder with everything in it copied, as `@std/fs`'s `copy` does: a link is copied as a link, modes are kept (not on
792
+ * Windows, FR-018), and what is at the destination is `AlreadyExists` unless `overwrite`. A folder cannot be copied into itself.
793
+ */
794
+ export async function copy(from: PathLike, to: PathLike, options: CopyOptions = {}): Promise<void> {
795
+ const src = resolve(p(from));
796
+ const dest = resolve(p(to));
797
+ if (src === dest) throw new InvalidData(`copy: ${src} is both the source and the destination`, "EINVAL", src);
798
+ const s = await hostCall(src, () => fsp.lstat(src));
799
+ const rel = relative(src, dest);
800
+ if (s.isDirectory() && rel !== "" && !rel.startsWith("..") && !isAbsolute(rel)) {
801
+ throw new InvalidData(`copy: ${dest} is inside ${src}`, "EINVAL", dest);
802
+ }
803
+ await copyAny(src, dest, s, options);
804
+ }
805
+
806
+ /** One entry of a walk: what `readDir` gives, with its path (the root's joined with the names, by the platform's separator). */
807
+ export type WalkEntry = DirEntry & { readonly path: string };
808
+
809
+ /**
810
+ * What a walk gives, as `@std/fs`'s `walk` takes it: how deep (`maxDepth`, the root being 0), which kinds (`includeFiles`, `includeDirs`,
811
+ * `includeSymlinks`, all true by default), whether links are followed (`followSymlinks`, false) and then given by their real path
812
+ * (`canonicalize`, true), and which paths: ending in one of `exts`, matching one of `match`, matching none of `skip`. The expressions are
813
+ * tested against the path with `/` between its parts on every platform, so one expression serves Windows too.
814
+ */
815
+ export type WalkOptions = {
816
+ readonly maxDepth?: number;
817
+ readonly includeFiles?: boolean;
818
+ readonly includeDirs?: boolean;
819
+ readonly includeSymlinks?: boolean;
820
+ readonly followSymlinks?: boolean;
821
+ readonly canonicalize?: boolean;
822
+ readonly exts?: readonly string[];
823
+ readonly match?: readonly RegExp[];
824
+ readonly skip?: readonly RegExp[];
825
+ };
826
+
827
+ const slashed = (path: string): string => (sep === "/" ? path : path.split(sep).join("/"));
828
+
829
+ function included(
830
+ path: string,
831
+ exts: readonly string[] | undefined,
832
+ match: readonly RegExp[] | undefined,
833
+ skip: readonly RegExp[] | undefined,
834
+ ): boolean {
835
+ const s = slashed(path);
836
+ if (exts !== undefined && !exts.some((e) => s.endsWith(e))) return false;
837
+ if (match !== undefined && !match.some((r) => s.match(r) !== null)) return false;
838
+ return !(skip !== undefined && skip.some((r) => s.match(r) !== null));
839
+ }
840
+
841
+ async function* walkIn(
842
+ root: string,
843
+ depth: number,
844
+ o: WalkOptions,
845
+ exts: readonly string[] | undefined,
846
+ seen: ReadonlySet<string>,
847
+ ): AsyncGenerator<WalkEntry> {
848
+ const maxDepth = o.maxDepth ?? Number.POSITIVE_INFINITY;
849
+ if (depth > maxDepth) return;
850
+ if (o.includeDirs !== false && included(root, exts, o.match, o.skip)) {
851
+ const s = await hostCall(root, () => fsp.stat(root));
852
+ yield { path: root, name: basename(root), isFile: s.isFile(), isDirectory: s.isDirectory(), isSymlink: false };
853
+ }
854
+ if (depth >= maxDepth || !included(root, undefined, undefined, o.skip)) return;
855
+ const entries = (await hostCall(root, () => fsp.readdir(root, { withFileTypes: true }))).sort((a, b) => byBytes(a.name, b.name));
856
+ for (const d of entries) {
857
+ let path = join(root, d.name);
858
+ let isDirectory = d.isDirectory();
859
+ let isFile = d.isFile();
860
+ let inner = seen;
861
+ if (d.isSymbolicLink()) {
862
+ if (o.followSymlinks !== true) {
863
+ if (o.includeSymlinks !== false && included(path, exts, o.match, o.skip)) yield { path, ...entry(d) };
864
+ continue;
865
+ }
866
+ const real = await hostCall(path, () => fsp.realpath(path));
867
+ // A link back to a folder the walk is inside of would never end; it is given, not entered.
868
+ if (seen.has(real)) {
869
+ if (o.includeSymlinks !== false && included(path, exts, o.match, o.skip)) yield { path, ...entry(d) };
870
+ continue;
871
+ }
872
+ if (o.canonicalize !== false) path = real;
873
+ const t = await hostCall(real, () => fsp.stat(real));
874
+ isDirectory = t.isDirectory();
875
+ isFile = t.isFile();
876
+ if (isDirectory) inner = new Set([...seen, real]);
877
+ } else if (isDirectory && o.followSymlinks === true) inner = new Set([...seen, await hostCall(path, () => fsp.realpath(path))]);
878
+ if (isDirectory) yield* walkIn(path, depth + 1, o, exts, inner);
879
+ else if (o.includeFiles !== false && included(path, exts, o.match, o.skip)) {
880
+ yield { path, name: d.name, isFile, isDirectory, isSymlink: d.isSymbolicLink() };
881
+ }
882
+ }
883
+ }
884
+
885
+ /**
886
+ * Every entry under a folder, as `@std/fs`'s `walk` gives them (see {@link WalkOptions}), depth first and in the byte order of the names at
887
+ * each level, so a walk is the same every time; the root first, where folders are included; a file as the root is the walk's one entry.
888
+ * `NotFound` where the root is not there.
889
+ */
890
+ export async function* walk(root: PathLike, options: WalkOptions = {}): AsyncGenerator<WalkEntry> {
891
+ const exts = options.exts?.map((e) => (e.startsWith(".") ? e : `.${e}`));
892
+ const base = p(root);
893
+ const s = await hostCall(base, () => fsp.stat(base));
894
+ if (!s.isDirectory()) {
895
+ // A file as the root is itself the walk.
896
+ if (options.includeFiles !== false && included(base, exts, options.match, options.skip)) {
897
+ yield { path: base, name: basename(base), isFile: s.isFile(), isDirectory: false, isSymlink: false };
898
+ }
899
+ return;
900
+ }
901
+ const seen = options.followSymlinks === true ? new Set([await hostCall(base, () => fsp.realpath(base))]) : new Set<string>();
902
+ yield* walkIn(base, 0, options, exts, seen);
903
+ }
904
+
905
+ // FR-058: the entries a glob matches.
906
+
907
+ /**
908
+ * How `expandGlob` reads its glob: the folder it is relative to (`root`, the working folder by default), globs whose matches (and all under
909
+ * them) are left out (`exclude`), whether folders are given (`includeDirs`, true) and links followed (`followSymlinks`, false), and the
910
+ * glob's own options (`extended`, `globstar`, `caseInsensitive`).
911
+ */
912
+ export type ExpandGlobOptions = GlobOptions & {
913
+ readonly root?: PathLike;
914
+ readonly exclude?: readonly string[];
915
+ readonly includeDirs?: boolean;
916
+ readonly followSymlinks?: boolean;
917
+ };
918
+
919
+ const regExpOf = (glob: string, o: GlobOptions): RegExp => {
920
+ const r = globToRegExp(glob, o);
921
+ if (r.kind === "err") throw new InvalidData(formatGlobError(r.error), "EINVAL");
922
+ return r.value;
923
+ };
924
+
925
+ /**
926
+ * The entries a glob matches (`src/**\/*.ts`; see `../kernel/glob.ts`), as `@std/fs`'s `expandGlob` gives them, sorted in the byte order of
927
+ * their paths so the result is the same every time. A glob is written with `/`, also on Windows, and may be absolute (`/srv/*.log`,
928
+ * `C:/x/*`); a relative one is read from `root`. Entries are matched by their path relative to where the glob starts. A glob that begins
929
+ * with `!` is refused as `InvalidData`; a folder that is not there has no entries.
930
+ */
931
+ export async function* expandGlob(glob: string, options: ExpandGlobOptions = {}): AsyncGenerator<WalkEntry> {
932
+ const g: GlobOptions = {
933
+ ...(options.extended === undefined ? {} : { extended: options.extended }),
934
+ ...(options.globstar === undefined ? {} : { globstar: options.globstar }),
935
+ ...(options.caseInsensitive === undefined ? {} : { caseInsensitive: options.caseInsensitive }),
936
+ };
937
+ const absolute = isAbsolute(glob);
938
+ const base = absolute ? parse(glob).root : resolve(p(options.root ?? process.cwd()));
939
+ const pattern = absolute ? glob.slice(parse(glob).root.length) : glob;
940
+ const re = regExpOf(pattern, g);
941
+ const excluded = (options.exclude ?? []).map((x) => regExpOf(x, g));
942
+ const start = resolve(base, globRoot(pattern));
943
+ const rest = slashed(relative(base, start))
944
+ .split("/")
945
+ .filter((s) => s !== "").length;
946
+ const segments = pattern.split("/").filter((s) => s !== "");
947
+ const deep = segments.some((s) => s.includes("**")) || pattern.includes("{");
948
+ const out: { readonly rel: string; readonly e: WalkEntry }[] = [];
949
+ const walkOptions: WalkOptions = {
950
+ includeDirs: options.includeDirs !== false,
951
+ followSymlinks: options.followSymlinks === true,
952
+ canonicalize: false,
953
+ ...(deep ? {} : { maxDepth: Math.max(0, segments.length - rest) }),
954
+ };
955
+ try {
956
+ for await (const e of walk(start, walkOptions)) {
957
+ const rel = slashed(relative(base, e.path));
958
+ if (rel === "" || !re.test(rel)) continue;
959
+ const parts = rel.split("/");
960
+ if (excluded.some((x) => parts.some((_, i) => x.test(parts.slice(0, i + 1).join("/"))))) continue;
961
+ out.push({ rel, e });
962
+ }
963
+ } catch (e) {
964
+ if (!(e instanceof NotFound)) throw e;
965
+ }
966
+ for (const x of out.sort((a, b) => byBytes(a.rel, b.rel))) yield x.e;
967
+ }