Built-in Validators

/**
 * Validates string values
 * @param spec - Optional specification with constraints
 * @returns ValidatorSpec for string type
 */
const str: BaseValidator<string>;

import { cleanEnv, str } from "envalid";

const env = cleanEnv(process.env, {
  // Required string
  APP_NAME: str(),
  
  // String with choices
  LOG_LEVEL: str({ choices: ["debug", "info", "warn", "error"] }),
  
  // String with default
  DEFAULT_LANG: str({ default: "en" }),
  
  // String with description
  SECRET_KEY: str({ desc: "Application secret key" }),
});

/**
 * Validates and parses numeric values
 * @param spec - Optional specification with constraints
 * @returns ValidatorSpec for number type
 */
const num: BaseValidator<number>;

import { cleanEnv, num } from "envalid";

const env = cleanEnv(process.env, {
  // Required number
  MAX_CONNECTIONS: num(),
  
  // Number with default
  TIMEOUT: num({ default: 5000 }),
  
  // Number with choices
  WORKER_COUNT: num({ choices: [1, 2, 4, 8] }),
  
  // Number with example
  RATE_LIMIT: num({ example: "100" }),
});

/**
 * Validates boolean values from string and boolean formats
 * Accepts: true/false, t/f, yes/no, on/off, 1/0 (strings or actual booleans)
 * @param spec - Optional specification with constraints
 * @returns ValidatorSpec for boolean type
 */
const bool: ExactValidator<boolean>;

import { cleanEnv, bool } from "envalid";

const env = cleanEnv(process.env, {
  // Required boolean
  ENABLE_LOGGING: bool(),
  
  // Boolean with default
  DEBUG_MODE: bool({ default: false }),
  
  // Boolean with description
  USE_HTTPS: bool({ desc: "Enable HTTPS connections" }),
});

// Accepts various formats (strings or actual booleans):
// true, false, 't', 'f', 'yes', 'no', 'on', 'off', '1', '0'

/**
 * Validates email addresses using regex pattern
 * @param spec - Optional specification with constraints  
 * @returns ValidatorSpec for email string type
 */
const email: BaseValidator<string>;

import { cleanEnv, email } from "envalid";

const env = cleanEnv(process.env, {
  // Required email
  ADMIN_EMAIL: email(),
  
  // Email with default
  SUPPORT_EMAIL: email({ default: "support@example.com" }),
  
  // Email with example
  NOTIFICATION_EMAIL: email({ example: "notify@yourapp.com" }),
});

/**
 * Validates URL strings using URL constructor
 * Accepts any valid URL format
 * @param spec - Optional specification with constraints
 * @returns ValidatorSpec for URL string type
 */
const url: BaseValidator<string>;

import { cleanEnv, url } from "envalid";

const env = cleanEnv(process.env, {
  // Required URL
  DATABASE_URL: url(),
  
  // URL with default
  REDIS_URL: url({ default: "redis://localhost:6379" }),
  
  // URL with example
  WEBHOOK_URL: url({ example: "https://api.example.com/webhook" }),
});

/**
 * Validates port numbers (1-65535)
 * Ensures integer values within valid port range
 * @param spec - Optional specification with constraints
 * @returns ValidatorSpec for port number type
 */
const port: BaseValidator<number>;

import { cleanEnv, port } from "envalid";

const env = cleanEnv(process.env, {
  // Required port
  HTTP_PORT: port(),
  
  // Port with default
  HTTPS_PORT: port({ default: 443 }),
  
  // Port with choices
  DB_PORT: port({ choices: [3306, 5432, 27017] }),
});

/**
 * Validates hostnames (FQDN) or IP addresses
 * Supports both IPv4 and IPv6 addresses
 * @param spec - Optional specification with constraints
 * @returns ValidatorSpec for host string type
 */
const host: BaseValidator<string>;

import { cleanEnv, host } from "envalid";

const env = cleanEnv(process.env, {
  // Required host
  DATABASE_HOST: host(),
  
  // Host with default
  REDIS_HOST: host({ default: "localhost" }),
  
  // Host with example
  API_HOST: host({ example: "api.example.com" }),
});

// Accepts: example.com, 192.168.1.1, ::1, etc.

/**
 * Validates and parses JSON strings
 * Can be typed with generic parameter for output type
 * @param spec - Optional specification with constraints
 * @returns ValidatorSpec for parsed JSON type
 */
const json: StructuredValidator;

import { cleanEnv, json } from "envalid";

interface DatabaseConfig {
  host: string;
  port: number;
  ssl: boolean;
}

const env = cleanEnv(process.env, {
  // Generic JSON
  APP_CONFIG: json(),
  
  // Typed JSON
  DATABASE_CONFIG: json<DatabaseConfig>(),
  
  // JSON with default
  FEATURE_FLAGS: json({ default: {} }),
  
  // JSON with example
  CORS_ORIGINS: json({ 
    example: '["http://localhost:3000", "https://app.com"]' 
  }),
});

// Parses valid JSON strings into objects

interface Spec<T> {
  /** Array of valid choices for the value */
  choices?: ReadonlyArray<T>;
  /** Human-readable description of the variable */
  desc?: string;
  /** Example value for documentation */
  example?: string;
  /** URL to additional documentation */
  docs?: string;
  /** Default value if not provided */
  default?: NonNullable<T> | undefined;
  /** Default value only in development environment */
  devDefault?: NonNullable<T> | undefined;
  /** Function to determine if variable is required based on other variables */
  requiredWhen?: (cleanedEnv: Record<string, unknown>) => boolean | undefined;
}