envapt 1.1.0 → 2.1.0

package/dist/index.d.mts

@@ -1,20 +1,62 @@
+import { DotenvConfigOptions } from 'dotenv';
+
+/**
+ * Enum for built-in converters
+ * @public
+ */
+declare enum Converters {
+    String = "string",
+    Number = "number",
+    Boolean = "boolean",
+    Bigint = "bigint",
+    Symbol = "symbol",
+    Integer = "integer",
+    Float = "float",
+    Json = "json",
+    Array = "array",
+    Url = "url",
+    Regexp = "regexp",
+    Date = "date",
+    Time = "time"
+}
+/**
+ * Type alias for converter values to maintain compatibility with existing string-based API
+ * @internal
+ */
+type ConverterValue = `${Converters}`;
+/**
+ * Valid array element converter types (excludes array, json, regexp)
+ * @internal
+ */
+type ArrayElementConverter = Exclude<Converters, Converters.Array | Converters.Json | Converters.Regexp>;
 /**
- * List of built-in converters for Envapt.
+ * Type alias for array element converter values
  * @internal
  */
-declare const ListOfBuiltInConverters: readonly ["string", "number", "boolean", "bigint", "symbol", "integer", "float", "json", "array", "url", "regexp", "date", "time"];
+type ArrayElementConverterValue = `${ArrayElementConverter}`;
 
+/**
+ * User defined options for dotenv configuration
+ *
+ * "processEnv" and "path" are managed by Envapter and should not be included in user-defined config.
+ * @public
+ */
+type PermittedDotenvConfig = Omit<DotenvConfigOptions, 'processEnv' | 'path'>;
 /**
  * Built-in converter types for common environment variable patterns
  * @public
  */
-type BuiltInConverter = (typeof ListOfBuiltInConverters)[number];
+type BuiltInConverter = ConverterValue | Converters;
 /**
  * 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'>;
+/**
+ * Valid array converter element types (excludes array, json, regexp)
+ * @public
+ */
+type ValidArrayConverterBuiltInType = ArrayElementConverterValue | ArrayElementConverter;
 /**
  * Array converter configuration for custom delimiters and element types
  * @public
@@ -27,7 +69,7 @@ interface ArrayConverter {
     /**
      * Type to convert each array element to (excludes array, json, and regexp types)
      */
-    type?: ValidArrayConverterBuiltInType;
+    type?: ArrayElementConverter | ArrayElementConverterValue;
 }
 /**
  * String value from a .env file or environment variable
@@ -41,30 +83,41 @@ type BaseInput = string | undefined;
  * @returns Parsed value of type T
  * @public
  */
-type ConverterFunction<FallbackType = unknown> = (raw: BaseInput, fallback?: FallbackType) => FallbackType;
+type ConverterFunction<TFallback = unknown> = (raw: BaseInput, fallback?: TFallback) => TFallback;
 /**
  * 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 Converters} 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>;
+type EnvaptConverter<TFallback> = PrimitiveConstructor | Converters | ConverterValue | ArrayConverter | ConverterFunction<TFallback>;
 /**
  * Options for the \@Envapt decorator (modern API)
  * @public
  */
-interface EnvaptOptions<FallbackType = string> {
+interface EnvaptOptions<TFallback = string> {
     /**
      * Default value to use if environment variable is not found
      */
-    fallback?: FallbackType;
+    fallback?: TFallback;
     /**
-     * Built-in converter, custom converter function, or boxed-primitives (String, Number, Boolean)
+     * Built-in converter, custom converter function, or boxed-primitives (String, Number, Boolean, Symbol, BigInt)
+     * @see {@link EnvaptConverter} for details
      */
-    converter?: EnvaptConverter<FallbackType>;
+    converter?: EnvaptConverter<TFallback>;
 }
+type JsonPrimitive = string | number | boolean | null;
+type JsonArray = JsonValue[];
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+/**
+ * JSON value types for custom converters
+ * @internal
+ */
+type JsonValue = JsonPrimitive | JsonArray | JsonObject;
 interface ConverterMap {
     string: string;
     number: number;
@@ -73,7 +126,7 @@ interface ConverterMap {
     symbol: symbol;
     integer: number;
     float: number;
-    json: unknown;
+    json: JsonValue;
     array: string[];
     url: URL;
     regexp: RegExp;
@@ -82,249 +135,391 @@ interface ConverterMap {
 }
 /**
  * Type mapping for built-in converters to their return types
+ * @internal
+ */
+type BuiltInConverterReturnType<ConverterKey extends BuiltInConverter> = ConverterKey extends Converters ? ConverterMap[`${ConverterKey}`] : ConverterKey extends keyof ConverterMap ? ConverterMap[ConverterKey] : never;
+/**
+ * Return type for built-in converter functions
+ * @internal
  */
-type BuiltInConverterReturnType<ConverterKey extends BuiltInConverter = BuiltInConverter> = ConverterMap[ConverterKey];
+type ReturnValuesOfConverterFunctions = ConverterMap[BuiltInConverter];
+/**
+ * Function type for built-in converter functions
+ * @internal
+ */
+type BuiltInConverterFunction = (...args: Parameters<(...args: any[]) => ReturnValuesOfConverterFunctions>) => ReturnValuesOfConverterFunctions | undefined;
+/**
+ * Map of built-in converter functions
+ * @internal
+ */
+type MapOfConverterFunctions = Record<BuiltInConverter, BuiltInConverterFunction>;
+/**
+ * Time unit types for duration conversions
+ * @internal
+ */
+type TimeUnit = 'ms' | 's' | 'm' | 'h';
+/**
+ * Helper type for getter methods that conditionally return undefined based on whether a fallback is provided
+ * If fallback is provided, return ReturnType. If no fallback (undefined), return ReturnType | undefined.
+ * @internal
+ */
+type ConditionalReturn<ReturnType, TFallback> = TFallback extends undefined ? ReturnType | undefined : ReturnType;
+/**
+ * Advanced type inference for built-in and array converters
+ * Maps converter types to their expected return types
+ * @internal
+ */
+type InferConverterReturnType<TConverter extends BuiltInConverter | ArrayConverter> = TConverter extends BuiltInConverter ? BuiltInConverterReturnType<TConverter> : TConverter extends ArrayConverter ? TConverter['type'] extends BuiltInConverter ? BuiltInConverterReturnType<TConverter['type']>[] : string[] : unknown[];
+/**
+ * Complete type inference for advanced converter methods
+ * @internal
+ */
+type AdvancedConverterReturn<TConverter extends BuiltInConverter | ArrayConverter, TFallback = undefined> = ConditionalReturn<InferConverterReturnType<TConverter>, TFallback>;
+/**
+ * Type inference for primitive constructor return types
+ * @internal
+ */
+type InferPrimitiveReturnType<TConstructor extends PrimitiveConstructor> = TConstructor extends typeof String ? string : TConstructor extends typeof Number ? number : TConstructor extends typeof Boolean ? boolean : TConstructor extends typeof BigInt ? bigint : TConstructor extends typeof Symbol ? symbol : never;
+/**
+ * Type inference for primitive fallback values
+ * @internal
+ */
+type InferPrimitiveFallbackType<TFallback extends string | number | boolean | bigint | symbol | undefined> = TFallback extends string ? string : TFallback extends number ? number : TFallback extends boolean ? boolean : TFallback extends bigint ? bigint : TFallback extends symbol ? symbol : undefined;
 
 /**
- * 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.
+ * Usage 1: Custom converter function with fallback provided
  *
  * @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[];
+ * @param options - Configuration options with custom converter and required fallback
+ * @public
+ */
+declare function Envapt<TFallback>(key: string, options: {
+    converter: (raw: string | undefined, fallback: TFallback) => TFallback;
+    fallback: TFallback;
+}): PropertyDecorator;
+/**
+ * Usage 2: Custom converter function without fallback
  *
- * ‎ ‎ \@Envapt('CONFIG', { converter: 'json' })
- * ‎ ‎ static readonly config: object;
+ * @param key - Environment variable name to load
+ * @param options - Configuration options with custom converter only
+ * @public
+ */
+declare function Envapt<TReturnType>(key: string, options: {
+    converter: ConverterFunction<TReturnType>;
+}): PropertyDecorator;
+/**
+ * Usage 3: Built-in converter with optional fallback
  *
- * ‎ ‎ \@Envapt('API_URL', { converter: 'url' })
- * ‎ ‎ declare public readonly apiUrl: URL;
+ * @param key - Environment variable name to load
+ * @param options - Configuration options with built-in converter
+ * @public
+ */
+declare function Envapt<TConverter extends BuiltInConverter>(key: string, options: {
+    converter: TConverter;
+    fallback?: InferConverterReturnType<TConverter>;
+}): PropertyDecorator;
+/**
+ * Usage 4: Array converter with optional fallback
  *
- * ‎ ‎ \@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 options - Configuration options with array converter
+ * @public
+ */
+declare function Envapt<TConverter extends ArrayConverter>(key: string, options: {
+    converter: TConverter;
+    fallback?: InferConverterReturnType<TConverter>;
+}): PropertyDecorator;
+/**
+ * Usage 5: Primitive constructor with optional fallback
  *
  * @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
+ * @param options - Configuration options with primitive constructor
+ * @public
+ */
+declare function Envapt<TConstructor extends PrimitiveConstructor>(key: string, options: {
+    converter: TConstructor;
+    fallback?: InferPrimitiveReturnType<TConstructor>;
+}): PropertyDecorator;
+/**
+ * Usage 6: Fallback only (no converter)
  *
- * @example Classic API
- * ```ts
- * class HealthCheck {
- * ‎ ‎ \@Envapt('PORT', 3000) declare readonly port: number;
+ * @param key - Environment variable name to load
+ * @param options - Configuration options with fallback only
+ * @public
+ */
+declare function Envapt<TFallback>(key: string, options: {
+    fallback: TFallback;
+    converter?: undefined;
+}): PropertyDecorator;
+/**
+ * Classic API: No fallback
  *
- * ‎ ‎ // code to start server
- * ‎ ‎ public start() {
- * ‎ ‎ ‎ ‎ // works on instance properties
- * ‎ ‎ ‎ ‎ console.log(`Server running on port ${this.port}`);
- * ‎ ‎ }
- * }
- * ```
+ * @param key - Environment variable name to load
+ */
+declare function Envapt<_TReturnType = string | null>(key: string): PropertyDecorator;
+/**
+ * Classic API: Primitive fallback only
  *
+ * @param key - Environment variable name to load
+ * @param fallback - Default primitive value
+ * @param converter - Optional primitive constructor (String, Number, etc.)
  * @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;
+declare function Envapt<TFallback extends string | number | boolean | bigint | symbol | undefined>(key: string, fallback: InferPrimitiveFallbackType<TFallback>, converter?: PrimitiveConstructor): 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;
+    get(key: string, def?: string): string | undefined;
+    getNumber(key: string, def?: number): number | undefined;
+    getBoolean(key: string, def?: boolean): boolean | undefined;
 }
-
 /**
- * Environment types supported by Envapter
- * @public
+ * Parser class for handling environment variable template resolution and type conversion
+ * @internal
  */
-declare enum Environment {
-    Development = 0,
-    Staging = 1,
-    Production = 2
+declare class Parser {
+    private readonly envService;
+    private readonly TEMPLATE_REGEX;
+    constructor(envService: EnvapterService);
+    /**
+     * Resolve template variables in a string while handling circular references and missing variables
+     * @internal
+     */
+    resolveTemplate(key: string, value: string, stack?: Set<string>): string;
+    convertValue<TFallback>(key: string, fallback: TFallback | undefined, converter: EnvaptConverter<TFallback> | undefined, hasFallback: boolean): TFallback | null | undefined;
+    private processFallbackForConverter;
+    private convertPrimitiveToString;
+    private processBuiltInConverter;
+    private processArrayConverter;
+    private processCustomConverter;
+    private resolveConverter;
 }
+
 /**
- * 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
+ * Base class for environment variable management
+ * Handles configuration, caching, and basic environment loading
+ * @internal
  */
-declare class Envapter implements EnvapterService {
-    private static readonly parser;
-    private static _envPaths;
-    private static internalEnvironment;
+declare abstract class EnvapterBase {
+    protected static _envPaths: string[];
+    protected static _userDefinedDotenvConfig: PermittedDotenvConfig;
     /**
      * 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';
-     * ```
+     * Set custom dotenv configuration options.
      */
-    static set environment(env: string | Environment);
+    static set dotenvConfig(config: PermittedDotenvConfig);
+    /**
+     * Get current dotenv configuration options
+     */
+    static get dotenvConfig(): PermittedDotenvConfig;
+    protected static refreshCache(): void;
+    protected static get config(): Map<string, unknown>;
+    /**
+     * Get raw environment variable value without parsing or conversion.
+     */
+    getRaw(key: string): string | undefined;
+}
+
+/**
+ * Environment types supported by Envapter
+ * @public
+ */
+declare enum Environment {
+    Development = 0,
+    Staging = 1,
+    Production = 2
+}
+/**
+ * Mixin for environment detection and checking methods
+ * @internal
+ */
+declare class EnvironmentMethods extends EnvapterBase {
+    protected static _environment: Environment | undefined;
+    protected static determineEnvironment(env?: string | Environment): void;
+    private static getRawValue;
     /**
      * Get the current application environment
-     * @returns Current environment enum value
      */
     static get environment(): Environment;
+    /**
+     * Set the application environment. Accepts either Environment enum or string value.
+     */
+    static set environment(env: string | Environment);
+    /**
+     * @see {@link EnvironmentMethods.environment}
+     */
+    get environment(): Environment;
+    /**
+     * @see {@link EnvironmentMethods.environment}
+     */
+    set environment(env: string | Environment);
     /**
      * Check if the current environment is production
-     * @returns true if environment is production
      */
     static get isProduction(): boolean;
+    /**
+     * @see {@link EnvironmentMethods.isProduction}
+     */
+    get isProduction(): boolean;
     /**
      * Check if the current environment is staging
-     * @returns true if environment is staging
      */
     static get isStaging(): boolean;
+    /**
+     * @see {@link EnvironmentMethods.isStaging}
+     */
+    get isStaging(): boolean;
     /**
      * Check if the current environment is development
-     * @returns true if environment is development
      */
     static get isDevelopment(): boolean;
-    private static get config();
+    /**
+     * @see {@link EnvironmentMethods.isDevelopment}
+     */
+    get isDevelopment(): boolean;
+    protected static refreshCache(): void;
+}
+
+/**
+ * Mixin for primitive environment variable getter methods
+ * @internal
+ */
+declare class PrimitiveMethods extends EnvironmentMethods implements EnvapterService {
+    protected static readonly parser: Parser;
     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;
+     */
+    static get<Default extends string | undefined = undefined>(key: string, def?: Default): ConditionalReturn<string, Default>;
+    /**
+     * @see {@link PrimitiveMethods.get}
+     */
+    get<Default extends string | undefined = undefined>(key: string, def?: Default): ConditionalReturn<string, Default>;
     /**
      * 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;
+     */
+    static getNumber<Default extends number | undefined = undefined>(key: string, def?: Default): ConditionalReturn<number, Default>;
+    /**
+     * @see {@link PrimitiveMethods.getNumber}
+     */
+    getNumber<Default extends number | undefined = undefined>(key: string, def?: Default): ConditionalReturn<number, Default>;
     /**
      * 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;
+     * Recognizes: `1`, `yes`, `true`, 'on' as **true**; `0`, `no`, `false`, 'off' as **false** (case-insensitive).
+     */
+    static getBoolean<Default extends boolean | undefined = undefined>(key: string, def?: Default): ConditionalReturn<boolean, Default>;
+    /**
+     * @see {@link PrimitiveMethods.getBoolean}
+     */
+    getBoolean<Default extends boolean | undefined = undefined>(key: string, def?: Default): ConditionalReturn<boolean, Default>;
     /**
      * 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;
+     */
+    static getBigInt<Default extends bigint | undefined = undefined>(key: string, def?: Default): ConditionalReturn<bigint, Default>;
+    /**
+     * @see {@link PrimitiveMethods.getBigInt}
+     */
+    getBigInt<Default extends bigint | undefined = undefined>(key: string, def?: Default): ConditionalReturn<bigint, Default>;
     /**
      * 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;
+     */
+    static getSymbol<Default extends symbol | undefined = undefined>(key: string, def?: Default): ConditionalReturn<symbol, Default>;
     /**
-     * Get raw environment variable value without parsing or conversion.
-     *
-     * @internal
+     * @see {@link PrimitiveMethods.getSymbol}
      */
-    getRaw(key: string): string | undefined;
+    getSymbol<Default extends symbol | undefined = undefined>(key: string, def?: Default): ConditionalReturn<symbol, Default>;
+}
+
+/**
+ * Mixin for advanced methods for environment variable conversion using built-in and custom converters
+ * @internal
+ */
+declare class AdvancedMethods extends PrimitiveMethods {
+    /**
+     * Get an environment variable using a built-in converter.
+     * Supports both Converter enum values and array converter configurations.
+     */
+    static getUsing<TConverter extends BuiltInConverter | ArrayConverter, TFallback = undefined>(key: string, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
+    static getUsing<TReturn>(key: string, converter: BuiltInConverter | ArrayConverter, fallback?: TReturn): TReturn;
+    /**
+     * @see {@link AdvancedMethods.getUsing}
+     */
+    getUsing<TConverter extends BuiltInConverter | ArrayConverter, TFallback = undefined>(key: string, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
+    getUsing<TReturn>(key: string, converter: BuiltInConverter | ArrayConverter, fallback?: TReturn): TReturn;
+    /**
+     * Get an environment variable using a custom converter function.
+     */
+    static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: string, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
+    /**
+     * @see {@link AdvancedMethods.getWith}
+     */
+    getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: string, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
+}
+
+/**
+ * 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 extends AdvancedMethods {
+}
+
+declare enum EnvaptErrorCodes {
+    /** Thrown when an invalid fallback value is provided */
+    InvalidFallback = 101,
+    /** Thrown when fallback value type doesn't match expected converter type */
+    InvalidFallbackType = 102,
+    /** Thrown when array fallback contains elements of wrong type */
+    ArrayFallbackElementTypeMismatch = 103,
+    /** Thrown when fallback type doesn't match the specified converter */
+    FallbackConverterTypeMismatch = 104,
+    /** Thrown when invalid array converter configuration is provided */
+    InvalidArrayConverterType = 201,
+    /** Thrown when an invalid built-in converter is specified */
+    InvalidBuiltInConverter = 202,
+    /** Thrown when a custom converter is not a function */
+    InvalidCustomConverter = 203,
+    /** Thrown when converter type is not recognized */
+    InvalidConverterType = 204,
+    /** Thrown when primitive type coercion on fallback value fails */
+    PrimitiveCoercionFailed = 205,
+    /** Thrown when delimiter is missing in array converter configuration */
+    MissingDelimiter = 301,
+    /** Thrown when invalid user-defined configuration is provided */
+    InvalidUserDefinedConfig = 302,
+    /** Thrown when specified environment files don't exist */
+    EnvFilesNotFound = 303
 }
 
-export { type ArrayConverter, type BaseInput, type BuiltInConverter, type BuiltInConverterReturnType, type ConverterFunction, Envapt, type EnvaptConverter, type EnvaptOptions, Envapter, Environment, type PrimitiveConstructor, type ValidArrayConverterBuiltInType };
+export { type AdvancedConverterReturn, type ArrayConverter, type BuiltInConverter, type BuiltInConverterFunction, type ConditionalReturn, type ConverterFunction, Converters, Envapt, type EnvaptConverter, EnvaptErrorCodes, type EnvaptOptions, Envapter, Environment, type InferConverterReturnType, type InferPrimitiveFallbackType, type InferPrimitiveReturnType, type JsonValue, type MapOfConverterFunctions, type PermittedDotenvConfig, type PrimitiveConstructor, type TimeUnit, type ValidArrayConverterBuiltInType };