CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-envalid

Validation for your environment variables

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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[];
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/envalid@8.1.x
Publish Source
CLI
Badge
tessl/npm-envalid badge