Environment Variable Loading

/**
 * Load environment variables from files with support for both env files and RC files
 * @param options - Configuration for loading environment variables
 * @returns Promise resolving to loaded environment variables
 */
function getEnvVars(options?: GetEnvVarOptions): Promise<Environment>;

interface GetEnvVarOptions {
  /** Configuration for .env file loading */
  envFile?: EnvFileOptions;
  /** Configuration for .env-cmdrc file loading */
  rc?: RCFileOptions;
  /** Enable verbose logging output */
  verbose?: boolean;
}

interface EnvFileOptions {
  /** Path to the environment file */
  filePath?: string;
  /** Whether to fall back to default locations if specified file not found */
  fallback?: boolean;
}

interface RCFileOptions {
  /** List of environment names to extract from RC file */
  environments: string[];
  /** Path to the RC file */
  filePath?: string;
}

// Via main package (GetEnvVars is an alias for getEnvVars)
import { GetEnvVars } from "env-cmd";

// Or via direct submodule import
import { getEnvVars } from "env-cmd/dist/get-env-vars.js";

// Load from default .env file locations (using GetEnvVars alias)
const env = await GetEnvVars();

// Load from specific env file
const env = await GetEnvVars({
  envFile: { filePath: ".env.production" },
  verbose: true
});

// Load from RC file with specific environments
const env = await GetEnvVars({
  rc: {
    environments: ["development", "staging"],
    filePath: ".env-cmdrc"
  }
});

// Load with fallback enabled
const env = await GetEnvVars({
  envFile: {
    filePath: "./config/.env",
    fallback: true
  }
});

/**
 * Load environment variables from .env format files
 * @param options - Configuration for env file loading
 * @returns Promise resolving to environment variables
 */
function getEnvFile(
  { filePath, fallback, verbose }: { filePath?: string, fallback?: boolean, verbose?: boolean },
): Promise<Environment>;

/**
 * Load environment variables from .env-cmdrc format files
 * @param options - Configuration for RC file loading
 * @returns Promise resolving to environment variables
 */
function getRCFile(
  { environments, filePath, verbose }: { environments: string[], filePath?: string, verbose?: boolean },
): Promise<Environment>;

{
  "development": {
    "NODE_ENV": "development",
    "API_URL": "http://localhost:3000"
  },
  "production": {
    "NODE_ENV": "production", 
    "API_URL": "https://api.production.com"
  }
}

/**
 * Parse environment variables from a specific file path
 * @param envFilePath - Path to the environment file
 * @returns Promise resolving to parsed environment variables
 */
function getEnvFileVars(envFilePath: string): Promise<Environment>;

/**
 * Parse environment variables from RC file with specific environments
 * @param options - RC file configuration
 * @returns Promise resolving to merged environment variables
 */
function getRCFileVars(
  { environments, filePath }: { environments: string[], filePath: string },
): Promise<Environment>;

const IMPORT_HOOK_EXTENSIONS = [
  '.json',
  '.js',
  '.cjs',
  '.mjs',
  '.ts',
  '.mts',
  '.cts',
  '.tsx',
];

interface PathError extends Error {
  name: 'PathError';
}

interface EnvironmentError extends Error {
  name: 'EnvironmentError';
}

interface ParseError extends Error {
  name: 'ParseError';
}

// File not found at specified path
const pathError = new Error(`Invalid env file path (${envFilePath}).`);
pathError.name = 'PathError';
throw pathError;

// Environment not found in RC file
const envError = new Error(`Failed to find environments: [${environments.join(',')}]`);
envError.name = 'EnvironmentError';
throw envError;

// File exists but cannot be parsed
const parseError = new Error(`Failed to parse file: ${filePath}`);
parseError.name = 'ParseError';
throw parseError;

// Success messages
console.info(`Found .env file at path: ${filePath}`);
console.info(`Found environments: [${environments.join(',')}] for .rc file at path: ${filePath}`);

// Failure messages  
console.info(`Failed to find .env file at path: ${filePath}`);
console.info(`Failed to find environments: [${environments.join(',')}] for .rc file at path: ${filePath}`);

/**
 * Resolve file paths with home directory expansion
 * @param userPath - User-provided file path (may include ~)
 * @returns Absolute resolved path
 */
function resolveEnvFilePath(userPath: string): string;