A collection of basic type guards.

Usage no npm install needed!

<script type="module">
  import tsGuards from 'https://cdn.skypack.dev/ts-guards';


Type Guards

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


  • Install the npm package ts-guards
    npm i ts-guards
  • Use the package
    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
    // 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 }


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.