valitype

A lightweight TypeScript validation library for environment variables and configuration.

Features

• Validate values against predefined types (string, number, boolean, url, enum)
• Support for custom validators with helpful utilities
• Required field validation
• Default values
• Clear error messages

Installation

npm install valitype

Usage

import { validateValue, validators } from 'valitype';

// Basic type validation
validateValue('PORT', '8080', { type: 'number', required: true }); // returns 8080 as number
validateValue('DEBUG', 'true', { type: 'boolean' }); // returns true as boolean
validateValue('API_URL', 'https://api.example.com', { type: 'url', required: true }); // validates URL format

// Enum validation
validateValue('NODE_ENV', 'development', { 
  type: { enum: ['development', 'production', 'test'] },
  default: 'development'
});

// Custom validation
validateValue('API_KEY', 'abc123', {
  type: 'custom',
  validator: validators.regex(/^[a-z0-9]{6}$/),
  errorMessage: 'API_KEY must be 6 alphanumeric characters',
  required: true
});

Validation Types

String

{ type: 'string', required?: boolean, default?: string }

Number

{ type: 'number', required?: boolean, default?: number }

Boolean

{ type: 'boolean', required?: boolean, default?: boolean }

URL

{ type: 'url', required?: boolean, default?: string }

Enum

{ type: { enum: string[] }, required?: boolean, default?: string }

Custom

{ 
  type: 'custom', 
  validator: (value: string | undefined) => boolean | string,
  required?: boolean, 
  default?: string,
  errorMessage?: string 
}

Custom Validators

The library includes several built-in validator utilities:

Regex Validator

validators.regex(/^[A-Z]{3}$/, 'Must be 3 uppercase letters')

Range Validator

validators.range(1, 100, 'Value must be between 1 and 100')

OneOf Validator

validators.oneOf(['apple', 'banana', 'orange'], 'Must be a valid fruit')

Date Validator

validators.date('YYYY-MM-DD', 'Must be a valid date')

JSON Validator

validators.json('Must be valid JSON')

AWS ARN Validator

validators.awsArn('lambda', 'Must be a valid Lambda ARN')

Combining Validators

validators.all(
  validators.regex(/^[A-Z]/),
  validators.oneOf(['Alpha', 'Beta', 'Gamma'])
)

Error Handling

The library throws descriptive errors when validation fails:

try {
  validateValue('PORT', 'abc', { type: 'number', required: true });
} catch (error) {
  console.error(error.message); // "PORT must be a number"
}

Contributing

Contributions are welcome. See CONTRIBUTING.md file.

License

This library is licensed under the MIT License. See the LICENSE file for details.