enforce.md

Type Enforcer

A type enforcement library for javascript

enforce : object

Utility functions for enforcing data types.

Example

import { enforce } from 'type-enforcer';

// Or import individual functions
import { enforceBoolean, enforceString } from 'type-enforcer';

Extending enforcers

All enforcers with a "coerce" option also have a static method ".extend" that creates a new enforcer. It accepts two args:

• The first arg should be a valid check function that accepts a second "coerce" arg.
• The second arg should be a function that coerces a coercible value (as determined by the check function).

• enforce : object
  • .array(value, alt, [coerce]) ⇒ Array.<ReturnType>
  • .boolean(value, alt, [coerce]) ⇒ boolean
  • .date(value, alt, [coerce]) ⇒ Date
  • .enum(value, enumerable, alt) ⇒ string
  • .float(value, alt, [coerce], [minValue], [maxValue]) ⇒ number
  • .function(value, alt) ⇒ function
  • .instanceOf(value, constructor, alt) ⇒ object
  • .integer(value, alt, [coerce], [minValue], [maxValue]) ⇒ number
  • .map(value, alt, [coerce]) ⇒ object
  • .number(value, alt, [coerce], [minValue], [maxValue]) ⇒ number
  • .object(value, alt, [coerce]) ⇒ T
  • .promise(value, alt, [coerce]) ⇒ Promise
  • .regExp(value, alt, [coerce]) ⇒ RegExp
  • .set(value, alt, [coerce]) ⇒ object
  • .string(value, alt, [coerce]) ⇒ string
  • .symbol(value, alt, [coerce]) ⇒ object
  • .weakMap(value, alt, [coerce]) ⇒ object
  • .weakSet(value, alt, [coerce]) ⇒ object

enforce.array(value, alt, [coerce]) ⇒ Array.<ReturnType>

Enforce that a value is an array. Uses isArray.

Alias: enforceArray

Param	Type	Default	Description
value	unknown
alt	Array.<ReturnType>		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value when possible

Example

import { enforce } from 'type-enforcer';

enforce.array(['a string'], ['alt']);
// => ['a string']

enforce.array('[]', ['alt']);
// => ['alt']

enforce.array('[]', ['alt'], true);
// => []

enforce.boolean(value, alt, [coerce]) ⇒ boolean

Enforce that a value is a boolean. Uses isBoolean.

Alias: enforceBoolean

Param	Type	Default	Description
value	unknown
alt	boolean		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value when possible

Example

import { enforce } from 'type-enforcer';

enforce.boolean(false, true);
// => false

enforce.boolean('', true);
// => true

enforce.boolean('', true, true);
// => false

enforce.date(value, alt, [coerce]) ⇒ Date

Enforce that a value is a date. Uses isDate.

Alias: enforceDate

Param	Type	Default	Description
value	unknown
alt	Date		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value when possible

Example

import { enforce } from 'type-enforcer';

enforce.date(new Date('10/12/1980'), new Date('1/1/2000'));
// => date of 10/12/1980

enforce.date('10/12/1980', new Date('1/1/2000'));
// => date of 1/1/2000

enforce.date('10/12/1980', new Date('1/1/2000'), true);
// => date of 10/12/1980

enforce.enum(value, enumerable, alt) ⇒ string

Enforce that a value exists in the provided Enum.

Alias: enforceEnum

Param	Type	Description
value	unknown	The value to enforce.
enumerable	Enum	A valid enum.
alt	string	Returned if the value is not the correct type.

Example

import { enforce, Enum } from 'type-enforcer';

const values = new Enum({
    a: 'item a',
    b: 'item b'
});

enforce.enum(values.a, values, values.b);
// => 'item a'

enforce.enum(values.c, values, values.b);
// => 'item b'

enforce.float(value, alt, [coerce], [minValue], [maxValue]) ⇒ number

Enforce that a value is a finite float. Uses isFloat.

Alias: enforceFloat

Param	Type	Default	Description
value	unknown
alt	number		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value when possible
[minValue]	number
[maxValue]	number

Example

import { enforce } from 'type-enforcer';

enforce.float(3.14159, 13.2);
// => 3.14159

enforce.float('3.14159', 13.2);
// => 13.2

enforce.float('3.14159', 13.2, true);
// => 3.14159

enforce.function(value, alt) ⇒ function

Enforce that a value is a function. Uses isFunction.

Alias: enforceFunction

Param	Type	Description
value	unknown	The value to enforce.
alt	function	Returned if the value is not the correct type.

Example

import { enforce } from 'type-enforcer';

const a = () => {};
const b = () => {};

enforce.function(a, b);
// => a

enforce.function('', b);
// => b

enforce.instanceOf(value, constructor, alt) ⇒ object

Enforce that a value is an instance of a constructor. Uses isInstanceOf.

Alias: enforceInstanceOf

Param	Type	Description
value	unknown	The value to enforce.
constructor	function	A constructor function.
alt	object	Returned if the value is not the correct type.

Example

import { enforce } from 'type-enforcer';

class A {};
class C {};

const a = new A();
const b = new A();
const c = new C();

enforce.instanceOf(b, A, a);
 => b

enforce.instanceOf(c, A, a);
 => a

enforce.integer(value, alt, [coerce], [minValue], [maxValue]) ⇒ number

Enforce that a value is a finite integer. Uses isInteger.

Alias: enforceInteger

Param	Type	Default	Description
value	unknown
alt	number		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value when possible
[minValue]	number
[maxValue]	number

Example

import { enforce } from 'type-enforcer';

enforce.integer(42, 12);
// => 42

enforce.integer('42', 12);
// => 12

enforce.integer('42', 12, true);
// => 42

enforce.map(value, alt, [coerce]) ⇒ object

Enforce that a value is a Map. Uses isMap.

Alias: enforceMap

Param	Type	Default	Description
value	unknown
alt	Map		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value when possible

Example

import { enforce } from 'type-enforcer';

const a = new Map();
const b = new Map();

enforce.map(a, b);
// => a

enforce.map('map', b);
// => b

enforce.number(value, alt, [coerce], [minValue], [maxValue]) ⇒ number

Enforce that a value is a number (excluding NaN). Uses isNumber.

Alias: enforceNumber

Param	Type	Default	Description
value	unknown
alt	number		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value when possible
[minValue]	number	-Infinity
[maxValue]	number	Infinity

Example

import { enforce } from 'type-enforcer';

enforce.number(3.14159, 13.2);
// => 3.14159

enforce.number('3.14159', 13.2);
// => 13.2

enforce.number('3.14159', 13.2, true);
// => 3.14159

enforce.number(Infinity, 13.2, true);
// => Infinity

enforce.object(value, alt, [coerce]) ⇒ T

Enforce that a value is an object. Uses isObject.

Alias: enforceObject

Param	Type	Default	Description
value	unknown
alt	T		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value when possible

Example

import { enforce } from 'type-enforcer';

const a = {};
const b = {};

enforce.object(a, b);
// => a

enforce.object('{}', b);
// => b

enforce.object('{}', b, true);
// => {}

enforce.promise(value, alt, [coerce]) ⇒ Promise

Enforce that a value is a Promise. Uses isPromise.

Alias: enforcePromise

Param	Type	Default	Description
value	unknown
alt	Promise		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value if it's a function. Functions are wrapped in a Promise that resolves with the result of the function.

Example

import { enforce } from 'type-enforcer';

const a = new Promise((resolve) => resolve());
const b = new Promise((resolve) => resolve());

enforce.promise(a, b);
// => a

enforce.promise('', b);
// => b

enforce.regExp(value, alt, [coerce]) ⇒ RegExp

Enforce that a value is a RegExp. Uses isRegExp.

Alias: enforceRegExp

Param	Type	Default	Description
value	unknown
alt	RegExp		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value when possible

Example

import { enforce } from 'type-enforcer';

enforce.regExp(/*+/g, /[a-z]+/);
// => /*+/g

enforce.regExp('/*+/g', /[a-z]+/);
// => /[a-z]+/

enforce.regExp('/*+/g', /[a-z]+/, true);
// => /*+/g

enforce.set(value, alt, [coerce]) ⇒ object

Enforce that a value is a Set. Uses isSet.

Alias: enforceSet

Param	Type	Default	Description
value	unknown
alt	Set		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value when possible

Example

import { enforce } from 'type-enforcer';

const a = new Set();
const b = new Set();

enforce.set(a, b);
// => a

enforce.set('set', b);
// => b

enforce.set([1, 2], b, true);
// => Set with 1 and 2

enforce.string(value, alt, [coerce]) ⇒ string

Enforce that a value is a string. Uses isString.

Alias: enforceString

Param	Type	Default	Description
value	unknown
alt	string		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value when possible

Example

import { enforce } from 'type-enforcer';

enforce.string('a', 'b');
// => 'a'

enforce.string(new Point(), 'b');
// => 'b'

enforce.string(new Point(), 'b', true);
// => '0,0'

enforce.symbol(value, alt, [coerce]) ⇒ object

Enforce that a value is a Symbol. Uses isSymbol.

Alias: enforceSymbol

Param	Type	Default	Description
value	unknown
alt	symbol		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value when possible

Example

import { enforce } from 'type-enforcer';

enforce.symbol(Symbol('label'), Symbol('alt'));
// => Symbol(label)

enforce.symbol('symbol', Symbol('alt'));
// => Symbol('alt')

enforce.symbol('label', Symbol('alt'), true);
// => Symbol(label)

enforce.weakMap(value, alt, [coerce]) ⇒ object

Enforce that a value is a WeakMap. Uses isWeakMap.

Alias: enforceWeakMap

Param	Type	Default	Description
value	unknown
alt	WeakMap		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value when possible

Example

import { enforce } from 'type-enforcer';

const a = new WeakMap();
const b = new WeakMap();

enforce.weakMap(a, b);
// => a

enforce.weakMap('weakMap', b);
// => b

enforce.weakMap([[a, 12]], new WeakMap(), true);
// => WeakMap with key a set to 12

enforce.weakSet(value, alt, [coerce]) ⇒ object

Enforce that a value is a WeakSet. Uses isWeakSet.

Alias: enforceWeakSet

Param	Type	Default	Description
value	unknown
alt	WeakSet		Returned if the value is not the correct type
[coerce]	boolean	false	If true then coerce the value when possible

Example

import { enforce } from 'type-enforcer';

const a = new WeakSet();
const b = new WeakSet();

enforce.weakSet(a, b);
// => a

enforce.weakSet('weakSet', b);
// => b

enforce.weakSet([new Map()], b, true);
// => WeakSet with a Map in it