@visulima/fs 5.0.0-alpha.12 → 5.0.0-alpha.13

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## @visulima/fs [5.0.0-alpha.13](https://github.com/visulima/visulima/compare/@visulima/fs@5.0.0-alpha.12...@visulima/fs@5.0.0-alpha.13) (2026-05-04)
+
+### Miscellaneous Chores
+
+* **fs:** upgrade packem to 2.0.0-alpha.76 ([3dfa709](https://github.com/visulima/visulima/commit/3dfa709d723dd74576ce7003c63c11858c1e72e3))
+* re-sort workspace package.json files via vis sort-package-json ([f625696](https://github.com/visulima/visulima/commit/f625696cfac974325774b3243e1a83c3d23acbd7))
+* simplify pnpm-workspace packages list ([7cab221](https://github.com/visulima/visulima/commit/7cab221163632d9b7aa044a6f88c49083103a869))
+
+
+### Dependencies
+
+* **@visulima/error:** upgraded to 6.0.0-alpha.15
+
 ## @visulima/fs [5.0.0-alpha.12](https://github.com/visulima/visulima/compare/@visulima/fs@5.0.0-alpha.11...@visulima/fs@5.0.0-alpha.12) (2026-04-22)
 
 ### Bug Fixes

package/LICENSE.md

@@ -281,14 +281,11 @@ Repository: git+https://github.com/SuperchupuDev/tinyglobby.git
 <!-- TYPE_DEPENDENCIES -->
 
 # Licenses of bundled types
-
 The published @visulima/fs artifact additionally contains code with the following licenses:
-MIT
+ISC, MIT
 
 # Bundled types:
-
 ## is-fs-case-sensitive
-
 License: MIT
 By: Hiroki Osame
 Repository: privatenumber/is-fs-case-sensitive
@@ -315,4 +312,25 @@ Repository: privatenumber/is-fs-case-sensitive
 > OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 > SOFTWARE.
 
+---------------------------------------
+
+## yaml
+License: ISC
+By: Eemeli Aro
+Repository: github:eemeli/yaml
+
+> Copyright Eemeli Aro <eemeli@gmail.com>
+>
+> Permission to use, copy, modify, and/or distribute this software for any purpose
+> with or without fee is hereby granted, provided that the above copyright notice
+> and this permission notice appear in all copies.
+>
+> THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+> REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+> FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+> INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+> OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+> TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+> THIS SOFTWARE.
+
 <!-- /TYPE_DEPENDENCIES -->

package/dist/eol.d.ts

@@ -1,6 +1,36 @@
+/** End-of-line character for POSIX platforms such as macOS and Linux. */
 declare const LF: "\n";
+/** End-of-line character for Windows platforms. */
 declare const CRLF: "\r\n";
+/**
+* End-of-line character evaluated for the current platform.
+*/
 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
+* ```
+*/
 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"
+* ```
+*/
 declare const format: (content: string, eol: typeof EOL) => string;
 export { CRLF, EOL, LF, detect, format };

package/dist/error.d.ts

@@ -1,43 +1,273 @@
-export { J as JSONError } from "./packem_shared/json-error.d-DgKaeuIf.js";
+export { J as JSONError } from "./packem_shared/json-error.d-DVILOyHc.js";
+/**
+* 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);
+  override get name(): string;
+  override set name(_name: string);
 }
+/**
+* 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);
+  override get name(): string;
+  override set name(_name: string);
 }
+/**
+* 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);
+  override get name(): string;
+  override set name(_name: string);
 }
+/**
+* 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);
+  override get name(): string;
+  override set name(_name: string);
 }
+/**
+* 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);
+  override get name(): string;
+  override set name(_name: string);
 }
+/**
+* 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);
+  override get name(): string;
+  override set name(_name: string);
 }
 export { AlreadyExistsError, DirectoryError, NotEmptyError, NotFoundError, PermissionError, WalkError };

package/dist/glob-parent.d.ts

@@ -1,5 +1,35 @@
+/**
+* Options accepted by {@link globParent}.
+*/
 interface GlobParentOptions {
+  /**
+  * On Windows, flip backslashes to forward slashes before analysing the pattern.
+  *
+  * Disable when the input contains backslash escape sequences you want to preserve.
+  * @default true
+  */
   flipBackslashes?: boolean;
 }
+/**
+* Extracts the non-glob parent directory from a glob pattern.
+*
+* Useful when you need to know which directory to watch or walk for a given pattern — for example
+* `src/**\/*.ts` → `src`, `foo/{a,b}/*.js` → `foo`. Patterns without glob characters are returned
+* unchanged.
+*
+* Powered by [`glob-parent`](https://github.com/gulpjs/glob-parent) which is bundled into the built output so
+* it does not appear as a runtime dependency of `@visulima/fs`.
+* @param pattern The glob pattern to inspect.
+* @param options Optional configuration. See {@link GlobParentOptions}.
+* @returns The static parent path of the glob.
+* @example
+* ```javascript
+* import { globParent } from "@visulima/fs";
+*
+* globParent("src/**\/*.ts"); // "src"
+* globParent("foo/{a,b}/*.js"); // "foo"
+* globParent("foo/bar.js"); // "foo/bar.js"
+* ```
+*/
 declare const globParent: (pattern: string, options?: GlobParentOptions) => string;
 export { type GlobParentOptions, globParent as default };

package/dist/glob.d.ts

@@ -1,5 +1,4 @@
-export { g as glob, a as globSync } from "./packem_shared/glob-sync.d-BlGjS68e.js";
-export { type G as GlobOptions } from "./packem_shared/types.d-CYpAhWov.js";
+export { g as glob, a as globSync } from "./packem_shared/glob-sync.d-Dsxhj3BW.js";
+export { type G as GlobOptions } from "./packem_shared/types.d-CixEXeyM.js";
 import 'node:fs';
 import 'tinyglobby';
-import './options';