@catbee/utils 0.0.8-rc.3 → 1.0.1

package/build/esm/utils/fs.utils.d.ts

@@ -1,163 +0,0 @@
-import { BufferEncoding } from './crypto.utils';
-import { Stats } from 'fs';
-/**
- * Checks whether a file or directory exists at the given path.
- *
- * @param {string} path - The file or directory path to check.
- * @returns {Promise<boolean>} Resolves to `true` if the path exists, `false` otherwise.
- */
-export declare function fileExists(path: string): Promise<boolean>;
-/**
- * Reads and parses a JSON file from the specified path.
- *
- * @typeParam T - The expected type of the parsed JSON object.
- * @param {string} path - The path to the JSON file.
- * @returns {Promise<T | null>} The parsed object, or `null` if reading or parsing fails.
- */
-export declare function readJsonFile<T = any>(path: string): Promise<T | null>;
-/**
- * Writes a JavaScript object to a file as formatted JSON.
- *
- * @param {string} path - The destination file path.
- * @param {any} data - The object to serialize and write.
- * @param {number} [space=2] - Number of spaces for JSON formatting.
- * @returns {Promise<void>} Resolves when writing is complete.
- */
-export declare function writeJsonFile(path: string, data: any, space?: number): Promise<void>;
-/**
- * Deletes a file if it exists.
- *
- * @param {string} path - The file path to delete.
- * @returns {Promise<boolean>} Resolves to `true` if the file was deleted or didn't exist, `false` if deletion failed.
- */
-export declare function deleteFileIfExists(path: string): Promise<boolean>;
-/**
- * Reads a text file from the specified path.
- *
- * @param {string} path - The path to the text file.
- * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
- * @returns {Promise<string | null>} The file contents, or `null` if reading fails.
- */
-export declare function readTextFile(path: string, encoding?: BufferEncoding): Promise<string | null>;
-/**
- * Writes text content to a file.
- *
- * @param {string} path - The destination file path.
- * @param {string} content - The text content to write.
- * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export declare function writeTextFile(path: string, content: string, encoding?: BufferEncoding): Promise<boolean>;
-/**
- * Appends text content to a file.
- *
- * @param {string} path - The file path to append to.
- * @param {string} content - The text content to append.
- * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export declare function appendTextFile(path: string, content: string, encoding?: BufferEncoding): Promise<boolean>;
-/**
- * Copies a file from source to destination.
- *
- * @param {string} source - Source file path.
- * @param {string} destination - Destination file path.
- * @param {boolean} [overwrite=false] - Whether to overwrite if destination exists.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export declare function copyFile(source: string, destination: string, overwrite?: boolean): Promise<boolean>;
-/**
- * Renames/moves a file.
- *
- * @param {string} oldPath - Current file path.
- * @param {string} newPath - New file path.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export declare function moveFile(oldPath: string, newPath: string): Promise<boolean>;
-/**
- * Gets file stats if the file exists.
- *
- * @param {string} path - Path to the file.
- * @returns {Promise<fs.Stats | null>} File stats object or null if file doesn't exist.
- */
-export declare function getFileStats(path: string): Promise<Stats | null>;
-/**
- * Creates a temporary file with optional content.
- *
- * @param {object} [options] - Options for creating the temp file.
- * @param {string} [options.prefix="tmp-"] - Filename prefix.
- * @param {string} [options.extension=""] - File extension.
- * @param {string} [options.dir] - Directory to create the file in (defaults to OS temp dir).
- * @param {string | Buffer} [options.content] - Optional content to write to the file.
- * @returns {Promise<string>} Path to the created temporary file.
- */
-export declare function createTempFile({ prefix, extension, dir, content }?: {
-    prefix?: string;
-    extension?: string;
-    dir?: string;
-    content?: string | Buffer;
-}): Promise<string>;
-/**
- * Streams a file from source to destination.
- * Useful for large files to avoid loading the entire file into memory.
- *
- * @param {string} source - Source file path.
- * @param {string} destination - Destination file path.
- * @returns {Promise<void>} Resolves when streaming completes.
- * @throws {Error} If streaming fails.
- */
-export declare function streamFile(source: string, destination: string): Promise<void>;
-/**
- * Reads a directory and returns file names.
- *
- * @param {string} dirPath - Path to the directory.
- * @param {object} [options] - Options for reading the directory.
- * @param {boolean} [options.fullPaths=false] - Whether to return full paths.
- * @param {RegExp} [options.filter] - Optional regex to filter files.
- * @returns {Promise<string[]>} Array of file names or paths.
- * @throws {Error} If directory cannot be read.
- */
-export declare function readDirectory(dirPath: string, options?: {
-    fullPaths?: boolean;
-    filter?: RegExp;
-}): Promise<string[]>;
-/**
- * Creates a directory if it doesn't exist.
- *
- * @param {string} dirPath - Path to the directory.
- * @param {boolean} [recursive=true] - Whether to create parent directories.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export declare function createDirectory(dirPath: string, recursive?: boolean): Promise<boolean>;
-/**
- * Safely reads and parses a JSON file with error details.
- *
- * @typeParam T - The expected type of the parsed JSON object.
- * @param {string} path - The path to the JSON file.
- * @returns {Promise<{ data: T | null; error: Error | null }>} Object with data and error properties.
- */
-export declare function safeReadJsonFile<T = any>(path: string): Promise<{
-    data: T | null;
-    error: Error | null;
-}>;
-/**
- * Checks if a path points to a file (not a directory).
- *
- * @param {string} path - Path to check.
- * @returns {Promise<boolean>} True if the path is a file, false otherwise.
- */
-export declare function isFile(path: string): Promise<boolean>;
-/**
- * Gets the size of a file in bytes.
- *
- * @param {string} path - Path to the file.
- * @returns {Promise<number>} Size in bytes or -1 if file doesn't exist.
- */
-export declare function getFileSize(path: string): Promise<number>;
-/**
- * Reads a file as a Buffer.
- *
- * @param {string} path - Path to the file.
- * @returns {Promise<Buffer | null>} File contents as Buffer or null if reading fails.
- */
-export declare function readFileBuffer(path: string): Promise<Buffer | null>;

package/build/esm/utils/fs.utils.js

@@ -1,348 +0,0 @@
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-import fs from 'fs/promises';
-import { createReadStream, createWriteStream } from 'fs';
-import { tmpdir } from 'os';
-import path from 'path';
-import { pipeline } from 'stream/promises';
-import { randomUUID } from 'crypto';
-/**
- * Checks whether a file or directory exists at the given path.
- *
- * @param {string} path - The file or directory path to check.
- * @returns {Promise<boolean>} Resolves to `true` if the path exists, `false` otherwise.
- */
-export async function fileExists(path) {
-    try {
-        await fs.access(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Reads and parses a JSON file from the specified path.
- *
- * @typeParam T - The expected type of the parsed JSON object.
- * @param {string} path - The path to the JSON file.
- * @returns {Promise<T | null>} The parsed object, or `null` if reading or parsing fails.
- */
-export async function readJsonFile(path) {
-    try {
-        const data = await fs.readFile(path, 'utf-8');
-        return JSON.parse(data);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Writes a JavaScript object to a file as formatted JSON.
- *
- * @param {string} path - The destination file path.
- * @param {any} data - The object to serialize and write.
- * @param {number} [space=2] - Number of spaces for JSON formatting.
- * @returns {Promise<void>} Resolves when writing is complete.
- */
-export async function writeJsonFile(path, data, space = 2) {
-    const json = JSON.stringify(data, null, space);
-    await fs.writeFile(path, json, 'utf-8');
-}
-/**
- * Deletes a file if it exists.
- *
- * @param {string} path - The file path to delete.
- * @returns {Promise<boolean>} Resolves to `true` if the file was deleted or didn't exist, `false` if deletion failed.
- */
-export async function deleteFileIfExists(path) {
-    try {
-        await fs.unlink(path);
-        return true;
-    }
-    catch (err) {
-        if (err.code === 'ENOENT')
-            return true;
-        return false;
-    }
-}
-/**
- * Reads a text file from the specified path.
- *
- * @param {string} path - The path to the text file.
- * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
- * @returns {Promise<string | null>} The file contents, or `null` if reading fails.
- */
-export async function readTextFile(path, encoding = 'utf-8') {
-    try {
-        return await fs.readFile(path, encoding);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Writes text content to a file.
- *
- * @param {string} path - The destination file path.
- * @param {string} content - The text content to write.
- * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export async function writeTextFile(path, content, encoding = 'utf-8') {
-    try {
-        await fs.writeFile(path, content, encoding);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Appends text content to a file.
- *
- * @param {string} path - The file path to append to.
- * @param {string} content - The text content to append.
- * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export async function appendTextFile(path, content, encoding = 'utf-8') {
-    try {
-        await fs.appendFile(path, content, encoding);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Copies a file from source to destination.
- *
- * @param {string} source - Source file path.
- * @param {string} destination - Destination file path.
- * @param {boolean} [overwrite=false] - Whether to overwrite if destination exists.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export async function copyFile(source, destination, overwrite = false) {
-    try {
-        const flags = overwrite ? 0 : fs.constants.COPYFILE_EXCL;
-        await fs.copyFile(source, destination, flags);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Renames/moves a file.
- *
- * @param {string} oldPath - Current file path.
- * @param {string} newPath - New file path.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export async function moveFile(oldPath, newPath) {
-    try {
-        await fs.rename(oldPath, newPath);
-        return true;
-    }
-    catch {
-        // If rename fails (e.g., across devices), try copy+delete
-        try {
-            await fs.copyFile(oldPath, newPath);
-            await fs.unlink(oldPath);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-}
-/**
- * Gets file stats if the file exists.
- *
- * @param {string} path - Path to the file.
- * @returns {Promise<fs.Stats | null>} File stats object or null if file doesn't exist.
- */
-export async function getFileStats(path) {
-    try {
-        return await fs.stat(path);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Creates a temporary file with optional content.
- *
- * @param {object} [options] - Options for creating the temp file.
- * @param {string} [options.prefix="tmp-"] - Filename prefix.
- * @param {string} [options.extension=""] - File extension.
- * @param {string} [options.dir] - Directory to create the file in (defaults to OS temp dir).
- * @param {string | Buffer} [options.content] - Optional content to write to the file.
- * @returns {Promise<string>} Path to the created temporary file.
- */
-export async function createTempFile({ prefix = 'tmp-', extension = '', dir = tmpdir(), content } = {}) {
-    const ext = extension ? (extension.startsWith('.') ? extension : `.${extension}`) : '';
-    const filename = `${prefix}${randomUUID()}${ext}`;
-    const filepath = path.join(dir, filename);
-    if (content) {
-        await fs.writeFile(filepath, content);
-    }
-    else {
-        await fs.writeFile(filepath, '');
-    }
-    return filepath;
-}
-/**
- * Streams a file from source to destination.
- * Useful for large files to avoid loading the entire file into memory.
- *
- * @param {string} source - Source file path.
- * @param {string} destination - Destination file path.
- * @returns {Promise<void>} Resolves when streaming completes.
- * @throws {Error} If streaming fails.
- */
-export async function streamFile(source, destination) {
-    const readStream = createReadStream(source);
-    const writeStream = createWriteStream(destination);
-    try {
-        await pipeline(readStream, writeStream);
-    }
-    catch (error) {
-        // Ensure both streams are closed in case of error
-        readStream.destroy();
-        writeStream.destroy();
-        throw error;
-    }
-}
-/**
- * Reads a directory and returns file names.
- *
- * @param {string} dirPath - Path to the directory.
- * @param {object} [options] - Options for reading the directory.
- * @param {boolean} [options.fullPaths=false] - Whether to return full paths.
- * @param {RegExp} [options.filter] - Optional regex to filter files.
- * @returns {Promise<string[]>} Array of file names or paths.
- * @throws {Error} If directory cannot be read.
- */
-export async function readDirectory(dirPath, options = {}) {
-    const files = await fs.readdir(dirPath);
-    let result = files;
-    if (options.filter) {
-        result = result.filter(file => options.filter.test(file));
-    }
-    if (options.fullPaths) {
-        result = result.map(file => path.join(dirPath, file));
-    }
-    return result;
-}
-/**
- * Creates a directory if it doesn't exist.
- *
- * @param {string} dirPath - Path to the directory.
- * @param {boolean} [recursive=true] - Whether to create parent directories.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export async function createDirectory(dirPath, recursive = true) {
-    try {
-        await fs.mkdir(dirPath, { recursive });
-        return true;
-    }
-    catch (err) {
-        // Consider it success if directory already exists
-        return err.code === 'EEXIST';
-    }
-}
-/**
- * Safely reads and parses a JSON file with error details.
- *
- * @typeParam T - The expected type of the parsed JSON object.
- * @param {string} path - The path to the JSON file.
- * @returns {Promise<{ data: T | null; error: Error | null }>} Object with data and error properties.
- */
-export async function safeReadJsonFile(path) {
-    try {
-        const content = await fs.readFile(path, 'utf-8');
-        try {
-            const data = JSON.parse(content);
-            return { data, error: null };
-        }
-        catch (error) {
-            return {
-                data: null,
-                error: new Error(`Invalid JSON in file ${path}: ${error.message}`)
-            };
-        }
-    }
-    catch (error) {
-        return {
-            data: null,
-            error: new Error(`Failed to read file ${path}: ${error.message}`)
-        };
-    }
-}
-/**
- * Checks if a path points to a file (not a directory).
- *
- * @param {string} path - Path to check.
- * @returns {Promise<boolean>} True if the path is a file, false otherwise.
- */
-export async function isFile(path) {
-    try {
-        const stat = await fs.stat(path);
-        return stat.isFile();
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Gets the size of a file in bytes.
- *
- * @param {string} path - Path to the file.
- * @returns {Promise<number>} Size in bytes or -1 if file doesn't exist.
- */
-export async function getFileSize(path) {
-    try {
-        const stat = await fs.stat(path);
-        return stat.size;
-    }
-    catch {
-        return -1;
-    }
-}
-/**
- * Reads a file as a Buffer.
- *
- * @param {string} path - Path to the file.
- * @returns {Promise<Buffer | null>} File contents as Buffer or null if reading fails.
- */
-export async function readFileBuffer(path) {
-    try {
-        return await fs.readFile(path);
-    }
-    catch {
-        return null;
-    }
-}