@anabranch/fs 0.1.0

package/esm/fs/dir.js

@@ -0,0 +1,90 @@
+import { readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Source } from "../anabranch/index.js";
+import { _matchGlob } from "./glob_match.js";
+import { nodeErrorToFSError, } from "./errors.js";
+/**
+ * Lists the immediate children of a directory.
+ */
+export function readDir(path) {
+    return Source.from(async function* () {
+        try {
+            const entries = await readdir(path, { withFileTypes: true });
+            for (const entry of entries) {
+                yield {
+                    name: entry.name,
+                    isFile: entry.isFile(),
+                    isDirectory: entry.isDirectory(),
+                    isSymlink: entry.isSymbolicLink(),
+                };
+            }
+        }
+        catch (error) {
+            throw nodeErrorToFSError(error, path);
+        }
+    });
+}
+/**
+ * Recursively walks a directory tree, yielding each entry.
+ */
+export function walk(root, options) {
+    return Source.from(async function* () {
+        const rootPath = root instanceof URL ? fileURLToPath(root) : root;
+        const maxDepth = options?.maxDepth ?? Infinity;
+        const includeFiles = options?.includeFiles ?? true;
+        const includeDirs = options?.includeDirs ?? true;
+        const includeSymlinks = options?.includeSymlinks ?? true;
+        const match = options?.match;
+        const skip = options?.skip;
+        const stack = [[rootPath, 0]];
+        while (stack.length > 0) {
+            const [dirPath, depth] = stack.pop();
+            let entries;
+            try {
+                entries = await readdir(dirPath, { withFileTypes: true });
+            }
+            catch (error) {
+                throw nodeErrorToFSError(error, dirPath);
+            }
+            for (const entry of entries) {
+                const entryPath = join(dirPath, entry.name);
+                const relPath = relative(rootPath, entryPath).replace(/\\/g, "/");
+                const isFile = entry.isFile();
+                const isDirectory = entry.isDirectory();
+                const isSymlink = entry.isSymbolicLink();
+                if (skip && skip.some((r) => r.test(relPath)))
+                    continue;
+                const matchesFilter = !match || match.some((r) => r.test(relPath));
+                const walkEntry = {
+                    name: entry.name,
+                    path: entryPath,
+                    isFile,
+                    isDirectory,
+                    isSymlink,
+                };
+                if (isFile && includeFiles && matchesFilter) {
+                    yield walkEntry;
+                }
+                else if (isDirectory) {
+                    if (includeDirs && matchesFilter) {
+                        yield walkEntry;
+                    }
+                    if (depth < maxDepth) {
+                        stack.push([entryPath, depth + 1]);
+                    }
+                }
+                else if (isSymlink && includeSymlinks && matchesFilter) {
+                    yield walkEntry;
+                }
+            }
+        }
+    });
+}
+/**
+ * Finds all entries under `root` whose relative path matches the glob `pattern`.
+ */
+export function glob(root, pattern, options) {
+    const regex = _matchGlob(pattern);
+    return walk(root, { ...options, match: [regex] });
+}

package/esm/fs/errors.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Structured error types for file-system operations.
+ *
+ * @example
+ * ```ts
+ * import { readTextFile, FSError, FSErrors } from "@anabranch/fs";
+ *
+ * const result = await readTextFile("./config.json").run();
+ * if (result.type === "error") {
+ *   const err = result.error;
+ *   if (err instanceof FSError) {
+ *     console.error(`${err.kind}: ${err.path} - ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class FSError extends Error {
+    readonly kind: string;
+    readonly path: string | URL;
+    constructor(kind: string, path: string | URL, message: string);
+}
+export declare class NotFound extends FSError {
+    constructor(path: string | URL, message: string);
+}
+export declare class AlreadyExists extends FSError {
+    constructor(path: string | URL, message: string);
+}
+export declare class IsDirectory extends FSError {
+    constructor(path: string | URL, message: string);
+}
+export declare class NotDirectory extends FSError {
+    constructor(path: string | URL, message: string);
+}
+export declare class PermissionDenied extends FSError {
+    constructor(path: string | URL, message: string);
+}
+export declare class ReadError extends FSError {
+    constructor(path: string | URL, message: string);
+}
+export declare class WriteError extends FSError {
+    constructor(path: string | URL, message: string);
+}
+export declare class InvalidData extends FSError {
+    readonly cause?: unknown;
+    constructor(path: string | URL, message: string, cause?: unknown);
+}
+export declare class Unknown extends FSError {
+    readonly cause?: unknown;
+    constructor(path: string | URL, message: string, cause?: unknown);
+}
+export declare const FSErrors: {
+    readonly NotFound: typeof NotFound;
+    readonly AlreadyExists: typeof AlreadyExists;
+    readonly IsDirectory: typeof IsDirectory;
+    readonly NotDirectory: typeof NotDirectory;
+    readonly PermissionDenied: typeof PermissionDenied;
+    readonly ReadError: typeof ReadError;
+    readonly WriteError: typeof WriteError;
+    readonly InvalidData: typeof InvalidData;
+    readonly Unknown: typeof Unknown;
+};
+declare function nodeErrorToFSError(error: unknown, path: string | URL): FSError;
+export { nodeErrorToFSError };
+//# sourceMappingURL=errors.d.ts.map

package/esm/fs/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/fs/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,OAAQ,SAAQ,KAAK;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC;gBAEhB,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,EAAE,MAAM;CAK9D;AAED,qBAAa,QAAS,SAAQ,OAAO;gBACvB,IAAI,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,EAAE,MAAM;CAGhD;AAED,qBAAa,aAAc,SAAQ,OAAO;gBAC5B,IAAI,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,EAAE,MAAM;CAGhD;AAED,qBAAa,WAAY,SAAQ,OAAO;gBAC1B,IAAI,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,EAAE,MAAM;CAGhD;AAED,qBAAa,YAAa,SAAQ,OAAO;gBAC3B,IAAI,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,EAAE,MAAM;CAGhD;AAED,qBAAa,gBAAiB,SAAQ,OAAO;gBAC/B,IAAI,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,EAAE,MAAM;CAGhD;AAED,qBAAa,SAAU,SAAQ,OAAO;gBACxB,IAAI,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,EAAE,MAAM;CAGhD;AAED,qBAAa,UAAW,SAAQ,OAAO;gBACzB,IAAI,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,EAAE,MAAM;CAGhD;AAED,qBAAa,WAAY,SAAQ,OAAO;IACtC,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEtB,IAAI,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAIjE;AAED,qBAAa,OAAQ,SAAQ,OAAO;IAClC,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEtB,IAAI,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAIjE;AAED,eAAO,MAAM,QAAQ;;;;;;;;;;CAUX,CAAC;AAEX,iBAAS,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAmBvE;AAED,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/esm/fs/errors.js

@@ -0,0 +1,125 @@
+/**
+ * Structured error types for file-system operations.
+ *
+ * @example
+ * ```ts
+ * import { readTextFile, FSError, FSErrors } from "@anabranch/fs";
+ *
+ * const result = await readTextFile("./config.json").run();
+ * if (result.type === "error") {
+ *   const err = result.error;
+ *   if (err instanceof FSError) {
+ *     console.error(`${err.kind}: ${err.path} - ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
+export class FSError extends Error {
+    constructor(kind, path, message) {
+        super(message);
+        Object.defineProperty(this, "kind", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "path", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.kind = kind;
+        this.path = path;
+    }
+}
+export class NotFound extends FSError {
+    constructor(path, message) {
+        super("NotFound", path, message);
+    }
+}
+export class AlreadyExists extends FSError {
+    constructor(path, message) {
+        super("AlreadyExists", path, message);
+    }
+}
+export class IsDirectory extends FSError {
+    constructor(path, message) {
+        super("IsDirectory", path, message);
+    }
+}
+export class NotDirectory extends FSError {
+    constructor(path, message) {
+        super("NotDirectory", path, message);
+    }
+}
+export class PermissionDenied extends FSError {
+    constructor(path, message) {
+        super("PermissionDenied", path, message);
+    }
+}
+export class ReadError extends FSError {
+    constructor(path, message) {
+        super("ReadError", path, message);
+    }
+}
+export class WriteError extends FSError {
+    constructor(path, message) {
+        super("WriteError", path, message);
+    }
+}
+export class InvalidData extends FSError {
+    constructor(path, message, cause) {
+        super("InvalidData", path, message);
+        Object.defineProperty(this, "cause", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.cause = cause;
+    }
+}
+export class Unknown extends FSError {
+    constructor(path, message, cause) {
+        super("Unknown", path, message);
+        Object.defineProperty(this, "cause", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.cause = cause;
+    }
+}
+export const FSErrors = {
+    NotFound,
+    AlreadyExists,
+    IsDirectory,
+    NotDirectory,
+    PermissionDenied,
+    ReadError,
+    WriteError,
+    InvalidData,
+    Unknown,
+};
+function nodeErrorToFSError(error, path) {
+    const message = error instanceof Error ? error.message : String(error);
+    const nodeError = error;
+    switch (nodeError.code) {
+        case "ENOENT":
+            return new NotFound(path, message);
+        case "EEXIST":
+            return new AlreadyExists(path, message);
+        case "EISDIR":
+            return new IsDirectory(path, message);
+        case "ENOTDIR":
+            return new NotDirectory(path, message);
+        case "EACCES":
+        case "EPERM":
+            return new PermissionDenied(path, message);
+        default:
+            return new Unknown(path, message, error);
+    }
+}
+export { nodeErrorToFSError };

package/esm/fs/glob_match.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Converts a glob pattern string to a `RegExp`.
+ *
+ * Supported syntax:
+ * - `*` — any sequence of non-separator characters
+ * - `**` — any sequence of characters including path separators
+ * - `?` — any single non-separator character
+ * - `{a,b}` — alternatives (may contain nested glob syntax)
+ * - `[abc]` — character classes (passed through verbatim)
+ *
+ * The resulting regex is anchored (`^...$`) and should be tested against
+ * forward-slash-normalised relative paths.
+ */
+export declare function _matchGlob(pattern: string): RegExp;
+//# sourceMappingURL=glob_match.d.ts.map

package/esm/fs/glob_match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob_match.d.ts","sourceRoot":"","sources":["../../src/fs/glob_match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/esm/fs/glob_match.js

@@ -0,0 +1,73 @@
+/**
+ * Converts a glob pattern string to a `RegExp`.
+ *
+ * Supported syntax:
+ * - `*` — any sequence of non-separator characters
+ * - `**` — any sequence of characters including path separators
+ * - `?` — any single non-separator character
+ * - `{a,b}` — alternatives (may contain nested glob syntax)
+ * - `[abc]` — character classes (passed through verbatim)
+ *
+ * The resulting regex is anchored (`^...$`) and should be tested against
+ * forward-slash-normalised relative paths.
+ */
+export function _matchGlob(pattern) {
+    return new RegExp(`^${patternToRegexStr(pattern)}$`);
+}
+function patternToRegexStr(pattern) {
+    const notSep = "[^/]";
+    let regex = "";
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === "*") {
+            if (i + 1 < pattern.length && pattern[i + 1] === "*") {
+                regex += ".*";
+                i += 2;
+                // consume the separator that follows **, e.g. "**/"
+                if (i < pattern.length && (pattern[i] === "/" || pattern[i] === "\\")) {
+                    i++;
+                }
+            }
+            else {
+                regex += `${notSep}*`;
+                i++;
+            }
+        }
+        else if (ch === "?") {
+            regex += notSep;
+            i++;
+        }
+        else if (ch === "{") {
+            const end = pattern.indexOf("}", i + 1);
+            if (end === -1) {
+                regex += "\\{";
+                i++;
+            }
+            else {
+                const alternatives = pattern.slice(i + 1, end).split(",");
+                regex += `(?:${alternatives.map(patternToRegexStr).join("|")})`;
+                i = end + 1;
+            }
+        }
+        else if (ch === "[") {
+            const end = pattern.indexOf("]", i + 1);
+            if (end === -1) {
+                regex += "\\[";
+                i++;
+            }
+            else {
+                regex += pattern.slice(i, end + 1);
+                i = end + 1;
+            }
+        }
+        else {
+            regex += escapeRegexChar(ch);
+            i++;
+        }
+    }
+    return regex;
+}
+function escapeRegexChar(ch) {
+    return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+}

package/esm/fs/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Streaming file-system utilities for the anabranch ecosystem.
+ *
+ * Multi-value operations return a {@link Source} so results can be streamed,
+ * filtered, and transformed with the full anabranch API. Single-value
+ * operations return a {@link Task} for composable error handling.
+ *
+ * @example Read all lines from a file
+ * ```ts
+ * import { readLines } from "@anabranch/fs";
+ *
+ * const { successes } = await readLines("./data.txt").partition();
+ * console.log(successes.join("\n"));
+ * ```
+ *
+ * @example Walk a directory and find TypeScript files
+ * ```ts
+ * import { glob } from "@anabranch/fs";
+ *
+ * const results = await glob("./src", "*.ts").collect();
+ * console.log(results.map((e) => e.path));
+ * ```
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+export { readFile, readJson, readLines, readTextFile } from "./read.js";
+export type { ReadFileError, ReadJsonError } from "./read.js";
+export { writeFile, writeJson, writeTextFile } from "./write.js";
+export type { WriteFileError } from "./write.js";
+export { glob, readDir, walk } from "./dir.js";
+export type { DirError } from "./dir.js";
+export { watch } from "./watch.js";
+export type { WatchError } from "./watch.js";
+export type { DirEntry, FsEvent, GlobOptions, WalkEntry, WalkOptions, WatchOptions, } from "./types.js";
+export { FSError, FSErrors } from "./errors.js";
+export type { AlreadyExists, InvalidData, IsDirectory, NotDirectory, NotFound, PermissionDenied, ReadError, Unknown, WriteError, } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/fs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,sBAAsB,CAAC;AAE9B,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACxE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACjE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EACV,QAAQ,EACR,OAAO,EACP,WAAW,EACX,SAAS,EACT,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EACV,aAAa,EACb,WAAW,EACX,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,gBAAgB,EAChB,SAAS,EACT,OAAO,EACP,UAAU,GACX,MAAM,aAAa,CAAC"}

package/esm/fs/index.js

@@ -0,0 +1,31 @@
+/**
+ * Streaming file-system utilities for the anabranch ecosystem.
+ *
+ * Multi-value operations return a {@link Source} so results can be streamed,
+ * filtered, and transformed with the full anabranch API. Single-value
+ * operations return a {@link Task} for composable error handling.
+ *
+ * @example Read all lines from a file
+ * ```ts
+ * import { readLines } from "@anabranch/fs";
+ *
+ * const { successes } = await readLines("./data.txt").partition();
+ * console.log(successes.join("\n"));
+ * ```
+ *
+ * @example Walk a directory and find TypeScript files
+ * ```ts
+ * import { glob } from "@anabranch/fs";
+ *
+ * const results = await glob("./src", "*.ts").collect();
+ * console.log(results.map((e) => e.path));
+ * ```
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+export { readFile, readJson, readLines, readTextFile } from "./read.js";
+export { writeFile, writeJson, writeTextFile } from "./write.js";
+export { glob, readDir, walk } from "./dir.js";
+export { watch } from "./watch.js";
+export { FSError, FSErrors } from "./errors.js";

package/esm/fs/read.d.ts

@@ -0,0 +1,22 @@
+import { Source, Task } from "../anabranch/index.js";
+import { FSError, FSErrors, type NotFound, type PermissionDenied, type ReadError, type Unknown } from "./errors.js";
+export { FSError, FSErrors };
+/**
+ * Streams lines from a text file one at a time using `node:readline`.
+ */
+export declare function readLines(path: string | URL): Source<string, ReadFileError>;
+/**
+ * Reads an entire file as a UTF-8 string.
+ */
+export declare function readTextFile(path: string | URL): Task<string, ReadFileError>;
+/**
+ * Reads an entire file as a `Uint8Array`.
+ */
+export declare function readFile(path: string | URL): Task<Uint8Array, ReadFileError>;
+/**
+ * Reads a JSON file and parses it, returning the value typed as `T`.
+ */
+export declare function readJson<T>(path: string | URL): Task<T, ReadJsonError>;
+export type ReadFileError = NotFound | PermissionDenied | ReadError | Unknown;
+export type ReadJsonError = NotFound | PermissionDenied | ReadError | InstanceType<typeof FSErrors.InvalidData> | Unknown;
+//# sourceMappingURL=read.d.ts.map

package/esm/fs/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/fs/read.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EACL,OAAO,EACP,QAAQ,EAER,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,OAAO,EACb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAE7B;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAe3E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,GAAG,GAAG,GACjB,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,CAQ7B;AAED;;GAEG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,GAAG,GAAG,GACjB,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CASjC;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,EAAE,aAAa,CAAC,CAkBtE;AAED,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAC;AAE9E,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,gBAAgB,GAChB,SAAS,GACT,YAAY,CAAC,OAAO,QAAQ,CAAC,WAAW,CAAC,GACzC,OAAO,CAAC"}

package/esm/fs/read.js

@@ -0,0 +1,75 @@
+import { createReadStream } from "node:fs";
+import { readFile as fsReadFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { Source, Task } from "../anabranch/index.js";
+import { FSError, FSErrors, nodeErrorToFSError, } from "./errors.js";
+export { FSError, FSErrors };
+/**
+ * Streams lines from a text file one at a time using `node:readline`.
+ */
+export function readLines(path) {
+    return Source.from(async function* () {
+        const stream = createReadStream(path);
+        const rl = createInterface({ input: stream, crlfDelay: Infinity });
+        try {
+            for await (const line of rl) {
+                yield line;
+            }
+        }
+        catch (error) {
+            throw nodeErrorToFSError(error, path);
+        }
+        finally {
+            rl.close();
+            stream.destroy();
+        }
+    });
+}
+/**
+ * Reads an entire file as a UTF-8 string.
+ */
+export function readTextFile(path) {
+    return Task.of(async () => {
+        try {
+            return await fsReadFile(path, "utf8");
+        }
+        catch (error) {
+            throw nodeErrorToFSError(error, path);
+        }
+    });
+}
+/**
+ * Reads an entire file as a `Uint8Array`.
+ */
+export function readFile(path) {
+    return Task.of(async () => {
+        try {
+            const buf = await fsReadFile(path);
+            return new Uint8Array(buf);
+        }
+        catch (error) {
+            throw nodeErrorToFSError(error, path);
+        }
+    });
+}
+/**
+ * Reads a JSON file and parses it, returning the value typed as `T`.
+ */
+export function readJson(path) {
+    return Task.of(async () => {
+        try {
+            const text = await fsReadFile(path, "utf8");
+            try {
+                return JSON.parse(text);
+            }
+            catch (error) {
+                throw new FSErrors.InvalidData(path, error.message, error);
+            }
+        }
+        catch (error) {
+            if (error instanceof FSError)
+                throw error;
+            throw nodeErrorToFSError(error, path);
+        }
+    });
+}

package/esm/fs/types.d.ts

@@ -0,0 +1,67 @@
+/** An entry in a directory listing. */
+export interface DirEntry {
+    /** The entry's file name (not the full path). */
+    name: string;
+    /** Whether the entry is a regular file. */
+    isFile: boolean;
+    /** Whether the entry is a directory. */
+    isDirectory: boolean;
+    /** Whether the entry is a symbolic link. */
+    isSymlink: boolean;
+}
+/** A directory entry with its full path, as yielded by {@link walk} and {@link glob}. */
+export interface WalkEntry extends DirEntry {
+    /** The absolute path to the entry. */
+    path: string;
+}
+/** Options for {@link walk}. */
+export interface WalkOptions {
+    /**
+     * Maximum recursion depth. `0` means only immediate children of root.
+     * @default Infinity
+     */
+    maxDepth?: number;
+    /**
+     * Whether to include regular files in results.
+     * @default true
+     */
+    includeFiles?: boolean;
+    /**
+     * Whether to include directories in results.
+     * @default true
+     */
+    includeDirs?: boolean;
+    /**
+     * Whether to include symbolic links in results.
+     * @default true
+     */
+    includeSymlinks?: boolean;
+    /**
+     * Only yield entries whose path (relative to root) matches at least one pattern.
+     * When omitted all entries are included.
+     */
+    match?: RegExp[];
+    /**
+     * Skip entries whose path (relative to root) matches any of these patterns.
+     */
+    skip?: RegExp[];
+}
+/** Options for {@link glob}. Same as {@link WalkOptions} without `match`. */
+export interface GlobOptions extends Omit<WalkOptions, "match"> {
+}
+/** A file-system change event, as yielded by {@link watch}. */
+export interface FsEvent {
+    /** The type of change. */
+    kind: "create" | "modify" | "remove";
+    /** Absolute paths of the affected files. */
+    paths: string[];
+}
+/** Options for {@link watch}. */
+export interface WatchOptions {
+    /**
+     * Whether to watch subdirectories recursively.
+     * @default true
+     */
+    recursive?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/fs/types.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,MAAM,WAAW,QAAQ;IACvB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,MAAM,EAAE,OAAO,CAAC;IAChB,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,yFAAyF;AACzF,MAAM,WAAW,SAAU,SAAQ,QAAQ;IACzC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gCAAgC;AAChC,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC;CAAG;AAElE,+DAA+D;AAC/D,MAAM,WAAW,OAAO;IACtB,0BAA0B;IAC1B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACrC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,iCAAiC;AACjC,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB"}

package/esm/fs/types.js

@@ -0,0 +1 @@
+export {};

package/esm/fs/watch.d.ts

@@ -0,0 +1,17 @@
+import type { Stream } from "../anabranch/index.js";
+import type { FsEvent, WatchOptions } from "./types.js";
+import { type NotFound, type PermissionDenied } from "./errors.js";
+export type WatchError = NotFound | PermissionDenied;
+/**
+ * Watches `path` for file-system changes, yielding a {@link FsEvent} for each.
+ *
+ * Uses a push-based queue internally so events are never dropped between yields.
+ * Cancel the stream to stop watching (e.g. via `take`, breaking `for await`, or
+ * returning from the generator).
+ *
+ * Note: on some platforms `rename` events cannot distinguish creation from
+ * deletion without a stat check. This implementation infers the kind by
+ * checking whether the file still exists at event time.
+ */
+export declare function watch(path: string | URL, options?: WatchOptions): Stream<FsEvent, WatchError>;
+//# sourceMappingURL=watch.d.ts.map

package/esm/fs/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/fs/watch.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACtB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,gBAAgB,CAAC;AAErD;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CACnB,IAAI,EAAE,MAAM,GAAG,GAAG,EAClB,OAAO,CAAC,EAAE,YAAY,GACrB,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CA0B7B"}