@visulima/fs 5.0.0-alpha.9 → 5.0.0

package/README.md

@@ -66,6 +66,71 @@ pnpm add yaml
 
 ## Usage
 
+### Quickstart by subpath
+
+`@visulima/fs` ships one entry per concern. Import from the narrowest subpath you
+need so the optional parser peers (`yaml`, `smol-toml`, `jsonc-parser`, `json5`,
+`ini`) stay tree-shaken.
+
+```typescript
+// Core fs surface: walk, glob, findUp, ensure*, read/writeFile, copy, move, remove, emptyDir, isAccessible, sanitize, EOL.
+import { copy, ensureDir, findUp, readFile, walk, writeFile } from "@visulima/fs";
+
+// Typed error classes (NotFoundError, AlreadyExistsError, PermissionError, …).
+import { NotFoundError } from "@visulima/fs/error";
+
+// Parser-backed helpers — each needs its peer dependency installed.
+import { readYaml, writeYaml } from "@visulima/fs/yaml";
+import { readJsonc, writeJsonc } from "@visulima/fs/jsonc";
+
+// Glob primitives and size/eol helpers.
+import { glob } from "@visulima/fs/glob";
+import { gzipSize } from "@visulima/fs/size";
+```
+
+### Copy a file or directory
+
+```typescript
+import { copy } from "@visulima/fs";
+
+// Copy a template directory, skipping node_modules and overwriting existing files.
+await copy("templates/app", "out/app", {
+    filter: (source) => !source.includes("node_modules"),
+});
+
+// Refuse to overwrite an existing destination.
+import { AlreadyExistsError } from "@visulima/fs/error";
+
+try {
+    await copy("a.txt", "b.txt", { overwrite: false });
+} catch (error) {
+    if (error instanceof AlreadyExistsError) {
+        console.error("destination already exists");
+    }
+}
+```
+
+### Coming from `fs-extra`?
+
+| `fs-extra`                     | `@visulima/fs`                                                          |
+| ------------------------------ | ----------------------------------------------------------------------- |
+| `copy` / `copySync`            | `copy` / `copySync`                                                     |
+| `move` / `moveSync`            | `move` / `moveSync`                                                     |
+| `remove` / `removeSync`        | `remove` / `removeSync` (real `EACCES`/`EBUSY` errors propagate)        |
+| `emptyDir` / `emptyDirSync`    | `emptyDir` / `emptyDirSync`                                             |
+| `ensureFile` / `ensureDir` / … | `ensureFile` / `ensureDir` / `ensureLink` / `ensureSymlink` (+ `*Sync`) |
+| `readJson` / `writeJson`       | `readJson` / `writeJson` (+ `*Sync`)                                    |
+| `pathExists`                   | `isAccessible` / `isAccessibleSync`                                     |
+
+> **`writeFile` notes:** `overwrite` defaults to `true`. With `overwrite: false`,
+> `writeFile` throws `AlreadyExistsError` if the target exists instead of
+> overwriting it. To keep a copy of the previous file before overwriting, pass
+> `{ backup: true }` — the old contents are renamed to `${path}.bak`.
+>
+> **`readFile` errors:** a missing file throws `NotFoundError` (`ENOENT`); a file
+> that cannot be read for permission reasons throws `PermissionError`
+> (`EACCES`/`EPERM`).
+
 ## walk
 
 ```typescript

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/eol.js

@@ -1,26 +1,3 @@
-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 };
+import{createRequire as i}from"node:module";const u=i(import.meta.url),a=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,{platform:p}=a,s=/\r?\n/g,c=`
+`,r=`\r
+`,_=p==="win32"?r:c,g=t=>{const e=t.match(s);if(!e||e.length===0)return null;const o=e.filter(l=>l===r).length,n=e.length-o;return o>n?r:c},h=(t,e)=>t.replaceAll(s,e);export{r as CRLF,_ as EOL,c as LF,g as detect,h as 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/error.js

@@ -1,7 +1 @@
-export { default as AlreadyExistsError } from './packem_shared/AlreadyExistsError-6Y9hjgMn.js';
-export { default as DirectoryError } from './packem_shared/DirectoryError-BfYPkIYP.js';
-export { default as JSONError } from './packem_shared/JSONError-BkHRnInH.js';
-export { default as NotEmptyError } from './packem_shared/NotEmptyError-B21RUlVr.js';
-export { default as NotFoundError } from './packem_shared/NotFoundError-BIp61X6k.js';
-export { default as PermissionError } from './packem_shared/PermissionError-CjoiJgip.js';
-export { default as WalkError } from './packem_shared/WalkError-DER5A43G.js';
+import{default as t}from"./packem_shared/AlreadyExistsError-DEb3UWja.js";import{default as a}from"./packem_shared/DirectoryError-BtwSTLmT.js";import{default as s}from"./packem_shared/JSONError-Cvp9ycba.js";import{default as l}from"./packem_shared/NotEmptyError-DZ1Ix089.js";import{default as E}from"./packem_shared/NotFoundError-CnRY6lVp.js";import{default as u}from"./packem_shared/PermissionError-DJ_2VWEj.js";import{default as i}from"./packem_shared/WalkError-B8qTd-v-.js";export{t as AlreadyExistsError,a as DirectoryError,s as JSONError,l as NotEmptyError,E as NotFoundError,u as PermissionError,i as 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-parent.js

@@ -1,90 +1 @@
-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 __cjs_getBuiltinModule = (module) => {
-    // Check if we're in Node.js and version supports getBuiltinModule
-    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
-        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
-        // Node.js 20.16.0+ and 22.3.0+
-        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
-            return __cjs_getProcess.getBuiltinModule(module);
-        }
-    }
-    // Fallback to createRequire
-    return __cjs_require(module);
-};
-
-import { g as getDefaultExportFromCjs } from './packem_shared/_commonjsHelpers-BqLXS_qQ.js';
-import { r as requireIsGlob } from './packem_shared/index-bhgnhm4u.js';
-const require$$1 = __cjs_getBuiltinModule("path");
-const require$$2 = __cjs_getBuiltinModule("os");
-
-var globParent$1;
-var hasRequiredGlobParent;
-
-function requireGlobParent () {
-	if (hasRequiredGlobParent) return globParent$1;
-	hasRequiredGlobParent = 1;
-	var isGlob = requireIsGlob();
-	var pathPosixDirname = require$$1.posix.dirname;
-	var isWin32 = require$$2.platform() === "win32";
-	var slash = "/";
-	var backslash = /\\/g;
-	var escaped = /\\([!*?|[\](){}])/g;
-	globParent$1 = function globParent(str, opts) {
-	  var options = Object.assign({ flipBackslashes: true }, opts);
-	  if (options.flipBackslashes && isWin32 && str.indexOf(slash) < 0) {
-	    str = str.replace(backslash, slash);
-	  }
-	  if (isEnclosure(str)) {
-	    str += slash;
-	  }
-	  str += "a";
-	  do {
-	    str = pathPosixDirname(str);
-	  } while (isGlobby(str));
-	  return str.replace(escaped, "$1");
-	};
-	function isEnclosure(str) {
-	  var lastChar = str.slice(-1);
-	  var enclosureStart;
-	  switch (lastChar) {
-	    case "}":
-	      enclosureStart = "{";
-	      break;
-	    case "]":
-	      enclosureStart = "[";
-	      break;
-	    default:
-	      return false;
-	  }
-	  var foundIndex = str.indexOf(enclosureStart);
-	  if (foundIndex < 0) {
-	    return false;
-	  }
-	  return str.slice(foundIndex + 1, -1).includes(slash);
-	}
-	function isGlobby(str) {
-	  if (/\([^()]+$/.test(str)) {
-	    return true;
-	  }
-	  if (str[0] === "{" || str[0] === "[") {
-	    return true;
-	  }
-	  if (/[^\\][{[]/.test(str)) {
-	    return true;
-	  }
-	  return isGlob(str);
-	}
-	return globParent$1;
-}
-
-var globParentExports = requireGlobParent();
-const globParentImpl = /*@__PURE__*/getDefaultExportFromCjs(globParentExports);
-
-const globParent = (pattern, options) => globParentImpl(pattern, options);
-
-export { globParent as default };
+import{createRequire as g}from"node:module";import{g as _}from"./packem_shared/_commonjsHelpers-CWAkuNXM.js";import{r as v}from"./packem_shared/index-BHy3Kcr7.js";const h=g(import.meta.url),i=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,f=s=>{if(typeof i<"u"&&i.versions&&i.versions.node){const[r,o]=i.versions.node.split(".").map(Number);if(r>22||r===22&&o>=3||r===20&&o>=16)return i.getBuiltinModule(s)}return h(s)},q=f("path"),j=f("os");var l,u;function x(){if(u)return l;u=1;var s=v(),r=q.posix.dirname,o=j.platform()==="win32",n="/",p=/\\/g,d=/\\([!*?|[\](){}])/g;l=function(e,a){var t=Object.assign({flipBackslashes:!0},a);t.flipBackslashes&&o&&e.indexOf(n)<0&&(e=e.replace(p,n)),b(e)&&(e+=n),e+="a";do e=r(e);while(m(e));return e.replace(d,"$1")};function b(e){var a=e.slice(-1),t;switch(a){case"}":t="{";break;case"]":t="[";break;default:return!1}var c=e.indexOf(t);return c<0?!1:e.slice(c+1,-1).includes(n)}function m(e){return/\([^()]+$/.test(e)||e[0]==="{"||e[0]==="["||/[^\\][{[]/.test(e)?!0:s(e)}return l}var P=x();const $=_(P),B=(s,r)=>$(s,r);export{B as default};

package/dist/glob.d.ts

@@ -1,5 +1,4 @@
-export { g as glob, a as globSync } from "./packem_shared/glob-sync.d-B83kqwUd.js";
-export { type G as GlobOptions } from "./packem_shared/types.d-dP-lAGNn.js";
+export { g as glob, a as globSync } from "./packem_shared/glob-sync.d-hXe38TnZ.js";
+export type { G as GlobOptions } from "./packem_shared/types.d-BMdL_ygj.js";
 import 'node:fs';
-import 'tinyglobby';
-import './options';
+import 'fdir';

package/dist/glob.js

@@ -1,2 +1 @@
-export { default as glob } from './packem_shared/glob-DY8l7izD.js';
-export { default as globSync } from './packem_shared/globSync-5P2KJf_g.js';
+import{default as e}from"./packem_shared/glob-fqg4KepW.js";import{default as l}from"./packem_shared/globSync-B8_ne93E.js";export{e as glob,l as globSync};