Environment Validation

/**
 * Sanitizes and validates environment variables against specifications
 * @param environment - Raw environment object (typically process.env)
 * @param specs - Validation specifications for each environment variable
 * @param options - Optional configuration for validation behavior
 * @returns Frozen, type-safe environment object with validated variables
 */
function cleanEnv<T extends Record<string, ValidatorSpec<any>>>(
  environment: unknown,
  specs: T,
  options?: CleanOptions<T>
): CleanedEnv<T>;

import { cleanEnv, str, num, bool, port } from "envalid";

// Basic validation
const env = cleanEnv(process.env, {
  NODE_ENV: str({ choices: ["development", "test", "production"] }),
  PORT: port({ default: 3000 }),
  DATABASE_URL: str(),
  DEBUG: bool({ default: false }),
});

// With custom reporter
const env2 = cleanEnv(process.env, {
  API_KEY: str(),
  TIMEOUT: num({ default: 5000 }),
}, {
  reporter: ({ errors }) => {
    console.error("Environment validation failed:", errors);
  }
});

// Access validated variables
console.log(env.PORT); // number: 3000
console.log(env.DEBUG); // boolean: false
console.log(env.isDevelopment); // boolean convenience property

/**
 * Advanced environment validation with custom middleware
 * @param environment - Raw environment object
 * @param specs - Validation specifications
 * @param applyMiddleware - Custom middleware function
 * @param options - Optional validation configuration
 * @returns Environment object transformed by custom middleware
 */
function customCleanEnv<T extends Record<string, ValidatorSpec<any>>, MW>(
  environment: unknown,
  specs: T,
  applyMiddleware: (cleanedEnv: CleanedEnv<T>, rawEnv: unknown) => MW,
  options?: CleanOptions<T>
): Readonly<MW>;

import { customCleanEnv, str, num, accessorMiddleware } from "envalid";

// Custom middleware that adds logging
const env = customCleanEnv(
  process.env,
  {
    DATABASE_URL: str(),
    PORT: num({ default: 3000 }),
  },
  (cleanedEnv, rawEnv) => {
    const withAccessors = accessorMiddleware(cleanedEnv, rawEnv);
    
    return {
      ...withAccessors,
      log: (message: string) => {
        console.log(`[${withAccessors.NODE_ENV}] ${message}`);
      }
    };
  }
);

// Use custom properties
env.log("Application starting"); // Custom method
console.log(env.DATABASE_URL); // Validated environment variable

/**
 * Provides default values only when NODE_ENV=test
 * @param defaultValueForTests - Value to return in test environment
 * @returns Value in test environment, internal symbol otherwise
 */
function testOnly<T>(defaultValueForTests: T): T;

import { cleanEnv, str, testOnly } from "envalid";

const env = cleanEnv(process.env, {
  DATABASE_URL: str({ 
    default: testOnly("sqlite://memory") 
  }),
  API_KEY: str({ 
    default: testOnly("test-api-key-123") 
  }),
});

// In test environment: uses test defaults
// In other environments: requires actual values

interface CleanOptions<T> {
  /** Custom error reporter function, null to disable reporting */
  reporter?: ((opts: ReporterOptions<T>) => void) | null;
}

interface ReporterOptions<T> {
  /** Validation errors keyed by environment variable name */
  errors: Partial<Record<keyof T, Error>>;
  /** Raw environment object that was validated */
  env: unknown;
}

interface CleanedEnv<T> extends CleanedEnvAccessors {
  readonly [K in keyof T]: T[K] extends ValidatorSpec<infer U> ? U : never;
}

interface CleanedEnvAccessors {
  /** True if NODE_ENV === 'development' */
  isDevelopment: boolean;
  /** Alias for isDevelopment */
  isDev: boolean;
  /** True if NODE_ENV === 'test' */
  isTest: boolean;  
  /** True if NODE_ENV === 'production' */
  isProduction: boolean;
  /** Alias for isProduction */
  isProd: boolean;
}