@azlabs/env-validator

Tiny, typed environment variable validator for Node.js.

Zero dependencies · < 1.5 KB gzipped · TypeScript-first

Install

npm install @azlabs/env-validator

Usage

import { env, str, num, bool, port } from '@azlabs/env-validator'

export const config = env({
  PORT:         port().default(3000),
  DATABASE_URL: str(),
  NODE_ENV:     str().oneOf(['development', 'production', 'test'] as const),
  API_KEY:      str().min(32),
  DEBUG:        bool().optional(),
})

// Fully typed — no `as` casts needed:
// config.PORT         → number
// config.NODE_ENV     → "development" | "production" | "test"
// config.DEBUG        → boolean | undefined

If any variable is missing or invalid, a descriptive error is thrown after collecting all errors:

Error: Invalid environment variables:
  PORT: must be a number
  DATABASE_URL: required
  API_KEY: min length: 32

Validators

str()

| Method | Description | |---|---| | .optional() | Allows undefined | | .default(val) | Fallback when not set | | .oneOf(vals) | Restrict to specific values — narrows TypeScript type | | .min(n) | Minimum string length | | .max(n) | Maximum string length |

num()

Coerces string → number automatically.

| Method | Description | |---|---| | .optional() | Allows undefined | | .default(val) | Fallback when not set | | .min(n) | Minimum value | | .max(n) | Maximum value | | .int() | Must be an integer |

bool()

Accepts true, false, 1, 0, yes, no (case-insensitive).

| Method | Description | |---|---| | .optional() | Allows undefined | | .default(val) | Fallback when not set |

url()

Validates via the native URL constructor.

| Method | Description | |---|---| | .optional() | Allows undefined |

email()

Lightweight format check (not RFC 5321 — use str() with a custom regex for strict validation).

| Method | Description | |---|---| | .optional() | Allows undefined |

json<T>()

Parses a JSON string value, optionally typed.

json<{ host: string; port: number }>()

| Method | Description | |---|---| | .optional() | Allows undefined |

port()

Shorthand for num().min(1).max(65535).int().

Custom source

Reads from process.env by default. Pass a second argument for a custom source (useful in tests):

const config = env(schema, { PORT: '3000', DATABASE_URL: '...' })

License

MIT