@visulima/fs 4.0.3 → 4.0.5

package/CHANGELOG.md

@@ -1,3 +1,38 @@
+## @visulima/fs [4.0.5](https://github.com/visulima/visulima/compare/@visulima/fs@4.0.4...@visulima/fs@4.0.5) (2025-11-12)
+
+### Bug Fixes
+
+* **deps:** update type-fest dependency across multiple packages ([93e13be](https://github.com/visulima/visulima/commit/93e13be5248207968a96303710db2a0604d16b9b))
+* update package configurations and TypeScript definitions ([b59aa59](https://github.com/visulima/visulima/commit/b59aa59dac1508216b944f4b917fb4a7ab1f70a4))
+
+### Miscellaneous Chores
+
+* Add jsr file to all packages for release ([#565](https://github.com/visulima/visulima/issues/565)) ([ec91652](https://github.com/visulima/visulima/commit/ec91652b4e4112adf14ba152c1239a7703ba425a))
+* update license files and clean up TypeScript definitions ([fe668cc](https://github.com/visulima/visulima/commit/fe668cc26de23591d4df54a0954455ebbe31b22d))
+
+
+### Dependencies
+
+* **@visulima/path:** upgraded to 2.0.4
+* **@visulima/error:** upgraded to 5.0.5
+
+## @visulima/fs [4.0.4](https://github.com/visulima/visulima/compare/@visulima/fs@4.0.3...@visulima/fs@4.0.4) (2025-11-07)
+
+### Bug Fixes
+
+* update TypeScript configurations and improve linting across multiple packages ([6f25ec7](https://github.com/visulima/visulima/commit/6f25ec7841da7246f8f9166efc5292a7089d37ee))
+
+### Miscellaneous Chores
+
+* update npm and pnpm configurations for monorepo optimization ([#564](https://github.com/visulima/visulima/issues/564)) ([5512b42](https://github.com/visulima/visulima/commit/5512b42f672c216b6a3c9e39035199a4ebd9a4b8))
+* update package.json files and pnpm-lock.yaml ([95d9f5b](https://github.com/visulima/visulima/commit/95d9f5b607105d05a006deadb4379e89f06dfe99))
+
+
+### Dependencies
+
+* **@visulima/path:** upgraded to 2.0.3
+* **@visulima/error:** upgraded to 5.0.4
+
 ## @visulima/fs [4.0.3](https://github.com/visulima/visulima/compare/@visulima/fs@4.0.2...@visulima/fs@4.0.3) (2025-11-05)
 
 ### Bug Fixes

package/LICENSE.md

@@ -68,7 +68,7 @@ Repository: git+https://github.com/visulima/visulima.git
 >
 > > MIT License
 > >
-> > Copyright (c) 2024 visulima
+> > Copyright (c) 2025 visulima
 > >
 > > Permission is hereby granted, free of charge, to any person obtaining a copy
 > > of this software and associated documentation files (the "Software"), to deal
@@ -252,11 +252,14 @@ Repository: privatenumber/is-fs-case-sensitive
 <!-- TYPE_DEPENDENCIES -->
 
 # Licenses of bundled types
+
 The published @visulima/fs artifact additionally contains code with the following licenses:
 MIT
 
 # Bundled types:
+
 ## is-fs-case-sensitive
+
 License: MIT
 By: Hiroki Osame
 Repository: privatenumber/is-fs-case-sensitive

package/dist/constants.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Constant to check if the path is visible to the calling process.
+ * Corresponds to `node:fs.constants.F_OK`.
+ */
+export declare const F_OK: number;
+/**
+ * Constant to check if the path is readable to the calling process.
+ * Corresponds to `node:fs.constants.R_OK`.
+ */
+export declare const R_OK: number;
+/**
+ * Constant to check if the path is writable to the calling process.
+ * Corresponds to `node:fs.constants.W_OK`.
+ */
+export declare const W_OK: number;
+/**
+ * Constant to check if the path is executable by the calling process.
+ * Corresponds to `node:fs.constants.X_OK`.
+ */
+export declare const X_OK: number;
+/**
+ * A special symbol that can be returned by the matcher function in `findUp` or `findUpSync`
+ * to stop the search process prematurely.
+ */
+export declare const FIND_UP_STOP: symbol;
+/**
+ * Regular expression for stripping comments from JSON.
+ * Matches:
+ * 1. Quoted strings: "example \"escaped\" string"
+ * 2. Single-line comments: // comment
+ * 3. Multi-line comments: /* comment *\/
+ * @example
+ * const json = `{
+ *   // comment
+ *   "key": "value" // comment
+ * }`;
+ * json.replace(INTERNAL_STRIP_JSON_REGEX, (match) =>
+ *   /^"/.test(match) ? match : ''
+ * );
+ * // Result: { "key": "value" }
+ */
+export declare const INTERNAL_STRIP_JSON_REGEX: RegExp;

package/dist/ensure/ensure-dir-sync.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Ensures that the directory exists.
+ * If the directory structure does not exist, it is created. Like mkdir -p.
+ * @param directory The path to the directory to ensure exists.
+ * @example
+ * ```javascript
+ * import ensureDirSync from "@visulima/fs/ensure/ensure-dir-sync";
+ *
+ * ensureDirSync("/tmp/foo/bar/baz");
+ * // Creates the directory structure /tmp/foo/bar/baz if it doesn't exist
+ * ```
+ */
+declare const ensureDirSync: (directory: URL | string) => void;
+export default ensureDirSync;

package/dist/ensure/ensure-dir.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Ensures that the directory exists.
+ * If the directory structure does not exist, it is created. Like mkdir -p.
+ * @param directory The path to the directory to ensure exists.
+ * @example
+ * ```javascript
+ * import ensureDir from "@visulima/fs/ensure/ensure-dir";
+ *
+ * await ensureDir("/tmp/foo/bar/baz");
+ * // Creates the directory structure /tmp/foo/bar/baz if it doesn't exist
+ * ```
+ */
+declare const ensureDir: (directory: URL | string) => Promise<void>;
+export default ensureDir;

package/dist/ensure/ensure-file-sync.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Ensures that the file exists.
+ * If the file that is requested to be created is in directories that do not exist,
+ * these directories are created. If the file already exists, it is NOT MODIFIED.
+ * @param filePath The path to the file to ensure exists.
+ * @example
+ * ```javascript
+ * import { ensureFileSync } from "@visulima/fs";
+ *
+ * ensureFileSync("/tmp/foo/bar/baz.txt");
+ * // Creates the file /tmp/foo/bar/baz.txt and any missing parent directories if they don't exist
+ * ```
+ */
+declare const ensureFileSync: (filePath: URL | string) => void;
+export default ensureFileSync;

package/dist/ensure/ensure-file.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Asynchronously ensures that a file exists.
+ * If the directory structure for the file does not exist, it is created.
+ * If the file already exists, it is not modified.
+ * @param filePath The path to the file. Can be a string or a URL object.
+ * @returns A Promise that resolves when the file has been created or confirmed to exist.
+ * @throws Will throw an error if the path exists and is not a file.
+ * @throws Will throw an error if directory or file creation fails for reasons other than the path not existing initially.
+ * @example
+ * ```typescript
+ * import { ensureFile } from "@visulima/fs";
+ *
+ * (async () => {
+ *   try {
+ *     await ensureFile("path/to/my/file.txt");
+ *     console.log("File ensured!");
+ *
+ *     await ensureFile(new URL("file:///path/to/another/file.log"));
+ *     console.log("Another file ensured!");
+ *   } catch (error) {
+ *     console.error("Failed to ensure file:", error);
+ *   }
+ * })();
+ * ```
+ */
+declare const ensureFile: (filePath: URL | string) => Promise<void>;
+export default ensureFile;

package/dist/ensure/ensure-link-sync.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Ensures that the hard link exists.
+ * If the directory structure does not exist, it is created.
+ * @param source The path to the source file or directory.
+ * @param destination The path to the destination link.
+ * @example
+ * ```javascript
+ * import { ensureLinkSync } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * // ensure the link /tmp/foo/bar-link.txt points to /tmp/foo/bar.txt
+ * ensureLinkSync(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "bar-link.txt"));
+ * ```
+ */
+declare const ensureLinkSync: (source: URL | string, destination: URL | string) => void;
+export default ensureLinkSync;

package/dist/ensure/ensure-link.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Ensures that the hard link exists.
+ * If the directory structure does not exist, it is created.
+ * @param source The path to the source file or directory.
+ * @param destination The path to the destination link.
+ * @example
+ * ```javascript
+ * import { ensureLink } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * // ensure the link /tmp/foo/bar-link.txt points to /tmp/foo/bar.txt
+ * await ensureLink(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "bar-link.txt"));
+ * ```
+ */
+declare const ensureLink: (source: URL | string, destination: URL | string) => Promise<void>;
+export default ensureLink;

package/dist/ensure/ensure-symlink-sync.d.ts

@@ -0,0 +1,23 @@
+import type { symlink } from "node:fs";
+/**
+ * Ensures that the link exists, and points to a valid file.
+ * If the directory structure does not exist, it is created.
+ * If the link already exists, it is not modified but error is thrown if it is not point to the given target.
+ * @param target the source file path
+ * @param linkName the destination link path
+ * @param type the type of the symlink, or null to use automatic detection
+ * @returns A void.
+ * @example
+ * ```javascript
+ * import { ensureSymlinkSync } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * // Ensure a symlink /tmp/foo/link-to-bar.txt points to /tmp/foo/bar.txt
+ * ensureSymlinkSync(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "link-to-bar.txt"));
+ *
+ * // Ensure a directory symlink /tmp/foo/link-to-baz-dir points to /tmp/foo/baz-dir
+ * ensureSymlinkSync(join("/tmp", "foo", "baz-dir"), join("/tmp", "foo", "link-to-baz-dir"), "dir");
+ * ```
+ */
+declare const ensureSymlinkSync: (target: URL | string, linkName: URL | string, type?: symlink.Type) => void;
+export default ensureSymlinkSync;

package/dist/ensure/ensure-symlink.d.ts

@@ -0,0 +1,23 @@
+import type { symlink as symlinkSync } from "node:fs";
+/**
+ * Ensures that the link exists, and points to a valid file.
+ * If the directory structure does not exist, it is created.
+ * If the link already exists, it is not modified but error is thrown if it is not point to the given target.
+ * @param target the source file path
+ * @param linkName the destination link path
+ * @param type the type of the symlink, or null to use automatic detection
+ * @returns A void promise that resolves once the link exists.
+ * @example
+ * ```javascript
+ * import { ensureSymlink } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * // Ensure a symlink /tmp/foo/link-to-bar.txt points to /tmp/foo/bar.txt
+ * await ensureSymlink(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "link-to-bar.txt"));
+ *
+ * // Ensure a directory symlink /tmp/foo/link-to-baz-dir points to /tmp/foo/baz-dir
+ * await ensureSymlink(join("/tmp", "foo", "baz-dir"), join("/tmp", "foo", "link-to-baz-dir"), "dir");
+ * ```
+ */
+declare const ensureSymlink: (target: URL | string, linkName: URL | string, type?: symlinkSync.Type) => Promise<void>;
+export default ensureSymlink;

package/dist/ensure/utils/get-file-info-type.d.ts

@@ -0,0 +1,7 @@
+import type { Stats } from "node:fs";
+export type PathType = "dir" | "file" | "symlink";
+/**
+ * Get a human-readable file type string.
+ * @param fileInfo A FileInfo describes a file and is returned by `stat`, `lstat`
+ */
+export declare const getFileInfoType: (fileInfo: Stats) => PathType | undefined;

package/dist/ensure/utils/is-stats-identical.d.ts

@@ -0,0 +1,3 @@
+import type { Stats } from "node:fs";
+declare const isStatsIdentical: (sourceStat: Stats, destinationStat: Stats) => boolean;
+export default isStatsIdentical;

package/dist/ensure/utils/resolve-symlink-target.d.ts

@@ -0,0 +1,2 @@
+declare const resolveSymlinkTarget: (target: URL | string, linkName: URL | string) => URL | string;
+export default resolveSymlinkTarget;

package/dist/eol.d.ts

@@ -1,7 +1,35 @@
-declare const LF: "\n";
-declare const CRLF: "\r\n";
-declare const EOL: "\n" | "\r\n";
-declare const detect: (content: string) => typeof EOL | null;
-declare const format: (content: string, eol: typeof EOL) => string;
-
-export { CRLF, EOL, LF, detect, format };
+/** End-of-line character for POSIX platforms such as macOS and Linux. */
+export declare const LF: "\n";
+/** End-of-line character for Windows platforms. */
+export declare const CRLF: "\r\n";
+/**
+ * End-of-line character evaluated for the current platform.
+ */
+export declare const EOL: "\n" | "\r\n";
+/**
+ * Detect the EOL character for string input.
+ * Returns null if no newline.
+ * @param content The string content to detect the EOL from.
+ * @example
+ * ```javascript
+ * import { detect } from "@visulima/fs/eol";
+ *
+ * detect("Hello\r\nWorld"); // "\r\n"
+ * detect("Hello\nWorld"); // "\n"
+ * detect("HelloWorld"); // null
+ * ```
+ */
+export declare const detect: (content: string) => typeof EOL | null;
+/**
+ * Format the file to the targeted EOL.
+ * @param content The string content to format.
+ * @param eol The target EOL character.
+ * @example
+ * ```javascript
+ * import { format, LF, CRLF } from "@visulima/fs/eol";
+ *
+ * format("Hello\r\nWorld\nUnix", LF); // "Hello\nWorld\nUnix"
+ * format("Hello\nWorld\r\nWindows", CRLF); // "Hello\r\nWorld\r\nWindows"
+ * ```
+ */
+export declare const format: (content: string, eol: typeof EOL) => string;

package/dist/eol.js

@@ -1,3 +1,26 @@
-var f=Object.defineProperty;var c=(t,e)=>f(t,"name",{value:e,configurable:!0});import{createRequire as u}from"node:module";const h=u(import.meta.url),p=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,{platform:g}=p;var m=Object.defineProperty,n=c((t,e)=>m(t,"name",{value:e,configurable:!0}),"r");const s=/\r?\n/g,l=`
-`,r=`\r
-`,b=g==="win32"?r:l,j=n(t=>{const e=t.match(s);if(!e||e.length===0)return null;const o=e.filter(i=>i===r).length,a=e.length-o;return o>a?r:l},"detect"),q=n((t,e)=>t.replaceAll(s,e),"format");export{r as CRLF,b as EOL,l as LF,j as detect,q as format};
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const {
+  platform
+} = __cjs_getProcess;
+
+const regDetect = /\r?\n/g;
+const LF = "\n";
+const CRLF = "\r\n";
+const EOL = platform === "win32" ? CRLF : LF;
+const detect = (content) => {
+  const matched = content.match(regDetect);
+  if (!matched || matched.length === 0) {
+    return null;
+  }
+  const crlf = matched.filter((newline) => newline === CRLF).length;
+  const lf = matched.length - crlf;
+  return crlf > lf ? CRLF : LF;
+};
+const format = (content, eol) => content.replaceAll(regDetect, eol);
+
+export { CRLF, EOL, LF, detect, format };

package/dist/error/already-exists-error.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Error thrown when a file or directory already exists at a specified path, and an operation was expecting it not to.
+ * @example
+ * ```javascript
+ * import { AlreadyExistsError } from "@visulima/fs/error"; // Assuming it's exported from an index or directly
+ * import { ensureSymlinkSync } from "@visulima/fs"; // Or any function that might throw this
+ * import { join } from "node:path";
+ *
+ * try {
+ *   // Example: ensureSymlinkSync might throw this if a file (not a symlink) already exists at linkName
+ *   // For demonstration, let's assume someFunction internally throws it:
+ *   const someFunctionThatMightThrow = (path) => {
+ *      if (path === "/tmp/existing-file.txt") { // Simulate a check
+ *          throw new AlreadyExistsError(`file already exists at '/tmp/existing-file.txt'`);
+ *      }
+ *   }
+ *   someFunctionThatMightThrow("/tmp/existing-file.txt");
+ * } catch (error) {
+ *   if (error instanceof AlreadyExistsError) {
+ *     console.error(`Operation failed because path exists: ${error.message}`);
+ *     console.error(`Error code: ${error.code}`); // EEXIST
+ *   } else {
+ *     console.error("An unexpected error occurred:", error);
+ *   }
+ * }
+ * ```
+ */
+declare class AlreadyExistsError extends Error {
+    /**
+     * Creates a new instance.
+     * @param message The error message.
+     */
+    constructor(message: string);
+    get code(): string;
+    set code(_name: string);
+    get name(): string;
+    set name(_name: string);
+}
+export default AlreadyExistsError;

package/dist/error/directory-error.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Error thrown when an operation that is not allowed on a directory is attempted.
+ * This typically occurs when a file-specific operation is used on a directory path.
+ * @example
+ * ```javascript
+ * import { DirectoryError } from "@visulima/fs/error";
+ * import { readFile } from "@visulima/fs"; // Or any function that might throw this
+ * import { join } from "node:path";
+ *
+ * const attemptToReadFileFromDir = async () => {
+ *   try {
+ *     // Attempting to read a directory as if it were a file
+ *     // This is a conceptual example; readFile might throw a different error first
+ *     // depending on its internal checks, but EISDIR is the underlying system error.
+ *     // Forcing the scenario:
+ *     const pretendReadFileOnDir = (path) => {
+ *       if (path === "/tmp/my-directory") { // Simulate a directory path
+ *         throw new DirectoryError(`read '/tmp/my-directory'`);
+ *       }
+ *     }
+ *     pretendReadFileOnDir("/tmp/my-directory");
+ *     // await readFile(join("/tmp", "my-directory"));
+ *   } catch (error) {
+ *     if (error instanceof DirectoryError) {
+ *       console.error(`Operation failed, path is a directory: ${error.message}`);
+ *       console.error(`Error code: ${error.code}`); // EISDIR
+ *     } else {
+ *       console.error("An unexpected error occurred:", error);
+ *     }
+ *   }
+ * };
+ *
+ * attemptToReadFileFromDir();
+ * ```
+ */
+declare class DirectoryError extends Error {
+    /**
+     * Creates a new instance.
+     * @param message The error message.
+     */
+    constructor(message: string);
+    get code(): string;
+    set code(_name: string);
+    get name(): string;
+    set name(_name: string);
+}
+export default DirectoryError;

package/dist/error/json-error.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Custom error class for handling JSON parsing or related errors.
+ * It can optionally include a file name and a code frame for better debugging.
+ * @example
+ * ```javascript
+ * import { JSONError } from "@visulima/fs/error";
+ * import { readJsonSync } from "@visulima/fs"; // Or any function that might throw this
+ * import { join } from "node:path";
+ *
+ * try {
+ *   // Imagine readJsonSync encounters a malformed JSON file and throws JSONError
+ *   // Forcing the scenario for demonstration:
+ *   const simulateJsonError = (filePath, content) => {
+ *     const err = new JSONError(`Unexpected token '}' at position 15`);
+ *     err.fileName = filePath;
+ *     // A real implementation might generate a code frame using a library
+ *     err.codeFrame = `  13 |   "key": "value",
+ * > 14 |   "anotherKey": "anotherValue",}
+ * |                             ^
+ * 15 |   "lastKey": "end"
+ * `;
+ *     throw err;
+ *   };
+ *
+ *   simulateJsonError(join("path", "to", "corrupted.json"), '{ "key": "value", "anotherKey": "anotherValue",} ');
+ *   // const jsonData = readJsonSync(join("path", "to", "corrupted.json"));
+ * } catch (error) {
+ *   if (error instanceof JSONError) {
+ *     console.error(`JSON Error: ${error.message}`);
+ *     // message property will include fileName and codeFrame if they were set.
+ *     // console.error(`File: ${error.fileName}`);
+ *     // console.error(`Code Frame:\n${error.codeFrame}`);
+ *   } else {
+ *     console.error("An unexpected error occurred:", error);
+ *   }
+ * }
+ * ```
+ */
+declare class JSONError extends Error {
+    #private;
+    fileName: string | undefined;
+    codeFrame: string | undefined;
+    readonly name = "JSONError";
+    /**
+     * Creates a new JSONError instance.
+     * @param message The primary error message.
+     */
+    constructor(message: string);
+    get message(): string;
+    set message(message: string);
+}
+export default JSONError;

package/dist/error/not-empty-error.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Error thrown when a directory is not empty.
+ * @example
+ * ```javascript
+ * import { NotEmptyError } from "@visulima/fs/error";
+ * import { rmdir } from "node:fs/promises"; // Or any fs function that might throw this system error
+ * import { join } from "node:path";
+ *
+ * const attemptToRemoveNonEmptyDir = async () => {
+ *   const dirPath = join("/tmp", "my-non-empty-dir"); // Assume this directory exists and has files
+ *   try {
+ *     // Forcing the scenario for demonstration, as rmdir might throw its own specific error.
+ *     // Node.js fs operations that encounter a non-empty directory when expecting an empty one
+ *     // typically throw an error with code ENOTEMPTY.
+ *     const simulateNotEmpty = (path) => {
+ *       if (path === dirPath) { // Simulate check for non-empty
+ *          throw new NotEmptyError(`rmdir '${dirPath}'`);
+ *       }
+ *     }
+ *     simulateNotEmpty(dirPath);
+ *     // await rmdir(dirPath); // This would likely throw an error with code ENOTEMPTY
+ *   } catch (error) {
+ *     if (error instanceof NotEmptyError) {
+ *       console.error(`Operation failed, directory is not empty: ${error.message}`);
+ *       console.error(`Error code: ${error.code}`); // ENOTEMPTY
+ *     } else {
+ *       console.error("An unexpected error occurred:", error);
+ *     }
+ *   }
+ * };
+ *
+ * // You would need to set up a non-empty directory at /tmp/my-non-empty-dir for a real test
+ * // import { ensureDirSync, writeFileSync } from "@visulima/fs";
+ * // ensureDirSync(dirPath);
+ * // writeFileSync(join(dirPath, "somefile.txt"), "content");
+ *
+ * attemptToRemoveNonEmptyDir();
+ * ```
+ */
+declare class NotEmptyError extends Error {
+    /**
+     * Creates a new instance.
+     * @param message The error message.
+     */
+    constructor(message: string);
+    get code(): string;
+    set code(_name: string);
+    get name(): string;
+    set name(_name: string);
+}
+export default NotEmptyError;

package/dist/error/not-found-error.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Error thrown when a file or directory is not found at a specified path.
+ * @example
+ * ```javascript
+ * import { NotFoundError } from "@visulima/fs/error";
+ * import { readFile } from "@visulima/fs"; // Or any function that might throw this
+ * import { join } from "node:path";
+ *
+ * const tryReadingNonExistentFile = async () => {
+ *   const filePath = join("/tmp", "this-file-does-not-exist.txt");
+ *   try {
+ *     // Forcing the scenario for demonstration, as readFile itself would throw this.
+ *     const simulateNotFound = (path) => {
+ *        if (path === filePath) {
+ *           throw new NotFoundError(`no such file or directory, open '${filePath}'`);
+ *        }
+ *     }
+ *     simulateNotFound(filePath);
+ *     // await readFile(filePath);
+ *   } catch (error) {
+ *     if (error instanceof NotFoundError) {
+ *       console.error(`Operation failed, path not found: ${error.message}`);
+ *       console.error(`Error code: ${error.code}`); // ENOENT
+ *     } else {
+ *       console.error("An unexpected error occurred:", error);
+ *     }
+ *   }
+ * };
+ *
+ * tryReadingNonExistentFile();
+ * ```
+ */
+declare class NotFoundError extends Error {
+    /**
+     * Creates a new instance.
+     * @param message The error message.
+     */
+    constructor(message: string);
+    get code(): string;
+    set code(_name: string);
+    get name(): string;
+    set name(_name: string);
+}
+export default NotFoundError;

package/dist/error/permission-error.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Error thrown when an operation is not permitted due to insufficient privileges
+ * or other access control restrictions.
+ * @example
+ * ```javascript
+ * import { PermissionError } from "@visulima/fs/error";
+ * import { writeFile } from "@visulima/fs"; // Or any function that might throw this
+ * import { join } from "node:path";
+ *
+ * const tryWritingToProtectedFile = async () => {
+ *   const filePath = join("/root", "protected-file.txt"); // A path that typically requires root privileges
+ *   try {
+ *     // Forcing the scenario for demonstration, as writeFile itself would throw this.
+ *     const simulatePermissionError = (path) => {
+ *        if (path === filePath) {
+ *           throw new PermissionError(`open '${filePath}'`);
+ *        }
+ *     }
+ *     simulatePermissionError(filePath);
+ *     // await writeFile(filePath, "test content");
+ *   } catch (error) {
+ *     if (error instanceof PermissionError) {
+ *       console.error(`Operation not permitted: ${error.message}`);
+ *       console.error(`Error code: ${error.code}`); // EPERM
+ *     } else {
+ *       console.error("An unexpected error occurred:", error);
+ *     }
+ *   }
+ * };
+ *
+ * tryWritingToProtectedFile();
+ * ```
+ */
+declare class PermissionError extends Error {
+    /**
+     * Creates a new instance.
+     * @param message The error message.
+     */
+    constructor(message: string);
+    get code(): string;
+    set code(_name: string);
+    get name(): string;
+    set name(_name: string);
+}
+export default PermissionError;