tiny-invariant 🔬💥

A tiny invariant alternative.

What is `invariant`?

An invariant function takes a value, and if the value is falsy then the invariant function will throw. If the value is truthy, then the function will not throw.

import invariant from 'tiny-invariant';

invariant(truthyValue, 'This should not throw!');

invariant(falsyValue, 'This will throw!');
// Error('Invariant violation: This will throw!');

Why `tiny-invariant`?

The library: invariant supports passing in arguments to the invariant function in a sprintf style (condition, format, a, b, c, d, e, f). It has internal logic to execute the sprintf substitutions. The sprintf logic is not removed in production builds. tiny-invariant has dropped all of the sprintf logic. tiny-invariant allows you to pass a single string message. With template literals there is really no need for a custom message formatter to be built into the library. If you need a multi part message you can just do this: invariant(condition, 'Hello, ${name} - how are you today?')

Type narrowing

tiny-invariant is useful for correctly narrowing types for flow and typescript

const value: Person | null = { name: 'Alex' }; // type of value == 'Person | null'
invariant(value, 'Expected value to be a person');
// type of value has been narrowed to 'Person'

API: `(condition: any, message?: string | (() => string)) => void`

condition is required and can be anything
message optional string or a function that returns a string (() => string)

Your message can be a function that returns a string (() => string) for the cases where you want to lazily create your error message, such as when they are expensive to make.

invariant(value, () => getExpensiveMessage());

Installation

# yarn
yarn add tiny-invariant

# npm
npm add tiny-invariant --save

Dropping your `message` for kb savings!

Big idea: you will want your compiler to convert this code:

invariant(condition, 'My cool message that takes up a lot of kbs');

Into this:

if (!condition) {
  if ('production' !== process.env.NODE_ENV) {
    invariant(false, 'My cool message that takes up a lot of kbs');
  } else {
    invariant(false);
  }
}

Babel: recommend babel-plugin-dev-expression
TypeScript: recommend tsdx (or you can run babel-plugin-dev-expression after TypeScript compiling)

Your bundler can then drop the code in the "production" !== process.env.NODE_ENV block for your production builds to end up with this:

if (!condition) {
  invariant(false);
}

rollup: use rollup-plugin-replace and set NODE_ENV to production and then rollup will treeshake out the unused code
Webpack: instructions

Builds

We have a es (EcmaScript module) build (because you know you want to deduplicate this super heavy library)
We have a cjs (CommonJS) build
We have a umd (Universal module definition) build in case you needed it

We expect process.env.NODE_ENV to be available at module compilation. We cache this value

That's it!

🤘

Current Tags

1.3.1-beta.1 ... beta (2 years ago)
1.3.3 ... latest (10 months ago)

21 Versions

1.3.3 ... 10 months ago
1.3.2 ... 10 months ago
1.3.1 ... 2 years ago
1.3.1-beta.1 ... 2 years ago
1.3.0 ... 2 years ago
1.3.0-beta.1 ... 2 years ago
1.2.0 ... 3 years ago
1.2.0-beta.1 ... 3 years ago
1.1.0 ... 5 years ago
1.1.0-beta.2 ... 5 years ago
1.1.0-beta.1 ... 5 years ago
1.0.6 ... 5 years ago
1.0.5 ... 5 years ago
1.0.4 ... 6 years ago
1.0.3 ... 6 years ago
1.0.2 ... 6 years ago
1.0.1 ... 6 years ago
1.0.0 ... 6 years ago
0.0.3 ... 7 years ago
0.0.2 ... 7 years ago
0.0.1 ... 7 years ago