assert-options/README.md

# 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.

[![Build Status](https://travis-ci.org/vitaly-t/assert-options.svg?branch=master)](https://travis-ci.org/vitaly-t/assert-options)
[![Coverage Status](https://coveralls.io/repos/vitaly-t/assert-options/badge.svg?branch=master)](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