Type Guards

A collection of generic type guards to check runtime variables in TypeScript.

How-to?

- Install the npm package ts-guards
``bash
npm i ts-guards
`
- Use the package
`javascript
import { asserts, primitiveType } from 'ts-guards';

let x = "a string";

// Type of x inferred inside the if statement as: let x: string
if(primitiveType.isString(x)) { console.log(x); }

// Type of x inferred after the call as:
// Throws an error if type doesn't match
asserts.isString(x);

// Properties of object inferred (if object does not have an x and a y property, it throws an error)
asserts.areObjectPropertiesOf({ x: "y", y: "x" }, ["x", "y"]);

// Type of x inferred inside the if statement as: let x: string
if(isLiteral(x, "x" as const)) { x }

// Type of x inferred inside the if statement as: let x: "x" | 1 | "y" | "z"
if(isLiteralType(x, new Set([ "x", 1, "y", "z" ] as const))) { x }
`

Why?

TypeScript helps only with compile time validation, you need to check anything coming from IO at runtime. TypeScript runtime validation relies upon type guards.

Type guards take a parameter x as unknown, denoting variables whose type we do not know.

There are two styles of validation: one relying on x is T; another relying on asserts x is T.

The former can be used in conditional cases (returns a boolean), the latter for input validation (throws an error).

One might consider that functions given a wrong parameter can’t answer the question they’re supposed to, hence they should throw an error, hence the asserts x is T style (error throwing).

All of asserts x is T style functions rely upon and have a x is T counterpart. Both validation styles trigger TypeScript type inference.

In some cases, type guards may take a parameter x: T` to catter for output type inference.