@visulima/fs 5.0.0-alpha.8 → 5.0.0-alpha.9

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

@@ -1,39 +0,0 @@
-/**
- * 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
-     */
-    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

@@ -1,47 +0,0 @@
-/**
- * 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
-     */
-    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

@@ -1,52 +0,0 @@
-/**
- * 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

@@ -1,51 +0,0 @@
-/**
- * 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
-     */
-    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

@@ -1,44 +0,0 @@
-/**
- * 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
-     */
-    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

@@ -1,45 +0,0 @@
-/**
- * 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
-     */
-    constructor(message: string);
-    get code(): string;
-    set code(_name: string);
-    get name(): string;
-    set name(_name: string);
-}
-export default PermissionError;

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

@@ -1,51 +0,0 @@
-/**
- * Error thrown in walk or walkSync during iteration.
- * @example
- * ```javascript
- * import { WalkError } from "@visulima/fs/error";
- * import { walk } from "@visulima/fs";
- * import { join } from "node:path";
- *
- * const processDirectory = async () => {
- *   const dirToWalk = join("/tmp", "non-existent-or-permission-denied-dir");
- *   try {
- *     // Forcing the scenario: walk might throw a WalkError if it encounters an issue
- *     // like a directory it cannot read during the walk process.
- *     const simulateWalkError = async (rootDir) => {
- *       // Let's say readdir inside walk fails for a subdirectory.
- *       const underlyingError = new Error("Permission denied reading subdirectory");
- *       throw new WalkError(underlyingError, rootDir);
- *     }
- *     // This is conceptual. In a real scenario, 'walk' itself would throw.
- *     // for await (const entry of walk(dirToWalk)) {
- *     //   console.log(entry.path);
- *     // }
- *     await simulateWalkError(dirToWalk);
- *   } catch (error) {
- *     if (error instanceof WalkError) {
- *       console.error(`Error during directory walk of "${error.root}": ${error.message}`);
- *       if (error.cause) {
- *         console.error(`Underlying cause: ${error.cause}`);
- *       }
- *     } else {
- *       console.error("An unexpected error occurred:", error);
- *     }
- *   }
- * };
- *
- * processDirectory();
- * ```
- */
-declare class WalkError extends Error {
-    /** File path of the root that's being walked. */
-    root: string;
-    /**
-     * Constructs a new instance.
-     * @param cause The underlying error or reason for the walk failure.
-     * @param root The root directory path where the walk operation started or encountered the error.
-     */
-    constructor(cause: unknown, root: string);
-    get name(): string;
-    set name(_name: string);
-}
-export default WalkError;

package/dist/find/collect-sync.d.ts

@@ -1,31 +0,0 @@
-import type { WalkOptions } from "../types.d.ts";
-/**
- * Synchronously collects all file paths within a directory that match the specified criteria.
- * By default, it searches for JavaScript and TypeScript file extensions.
- * @param directory The root directory to start collecting files from.
- * @param options Optional configuration to control the collection process. See {@link WalkOptions}.
- * @returns An array of absolute file paths.
- * @example
- * ```javascript
- * import { collectSync } from "@visulima/fs";
- * import { join } from "node:path";
- *
- * // Collect all .txt and .md files in /tmp/docs, up to 2 levels deep
- * const files = collectSync(join("/tmp", "docs"), {
- *   extensions: ["txt", "md"],
- *   maxDepth: 2,
- *   includeDirs: false, // Only collect files
- * });
- * console.log(files);
- * // Example output: ['/tmp/docs/file1.txt', '/tmp/docs/subdir/report.md']
- *
- * // Collect all .js files, excluding anything in node_modules
- * const jsFiles = collectSync(join("/tmp", "project"), {
- *   extensions: ["js"],
- *   skip: [/node_modules/],
- * });
- * console.log(jsFiles);
- * ```
- */
-declare const collectSync: (directory: string, options?: WalkOptions) => string[];
-export default collectSync;

package/dist/find/collect.d.ts

@@ -1,35 +0,0 @@
-import type { WalkOptions } from "../types.d.ts";
-/**
- * Asynchronously collects all file paths within a directory that match the specified criteria.
- * By default, it searches for JavaScript and TypeScript file extensions.
- * @param directory The root directory to start collecting files from.
- * @param options Optional configuration to control the collection process. See {@link WalkOptions}.
- * @returns A promise that resolves to an array of absolute file paths.
- * @example
- * ```javascript
- * import { collect } from "@visulima/fs";
- * import { join } from "node:path";
- *
- * const collectFiles = async () => {
- *   // Collect all .txt and .md files in /tmp/docs, up to 2 levels deep
- *   const files = await collect(join("/tmp", "docs"), {
- *     extensions: ["txt", "md"],
- *     maxDepth: 2,
- *     includeDirs: false, // Only collect files
- *   });
- *   console.log(files);
- *   // Example output: ['/tmp/docs/file1.txt', '/tmp/docs/subdir/report.md']
- *
- *   // Collect all .js files, excluding anything in node_modules
- *   const jsFiles = await collect(join("/tmp", "project"), {
- *     extensions: ["js"],
- *     skip: [/node_modules/],
- *   });
- *   console.log(jsFiles);
- * };
- *
- * collectFiles();
- * ```
- */
-declare const collect: (directory: string, options?: WalkOptions) => Promise<string[]>;
-export default collect;

package/dist/find/find-up-sync.d.ts

@@ -1,42 +0,0 @@
-import type { FindUpNameSync, FindUpOptions } from "../types.d.ts";
-/**
- * Synchronously finds a file or directory by walking up parent directories.
- * @param name The name(s) of the file or directory to find. Can be a string, an array of strings, or a function that returns a name or `FIND_UP_STOP`.
- * @param options Optional configuration for the search. See {@link FindUpOptions}.
- * @returns The absolute path of the first found file/directory, or `undefined` if not found.
- * @example
- * ```javascript
- * import { findUpSync } from "@visulima/fs";
- * import { join } from "node:path";
- *
- * // Find the closest package.json, starting from /tmp/foo/bar/baz
- * const projectRoot = findUpSync("package.json", {
- *   cwd: join("/tmp", "foo", "bar", "baz"),
- *   type: "file",
- * });
- * console.log(projectRoot); // e.g., /tmp/foo/package.json or undefined
- *
- * // Find the closest .git directory or a README.md file
- * const gitDirOrReadme = findUpSync([".git", "README.md"], {
- *   cwd: join("/tmp", "foo", "bar"),
- * });
- * console.log(gitDirOrReadme);
- *
- * // Find using a custom function, stopping at /tmp
- * const customFound = findUpSync(
- *   (directory) => {
- *     if (directory === join("/tmp", "foo")) {
- *       return "found-it-here.txt"; // Pretend this file exists in /tmp/foo
- *     }
- *     return undefined;
- *   },
- *   {
- *     cwd: join("/tmp", "foo", "bar", "baz"),
- *     stopAt: join("/tmp"),
- *   }
- * );
- * console.log(customFound);
- * ```
- */
-declare const findUpSync: (name: FindUpNameSync, options?: FindUpOptions) => string | undefined;
-export default findUpSync;

package/dist/find/find-up.d.ts

@@ -1,46 +0,0 @@
-import type { FindUpName, FindUpOptions } from "../types.d.ts";
-/**
- * Asynchronously finds a file or directory by walking up parent directories.
- * @param name The name(s) of the file or directory to find. Can be a string, an array of strings, or a function that returns a name or `FIND_UP_STOP`.
- * @param options Optional configuration for the search. See {@link FindUpOptions}.
- * @returns A promise that resolves to the absolute path of the first found file/directory, or `undefined` if not found.
- * @example
- * ```javascript
- * import { findUp } from "@visulima/fs";
- * import { join } from "node:path";
- *
- * const findProjectRoot = async () => {
- *   // Find the closest package.json, starting from /tmp/foo/bar/baz
- *   const projectRoot = await findUp("package.json", {
- *     cwd: join("/tmp", "foo", "bar", "baz"),
- *     type: "file",
- *   });
- *   console.log(projectRoot); // e.g., /tmp/foo/package.json or undefined
- *
- *   // Find the closest .git directory or a README.md file
- *   const gitDirOrReadme = await findUp([".git", "README.md"], {
- *     cwd: join("/tmp", "foo", "bar"),
- *   });
- *   console.log(gitDirOrReadme);
- *
- *   // Find using a custom function, stopping at /tmp
- *   const customFound = await findUp(
- *     (directory) => {
- *       if (directory === join("/tmp", "foo")) {
- *         return "found-it-here.txt"; // Pretend this file exists in /tmp/foo
- *       }
- *       return undefined;
- *     },
- *     {
- *       cwd: join("/tmp", "foo", "bar", "baz"),
- *       stopAt: join("/tmp"),
- *     }
- *   );
- *   console.log(customFound);
- * };
- *
- * findProjectRoot();
- * ```
- */
-declare const findUp: (name: FindUpName, options?: FindUpOptions) => Promise<string | undefined>;
-export default findUp;

package/dist/find/utils/glob-to-regexp.d.ts

@@ -1,2 +0,0 @@
-declare const globToRegExp: (glob: string) => RegExp;
-export default globToRegExp;

package/dist/find/utils/walk-include.d.ts

@@ -1,2 +0,0 @@
-declare const walkInclude: (path: string, extensions?: string[], match?: RegExp[], skip?: RegExp[]) => boolean;
-export default walkInclude;

package/dist/find/walk-sync.d.ts

@@ -1,34 +0,0 @@
-import type { WalkEntry, WalkOptions } from "../types.d.ts";
-/**
- * Synchronously walks the file tree rooted at `directory`, yielding each file or directory that matches the criteria specified in `options`.
- * This is the synchronous version of the async walk function.
- * @param directory The root directory to start walking from.
- * @param options Optional configuration to control the walking process. See {@link WalkOptions}.
- * @param options.extensions List of file extensions used to filter entries.
- * @param options.followSymlinks Indicates whether symlinks should be resolved or not.
- * @param options.includeDirs Indicates whether directory entries should be included or not.
- * @param options.includeFiles Indicates whether file entries should be included or not.
- * @param options.includeSymlinks Indicates whether symlink entries should be included or not.
- * @param options.match List of regular expression or glob patterns used to filter entries.
- * @param options.maxDepth Maximum depth to walk. Defaults to infinity.
- * @param options.skip List of regular expression or glob patterns used to skip entries.
- * @returns An iterable iterator yielding {@link WalkEntry} objects for each matching file or directory.
- * @example
- * ```javascript
- * import { walkSync } from "@visulima/fs";
- * import { join } from "node:path";
- *
- * // Walk through /tmp/my-project, looking for .ts files, max depth 2
- * for (const entry of walkSync(join("/tmp", "my-project"), { extensions: ["ts"], maxDepth: 2 })) {
- *   console.log(`Found: ${entry.path} (Type: ${entry.isFile() ? 'file' : 'directory'})`);
- * }
- *
- * // Walk, including only directories, and skip any node_modules folders
- * for (const entry of walkSync(join("/tmp", "another-project"), { includeFiles: false, skip: [/node_modules/] })) {
- *   if (entry.isDirectory()) {
- *      console.log(`Directory: ${entry.path}`);
- *   }
- * }
- * ```
- */
-export default function walkSync(directory: URL | string, { extensions, followSymlinks, includeDirs: includeDirectories, includeFiles, includeSymlinks, match, maxDepth, skip, }?: WalkOptions): IterableIterator<WalkEntry>;

package/dist/find/walk.d.ts

@@ -1,37 +0,0 @@
-import type { WalkEntry, WalkOptions } from "../types.d.ts";
-/**
- * Asynchronously walks the file tree rooted at `directory`, yielding each file or directory that matches the criteria specified in `options`.
- * @param directory The root directory to start walking from.
- * @param options Optional configuration to control the walking process. See {@link WalkOptions}.
- * @param options.extensions List of file extensions used to filter entries.
- * @param options.followSymlinks Indicates whether symlinks should be resolved or not.
- * @param options.includeDirs Indicates whether directory entries should be included or not.
- * @param options.includeFiles Indicates whether file entries should be included or not.
- * @param options.includeSymlinks Indicates whether symlink entries should be included or not.
- * @param options.match List of regular expression or glob patterns used to filter entries.
- * @param options.maxDepth Maximum depth to walk. Defaults to infinity.
- * @param options.skip List of regular expression or glob patterns used to skip entries.
- * @returns An async iterable iterator yielding {@link WalkEntry} objects for each matching file or directory.
- * @example
- * ```javascript
- * import { walk } from "@visulima/fs";
- * import { join } from "node:path";
- *
- * const printEntries = async () => {
- *   // Walk through /tmp/my-project, looking for .ts files, max depth 2
- *   for await (const entry of walk(join("/tmp", "my-project"), { extensions: ["ts"], maxDepth: 2 })) {
- *     console.log(`Found: ${entry.path} (Type: ${entry.isFile() ? 'file' : 'directory'})`);
- *   }
- *
- *   // Walk, including only directories, and skip any node_modules folders
- *   for await (const entry of walk(join("/tmp", "another-project"), { includeFiles: false, skip: [/node_modules/] })) {
- *     if (entry.isDirectory()) {
- *        console.log(`Directory: ${entry.path}`);
- *     }
- *   }
- * };
- *
- * printEntries();
- * ```
- */
-export default function walk(directory: URL | string, { extensions, followSymlinks, includeDirs: includeDirectories, includeFiles, includeSymlinks, match, maxDepth, skip, }?: WalkOptions): AsyncIterableIterator<WalkEntry>;

package/dist/is-accessible-sync.d.ts

@@ -1,3 +0,0 @@
-/** Returns a boolean indicating if the path is accessible or not. */
-declare function isAccessibleSync(path: URL | string, mode?: number): boolean;
-export default isAccessibleSync;

package/dist/is-accessible.d.ts

@@ -1,29 +0,0 @@
-/**
- * Asynchronously tests a user's permissions for the file or directory specified by path.
- * Returns a Promise that resolves to `true` if the accessibility check is successful, `false` otherwise.
- * @param path The path to the file or directory. Can be a string or a URL object.
- * @param mode The accessibility checks to perform. Defaults to `F_OK` (check for existence).
- * Other possible values include `R_OK` (check for read access), `W_OK` (check for write access),
- * and `X_OK` (check for execute/search access). Multiple modes can be combined using bitwise OR.
- * @returns A Promise that resolves to a boolean indicating if the path is accessible with the specified mode.
- * @example
- * ```typescript
- * import { isAccessible, F_OK, R_OK } from "@visulima/fs";
- *
- * (async () => {
- *   if (await isAccessible("myFile.txt")) {
- *     console.log("myFile.txt exists");
- *   }
- *
- *   if (await isAccessible("myFile.txt", R_OK)) {
- *     console.log("myFile.txt is readable");
- *   }
- *
- *   if (await isAccessible("myDirectory", F_OK | R_OK | W_OK)) {
- *     console.log("myDirectory exists, is readable and writable");
- *   }
- * })();
- * ```
- */
-declare function isAccessible(path: URL | string, mode?: number): Promise<boolean>;
-export default isAccessible;