@visulima/fs 5.0.0-alpha.8 → 5.0.0

package/dist/error.d.ts

@@ -1,7 +1,273 @@
-export { default as AlreadyExistsError } from "./error/already-exists-error.d.ts";
-export { default as DirectoryError } from "./error/directory-error.d.ts";
-export { default as JSONError } from "./error/json-error.d.ts";
-export { default as NotEmptyError } from "./error/not-empty-error.d.ts";
-export { default as NotFoundError } from "./error/not-found-error.d.ts";
-export { default as PermissionError } from "./error/permission-error.d.ts";
-export { default as WalkError } from "./error/walk-error.d.ts";
+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);
+  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);
+  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);
+  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);
+  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);
+  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);
+  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

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

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

@@ -0,0 +1,4 @@
+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 'fdir';

package/dist/glob.js

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