enval

Zero-dependency TypeScript library to validate environment variables at startup — fail fast with clear, structured errors.

Features

• Fully typed schema definition
• Six field types: string, number, boolean, enum, url, email
• Required fields, default values, and rich per-type constraints
• Coerces raw strings into proper JS values (number, boolean, …)
• Two error modes: throw immediately or collect and return all errors
• Optional CLI to validate a schema against the live environment

What failure looks like

When validation fails, enval prints a single, scannable error block to stderr — one line per problem with the received value and an optional description beneath each entry:

Environment variables validation - 3 errors

API_KEY: value is required but missing

PORT: must be <= 65535
    received: "99999"
    The port the HTTP server listens on

NODE_ENV: must be one of development, production, test
    received: "staging"

Exit code is 1, so CI pipelines and process managers catch it immediately.

---

Installation

npm install @tonyrubanraj/enval

Quick start

import { validate } from "@tonyrubanraj/enval";

const result = validate(
  {
    PORT: { type: "number", min: 1, max: 65535, default: 3000 },
    NODE_ENV: { type: "enum", values: ["development", "production", "test"] },
    API_KEY: { type: "string", required: true },
    DEBUG: { type: "boolean", default: false },
  },
  { onError: "return" },
);

if (!result.success) {
  console.error(result.errors);
  process.exit(1);
}

// result.data is fully coerced
const { PORT, NODE_ENV, API_KEY, DEBUG } = result.data as {
  PORT: number;
  NODE_ENV: string;
  API_KEY: string;
  DEBUG: boolean;
};

API

validate(schema, options?)

Validates environment variables against a schema.

Parameter	Type	Description
schema	EnvSchema	Record of variable names to field specs
options.env	Record<string, string>	Variable source — defaults to process.env
options.onError	"throw" | "return"	"throw" (default) throws on the first batch of errors; "return" always returns a result

Returns a ValidationResult:

interface ValidationResult {
  success: boolean;
  data: Record<string, unknown>; // coerced values
  errors: FieldError[];
}

---

Schema field types

All field types share these common properties:

Property	Type	Description
required	true	Fails validation when the variable is absent
description	string	Included in error messages for context
default	(varies)	Used when the variable is absent or empty

number

{ type: "number", min?: number, max?: number, integer?: boolean }

Property	Description
min	Value must be ≥ min
max	Value must be ≤ max
integer	Value must be a whole number

string

{ type: "string", minLength?: number, maxLength?: number, pattern?: RegExp }

Property	Description
minLength	Minimum character length
maxLength	Maximum character length
pattern	Must match the given regular expression

boolean

{ type: "boolean", truthy?: string[], falsy?: string[] }

Defaults accept true / 1 / yes / on / enabled as true and false / 0 / no / off / disabled as false. Override with custom truthy / falsy arrays.

enum

{ type: "enum", values: readonly string[] }

Value must be one of the items in values.

url

{ type: "url", protocols?: string[] }

Property	Description
protocols	Allowed URL protocols, e.g. ["https:"]

email

{
  type: "email";
}

Value must be a valid email address.

---

CLI

enval ships a CLI that validates the live process.env against a schema file and exits with code 1 if validation fails.

enval --schema ./env.schema.js

The schema file must export a default EnvSchema object:

// env.schema.ts  (compiled to env.schema.js)
import type { EnvSchema } from "@tonyrubanraj/enval";

const schema: EnvSchema = {
  PORT: { type: "number", min: 1, max: 65535, required: true },
  API_KEY: { type: "string", required: true },
};

export default schema;

Add it as a pre-start check in package.json:

{
  "scripts": {
    "prestart": "enval --schema ./dist/env.schema.js",
    "start": "node dist/index.js"
  }
}

---

Types reference

type EnvSchema = Record<string, FieldSpec>;

interface Options {
  env?: Record<string, string>;
  onError?: "return" | "throw";
}

interface FieldError {
  variable: string;
  message: string;
  description?: string;
  received?: string;
}

interface ValidationResult {
  success: boolean;
  data: Record<string, unknown>;
  errors: FieldError[];
}

License

MIT