@caeljs/tsh NPM

# Type-Safe Validation Library

A robust, type-safe validation library for TypeScript that provides runtime validation while maintaining full type safety.

## Features

- 🛠️ **Type-safe validators** with TypeScript inference
- 🧩 **Composable API** for building complex validation schemas
- 🔍 **Runtime validation** with detailed error reporting
- 🏗️ **Object shape validation** with nested structures
- 🔄 **Coercion support** for common type conversions
- ✨ **Utility functions** for common validation patterns

## Installation

```bash
npm install @caeljs/tsh
# or
yarn add @caeljs/tsh

Basic Usage

import { t } from '@caeljs/tsh';

// Define a schema
const userSchema = object({
  name: t.string().required(),
  age: t.number().positive().int(),
  email: t.string().email(),
  tags: t.array(t.string()).minLength(1),
});

// Validate data
const result = t.validate({
  name: "Drylian",
  age: 23,
  email: "drylian@example.com",
  tags: ["developer", "typescript"]
}, userSchema);

if (result.success) {
  console.log("Valid data:", result.data);
} else {
  console.error("Validation error:", result.error);
}

Core Validators

Primitive Validators

t.string() - Validates string values
t.number() - Validates number values
t.boolean() - Validates boolean values
t.any() - Accepts any value
t.enum() - Validates against enum values

Complex Validators

t.object(shape) - Validates object structures
t.array(shape) - Validates arrays
t.record(keyShape, valueShape) - Validates dictionary/map structures
t.union(shapes) - Validates against multiple possible shapes

Modifiers

.optional() - Makes a field optional
.nullable() - Allows null values
.required() - Requires non-null, non-undefined values
.partial() - Makes all object properties optional
.refine(predicate, message) - Adds custom validation

Utility Functions

Validation

t.validate(value, shape) - Validates a value against a shape
t.isValid(value, shape) - Checks if a value is valid

Object Manipulation

t.pick(shape, keys) - Creates a shape with only specified keys
t.omit(shape, keys) - Creates a shape without specified keys
t.merge(shape1, shape2) - Merges two object shapes
t.extend(shape, extensions) - Extends an object shape

Array Utilities

t.nonEmptyArray(shape) - Requires non-empty arrays
t.uniqueArray(shape) - Requires unique array elements
t.minLength(shape, min) - Sets minimum array length
t.maxLength(shape, max) - Sets maximum array length

Common Validators

String Validators

t.email() - Validates email format
t.uuid() - Validates UUID format
t.url() - Validates URL format
t.ip() - Validates IP address
t.regex(pattern) - Validates against regex

Number Validators

t.int() - Validates integers
t.positive() - Validates positive numbers
t.negative() - Validates negative numbers
t.port() - Validates port numbers
t.percentage() - Validates percentages

Advanced Features

Logical Operators

t.and(shape1, shape2) - Requires both shapes to match (intersection)
t.or(shape1, shape2) - Requires either shape to match (union)
t.not(shape) - Requires value to NOT match shape

Coercion

import { t } from '@caeljs/tsh';

// Coerce values to specific types
const coercedString = t.coerce.string(); // Converts value to string
const coercedNumber = t.coerce.number(); // Converts value to number
const coercedBoolean = t.coerce.boolean(); // Converts value to boolean

Custom Validators

import { t } from '@caeljs/tsh';

// Create custom validator
const evenNumber = t.custom(
  (value): value is number => typeof value === 'number' && value % 2 === 0,
  'Value must be an even number'
);

Error Handling

All validation errors include detailed information about what failed:

try {
  shape.parse(invalidValue);
} catch (error) {
  if (error instanceof TshShapeError) {
    console.error(error.message);
    console.error(error.path); // Path to invalid field
    console.error(error.value); // Invalid value
  }
}

Type Safety

The library provides full TypeScript type inference:

const userSchema = t.object({
  name: t.string(),
  age: t.number(),
});

type User = t.infer<typeof userSchema>;
// Equivalent to:
// type User = {
//   name: string;
//   age: number;
// }

Random Value Generation

import { random, randomInt, randomUuid } from '@caeljs/tsh';

t.random(); // Random string
t.randomInt(1, 100); // Random integer between 1-100
t.randomUuid(); // Random UUID v4