vakt

A modern type guard utility for Node.js

Installation

Requires Node.js v6 LTS or greater.

$ npm install vakt

Usage

Basic usage

vakt throws an error when a variable is not of the expected type.

const vakt = require('vakt');

const greet = (name) => {
  vakt.check({ name }, 'string');

  return `Hello, ${name}!`;
};

greet('Alice'); // => Hello, Alice!

greet(3.14159); // => TypeError: name must be a string

vakt takes advantage of the ES6/ES2015 property value shorthand so you don't have to write the variable twice.

With Promises

You can also use vakt in Promises, since thrown errors automatically become rejections.

const vakt = require('vakt');

const delay = (ms) => {
  return new Promise((resolve, reject) => {
    vakt.check({ ms }, 'number');

    // if we reach this part, ms is guaranteed to be a number
    setTimeout(resolve, ms);
  });
};

delay(5000).then(() => {
  console.log('5 seconds have passed!');
});
// => 5 seconds have passed!

delay(false).catch((err) => {
  console.error(err);
});
// => TypeError: ms must be a number

Define custom types

vakt lets you create your own type checks by providing it with a validation function that returns true or false.

const vakt = require('vakt');

vakt.customTypes['non-negative integer'] = (value) => vakt.is.integer(value) && value >= 0;

const pick = (array, index) => {
  vakt.check({ array }, 'array');
  vakt.check({ index }, 'non-negative integer');

  return array[index];
};

pick([4, 8, 15, 16, 23, 42], 3); // => 16

pick(['rainbows', 'unicorns'], -12.5); // => TypeError: index must be a non-negative integer

Multiple checks at once

vakt also has a handy shorthand for checking multiple variables with one call.

const vakt = require('vakt');

const doMaths = (num1, num2, round) => {
  vakt.check([
    [{ num1 },  'number'],
    [{ num2 },  'number'],
    [{ round }, 'boolean'],
  ]);

  let value = 1 / (num1 * num2);

  if (round) value = Math.round(value);

  return value;
};

doMaths(1, 2, false); // => 0.5

doMaths(1, 2, 3) // => TypeError: round must be a boolean

API

vakt.check(variable, type)

vakt.check([[variable, type], [variable, type], [...]])

variable

Type: object

The variable to check. Should be in the form of { name: value }. Since you will practically always want to pass both the name and value of a variable, you can make use of the ES6/ES2015 property value shorthand to save you some typing: { name }

type

Type: string

The type to validate against, passed as a string.

vakt.types

Type: array

An array containing the types vakt can check out of the box:

[
  'array',
  'boolean',
  'date',
  'decimal',
  'function',
  'integer',
  'number',
  'object',
  'regexp',
  'string',
]

vakt.is

Type: object

An instance of the is.js micro check library which vakt uses to perform type checks.

vakt.customTypes

Type: object

An object containing the custom types that have been added to vakt. To define a new custom type you can add a validation function directly to the object. The validation function should return true or false.

vakt.customTypes['cat'] = (value) => vakt.is.object(value) && vakt.is.function(value['meow']);

Once you have defined a custom type, you can use it with vakt.check:

const dog = {
  woof () {
    console.log('woof!');
  },
};

vakt.check({ dog }, 'cat'); // => TypeError: dog must be a cat

vakt.VERSION

Type: string

The version of vakt in semver format.

License

MIT © Mick Dekkers