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

package/dist/ini.d.ts

@@ -1,10 +1,70 @@
-import { a as CompressionType, n as ReadIniOptions, o as WriteIniOptions } from "./packem_shared/types.d-CYpAhWov.js";
-export { type I as IniEncodeOptions, type p as IniLineEnding } from "./packem_shared/types.d-CYpAhWov.js";
+import { a as CompressionType, j as ReadIniOptions, k as WriteIniOptions } from "./packem_shared/types.d-CixEXeyM.js";
+export { type I as IniEncodeOptions, type l as IniLineEnding } from "./packem_shared/types.d-CixEXeyM.js";
 import 'node:fs';
 import 'tinyglobby';
-import './options';
+/**
+* Asynchronously reads an INI file and parses it into an object.
+* @template R The expected type of the parsed object. Defaults to `Record<string, unknown>`.
+* @param path The path to the INI file. Can be a file URL or a string path.
+* @param options Optional configuration. See {@link ReadIniOptions}.
+* @returns A promise that resolves with the parsed object.
+* @example
+* ```javascript
+* import { readIni } from "@visulima/fs/ini";
+*
+* const config = await readIni("./config.ini");
+* ```
+*/
 declare const readIni: <R = Record<string, unknown>>(path: URL | string, options?: ReadIniOptions<CompressionType>) => Promise<R>;
+/**
+* Synchronously reads an INI file and parses it into an object.
+* @template R The expected type of the parsed object. Defaults to `Record&lt;string, unknown>`.
+* @param path The path to the INI file. Can be a file URL or a string path.
+* @param options Optional configuration. See {@link ReadIniOptions}.
+* @returns The parsed object.
+* @example
+* ```javascript
+* import { readIniSync } from "@visulima/fs/ini";
+*
+* const config = readIniSync("./config.ini");
+* ```
+*/
 declare const readIniSync: (path: URL | string, options?: ReadIniOptions<CompressionType>) => Record<string, unknown>;
+/**
+* Asynchronously writes an object to an INI file.
+*
+* When an existing file is present and `preserveStyle` is `true` (the default), the original file's
+* whitespace-around-`=` style and line endings are auto-detected and retained, and any line whose
+* parsed value is unchanged is kept verbatim — preserving trailing whitespace and inline `;`/`#`
+* comments. Explicit `whitespace` / `eol` options always win over detection.
+* @param path The path to the INI file. Can be a file URL or a string path.
+* @param data The data to serialize.
+* @param options Optional configuration. See {@link WriteIniOptions}.
+* @returns A promise that resolves when the file has been written.
+* @example
+* ```javascript
+* import { writeIni } from "@visulima/fs/ini";
+*
+* await writeIni("./config.ini", { server: { port: 8080 } });
+* ```
+*/
 declare const writeIni: (path: URL | string, data: Record<string, unknown>, options?: WriteIniOptions) => Promise<void>;
+/**
+* Synchronously writes an object to an INI file.
+*
+* When an existing file is present and `preserveStyle` is `true` (the default), the original file's
+* whitespace-around-`=` style and line endings are auto-detected and retained, and any line whose
+* parsed value is unchanged is kept verbatim — preserving trailing whitespace and inline `;`/`#`
+* comments. Explicit `whitespace` / `eol` options always win over detection.
+* @param path The path to the INI file. Can be a file URL or a string path.
+* @param data The data to serialize.
+* @param options Optional configuration. See {@link WriteIniOptions}.
+* @example
+* ```javascript
+* import { writeIniSync } from "@visulima/fs/ini";
+*
+* writeIniSync("./config.ini", { server: { port: 8080 } });
+* ```
+*/
 declare const writeIniSync: (path: URL | string, data: Record<string, unknown>, options?: WriteIniOptions) => void;
 export { type ReadIniOptions, type WriteIniOptions, readIni, readIniSync, writeIni, writeIniSync };

package/dist/is-glob.d.ts

@@ -1,5 +1,34 @@
+/**
+* Options accepted by {@link isGlob}.
+*/
 interface IsGlobOptions {
+  /**
+  * When `false`, matches more permissively — any string containing unescaped glob
+  * meta characters (`*`, `?`, `{}`, `()`, `[]`) is treated as a glob, even when the
+  * sequence is not a valid glob expression.
+  * @default true
+  */
   strict?: boolean;
 }
+/**
+* Returns `true` if the given value looks like a glob pattern (including extglobs like `@(foo|bar)`).
+*
+* Escaped meta characters (e.g. `\\*`) are not considered globs. Non-string values always return `false`.
+*
+* Powered by [`is-glob`](https://github.com/micromatch/is-glob) which is bundled into the built output so it does
+* not appear as a runtime dependency of `@visulima/fs`.
+* @param value The value to inspect.
+* @param options Optional configuration. See {@link IsGlobOptions}.
+* @returns `true` if `value` looks like a glob pattern, otherwise `false`.
+* @example
+* ```javascript
+* import { isGlob } from "@visulima/fs";
+*
+* isGlob("src/**\/*.ts"); // true
+* isGlob("src/index.ts"); // false
+* isGlob("src/\\*.ts"); // false — escaped
+* isGlob("!foo.js"); // true — negation
+* ```
+*/
 declare const isGlob: (value: unknown, options?: IsGlobOptions) => boolean;
 export { type IsGlobOptions, isGlob as default };

package/dist/json5.d.ts

@@ -1,12 +1,36 @@
-import { a as CompressionType, j as ReadJson5Options, k as Json5Reviver, l as WriteJson5Options } from "./packem_shared/types.d-CYpAhWov.js";
-export { type m as Json5Replacer } from "./packem_shared/types.d-CYpAhWov.js";
+import { a as CompressionType, f as ReadJson5Options, g as Json5Reviver, h as WriteJson5Options } from "./packem_shared/types.d-CixEXeyM.js";
+export { type i as Json5Replacer } from "./packem_shared/types.d-CixEXeyM.js";
 import 'node:fs';
 import 'tinyglobby';
-import './options';
 declare function readJson5<R = unknown>(path: URL | string, options?: ReadJson5Options<CompressionType>): Promise<R>;
 declare function readJson5<R = unknown>(path: URL | string, reviver: Json5Reviver, options?: ReadJson5Options<CompressionType>): Promise<R>;
 declare function readJson5Sync(path: URL | string, options?: ReadJson5Options<CompressionType>): unknown;
 declare function readJson5Sync(path: URL | string, reviver: Json5Reviver, options?: ReadJson5Options<CompressionType>): unknown;
+/**
+* Asynchronously writes a value to a JSON5 file.
+* @param path The path to the JSON5 file. Can be a file URL or a string path.
+* @param data The data to serialize.
+* @param options Optional configuration. See {@link WriteJson5Options}.
+* @returns A promise that resolves when the file has been written.
+* @example
+* ```javascript
+* import { writeJson5 } from "@visulima/fs/json5";
+*
+* await writeJson5("./config.json5", { name: "app" }, { indent: 2, quote: "'" });
+* ```
+*/
 declare const writeJson5: (path: URL | string, data: unknown, options?: WriteJson5Options) => Promise<void>;
+/**
+* Synchronously writes a value to a JSON5 file.
+* @param path The path to the JSON5 file. Can be a file URL or a string path.
+* @param data The data to serialize.
+* @param options Optional configuration. See {@link WriteJson5Options}.
+* @example
+* ```javascript
+* import { writeJson5Sync } from "@visulima/fs/json5";
+*
+* writeJson5Sync("./config.json5", { name: "app" }, { indent: 2 });
+* ```
+*/
 declare const writeJson5Sync: (path: URL | string, data: unknown, options?: WriteJson5Options) => void;
 export { type Json5Reviver, type ReadJson5Options, type WriteJson5Options, readJson5, readJson5Sync, writeJson5, writeJson5Sync };

package/dist/jsonc.d.ts

@@ -1,10 +1,65 @@
-import { a as CompressionType, d as ReadJsoncOptions, e as WriteJsoncOptions } from "./packem_shared/types.d-CYpAhWov.js";
-export { type f as JsoncFormattingOptions, type g as JsoncParseOptions } from "./packem_shared/types.d-CYpAhWov.js";
+import { a as CompressionType, b as ReadJsoncOptions, c as WriteJsoncOptions } from "./packem_shared/types.d-CixEXeyM.js";
+export { type d as JsoncFormattingOptions, type e as JsoncParseOptions } from "./packem_shared/types.d-CixEXeyM.js";
 import 'node:fs';
 import 'tinyglobby';
-import './options';
+/**
+* Asynchronously reads a JSONC (JSON with comments) file and parses it into a JavaScript value.
+* Supports `//` and `/* *\/` comments and, optionally, trailing commas via `jsonc-parser`.
+* @param path The path to the JSONC file. Can be a file URL or a string path.
+* @param options Optional configuration. See {@link ReadJsoncOptions}.
+* @returns A promise that resolves with the parsed value.
+* @example
+* ```javascript
+* import { readJsonc } from "@visulima/fs/jsonc";
+*
+* const config = await readJsonc("./tsconfig.json", { allowTrailingComma: true });
+* ```
+*/
 declare const readJsonc: (path: URL | string, options?: ReadJsoncOptions<CompressionType>) => Promise<unknown>;
+/**
+* Synchronously reads a JSONC (JSON with comments) file and parses it into a JavaScript value.
+* Supports `//` and `/* *\/` comments and, optionally, trailing commas via `jsonc-parser`.
+* @param path The path to the JSONC file. Can be a file URL or a string path.
+* @param options Optional configuration. See {@link ReadJsoncOptions}.
+* @returns The parsed value.
+* @example
+* ```javascript
+* import { readJsoncSync } from "@visulima/fs/jsonc";
+*
+* const config = readJsoncSync("./tsconfig.json", { allowTrailingComma: true });
+* ```
+*/
 declare const readJsoncSync: (path: URL | string, options?: ReadJsoncOptions<CompressionType>) => unknown;
+/**
+* Asynchronously writes a value to a JSONC file. When `preserveComments` is `true` (the default)
+* and the target file already exists, existing comments and formatting are preserved by computing
+* a minimal diff against the new value via `jsonc-parser`'s `modify` API.
+* @param path The path to the JSONC file. Can be a file URL or a string path.
+* @param data The data to serialize.
+* @param options Optional configuration. See {@link WriteJsoncOptions}.
+* @returns A promise that resolves when the file has been written.
+* @example
+* ```javascript
+* import { writeJsonc } from "@visulima/fs/jsonc";
+*
+* // Preserves comments inside an existing tsconfig.json
+* await writeJsonc("./tsconfig.json", { ...tsconfig, compilerOptions: { target: "es2024" } });
+* ```
+*/
 declare const writeJsonc: (path: URL | string, data: unknown, options?: WriteJsoncOptions) => Promise<void>;
+/**
+* Synchronously writes a value to a JSONC file. When `preserveComments` is `true` (the default)
+* and the target file already exists, existing comments and formatting are preserved by computing
+* a minimal diff against the new value via `jsonc-parser`'s `modify` API.
+* @param path The path to the JSONC file. Can be a file URL or a string path.
+* @param data The data to serialize.
+* @param options Optional configuration. See {@link WriteJsoncOptions}.
+* @example
+* ```javascript
+* import { writeJsoncSync } from "@visulima/fs/jsonc";
+*
+* writeJsoncSync("./tsconfig.json", updated);
+* ```
+*/
 declare const writeJsoncSync: (path: URL | string, data: unknown, options?: WriteJsoncOptions) => void;
 export { type ReadJsoncOptions, type WriteJsoncOptions, readJsonc, readJsoncSync, writeJsonc, writeJsoncSync };

package/dist/match.d.ts

@@ -1,5 +1,46 @@
-import { PicomatchOptions } from 'picomatch';
-type MatchOptions = PicomatchOptions;
+import picomatch from './lib/picomatch';
+/**
+* Options accepted by {@link match} and {@link matcher}.
+*
+* Passed straight through to [`picomatch`](https://github.com/micromatch/picomatch#options); see its documentation for the full list.
+*/
+type MatchOptions = picomatch.PicomatchOptions;
+/**
+* Tests whether a path matches one or more glob patterns.
+*
+* Powered by [`picomatch`](https://github.com/micromatch/picomatch) which is bundled into the built output so it does
+* not appear as a runtime dependency of `@visulima/fs`.
+*
+* If you match many values against the same pattern, prefer {@link matcher} to compile the pattern once.
+* @param value The path (or paths) to test.
+* @param pattern A single glob or array of globs.
+* @param options Optional picomatch options. See {@link MatchOptions}.
+* @returns `true` if `value` matches any of `pattern`.
+* @example
+* ```javascript
+* import { match } from "@visulima/fs";
+*
+* match("src/index.ts", "src/**\/*.ts"); // true
+* match("src/index.ts", ["**\/*.js", "**\/*.ts"]); // true
+* match("src/index.ts", "**\/*.js"); // false
+* ```
+*/
 declare const match: (value: string | string[], pattern: string | string[], options?: MatchOptions) => boolean;
+/**
+* Compiles a glob pattern into a reusable matcher function.
+*
+* Powered by [`picomatch`](https://github.com/micromatch/picomatch) which is bundled into the built output so it does
+* not appear as a runtime dependency of `@visulima/fs`.
+* @param pattern A single glob or array of globs.
+* @param options Optional picomatch options. See {@link MatchOptions}.
+* @returns A function that returns `true` when its argument matches the compiled pattern.
+* @example
+* ```javascript
+* import { matcher } from "@visulima/fs";
+*
+* const isTs = matcher("**\/*.ts");
+* ["a.ts", "b.js", "c.ts"].filter(isTs); // ["a.ts", "c.ts"]
+* ```
+*/
 declare const matcher: (pattern: string | string[], options?: MatchOptions) => (value: string) => boolean;
 export { MatchOptions, match, matcher };

package/dist/packem_shared/glob-sync.d-Dsxhj3BW.d.ts

@@ -0,0 +1,54 @@
+import { G as GlobOptions } from "./types.d-CixEXeyM.js";
+/**
+* Asynchronously matches files on disk using one or more glob patterns.
+*
+* Powered by [`tinyglobby`](https://github.com/SuperchupuDev/tinyglobby); `tinyglobby` is bundled into the
+* built output so it does not appear as a runtime dependency of `@visulima/fs`.
+*
+* Pattern forms:
+*
+* - Plain glob — `src/**\/*.ts`
+* - Negated pattern — `!src/**\/*.spec.ts` inside `patterns` adds to the internal ignore list (same as passing it via `ignore`).
+* - Negated ignore — a leading `!` inside {@link GlobOptions.ignore} _un-ignores_ entries that an earlier ignore pattern would drop, e.g. `ignore: ["dist/**", "!dist/index.d.ts"]`.
+* @param patterns A single glob pattern or an array of glob patterns.
+* @param options Optional glob options. See {@link GlobOptions}.
+* @returns A promise resolving to the array of matched paths. Paths are relative to {@link GlobOptions.cwd} unless {@link GlobOptions.absolute} is `true`.
+* @example
+* ```javascript
+* import { glob } from "@visulima/fs";
+*
+* const jsFiles = await glob("src/**\/*.{js,ts}", { cwd: process.cwd(), ignore: ["**\/node_modules/**"] });
+* console.log(jsFiles);
+*
+* // Negated ignore: drop everything under `ignored/` except `ignored/keep.ts`.
+* const keep = await glob("**\/*.ts", { ignore: ["ignored/**", "!ignored/keep.ts"] });
+* ```
+*/
+declare const glob: (patterns: string | ReadonlyArray<string>, options?: GlobOptions) => Promise<string[]>;
+/**
+* Synchronously matches files on disk using one or more glob patterns.
+*
+* Synchronous counterpart of `glob`. Powered by [`tinyglobby`](https://github.com/SuperchupuDev/tinyglobby);
+* bundled into the built output so it does not appear as a runtime dependency of `@visulima/fs`.
+*
+* Pattern forms:
+*
+* - Plain glob — `src/**\/*.ts`
+* - Negated pattern — `!src/**\/*.spec.ts` inside `patterns` adds to the internal ignore list.
+* - Negated ignore — a leading `!` inside {@link GlobOptions.ignore} _un-ignores_ entries that an earlier ignore pattern would drop, e.g. `ignore: ["dist/**", "!dist/index.d.ts"]`.
+* @param patterns A single glob pattern or an array of glob patterns.
+* @param options Optional glob options. See {@link GlobOptions}.
+* @returns The array of matched paths. Paths are relative to {@link GlobOptions.cwd} unless {@link GlobOptions.absolute} is `true`.
+* @example
+* ```javascript
+* import { globSync } from "@visulima/fs";
+*
+* const jsFiles = globSync(["src/**\/*.ts", "!**\/*.spec.ts"]);
+* console.log(jsFiles);
+*
+* // Negated ignore: drop everything under `ignored/` except `ignored/keep.ts`.
+* const keep = globSync("**\/*.ts", { ignore: ["ignored/**", "!ignored/keep.ts"] });
+* ```
+*/
+declare const globSync: (patterns: string | ReadonlyArray<string>, options?: GlobOptions) => string[];
+export { globSync as a, glob as g };

package/dist/packem_shared/json-error.d-DVILOyHc.d.ts

@@ -0,0 +1,52 @@
+/**
+* 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;
+  override readonly name = "JSONError";
+  /**
+  * Creates a new JSONError instance.
+  * @param message The primary error message.
+  */
+  constructor(message: string);
+  override get message(): string;
+  override set message(message: string);
+}
+export { JSONError as J };