README.md

TypeGuards

Runtime type checking library for TypeScript & JavaScript.

✨ Features

• Provides runtime type validation.
• Can derive static type from any type guard, thus types are never out of sync.
• Supports nested type guards.
• Supports almost all JS data types, including Promise, Proxy, DataView and typed arrays.
• Package has 0 dependency.

📦 Installation

# npm
npm install @typeguards/core
# yarn
yarn add @typeguards/core

🔨 Usage

Basics

import T from '@typeguards/core'

T.Number.validates(1) // true
T.Number.validates('1') // false
T.Optional(T.String).validates('1') // true
T.Optional(T.String).validates(undefined) // true
T.Optional(T.String).validates(1) // false

// Custom type guard
const Range = T.Number.config({
  // Custom validation function
  validate: value => typeof value === 'number' && value > 0 && value < 3,
})
Range.validate(0) // false
Range.validate(1) // true
Range.validate(2) // true
Range.validate(3) // false

Schema

import type { Static } from '@typeguards/core'
import T, { createSchema } from '@typeguards/core'

const Age = T.Number.config({ validate: v => typeof v === 'number' && v >= 0 })

// Custom schema
const JobSchema = T.Schema({
  title: T.String,
  salary: T.Nullable(T.Number),
})

// Use closure to use type guard directly & prevent naming conflicts with JS built-in objects
const PersonSchema = createSchema(({ Boolean, String, Number, Array, Optional, Union }) => ({
  name: String,
  age: Age,
  alive: Boolean,
  address: Optional(String),
  // Support complex nested type guard
  favorites: Array(Union(String, Number)),
  // Support nested schema
  job: JobSchema,
}))

// Support static type derivation, thus type is never out of sync
const person: Static<typeof PersonSchema> = {
  name: 'John Doe',
  age: 23,
  alive: true,
  address: undefined,
  favorites: ['cat', 'dog', 7],
  job: {
    title: 'Dreamer',
    salary: null,
  },
}

PersonSchema.validate(person) // true
PersonSchema.validate({ ...person, address: undefined }) // true, because address is optional
PersonSchema.validate({ ...person, name: undefined }) // false
PersonSchema.validate({ ...person, age: '23' }) // false

const CatSchema = T.Partial(T.Pick(PersonSchema, ['name', 'age', 'alive']))
// Equivalent to Partial<Pick<PersonType, 'name' | 'age' | 'alive'>>
type Cat = Static<typeof CatSchema>

CatSchema.validate(person) // false
CatSchema.validate({ name: 'Baby', age: undefined }) // true

// Retrieve Schema definition
const catDefinition = CatSchema.definition() // { name: String, age: Age, alive: Boolean }
// Retrieve Indexed access type definition, which is a type guard in this case
const CatName = CatSchema.definition('name') // T.String
CatName.validate('str') // true
catDefinition.name.validate('str') // true

Transformer (Experimental Feature)

import T from '@typeguards/core'

// Customize transformation function
const Name = T.String.config({ transform: val => `${val} Jr.` })
const Alive = T.Boolean.config({ transform: val => val ?? true })
const Person = T.Partial(T.Schema({ name: Name, alive: Alive }))

const john = { name: 'John' }
Person.validate(john) // true
const johnJr = Person.transform(john) // { name: 'John Jr.', alive: true }

🛡️ List of type guards

name	description
Boolean
StringBoolean	"true" | "TRUE" | "false" | "FALSE" | "1" | "0"
Number
NaN	NaN
PositiveNumber	A number value that's greater than 0
NegativeNumber	A number value that's less than 0
BigInt
PositiveBigInt	A BigInt value that's greater than 0
NegativeBigInt	A BigInt value that's less than 0
StringNumber	A string whose value is a number, such as "0", "-1", "3.333"
String
NonEmptyString	A string that's not empty even after trimming
Symbol
Undefined	undefined
Null	null
Object	An object (Any object will qualify as long as typeof obj === 'object')
RegExp
Map
WeakMap
Set
WeakSet
Promise
Proxy
Date
StringDate	A correctly formatted date string, such as "1996-07-23", "1996/07/23", "1996 Jul", "1996"
Array
StringArray	A string whose value is an array separated by delimiter "," (delimiter is customizable)
ArrayBuffer
SharedArrayBuffer
DataView
Int8Array
Uint8Array
Uint8ClampedArray
Int16Array
Uint16Array
Int32Array
Uint32Array
Float32Array
Float64Array
BigInt64Array
BigUint64Array
Function	A function
Schema	A plain object
Optional	T | undefined
Nullable	T | null
Never	Equivalent of TypeScript never type
Unknown	Equivalent of TypeScript unknown type
Any	Equivalent of TypeScript any type
Record	Equivalent of TypeScript Record type
Partial	Equivalent of TypeScript Partial type
Required	Equivalent of TypeScript Required type
Pick	Equivalent of TypeScript Pick type
Omit	Equivalent of TypeScript Omit type
NonNullable	Equivalent of TypeScript NonNullable type
Union	Equivalent of TypeScript union type
Const	Equivalent of TypeScript const assertion
GeneratorFunction	Requires ES6/ES2015 or later
Generator	Requires ES6/ES2015 or later
AsyncFunction	Requires ES8/ES2017 or later

📜 License

Apache License 2.0