# precond

> Precondition checking utilities.

Latest version **0.2.3** (published 2014-06-21) · 0 weekly downloads

## Install

```sh
npm install precond
pnpm add precond
yarn add precond
bun add precond
```

## Health

**Score 18/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.3 |
| Published | 2014-06-21 |
| First published | 2012-11-15 |
| Weekly downloads | 0 |
| TypeScript types | separate (@types/precond) |
| Module format | CommonJS |
| Node | >= 0.6 |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9 |
| Author | Mathieu Turcotte |
| Maintainers | mathieu |
| Keywords | precondition, assert, invariant, contract, condition |

## Links

- npm: https://www.npmjs.com/package/precond
- Repository: https://github.com/MathieuTurcotte/node-precond
- Issues: https://github.com/MathieuTurcotte/node-precond/issues
- npm.io page: https://npm.io/package/precond

## Recent versions

- 0.2.3 (latest) — 2014-06-21
- 0.2.2 — 2013-06-15
- 0.2.1 — 2013-05-26
- 0.2.0 — 2013-05-26
- 0.1.1 — 2012-11-16
- 0.1.0 — 2012-11-15

## README

# Preconditions for Node.js
[![Build Status](https://secure.travis-ci.org/MathieuTurcotte/node-precond.png?branch=master)](https://travis-ci.org/MathieuTurcotte/node-precond)
[![NPM version](https://badge.fury.io/js/precond.png)](http://badge.fury.io/js/precond)

Precondition checks for Node.js inspired by [Guava's precondition checking
utilities](https://code.google.com/p/guava-libraries/wiki/PreconditionsExplained).

## Installation

```
npm install precond
```

## Unit tests

```
npm test
```

## Overview

Precond provides a set of functions to verify arguments and state correctness

It lets you rewrite constructs like the following

```js
if (!this.isConnected) {
    throw new Error('Client should be connected before calling X.');
}
```

into a more compact and declarative check bellow.

```js
precond.checkState(this.isConnected, 'Client should be ...');
```

**Note that even though the throw statement is wrapped in a function, the call
stack will still start from the calling function. So the previous examples would
both produce the same stack trace.**

All arguments after the message will be used to format the actual error
message that will be thrown.

The following precondition checks are provded:

- checkArgument(value, [messageFormat, [formatArgs, ...]])
- checkState(value, [messageFormat, [formatArgs, ...]])
- checkIsDef(value, [messageFormat, [formatArgs, ...]]) -> value
- checkIsDefAndNotNull(value, [messageFormat, [formatArgs, ...]]) -> value
- checkIsString(value, [messageFormat, [formatArgs, ...]]) -> value
- checkIsArray(value, [messageFormat, [formatArgs, ...]]) -> value
- checkIsNumber(value, [messageFormat, [formatArgs, ...]]) -> value
- checkIsBoolean(value, [messageFormat, [formatArgs, ...]]) -> value
- checkIsFunction(value, [messageFormat, [formatArgs, ...]]) -> value
- checkIsObject(value, [messageFormat, [formatArgs, ...]]) -> value

## API

### Static functions

#### precond.checkArgument(value, [messageFormat, [formatArgs, ...]])

- value: the value that is required to be truthy
- messageFormat: error message format template
- formatArgs: arguments to be substituted into the message template

Ensures that value is true. Throws an `IllegalArgumentError` if value
is false.

#### precond.checkState(value, [messageFormat, [formatArgs, ...]])

- value: the value that is required to be truthy
- messageFormat: error message format template
- formatArgs: arguments to be substituted into the message template

Ensures that value is true. Throws an `IllegalStateError` if value
is false.

#### precond.checkIsDef(value, [messageFormat, [formatArgs, ...]])

- value: the value that is required to be defined
- messageFormat: error message format template
- formatArgs: arguments to be substituted into the message template

Ensures that value is defined (could be null). Throws an
`IllegalArgumentError` if value is undefined. Returns the value of
the value that was validated.

#### precond.checkIsDefAndNotNull(value, [messageFormat, [formatArgs, ...]])

- value: the value that is required to be defined and not null
- messageFormat: error message format template
- formatArgs: arguments to be substituted into the message template

Ensures that value is defined and not null. Throws an
`IllegalArgumentError` if value is undefined or null. Returns the value of
the value that was validated.

#### precond.checkIsString(value, [messageFormat, [formatArgs, ...]])

- value: the value that is required to be a string
- messageFormat: error message format template
- formatArgs: arguments to be substituted into the message template

Ensures that value is a string or a String object. Throws an
`IllegalArgumentError` if value isn't a string. Returns the value of
the value that was validated.

#### precond.checkIsArray(value, [messageFormat, [formatArgs, ...]])

- value: the value that is required to be an array
- messageFormat: error message format template
- formatArgs: arguments to be substituted into the message template

Ensures that value is an array. Throws an `IllegalArgumentError` if
value isn't an array. Returns the value of the value that was
validated.

#### precond.checkIsNumber(value, [messageFormat, [formatArgs, ...]])

- value: the value that is required to be a number
- messageFormat: error message format template
- formatArgs: arguments to be substituted into the message template

Ensures that value is a number. Throws an `IllegalArgumentError` if
value isn't a number. Returns the value of the value that was
validated.

#### precond.checkIsBoolean(value, [messageFormat, [formatArgs, ...]])

- value: the value that is required to be a boolean
- messageFormat: error message format template
- formatArgs: arguments to be substituted into the message template

Ensures that value is a boolean. Throws an `IllegalArgumentError` if
value isn't a boolean. Returns the value of the value that was
validated.

#### precond.checkIsFunction(value, [messageFormat, [formatArgs, ...]])

- value: the value that is required to be a function
- messageFormat: error message format template
- formatArgs: arguments to be substituted into the message template

Ensures that value is a function. Throws an `IllegalArgumentError` if
value isn't a function. Returns the value of the value that was
validated.

#### precond.checkIsObject(value, [messageFormat, [formatArgs, ...]])

- value: the value that is required to be an object
- messageFormat: error message format template
- formatArgs: arguments to be substituted into the message template

Ensures that value is an object. Throws an `IllegalArgumentError` if
value isn't an object. Returns the value of the value that was
validated.

### Class precond.IllegalArgumentError

Extends `Error` and is thrown to signal illegal arguments.

### Class precond.IllegalStateError

Extends `Error` and is thrown to signal that the program or object has reached
an illegal state.

## License

This code is free to use under the terms of the [MIT license](http://mturcotte.mit-license.org/).

---
_Source: https://npm.io/package/precond · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._