@kasifraza/env-validator

Type-safe environment variable validation with defaults, coercion, and early failure. Zero dependencies.

Install

npm install @kasifraza/env-validator

Usage

import { validateEnv } from '@kasifraza/env-validator';

const config = validateEnv({
  PORT: { type: 'number', default: 3000 },
  DATABASE_URL: { type: 'string' },
  REDIS_URL: { type: 'string' },
  ENABLE_CACHE: { type: 'boolean', default: true },
  NODE_ENV: { type: 'string', choices: ['development', 'production', 'test'] },
  ALLOWED_ORIGINS: { type: 'array', default: ['http://localhost:3000'] },
  AWS_CONFIG: { type: 'json', required: false },
});

// config is fully typed:
// config.PORT → number
// config.DATABASE_URL → string
// config.ENABLE_CACHE → boolean
// config.ALLOWED_ORIGINS → string[]

Features

• Type coercion — string, number, boolean, json, array
• Defaults — Fallback values when env var is not set
• Required/Optional — Required by default, opt-out with required: false
• Choices — Restrict to allowed values
• Custom transform — Apply any transformation function
• Collect all errors — Reports every invalid var at once, not one at a time
• Zero dependencies — No bloat
• Full TypeScript — Inferred return types from schema

API

validateEnv(schema, env?)

| Param | Type | Description | |-------|------|-------------| | schema | EnvSchema | Validation rules per variable | | env | Record<string, string> | Defaults to process.env |

Rule options

| Option | Type | Default | Description | |--------|------|---------|-------------| | type | 'string' \| 'number' \| 'boolean' \| 'json' \| 'array' | 'string' | Coercion type | | required | boolean | true | Throw if missing | | default | any | — | Fallback value | | choices | any[] | — | Allowed values | | transform | (value: string) => any | — | Custom transform (overrides type coercion) |

Custom transform example

const config = validateEnv({
  API_URL: {
    transform: (v) => v.replace(/\/$/, ''), // strip trailing slash
  },
});

Error handling

Throws EnvValidationError with all failures collected:

EnvValidationError: Environment validation failed:
  - DATABASE_URL is required but not set
  - PORT: Cannot convert "abc" to number
  - NODE_ENV must be one of [development, production, test], got "staging"

License

MIT