@visulima/fs/dist/size.d.ts

Human friendly file system utilities for Node.js

import { Readable } from "node:stream";
import { URL } from "node:url";
import type { 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);
 * ```
 */
export 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);
 * ```
 */
export 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);
 * ```
 */
export 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
 * }
 * ```
 */
export 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
 * }
 * ```
 */
export 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
 * }
 * ```
 */
export declare const rawSizeSync: (input: SizeInputSync) => number;
export {};