@catbee/utils 0.0.3 → 0.0.5

package/build/esnext/utils/env.utils.d.ts

@@ -7,11 +7,36 @@ export declare enum Environment {
     STAGING = "staging",
     TESTING = "testing"
 }
+/**
+ * Options for validating URL environment variables
+ */
+export interface UrlOptions {
+    /** List of allowed protocols (e.g., ['http', 'https']) */
+    protocols?: string[];
+    /** Whether a top-level domain is required (default: true) */
+    requireTld?: boolean;
+    /** Whether to allow IP addresses (default: true) */
+    allowIp?: boolean;
+    /** Whether to allow localhost (default: true) */
+    allowLocalhost?: boolean;
+}
+/**
+ * Options for validating path environment variables
+ */
+export interface PathOptions {
+    /** Whether the path must exist on the filesystem (default: false) */
+    mustExist?: boolean;
+    /** Whether to convert relative paths to absolute (default: true) */
+    makeAbsolute?: boolean;
+    /** List of allowed file extensions */
+    allowedExtensions?: string[];
+}
 /**
  * Utility class for accessing and managing environment variables.
  * Provides typed getters with fallback defaults and validation.
  */
 export declare class Env {
+    private static cache;
     /**
      * Checks if the current NODE_ENV is 'development'.
      *
@@ -51,12 +76,18 @@ export declare class Env {
     static getAll(): object;
     /**
      * Retrieves a string environment variable with a fallback default.
+     * Supports variable expansion with ${VAR_NAME} syntax.
      *
      * @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.
+     * @returns {string} The env value or the fallback.
+     *
+     * @example
+     * // If DATABASE_URL is "postgres://localhost:5432/${DB_NAME}"
+     * // and DB_NAME is "myapp"
+     * const url = Env.get('DATABASE_URL', ''); // "postgres://localhost:5432/myapp"
      */
-    static get(key: string, defaultValue?: string): string | undefined;
+    static get(key: string, defaultValue: string): string;
     /**
      * Retrieves a string environment variable and throws if it's missing.
      *
@@ -65,6 +96,21 @@ export declare class Env {
      * @throws {Error} If the variable is not defined.
      */
     static getRequired(key: string): string;
+    /**
+     * Retrieves a value using a default generating function if the key doesn't exist.
+     * Useful for expensive default calculations.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {() => string} defaultFn - Function that generates default value.
+     * @returns {string} The environment value or generated default.
+     *
+     * @example
+     * const hostname = Env.getWithDefault('HOSTNAME', () => {
+     *   // Only called if HOSTNAME is not set
+     *   return require('os').hostname();
+     * });
+     */
+    static getWithDefault(key: string, defaultFn: () => string): string;
     /**
      * Retrieves an environment variable as a number, or returns a default.
      *
@@ -82,6 +128,24 @@ export declare class Env {
      * @throws {Error} If the value is missing or not a number.
      */
     static getNumberRequired(key: string): number;
+    /**
+     * Retrieves an integer environment variable and validates it.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {number} defaultValue - Fallback number if key is not present.
+     * @param {object} [options] - Validation options.
+     * @param {number} [options.min] - Minimum allowed value.
+     * @param {number} [options.max] - Maximum allowed value.
+     * @returns {number} The parsed integer.
+     *
+     * @example
+     * // Require PORT to be between 1000 and 9999
+     * const port = Env.getInteger('PORT', 3000, { min: 1000, max: 9999 });
+     */
+    static getInteger(key: string, defaultValue: number, options?: {
+        min?: number;
+        max?: number;
+    }): number;
     /**
      * Retrieves an environment variable as a boolean.
      * Accepts `true`, `1`, `yes`, `on` as true; `false`, `0`, `no`, `off` as false.
@@ -90,6 +154,10 @@ export declare class Env {
      * @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.
+     *
+     * @example
+     * // If DEBUG=yes
+     * const isDebug = Env.getBoolean('DEBUG', false); // true
      */
     static getBoolean(key: string, defaultValue?: boolean): boolean;
     /**
@@ -108,6 +176,11 @@ export declare class Env {
      * @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.
+     *
+     * @example
+     * // If CONFIG='{"debug":true,"api":{"url":"https://api.example.com"}}'
+     * const config = Env.getJSON('CONFIG', { debug: false });
+     * // { debug: true, api: { url: "https://api.example.com" }}
      */
     static getJSON<T extends object = object>(key: string, defaultValue: T): T;
     /**
@@ -117,9 +190,32 @@ export declare class Env {
      * @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.
+     * @param {(item: string) => T} [transform] - Optional function to transform each item.
+     * @returns {T[]} An array of items.
+     *
+     * @example
+     * // If ALLOWED_IPS=127.0.0.1,192.168.1.1,10.0.0.1
+     * const ips = Env.getArray('ALLOWED_IPS');
+     * // ["127.0.0.1", "192.168.1.1", "10.0.0.1"]
+     *
+     * // With transformation function
+     * const ports = Env.getArray('PORTS', [], ',', (p) => parseInt(p, 10));
+     */
+    static getArray<T = string>(key: string, defaultValue?: T[], splitter?: string, transform?: (item: string) => T): T[];
+    /**
+     * Parses a comma-separated list of numbers.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {number[]} [defaultValue=[]] - Default value if not present.
+     * @param {string} [splitter=','] - Delimiter to split on.
+     * @returns {number[]} Array of parsed numbers.
+     *
+     * @example
+     * // If ALLOWED_PORTS=80,443,3000,8080
+     * const ports = Env.getNumberArray('ALLOWED_PORTS');
+     * // [80, 443, 3000, 8080]
      */
-    static getArray<T = string>(key: string, defaultValue?: T[], splitter?: string): string[] | T[];
+    static getNumberArray(key: string, defaultValue?: number[], splitter?: string): number[];
     /**
      * Retrieves an enum-like environment variable value, validating against allowed values.
      *
@@ -129,23 +225,44 @@ export declare class Env {
      * @param {T} [defaultValue] - Optional fallback value.
      * @returns {T} The validated environment value.
      * @throws {Error} If missing or invalid.
+     *
+     * @example
+     * // If LOG_LEVEL=debug
+     * const level = Env.getEnum('LOG_LEVEL', ['debug', 'info', 'warn', 'error'] as const, 'info');
+     * // 'debug' (typed as 'debug' | 'info' | 'warn' | 'error')
+     */
+    static getEnum<T extends string>(key: string, allowedValues: readonly T[], defaultValue: T): T;
+    /**
+     * Retrieves an enum-like numeric environment variable.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {number[]} allowedValues - Array of accepted values.
+     * @param {number} defaultValue - Default value if not present.
+     * @returns {number} The validated value.
+     *
+     * @example
+     * // If NODE_VERSION=16
+     * const version = Env.getNumberEnum('NODE_VERSION', [14, 16, 18], 16);
      */
-    static getEnum<T extends string>(key: string, allowedValues: T[], defaultValue?: T): T;
+    static getNumberEnum(key: string, allowedValues: number[], defaultValue: number): number;
     /**
      * 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.
+     * @param {UrlOptions} [options] - Validation options.
      * @returns {string} The validated URL.
      * @throws {Error} If URL is invalid.
+     *
+     * @example
+     * // Validate API URL requires HTTPS
+     * const apiUrl = Env.getUrl('API_URL', 'https://api.example.com', {
+     *   protocols: ['https'],
+     *   requireTld: true,
+     *   allowIp: false
+     * });
      */
-    static getUrl(key: string, defaultValue?: string, options?: {
-        protocols?: string[];
-        requireTld?: boolean;
-    }): string;
+    static getUrl(key: string, defaultValue: string, options?: UrlOptions): string;
     /**
      * Retrieves an email environment variable and validates it.
      *
@@ -153,40 +270,65 @@ export declare class Env {
      * @param {string} [defaultValue] - Optional fallback value.
      * @returns {string} The validated email address.
      * @throws {Error} If email is invalid.
+     *
+     * @example
+     * const supportEmail = Env.getEmail('SUPPORT_EMAIL', 'support@example.com');
      */
-    static getEmail(key: string, defaultValue?: string): string;
+    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.
+     * @param {PathOptions} [options] - Validation options.
      * @returns {string} The validated path.
      * @throws {Error} If path is invalid.
+     *
+     * @example
+     * // Require that the path exists and is a .json file
+     * const configPath = Env.getPath('CONFIG_PATH', './config.json', {
+     *   mustExist: true,
+     *   allowedExtensions: ['.json', '.yaml']
+     * });
      */
-    static getPath(key: string, defaultValue?: string, options?: {
-        mustExist?: boolean;
-        makeAbsolute?: boolean;
-    }): string;
+    static getPath(key: string, defaultValue: string, options?: PathOptions): string;
     /**
      * Retrieves a port environment variable and validates it.
      *
      * @param {string} key - The environment variable key.
-     * @param {number} [defaultValue=3000] - Optional fallback value.
+     * @param {number} [defaultValue] - Optional fallback value.
      * @returns {number} The validated port number.
      * @throws {Error} If port is invalid.
+     *
+     * @example
+     * const serverPort = Env.getPort('PORT', 3000);
      */
-    static getPort(key: string, defaultValue?: number): number;
+    static getPort(key: string, defaultValue: number): number;
     /**
-     * Retrieves a duration string and converts to milliseconds.
+     * Retrieves an ISO date string and converts it to a Date object.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {string|Date} [defaultValue] - Optional fallback value.
+     * @returns {Date} The parsed Date object.
+     *
+     * @example
+     * // If EXPIRY_DATE=2023-12-31T23:59:59Z
+     * const expiryDate = Env.getDate('EXPIRY_DATE', new Date());
+     */
+    static getDate(key: string, defaultValue?: string | Date): Date;
+    /**
+     * Retrieves a duration string and converts it 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.
+     *
+     * @example
+     * // If CACHE_TTL=2h30m
+     * const cacheTtlMs = Env.getDuration('CACHE_TTL', '1h');
+     * // 9000000 (2.5 hours in milliseconds)
      */
     static getDuration(key: string, defaultValue?: string | number): number;
     /**
@@ -194,8 +336,24 @@ export declare class Env {
      *
      * @param {string[]} [sensitiveKeys=['password', 'secret', 'key', 'token', 'auth']] - Keys to mask.
      * @returns {Record<string, string>} Environment variables with sensitive values masked.
+     *
+     * @example
+     * console.log(Env.getSafeEnv(['password', 'secret', 'key']));
+     * // { DATABASE_URL: "postgres://...", API_KEY: "******", ... }
      */
     static getSafeEnv(sensitiveKeys?: string[]): Record<string, string>;
+    /**
+     * Loads environment variables from a .env file.
+     * Does not override existing variables.
+     *
+     * @param {string} [path='.env'] - Path to the .env file.
+     * @returns {Record<string, string>} Loaded environment variables.
+     *
+     * @example
+     * // Load variables from .env.development
+     * Env.loadFromFile('.env.development');
+     */
+    static loadFromFile(path?: string): Record<string, string>;
     /**
      * Checks whether the specified environment variable exists.
      *
@@ -210,5 +368,10 @@ export declare class Env {
      * @returns {void}
      */
     static delete(key: string): void;
+    /**
+     * Clears the internal cache of parsed environment values.
+     * Useful for testing or when environment variables might change.
+     */
+    static clearCache(): void;
 }
 //# sourceMappingURL=env.utils.d.ts.map