/**
 * Options for loading environment variables.
 *
 * This loader is fully isolated:
 * - It does NOT rely on process.env as a source of truth
 * - It uses dotenv.parse internally (not dotenv.config)
 * - It builds a deterministic environment object from files + envInitial
 */
type LoadEnvOpts = {
    /**
     * Directory where the environment variable files are located.
     * If not specified, the current working directory will be used.
     *
     * @default process.cwd()
     */
    envDir?: string;
    /**
     * The environment mode used to resolve file names.
     * Common values: "development", "production", "testing", "staging".
     *
     * This is NOT validated against a fixed list (except "local" which is forbidden).
     *
     * @default process.env.NODE_ENV || "production"
     */
    mode?: "development" | "production" | "testing" | "staging" | string;
    /**
     * Prefix or prefixes used to filter environment variables.
     *
     * Only keys that start with one of these prefixes will be included
     * in the final result.
     *
     * @default "APP_"
     */
    envPrefix?: string | string[];
    /**
     * Initial environment variables used as the base layer.
     *
     * These values are merged BEFORE loading any .env files.
     *
     * @default {}
     */
    envInitial?: Record<string, string>;
    /**
     * If true, removes the prefix from exported keys.
     *
     * Example:
     *   APP_API_URL → API_URL
     *
     * If false, keys remain unchanged.
     *
     * @default false
     */
    removeEnvPrefix?: boolean;
    /**
     * Encoding used to read .env files.
     *
     * @default "utf-8"
     */
    encoding?: BufferEncoding;
    /**
     * Controls whether the resulting values are synced into process.env.
     *
     * NOTE:
     * This does NOT affect how values are loaded or computed,
     * only whether they are written into process.env after resolution.
     *
     * - "none": do not modify process.env
     * - "preserve": only set keys that do not exist in process.env
     * - "overwrite": always overwrite process.env values
     *
     * @default "none"
     */
    processEnvMode?: "none" | "overwrite" | "preserve";
};
/**
 * Loads and resolves environment variables from .env files.
 *
 * This function:
 * 1. Starts from envInitial
 * 2. Loads and parses .env files using dotenv.parse (no process.env mutation)
 * 3. Merges files in deterministic order
 * 4. Filters variables by prefix
 * 5. Optionally strips prefixes from keys
 * 6. Optionally syncs result into process.env
 *
 * Returns a fully resolved environment object.
 */
declare const loadEnv: (opts?: LoadEnvOpts) => Record<string, string>;

export { LoadEnvOpts, loadEnv };