outvariant

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.

README

outvariant

Why?

• Type-safe implementation of invariant. Asserts the given predicate expression so it's treated as non-nullable after the invariant call:

// Regular "invariant":
invariant(user, 'Failed to fetch')
user?.firstName // "user" is possibly undefined

// The glorious "outvariant":
invariant(user, 'Failed to fetch')
user.firstName // OK, "user" exists at this point

• Positionals support.

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

Getting started

npm install outvariant
# or
yarn add outvariant

import { invariant } from 'outvariant'

invariant(user, 'Failed to load: expected user, but got %o', user)