Skip to content
Runtime validation and processing of JavaScript types
JavaScript
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
array-length
array-like feat: array-like/ensure Apr 4, 2019
array fix: ensure 'is' functions can't crash Apr 4, 2019
date
error fix: Recognize custom built ES5 era errors Aug 6, 2019
finite feat: finite/ensure Apr 3, 2019
function feat: function/ensure Apr 4, 2019
integer feat: integer/ensure Apr 3, 2019
iterable refactor: Unify internal logic Oct 10, 2019
lib
natural-number
number feat: ensure/number Apr 3, 2019
object refactor: improve object.is Apr 2, 2019
plain-function feat: plain-function/ensure Apr 4, 2019
plain-object
promise
prototype feat: ensure to not crash Apr 4, 2019
reg-exp fix: ensure 'is' functions can't crash Apr 4, 2019
safe-integer feat: safe-integer/ensure Apr 4, 2019
string feat(string/coerce): restrict toString acceptance Apr 2, 2019
test feat: `ensurePropertyValue` option for plain-object/ensure Oct 10, 2019
thenable feat: thenable/ensure Apr 4, 2019
time-value feat: time-value/ensure Apr 4, 2019
value
.editorconfig
.gitignore test: configure coverage scripts Mar 25, 2019
CHANGELOG.md chore(release): 2.0.0 Oct 10, 2019
LICENSE chore: Ensure license file Jun 17, 2019
README.md feat: `ensurePropertyValue` option for plain-object/ensure Oct 10, 2019
package.json

README.md

*nix build status Windows build status Tests coverage npm version

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

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

Serves following kind of utilities:

*/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 (%v can be used as a placeholder for input value)

Value

Value, any value that's neither null nor undefined .

value/is

Confirms whether passed argument is a value

const isValue = require("type/value/is");

isValue({}); // true
isValue(null); // false

value/ensure

Ensures if given argument is a value. If it's a value it is returned back, if not TypeError is thrown

const ensureValue = require("type/value/ensure");

const obj = {};

ensureValue(obj); // obj
ensureValue(null); // Thrown TypeError: Cannot use null

Object

Object, any non-primitive value

object/is

Confirms if passed value is an object

const isObject = require("type/object/is");

isObject({}); // true
isObject(true); // false
isObject(null); // false

object/ensure

If given argument is an object, it is returned back. Otherwise TypeError is thrown.

const ensureObject = require("type/object/ensure");

const obj = {};

ensureObject(obj); // obj
ensureString(null); // Thrown TypeError: null is not an object

String

string primitive

string/coerce

Restricted string coercion. Returns string presentation for every value that follows below constraints

  • is implicitly coercible to string
  • is neithernull nor undefined
  • its toString method is not Object.prototype.toString

For all other values null is returned

const coerceToString = require("type/string/coerce");

coerceToString(12); // "12"
coerceToString(undefined); // null

string/ensure

If given argument is a string coercible value (via string/coerce) returns result string. Otherwise TypeError is thrown.

const ensureString = require("type/string/ensure");

ensureString(12); // "12"
ensureString(null); // Thrown TypeError: null is not a string

Number

number primitive

number/coerce

Restricted number coercion. Returns number presentation for every value that follows below constraints

  • is implicitly coercible to number
  • is neither null nor undefined
  • is not NaN and doesn't coerce to NaN

For all other values null is returned

const coerceToNumber = require("type/number/coerce");

coerceToNumber("12"); // 12
coerceToNumber({}); // null
coerceToNumber(null); // null

number/ensure

If given argument is a number coercible value (via number/coerce) returns result number. Otherwise TypeError is thrown.

const ensureNumber = require("type/number/ensure");

ensureNumber(12); // "12"
ensureNumber(null); // Thrown TypeError: null is not a number

Finite Number

Finite number primitive

finite/coerce

Follows number/coerce additionally rejecting Infinity and -Infinity values (null is returned if given values coerces to them)

const coerceToFinite = require("type/finite/coerce");

coerceToFinite("12"); // 12
coerceToFinite(Infinity); // null
coerceToFinite(null); // null
finite/ensure

If given argument is a finite number coercible value (via finite/coerce) returns result number. Otherwise TypeError is thrown.

const ensureFinite = require("type/finite/ensure");

ensureFinite(12); // "12"
ensureFinite(null); // Thrown TypeError: null is not a finite number

Integer Number

Integer number primitive

integer/coerce

Follows finite/coerce additionally stripping decimal part from the number

const coerceToInteger = require("type/integer/coerce");

coerceToInteger("12.95"); // 12
coerceToInteger(Infinity); // null
coerceToInteger(null); // null
integer/ensure

If given argument is an integer coercible value (via integer/coerce) returns result number. Otherwise TypeError is thrown.

const ensureInteger = require("type/integer/ensure");

ensureInteger(12.93); // "12"
ensureInteger(null); // Thrown TypeError: null is not an integer

Safe Integer Number

Safe integer number primitive

safe-integer/coerce

Follows integer/coerce but returns null in place of values which are beyond Number.MIN_SAFE_INTEGER and Number.MAX_SAFE_INTEGER range.

const coerceToSafeInteger = require("type/safe-integer/coerce");

coerceToInteger("12.95"); // 12
coerceToInteger(9007199254740992); // null
coerceToInteger(null); // null
safe-integer/ensure

If given argument is a safe integer coercible value (via safe-integer/coerce) returns result number. Otherwise TypeError is thrown.

const ensureSafeInteger = require("type/safe-integer/ensure");

ensureSafeInteger(12.93); // "12"
ensureSafeInteger(9007199254740992); // Thrown TypeError: null is not a safe integer

Natural Number

Natural number primitive

natural-number/coerce

Follows integer/coerce but returns null for values below 0

const coerceToNaturalNumber = require("type/natural-number/coerce");

coerceToNaturalNumber("12.95"); // 12
coerceToNaturalNumber(-120); // null
coerceToNaturalNumber(null); // null
natural-number/ensure

If given argument is a natural number coercible value (via natural-number/coerce) returns result number. Otherwise TypeError is thrown.

const ensureNaturalNumber = require("type/natural-number/ensure");

ensureNaturalNumber(12.93); // "12"
ensureNaturalNumber(-230); // Thrown TypeError: null is not a natural number

Plain Object

A plain object

  • Inherits directly from Object.prototype or null
  • Is not a constructor's prototype property

plain-object/is

Confirms if given object is a plain object

const isPlainObject = require("type/plain-object/is");

isPlainObject({}); // true
isPlainObject(Object.create(null)); // true
isPlainObject([]); // false

plain-object/ensure

If given argument is a plain object it is returned back. Otherwise TypeError is thrown.

const ensurePlainObject = require("type/plain-object/ensure");

ensurePlainObject({}); // {}
ensurePlainObject("foo"); // Thrown TypeError: foo is not a plain object
Confirming on keys

Keys can be validated by passing allowedKeys option. Note that in this case:

  • Error message lists up to three invalid keys
const allowedKeys = ["foo"];

ensurePlainObject({}, { allowedKeys }); // {}
ensurePlainObject({ foo: "bar" }, { allowedKeys }); // { foo: 'bar' }

/*
 Below invocation with crash with:
 TypeError: [object Object] is not a valid plain object.
            Following keys are unexpected: lorem, ipsum
*/
ensurePlainObject({ foo: "bar", lorem: 1, ipsum: 2 }, { allowedKeys });
Confirming on property values

Property values can be validated by passing ensurePropertyValue option. Note that in this case:

  • A newly created instance of plain object with coerced values is returned
  • Error message lists up to three keys that contain invalid values
const ensureString = require("type/string/ensure");

ensurePlainObject({ foo: 12 }, { ensurePropertyValue: ensureString }); // { foo: '12' }

/*
 Below invocation with crash with:
 TypeError: [object Object] is not a valid plain object.
            Valuees for following keys are invalid: lorem, ipsum
*/
ensurePlainObject({ foo: 23, lorem: {}, ipsum: {} }, { ensurePropertyValue: ensureString });

Array

Array instance

array/is

Confirms if given object is a native array

const isArray = require("type/array/is");

isArray([]); // true
isArray({}); // false
isArray("foo"); // false

array/ensure

If given argument is an array, it is returned back. Otherwise TypeError is thrown.

const ensureArray = require("type/array/ensure");

ensureArray(["foo"]); // ["foo"]
ensureArray("foo"); // Thrown TypeError: foo is not an array

Array Like

Array-like value (any value with length property)

array-like/is

Restricted array-like confirmation. Returns true for every value that meets following contraints

  • is an object (or with allowString option, a string)
  • is not a function
  • Exposes length that meets array-length constraints
const isArrayLike = require("type/array-like/is");

isArrayLike([]); // true
isArrayLike({}); // false
isArrayLike({ length: 0 }); // true
isArrayLike("foo"); // false
isArrayLike("foo", { allowString: true }); // true

array-like/ensure

If given argument is an array-like, it is returned back. Otherwise TypeError is thrown.

const ensureArrayLike = require("type/array-like/ensure");

ensureArrayLike({ length: 0 }); // { length: 0 }
ensureArrayLike("foo", { allowString: true }); // "foo"
ensureArrayLike({}); // Thrown TypeError: null is not an iterable

Array length

number primitive that conforms as valid array length

array-length/coerce

Follows safe-integer/coerce but returns null in place of values which are below 0

const coerceToArrayLength = require("type/safe-integer/coerce");

coerceToArrayLength("12.95"); // 12
coerceToArrayLength(9007199254740992); // null
coerceToArrayLength(null); // null
array-length/ensure

If given argument is an array length coercible value (via array-length/coerce) returns result number. Otherwise TypeError is thrown.

const ensureArrayLength = require("type/array-length/ensure");

ensureArrayLength(12.93); // "12"
ensureArrayLength(9007199254740992); // Thrown TypeError: null is not a valid array length

Iterable

Value which implements iterable protocol

iterable/is

Confirms if given object is an iterable and is not a string (unless allowString option is passed)

const isIterable = require("type/iterable/is");

isIterable([]); // true
isIterable({}); // false
isIterable("foo"); // false
isIterable("foo", { allowString: true }); // true

Supports also denyEmpty option

isIterable([], { denyEmpty: true }); // false
isIterable(["foo"], { denyEmpty: true }); // true

iterable/ensure

If given argument is an iterable, it is returned back. Otherwise TypeError is thrown. By default string primitives are rejected unless allowString option is passed.

const ensureIterable = require("type/iterable/ensure");

ensureIterable([]); // []
ensureIterable("foo", { allowString: true }); // "foo"
ensureIterable({}); // Thrown TypeError: null is not expected iterable
Denying empty iterables

Pass denyEmpty option to require non empty iterables

ensureIterable([], { denyEmpty: true }); // Thrown TypeError: [] is not expected iterable
Confirming on items

Items can be validated by passing ensureItem option. Note that in this case:

  • A newly created instance of array with coerced values is returned
  • Error message lists up to three invalid items
const ensureString = require("type/string/ensure");

ensureIterable(new Set(["foo", 12]), { ensureItem: ensureString }); // ["foo", "12"]

/*
 Below invocation with crash with:
 TypeError: [object Set] is not expected iterable value.
            Following items are invalid:
              - [object Object]
*/
ensureIterable(new Set(["foo", {}]), { ensureItem: ensureString });

Date

Date instance

date/is

Confirms if given object is a native date, and is not an Invalid Date

const isDate = require("type/date/is");

isDate(new Date()); // true
isDate(new Date("Invalid date")); // false
isDate(Date.now()); // false
isDate("foo"); // false

date/ensure

If given argument is a date object, it is returned back. Otherwise TypeError is thrown.

const ensureDate = require("type/date/ensure");

const date = new Date();
ensureDate(date); // date
ensureDate(123123); // Thrown TypeError: 123123 is not a date object

Time value

number primitive which is a valid time value (as used internally in Date instances)

time-value/coerce

Follows integer/coerce but returns null in place of values which go beyond 100 000 0000 days from unix epoch

const coerceToTimeValue = require("type/time-value/coerce");

coerceToTimeValue(12312312); // true
coerceToTimeValue(Number.MAX_SAFE_INTEGER); // false
coerceToTimeValue("foo"); // false
time-value/ensure

If given argument is a time value coercible value (via time-value/coerce) returns result number. Otherwise TypeError is thrown.

const ensureTimeValue = require("type/time-value/ensure");

ensureTimeValue(12.93); // "12"
ensureTimeValue(Number.MAX_SAFE_INTEGER); // Thrown TypeError: null is not a natural number

Function

Function instance

function/is

Confirms if given object is a native function

const isFunction = require("type/function/is");

isFunction(function () {}); // true
isFunction(() => {}); // true
isFunction(class {}); // true
isFunction("foo"); // false

function/ensure

If given argument is a function object, it is returned back. Otherwise TypeError is thrown.

const ensureFunction = require("type/function/ensure");

const fn = function () {};
ensureFunction(fn); // fn
ensureFunction(/foo/); // Thrown TypeError: /foo/ is not a function

Plain Function

A Function instance that is not a Class

plain-function/is

Confirms if given object is a plain function

const isPlainFunction = require("type/plain-function/is");

isPlainFunction(function () {}); // true
isPlainFunction(() => {}); // true
isPlainFunction(class {}); // false
isPlainFunction("foo"); // false
plain-function/ensure

If given argument is a plain function object, it is returned back. Otherwise TypeError is thrown.

const ensurePlainFunction = require("type/function/ensure");

const fn = function () {};
ensurePlainFunction(fn); // fn
ensurePlainFunction(class {}); // Thrown TypeError: class is not a plain function

RegExp

RegExp instance

reg-exp/is

Confirms if given object is a native regular expression object

const isRegExp = require("type/reg-exp/is");

isRegExp(/foo/);
isRegExp({}); // false
isRegExp("foo"); // false

reg-exp/ensure

If given argument is a regular expression object, it is returned back. Otherwise TypeError is thrown.

const ensureRegExp = require("type/reg-exp/ensure");

ensureRegExp(/foo/); // /foo/
ensureRegExp("foo"); // Thrown TypeError: null is not a regular expression object

Promise

Promise instance

promise/is

Confirms if given object is a native promise

const isPromise = require("type/promise/is");

isPromise(Promise.resolve()); // true
isPromise({ then: () => {} }); // false
isPromise({}); // false
promise/ensure

If given argument is a promise, it is returned back. Otherwise TypeError is thrown.

const ensurePromise = require("type/promise/ensure");

const promise = Promise.resolve();
ensurePromise(promise); // promise
eensurePromise({}); // Thrown TypeError: [object Object] is not a promise

Thenable

Thenable object (an object with then method)

thenable/is

Confirms if given object is a thenable

const isThenable = require("type/thenable/is");

isThenable(Promise.resolve()); // true
isThenable({ then: () => {} }); // true
isThenable({}); // false
thenable/ensure

If given argument is a thenable object, it is returned back. Otherwise TypeError is thrown.

const ensureThenable = require("type/thenable/ensure");

const promise = Promise.resolve();
ensureThenable(promise); // promise
ensureThenable({}); // Thrown TypeError: [object Object] is not a thenable object

Error

Error instance

error/is

Confirms if given object is a native error object

const isError = require("type/error/is");

isError(new Error()); // true
isError({ message: "Fake error" }); // false

error/ensure

If given argument is an error object, it is returned back. Otherwise TypeError is thrown.

const ensureError = require("type/error/ensure");

const someError = new Error("Some error");
ensureError(someError); // someError
ensureError({ message: "Fake error" }); // Thrown TypeError: [object Object] is not an error object

Prototype

Some constructor's prototype property

prototype/is

Confirms if given object serves as a prototype property

const isPrototype = require("type/prototype/is");

isPrototype({}); // false
isPrototype(Object.prototype); // true
isPrototype(Array.prototype); // true

Tests

$ npm test
You can’t perform that action at this time.