You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
72 lines
2.6 KiB
72 lines
2.6 KiB
# assert-options
|
|
|
|
Smart `options` handling, with one line of code:
|
|
|
|
* throw detailed error on invalid options
|
|
* set default values for missing options
|
|
|
|
Strongly-typed, built with TypeScript 4.x `strict` mode, for JavaScript clients.
|
|
|
|
[](https://travis-ci.org/vitaly-t/assert-options)
|
|
[](https://coveralls.io/r/vitaly-t/assert-options?branch=master)
|
|
|
|
## Rationale
|
|
|
|
* Passing in invalid or misspelled option names is one of the most common errors in JavaScript.
|
|
* Assigning defaults is the most common operation for methods that take options.
|
|
|
|
This module automates proper options handling - parsing and setting defaults where needed.
|
|
|
|
Although this library is implemented in TypeScript, its objective is mainly to help JavaScript clients,
|
|
because TypeScript itself can handle invalid options and defaults natively.
|
|
|
|
## Installation
|
|
|
|
```
|
|
$ npm i assert-options
|
|
```
|
|
|
|
## Usage
|
|
|
|
```js
|
|
const { assertOptions } = require('assert-options');
|
|
|
|
function functionWithOptions(options) {
|
|
options = assertOptions(options, {first: 123, second: null});
|
|
|
|
// options is a safe object here, with all missing defaults set.
|
|
}
|
|
```
|
|
|
|
When default values are not needed, you can just use an array of strings:
|
|
|
|
```js
|
|
function functionWithOptions(options) {
|
|
options = assertOptions(options, ['first', 'second']);
|
|
|
|
// the result is exactly the same as using the following:
|
|
// options = assertOptions(options, {first: undefined, second: undefined});
|
|
|
|
// options is a safe object here, without defaults.
|
|
}
|
|
```
|
|
|
|
## API
|
|
|
|
### `assertOptions(options, defaults) => {}`
|
|
|
|
* When `options` is `null`/`undefined`, new `{}` is returned, applying `defaults` as specified.
|
|
|
|
* When `options` contains an unknown property, [Error] `Option "name" is not recognized.` is thrown.
|
|
|
|
* When a property in `options` is missing or `undefined`, its value is set from the `defaults`,
|
|
provided it is available and its value is not `undefined`.
|
|
|
|
* When `options` is not `null`/`undefined`, it must be of type `object`, or else [TypeError] is thrown:
|
|
`Invalid "options" parameter: value`.
|
|
|
|
* Parameter `defaults` is required, as a non-`null` object or an array of strings, or else [TypeError]
|
|
is thrown: `Invalid "defaults" parameter: value`.
|
|
|
|
[Error]:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
|
|
[TypeError]:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError
|
|
|