README

# type

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

## Use case

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 or @hapi/joi)

### Example usage

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" });
if (!isObject(options)) options = {};
const min = ensureNaturalNumber(options.min, { default: 0 })
, max = ensureNaturalNumber(options.max, { isOptional: true })
, startTime = ensureDate(options.startTime, { isOptional: true });
// ...logic
};

### Installation

npm install type

## Utilities

Aside of general `ensure` validation util, following kind of utilities for recognized JavaScript types are provided:

##### `*/coerce`

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

##### `*/is`

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

##### `*/ensure`

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
- `name` - Meaningful name for validated value, to be used in error message, assuming it contains `n` placeholder

### Index

#### General utils:

- `ensure`

#### Type specific utils:

- Value
  - `value/is`
  - `value/ensure`
- Object
  - `object/is`
  - `object/ensure`
  - Plain Object
    - `plain-object/is`
    - `plain-object/ensure`
- String
  - `string/coerce`
  - `string/ensure`
- Number
  - `number/coerce`
  - `number/ensure`
  - Finite Number
    - `finite/coerce`
    - `finite/ensure`
  - Integer Number
    - `integer/coerce`
    - `integer/ensure`
  - Safe Integer Number
    - `safe-integer/coerce`
    - `safe-integer/ensure`
  - Natural Number
    - `natural-number/coerce`
    - `natural-number/ensure`
  - Array Length
    - `array-length/coerce`
    - `array-length/ensure`
  - Time Value
    - `time-value/coerce`
    - `time-value/ensure`
- Array Like
  - `array-like/is`
  - `array-like/ensure`
  - Array
    - `array/is`
    - `array/ensure`
- Iterable
  - `iterable/is`
  - `iterable/ensure`
- Date
  - `date/is`
  - `date/ensure`
- Function
  - `function/is`
  - `function/ensure`
  - Plain Function
    - `plain-function/is`
    - `plain-function/ensure`
- Reg Exp
  - `reg-exp/is`
  - `reg-exp/ensure`
- Thenable
  - `thenable/is`
  - `thenable/ensure`
  - Promise
    - `promise/is`
    - `promise/ensure`
- Error
  - `error/is`
  - `error/ensure`
- Prototype
  - `prototype/is`

### Tests

    $ npm test