What is outvariant?
The outvariant package is a utility library for creating invariant conditions in JavaScript and TypeScript applications. It allows developers to enforce certain conditions or assumptions in their code, throwing errors when those conditions are not met. This can be particularly useful for validating arguments, ensuring application states, or enforcing coding contracts during development.
What are outvariant's main functionalities?
Invariant enforcement
This feature allows developers to enforce conditions within their code. If the condition fails, an error is thrown with a custom message. In the example, an error is thrown if an attempt is made to divide by zero.
import { invariant } from 'outvariant';
function divide(a, b) {
invariant(b !== 0, 'Attempted to divide by zero.');
return a / b;
}
Warn
This feature enables developers to issue warnings instead of errors. It's useful for deprecation notices or highlighting undesirable but non-fatal behavior. In the example, a warning is issued for using a deprecated function.
import { warn } from 'outvariant';
function deprecatedFunction() {
warn('deprecatedFunction is deprecated and will be removed in the next major release.');
}
Other packages similar to outvariant
invariant
The invariant package offers similar functionality to outvariant by providing a way to enforce invariants within code. However, it focuses more narrowly on invariants without the additional utilities for warnings that outvariant provides.
tiny-warning
Similar to the 'warn' feature in outvariant, tiny-warning is a small utility for issuing warnings in development environments. It's similar to outvariant's warning capabilities but does not include invariant enforcement.
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:
invariant(user, 'Failed to fetch')
user?.firstName
invariant(user, 'Failed to fetch')
user.firstName
Positionals support
This implementation uses rest parameters to support dynamic number of positionals:
invariant(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:
if (!token) {
throw new Error(`Expected a token to be set but got ${typeof token}`)
}
import { invariant } from 'outvariant'
invariant(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
npm install outvariant
yarn add outvariant
You may want to install this library as a dev dependency (-D
) based on your usage.
Write an assertion
import { invariant } from 'outvariant'
invariant(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
.
invariant(
false,
'Expected the "%s" property but got %j',
'firstName',
{
id: 1,
}
)
Contributing
Please open an issue or submit a pull request if you wish to contribute. Thank you.