envapt 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,330 @@
+/**
+ * List of built-in converters for Envapt.
+ * @internal
+ */
+declare const ListOfBuiltInConverters: readonly ["string", "number", "boolean", "bigint", "symbol", "integer", "float", "json", "array", "url", "regexp", "date", "time"];
+
+/**
+ * Built-in converter types for common environment variable patterns
+ * @public
+ */
+type BuiltInConverter = (typeof ListOfBuiltInConverters)[number];
+/**
+ * Primitive types supported by Envapter
+ * @public
+ */
+type PrimitiveConstructor = typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol;
+type ValidArrayConverterBuiltInType = Exclude<BuiltInConverter, 'array' | 'json' | 'regexp'>;
+/**
+ * Array converter configuration for custom delimiters and element types
+ * @public
+ */
+interface ArrayConverter {
+    /**
+     * Delimiter to split the string by
+     */
+    delimiter: string;
+    /**
+     * Type to convert each array element to (excludes array, json, and regexp types)
+     */
+    type?: ValidArrayConverterBuiltInType;
+}
+/**
+ * String value from a .env file or environment variable
+ * @public
+ */
+type BaseInput = string | undefined;
+/**
+ * Custom parser function type for environment variables
+ * @param raw - Raw string value from environment
+ * @param fallback - Fallback value if parsing fails
+ * @returns Parsed value of type T
+ * @public
+ */
+type ConverterFunction<FallbackType = unknown> = (raw: BaseInput, fallback?: FallbackType) => FallbackType;
+/**
+ * Environment variable converter - can be a primitive constructor, built-in converter string, array converter object, or custom parser function
+ * @see {@link PrimitiveConstructor} for primitive types
+ * @see {@link BuiltInConverter} for built-in types
+ * @see {@link ArrayConverter} for array converter configuration
+ * @see {@link ConverterFunction} for custom parser functions
+ * @public
+ */
+type EnvaptConverter<FallbackType> = PrimitiveConstructor | BuiltInConverter | ArrayConverter | ConverterFunction<FallbackType>;
+/**
+ * Options for the \@Envapt decorator (modern API)
+ * @public
+ */
+interface EnvaptOptions<FallbackType = string> {
+    /**
+     * Default value to use if environment variable is not found
+     */
+    fallback?: FallbackType;
+    /**
+     * Built-in converter, custom converter function, or boxed-primitives (String, Number, Boolean)
+     */
+    converter?: EnvaptConverter<FallbackType>;
+}
+interface ConverterMap {
+    string: string;
+    number: number;
+    boolean: boolean;
+    bigint: bigint;
+    symbol: symbol;
+    integer: number;
+    float: number;
+    json: unknown;
+    array: string[];
+    url: URL;
+    regexp: RegExp;
+    date: Date;
+    time: number;
+}
+/**
+ * Type mapping for built-in converters to their return types
+ */
+type BuiltInConverterReturnType<ConverterKey extends BuiltInConverter = BuiltInConverter> = ConverterMap[ConverterKey];
+
+/**
+ * Instance/Static Property decorator that automatically loads and converts environment variables.
+ *
+ * Supports both modern options-based API and classic parameter-based API.
+ * Automatically detects types from fallback values and provides caching for performance.
+ *
+ * Note: Using \@Envapt on a variable for an env that doesn't exist will set the value to `null` if no fallback is provided, regardless of a converter being used.
+ *
+ * @param key - Environment variable name to load
+ * @param options - Configuration options (modern API)
+ *
+ * @example Modern API (recommended):
+ * ```ts
+ * class Config extends Envapter {
+ * ‎ ‎ \@Envapt('PORT', { fallback: 3000 })
+ * ‎ ‎ static readonly port: number;
+ *
+ * ‎ ‎ \@Envapt('FEATURES', { fallback: ['auth'], converter: 'array' })
+ * ‎ ‎ declare private readonly features: string[];
+ *
+ * ‎ ‎ \@Envapt('CONFIG', { converter: 'json' })
+ * ‎ ‎ static readonly config: object;
+ *
+ * ‎ ‎ \@Envapt('API_URL', { converter: 'url' })
+ * ‎ ‎ declare public readonly apiUrl: URL;
+ *
+ * ‎ ‎ \@Envapt('CUSTOM_LIST', {
+ * ‎ ‎ ‎ ‎ fallback: [1, 2, 3],
+ * ‎ ‎ ‎ ‎ converter: {
+ * ‎ ‎ ‎ ‎   delimiter: ',',
+ * ‎ ‎ ‎ ‎   type: 'number' // Convert each item to number
+ * ‎ ‎ ‎ ‎ }
+ * ‎ ‎ })
+ * ‎ ‎ static readonly customList: string[];
+ * }
+ * ```
+ *
+ * @param key - Environment variable name to load
+ * @param fallback - Default value if variable is not found. Only suppoerts primitive types (string, number, boolean, bigint, symbol).
+ * @param converter - Custom converter function or built-in converter
+ *
+ * @example Classic API
+ * ```ts
+ * class HealthCheck {
+ * ‎ ‎ \@Envapt('PORT', 3000) declare readonly port: number;
+ *
+ * ‎ ‎ // code to start server
+ * ‎ ‎ public start() {
+ * ‎ ‎ ‎ ‎ // works on instance properties
+ * ‎ ‎ ‎ ‎ console.log(`Server running on port ${this.port}`);
+ * ‎ ‎ }
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function Envapt<FallbackType = unknown>(key: string, options?: EnvaptOptions<FallbackType>): PropertyDecorator;
+declare function Envapt<FallbackType = string | number | boolean | bigint | symbol>(key: string, fallback?: FallbackType, converter?: EnvaptConverter<FallbackType>): PropertyDecorator;
+
+/**
+ * @internal
+ */
+interface EnvapterService {
+    getRaw(key: string): string | undefined;
+    get(key: string, def?: string): string;
+    getNumber(key: string, def?: number): number;
+    getBoolean(key: string, def?: boolean): boolean;
+}
+
+/**
+ * Environment types supported by Envapter
+ * @public
+ */
+declare enum Environment {
+    Development = 0,
+    Staging = 1,
+    Production = 2
+}
+/**
+ * Main configuration class for environment variable management.
+ *
+ * Provides both static and instance methods for retrieving typed environment variables
+ * with support for template resolution, multiple .env files, and environment detection.
+ *
+ * Extend your own classes from this to define properties with \@Envapt decorators and provide access to environment variables methods.
+ *
+ * @example
+ * ```ts
+ * // Static usage
+ * const port = Envapter.getNumber('PORT', 3000);
+ * const url = Envapter.get('API_URL', 'http://localhost');
+ *
+ * // Instance usage
+ * const env = new Envapter();
+ * const dbUrl = env.get('DATABASE_URL', 'sqlite://memory');
+ * ```
+ *
+ * @public
+ */
+declare class Envapter implements EnvapterService {
+    private static readonly parser;
+    private static _envPaths;
+    private static internalEnvironment;
+    /**
+     * Set custom .env file paths. Accepts either a single path or array of paths.
+     * Setting new paths clears the cache and reloads environment variables.
+     *
+     * @param paths - Single file path or array of file paths to load
+     *
+     * @example
+     * ```ts
+     * // Single file
+     * Envapter.envPaths = '.env.production';
+     *
+     * // Multiple files (loaded in order)
+     * Envapter.envPaths = ['.env', '.env.local', '.env.production'];
+     * ```
+     */
+    static set envPaths(paths: string[] | string);
+    /**
+     * Get currently configured .env file paths
+     * @returns Array of file paths being loaded
+     */
+    static get envPaths(): string[];
+    private static determineEnvironment;
+    /**
+     * Set the application environment. Accepts either Environment enum or string value.
+     *
+     * @param env - Environment value ('development', 'staging', 'production') or Environment enum
+     *
+     * @example
+     * ```ts
+     * Envapter.environment = Environment.Production;
+     * Envapter.environment = 'staging';
+     * ```
+     */
+    static set environment(env: string | Environment);
+    /**
+     * Get the current application environment
+     * @returns Current environment enum value
+     */
+    static get environment(): Environment;
+    /**
+     * Check if the current environment is production
+     * @returns true if environment is production
+     */
+    static get isProduction(): boolean;
+    /**
+     * Check if the current environment is staging
+     * @returns true if environment is staging
+     */
+    static get isStaging(): boolean;
+    /**
+     * Check if the current environment is development
+     * @returns true if environment is development
+     */
+    static get isDevelopment(): boolean;
+    private static get config();
+    private static _get;
+    /**
+     * Get a string environment variable with optional fallback.
+     * Supports template variable resolution using ${VAR} syntax.
+     *
+     * @param key - Environment variable name
+     * @param def - Default value if variable is not found
+     * @returns The environment variable value or default
+     *
+     * @example
+     * ```ts
+     * const apiUrl = Envapter.get('API_URL', 'http://localhost:3000');
+     * ```
+     */
+    static get(key: string, def?: string): string;
+    /**
+     * Get a number environment variable with optional fallback.
+     * Automatically converts string values to numbers.
+     *
+     * @param key - Environment variable name
+     * @param def - Default value if variable is not found or cannot be converted
+     * @returns The environment variable value as number or default
+     *
+     * @example
+     * ```ts
+     * const port = Envapter.getNumber('PORT', 3000);
+     * ```
+     */
+    static getNumber(key: string, def?: number): number;
+    /**
+     * Get a boolean environment variable with optional fallback.
+     * Recognizes: `1`, `yes`, `true` as **true**; `0`, `no`, `false` as **false** (case-insensitive).
+     *
+     * @param key - Environment variable name
+     * @param def - Default value if variable is not found or cannot be converted
+     * @returns The environment variable value as boolean or default
+     *
+     * @example
+     * ```ts
+     * const isProduction = Envapter.getBoolean('IS_PRODUCTION', false);
+     * ```
+     */
+    static getBoolean(key: string, def?: boolean): boolean;
+    /**
+     * Get a bigint environment variable with optional fallback.
+     * Automatically converts string values to bigint.
+     *
+     * @param key - Environment variable name
+     * @param def - Default value if variable is not found or cannot be converted
+     * @returns The environment variable value as bigint or default
+     *
+     * @example
+     * ```ts
+     * const largeNumber = Envapter.getBigInt('LARGE_NUMBER', 123456789012345678901234567890n);
+     * ```
+     */
+    static getBigInt(key: string, def?: bigint): bigint;
+    /**
+     * Get a symbol environment variable with optional fallback.
+     * Creates a symbol from the string value.
+     *
+     * @param key - Environment variable name
+     * @param def - Default value if variable is not found
+     * @returns The environment variable value as symbol or default
+     *
+     * @example
+     * ```ts
+     * const uniqueKey = Envapter.getSymbol('UNIQUE_KEY', Symbol('default'));
+     * ```
+     */
+    static getSymbol(key: string, def?: symbol): symbol;
+    get(key: string, def?: string): string;
+    getNumber(key: string, def?: number): number;
+    getBoolean(key: string, def?: boolean): boolean;
+    getBigInt(key: string, def?: bigint): bigint;
+    getSymbol(key: string, def?: symbol): symbol;
+    /**
+     * Get raw environment variable value without parsing or conversion.
+     *
+     * @internal
+     */
+    getRaw(key: string): string | undefined;
+}
+
+export { type ArrayConverter, type BaseInput, type BuiltInConverter, type BuiltInConverterReturnType, type ConverterFunction, Envapt, type EnvaptConverter, type EnvaptOptions, Envapter, Environment, type PrimitiveConstructor, type ValidArrayConverterBuiltInType };

package/dist/index.d.ts

@@ -0,0 +1,330 @@
+/**
+ * List of built-in converters for Envapt.
+ * @internal
+ */
+declare const ListOfBuiltInConverters: readonly ["string", "number", "boolean", "bigint", "symbol", "integer", "float", "json", "array", "url", "regexp", "date", "time"];
+
+/**
+ * Built-in converter types for common environment variable patterns
+ * @public
+ */
+type BuiltInConverter = (typeof ListOfBuiltInConverters)[number];
+/**
+ * Primitive types supported by Envapter
+ * @public
+ */
+type PrimitiveConstructor = typeof String | typeof Number | typeof Boolean | typeof BigInt | typeof Symbol;
+type ValidArrayConverterBuiltInType = Exclude<BuiltInConverter, 'array' | 'json' | 'regexp'>;
+/**
+ * Array converter configuration for custom delimiters and element types
+ * @public
+ */
+interface ArrayConverter {
+    /**
+     * Delimiter to split the string by
+     */
+    delimiter: string;
+    /**
+     * Type to convert each array element to (excludes array, json, and regexp types)
+     */
+    type?: ValidArrayConverterBuiltInType;
+}
+/**
+ * String value from a .env file or environment variable
+ * @public
+ */
+type BaseInput = string | undefined;
+/**
+ * Custom parser function type for environment variables
+ * @param raw - Raw string value from environment
+ * @param fallback - Fallback value if parsing fails
+ * @returns Parsed value of type T
+ * @public
+ */
+type ConverterFunction<FallbackType = unknown> = (raw: BaseInput, fallback?: FallbackType) => FallbackType;
+/**
+ * Environment variable converter - can be a primitive constructor, built-in converter string, array converter object, or custom parser function
+ * @see {@link PrimitiveConstructor} for primitive types
+ * @see {@link BuiltInConverter} for built-in types
+ * @see {@link ArrayConverter} for array converter configuration
+ * @see {@link ConverterFunction} for custom parser functions
+ * @public
+ */
+type EnvaptConverter<FallbackType> = PrimitiveConstructor | BuiltInConverter | ArrayConverter | ConverterFunction<FallbackType>;
+/**
+ * Options for the \@Envapt decorator (modern API)
+ * @public
+ */
+interface EnvaptOptions<FallbackType = string> {
+    /**
+     * Default value to use if environment variable is not found
+     */
+    fallback?: FallbackType;
+    /**
+     * Built-in converter, custom converter function, or boxed-primitives (String, Number, Boolean)
+     */
+    converter?: EnvaptConverter<FallbackType>;
+}
+interface ConverterMap {
+    string: string;
+    number: number;
+    boolean: boolean;
+    bigint: bigint;
+    symbol: symbol;
+    integer: number;
+    float: number;
+    json: unknown;
+    array: string[];
+    url: URL;
+    regexp: RegExp;
+    date: Date;
+    time: number;
+}
+/**
+ * Type mapping for built-in converters to their return types
+ */
+type BuiltInConverterReturnType<ConverterKey extends BuiltInConverter = BuiltInConverter> = ConverterMap[ConverterKey];
+
+/**
+ * Instance/Static Property decorator that automatically loads and converts environment variables.
+ *
+ * Supports both modern options-based API and classic parameter-based API.
+ * Automatically detects types from fallback values and provides caching for performance.
+ *
+ * Note: Using \@Envapt on a variable for an env that doesn't exist will set the value to `null` if no fallback is provided, regardless of a converter being used.
+ *
+ * @param key - Environment variable name to load
+ * @param options - Configuration options (modern API)
+ *
+ * @example Modern API (recommended):
+ * ```ts
+ * class Config extends Envapter {
+ * ‎ ‎ \@Envapt('PORT', { fallback: 3000 })
+ * ‎ ‎ static readonly port: number;
+ *
+ * ‎ ‎ \@Envapt('FEATURES', { fallback: ['auth'], converter: 'array' })
+ * ‎ ‎ declare private readonly features: string[];
+ *
+ * ‎ ‎ \@Envapt('CONFIG', { converter: 'json' })
+ * ‎ ‎ static readonly config: object;
+ *
+ * ‎ ‎ \@Envapt('API_URL', { converter: 'url' })
+ * ‎ ‎ declare public readonly apiUrl: URL;
+ *
+ * ‎ ‎ \@Envapt('CUSTOM_LIST', {
+ * ‎ ‎ ‎ ‎ fallback: [1, 2, 3],
+ * ‎ ‎ ‎ ‎ converter: {
+ * ‎ ‎ ‎ ‎   delimiter: ',',
+ * ‎ ‎ ‎ ‎   type: 'number' // Convert each item to number
+ * ‎ ‎ ‎ ‎ }
+ * ‎ ‎ })
+ * ‎ ‎ static readonly customList: string[];
+ * }
+ * ```
+ *
+ * @param key - Environment variable name to load
+ * @param fallback - Default value if variable is not found. Only suppoerts primitive types (string, number, boolean, bigint, symbol).
+ * @param converter - Custom converter function or built-in converter
+ *
+ * @example Classic API
+ * ```ts
+ * class HealthCheck {
+ * ‎ ‎ \@Envapt('PORT', 3000) declare readonly port: number;
+ *
+ * ‎ ‎ // code to start server
+ * ‎ ‎ public start() {
+ * ‎ ‎ ‎ ‎ // works on instance properties
+ * ‎ ‎ ‎ ‎ console.log(`Server running on port ${this.port}`);
+ * ‎ ‎ }
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function Envapt<FallbackType = unknown>(key: string, options?: EnvaptOptions<FallbackType>): PropertyDecorator;
+declare function Envapt<FallbackType = string | number | boolean | bigint | symbol>(key: string, fallback?: FallbackType, converter?: EnvaptConverter<FallbackType>): PropertyDecorator;
+
+/**
+ * @internal
+ */
+interface EnvapterService {
+    getRaw(key: string): string | undefined;
+    get(key: string, def?: string): string;
+    getNumber(key: string, def?: number): number;
+    getBoolean(key: string, def?: boolean): boolean;
+}
+
+/**
+ * Environment types supported by Envapter
+ * @public
+ */
+declare enum Environment {
+    Development = 0,
+    Staging = 1,
+    Production = 2
+}
+/**
+ * Main configuration class for environment variable management.
+ *
+ * Provides both static and instance methods for retrieving typed environment variables
+ * with support for template resolution, multiple .env files, and environment detection.
+ *
+ * Extend your own classes from this to define properties with \@Envapt decorators and provide access to environment variables methods.
+ *
+ * @example
+ * ```ts
+ * // Static usage
+ * const port = Envapter.getNumber('PORT', 3000);
+ * const url = Envapter.get('API_URL', 'http://localhost');
+ *
+ * // Instance usage
+ * const env = new Envapter();
+ * const dbUrl = env.get('DATABASE_URL', 'sqlite://memory');
+ * ```
+ *
+ * @public
+ */
+declare class Envapter implements EnvapterService {
+    private static readonly parser;
+    private static _envPaths;
+    private static internalEnvironment;
+    /**
+     * Set custom .env file paths. Accepts either a single path or array of paths.
+     * Setting new paths clears the cache and reloads environment variables.
+     *
+     * @param paths - Single file path or array of file paths to load
+     *
+     * @example
+     * ```ts
+     * // Single file
+     * Envapter.envPaths = '.env.production';
+     *
+     * // Multiple files (loaded in order)
+     * Envapter.envPaths = ['.env', '.env.local', '.env.production'];
+     * ```
+     */
+    static set envPaths(paths: string[] | string);
+    /**
+     * Get currently configured .env file paths
+     * @returns Array of file paths being loaded
+     */
+    static get envPaths(): string[];
+    private static determineEnvironment;
+    /**
+     * Set the application environment. Accepts either Environment enum or string value.
+     *
+     * @param env - Environment value ('development', 'staging', 'production') or Environment enum
+     *
+     * @example
+     * ```ts
+     * Envapter.environment = Environment.Production;
+     * Envapter.environment = 'staging';
+     * ```
+     */
+    static set environment(env: string | Environment);
+    /**
+     * Get the current application environment
+     * @returns Current environment enum value
+     */
+    static get environment(): Environment;
+    /**
+     * Check if the current environment is production
+     * @returns true if environment is production
+     */
+    static get isProduction(): boolean;
+    /**
+     * Check if the current environment is staging
+     * @returns true if environment is staging
+     */
+    static get isStaging(): boolean;
+    /**
+     * Check if the current environment is development
+     * @returns true if environment is development
+     */
+    static get isDevelopment(): boolean;
+    private static get config();
+    private static _get;
+    /**
+     * Get a string environment variable with optional fallback.
+     * Supports template variable resolution using ${VAR} syntax.
+     *
+     * @param key - Environment variable name
+     * @param def - Default value if variable is not found
+     * @returns The environment variable value or default
+     *
+     * @example
+     * ```ts
+     * const apiUrl = Envapter.get('API_URL', 'http://localhost:3000');
+     * ```
+     */
+    static get(key: string, def?: string): string;
+    /**
+     * Get a number environment variable with optional fallback.
+     * Automatically converts string values to numbers.
+     *
+     * @param key - Environment variable name
+     * @param def - Default value if variable is not found or cannot be converted
+     * @returns The environment variable value as number or default
+     *
+     * @example
+     * ```ts
+     * const port = Envapter.getNumber('PORT', 3000);
+     * ```
+     */
+    static getNumber(key: string, def?: number): number;
+    /**
+     * Get a boolean environment variable with optional fallback.
+     * Recognizes: `1`, `yes`, `true` as **true**; `0`, `no`, `false` as **false** (case-insensitive).
+     *
+     * @param key - Environment variable name
+     * @param def - Default value if variable is not found or cannot be converted
+     * @returns The environment variable value as boolean or default
+     *
+     * @example
+     * ```ts
+     * const isProduction = Envapter.getBoolean('IS_PRODUCTION', false);
+     * ```
+     */
+    static getBoolean(key: string, def?: boolean): boolean;
+    /**
+     * Get a bigint environment variable with optional fallback.
+     * Automatically converts string values to bigint.
+     *
+     * @param key - Environment variable name
+     * @param def - Default value if variable is not found or cannot be converted
+     * @returns The environment variable value as bigint or default
+     *
+     * @example
+     * ```ts
+     * const largeNumber = Envapter.getBigInt('LARGE_NUMBER', 123456789012345678901234567890n);
+     * ```
+     */
+    static getBigInt(key: string, def?: bigint): bigint;
+    /**
+     * Get a symbol environment variable with optional fallback.
+     * Creates a symbol from the string value.
+     *
+     * @param key - Environment variable name
+     * @param def - Default value if variable is not found
+     * @returns The environment variable value as symbol or default
+     *
+     * @example
+     * ```ts
+     * const uniqueKey = Envapter.getSymbol('UNIQUE_KEY', Symbol('default'));
+     * ```
+     */
+    static getSymbol(key: string, def?: symbol): symbol;
+    get(key: string, def?: string): string;
+    getNumber(key: string, def?: number): number;
+    getBoolean(key: string, def?: boolean): boolean;
+    getBigInt(key: string, def?: bigint): bigint;
+    getSymbol(key: string, def?: symbol): symbol;
+    /**
+     * Get raw environment variable value without parsing or conversion.
+     *
+     * @internal
+     */
+    getRaw(key: string): string | undefined;
+}
+
+export { type ArrayConverter, type BaseInput, type BuiltInConverter, type BuiltInConverterReturnType, type ConverterFunction, Envapt, type EnvaptConverter, type EnvaptOptions, Envapter, Environment, type PrimitiveConstructor, type ValidArrayConverterBuiltInType };