Nuptial Predicament Mediation

    type
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.0 • Public • Published

    *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({}); // {}
    ensureArray("foo"); // Thrown TypeError: foo is not a plain object

    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.

    const ensureIterable = require("type/iterable/ensure");
    
    ensureIterable([]); // []
    ensureIterable("foo", { allowString: true }); // "foo"
    ensureIterable({}); // Thrown TypeError: null is not expected iterable

    Additionally items can be coreced with coerceItem option. Note that in this case:

    • A newly created array with coerced values is returned
    • Validation crashes if any of the items is not coercible
    ensureIterable(new Set(["foo", 12])); // ["foo", "12"]
    
    ensureIterable(new Set(["foo", {}])); // Thrown TypeError: Set({ "foo", {} }) is not expected iterable

    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
    

    Keywords

    Install

    npm i type@1.2.0

    Version

    1.2.0

    License

    ISC

    Unpacked Size

    102 kB

    Total Files

    101

    Last publish

    Collaborators

    • gozala
    • medikoo