@ac-kit/node 0.1.0

package/dist/fs/escape-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-path.d.ts","sourceRoot":"","sources":["../../src/fs/escape-path.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;AAEzE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU,EAAE,YACqC,CAAC"}

package/dist/fs/escape-path.js

@@ -0,0 +1,20 @@
+import os from "node:os";
+import { escapePosixPath, escapeWin32Path } from "@ac-kit/core";
+/**
+ * Escapes a string to be used as a safe file or directory name.
+ *
+ * It replaces any characters that are not allowed in file or directory names
+ * with an underscore (_). It also ensures that the name does not exceed the
+ * maximum length allowed by the operating system (255 characters).
+ *
+ * On POSIX systems, it replaces / and null characters. On Windows systems, it
+ * replaces < > : " / \ | ? * and control characters (0-31). It also avoids
+ * reserved names like CON, PRN, AUX, NUL, COM1, LPT1, etc.
+ *
+ * @param str The string to escape
+ * @returns The escaped string
+ * @see https://stackoverflow.com/questions/1976007/what-characters-are-forbidden-in-windows-and-linux-directory-names
+ * @see https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits
+ */
+export const escapePath = os.platform() === "win32" ? escapeWin32Path : escapePosixPath;
+//# sourceMappingURL=escape-path.js.map

package/dist/fs/escape-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-path.js","sourceRoot":"","sources":["../../src/fs/escape-path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAIhE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,UAAU,GACtB,EAAE,CAAC,QAAQ,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,eAAe,CAAC"}

package/dist/fs/exists-async.d.ts

@@ -0,0 +1,9 @@
+import { access } from "node:fs/promises";
+/**
+ * Tests whether the given file is visible by the calling process.
+ *
+ * @param path The file path to check for existence.
+ * @returns True if the file is visible by the calling process, false otherwise.
+ */
+export declare function existsAsync(path: Parameters<typeof access>[0]): Promise<boolean>;
+//# sourceMappingURL=exists-async.d.ts.map

package/dist/fs/exists-async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exists-async.d.ts","sourceRoot":"","sources":["../../src/fs/exists-async.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,MAAM,kBAAkB,CAAC;AAErD;;;;;GAKG;AACH,wBAAsB,WAAW,CAChC,IAAI,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,GAChC,OAAO,CAAC,OAAO,CAAC,CAOlB"}

package/dist/fs/exists-async.js

@@ -0,0 +1,17 @@
+import { access, constants } from "node:fs/promises";
+/**
+ * Tests whether the given file is visible by the calling process.
+ *
+ * @param path The file path to check for existence.
+ * @returns True if the file is visible by the calling process, false otherwise.
+ */
+export async function existsAsync(path) {
+    try {
+        await access(path, constants.F_OK);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=exists-async.js.map

package/dist/fs/exists-async.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exists-async.js","sourceRoot":"","sources":["../../src/fs/exists-async.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAChC,IAAkC;IAElC,IAAI,CAAC;QACJ,MAAM,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC"}

package/dist/fs/file-content-equal.d.ts

@@ -0,0 +1,18 @@
+import type { PathLike } from "node:fs";
+export type FileContentEqualOptions = {
+    /** The size of the buffer to use when reading the file (default: 64KiB) */
+    bufferSize?: number;
+    /** An AbortSignal to cancel the operation. */
+    signal?: AbortSignal | null;
+};
+/**
+ * Compares the content of a file with the provided data.
+ *
+ * @param path The path to the file to compare.
+ * @param data The data to compare with the file content.
+ * @param options Options for the file comparison.
+ * @returns True if the file content is equal to the provided data, false
+ *   otherwise.
+ */
+export declare function fileContentEqual(path: PathLike, data: Buffer, options?: FileContentEqualOptions): Promise<boolean>;
+//# sourceMappingURL=file-content-equal.d.ts.map

package/dist/fs/file-content-equal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-content-equal.d.ts","sourceRoot":"","sources":["../../src/fs/file-content-equal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAKxC,MAAM,MAAM,uBAAuB,GAAG;IACrC,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CAC5B,CAAC;AAOF;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACrC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,uBAAuB,GAC/B,OAAO,CAAC,OAAO,CAAC,CAqDlB"}

package/dist/fs/file-content-equal.js

@@ -0,0 +1,50 @@
+import { open, stat } from "node:fs/promises";
+import { BYTES_PER_KIB, defaults } from "@ac-kit/core";
+const DEFAULT_FILE_CONTENT_EQUAL_OPTIONS = {
+    bufferSize: 64 * BYTES_PER_KIB,
+    signal: null,
+};
+/**
+ * Compares the content of a file with the provided data.
+ *
+ * @param path The path to the file to compare.
+ * @param data The data to compare with the file content.
+ * @param options Options for the file comparison.
+ * @returns True if the file content is equal to the provided data, false
+ *   otherwise.
+ */
+export async function fileContentEqual(path, data, options) {
+    const effectiveOptions = defaults(options, DEFAULT_FILE_CONTENT_EQUAL_OPTIONS);
+    if (effectiveOptions.bufferSize <= 0) {
+        throw new Error("The buffer size must be greater than 0.");
+    }
+    const fileStat = await stat(path);
+    if (fileStat.size !== data.length) {
+        return false;
+    }
+    if (fileStat.size === 0) {
+        return true;
+    }
+    const handle = await open(path, "r");
+    let position = 0;
+    try {
+        const buffer = Buffer.alloc(effectiveOptions.bufferSize);
+        do {
+            effectiveOptions.signal?.throwIfAborted();
+            const result = await handle.read(buffer, 0, buffer.length, position);
+            if (result.bytesRead === 0) {
+                break;
+            }
+            const compareResult = buffer.compare(data, position, position + result.bytesRead, 0, result.bytesRead);
+            if (compareResult !== 0) {
+                break;
+            }
+            position += result.bytesRead;
+        } while (position < data.length);
+    }
+    finally {
+        await handle.close();
+    }
+    return position === data.length;
+}
+//# sourceMappingURL=file-content-equal.js.map

package/dist/fs/file-content-equal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-content-equal.js","sourceRoot":"","sources":["../../src/fs/file-content-equal.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAUvD,MAAM,kCAAkC,GAAsC;IAC7E,UAAU,EAAE,EAAE,GAAG,aAAa;IAC9B,MAAM,EAAE,IAAI;CACZ,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,IAAc,EACd,IAAY,EACZ,OAAiC;IAEjC,MAAM,gBAAgB,GAAG,QAAQ,CAChC,OAAO,EACP,kCAAkC,CAClC,CAAC;IAEF,IAAI,gBAAgB,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;QACnC,OAAO,KAAK,CAAC;IACd,CAAC;IAED,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAErC,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;QAEzD,GAAG,CAAC;YACH,gBAAgB,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;YAE1C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAErE,IAAI,MAAM,CAAC,SAAS,KAAK,CAAC,EAAE,CAAC;gBAC5B,MAAM;YACP,CAAC;YAED,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,CACnC,IAAI,EACJ,QAAQ,EACR,QAAQ,GAAG,MAAM,CAAC,SAAS,EAC3B,CAAC,EACD,MAAM,CAAC,SAAS,CAChB,CAAC;YACF,IAAI,aAAa,KAAK,CAAC,EAAE,CAAC;gBACzB,MAAM;YACP,CAAC;YAED,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC;QAC9B,CAAC,QAAQ,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE;IAClC,CAAC;YAAS,CAAC;QACV,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,OAAO,QAAQ,KAAK,IAAI,CAAC,MAAM,CAAC;AACjC,CAAC"}

package/dist/fs/is-directory-async.d.ts

@@ -0,0 +1,11 @@
+import { stat } from "node:fs/promises";
+/**
+ * Tests whether `path` exists and is a directory. An unreadable or missing path
+ * is `false`, never a throw — the caller asked a question, not for the reason
+ * behind the answer.
+ *
+ * @param path The path to check.
+ * @returns True when `path` resolves to a directory.
+ */
+export declare function isDirectoryAsync(path: Parameters<typeof stat>[0]): Promise<boolean>;
+//# sourceMappingURL=is-directory-async.d.ts.map

package/dist/fs/is-directory-async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-directory-async.d.ts","sourceRoot":"","sources":["../../src/fs/is-directory-async.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAExC;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACrC,IAAI,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,OAAO,CAAC,CAMlB"}

package/dist/fs/is-directory-async.js

@@ -0,0 +1,18 @@
+import { stat } from "node:fs/promises";
+/**
+ * Tests whether `path` exists and is a directory. An unreadable or missing path
+ * is `false`, never a throw — the caller asked a question, not for the reason
+ * behind the answer.
+ *
+ * @param path The path to check.
+ * @returns True when `path` resolves to a directory.
+ */
+export async function isDirectoryAsync(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=is-directory-async.js.map

package/dist/fs/is-directory-async.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-directory-async.js","sourceRoot":"","sources":["../../src/fs/is-directory-async.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,IAAgC;IAEhC,IAAI,CAAC;QACJ,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AACF,CAAC"}

package/dist/fs/types.d.ts

@@ -0,0 +1,19 @@
+import type { readFile, writeFile } from "node:fs/promises";
+import { type SetNullable } from "@ac-kit/core";
+/** Options for fs.readFile (excluding `signal`) */
+export type NodeReadFileOptions = SetNullable<Extract<Parameters<typeof readFile>[1], object>, "signal">;
+/** Options for fs.writeFile (excluding `signal`) */
+export type NodeWriteFileOptions = SetNullable<Extract<Parameters<typeof writeFile>[2], object>, "signal">;
+/**
+ * Default options for fs.writeFile from Node.js documentation.
+ *
+ * @see https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback
+ */
+export declare const NODE_WRITE_FILE_DEFAULT_OPTIONS: Required<NodeWriteFileOptions>;
+/**
+ * Default options for fs.readFile from Node.js documentation.
+ *
+ * @see https://nodejs.org/api/fs.html#fs_fs_readfile_path_options_callback
+ */
+export declare const NODE_READ_FILE_DEFAULT_OPTIONS: Required<NodeReadFileOptions>;
+//# sourceMappingURL=types.d.ts.map

package/dist/fs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/fs/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE5D,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,mDAAmD;AACnD,MAAM,MAAM,mBAAmB,GAAG,WAAW,CAC5C,OAAO,CAAC,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAC/C,QAAQ,CACR,CAAC;AAEF,oDAAoD;AACpD,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAC7C,OAAO,CAAC,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAChD,QAAQ,CACR,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,EAAE,QAAQ,CAAC,oBAAoB,CAM1E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,mBAAmB,CAIxE,CAAC"}

package/dist/fs/types.js

@@ -0,0 +1,23 @@
+/**
+ * Default options for fs.writeFile from Node.js documentation.
+ *
+ * @see https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback
+ */
+export const NODE_WRITE_FILE_DEFAULT_OPTIONS = {
+    encoding: null,
+    mode: 0o666,
+    flag: "w",
+    flush: false,
+    signal: null,
+};
+/**
+ * Default options for fs.readFile from Node.js documentation.
+ *
+ * @see https://nodejs.org/api/fs.html#fs_fs_readfile_path_options_callback
+ */
+export const NODE_READ_FILE_DEFAULT_OPTIONS = {
+    encoding: null,
+    flag: "r",
+    signal: null,
+};
+//# sourceMappingURL=types.js.map

package/dist/fs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/fs/types.ts"],"names":[],"mappings":"AAgBA;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAmC;IAC9E,QAAQ,EAAE,IAAI;IACd,IAAI,EAAE,KAAK;IACX,IAAI,EAAE,GAAG;IACT,KAAK,EAAE,KAAK;IACZ,MAAM,EAAE,IAAI;CACZ,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAkC;IAC5E,QAAQ,EAAE,IAAI;IACd,IAAI,EAAE,GAAG;IACT,MAAM,EAAE,IAAI;CACZ,CAAC"}

package/dist/fs/walk-paths.d.ts

@@ -0,0 +1,108 @@
+import type { Dirent } from "node:fs";
+/**
+ * Selects paths during a walk.
+ *
+ * A glob and a regular expression are both tested against the `/`-separated
+ * path relative to the walk's root; a predicate additionally receives the
+ * directory entry, whose kind is already known and costs no extra syscall.
+ *
+ * Only a glob carries depth information. That is what lets
+ * {@link WalkPathsOptions.descend} default itself, and it is why an `include`
+ * predicate costs a full walk: a predicate cannot be asked whether anything
+ * under a directory could match, so nothing can be pruned on its behalf.
+ */
+export type PathFilter = string | RegExp | ((entry: Dirent, path: string) => boolean);
+/** What a walk does when a directory cannot be read. */
+export type UnreadablePolicy = 
+/** Any unreadable directory aborts the walk. */
+"throw"
+/** The root must be readable; an unreadable directory below it is skipped. */
+ | "require-root"
+/** Nothing throws — an unreadable root simply yields nothing. */
+ | "skip";
+export type WalkPathsOptions = {
+    /** Directory the walk starts from, and paths are relative to. Default `"."`. */
+    readonly root?: string | null;
+    /** Yields only the paths matching one of these. Default: every path. */
+    readonly include?: PathFilter | readonly PathFilter[] | null;
+    /**
+     * Drops the matching paths, and never descends into a matching directory.
+     * This is the pruning knob: an excluded subtree costs nothing.
+     */
+    readonly exclude?: PathFilter | readonly PathFilter[] | null;
+    /**
+     * Which directories to descend into.
+     *
+     * Defaults to `true` when any `include` glob contains `**`, and to `false`
+     * otherwise — a regular expression or a predicate says nothing about depth,
+     * so it stays flat. An explicit value always wins over that default.
+     */
+    readonly descend?: boolean | PathFilter | null;
+    /** Hard depth cap; `1` is the root's own entries. Default: unbounded. */
+    readonly maxDepth?: number | null;
+    /**
+     * Descends through symbolic links to directories. Default `false`.
+     *
+     * Enabling it costs a `stat` and a `realpath` per symlink encountered, which
+     * is what makes a link back to an ancestor detectable instead of endless.
+     */
+    readonly followSymlinks?: boolean | null;
+    /** Default `"require-root"`. */
+    readonly unreadable?: UnreadablePolicy | null;
+    readonly signal?: AbortSignal | null;
+};
+export type WalkedPath = {
+    /** Path relative to the root, always `/`-separated. */
+    path: string;
+    entry: Dirent;
+};
+/**
+ * Streams the paths under a directory, filtered by globs, regular expressions
+ * or predicates.
+ *
+ * Paths are yielded relative to the root, `/`-separated on every platform, and
+ * sorted within each directory. Because one traversal tests every filter, a
+ * path is yielded once no matter how many patterns it matches — no
+ * deduplication needed. Stop early by breaking out of the loop; the generator's
+ * cleanup runs as usual.
+ *
+ * Depth comes from the patterns, as it does in a shell: `"*.ts"` stays flat,
+ * `"**\/*.ts"` recurses. {@link WalkPathsOptions.descend} overrides that, and
+ * is the only way to recurse with a regular expression or a predicate.
+ *
+ * Time complexity: one `readdir` per directory descended into, and one filter
+ * test per entry visited. `exclude` is applied before descending, so an
+ * excluded subtree is never read.
+ *
+ * @example
+ * 	Every `.bench.ts` outside `node_modules`
+ * 	```ts
+ * 	for await (const { path } of walkPaths({
+ * 	include: "**\/*.bench.ts",
+ * 	exclude: "**\/node_modules/**",
+ * 	})) {
+ * 	console.log(path);
+ * 	}
+ * 	```
+ *
+ * @example
+ * 	The CPU directories of sysfs, tolerating an absent tree
+ * 	```ts
+ * 	const names = await Array.fromAsync(
+ * 	walkPaths({
+ * 	root: "/sys/devices/system/cpu",
+ * 	include: /^cpu\d+$/,
+ * 	unreadable: "skip",
+ * 	}),
+ * 	(walked) => walked.path,
+ * 	);
+ * 	```
+ *
+ * @param options Root, filters, depth, symlink and error handling. See
+ *   {@link WalkPathsOptions}.
+ * @returns The matching paths, each with the directory entry it came from.
+ * @throws When a directory cannot be read and
+ *   {@link WalkPathsOptions.unreadable} does not tolerate it.
+ */
+export declare function walkPaths(options?: WalkPathsOptions): AsyncGenerator<WalkedPath>;
+//# sourceMappingURL=walk-paths.d.ts.map

package/dist/fs/walk-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk-paths.d.ts","sourceRoot":"","sources":["../../src/fs/walk-paths.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAItC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GACnB,MAAM,GACN,MAAM,GACN,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;AAE9C,wDAAwD;AACxD,MAAM,MAAM,gBAAgB;AAC3B,gDAAgD;AAC9C,OAAO;AACT,8EAA8E;GAC5E,cAAc;AAChB,iEAAiE;GAC/D,MAAM,CAAC;AAEV,MAAM,MAAM,gBAAgB,GAAG;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,SAAS,UAAU,EAAE,GAAG,IAAI,CAAC;IAE7D;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,SAAS,UAAU,EAAE,GAAG,IAAI,CAAC;IAE7D;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAAC;IAE/C,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAElC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAEzC,gCAAgC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAE9C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACxB,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IAEb,KAAK,EAAE,MAAM,CAAC;CACd,CAAC;AAyLF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAuB,SAAS,CAC/B,OAAO,CAAC,EAAE,gBAAgB,GACxB,cAAc,CAAC,UAAU,CAAC,CAmC5B"}

package/dist/fs/walk-paths.js

@@ -0,0 +1,197 @@
+import { readdir, realpath, stat } from "node:fs/promises";
+import { join, matchesGlob, resolve, sep } from "node:path";
+function matchesFilter_(filter, entry, path) {
+    if (typeof filter === "function") {
+        return filter(entry, path);
+    }
+    if (typeof filter === "string") {
+        return matchesGlob(path, filter);
+    }
+    // `search` over `test`: it ignores `lastIndex`, so a caller's `/g` pattern
+    // cannot make the filter stateful.
+    return path.search(filter) !== -1;
+}
+function matchesAny_(filters, entry, path) {
+    for (let index = 0; index < filters.length; index++) {
+        if (matchesFilter_(filters[index], entry, path)) {
+            return true;
+        }
+    }
+    return false;
+}
+function toFilterList_(filter) {
+    if (filter === null || filter === undefined) {
+        return [];
+    }
+    if (typeof filter === "string" ||
+        typeof filter === "function" ||
+        filter instanceof RegExp) {
+        return [filter];
+    }
+    return filter;
+}
+function compareByName_(left, right) {
+    if (left.name < right.name) {
+        return -1;
+    }
+    return left.name > right.name ? 1 : 0;
+}
+/** `null` when the directory is unreadable and the policy tolerates it. */
+async function readEntries_(context, relativeDirectory) {
+    const isRoot = relativeDirectory === "";
+    try {
+        const entries = await readdir(isRoot ? context.root : join(context.root, relativeDirectory), { withFileTypes: true });
+        // Sorted per directory so a walk is reproducible across filesystems.
+        return entries.sort(compareByName_);
+    }
+    catch (error) {
+        if (context.unreadable === "throw" ||
+            (context.unreadable === "require-root" && isRoot)) {
+            throw error;
+        }
+        return null;
+    }
+}
+function shouldDescend_(context, entry, path) {
+    if (typeof context.descend === "boolean") {
+        return context.descend;
+    }
+    return matchesFilter_(context.descend, entry, path);
+}
+/**
+ * The resolved path to descend into, or `null` when the entry is not a
+ * directory, is a link that would loop, or cannot be inspected.
+ */
+async function resolveChildDirectory_(context, entry, path, resolvedDirectory) {
+    if (!entry.isSymbolicLink()) {
+        return entry.isDirectory() ? join(resolvedDirectory, entry.name) : null;
+    }
+    if (!context.followSymlinks) {
+        return null;
+    }
+    const absolute = join(context.root, path);
+    let target;
+    try {
+        if (!(await stat(absolute)).isDirectory()) {
+            return null;
+        }
+        target = await realpath(absolute);
+    }
+    catch (error) {
+        if (context.unreadable === "throw") {
+            throw error;
+        }
+        return null;
+    }
+    // A link resolving to an ancestor would walk its own subtree forever.
+    if (resolvedDirectory === target ||
+        resolvedDirectory.startsWith(target + sep)) {
+        return null;
+    }
+    return target;
+}
+async function* walkDirectory_(context, relativeDirectory, resolvedDirectory, depth) {
+    const entries = await readEntries_(context, relativeDirectory);
+    if (entries === null) {
+        return;
+    }
+    const prefix = relativeDirectory === "" ? "" : `${relativeDirectory}/`;
+    for (const entry of entries) {
+        context.signal?.throwIfAborted();
+        const path = prefix + entry.name;
+        if (matchesAny_(context.exclude, entry, path)) {
+            continue;
+        }
+        if (context.include.length === 0 ||
+            matchesAny_(context.include, entry, path)) {
+            yield { path, entry };
+        }
+        if (depth >= context.maxDepth || !shouldDescend_(context, entry, path)) {
+            continue;
+        }
+        const child = await resolveChildDirectory_(context, entry, path, resolvedDirectory);
+        if (child !== null) {
+            yield* walkDirectory_(context, path, child, depth + 1);
+        }
+    }
+}
+/**
+ * Streams the paths under a directory, filtered by globs, regular expressions
+ * or predicates.
+ *
+ * Paths are yielded relative to the root, `/`-separated on every platform, and
+ * sorted within each directory. Because one traversal tests every filter, a
+ * path is yielded once no matter how many patterns it matches — no
+ * deduplication needed. Stop early by breaking out of the loop; the generator's
+ * cleanup runs as usual.
+ *
+ * Depth comes from the patterns, as it does in a shell: `"*.ts"` stays flat,
+ * `"**\/*.ts"` recurses. {@link WalkPathsOptions.descend} overrides that, and
+ * is the only way to recurse with a regular expression or a predicate.
+ *
+ * Time complexity: one `readdir` per directory descended into, and one filter
+ * test per entry visited. `exclude` is applied before descending, so an
+ * excluded subtree is never read.
+ *
+ * @example
+ * 	Every `.bench.ts` outside `node_modules`
+ * 	```ts
+ * 	for await (const { path } of walkPaths({
+ * 	include: "**\/*.bench.ts",
+ * 	exclude: "**\/node_modules/**",
+ * 	})) {
+ * 	console.log(path);
+ * 	}
+ * 	```
+ *
+ * @example
+ * 	The CPU directories of sysfs, tolerating an absent tree
+ * 	```ts
+ * 	const names = await Array.fromAsync(
+ * 	walkPaths({
+ * 	root: "/sys/devices/system/cpu",
+ * 	include: /^cpu\d+$/,
+ * 	unreadable: "skip",
+ * 	}),
+ * 	(walked) => walked.path,
+ * 	);
+ * 	```
+ *
+ * @param options Root, filters, depth, symlink and error handling. See
+ *   {@link WalkPathsOptions}.
+ * @returns The matching paths, each with the directory entry it came from.
+ * @throws When a directory cannot be read and
+ *   {@link WalkPathsOptions.unreadable} does not tolerate it.
+ */
+export async function* walkPaths(options) {
+    const include = toFilterList_(options?.include);
+    const root = resolve(options?.root ?? ".");
+    const followSymlinks = options?.followSymlinks ?? false;
+    const unreadable = options?.unreadable ?? "require-root";
+    const context = {
+        root,
+        include,
+        exclude: toFilterList_(options?.exclude),
+        descend: options?.descend ??
+            include.some((filter) => typeof filter === "string" && filter.includes("**")),
+        maxDepth: options?.maxDepth ?? Number.POSITIVE_INFINITY,
+        followSymlinks,
+        unreadable,
+        signal: options?.signal ?? null,
+    };
+    // The ancestor check compares resolved paths, so the root has to be one too.
+    let resolvedRoot = root;
+    if (followSymlinks) {
+        try {
+            resolvedRoot = await realpath(root);
+        }
+        catch (error) {
+            if (unreadable !== "skip") {
+                throw error;
+            }
+            return;
+        }
+    }
+    yield* walkDirectory_(context, "", resolvedRoot, 1);
+}
+//# sourceMappingURL=walk-paths.js.map

package/dist/fs/walk-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk-paths.js","sourceRoot":"","sources":["../../src/fs/walk-paths.ts"],"names":[],"mappings":"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"}

package/dist/fs/write-file-atomic.d.ts

@@ -0,0 +1,42 @@
+import { type PathLike } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { type NodeWriteFileOptions } from "./types.js";
+/**
+ * Replaces a file's contents in one step: a reader sees either the previous
+ * contents or the new ones, never a partial write.
+ *
+ * The data goes to a uniquely named temporary file beside the destination,
+ * which is then `rename`d over it. `rename` replaces the destination
+ * atomically, so no window exists in which the path is missing.
+ *
+ * Appending is rejected — `flag: "a"` and `O_APPEND` throw. Staging an append
+ * means copying the destination into the temporary file and appending there,
+ * which silently discards whatever another process wrote in between: the
+ * opposite of what an appender expects. Read, concatenate and replace instead,
+ * serialising the writers yourself when there is more than one:
+ *
+ * ```ts
+ * const current = await readFile(path, "utf8").catch(() => "");
+ * await writeFileAtomic(path, `${current}${line}\n`);
+ * ```
+ *
+ * When the destination already exists its permission bits carry over, unless
+ * `options.mode` says otherwise. Ownership does not: the replacement belongs to
+ * the calling user.
+ *
+ * Durability is a separate concern from atomicity — pass `flush: true` to fsync
+ * the data before the rename. The parent directory is never fsynced, so the
+ * rename itself may still be lost to a power failure.
+ *
+ * @param filePath The path to replace.
+ * @param data The contents to write.
+ * @param options Encoding, mode, flag, flush and abort signal, as for
+ *   `fs.writeFile`. `flag` may only select exclusive creation (`"wx"`,
+ *   `O_EXCL`); appending throws.
+ * @returns A promise that resolves once the destination holds the new contents.
+ * @throws {TypeError} When `options.flag` requests an append.
+ * @throws When the destination exists and `options.flag` is exclusive (`code:
+ *   "EEXIST"`), or when any underlying syscall fails.
+ */
+export declare function writeFileAtomic(filePath: PathLike, data: Parameters<typeof writeFile>[1], options?: NodeWriteFileOptions): ReturnType<typeof writeFile>;
+//# sourceMappingURL=write-file-atomic.d.ts.map

package/dist/fs/write-file-atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-file-atomic.d.ts","sourceRoot":"","sources":["../../src/fs/write-file-atomic.ts"],"names":[],"mappings":"AACA,OAAO,EAAwB,KAAK,QAAQ,EAAc,MAAM,SAAS,CAAC;AAC1E,OAAO,EAA+B,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAM1E,OAAO,EAEN,KAAK,oBAAoB,EACzB,MAAM,YAAY,CAAC;AAwDpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,eAAe,CACpC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,EACrC,OAAO,CAAC,EAAE,oBAAoB,GAC5B,UAAU,CAAC,OAAO,SAAS,CAAC,CAgD9B"}