or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

custom-validators.mderror-handling.mdindex.mdmiddleware.mdvalidation.mdvalidators.md
tile.json

index.mddocs/

Envalid

Envalid is a TypeScript library for environment variable validation that ensures programs only run when all environment dependencies are met. It provides type-safe validation, built-in validators, and comprehensive error handling for Node.js applications.

Package Information

  • Package Name: envalid
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install envalid

Core Imports

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

Complete import options:

import {
  // Core validation functions
  cleanEnv,
  customCleanEnv,
  testOnly,
  
  // Built-in validators
  str,
  num,
  bool,
  email,
  url,
  port,
  host,
  json,
  
  // Custom validator factories
  makeValidator,
  makeExactValidator,
  makeStructuredValidator,
  
  // Error classes
  EnvError,
  EnvMissingError,
  
  // Reporters and formatters
  defaultReporter,
  envalidErrorFormatter,
  
  // Middleware functions
  strictProxyMiddleware,
  accessorMiddleware,
  applyDefaultMiddleware,
  
  // Type interfaces
  type CleanedEnv,
  type CleanOptions,
  type ValidatorSpec,
  type Spec,
} from "envalid";

For CommonJS:

const {
  cleanEnv,
  str,
  num,
  bool,
  port,
  email,
  url,
  host,
  json,
  makeValidator,
  EnvError,
  EnvMissingError,
} = require("envalid");

Basic Usage

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

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

// Type-safe access to validated environment variables
console.log(env.PORT); // number
console.log(env.DEBUG); // boolean
console.log(env.isDevelopment); // boolean (convenience property)

Architecture

Envalid is built around several key components:

  • Core Validation: cleanEnv function that sanitizes and validates environment variables
  • Built-in Validators: Pre-built validators for common types (string, number, boolean, etc.)
  • Custom Validators: Factory functions for creating domain-specific validators
  • Middleware System: Extensible middleware for transforming validated environments
  • Error Handling: Comprehensive error reporting with detailed validation failures
  • Type Safety: Full TypeScript integration with strict typing throughout

Capabilities

Environment Validation

Core environment variable validation functionality that sanitizes and validates environment variables against specifications.

function cleanEnv<T extends Record<string, ValidatorSpec<any>>>(
  environment: unknown,
  specs: T,
  options?: CleanOptions<T>
): CleanedEnv<T>;

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>;

function testOnly<T>(defaultValueForTests: T): T;

Environment Validation

Built-in Validators

Collection of pre-built validators for common data types including strings, numbers, booleans, emails, URLs, and more.

const str: BaseValidator<string>;
const num: BaseValidator<number>;
const bool: ExactValidator<boolean>;
const email: BaseValidator<string>;
const url: BaseValidator<string>;
const port: BaseValidator<number>;
const host: BaseValidator<string>;
const json: StructuredValidator;

Built-in Validators

Custom Validators

Factory functions for creating custom validators with type safety and validation logic for domain-specific requirements.

function makeValidator<BaseT>(
  parseFn: (input: string) => BaseT
): BaseValidator<BaseT>;

function makeExactValidator<T>(
  parseFn: (input: string) => T
): ExactValidator<T>;

function makeStructuredValidator(
  parseFn: (input: string) => unknown
): StructuredValidator;

Custom Validators

Error Handling

Comprehensive error classes and reporting system for validation failures and missing environment variables.

class EnvError extends TypeError {
  constructor(message: string);
}

class EnvMissingError extends ReferenceError {
  constructor(message: string);
}

function defaultReporter<T>(
  opts: ReporterOptions<T>,
  extraOpts?: ExtraOptions<T>
): void;

function envalidErrorFormatter<T>(
  errors: Partial<Record<keyof T, Error>>,
  logger?: (data: any, ...args: any[]) => void
): void;

Error Handling

Middleware System

Extensible middleware system for transforming and enhancing validated environment objects with custom functionality.

function strictProxyMiddleware<T extends object>(
  envObj: T,
  rawEnv: unknown,
  options?: StrictProxyMiddlewareOptions
): Proxy<T>;

function accessorMiddleware<T>(
  envObj: T,
  rawEnv: unknown
): T & CleanedEnvAccessors;

function applyDefaultMiddleware<T>(
  cleanedEnv: T,
  rawEnv: unknown
): Proxy<T & CleanedEnvAccessors>;

Middleware System

Types

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' */
  readonly isDevelopment: boolean;
  /** Alias for isDevelopment */
  readonly isDev: boolean;
  /** True if NODE_ENV === 'test' */
  readonly isTest: boolean;
  /** True if NODE_ENV === 'production' */
  readonly isProduction: boolean;
  /** Alias for isProduction */
  readonly isProd: boolean;
}

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 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 non-production environments */
  devDefault?: NonNullable<T> | undefined;
  /** Function to determine if variable is required based on other variables */
  requiredWhen?: (cleanedEnv: Record<string, unknown>) => boolean | undefined;
}

type ValidatorSpec<T> = RequiredValidatorSpec<T> | OptionalValidatorSpec<T>;

interface RequiredValidatorSpec<T> extends Spec<T> {
  /** Internal parsing function */
  _parse: (input: string) => T;
}

interface OptionalValidatorSpec<T> extends Spec<T | undefined> {
  /** Internal parsing function */
  _parse: (input: string) => T;
}

type BaseValidator<BaseT> = <T extends BaseT = BaseT>(
  spec?: Spec<T>
) => ValidatorSpec<T>;

type ExactValidator<T> = (spec?: Spec<T>) => ValidatorSpec<T>;

type StructuredValidator = <T = unknown>(spec?: Spec<T>) => ValidatorSpec<T>;

interface StrictProxyMiddlewareOptions {
  /** Additional properties that can be inspected/enumerated */
  extraInspectables?: string[];
}