assert-options
Smart options
-object 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.
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 + setting defaults in one line.
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
const { assertOptions } = require('assert-options');
function functionWithOptions(options) {
options = assertOptions(options, {first: 123, second: null});
}
When default values are not needed, you can just use an array of strings:
function functionWithOptions(options) {
options = assertOptions(options, ['first', 'second']);
}
You can override how errors are thrown, by creating the assert
function yourself,
and specifying a custom handler:
const {createAssert} = require('assert-options');
class MyErrorHanler {
handle(err, ctx) {
}
}
const assert = createAssert(new MyErrorHanler());
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
.
createAssert(handler)
Creates a new assert function, using a custom error handler that implements IOptionsErrorHandler
protocol.
For example, the default assertOptions
is created internally like this:
const {createOptions, DefaultErrorHandler} = require('assert-options');
const assertOptions = createAssert(new DefaultErrorHandler());