172 lines
5.9 KiB
Markdown
172 lines
5.9 KiB
Markdown
|
# Preconditions for Node.js
|
||
|
|
[](https://travis-ci.org/MathieuTurcotte/node-precond)
|
||
|
|
[](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/).
|