@visulima/fs 5.0.0-alpha.2 → 5.0.0-alpha.21

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

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

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

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

@@ -1,23 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

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

@@ -1,3 +0,0 @@
-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

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

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 {@linkcode walk} or {@linkcode 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;