outvariant

Type-safe implementation of invariant with positionals.

Motivation

Type-safely

This implementation asserts the given predicate expression so it's treated as non-nullable after the invariant call:

1// Regular invariant:
2invariant(user, 'Failed to fetch')
3user?.firstName // "user" is possibly undefined
4
5// Outvariant:
6invariant(user, 'Failed to fetch')
7user.firstName // OK, "invariant" ensured the "user" exists

Positionals support

This implementation uses rest parameters to support dynamic number of positionals:

1invariant(predicate, 'Expected %s but got %s', 'one', false)

What is this for?

Invariant is a shorthand function that asserts a given predicate and throws an error if that predicate is false.

Compare these two pieces of code identical in behavior:

1if (!token) {
2  throw new Error(`Expected a token to be set but got ${typeof token}`)
3}

1import { invariant } from 'outvariant'
2
3invariant(token, 'Expected a token to be set but got %s', typeof token)

Using invariant reduces the visual nesting of the code and leads to cleaner error messages thanks to formatted positionals (i.e. the %s (string) positional above).

Usage

Install

1npm install outvariant

You may want to install this library as a dev dependency (-D) based on your usage.

Write an assertion

1import { invariant } from 'outvariant'
2
3invariant(user, 'Failed to load: expected user, but got %o', user)

Positionals

The following positional tokens are supported:

Token	Expected value type
%s	String
%d/%i	Number
%j	JSON (non-stringified)
%o	Arbitrary object or object-like (i.e. a class instance)

Whenever present in the error message, a positional token will look up the value to insert in its place from the arguments given to invariant.

1invariant(
2  false,
3  'Expected the "%s" property but got %j',
4  // Note that positionals are sensitive to order:
5  // - "firstName" replaces "%s" because it's first.
6  // - {"id":1} replaces "%j" because it's second.
7  'firstName',
8  {
9    id: 1,
10  },
11)

Polymorphic errors

It is possible to throw a custom Error instance using invariant.as:

1import { invariant } from 'outvariant'
2
3class NetworkError extends Error {
4  constructor(message) {
5    super(message)
6  }
7}
8
9invariant.as(NetworkError, res.fulfilled, 'Failed to handle response')

Note that providing a custom error constructor as the argument to invariant.as requires the custom constructor's signature to be compatible with the Error class constructor.

If your error constructor has a different signature, you can pass a function as the first argument to invariant.as that creates a new custom error instance.

1import { invariant } from 'outvariant'
2
3class NetworkError extends Error {
4  constructor(statusCode, message) {
5    super(message)
6    this.statusCode = statusCode
7  }
8}
9
10invariant.as(
11  (message) => new NetworkError(500, message),
12  res.fulfilled,
13  'Failed to handle response',
14)

Abstract the error into helper functions for flexibility:

1function toNetworkError(statusCode) {
2  return (message) => new NetworkError(statusCode, message)
3}
4
5invariant.as(toNetworkError(404), res?.user?.id, 'User Not Found')
6invariant.as(toNetworkError(500), res.fulfilled, 'Internal Server Error')

Contributing

Please open an issue or submit a pull request if you wish to contribute. Thank you.