evp-ts

1.1.1 verified Sat Apr 25 auth: no javascript

Lightweight environment variable parser for TypeScript, inspired by Zod and Haskell's EVP. Current stable version 1.1.1 is actively maintained with regular releases. Supports nested object parsing, type inference, secret masking, default values, optional fields, and dotenv-style help generation. Key differentiators: low dependency footprint, comprehensive error reporting that continues parsing all variables, and explicit logging with secret hashing. Alternative to dotenv with stronger typing and validation, but less mature ecosystem.

Common errors

error TypeError: EVP.infer is not a function ↓

cause EVP.infer is a type-level utility, not a runtime function. It cannot be used in JavaScript files or at runtime.

fix

Only use EVP.infer in TypeScript type annotations: type T = EVP.infer<typeof parser>

error Cannot find module 'evp-ts' or its corresponding type declarations. ↓

cause Missing @types/evp-ts or not installed with TypeScript (but package ships types). Possibly bundler misconfiguration.

fix

Ensure tsconfig.json has 'strict' or 'esModuleInterop' enabled. Try reinstalling: npm install evp-ts

error ReferenceError: EVP is not defined ↓

cause Using CommonJS require without destructuring correctly, or running in a non-ESM environment without transpilation.

fix

Use the ESM import syntax: import { EVP } from 'evp-ts'

error Error: Environment variable API_TOKEN is missing and no default provided ↓

cause Required environment variable not set and no default with .default() or .optional().

fix

Set the variable or add .default(value) or .optional() to the parser definition.

Warnings

breaking EVP.infer changed from returning a tuple to a single type in v1.0.0 ↓

fix Update usage to align with v1.x: EVP.infer<typeof parser> now returns the inferred config object type directly.

deprecated EVP.boolean() accepts 'yes'/'no' as truthy/falsy; this is unconfigurable and may not match all locales ↓

fix Use EVP.string() with custom validation if you need other truthy/falsy strings.

gotcha parse() does not throw on missing optional fields; it returns undefined for those keys ↓

fix Check for undefined or use .default() to ensure a value.

gotcha Secret values are hashed with SHA-256 in logs; only the hash is shown, but the actual value is still accessible in code ↓

fix Be careful not to log the config object directly in production.

Install

npm install evp-ts

yarn add evp-ts

pnpm add evp-ts

Imports

EVP

wrong

const EVP = require('evp-ts')

correct

import { EVP } from 'evp-ts'

ESM-only. No CommonJS support.

EVP.infer
wrong
```
type Config = Infer<typeof parser>
```
correct
```
type Config = EVP.infer<typeof parser>
```
EVP.infer is a type utility on the imported EVP namespace, not a separate export.

EVP.string

wrong

import { string } from 'evp-ts'

correct

import { EVP } from 'evp-ts'; const s = EVP.string()

All parsers are methods on the EVP object, not named exports.

Quickstart

Shows parsing environment variables with types, defaults, secret masking, and custom env names.

import { EVP } from 'evp-ts';

const parser = EVP.object({
  API_ENDPOINT: EVP.string(),
  API_TOKEN: EVP.string().secret(),
  HTTP_PORT: EVP.number(),
  DEBUG_MODE: EVP.boolean().default(false),
  DB_HOST: EVP.string().default('localhost').env('MYSQL_HOST'),
  DB_PORT: EVP.number().default(3306).env('MYSQL_PORT'),
});

type Config = EVP.infer<typeof parser>;
const config: Config = parser.parse();

console.log(config.API_ENDPOINT); // => string
console.log(config.HTTP_PORT);    // => number
console.log(config.DEBUG_MODE);   // => false (default)