@catbee/utils 0.0.8-rc.0 → 0.0.8-rc.2

package/build/src/utils/fs.utils.js

@@ -1,372 +0,0 @@
-"use strict";
-/*
- * 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.
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.fileExists = fileExists;
-exports.readJsonFile = readJsonFile;
-exports.writeJsonFile = writeJsonFile;
-exports.deleteFileIfExists = deleteFileIfExists;
-exports.readTextFile = readTextFile;
-exports.writeTextFile = writeTextFile;
-exports.appendTextFile = appendTextFile;
-exports.copyFile = copyFile;
-exports.moveFile = moveFile;
-exports.getFileStats = getFileStats;
-exports.createTempFile = createTempFile;
-exports.streamFile = streamFile;
-exports.readDirectory = readDirectory;
-exports.createDirectory = createDirectory;
-exports.safeReadJsonFile = safeReadJsonFile;
-exports.isFile = isFile;
-exports.getFileSize = getFileSize;
-exports.readFileBuffer = readFileBuffer;
-const promises_1 = __importDefault(require("fs/promises"));
-const fs_1 = require("fs");
-const os_1 = require("os");
-const path_1 = __importDefault(require("path"));
-const promises_2 = require("stream/promises");
-const crypto_1 = require("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.
- */
-async function fileExists(path) {
-    try {
-        await promises_1.default.access(path);
-        return true;
-    }
-    catch (_a) {
-        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.
- */
-async function readJsonFile(path) {
-    try {
-        const data = await promises_1.default.readFile(path, 'utf-8');
-        return JSON.parse(data);
-    }
-    catch (_a) {
-        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.
- */
-async function writeJsonFile(path, data, space = 2) {
-    const json = JSON.stringify(data, null, space);
-    await promises_1.default.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.
- */
-async function deleteFileIfExists(path) {
-    try {
-        await promises_1.default.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.
- */
-async function readTextFile(path, encoding = 'utf-8') {
-    try {
-        return await promises_1.default.readFile(path, encoding);
-    }
-    catch (_a) {
-        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.
- */
-async function writeTextFile(path, content, encoding = 'utf-8') {
-    try {
-        await promises_1.default.writeFile(path, content, encoding);
-        return true;
-    }
-    catch (_a) {
-        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.
- */
-async function appendTextFile(path, content, encoding = 'utf-8') {
-    try {
-        await promises_1.default.appendFile(path, content, encoding);
-        return true;
-    }
-    catch (_a) {
-        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.
- */
-async function copyFile(source, destination, overwrite = false) {
-    try {
-        const flags = overwrite ? 0 : promises_1.default.constants.COPYFILE_EXCL;
-        await promises_1.default.copyFile(source, destination, flags);
-        return true;
-    }
-    catch (_a) {
-        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.
- */
-async function moveFile(oldPath, newPath) {
-    try {
-        await promises_1.default.rename(oldPath, newPath);
-        return true;
-    }
-    catch (_a) {
-        // If rename fails (e.g., across devices), try copy+delete
-        try {
-            await promises_1.default.copyFile(oldPath, newPath);
-            await promises_1.default.unlink(oldPath);
-            return true;
-        }
-        catch (_b) {
-            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.
- */
-async function getFileStats(path) {
-    try {
-        return await promises_1.default.stat(path);
-    }
-    catch (_a) {
-        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.
- */
-async function createTempFile({ prefix = 'tmp-', extension = '', dir = (0, os_1.tmpdir)(), content } = {}) {
-    const ext = extension ? (extension.startsWith('.') ? extension : `.${extension}`) : '';
-    const filename = `${prefix}${(0, crypto_1.randomUUID)()}${ext}`;
-    const filepath = path_1.default.join(dir, filename);
-    if (content) {
-        await promises_1.default.writeFile(filepath, content);
-    }
-    else {
-        await promises_1.default.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.
- */
-async function streamFile(source, destination) {
-    const readStream = (0, fs_1.createReadStream)(source);
-    const writeStream = (0, fs_1.createWriteStream)(destination);
-    try {
-        await (0, promises_2.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.
- */
-async function readDirectory(dirPath, options = {}) {
-    const files = await promises_1.default.readdir(dirPath);
-    let result = files;
-    if (options.filter) {
-        result = result.filter(file => options.filter.test(file));
-    }
-    if (options.fullPaths) {
-        result = result.map(file => path_1.default.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.
- */
-async function createDirectory(dirPath, recursive = true) {
-    try {
-        await promises_1.default.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.
- */
-async function safeReadJsonFile(path) {
-    try {
-        const content = await promises_1.default.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.
- */
-async function isFile(path) {
-    try {
-        const stat = await promises_1.default.stat(path);
-        return stat.isFile();
-    }
-    catch (_a) {
-        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.
- */
-async function getFileSize(path) {
-    try {
-        const stat = await promises_1.default.stat(path);
-        return stat.size;
-    }
-    catch (_a) {
-        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.
- */
-async function readFileBuffer(path) {
-    try {
-        return await promises_1.default.readFile(path);
-    }
-    catch (_a) {
-        return null;
-    }
-}
-//# sourceMappingURL=fs.utils.js.map

package/build/src/utils/fs.utils.js.map

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

package/build/src/utils/http-status-codes.d.ts

@@ -1,266 +0,0 @@
-/**
- * Complete HTTP status codes enum with descriptions.
- * For use with API responses and error handling.
- */
-export declare enum HttpStatusCodes {
-    /**
-     * The server has received the request headers and the client should proceed to send the request body.
-     */
-    CONTINUE = 100,
-    /**
-     * The server is switching protocols according to the client's request.
-     */
-    SWITCHING_PROTOCOLS = 101,
-    /**
-     * Server has received the request and is still processing it.
-     */
-    PROCESSING = 102,
-    /**
-     * The server is sending preliminary headers while preparing the final response.
-     */
-    EARLY_HINTS = 103,
-    /**
-     * The request succeeded. The result meaning depends on the HTTP method used.
-     */
-    OK = 200,
-    /**
-     * The request succeeded and a new resource was created as a result.
-     */
-    CREATED = 201,
-    /**
-     * The request has been received but not yet acted upon.
-     */
-    ACCEPTED = 202,
-    /**
-     * The returned information is from a third-party source, not the origin server.
-     */
-    NON_AUTHORITATIVE_INFORMATION = 203,
-    /**
-     * The request succeeded but there's no content to send in the response.
-     */
-    NO_CONTENT = 204,
-    /**
-     * The client should reset the document view that caused this request.
-     */
-    RESET_CONTENT = 205,
-    /**
-     * The server is delivering only part of the resource due to a range header sent by the client.
-     */
-    PARTIAL_CONTENT = 206,
-    /**
-     * Conveys information about multiple resources, for complex operations.
-     */
-    MULTI_STATUS = 207,
-    /**
-     * The members of a DAV binding have already been enumerated and are not included in the response.
-     */
-    ALREADY_REPORTED = 208,
-    /**
-     * The server has fulfilled a request for the resource, and the response represents the result of one or more instance-manipulations.
-     */
-    IM_USED = 226,
-    /**
-     * The request has more than one possible response and the client should choose one.
-     */
-    MULTIPLE_CHOICES = 300,
-    /**
-     * The resource has been permanently moved to a new URL.
-     */
-    MOVED_PERMANENTLY = 301,
-    /**
-     * The resource has been temporarily moved to another URL.
-     */
-    MOVED_TEMPORARILY = 302,
-    /**
-     * The response to the request can be found under another URI using the GET method.
-     */
-    SEE_OTHER = 303,
-    /**
-     * The resource hasn't been modified since the last request.
-     */
-    NOT_MODIFIED = 304,
-    /**
-     * @deprecated
-     * Response must be accessed through a proxy.
-     */
-    USE_PROXY = 305,
-    /**
-     * The resource is temporarily available at a different URI, using the same HTTP method.
-     */
-    TEMPORARY_REDIRECT = 307,
-    /**
-     * The resource has been permanently moved to another URL, using the same HTTP method.
-     */
-    PERMANENT_REDIRECT = 308,
-    /**
-     * The server cannot process the request due to a client error (malformed request).
-     */
-    BAD_REQUEST = 400,
-    /**
-     * Authentication is required and has failed or not been provided.
-     */
-    UNAUTHORIZED = 401,
-    /**
-     * Reserved for future use, originally intended for digital payment systems.
-     */
-    PAYMENT_REQUIRED = 402,
-    /**
-     * The client doesn't have permission to access the requested resource.
-     */
-    FORBIDDEN = 403,
-    /**
-     * The requested resource could not be found on the server.
-     */
-    NOT_FOUND = 404,
-    /**
-     * The request method is not supported for the requested resource.
-     */
-    METHOD_NOT_ALLOWED = 405,
-    /**
-     * The server can't provide a response matching the list of acceptable values in the client's headers.
-     */
-    NOT_ACCEPTABLE = 406,
-    /**
-     * Authentication by a proxy is required.
-     */
-    PROXY_AUTHENTICATION_REQUIRED = 407,
-    /**
-     * The server timed out waiting for the request.
-     */
-    REQUEST_TIMEOUT = 408,
-    /**
-     * The request conflicts with the current state of the server.
-     */
-    CONFLICT = 409,
-    /**
-     * The resource has been permanently deleted with no forwarding address.
-     */
-    GONE = 410,
-    /**
-     * The server requires a Content-Length header field.
-     */
-    LENGTH_REQUIRED = 411,
-    /**
-     * Preconditions in the client's headers failed.
-     */
-    PRECONDITION_FAILED = 412,
-    /**
-     * Request entity is larger than limits defined by server.
-     */
-    REQUEST_TOO_LONG = 413,
-    /**
-     * The request payload exceeds server size limits.
-     * Modern equivalent of REQUEST_TOO_LONG.
-     */
-    PAYLOAD_TOO_LARGE = 413,
-    /**
-     * The URI requested is too long for the server to interpret.
-     */
-    REQUEST_URI_TOO_LONG = 414,
-    /**
-     * The server does not support the media type requested by the client.
-     */
-    UNSUPPORTED_MEDIA_TYPE = 415,
-    /**
-     * The range specified by the Range header cannot be fulfilled.
-     */
-    REQUESTED_RANGE_NOT_SATISFIABLE = 416,
-    /**
-     * The server cannot meet the expectations given in the Expect header.
-     */
-    EXPECTATION_FAILED = 417,
-    /**
-     * The server refuses to brew coffee because it is a teapot. (April Fools' joke)
-     */
-    IM_A_TEAPOT = 418,
-    /**
-     * The server cannot store the representation needed to complete the request.
-     */
-    INSUFFICIENT_SPACE_ON_RESOURCE = 419,
-    /**
-     * @deprecated
-     * A method has failed - specific to Spring Framework.
-     */
-    METHOD_FAILURE = 420,
-    /**
-     * The server cannot produce a response for the requested URI scheme and authority.
-     */
-    MISDIRECTED_REQUEST = 421,
-    /**
-     * The request was well-formed but has semantic errors preventing processing.
-     */
-    UNPROCESSABLE_ENTITY = 422,
-    /**
-     * The requested resource is locked against access.
-     */
-    LOCKED = 423,
-    /**
-     * The request failed due to the failure of a previous request.
-     */
-    FAILED_DEPENDENCY = 424,
-    /**
-     * The client should switch to a different protocol.
-     */
-    UPGRADE_REQUIRED = 426,
-    /**
-     * The server requires conditional requests to prevent lost updates.
-     */
-    PRECONDITION_REQUIRED = 428,
-    /**
-     * The client has sent too many requests in a given time period (rate limiting).
-     */
-    TOO_MANY_REQUESTS = 429,
-    /**
-     * Request headers are too large for the server to process.
-     */
-    REQUEST_HEADER_FIELDS_TOO_LARGE = 431,
-    /**
-     * Resource cannot be legally provided (e.g., censored by government).
-     */
-    UNAVAILABLE_FOR_LEGAL_REASONS = 451,
-    /**
-     * The server encountered an unexpected error preventing it from fulfilling the request.
-     */
-    INTERNAL_SERVER_ERROR = 500,
-    /**
-     * The server does not support the functionality required to fulfill the request.
-     */
-    NOT_IMPLEMENTED = 501,
-    /**
-     * The server, acting as a gateway, received an invalid response from an upstream server.
-     */
-    BAD_GATEWAY = 502,
-    /**
-     * The server is currently unable to handle the request due to temporary overload or maintenance.
-     */
-    SERVICE_UNAVAILABLE = 503,
-    /**
-     * The server, acting as a gateway, did not receive a timely response from an upstream server.
-     */
-    GATEWAY_TIMEOUT = 504,
-    /**
-     * The server does not support the HTTP protocol version used in the request.
-     */
-    HTTP_VERSION_NOT_SUPPORTED = 505,
-    /**
-     * Transparent content negotiation for the request resulted in circular reference.
-     */
-    VARIANT_ALSO_NEGOTIATES = 506,
-    /**
-     * The server cannot store the representation needed to complete the request.
-     */
-    INSUFFICIENT_STORAGE = 507,
-    /**
-     * The server detected an infinite loop while processing the request.
-     */
-    LOOP_DETECTED = 508,
-    /**
-     * Further extensions to the request are required for the server to fulfill it.
-     */
-    NOT_EXTENDED = 510,
-    /**
-     * The client needs to authenticate to gain network access.
-     */
-    NETWORK_AUTHENTICATION_REQUIRED = 511
-}
-//# sourceMappingURL=http-status-codes.d.ts.map