Parameters and Props Validator for Open Source Developers

This tool designed for validating user options against declarative configuration. To show how it is designed I introduce two characters. A developer of a library and a consumer of the library. The first uses merge-options internally and delegate it user options validation. The developer describes the options accepting by the library in declarative way. Each option either required or has default value, have a validator function and description of the validator. The developer can be sure that the library will get valid options passed through merge-options. Also, the developer can be sure the consumer will get verbose exceptions or warnings if they will pass invalid options or will forget to pass required options.

Reasoning

It saves the developer time on validation props and saves the consumer time on debugging.

How it Works

The function iterates over option configuration and looks for user option with same key. If the user option pass validation the function writes user value to a resulting object key. If the option isn't required, so the function writes default value to the resulting object key. If the user option fails validation or the user didn't pass required option the function throws an exception with a verbose message. If all options validation the function returns the resulting object.

Merge-options uses itself internally to validate its options :)

Installation

Using npm

npm i @dubaua/merge-options

or yarn

yarn add @dubaua/merge-options

or if you want to use package as UMD

<script src="https://unpkg.com/@dubaua/[email protected]/dist/merge-options.min.umd.js"></script>

Parameters and Return

The function accepts the only parameter — a configuration object described below. It returns an object with all keys in options. User value passing validation overrides corresponding initial value in defaults.

| option | type | default | description | | ------------ | ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | optionConfig | Object.<string, Option> | | required. declarative option configuration | | userOptions | Object | {} | user options needs validation before merge | | preffix | string | '' | string before an error or warning message | | suffix | string | '' | string after an error or warning message | | strict | boolean | true | in strict mode if user value fails validation the function throws an exception. In not strict mode the function shows a warning message and fallback to default value |

Option

Each option configuration have necessary information to validation and composing message

| name | type | description | | ----------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | required | boolean|function | a flag or function accepts userOptions | | default | any | default value for fallback if user option fail validation | | validator | function | function for validating user option. Accepts userValue as first argument and userOptions as second. Should return boolean value. | | description | string | human readable validator description. Uses to compose an error message and warning |

Usage

Import to Your Code

If you're using merge-options as UMD you don't have to import. It accessible as global function mergeOptions.

import mergeOptions from '@dubaua/merge-options';

Describe Default Options

Create an object with option configuration. Each option should have initial value, description and validator function.

const LIBRARY_OPTION_CONFIG = {
  pagerThreshold: {
    default: 0.5,
    validator: (x) => typeof x === 'number' && 0 <= x && x <= 1,
    description: 'a number between 0 and 1',
  },
};

class Library {
  constructor(userOptions) {
    this.options = mergeOptions({
      optionConfig: LIBRARY_OPTION_CONFIG,
      userOptions,
      preffix: '[Library]:',
      suffix: 'Check out documentation https://github.com/dubaua/merge-options',
      strict: false,
    });
  }
}

Now, everyone can pass options to your library.

// passing valid options to library
const libraryInstance = new Library({ pagerThreshold: 1 });
// options passing validation overrides defaults
libraryInstance.options.pagerThreshold; // 1

If invalid option passed user will see a warning in not strict mode and exceptions in strict.

// pass invalid options to your code
const anotherInstance = new Library({ pagerThreshold: 1.5 });
// [Library]: Expected pagerThreshold to be a number between 0 and 1,
// got number 1.5. Fallback to default value 0.5.
// Check out documentation https://github.com/dubaua/merge-options
anotherInstance.options.pagerThreshold; // 0.5

Validation Based on Another Option

In example below startPosition option validator relies on inputRange value.

const OPTION_CONFIG = {
  inputRange: {
    required: true,
    validator: (x) => Array.isArray(x) && x.length === 2 && x.every((y) => typeof y === 'number'),
    description: 'an array of two numbers',
  },
  startPosition: {
    required: (userOptions) => Object.prototype.hasOwnProperty.call(userOptions, 'inputRange'),
    default: 0,
    validator: (value, userOptions) =>
      Object.prototype.hasOwnProperty.call(userOptions, 'inputRange')
        ? userOptions.inputRange[0] <= value && value <= userOptions.inputRange[1]
        : true,
    description: 'an number within inputRange',
  },
};