1 | # tiny-invariant 🔬💥
|
2 |
|
3 | [![Build Status](https://travis-ci.org/alexreardon/tiny-invariant.svg?branch=master)](https://travis-ci.org/alexreardon/tiny-invariant)
|
4 | [![npm](https://img.shields.io/npm/v/tiny-invariant.svg)](https://www.npmjs.com/package/tiny-invariant) [![dependencies](https://david-dm.org/alexreardon/tiny-invariant.svg)](https://david-dm.org/alexreardon/tiny-invariant)
|
5 | ![types](https://img.shields.io/badge/types-typescript%20%7C%20flow-blueviolet)
|
6 | [![minzip](https://img.shields.io/bundlephobia/minzip/tiny-invariant.svg)](https://www.npmjs.com/package/tiny-invariant)
|
7 | [![Downloads per month](https://img.shields.io/npm/dm/tiny-invariant.svg)](https://www.npmjs.com/package/tiny-invariant)
|
8 |
|
9 | A tiny [`invariant`](https://www.npmjs.com/package/invariant) alternative.
|
10 |
|
11 | ## What is `invariant`?
|
12 |
|
13 | An `invariant` function takes a value, and if the value is [falsy](https://github.com/getify/You-Dont-Know-JS/blob/bdbe570600d4e1107d0b131787903ca1c9ec8140/up%20%26%20going/ch2.md#truthy--falsy) then the `invariant` function will throw. If the value is [truthy](https://github.com/getify/You-Dont-Know-JS/blob/bdbe570600d4e1107d0b131787903ca1c9ec8140/up%20%26%20going/ch2.md#truthy--falsy), then the function will not throw.
|
14 |
|
15 | ```js
|
16 | import invariant from 'tiny-invariant';
|
17 |
|
18 | invariant(truthyValue, 'This should not throw!');
|
19 |
|
20 | invariant(falsyValue, 'This will throw!');
|
21 | // Error('Invariant violation: This will throw!');
|
22 | ```
|
23 |
|
24 | You can also provide a function to generate your message, for when your message is expensive to create
|
25 |
|
26 | ```js
|
27 | import invariant from 'tiny-invariant';
|
28 |
|
29 | invariant(value, () => getExpensiveMessage());
|
30 | ```
|
31 |
|
32 | ## Why `tiny-invariant`?
|
33 |
|
34 | The [`library: invariant`](https://www.npmjs.com/package/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/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?')`
|
35 |
|
36 | ## Type narrowing
|
37 |
|
38 | `tiny-invariant` is useful for correctly narrowing types for `flow` and `typescript`
|
39 |
|
40 | ```ts
|
41 | const value: Person | null = { name: 'Alex' }; // type of value == 'Person | null'
|
42 | invariant(value, 'Expected value to be a person');
|
43 | // type of value has been narrowed to 'Person'
|
44 | ```
|
45 |
|
46 | ## API: `(condition: any, message?: string | (() => string)) => void`
|
47 |
|
48 | - `condition` is required and can be anything
|
49 | - `message` optional `string` or a function that returns a `string` (`() => string`)
|
50 |
|
51 | ## Installation
|
52 |
|
53 | ```bash
|
54 | # yarn
|
55 | yarn add tiny-invariant
|
56 |
|
57 | # npm
|
58 | npm add tiny-invariant --save
|
59 | ```
|
60 |
|
61 | ## Dropping your `message` for kb savings!
|
62 |
|
63 | Big idea: you will want your compiler to convert this code:
|
64 |
|
65 | ```js
|
66 | invariant(condition, 'My cool message that takes up a lot of kbs');
|
67 | ```
|
68 |
|
69 | Into this:
|
70 |
|
71 | ```js
|
72 | if (!condition) {
|
73 | if ('production' !== process.env.NODE_ENV) {
|
74 | invariant(false, 'My cool message that takes up a lot of kbs');
|
75 | } else {
|
76 | invariant(false);
|
77 | }
|
78 | }
|
79 | ```
|
80 |
|
81 | - **Babel**: recommend [`babel-plugin-dev-expression`](https://www.npmjs.com/package/babel-plugin-dev-expression)
|
82 | - **TypeScript**: recommend [`tsdx`](https://github.com/jaredpalmer/tsdx#invariant) (or you can run `babel-plugin-dev-expression` after TypeScript compiling)
|
83 |
|
84 | Your bundler can then drop the code in the `"production" !== process.env.NODE_ENV` block for your production builds to end up with this:
|
85 |
|
86 | ```js
|
87 | if (!condition) {
|
88 | invariant(false);
|
89 | }
|
90 | ```
|
91 |
|
92 | - rollup: use [rollup-plugin-replace](https://github.com/rollup/rollup-plugin-replace) and set `NODE_ENV` to `production` and then `rollup` will treeshake out the unused code
|
93 | - Webpack: [instructions](https://webpack.js.org/guides/production/#specify-the-mode)
|
94 |
|
95 | ## Builds
|
96 |
|
97 | - We have a `es` (EcmaScript module) build
|
98 | - We have a `cjs` (CommonJS) build
|
99 | - We have a `umd` (Universal module definition) build in case you needed it
|
100 |
|
101 | We expect `process.env.NODE_ENV` to be available at module compilation. We cache this value
|
102 |
|
103 | ## That's it!
|
104 |
|
105 | 🤘
|