typeGuard

Type Guard Pro

A zero-dependency TypeScript runtime type validation library that provides comprehensive type safety with minimal overhead.

Features

• 🔍 Type Safety: Runtime validation that complements TypeScript’s static typing
• 🚀 Ultra Lightweight: Just ~3KB minified and gzipped with zero dependencies
• ⚡ High Performance: Up to 80% faster than alternatives with lower memory usage
• 🧩 Extensible: Plugin system for custom validators
• 📘 Type Inference: Full TypeScript type inference with no type-casting needed
• 🛠️ Advanced Type Support: Handles tuples, literals, records, refined types and more

Try it Online

Live Demo - Experiment with the library in your browser

Installation

npm install type-guard-pro
# or
yarn add type-guard-pro
# or
pnpm add type-guard-pro

Basic Usage

import { createGuard, guards } from 'type-guard-pro';

// Define your TypeScript interface
interface User {
  id: number;
  name: string;
  email: string;
  active: boolean;
  createdAt: Date;
}

// Create a type guard for the interface
const userGuard = createGuard<User>().object({
  id: guards.number,
  name: guards.string,
  email: guards.email, // Built-in email validation
  active: guards.boolean,
  createdAt: guards.date,
});

// Use the guard to validate data
function processUser(data: unknown): User {
  if (userGuard(data)) {
    // TypeScript now knows that data is a valid User
    return data;
  }
  throw new Error('Invalid user data');
}

// Or with error handling
try {
  const result = userGuard(data, { throwOnError: true });
  // data is valid if we get here
} catch (error) {
  console.error('Validation failed:', error);
}

Advanced Features

Array Validation

// Array of numbers
const numberArrayGuard = createGuard<number[]>().array(guards.number);

// Array of objects
const userArrayGuard = createGuard<User[]>().array(userGuard);

Union Types

// String or number
const stringOrNumberGuard = createGuard<string | number>().union(
  guards.string,
  guards.number
);

Intersection Types

// Both interfaces must be satisfied
const tokenGuard = createGuard<Token & Expirable>().intersection(
  tokenGuard,
  expirableGuard
);

Tuple Types

// Validate exact tuple structure
const pointGuard = createGuard<[number, number]>().tuple(
  guards.number,
  guards.number
);

// Also works with mixed types
const nameAgeGuard = createGuard<[string, number]>().tuple(
  guards.string,
  guards.number
);

Literal Types

// Exact value matching
const statusGuard = createGuard<'active' | 'inactive' | 'pending'>().union(
  createGuard().literal('active'),
  createGuard().literal('inactive'),
  createGuard().literal('pending')
);

Record Types

// Dictionaries/maps with specific key and value types
const configGuard = createGuard<Record<string, boolean>>().record(
  (key): key is string => typeof key === 'string',
  guards.boolean
);

Partial Objects

// Partial objects where all fields are optional
const partialUserGuard = createGuard<Partial<User>>().partial({
  id: guards.number,
  name: guards.string,
  email: guards.email,
  active: guards.boolean,
  createdAt: guards.date,
});

Refined Types

// Add additional validation constraints to base types
const positiveNumberGuard = createGuard<number>().refined(
  guards.number,
  (value) => value > 0
);

const emailGuard = createGuard<string>().refined(guards.string, (value) =>
  /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
);

Built-in Guards

Type Guard Pro comes with a variety of pre-built guards:

// Primitive guards
guards.string; // String validation
guards.number; // Number validation
guards.boolean; // Boolean validation
guards.date; // Date object validation
guards.null; // null validation
guards.undefined; // undefined validation
guards.bigint; // BigInt validation
guards.symbol; // Symbol validation
guards.object; // Object validation
guards.function; // Function validation

// Enhanced guards
guards.integer; // Integer validation
guards.positiveNumber; // Positive number validation
guards.negativeNumber; // Negative number validation
guards.nonEmptyString; // Non-empty string validation
guards.email; // Email format validation
guards.url; // URL format validation
guards.uuid; // UUID format validation
guards.iso8601Date; // ISO 8601 date string validation

Custom Validation

const passwordGuard = createGuard<string>().custom((value): value is string => {
  if (typeof value !== 'string') return false;

  // At least 8 characters, 1 uppercase, 1 lowercase, 1 number
  return /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{8,}$/.test(value);
});

Plugin System

import { registerPlugin, getPlugin } from 'type-guard-pro';

// Create a custom validator plugin
const creditCardPlugin = {
  name: 'creditCard',
  validate: (value: unknown): value is string => {
    if (typeof value !== 'string') return false;
    // Luhn algorithm implementation for credit card validation
    // ...validation logic here...
    return true;
  },
};

// Register the plugin
registerPlugin(creditCardPlugin);

// Use the plugin
const plugin = getPlugin('creditCard');
if (plugin && plugin.validate('4111111111111111')) {
  console.log('Valid credit card');
}

Performance

Type Guard Pro is designed to be lightweight and performant:

• Bundle Size: ~3KB minified and gzipped (83% smaller than alternatives)
• Execution Speed: 30-80% faster than comparable libraries
• Memory Usage: 57-80% less memory usage during validation
• Dependencies: Zero external dependencies

Benchmarks

Library	Bundle Size	Validation Speed	Memory Usage
Type Guard Pro	3KB	0.68ms	217KB
Zod	29.4KB	1.24ms	502KB
Yup	44.1KB	2.31ms	784KB
Joi	64.2KB	3.56ms	1046KB

Benchmark data from validating a complex object with 50+ nested fields, arrays, and mixed types.

Browser and Node.js Support

Type Guard Pro works in both browser and Node.js environments:

• Modern browsers (Chrome, Firefox, Safari, Edge)
• Node.js 14+
• Supports ESM and CommonJS imports

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT

This site is open source. Improve this page.