[![MIT license][license-badge]][license]
[![NPM version][npm-badge]][npm]

ts-guardian

Runtime type guards. Composable, TypeScript-like syntax. 100% type-safe.

Full TypeScript support _(TypeScript not required)_.

$3

Type guards let you check whether a value matches a type at runtime.
ts-guardian makes them composable, readable, and type-safe — no more verbose checks or unsafe assertions.

If you're working with API responses, optional object members, or unknown values, ts-guardian will help you out.

Installation

``
npm install ts-guardian
`

Quick Start

Import the is function and create a type-guard, such as isUser. Use that type-guard to confirm objects match the type:

`ts
import { is } from 'ts-guardian'

const isUser = is({
id: 'number',
name: 'string',
email: 'string?',
teamIds: 'number[]',
})

isUser({ id: 1, name: 'John', teamIds: [2, 3] }) // true
`

$3

- Minimal and declarative syntax improves readability.
- Composable type guards mimick the way types are constructed.
- 100% type-safety means no assumptions, type assertions, or inaccurate type predicates.

API

- is function
- Basic types
- Union types
- Intersection types
- Literal types
- Array types
- Object types
- Tuple types
- Instance types
- Optional and nullable types
- Parsing to user-defined types
- Composition
- Throwing

$3

`ts
import { is } from 'ts-guardian'
`

The main tool to create type guards. The is function takes a parameter that defines a type, and returns a guard for that type:

`ts
const isNumber = is('number') // guard for 'number'
isNumber(0) // true
isNumber('') // false
`

$3

Pass a type string to create guards for basic types:

`ts
const isBoolean = is('boolean') // guard for 'boolean'
const isNull = is('null') // guard for 'null'
`

All basic type strings:

| String | Type | Equivalent type check |
| ------------- | ----------- | ------------------------------- |
| 'any' | any | true (matches anything) |
| 'boolean' | boolean | typeof === 'boolean' |
| 'bigint' | bigint | typeof === 'bigint' |
| 'function' | Function | typeof === 'function' |
| 'null' | null | === null |
| 'number' | number | typeof === 'number' |
| 'object' | object | typeof === 'object' |
| 'string' | string | typeof === 'string' |
| 'symbol' | symbol | typeof === 'symbol' |
| 'undefined' | undefined | === undefined |
| 'unknown' | unknown | true (matches anything) |

> Basic guards will return false for objects created with constructors. For example, is('string')(new String()) returns false. Use isInstanceOf instead.

$3

Every guard has an or method with the same signature as is. You can use or to create union types:

`ts
const isStringOrNumber = is('string').or('number') // guard for 'string | number'
isStringOrNumber('') // true
isStringOrNumber(0) // true
isStringOrNumber(true) // false
`

$3

Pass a number, string, or boolean to the isLiterally function and the orLiterally method to create guards for literal types. You can also pass multiple arguments to create literal union type guards:

`ts
import { isLiterally } from 'ts-guardian'

const isCat = isLiterally('cat') // guard for '"cat"'
const is5 = isLiterally(5) // guard for '5'
const isTrue = isLiterally(true) // guard for 'true'
const isCatOr5 = isLiterally('cat').orLiterally(5) // guard for '"cat" | 5'
const isCatOr5OrTrue = isLiterally('cat', 5, true) // guard for '"cat" | 5 | true'
`

$3

To check that every element in an array is of a specific type, use the isArrayOf function and the orArrayOf method:

`ts
import { is, isArrayOf } from 'ts-guardian'

const isStrArr = isArrayOf('string') // guard for 'string[]'
const isStrOrNumArr = isArrayOf(is('string').or('number')) // guard for '(string | number)[]'
const isStrArrOrNumArr = isArrayOf('string').orArrayOf('number') // guard for 'string[] | number[]'
`

> Note the difference between isStrOrNumArr which is a guard for (string | number)[], and isStrArrOrNumArr which is a guard for string[] | number[].

For basic array types, you can simply pass a string to the is function instead of using isArrayOf:

`ts
import { is } from 'ts-guardian'

const isStrArr = is('string[]') // guard for 'string[]'
const isStrArrOrNumArr = is('string[]').or('number[]') // guard for 'string[] | number[]'
`

$3

To check that every value in an object is of a specific type, use the isRecordOf function and the orRecordOf method:

`ts
import { is, isRecordOf } from 'ts-guardian'

const isStrRecord = isRecordOf('string') // guard for 'Record'
const isStrOrNumRecord = isRecordOf(is('string').or('number')) // guard for 'Record'
const isStrRecordOrNumRecord = isRecordOf('string').orRecordOf('number') // guard for 'Record | Record'
`

$3

Guards for tuples are defined by passing a tuple to is:

`ts
const isStrNumTuple = is(['string', 'number']) // guard for '[string, number]'
isStrNumTuple(['high']) // false
isStrNumTuple(['high', 5]) // true
`

Guards for nested tuples can be defined by nesting tuple guards inside tuple guards:

`ts
const isStrAndNumNumTupleTuple = is(['string', is(['number', 'number'])]) // guard for '['string', [number, number]]'
`

$3

Use is({}) to check for any non-null object. Avoid is('object') as it matches null:

`ts
const isObject = is({}) // guard for '{}'
isObject({ some: 'prop' }) // true
isObject(null) // false
`

To create a guard for an object with specific members, define a guard for each member key:

`ts
const hasAge = is({ age: 'number' }) // guard for '{ age: number; }'
hasAge({ name: 'John' }) // false
hasAge({ name: 'John', age: 40 }) // true
`

$3

Every type guard has an and method which has the same signature as or. Use and to create intersection types:

`ts
const hasXOrY = is({ x: 'any' }).or({ y: 'any' }) // guard for '{ x: any; } | { y: any; }'
hasXOrY({ x: '' }) // true
hasXOrY({ y: '' }) // true
hasXOrY({ x: '', y: '' }) // true

const hasXAndY = is({ x: 'any' }).and({ y: 'any' }) // guard for '{ x: any; } & { y: any; }'
hasXAndY({ x: '' }) // false
hasXAndY({ y: '' }) // false
hasXAndY({ x: '', y: '' }) // true
`

$3

Guards for object instances are defined by passing a constructor object to the isInstanceOf function and the orInstanceOf method:

`ts
const isDate = isInstanceOf(Date) // guard for 'Date'
isDate(new Date()) // true

const isRegExpOrUndefined = is('undefined').orInstanceOf(RegExp) // guard for 'undefined | RegExp'
isRegExpOrUndefined(/./) // true
isRegExpOrUndefined(new RegExp('.')) // true
isRegExpOrUndefined(undefined) // true
`

This works with user-defined classes too:

`ts
class Person {
name: string
constructor(name: string) {
this.name = name
}
}

const john = new Person('John')
const isPerson = isInstanceOf(Person) // guard for 'Person'
isPerson(john) // true
`

$3

Use isOptional, isNullable, and isNullish to quickly create guards for optional and nullable types:

`ts
import { isOptional, isNullable, isNullish } from 'ts-guardian'

const isOptionalNumber = isOptional('number') // guard for 'number | undefined'
const isNullableNumber = isNullable('number') // guard for 'number | null'
const isNullishNumber = isNullish('number') // guard for 'number | null | undefined'
`

For optional basic types, you can simply pass a string to the is function instead of using isOptional:

`ts
import { is } from 'ts-guardian'

const isOptionalString = is('string?') // guard for 'string | undefined'
const isOptionalNumberArray = is('number[]?') // guard for 'number[] | undefined'
`

$3

Consider the following type and its guard:

`ts
type Book = {
title: string
author: string
}

const isBook = is({
title: 'string',
author: 'string',
})
`

If isBook returns true for a value, that value will be typed as:

`ts
{
title: string
author: string
}
`

Ideally, we want to type the value as Book, while avoiding type assertions and user-defined type predicates.

One way is with a parse function that utilizes TypeScript's implicit casting:

`ts
const parseBook = (input: any): Book | undefined => {
return isBook(input) ? input : undefined
}
`

TypeScript will complain if the type predicate returned from isBook is not compatible with the Book type. This function is type-safe, but defining it is tedious.

Instead, you can use the parserFor function:

`ts
import { parserFor } from 'ts-guardian'

const parseBook = parserFor(isBook)
`

The parserFor function takes a guard, and returns a function you can use to parse values.

This function acts in the same way as the previous parseBook function. It takes a value and passes it to the guard. If the guard matches, it returns the value typed as the supplied user-defined type. If the guard does not match, the function returns undefined:

`ts
const book = {
title: 'Odyssey',
author: 'Homer',
}

const film = {
title: 'Psycho',
director: 'Alfred Hitchcock',
}

parseBook(book) // book as type 'Book'
parseBook(film) // undefined
`

The parserFor function is type-safe. TypeScript will complain if you try to create a parser for a user-defined type that isn't compatible with the supplied type guard:

`ts
const parseBook = parserFor(isBook) // Fine
const parseBook = parserFor(isString) // TypeScript error - type 'string' is not assignable to type 'Book'
`

$3

Guards can be composed from existing guards:

`ts
const isString = is('string') // guard for 'string'
const isStringOrNumber = isString.or('number') // guard for 'string | number'
`

You can even pass guards into or:

`ts
const isStrOrNum = is('string').or('number') // guard for 'string | number'
const isNullOrUndef = is('null').or('undefined') // guard for 'null | undefined'
// guard for 'string | number | null | undefined'
const isStrOrNumOrNullOrUndef = isStrOrNum.or(isNullOrUndef)
`

$3

Use the requireThat function to throw an error if a value does not match a guard:

`ts
import { is, requireThat } from 'ts-guardian'

const value = getSomeUnknownValue()
// Throws an error if type of value is not 'string'
// Error message: Type of '' does not match type guard.
requireThat(value, is('string'))
// Otherwise, type of value is 'string'
value.toUpperCase()
`

You can optionally pass an error message to requireThat:

`ts
import { isUser } from '../myTypeGuards/isUser'

requireThat(value, isUser, 'Value is not a user!')
`

Type-safe type guards

Consider the following problem:

You fetch data from an API. How do you ensure it's a valid User before using it?

The User type:

`ts
type User = {
id: number
name: string
email?: string
phone?: {
primary?: string
secondary?: string
}
teamIds: string[]
}
`

$3

With TypeScript's [user-defined type guards][user-defined-type-guards], you could write an isUser function to confirm the value is of type User. It might look something like this:

`ts
const isUser = (input: any): input is User => {
const u = input as User
return (
typeof u === 'object' &&
u !== null &&
typeof u.id === 'number' &&
typeof u.name === 'string' &&
(typeof u.email === 'string' || u.email === undefined) &&
((typeof u.phone === 'object' &&
u.phone !== null &&
(typeof u.phone.primary === 'string' || u.phone.primary === undefined) &&
(typeof u.phone.secondary === 'string' || u.phone.secondary === undefined)) ||
u.phone === undefined) &&
Array.isArray(u.teamIds) &&
u.teamIds.every(teamId => typeof teamId === 'string')
)
}
`

Hard to read, but it works. However, you could also write:

`ts
const isUser = (input: any): input is User => {
return typeof input === 'object'
}
`

Clearly this function is not enough to confirm that input is of type User, but TypeScript doesn't complain because _type predicates are effectively type assertions._

Using type predicates means you potentially lose type safety and introduce runtime errors into your app.

$3

Rather than making assumptions about the value, you define a primitive-based type of what a User object looks like, and rely on TypeScript to determine compatibility with the User type:

> A _primitive-based type_ is a type constructed from only primitive TypeScript types (string, number, undefined, any, etc...).

`ts
import { is, isOptional } from 'ts-guardian'

// We make no assumptions that the data is a user-defined type
const isUser = is({
id: 'number',
name: 'string',
email: 'string?',
phone: isOptional({
primary: 'string?',
secondary: 'string?',
}),
teamIds: 'string[]',
})
`

This is much more readable, and more importantly, it's 100% type-safe.

In this case, the type predicate looks like:

`ts
// Type predicate for our primitive-based type
input is {
id: number
name: string
email: string | undefined
phone: {
primary: string | undefined
secondary: string | undefined
} | undefined
teamIds: string[]
}
`

Now TypeScript will tell you if this type is compatible with User:

`ts
// TypeScript complains if the primitive-based type is not compatible with 'User'
const parseUser = parserFor(isUser)
`

If the type from isUser is not compatible with the User`, a TypeScript compiler error will let you know. 🎉

[license-badge]: https://img.shields.io/badge/license-MIT-informational.svg
[license]: license.md
[npm]: https://npmjs.org/package/ts-guardian
[npm-badge]: https://badge.fury.io/js/ts-guardian.svg
[user-defined-type-guards]: https://www.typescriptlang.org/docs/handbook/advanced-types.html#user-defined-type-guards
[typescript]: https://www.typescriptlang.org/docs
[functional-programming]: https://en.wikipedia.org/wiki/Functional_programming