@catbee/utils/build/esnext/utils/env.utils.d.ts

A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.

/**
 * Enum representing valid application environments.
 */
export declare enum Environment {
    PRODUCTION = "production",
    DEVELOPMENT = "development",
    STAGING = "staging",
    TESTING = "testing"
}
/**
 * Utility class for accessing and managing environment variables.
 * Provides typed getters with fallback defaults and validation.
 */
export declare class Env {
    /**
     * Checks if the current NODE_ENV is 'development'.
     *
     * @returns {boolean} `true` if NODE_ENV is 'development', else `false`.
     */
    static isDev(): boolean;
    /**
     * Checks if the current NODE_ENV is 'production'.
     *
     * @returns {boolean} `true` if NODE_ENV is 'production', else `false`.
     */
    static isProd(): boolean;
    /**
     * Checks if the current NODE_ENV is 'testing'.
     *
     * @returns {boolean} `true` if NODE_ENV is 'testing', else `false`.
     */
    static isTest(): boolean;
    /**
     * Checks if the current NODE_ENV is 'staging'.
     *
     * @returns {boolean} `true` if NODE_ENV is 'staging', else `false`.
     */
    static isStaging(): boolean;
    /**
     * Sets an environment variable (only affects runtime memory).
     *
     * @param {string} key - The environment variable key.
     * @param {string} value - The value to set.
     */
    static set(key: string, value: string): void;
    /**
     * Returns all environment variables as an object.
     *
     * @returns {object} The current `process.env` object.
     */
    static getAll(): object;
    /**
     * Retrieves a string environment variable with a fallback default.
     *
     * @param {string} key - The environment variable key.
     * @param {string} [defaultValue] - Value to return if the key is missing.
     * @returns {string | undefined} The env value or the fallback.
     */
    static get(key: string, defaultValue?: string): string | undefined;
    /**
     * Retrieves a string environment variable and throws if it's missing.
     *
     * @param {string} key - The environment variable key.
     * @returns {string} The environment variable's value.
     * @throws {Error} If the variable is not defined.
     */
    static getRequired(key: string): string;
    /**
     * Retrieves an environment variable as a number, or returns a default.
     *
     * @param {string} key - The environment variable key.
     * @param {number} defaultValue - Fallback number if key is not present.
     * @returns {number} Parsed numeric value or default.
     * @throws {Error} If the value is not a valid number.
     */
    static getNumber(key: string, defaultValue: number): number;
    /**
     * Retrieves a required environment variable as a number.
     *
     * @param {string} key - The environment variable key.
     * @returns {number} Parsed number.
     * @throws {Error} If the value is missing or not a number.
     */
    static getNumberRequired(key: string): number;
    /**
     * Retrieves an environment variable as a boolean.
     * Accepts `true`, `1`, `yes`, `on` as true; `false`, `0`, `no`, `off` as false.
     *
     * @param {string} key - The environment variable key.
     * @param {boolean} [defaultValue=false] - Optional fallback value if key is missing.
     * @returns {boolean} Parsed boolean.
     * @throws {Error} If the value is not a recognized boolean string.
     */
    static getBoolean(key: string, defaultValue?: boolean): boolean;
    /**
     * Retrieves a required environment variable as a boolean.
     *
     * @param {string} key - The environment variable key.
     * @returns {boolean} Parsed boolean value.
     * @throws {Error} If missing or invalid.
     */
    static getBooleanRequired(key: string): boolean;
    /**
     * Parses a stringified JSON object from an environment variable.
     *
     * @typeParam T - The type to parse as (defaults to `object`).
     * @param {string} key - The environment variable key.
     * @param {T} defaultValue - Value to return if key is missing.
     * @returns {T} Parsed object or default.
     * @throws {Error} If the value is not valid JSON.
     */
    static getJSON<T extends object = object>(key: string, defaultValue: T): T;
    /**
     * Parses a comma-separated string as an array.
     *
     * @typeParam T - The item type (optional, defaults to string).
     * @param {string} key - The environment variable key.
     * @param {T[]} [defaultValue=[]] - Array to return if value is empty or missing.
     * @param {string} [splitter=','] - Delimiter to split on.
     * @returns {string[] | T[]} An array of strings.
     */
    static getArray<T = string>(key: string, defaultValue?: T[], splitter?: string): string[] | T[];
    /**
     * Retrieves an enum-like environment variable value, validating against allowed values.
     *
     * @typeParam T - The allowed value type (string literal types).
     * @param {string} key - The environment variable key.
     * @param {T[]} allowedValues - Array of accepted string values.
     * @param {T} [defaultValue] - Optional fallback value.
     * @returns {T} The validated environment value.
     * @throws {Error} If missing or invalid.
     */
    static getEnum<T extends string>(key: string, allowedValues: T[], defaultValue?: T): T;
    /**
     * Retrieves a URL environment variable and validates it.
     *
     * @param {string} key - The environment variable key.
     * @param {string} [defaultValue] - Optional fallback value.
     * @param {object} [options] - Validation options.
     * @param {string[]} [options.protocols] - Allowed protocols.
     * @param {boolean} [options.requireTld=true] - Whether TLD is required.
     * @returns {string} The validated URL.
     * @throws {Error} If URL is invalid.
     */
    static getUrl(key: string, defaultValue?: string, options?: {
        protocols?: string[];
        requireTld?: boolean;
    }): string;
    /**
     * Retrieves an email environment variable and validates it.
     *
     * @param {string} key - The environment variable key.
     * @param {string} [defaultValue] - Optional fallback value.
     * @returns {string} The validated email address.
     * @throws {Error} If email is invalid.
     */
    static getEmail(key: string, defaultValue?: string): string;
    /**
     * Retrieves a path environment variable and validates it exists.
     *
     * @param {string} key - The environment variable key.
     * @param {string} [defaultValue] - Optional fallback value.
     * @param {object} [options] - Validation options.
     * @param {boolean} [options.mustExist=false] - Whether path must exist.
     * @param {boolean} [options.makeAbsolute=true] - Convert relative paths to absolute.
     * @returns {string} The validated path.
     * @throws {Error} If path is invalid.
     */
    static getPath(key: string, defaultValue?: string, options?: {
        mustExist?: boolean;
        makeAbsolute?: boolean;
    }): string;
    /**
     * Retrieves a port environment variable and validates it.
     *
     * @param {string} key - The environment variable key.
     * @param {number} [defaultValue=3000] - Optional fallback value.
     * @returns {number} The validated port number.
     * @throws {Error} If port is invalid.
     */
    static getPort(key: string, defaultValue?: number): number;
    /**
     * Retrieves a duration string and converts to milliseconds.
     * Supports formats like "1d", "2h", "30m", "45s", "100ms" or combinations like "1h30m".
     *
     * @param {string} key - The environment variable key.
     * @param {string|number} [defaultValue='0'] - Optional fallback value.
     * @returns {number} The duration in milliseconds.
     * @throws {Error} If duration format is invalid.
     */
    static getDuration(key: string, defaultValue?: string | number): number;
    /**
     * Gets all environment variables with sensitive values masked for safe logging.
     *
     * @param {string[]} [sensitiveKeys=['password', 'secret', 'key', 'token', 'auth']] - Keys to mask.
     * @returns {Record<string, string>} Environment variables with sensitive values masked.
     */
    static getSafeEnv(sensitiveKeys?: string[]): Record<string, string>;
    /**
     * Checks whether the specified environment variable exists.
     *
     * @param {string} key - The environment variable key.
     * @returns {boolean} `true` if the variable is defined, otherwise `false`.
     */
    static has(key: string): boolean;
    /**
     * Deletes the given environment variable (useful in tests).
     *
     * @param {string} key - The environment variable key to delete.
     * @returns {void}
     */
    static delete(key: string): void;
}
//# sourceMappingURL=env.utils.d.ts.map