https://github.com/flaque/stop-if
An assert statement that turns off in production
https://github.com/flaque/stop-if
assertion-library javascript npm-package
Last synced: 2 months ago
JSON representation
An assert statement that turns off in production
- Host: GitHub
- URL: https://github.com/flaque/stop-if
- Owner: Flaque
- Created: 2017-07-15T03:57:29.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2017-10-01T19:22:49.000Z (over 7 years ago)
- Last Synced: 2025-01-20T10:13:53.582Z (4 months ago)
- Topics: assertion-library, javascript, npm-package
- Language: JavaScript
- Homepage:
- Size: 4.88 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Hey You! Don't use this library
It already exists in the form of [invariant](https://github.com/zertosh/invariant). Didn't realize that at the time.
----
# stop-if
`stop-if` is a tiny function that fills the need of an assert statement in javascript. However, if the function is run in a production environment:
``` js
process.env.NODE_ENV === "production"
```
then `stop-if` will do nothing.
The goal of `stop-if` is to catch bugs early without ever risking uncaught production errors.
## Install
With npm
``` bash
$ npm install --save stop-if
```
With yarn
``` bash
$ yarn add stop-if
```
## Example
``` js
import stopIf from 'stop-if';
function addToList(item) {
stopIf(list === undefined)
list.add(item)
}
```
You can also add a message if you would like:
``` js
stopIf(foo, "Fee fi fo fum, I smell the code of a hum-ity-dum.");
```
## Why is this not called `assert`?
Javascript testing frameworks frequently use terms like `assert` or `expect` to prove a statement. `stopIf` is named differently to avoid any confusion with these sorts of statements.
## When should I use `stop-if`?
Stop-if, as with all assert statements, should be used as a way of expressing original intent of a function. It should be used to prove pre or post conditions or to standardize a way a function should be used.
## When should I not use `stop-if`?
You should not use `stop-if` as a regular `throw` statement. A regular throw statement should only be used in `except`tional circumstances that are theoretically possible in the function, but not desired. For example, opening a file and then noticing that it doesn't exist would be an exception that you should use a regular `throw` statement.
It follows that you should not ever attempt to `catch` a `stopIf` function. The function will not run in production and therefore your catch is entirely useless.
Never do this:
``` js
try { // no
stopIf(true); // no
} catch (Error e) { // no
console.error(e); // no
} // no wtf no
```