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

package/dist/size.d.ts

@@ -1,12 +1,256 @@
 import { Readable } from 'node:stream';
 import { URL } from 'node:url';
 import { BrotliOptions, ZlibOptions } from 'node:zlib';
+/**
+* Input type for size calculation functions.
+* Can be a Buffer, Readable stream, URL object, or string (file path or content).
+*/
 type SizeInput = Buffer | Readable | URL | string;
+/**
+* Input type for synchronous size calculation functions.
+* Can be a Buffer, URL object, or string (file path or content).
+*/
 type SizeInputSync = Buffer | URL | string;
+/**
+* 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);
+* ```
+*/
 declare const gzipSize: (input: SizeInput, 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);
+* ```
+*/
 declare const brotliSize: (input: SizeInput, 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);
+* ```
+*/
 declare const rawSize: (input: SizeInput) => 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
+* }
+* ```
+*/
 declare const gzipSizeSync: (input: SizeInputSync, 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
+* }
+* ```
+*/
 declare const brotliSizeSync: (input: SizeInputSync, 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
+* }
+* ```
+*/
 declare const rawSizeSync: (input: SizeInputSync) => number;
 export { brotliSize, brotliSizeSync, gzipSize, gzipSizeSync, rawSize, rawSizeSync };

package/dist/toml.d.ts

@@ -1,9 +1,63 @@
-import { a as CompressionType, h as ReadTomlOptions, i as WriteTomlOptions } from "./packem_shared/types.d-CYpAhWov.js";
+import { a as CompressionType, R as ReadTomlOptions, W as WriteTomlOptions } from "./packem_shared/types.d-CixEXeyM.js";
 import 'node:fs';
 import 'tinyglobby';
-import './options';
+/**
+* Asynchronously reads a TOML file and parses it into an object.
+* @template R The expected type of the parsed TOML object. Defaults to `Record<string, unknown>`.
+* @param path The path to the TOML file to read. Can be a file URL or a string path.
+* @param options Optional configuration for reading the file. See {@link ReadTomlOptions}.
+* @returns A promise that resolves with the parsed TOML object of type `R`.
+* @example
+* ```javascript
+* import { readToml } from "@visulima/fs/toml";
+* import { join } from "node:path";
+*
+* const config = await readToml(join("path", "to", "config.toml"));
+* ```
+*/
 declare const readToml: <R = Record<string, unknown>>(path: URL | string, options?: ReadTomlOptions<CompressionType>) => Promise<R>;
+/**
+* Synchronously reads a TOML file and parses it into an object.
+* @template R The expected type of the parsed TOML object. Defaults to `Record&lt;string, unknown>`.
+* @param path The path to the TOML file to read. Can be a file URL or a string path.
+* @param options Optional configuration for reading the file. See {@link ReadTomlOptions}.
+* @returns The parsed TOML object of type `R`.
+* @example
+* ```javascript
+* import { readTomlSync } from "@visulima/fs/toml";
+* import { join } from "node:path";
+*
+* const config = readTomlSync(join("path", "to", "config.toml"));
+* ```
+*/
 declare const readTomlSync: (path: URL | string, options?: ReadTomlOptions<CompressionType>) => Record<string, unknown>;
+/**
+* Asynchronously writes an object to a TOML file.
+* @param path The path to the TOML file to write. Can be a file URL or a string path.
+* @param data The data to serialize. Must be a plain object compatible with `smol-toml.stringify`.
+* @param options Optional configuration for writing the TOML file. See {@link WriteTomlOptions}.
+* @returns A promise that resolves when the TOML file has been written.
+* @example
+* ```javascript
+* import { writeToml } from "@visulima/fs/toml";
+* import { join } from "node:path";
+*
+* await writeToml(join("/tmp", "config.toml"), { name: "app", version: 1 });
+* ```
+*/
 declare const writeToml: (path: URL | string, data: Record<string, unknown>, options?: WriteTomlOptions) => Promise<void>;
+/**
+* Synchronously writes an object to a TOML file.
+* @param path The path to the TOML file to write. Can be a file URL or a string path.
+* @param data The data to serialize. Must be a plain object compatible with `smol-toml.stringify`.
+* @param options Optional configuration for writing the TOML file. See {@link WriteTomlOptions}.
+* @example
+* ```javascript
+* import { writeTomlSync } from "@visulima/fs/toml";
+* import { join } from "node:path";
+*
+* writeTomlSync(join("/tmp", "config.toml"), { name: "app", version: 1 });
+* ```
+*/
 declare const writeTomlSync: (path: URL | string, data: Record<string, unknown>, options?: WriteTomlOptions) => void;
 export { type ReadTomlOptions, type WriteTomlOptions, readToml, readTomlSync, writeToml, writeTomlSync };

package/dist/utils.d.ts

@@ -1,14 +1,102 @@
-export { J as JSONError } from "./packem_shared/json-error.d-DgKaeuIf.js";
+export { J as JSONError } from "./packem_shared/json-error.d-DVILOyHc.js";
 import { JsonValue } from 'type-fest';
-import { C as CodeFrameOptions, J as JsonReviver } from "./packem_shared/types.d-CYpAhWov.js";
+import { C as CodeFrameOptions, J as JsonReviver } from "./packem_shared/types.d-CixEXeyM.js";
 export { toPath } from '@visulima/path/utils';
 import 'node:fs';
 import 'tinyglobby';
-import './options';
+/**
+* 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;
+/**
+* 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;
 declare function parseJson(string: string, filename?: string, options?: CodeFrameOptions): JsonValue;
 declare function parseJson(string: string, reviver: JsonReviver, fileName?: string, options?: CodeFrameOptions): JsonValue;
+/**
+* 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;

package/dist/yaml.d.ts

@@ -1,8 +1,7 @@
-import { a as CompressionType, R as ReadYamlOptions, Y as YamlReviver, W as WriteYamlOptions, b as JsonReplacer } from "./packem_shared/types.d-CYpAhWov.js";
-export { type c as YamlReplacer } from "./packem_shared/types.d-CYpAhWov.js";
+import { a as CompressionType, m as ReadYamlOptions, Y as YamlReviver, n as WriteYamlOptions, o as JsonReplacer } from "./packem_shared/types.d-CixEXeyM.js";
+export { type p as YamlReplacer } from "./packem_shared/types.d-CixEXeyM.js";
 import 'node:fs';
 import 'tinyglobby';
-import './options';
 declare function readYaml<R = Record<string, unknown>>(path: URL | string, options?: ReadYamlOptions<CompressionType>): Promise<R>;
 declare function readYaml<R = Record<string, unknown>>(path: URL | string, reviver?: YamlReviver, options?: ReadYamlOptions<CompressionType>): Promise<R>;
 declare function readYamlSync(path: URL | string, options?: ReadYamlOptions<CompressionType>): Record<string, unknown>;

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "@visulima/fs",
-  "version": "5.0.0-alpha.11",
+  "version": "5.0.0-alpha.13",
   "description": "Human friendly file system utilities for Node.js",
   "keywords": [
     "anolilab",
+    "brotli",
     "detect-newline",
     "dir",
     "directory",
-    "eol",
     "empty-dir",
     "ensure",
-    "ensure-file",
     "ensure-dir",
+    "ensure-file",
     "ensure-link",
     "ensure-symlink",
+    "eol",
     "file",
     "files",
     "filesystem",
@@ -23,10 +24,14 @@
     "folder",
     "fs",
     "fs-safe",
+    "gzip",
+    "ini",
+    "json",
+    "json5",
+    "jsonc",
+    "jsonc-parser",
     "look",
     "look-up",
-    "json",
-    "read-json",
     "match",
     "package",
     "parent",
@@ -34,12 +39,16 @@
     "path",
     "read",
     "read-file",
+    "read-json",
     "read-yaml",
     "resolve",
     "safe",
     "search",
-    "std",
+    "size",
+    "smol-toml",
     "standard",
+    "std",
+    "toml",
     "up",
     "visulima",
     "walk",
@@ -48,16 +57,7 @@
     "write-dir",
     "write-file",
     "write-safe",
-    "yaml",
-    "toml",
-    "jsonc",
-    "json5",
-    "ini",
-    "smol-toml",
-    "jsonc-parser",
-    "size",
-    "brotli",
-    "gzip"
+    "yaml"
   ],
   "homepage": "https://visulima.com/packages/fs/",
   "bugs": {
@@ -151,15 +151,14 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@visulima/path": "3.0.0-alpha.9",
-    "type-fest": "5.6.0"
+    "@visulima/path": "3.0.0-alpha.10"
   },
   "peerDependencies": {
     "ini": "^6.0.0",
     "json5": "^2.2.3",
     "jsonc-parser": "^3.3.1",
     "smol-toml": "^1.6.1",
-    "yaml": "2.8.3"
+    "yaml": "2.8.4"
   },
   "peerDependenciesMeta": {
     "ini": {

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

@@ -1,4 +0,0 @@
-import { G as GlobOptions } from "./types.d-CYpAhWov.js";
-declare const glob: (patterns: string | ReadonlyArray<string>, options?: GlobOptions) => Promise<string[]>;
-declare const globSync: (patterns: string | ReadonlyArray<string>, options?: GlobOptions) => string[];
-export { globSync as a, glob as g };

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

@@ -1,10 +0,0 @@
-declare class JSONError extends Error {
-  #private;
-  fileName: string | undefined;
-  codeFrame: string | undefined;
-  readonly name = "JSONError";
-  constructor(message: string);
-  get message(): string;
-  set message(message: string);
-}
-export { JSONError as J };