/**
 * Create a case-insensitive environment variable Proxy for Windows compatibility.
 * On Windows, environment variables are case-insensitive (PATH vs Path vs path).
 * This Proxy provides consistent access regardless of case, with priority given
 * to exact matches, then case-insensitive matches for known vars.
 *
 * **Use Cases:**
 * - Cross-platform test environments needing consistent env var access
 * - Windows compatibility when passing env to child processes
 * - Merging environment overrides while preserving case-insensitive lookups
 *
 * **Performance Note:**
 * Proxy operations have runtime overhead. Only use when Windows case-insensitive
 * access is required. For most use cases, process.env directly is sufficient.
 *
 * @param base - Base environment object (usually process.env)
 * @param overrides - Optional overrides to merge
 * @returns Proxy that handles case-insensitive env var access
 *
 * @example
 * // Create a Proxy with overrides
 * const env = createEnvProxy(process.env, { NODE_ENV: 'test' })
 * console.log(env.PATH)  // Works with any case: PATH, Path, path
 * console.log(env.NODE_ENV)  // 'test'
 *
 * @example
 * // Pass to child process spawn
 * import { createEnvProxy } from '@socketsecurity/lib/env'
 * import { spawn } from '@socketsecurity/lib/spawn'
 *
 * spawn('node', ['script.js'], {
 *   env: createEnvProxy(process.env, { NODE_ENV: 'test' })
 * })
 */
export declare function createEnvProxy(base: NodeJS.ProcessEnv, overrides?: Record<string, string | undefined>): NodeJS.ProcessEnv;
/**
 * Convert an environment variable value to a boolean.
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function envAsBoolean(value: unknown, defaultValue?: boolean): boolean;
/**
 * Convert an environment variable value to a number.
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function envAsNumber(value: unknown, defaultValue?: number): number;
/**
 * Convert an environment variable value to a trimmed string.
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function envAsString(value: unknown, defaultValue?: string): string;
/**
 * Find a case-insensitive environment variable key match.
 * Searches for an environment variable key that matches the given uppercase name,
 * using optimized fast-path checks to minimize expensive toUpperCase() calls.
 *
 * **Use Cases:**
 * - Finding PATH when env object has "Path" or "path"
 * - Cross-platform env var access where case may vary
 * - Custom case-insensitive env lookups
 *
 * **Performance:**
 * - Fast path: Checks length first (O(1)) before toUpperCase (expensive)
 * - Only converts to uppercase when length matches
 * - Early exit on first match
 *
 * @param env - Environment object or env-like record to search
 * @param upperEnvVarName - Uppercase environment variable name to find (e.g., 'PATH')
 * @returns The actual key from env that matches (e.g., 'Path'), or undefined
 *
 * @example
 * // Find PATH regardless of case
 * const envObj = { Path: 'C:\\Windows', NODE_ENV: 'test' }
 * const key = findCaseInsensitiveEnvKey(envObj, 'PATH')
 * console.log(key)  // 'Path'
 * console.log(envObj[key])  // 'C:\\Windows'
 *
 * @example
 * // Not found returns undefined
 * const key = findCaseInsensitiveEnvKey({}, 'MISSING')
 * console.log(key)  // undefined
 */
export declare function findCaseInsensitiveEnvKey(env: Record<string, string | undefined>, upperEnvVarName: string): string | undefined;
