@frauschert/ts-guard NPM

ts-guard

ts-guard is a TypeScript library that provides composable type guards. It's inspired by zod but focuses only on type guards and is more lightweight.

Installation

npm install @frauschert/ts-guard

Features

🎯 Pure TypeScript
💡 First-class type inference
🔒 Runtime type checking
🧩 Composable guards
🪶 Lightweight with treeshaking support
📘 Well documented

Basic Usage

import { isObject, isString, isNumber } from '@frauschert/ts-guard';

const isPerson = isObject({ name: isString(), age: isNumber() });
const value = { name: "John", age: 30 };

if (isPerson(value)) {
  // value is typed as { name: string; age: number }
  console.log(value.name); // TypeScript knows this is safe
}

Optimizing Bundle Size

The library provides several entry points to help you optimize your bundle size:

// Import only primitive type guards
import { isString, isNumber } from '@frauschert/ts-guard/primitive';

// Import only compound type guards
import { isObject, isArray } from '@frauschert/ts-guard/compound';

// Import Node.js specific guards (only in Node.js environment)
import { isBuffer } from '@frauschert/ts-guard/node';

Available Guards

Primitive Types

import { isString, isNumber, isBoolean, isBigInt } from '@frauschert/ts-guard/primitive';

isString({ minLength: 3, maxLength: 10, pattern: /^[A-Z]/, trim: true })
isNumber({ min: 0, max: 100, integer: true, positive: true })
isBoolean()
isBigInt({ min: 0n, max: 100n, positive: true })

Complex Types

import { isDate, isArrayOf, isObject, isInstanceOf } from '@frauschert/ts-guard/compound';

isDate()
isArrayOf(isString())
isObject({ name: isString(), age: isNumber() })
isInstanceOf(MyClass)

Type Composition

import { isUnion, isIntersection, isEnum, isOptional, isOneOf } from '@frauschert/ts-guard/compound';

// Union types
const isStringOrNumber = isUnion([isString(), isNumber()]);

// Intersection types
const isPerson = isObject({ name: isString() });
const hasAge = isObject({ age: isNumber() });
const isPersonWithAge = isIntersection([isPerson, hasAge]);

// Enum validation
enum Status { Active = 'ACTIVE', Inactive = 'INACTIVE' }
const isStatus = isEnum(Status);

// Optional values
const isOptionalString = isOptional(isString());

// Literal values
const isRole = isOneOf(['admin', 'user', 'guest']);

Node.js Specific Types

import { isBuffer } from '@frauschert/ts-guard/node';

// Only available in Node.js environment
isBuffer()

Type Inference

The library provides full type inference:

import { isObject, isString, isNumber, TypeOf } from '@frauschert/ts-guard';

const isPerson = isObject({
  name: isString(),
  age: isNumber({ positive: true }),
  email: isOptional(isString())
});

type Person = TypeOf<typeof isPerson>;
// Inferred as: {
//   name: string;
//   age: number;
//   email?: string | undefined;
// }