Home Original page

GitHub - stacksjs/ts-validation: Lightweight & performant form & request data validation library.

Social Card of this repo

npm version GitHub Actions Commitizen friendly

A lightweight, type-safe validation library for TypeScript with blazing-fast performance, built for Bun.

Features

  • 🚀 Blazing fast performance - Optimized for speed
  • 🔒 Type-safe - Full TypeScript support with strong typing
  • 🔄 Fluent API - Chain validation rules for clean, readable code
  • 🏗️ Composable - Create reusable validations and schemas
  • 🧩 Extendable - Easy to add custom validators
  • 💾 Tiny footprint - Lightweight with no dependencies
  • 🔍 Detailed errors - Comprehensive error reporting
  • 🛡️ Robust validation - Handles null, undefined, and edge cases properly

Installation

# Using bun
bun add @stacksjs/ts-validation

# Using npm
npm install @stacksjs/ts-validation

# Using yarn
yarn add @stacksjs/ts-validation

# Using pnpm
pnpm add @stacksjs/ts-validation

Quick Start

import { v } from '@stacksjs/ts-validation'

// Create a validator for a user object
const userValidator = v.object({
  name: v.string().min(2).max(50).required(),
  email: v.string().email().required(),
  age: v.integer().min(18).max(120).required(),
  website: v.string().url().optional(),
  tags: v.array().each(v.string()).optional(),
})

// Validate a user object
const user = {
  name: 'John Doe',
  email: 'john@example.com',
  age: 25,
  website: 'https://example.com',
  tags: ['developer', 'TypeScript'],
}

const result = userValidator.validate(user)

if (result.valid) {
  console.log('User is valid!')
}
else {
  console.error('Validation errors:', result.errors)
}

Basic Usage

Simple Validation

import { v } from '@stacksjs/ts-validation'

// Validate a single value
const emailValidator = v.string().email().required()
const result = emailValidator.validate('john@example.com')

if (result.valid) {
  console.log('Email is valid!')
}
else {
  console.log('Validation errors:', result.errors)
}

// Quick test method
const isValid = emailValidator.test('john@example.com') // returns boolean

Error Handling

const result = userValidator.validate(invalidUser)

if (!result.valid) {
  // For single field validation
  result.errors.forEach((error) => {
    console.log(error.message)
  })

  // For object validation
  Object.entries(result.errors).forEach(([field, errors]) => {
    console.log(`${field}:`, errors.map(e => e.message))
  })
}

Validation Types

String Validation

// Basic string validation
const nameValidator = v.string().min(2).max(50).required()

// Email validation
const emailValidator = v.string().email().required()

// URL validation
const websiteValidator = v.string().url().optional()

// Pattern matching
const zipCodeValidator = v.string().matches(/^\d{5}$/).required()

// Alphanumeric, alpha, or numeric characters
const usernameValidator = v.string().alphanumeric().required()

// Text validation (specialized for text content)
const bioValidator = v.text().max(500).optional()

Number Validation

// Basic number validation
const ageValidator = v.number().min(18).max(120).required()

// Integer validation (whole numbers only)
const quantityValidator = v.integer().positive().required()

// Float validation (decimal numbers)
const priceValidator = v.float().min(0.01).required()

// Small integer validation (-32,768 to 32,767)
const smallNumberValidator = v.smallint().required()

// Decimal validation (with precision control)
const decimalValidator = v.decimal().min(0).max(999.99).required()

// Negative numbers
const temperatureValidator = v.number().negative().required()

Boolean Validation

// Boolean validation
const termsAcceptedValidator = v.boolean().required()

Array Validation

// Array validation
const tagsValidator = v.array().min(1).max(10).required()

// Validate each item in the array
const numbersValidator = v.array().each(v.number().positive()).required()

// Array with specific length
const coordinatesValidator = v.array().length(2).each(v.number()).required()

Object Validation

// Object validation
const addressValidator = v.object({
  street: v.string().required(),
  city: v.string().required(),
  state: v.string().length(2).required(),
  zip: v.string().matches(/^\d{5}$/).required(),
})

// Nested object validation
const userValidator = v.object({
  name: v.string().required(),
  address: addressValidator,
})

// Strict object validation (no extra fields allowed)
const strictValidator = v.object().strict().shape({
  id: v.number().required(),
  name: v.string().required(),
})

Date and Time Validation

// Basic date validation
const dateValidator = v.date()
expect(dateValidator.test(new Date())).toBe(true)
expect(dateValidator.test(new Date('invalid'))).toBe(false)

// Datetime validation (MySQL DATETIME compatible)
const datetimeValidator = v.datetime()
expect(datetimeValidator.test(new Date('2023-01-01'))).toBe(true)

// Time validation (24-hour format)
const timeValidator = v.time()
expect(timeValidator.test('14:30')).toBe(true)
expect(timeValidator.test('25:00')).toBe(false) // Invalid hour

// Unix timestamp validation
const unixValidator = v.unix()
expect(unixValidator.test(1683912345)).toBe(true) // Seconds
expect(unixValidator.test(1683912345000)).toBe(true) // Milliseconds

// Regular timestamp validation (MySQL TIMESTAMP compatible)
const timestampValidator = v.timestamp()
expect(timestampValidator.test(0)).toBe(true) // 1970-01-01 00:00:00 UTC

// Timestamp with timezone
const timestampTzValidator = v.timestampTz()

JSON Validation

// JSON string validation
const jsonValidator = v.json()
expect(jsonValidator.test('{"name": "John"}')).toBe(true)
expect(jsonValidator.test('{"a": 1, "b": 2}')).toBe(true)
expect(jsonValidator.test('123')).toBe(false) // Primitive values are invalid
expect(jsonValidator.test('not json')).toBe(false)

Binary and Blob Validation

// Binary data validation
const binaryValidator = v.binary()

// Blob validation
const blobValidator = v.blob()

BigInt Validation

// BigInt validation
const bigIntValidator = v.bigint().min(0n).max(1000000n).required()

Enum Validation

// Enum validation
const statusValidator = v.enum(['active', 'inactive', 'pending']).required()

Custom Validation

// Custom validation
const isEven = (val: number) => val % 2 === 0
const evenNumberValidator = v.custom(isEven, 'Number must be even')

// Complex custom validation
const passwordValidator = v.string()
  .min(8)
  .matches(/[A-Z]/)
  .matches(/[a-z]/)
  .matches(/\d/)
  .matches(/[^A-Z0-9]/i)

Password Validation

The password validator provides comprehensive password validation with multiple security rules:

// Basic password validation
const passwordValidator = v.password()
  .min(8)
  .max(128)
  .alphanumeric()
  .hasUppercase()
  .hasLowercase()
  .hasNumbers()
  .hasSpecialCharacters()

// Validate a password
const result = passwordValidator.validate('MySecureP@ss123')

if (result.valid) {
  console.log('Password is valid!')
}
else {
  console.error('Validation errors:', result.errors)
}

// Password matching validation
const confirmPasswordValidator = v.password().matches('MySecureP@ss123')

Advanced Usage

Conditional Validation

const userValidator = v.object({
  name: v.string().required(),
  email: v.string().email().required(),
  age: v.integer().min(18).required(),
  // Conditional validation based on age
  guardianInfo: v.object({
    name: v.string().required(),
    phone: v.string().required(),
  }).custom((value, data) => {
    return data.age < 18 ? value !== null : true
  }, 'Guardian information required for users under 18'),
})

Reusable Validators

// Create reusable validators
const emailValidator = v.string().email().required()
const phoneValidator = v.string().matches(/^\+?[\d\s-()]+$/).required()

// Use them in multiple places
const contactFormValidator = v.object({
  email: emailValidator,
  phone: phoneValidator,
})

const userProfileValidator = v.object({
  primaryEmail: emailValidator,
  secondaryEmail: emailValidator.optional(),
  phone: phoneValidator.optional(),
})

Validation with Custom Error Messages

const userValidator = v.object({
  name: v.string()
    .min(2, 'Name must be at least 2 characters')
    .max(50, 'Name cannot exceed 50 characters')
    .required('Name is required'),
  email: v.string()
    .email('Please provide a valid email address')
    .required('Email is required'),
})

Error Handling Examples

// Single field validation
const emailResult = emailValidator.validate('invalid-email')
if (!emailResult.valid) {
  emailResult.errors.forEach((error) => {
    console.log(`Email error: ${error.message}`)
  })
}

// Object validation
const userResult = userValidator.validate(invalidUser)
if (!userResult.valid) {
  // userResult.errors is an object with field names as keys
  Object.entries(userResult.errors).forEach(([field, errors]) => {
    console.log(`${field}:`)
    errors.forEach((error) => {
      console.log(`  - ${error.message}`)
    })
  })
}

Performance Tips

  1. Reuse validators: Create validators once and reuse them instead of creating new ones for each validation
  2. Use specific validators: Use v.integer() instead of v.number().integer() for better performance
  3. Chain efficiently: Order validation rules from most likely to fail first
  4. Avoid unnecessary validations: Use .optional() for fields that can be undefined

TypeScript Integration

import { v } from '@stacksjs/ts-validation'

// Type-safe validation
interface User {
  name: string
  email: string
  age: number
}

const userValidator = v.object({
  name: v.string().required(),
  email: v.string().email().required(),
  age: v.integer().min(18).required(),
})

// The result is fully typed
const result = userValidator.validate(userData)
if (result.valid) {
  // TypeScript knows userData is valid here
  const validUser: User = userData
}

Configuration

You can customize the validation behavior by modifying the validation.config.ts file:

// validation.config.ts
import type { ValidationOptions } from '@stacksjs/ts-validation'

const config: ValidationOptions = {
  verbose: true, // Enable detailed error messages
  strictMode: false, // Stop on first error if true
  cacheResults: true, // Cache validation results for better performance
  errorMessages: {
    // Customize error messages
    required: '{field} is required',
    email: '{field} must be a valid email address',
    // ...more custom messages
  },
}

export default config

Testing

Changelog

Please see our releases page for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Credits

  • validator.js - for the original string validation functions

Postcardware

"Software that is free, but hopes for a postcard." We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙