@visulima/fs 4.0.4 → 4.0.5

package/dist/size.d.ts

@@ -1,12 +1,245 @@
-import { Readable } from 'node:stream';
-import { URL } from 'node:url';
-import { ZlibOptions, BrotliOptions } from 'node:zlib';
-
-declare const gzipSize: (input: Buffer | Readable | URL | string, options?: ZlibOptions) => Promise<number>;
-declare const brotliSize: (input: Buffer | Readable | URL | string, options?: BrotliOptions) => Promise<number>;
-declare const rawSize: (input: Buffer | Readable | URL | string) => Promise<number>;
-declare const gzipSizeSync: (input: Buffer | URL | string, options?: ZlibOptions) => number;
-declare const brotliSizeSync: (input: Buffer | URL | string, options?: BrotliOptions) => number;
-declare const rawSizeSync: (input: Buffer | URL | string) => number;
-
-export { brotliSize, brotliSizeSync, gzipSize, gzipSizeSync, rawSize, rawSizeSync };
+import { Readable } from "node:stream";
+import { URL } from "node:url";
+import type { BrotliOptions, ZlibOptions } from "node:zlib";
+/**
+ * Asynchronously calculates the gzipped size of the given input.
+ * The input can be a Buffer, a Readable stream, a URL object pointing to a file, or a string (file path or content).
+ * Uses memory-efficient streaming for files and streams to avoid loading entire contents into memory.
+ * @param input The input data to gzip and measure.
+ * @param [options] Optional Zlib options for gzip compression.
+ * @returns A promise that resolves with the gzipped size in bytes.
+ * @example
+ * ```javascript
+ * import { gzipSize } from "@visulima/fs";
+ * import { Readable } from "node:stream";
+ * import { writeFile, unlink } from "node:fs/promises";
+ * import { join } from "node:path";
+ *
+ * const text = "Lorem ipsum dolor sit amet, consectetur adipiscing elit.";
+ * const filePath = join("temp-file.txt");
+ *
+ * async function main() {
+ *   // From Buffer
+ *   const buffer = Buffer.from(text);
+ *   console.log(`Gzip size of buffer: ${await gzipSize(buffer)} bytes`);
+ *
+ *   // From string (content)
+ *   console.log(`Gzip size of string content: ${await gzipSize(text)} bytes`);
+ *
+ *   // From file path
+ *   await writeFile(filePath, text);
+ *   console.log(`Gzip size of file: ${await gzipSize(filePath)} bytes`);
+ *
+ *   // From URL
+ *   const fileUrl = new URL(`file://${filePath}`);
+ *   console.log(`Gzip size of URL: ${await gzipSize(fileUrl)} bytes`);
+ *
+ *   // From Readable stream
+ *   const stream = Readable.from(text);
+ *   console.log(`Gzip size of stream: ${await gzipSize(stream)} bytes`);
+ *
+ *   await unlink(filePath); // Clean up temp file
+ * }
+ *
+ * main().catch(console.error);
+ * ```
+ */
+export declare const gzipSize: (input: Buffer | Readable | URL | string, options?: ZlibOptions) => Promise<number>;
+/**
+ * Asynchronously calculates the Brotli compressed size of the given input.
+ * The input can be a Buffer, a Readable stream, a URL object pointing to a file, or a string (file path or content).
+ * Uses memory-efficient streaming for files and streams to avoid loading entire contents into memory.
+ * @param input The input data to compress with Brotli and measure.
+ * @param [options] Optional Zlib options for Brotli compression.
+ * @returns A promise that resolves with the Brotli compressed size in bytes.
+ * @example
+ * ```javascript
+ * import { brotliSize } from "@visulima/fs";
+ * import { Readable } from "node:stream";
+ * import { writeFile, unlink } from "node:fs/promises";
+ * import { join } from "node:path";
+ *
+ * const text = "This is a test string for Brotli compression efficiency.";
+ * const filePath = join("temp-brotli-file.txt");
+ *
+ * async function main() {
+ *   // From Buffer
+ *   const buffer = Buffer.from(text);
+ *   console.log(`Brotli size of buffer: ${await brotliSize(buffer)} bytes`);
+ *
+ *   // From string (content)
+ *   console.log(`Brotli size of string content: ${await brotliSize(text)} bytes`);
+ *
+ *   // From file path
+ *   await writeFile(filePath, text);
+ *   console.log(`Brotli size of file: ${await brotliSize(filePath)} bytes`);
+ *
+ *   // From URL
+ *   const fileUrl = new URL(`file://${filePath}`);
+ *   console.log(`Brotli size of URL: ${await brotliSize(fileUrl)} bytes`);
+ *
+ *   // From Readable stream
+ *   const stream = Readable.from(text);
+ *   console.log(`Brotli size of stream: ${await brotliSize(stream)} bytes`);
+ *
+ *   await unlink(filePath); // Clean up temp file
+ * }
+ *
+ * main().catch(console.error);
+ * ```
+ */
+export declare const brotliSize: (input: Buffer | Readable | URL | string, options?: BrotliOptions) => Promise<number>;
+/**
+ * Asynchronously calculates the raw (uncompressed) size of the given input.
+ * The input can be a Buffer, a Readable stream, a URL object pointing to a file, or a string (file path or content).
+ * Uses memory-efficient streaming for files and streams to avoid loading entire contents into memory.
+ * @param input The input data to measure.
+ * @returns A promise that resolves with the raw size in bytes.
+ * @example
+ * ```javascript
+ * import { rawSize } from "@visulima/fs";
+ * import { Readable } from "node:stream";
+ * import { writeFile, unlink } from "node:fs/promises";
+ * import { join } from "node:path";
+ *
+ * const text = "Hello, World!";
+ * const filePath = join("temp-raw-file.txt");
+ *
+ * async function main() {
+ *   // From Buffer
+ *   const buffer = Buffer.from(text);
+ *   console.log(`Raw size of buffer: ${await rawSize(buffer)} bytes`);
+ *
+ *   // From string (content)
+ *   console.log(`Raw size of string content: ${await rawSize(text)} bytes`);
+ *
+ *   // From file path
+ *   await writeFile(filePath, text);
+ *   console.log(`Raw size of file: ${await rawSize(filePath)} bytes`);
+ *
+ *   // From URL
+ *   const fileUrl = new URL(`file://${filePath}`);
+ *   console.log(`Raw size of URL: ${await rawSize(fileUrl)} bytes`);
+ *
+ *   // From Readable stream
+ *   const stream = Readable.from(text);
+ *   console.log(`Raw size of stream: ${await rawSize(stream)} bytes`);
+ *
+ *   await unlink(filePath); // Clean up temp file
+ * }
+ *
+ * main().catch(console.error);
+ * ```
+ */
+export declare const rawSize: (input: Buffer | Readable | URL | string) => Promise<number>;
+/**
+ * Synchronously calculates the gzipped size of the given input.
+ * The input can be a Buffer, a URL object pointing to a file, or a string (file path or content).
+ * Note: For Readable streams or very large files, consider using the asynchronous `gzipSize` function for better performance and to avoid blocking.
+ * @param input The input data to gzip and measure.
+ * @param [options] Optional Zlib options for gzip compression.
+ * @returns The gzipped size in bytes.
+ * @example
+ * ```javascript
+ * import { gzipSizeSync } from "@visulima/fs";
+ * import { writeFileSync, unlinkSync } from "node:fs";
+ * import { join } from "node:path";
+ *
+ * const text = "Lorem ipsum dolor sit amet, consectetur adipiscing elit.";
+ * const filePath = join("temp-sync-file.txt");
+ *
+ * // From Buffer
+ * const buffer = Buffer.from(text);
+ * console.log(`Sync Gzip size of buffer: ${gzipSizeSync(buffer)} bytes`);
+ *
+ * // From string (content)
+ * console.log(`Sync Gzip size of string content: ${gzipSizeSync(text)} bytes`);
+ *
+ * // From file path
+ * try {
+ *   writeFileSync(filePath, text);
+ *   console.log(`Sync Gzip size of file: ${gzipSizeSync(filePath)} bytes`);
+ *
+ *   // From URL
+ *   const fileUrl = new URL(`file://${filePath}`);
+ *   console.log(`Sync Gzip size of URL: ${gzipSizeSync(fileUrl)} bytes`);
+ * } finally {
+ *   try { unlinkSync(filePath); } catch {} // Clean up temp file
+ * }
+ * ```
+ */
+export declare const gzipSizeSync: (input: Buffer | URL | string, options?: ZlibOptions) => number;
+/**
+ * Synchronously calculates the Brotli compressed size of the given input.
+ * The input can be a Buffer, a URL object pointing to a file, or a string (file path or content).
+ * Note: For Readable streams or very large files, consider using the asynchronous `brotliSize` function for better performance and to avoid blocking.
+ * @param input The input data to compress with Brotli and measure.
+ * @param [options] Optional Zlib options for Brotli compression.
+ * @returns The Brotli compressed size in bytes.
+ * @example
+ * ```javascript
+ * import { brotliSizeSync } from "@visulima/fs";
+ * import { writeFileSync, unlinkSync } from "node:fs";
+ * import { join } from "node:path";
+ *
+ * const text = "This is a test string for Brotli compression efficiency, synchronously.";
+ * const filePath = join("temp-brotli-sync-file.txt");
+ *
+ * // From Buffer
+ * const buffer = Buffer.from(text);
+ * console.log(`Sync Brotli size of buffer: ${brotliSizeSync(buffer)} bytes`);
+ *
+ * // From string (content)
+ * console.log(`Sync Brotli size of string content: ${brotliSizeSync(text)} bytes`);
+ *
+ * // From file path
+ * try {
+ *   writeFileSync(filePath, text);
+ *   console.log(`Sync Brotli size of file: ${brotliSizeSync(filePath)} bytes`);
+ *
+ *   // From URL
+ *   const fileUrl = new URL(`file://${filePath}`);
+ *   console.log(`Sync Brotli size of URL: ${brotliSizeSync(fileUrl)} bytes`);
+ * } finally {
+ *   try { unlinkSync(filePath); } catch {} // Clean up temp file
+ * }
+ * ```
+ */
+export declare const brotliSizeSync: (input: Buffer | URL | string, options?: BrotliOptions) => number;
+/**
+ * Synchronously calculates the raw (uncompressed) size of the given input.
+ * The input can be a Buffer, a URL object pointing to a file, or a string (file path or content).
+ * For file paths, it uses `statSync` to get the file size.
+ * Note: For Readable streams or very large files, consider using the asynchronous `rawSize` function for better performance and to avoid blocking.
+ * @param input The input data to measure.
+ * @returns The raw size in bytes.
+ * @example
+ * ```javascript
+ * import { rawSizeSync } from "@visulima/fs";
+ * import { writeFileSync, unlinkSync } from "node:fs";
+ * import { join } from "node:path";
+ *
+ * const text = "Hello, Synchronous World!";
+ * const filePath = join("temp-raw-sync-file.txt");
+ *
+ * // From Buffer
+ * const buffer = Buffer.from(text);
+ * console.log(`Sync Raw size of buffer: ${rawSizeSync(buffer)} bytes`);
+ *
+ * // From string (content)
+ * console.log(`Sync Raw size of string content: ${rawSizeSync(text)} bytes`);
+ *
+ * // From file path
+ * try {
+ *   writeFileSync(filePath, text);
+ *   console.log(`Sync Raw size of file: ${rawSizeSync(filePath)} bytes`);
+ *
+ *   // From URL
+ *   const fileUrl = new URL(`file://${filePath}`);
+ *   console.log(`Sync Raw size of URL: ${rawSizeSync(fileUrl)} bytes`);
+ * } finally {
+ *   try { unlinkSync(filePath); } catch {} // Clean up temp file
+ * }
+ * ```
+ */
+export declare const rawSizeSync: (input: Buffer | URL | string) => number;

package/dist/types.d.ts

@@ -0,0 +1,299 @@
+import type { Dirent, PathLike } from "node:fs";
+import type { CreateNodeOptions, DocumentOptions, ParseOptions, SchemaOptions, ToJSOptions, ToStringOptions } from "yaml";
+import type { FIND_UP_STOP } from "./constants.d.ts";
+type ColorizeMethod = (value: string) => string;
+/**
+ * Options for the `walk` and `walkSync` functions.
+ */
+export interface WalkOptions {
+    /**
+     * List of file extensions used to filter entries.
+     * If specified, entries without the file extension specified by this option are excluded.
+     * @default {undefined}
+     */
+    extensions?: string[];
+    /**
+     * Indicates whether symlinks should be resolved or not.
+     * @default {false}
+     */
+    followSymlinks?: boolean;
+    /**
+     * Indicates whether directory entries should be included or not.
+     * @default {true}
+     */
+    includeDirs?: boolean;
+    /**
+     * Indicates whether file entries should be included or not.
+     * @default {true}
+     */
+    includeFiles?: boolean;
+    /**
+     * Indicates whether symlink entries should be included or not.
+     * This option is meaningful only if `followSymlinks` is set to `false`.
+     * @default {true}
+     */
+    includeSymlinks?: boolean;
+    /**
+     * List of regular expression or glob patterns used to filter entries.
+     * If specified, entries that do not match the patterns specified by this option are excluded.
+     * @default {undefined}
+     */
+    match?: (RegExp | string)[];
+    /**
+     * The maximum depth of the file tree to be walked recursively.
+     * @default {Infinity}
+     */
+    maxDepth?: number;
+    /**
+     * List of regular expression or glob patterns used to filter entries.
+     * If specified, entries matching the patterns specified by this option are excluded.
+     * @default {undefined}
+     */
+    skip?: (RegExp | string)[];
+}
+/**
+ * Represents an entry found by `walk` or `walkSync`.
+ */
+export interface WalkEntry extends Pick<Dirent, "isDirectory" | "isFile" | "isSymbolicLink" | "name"> {
+    /** The full path to the entry. */
+    path: string;
+}
+/**
+ * Supported file encodings for reading files.
+ */
+export type ReadFileEncoding = "ascii" | "base64" | "base64url" | "hex" | "latin1" | "ucs-2" | "ucs2" | "utf-8" | "utf-16le" | "utf8" | "utf16le";
+/**
+ * Options for reading files.
+ * @template C - The type of compression used.
+ */
+export type ReadFileOptions<C> = {
+    /**
+     * Return content as a Buffer. Default: `false`
+     */
+    buffer?: boolean;
+    /**
+     * Compression method to decompress the file against. Default: `none`
+     */
+    compression?: C;
+    /**
+     * The encoding to use. Default: `utf8`
+     * @see https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings
+     */
+    encoding?: ReadFileEncoding | undefined;
+    /**
+     * The flag used to open the file. Default: `r`
+     */
+    flag?: number | string | undefined;
+};
+/**
+ * Represents the content type of a read file, which can be a Buffer or a string based on options.
+ * @template O - The ReadFileOptions type.
+ */
+export type ContentType<O = undefined> = O extends {
+    buffer: true;
+} ? Buffer : string;
+/**
+ * Type for the `reviver` parameter of `JSON.parse()`.
+ * A function that transforms the results. This function is called for each member of the object.
+ * If a member contains nested objects, the nested objects are transformed before the parent object is.
+ */
+export type JsonReviver = Parameters<(typeof JSON)["parse"]>["1"];
+/**
+ * Specifies a location (line and column) in a file for code frame generation.
+ */
+export type CodeFrameLocation = {
+    /** The column number. */
+    column?: number;
+    /** The line number. */
+    line: number;
+};
+/**
+ * Options for customizing the appearance of code frames.
+ */
+export type CodeFrameOptions = {
+    /** Colorization methods for different parts of the code frame. */
+    color?: {
+        /** Color for the gutter (line numbers). */
+        gutter?: ColorizeMethod;
+        /** Color for the marker (pointing to the error). */
+        marker?: ColorizeMethod;
+        /** Color for the message. */
+        message?: ColorizeMethod;
+    };
+};
+/**
+ * Options for reading and parsing JSON files.
+ * Extends {@link CodeFrameOptions}.
+ */
+export type ReadJsonOptions = CodeFrameOptions & {
+    /**
+     * A function to transform the string content before parsing.
+     * @param source The raw string content of the file.
+     * @returns The transformed string content.
+     */
+    beforeParse?: (source: string) => string;
+};
+/**
+ * Options for writing files.
+ */
+export type WriteFileOptions = {
+    /**
+     * The group and user ID used to set the file ownership. Default: `undefined`
+     */
+    chown?: {
+        gid: number;
+        uid: number;
+    };
+    /**
+     * The encoding to use. Default: `utf8`
+     */
+    encoding?: BufferEncoding | null | undefined;
+    /**
+     * The flag used to write the file. Default: `w`
+     */
+    flag?: string | undefined;
+    /**
+     * The file mode (permission and sticky bits). Default: `0o666`
+     */
+    mode?: number;
+    /**
+     * Indicates whether the file should be overwritten if it already exists. Default: `false`
+     */
+    overwrite?: boolean;
+    /**
+     * Recursively create parent directories if needed. Default: `true`
+     */
+    recursive?: boolean;
+};
+/**
+ * Type for the `replacer` parameter of `JSON.stringify()`.
+ * Can be a function that alters the behavior of the stringification process,
+ * or an array of strings and numbers that acts as a whitelist for selecting
+ * the properties of the value object to be included in the JSON string.
+ * If this value is null or not provided, all properties of the object are included in the resulting JSON string.
+ */
+export type JsonReplacer = (number | string)[] | ((this: unknown, key: string, value: unknown) => unknown) | null;
+/**
+ * Type for the `replacer` parameter used in YAML serialization, similar to `JSON.stringify`'s replacer.
+ */
+export type YamlReplacer = JsonReplacer;
+/**
+ * Options for writing JSON files.
+ * Extends {@link WriteFileOptions}.
+ */
+export type WriteJsonOptions = WriteFileOptions & {
+    /**
+     * Detect indentation automatically if the file exists. Default: `false`
+     */
+    detectIndent?: boolean;
+    /**
+     * The space used for pretty-printing.
+     *
+     * Pass in `undefined` for no formatting.
+     */
+    indent?: number | string | undefined;
+    /**
+     * Passed into `JSON.stringify`.
+     */
+    replacer?: JsonReplacer;
+    /**
+     * Override the default `JSON.stringify` method.
+     */
+    stringify?: (data: unknown, replacer: JsonReplacer, space: number | string | undefined) => string;
+};
+/**
+ * Options for the `findUp` and `findUpSync` functions.
+ */
+export type FindUpOptions = {
+    /**
+     * Whether to follow symbolic links.
+     * @default undefined (behaves like `true` for `findUp`, `false` for `findUpSync` due to `fs.stat` vs `fs.lstat`)
+     */
+    allowSymlinks?: boolean;
+    /**
+     * The current working directory.
+     * @default process.cwd()
+     */
+    cwd?: URL | string;
+    /**
+     * The directory to stop searching at.
+     * @default path.parse(cwd).root
+     */
+    stopAt?: URL | string;
+    /**
+     * The type of path to find.
+     * @default "file"
+     */
+    type?: "directory" | "file";
+};
+/**
+ * The result type for the name matcher function used in `findUp`.
+ * It can be a `PathLike` (string, Buffer, or URL), a Promise resolving to `PathLike` or `FIND_UP_STOP`,
+ * `FIND_UP_STOP` to stop the search, or `undefined` to continue.
+ */
+export type FindUpNameFnResult = PathLike | Promise<PathLike | typeof FIND_UP_STOP> | typeof FIND_UP_STOP | undefined;
+/**
+ * Specifies the name(s) of the file or directory to search for in `findUp`.
+ * Can be a single name, an array of names, or a function that returns a name or `FIND_UP_STOP`.
+ */
+export type FindUpName = string[] | string | ((directory: string) => FindUpNameFnResult);
+/**
+ * The result type for the name matcher function used in `findUpSync`.
+ * It can be a `PathLike` (string, Buffer, or URL), `FIND_UP_STOP` to stop the search,
+ * or `undefined` to continue.
+ */
+export type FindUpNameSyncFnResult = PathLike | typeof FIND_UP_STOP | undefined;
+/**
+ * Specifies the name(s) of the file or directory to search for in `findUpSync`.
+ * Can be a single name, an array of names, or a function that returns a name or `FIND_UP_STOP`.
+ */
+export type FindUpNameSync = string[] | string | ((directory: string) => FindUpNameSyncFnResult);
+/**
+ * Options for operations that might require retries, like `emptyDir` or `remove`.
+ */
+export type RetryOptions = {
+    /**
+     * If an `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or
+     * `EPERM` error is encountered, Node.js will retry the operation with a linear
+     * backoff wait of `retryDelay` ms longer on each try. This option represents the
+     * number of retries. This option is ignored if the `recursive` option is not
+     * `true` for operations that support it (like `rm`).
+     * @default 0
+     */
+    maxRetries?: number | undefined;
+    /**
+     * The amount of time in milliseconds to wait between retries.
+     * This option is ignored if the `recursive` option is not `true` for operations that support it.
+     * @default 100
+     */
+    retryDelay?: number | undefined;
+};
+/**
+ * Options for reading YAML files.
+ * Combines options from `yaml` library (DocumentOptions, ParseOptions, SchemaOptions, ToJSOptions)
+ * and custom {@link ReadFileOptions}.
+ * @template C - The type of compression used.
+ */
+export type ReadYamlOptions<C> = DocumentOptions & ParseOptions & ReadFileOptions<C> & SchemaOptions & ToJSOptions;
+/**
+ * Type for the `reviver` parameter used in YAML deserialization, similar to `JSON.parse`'s reviver.
+ * A function that transforms the results. This function is called for each member of the object.
+ * If a member contains nested objects, the nested objects are transformed before the parent object is.
+ */
+export type YamlReviver = (key: unknown, value: unknown) => unknown;
+/**
+ * Options for writing YAML files.
+ * Extends {@link WriteFileOptions} and includes options from the `yaml` library for stringification.
+ */
+export type WriteYamlOptions = CreateNodeOptions & DocumentOptions & ParseOptions & SchemaOptions & ToStringOptions & WriteFileOptions & {
+    /**
+     * Passed into `yaml.stringify` as the replacer argument.
+     */
+    replacer?: YamlReplacer;
+    /**
+     * Passed into `yaml.stringify` as the space argument for indentation.
+     * Can be a number of spaces or a string (e.g., a tab character).
+     */
+    space?: number | string;
+};
+export {};

package/dist/utils/assert-valid-file-contents.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Asserts that the provided contents are valid for writing to a file.
+ * Valid contents can be a string, an ArrayBuffer, or an ArrayBuffer view (e.g., Uint8Array).
+ * @param contents The file contents to validate.
+ * @throws {TypeError} If the contents are not a string, ArrayBuffer, or ArrayBuffer view.
+ * @example
+ * ```javascript
+ * import { assertValidFileContents } from "@visulima/fs"; // Assuming this util is exported
+ *
+ * try {
+ *   assertValidFileContents("Hello, world!");
+ *   assertValidFileContents(new Uint8Array([72, 101, 108, 108, 111])); // "Hello"
+ *   assertValidFileContents(new ArrayBuffer(8));
+ *   console.log("File contents are valid.");
+ * } catch (error) {
+ *   console.error(error.message); // File contents must be a string, ArrayBuffer, or ArrayBuffer view.
+ * }
+ *
+ * try {
+ *   assertValidFileContents(123); // Invalid content type
+ * } catch (error) {
+ *   console.error(error.message); // File contents must be a string, ArrayBuffer, or ArrayBuffer view.
+ * }
+ * ```
+ */
+declare const assertValidFileContents: (contents: any) => void;
+export default assertValidFileContents;

package/dist/utils/assert-valid-file-or-directory-path.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Asserts that the provided path is a valid file or directory path.
+ * A valid path must be a non-empty string or a URL instance.
+ * @param fileOrDirectoryPath The path to validate.
+ * @throws {TypeError} If the path is not a non-empty string or a URL.
+ * @example
+ * ```javascript
+ * import { assertValidFileOrDirectoryPath } from "@visulima/fs"; // Assuming this util is exported
+ *
+ * try {
+ *   assertValidFileOrDirectoryPath("/path/to/file.txt");
+ *   assertValidFileOrDirectoryPath(new URL("file:///path/to/file.txt"));
+ *   console.log("Path is valid.");
+ * } catch (error) {
+ *   console.error(error.message); // Path must be a non-empty string or URL.
+ * }
+ *
+ * try {
+ *   assertValidFileOrDirectoryPath(""); // Invalid path
+ * } catch (error) {
+ *   console.error(error.message); // Path must be a non-empty string or URL.
+ * }
+ * ```
+ */
+declare const assertValidFileOrDirectoryPath: (fileOrDirectoryPath: any) => void;
+export default assertValidFileOrDirectoryPath;

package/dist/utils/parse-json.d.ts

@@ -0,0 +1,5 @@
+import type { JsonValue } from "type-fest";
+import type { CodeFrameOptions, JsonReviver } from "../types.d.ts";
+declare function parseJson<T = JsonValue>(string: string, filename?: string, options?: CodeFrameOptions): T;
+declare function parseJson<T = JsonValue>(string: string, reviver: JsonReviver, fileName?: string, options?: CodeFrameOptions): T;
+export default parseJson;

package/dist/utils/strip-json-comments.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Strips comments from a JSON string.
+ * Handles both single-line (//) and multi-line (/* ... */) comments.
+ * @param jsonString The JSON string possibly containing comments.
+ * @param [options] Optional configuration for stripping comments.
+ * @param [options.whitespace] If `true` (default), comments are replaced with whitespace to preserve line numbers and character positions. If `false`, comments are removed entirely.
+ * @returns The JSON string with comments stripped.
+ * @example
+ * ```javascript
+ * import { stripJsonComments } from "@visulima/fs"; // Assuming this util is exported
+ *
+ * const jsonWithComments = `{
+ *   // This is a single-line comment
+ *   "name": "John Doe",
+ *   "age": 30, /* This is a
+ *   multi-line comment */
+ *   "city": "New York"
+ * }`;
+ *
+ * const stripped = stripJsonComments(jsonWithComments);
+ * console.log(stripped);
+ * // Output (with whitespace=true):
+ * // {
+ * //
+ * //   "name": "John Doe",
+ * //   "age": 30, /*
+ * //
+ * //   "city": "New York"
+ * // }
+ *
+ * const strippedWithoutWhitespace = stripJsonComments(jsonWithComments, { whitespace: false });
+ * console.log(strippedWithoutWhitespace);
+ * // Output (with whitespace=false):
+ * // {
+ * //   "name": "John Doe",
+ * //   "age": 30,
+ * //   "city": "New York"
+ * // }
+ * ```
+ */
+declare const stripJsonComments: (jsonString: string, options?: {
+    whitespace?: boolean;
+}) => string;
+export default stripJsonComments;