Runtime validation and processing of JavaScript types. 

Runtime validation and processing of JavaScript types

medikoo

gozala

type

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

## [2.5.0](https://github.com/medikoo/type/compare/v2.4.0...v2.5.0) (2021-03-08)

- `errorCode` option for `ensure*` utils ([777a1f2](https://github.com/medikoo/type/commit/777a1f2c9fd76defcd24d3a30cce49491947fef7))

## [2.4.0](https://github.com/medikoo/type/compare/v2.3.0...v2.4.0) (2021-03-08)

- `set/is` and `set/ensure` utils ([083ec23](https://github.com/medikoo/type/commit/083ec2351718c310f316dcfd8c624a13201e227f))

## [2.3.0](https://github.com/medikoo/type/compare/v2.2.0...v2.3.0) (2021-02-16)

- `map/is` and `map/ensure` utils ([aafd1cb](https://github.com/medikoo/type/commit/aafd1cbd8c888fda98d39fd17e59f38b078d7bcf))

## [2.2.0](https://github.com/medikoo/type/compare/v2.1.0...v2.2.0) (2021-02-11)

- Support `ensureItem` option in `array/ensure` ([8f74973](https://github.com/medikoo/type/commit/8f749739df9bfebf44087093e09c8f7341a33a09))

## [2.1.0](https://github.com/medikoo/type/compare/v2.0.0...v2.1.0) (2020-08-21)

- `ensure` util for cumulated input validation ([814c5a8](https://github.com/medikoo/type/commit/814c5a801ecac23d06d8a5f4bcafc4763a04408c))

- Provide an alternative error message with `options.name` ([c7751c0](https://github.com/medikoo/type/commit/c7751c084ee4f3d3ed10500db0edde2ff00e03a1))

- Support `%n` (meaningful name) token in error message resolver ([b0f374e](https://github.com/medikoo/type/commit/b0f374e54345c714fe37a90887ecfe60577ce133))

- Support `min` validation for natural numbers ([e703512](https://github.com/medikoo/type/commit/e70351248818d3e113110106ad174b42c5fd9b25))

- Support custom Error constructors ([c6ecb90](https://github.com/medikoo/type/commit/c6ecb90e21c1c778210934204cbe393fb89ef2f6))

- Fix typo in error message ([2735533](https://github.com/medikoo/type/commit/2735533de28d33dfa13222743698169c92d08c09))

## [2.0.0](https://github.com/medikoo/type/compare/v1.2.0...v2.0.0) (2019-10-10)

- `allowedKeys` option for plain-object/ensure ([f81e72e](https://github.com/medikoo/type/commit/f81e72e))

- `ensurePropertyValue` option for plain-object/ensure ([c5ff8fb](https://github.com/medikoo/type/commit/c5ff8fb))

- Replace `coerceItem` with `ensureItem` option in iterable/ensure ([721494f](https://github.com/medikoo/type/commit/721494f))

- Seclude lib/resolve-error-message ([12636d9](https://github.com/medikoo/type/commit/12636d9))

- Validate options.ensureItem in iterable/ensure ([78da6c1](https://github.com/medikoo/type/commit/78da6c1))

- iterable/ensure no longer supports `coerceItem` option. Instead `ensureItem` was introduced

## [1.2.0](https://github.com/medikoo/type/compare/v1.1.0...v1.2.0) (2019-09-20)

- Improve error message so it's not confusing ([97cd6b9](https://github.com/medikoo/type/commit/97cd6b9))

- 'coerceItem' option for iterable/ensure ([0818860](https://github.com/medikoo/type/commit/0818860))

## [1.1.0](https://github.com/medikoo/type/compare/v1.0.3...v1.1.0) (2019-09-20)

- `denyEmpty` option for iterables validation ([301d071](https://github.com/medikoo/type/commit/301d071))

### [1.0.3](https://github.com/medikoo/type/compare/v1.0.2...v1.0.3) (2019-08-06)

- Recognize custom built ES5 era errors ([6462fac](https://github.com/medikoo/type/commit/6462fac))

### [1.0.2](https://github.com/medikoo/type/compare/v1.0.1...v1.0.2) (2019-08-06)

- Recognize host errors (e.g. DOMException) ([96ef399](https://github.com/medikoo/type/commit/96ef399))

## [1.0.1](https://github.com/medikoo/type/compare/v1.0.0...v1.0.1) (2019-04-08)

- ensure 'is' functions can't crash ([59ceb78](https://github.com/medikoo/type/commit/59ceb78))

- array-length/coerce ([af8ddec](https://github.com/medikoo/type/commit/af8ddec))

- array-length/ensure ([d313eb6](https://github.com/medikoo/type/commit/d313eb6))

- array-like/ensure ([45f1ddd](https://github.com/medikoo/type/commit/45f1ddd))

- array-like/is ([9a026a5](https://github.com/medikoo/type/commit/9a026a5))

- array/ensure ([9db1515](https://github.com/medikoo/type/commit/9db1515))

- array/is ([9672839](https://github.com/medikoo/type/commit/9672839))

- date/ensure ([44e25a0](https://github.com/medikoo/type/commit/44e25a0))

- date/is ([0316558](https://github.com/medikoo/type/commit/0316558))

- ensure to not crash ([3998348](https://github.com/medikoo/type/commit/3998348))

- ensure/number ([134b5cb](https://github.com/medikoo/type/commit/134b5cb))

- error/ensure ([d5c8a30](https://github.com/medikoo/type/commit/d5c8a30))

- error/is-error ([4d6b899](https://github.com/medikoo/type/commit/4d6b899))

- finite/coerce ([accaad1](https://github.com/medikoo/type/commit/accaad1))

- finite/ensure ([51e4174](https://github.com/medikoo/type/commit/51e4174))

- function/ensure ([b624c9a](https://github.com/medikoo/type/commit/b624c9a))

- function/is ([dab8026](https://github.com/medikoo/type/commit/dab8026))

- integer/coerce ([89dea2e](https://github.com/medikoo/type/commit/89dea2e))

var isValue             = require("../value/is")

  , resolveErrorMessage = require("./resolve-error-message");

module.exports = function (value, defaultMessage, inputOptions) {

		if ("default" in inputOptions) return inputOptions["default"];

		if (inputOptions.isOptional) return null;

	var ErrorConstructor = (inputOptions && inputOptions.Error) || TypeError;

	throw new ErrorConstructor(resolveErrorMessage(defaultMessage, value, inputOptions));

	var error = new ErrorConstructor(resolveErrorMessage(defaultMessage, value, inputOptions));

	if (inputOptions && inputOptions.errorCode) error.code = inputOptions.errorCode;

	"description": "Runtime validation and processing of JavaScript types",

	"author": "Mariusz Nowak <medyk@medikoo.com> (https://www.medikoo.com/)",

		"coverage": "nyc --reporter=lcov --reporter=html --reporter=text-summary npm test",

		"check-coverage": "npm run coverage && nyc check-coverage --statements 80 --function 80 --branches 80 --lines 80",

		"lint": "eslint --ignore-path=.gitignore .",

		"lint-updated": "pipe-git-updated --ext=js -- eslint --ignore-pattern '!*'",

		"prettier-check-updated": "pipe-git-updated --ext=css --ext=html --ext=js --ext=json --ext=md --ext=yaml --ext=yml -- prettier -c",

		"prettify": "prettier --write --ignore-path .gitignore '**/*.{css,html,js,json,md,yaml,yml}'",

[![*nix build status][nix-build-image]][nix-build-url]

[![Windows build status][win-build-image]][win-build-url]

## Runtime validation and processing of JavaScript types

- Respects language nature and acknowledges its quirks

- Allows coercion in restricted forms (rejects clearly invalid input, normalizes permissible type deviations)

- No transpilation implied, written to work in all ECMAScript 3+ engines

Validate arguments input in public API endpoints.

_For validation of more sophisticated input structures (as deeply nested configuration objects) it's recommended to consider more powerful schema based utlities (as [AJV](https://ajv.js.org/) or [@hapi/joi](https://hapi.dev/family/joi/))_

Bulletproof input arguments normalization and validation:

const ensureString        = require('type/string/ensure')

    , ensureDate          = require('type/date/ensure')

    , ensureNaturalNumber = require('type/natural-number/ensure')

    , isObject            = require('type/object/is');

module.exports = (path, options = { min: 0 }) {

  path = ensureString(path, { errorMessage: "%v is not a path" });

  const min = ensureNaturalNumber(options.min, { default: 0 })

      , max = ensureNaturalNumber(options.max, { isOptional: true })

      , startTime = ensureDate(options.startTime, { isOptional: true });

Aside of general [`ensure`](docs/ensure.md) validation util, following kind of utilities for recognized JavaScript types are provided:

Restricted coercion into primitive type. Returns coerced value or `null` if value is not coercible per rules.

Object type/kind confirmation, returns either `true` or `false`.

Value validation. Returns input value (in primitive cases possibly coerced) or if value doesn't meet the constraints throws `TypeError` .

Each `*/ensure` utility, accepts following options (eventually passed with second argument):

- `isOptional` - Makes `null` or `undefined` accepted as valid value. In such case instead of `TypeError` being thrown, `null` is returned.

- `default` - A value to be returned if `null` or `undefined` is passed as an input value.

- `errorMessage` - Custom error message. Following placeholders can be used:

  - `%v` - To be replaced with short string representation of invalid value

  - `%n` - To be replaced with meaninfgul name (to be passed with `name` option) of validated value. Not effective if `name` option is not present

- `errorCode` - Eventual error code to be exposed on `.code` error property

- `name` - Meaningful name for validated value, to be used in error message, assuming it contains `%n` placeholder

- `Error` - Alternative error constructor to be used (defaults to `TypeError`)

  - [`value/ensure`](docs/value.md#valueensure)

  - [`object/is`](docs/object.md#objectis)

  - [`object/ensure`](docs/object.md#objectensure)

    - [`plain-object/is`](docs/plain-object.md#plain-objectis)

    - [`plain-object/ensure`](docs/plain-object.md#plain-objectensure)

  - [`string/coerce`](docs/string.md#stringcoerce)

  - [`string/ensure`](docs/string.md#stringensure)

  - [`number/coerce`](docs/number.md#numbercoerce)

  - [`number/ensure`](docs/number.md#numberensure)

    - [`finite/coerce`](docs/finite.md#finitecoerce)

    - [`finite/ensure`](docs/finite.md#finiteensure)

    - [`integer/coerce`](docs/integer.md#integercoerce)

    - [`integer/ensure`](docs/integer.md#integerensure)

    - [`safe-integer/coerce`](docs/safe-integer.md#safe-integercoerce)

    - [`safe-integer/ensure`](docs/.md#safe-integerensure)

    - [`natural-number/coerce`](docs/natural-number.md#natural-numbercoerce)

    - [`natural-number/ensure`](docs/natural-number.md#natural-numberensure)

    - [`array-length/coerce`](docs/array-length.md#array-lengthcoerce)

    - [`array-length/ensure`](docs/array-length.md#array-lengthensure)

    - [`time-value/coerce`](docs/time-value.md#time-valuecoerce)

    - [`time-value/ensure`](docs/time-value.md#time-valueensure)

  - [`array-like/is`](docs/array-like.md#array-likeis)

  - [`array-like/ensure`](docs/array-like.md#array-likeensure)

    - [`array/is`](docs/array.md#arrayis)

    - [`array/ensure`](docs/array.md#arrayensure)

  - [`iterable/is`](docs/iterable.md#iterableis)

  - [`iterable/ensure`](docs/iterable.md#iterableensure)

  - [`set/ensure`](docs/set.md#setensure)

  - [`map/ensure`](docs/map.md#mapensure)

  - [`date/ensure`](docs/date.md#dateensure)

  - [`function/is`](docs/function.md#functionis)

  - [`function/ensure`](docs/function.md#functionensure)

    - [`plain-function/is`](docs/plain-function.md#plain-functionis)

    - [`plain-function/ensure`](docs/plain-function.md#plain-functionensure)

  - [`reg-exp/is`](docs/reg-exp.md#reg-expis)

  - [`reg-exp/ensure`](docs/.md#reg-expensure)

  - [`thenable/is`](docs/thenable.md#thenableis)

  - [`thenable/ensure`](docs/thenable.md#thenableensure)

    - [`promise/is`](docs/promise.md#promiseis)

    - [`promise/ensure`](docs/promise.md#promiseensure)

  - [`error/ensure`](docs/error.md#errorensure)

  - [`prototype/is`](docs/prototype.md#prototypeis)

[nix-build-image]: https://semaphoreci.com/api/v1/medikoo-org/type/branches/master/shields_badge.svg

[nix-build-url]: https://semaphoreci.com/medikoo-org/type

[win-build-image]: https://ci.appveyor.com/api/projects/status/8nrtluuwsb5k9l8d?svg=true

[win-build-url]: https://ci.appveyor.com/api/project/medikoo/type

[cov-image]: https://img.shields.io/codecov/c/github/medikoo/type.svg

[cov-url]: https://codecov.io/gh/medikoo/type

[npm-image]: https://img.shields.io/npm/v/type.svg

[npm-url]: https://www.npmjs.com/package/type

		{
		"name": "type",
		"version": "2.4.0",
		"version": "2.5.0",
		"description": "Runtime validation and processing of JavaScript types",
		@@ -5,0 +5,0 @@ "author": "Mariusz Nowak <medyk@medikoo.com> (https://www.medikoo.com/)",

		@@ -5,2 +5,8 @@ # Changelog

		## [2.5.0](https://github.com/medikoo/type/compare/v2.4.0...v2.5.0) (2021-03-08)

		### Features

		- `errorCode` option for `ensure*` utils ([777a1f2](https://github.com/medikoo/type/commit/777a1f2c9fd76defcd24d3a30cce49491947fef7))

		## [2.4.0](https://github.com/medikoo/type/compare/v2.3.0...v2.4.0) (2021-03-08)
		@@ -7,0 +13,0 @@

		@@ -12,3 +12,5 @@ "use strict";
		var ErrorConstructor = (inputOptions && inputOptions.Error) \|\| TypeError;
		throw new ErrorConstructor(resolveErrorMessage(defaultMessage, value, inputOptions));
		var error = new ErrorConstructor(resolveErrorMessage(defaultMessage, value, inputOptions));
		if (inputOptions && inputOptions.errorCode) error.code = inputOptions.errorCode;
		throw error;
		};

		@@ -70,2 +70,3 @@ [![*nix build status][nix-build-image]][nix-build-url]
		- `%n` - To be replaced with meaninfgul name (to be passed with `name` option) of validated value. Not effective if `name` option is not present
		- `errorCode` - Eventual error code to be exposed on `.code` error property
		- `name` - Meaningful name for validated value, to be used in error message, assuming it contains `%n` placeholder
		@@ -72,0 +73,0 @@ - `Error` - Alternative error constructor to be used (defaults to `TypeError`)

Improved metrics