assert-options

What is assert-options?

The assert-options npm package is a utility for validating and asserting options in JavaScript objects. It helps ensure that the options passed to a function or module are valid and meet the expected criteria.

What are assert-options's main functionalities?

Basic Option Validation

This feature allows you to validate and merge user-provided options with default options. If the user does not provide an option, the default value is used.

const assertOptions = require('assert-options');

function myFunction(options) {
  const defaultOptions = { a: 1, b: 2 };
  options = assertOptions(options, defaultOptions);
  console.log(options);
}

myFunction({ a: 10 }); // { a: 10, b: 2 }
myFunction(); // { a: 1, b: 2 }

Strict Option Validation

This feature enforces strict validation, ensuring that only the specified options are allowed. If an unknown option is provided, an error is thrown.

const assertOptions = require('assert-options');

function myFunction(options) {
  const defaultOptions = { a: 1, b: 2 };
  options = assertOptions(options, defaultOptions, { strict: true });
  console.log(options);
}

myFunction({ a: 10, c: 3 }); // Throws an error because 'c' is not a valid option

Nested Option Validation

This feature supports validation of nested options, allowing you to merge and validate deeply nested objects.

const assertOptions = require('assert-options');

function myFunction(options) {
  const defaultOptions = { a: 1, b: { c: 2, d: 3 } };
  options = assertOptions(options, defaultOptions);
  console.log(options);
}

myFunction({ b: { c: 10 } }); // { a: 1, b: { c: 10, d: 3 } }
myFunction(); // { a: 1, b: { c: 2, d: 3 } }

Other packages similar to assert-options

joi

Joi is a powerful schema description language and data validator for JavaScript. It allows you to create blueprints or schemas for JavaScript objects to ensure validation. Compared to assert-options, Joi offers more advanced and flexible validation capabilities, including support for complex data types and custom validation rules.

yup

Yup is a JavaScript schema builder for value parsing and validation. It is similar to Joi but is often preferred for its simplicity and ease of use. Like assert-options, Yup can validate and transform objects, but it provides more comprehensive validation features and better integration with form libraries.

prop-types

Prop-types is a runtime type checking library for React props. While it is primarily used for validating React component props, it can also be used for general object validation. Compared to assert-options, prop-types is more focused on type checking rather than option validation and merging.

README

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 for TypeScript 3.x strict mode.

Rationale

• Passing in invalid or misspelled option names is one of the most common errors.
• Assigning defaults is the most common operation for methods that take options.

This module automates proper options parsing and setting defaults where needed.

Installation

$ npm install assert-options

Usage

import {assertOptions} from 'assert-options';

function functionWithOptions(options) {
    options = assertOptions(options, {first: 123, second: null});
    
    // options is a safe object here, with all missing defaults set.
}

And when default values are not needed, you can use an array of strings:

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