typeof-arguments

5.1.3 • Public • Published

Description

typeof-arguments validates the arguments' types passed through the enclosing function.

  • Also see of-type package to check if the given value|object is of expected type.
  • Also see typeof-properties to validate the object's properties' type.
  • Also see typeof-items to validate the array's items' type

Implementation

with NodeJS

npm install typeof-arguments

const type = require('typeof-arguments');

with Browser

Add typeof-arguments.js library to the HTML file.

The library is located in ./dist/typeof-arguments.js directory.
It is a webpack&babel bundled cross-browser library version.
The library is accessible as typeofArguments variable in the global (window) scope.

<head>
  <script src='typeof-arguments.js'></script> 
  <script>
    function test(name, age) {
      typeofArguments(arguments, ['string', 'number|string|null']);
    }
    test('Nikola', 26);
  </script> 
</head>

Tests

> git clone https://github.com/devrafalko/typeof-arguments.git
> cd typeof-arguments
> npm install
> npm test        //run tests in node
> npm test deep   //run tests in node with errors shown

Usage

type(actual, expected[, callback])

actual [Object]

It should always indicate the enclosing function arguments object.

expected [Array]

  • It should contain the [Array] list of expected types for each subsequent argument passed through the enclosing function.
  • The [Array] expected item's index coheres with the index of actual argument item passed through the enclosing function.
  • The values of [Array] expected items indicate the expected types of the coherent actual arguments passed through the enclosing function.
test('Nikola', 26);
 
function test(name, age) {
  //the name should be of [String] type
  //and the age should be of [Number|String|null] type
  type(arguments, ['string', 'number|string|null']);
}

The expected Types

There are four ways to check the type of the arguments:

  • by string expression values
  • by regular expression values
  • by constructor functions, null or undefined values
  • by some of supported custom types

Mind, that the typeof-arguments library uses the of-type library as the dependency, to validate the types. If you feel confused how to use the types, see more samples here.

[String]

  • Possible values:
    • 'null', 'undefined'
    • any value that equals to argument's constructor.name, eg:
      'string', 'number', 'regexp', 'array', 'object', 'boolean','buffer', etc.
  • The [String] type is case insensitive:
    • 'String', 'string', 'StRiNg' checks if the argument is of [String] type
    • 'RegExp', 'REGEXP', 'regexp' checks if the argument is of [RegExp] type
  • The [String] type can contain multiple types, separated with |:
    • 'array|object' checks if the argument is of [Array] OR [Object] type
    • 'undefined|null' checks if the argument is of undefined OR null type
test('Nikola', 26);
 
function test() {
  type(arguments, ['string', 'number|string|null']);
}

[RegExp]

  • Possible values:
    • /null/, /undefined/
    • any value matching the argument's constructor.name, eg: /String/, /Number/, /RegExp/, /Array/, /Object/, /Boolean/,/Buffer/, /Promise/, etc.
  • Use all regular expression's features to match the type in a desired way:
    • /Str/, /Err/, /Reg/, /B/
    • /.+Error$/, /^RegExp$/,
    • /^[A-Z][a-z]+$/
  • For the case insensitivity use i flag:
    • /string/i, /regexp/i, /TYPEERROR/i
  • For multiple values use regexp (x|y) expression:
    • /String|Number/, /TypeError|Error/, /(obj|str)/i
test('Nikola', 26);
 
function test() {
  type(arguments, [/string/i, /number|string|null/i]);
}

[Function|Array|null|undefined]

  • Possible values:
    • null, undefined
    • any [Function] constructor, eg: String, TypeError, Promise, Array, etc.
  • For multiple values use array:
    • [String, Object, Array, null]
    • [null, undefined, Boolean]
test('Nikola', 26);
 
function test() {
  type(arguments, [String, [Number, String, null]]);
}

When you use bundlers or minifiers, use [String|RegExp] type wisely as bundlers may change the names of functions|constructors|classes in the output file and eg. type(arguments, ['MyClass']); that returns true before compilation, may return false after compilation, if the bundler minifies the 'MyClass' constructor name.

Extra types:

[String] 'arguments' | [RegExp] /arguments/

  • The type 'arguments' or /arguments/ expects the passed argument to be the function's arguments object

[String] 'instance' | [RegExp] /instance/

  • The type 'instance' or /instance/ expects the passed argument to be the instance of the user's class|constructor
  • It fails when the passed argument is an instance of built-in (native) constructor
    • [], 'hello world', {}
  • It fails for instances that are the global|window's properties

[String] 'objectable' | [RegExp] /objectable/

  • The type 'objectable' or /objectable/ expects the passed argument to be the object that is the instance of the Object constructor
    • {}, [], new String('hello world'), new Boolean(1)
  • It fails when the passed argument is a primitive value or a simple value
    • 'hello world', true, 10, null, undefined

[String] 'truthy' | [RegExp] /truthy/

  • The type 'truthy' or /truthy/ expects the passed argument to be like:
    • 'abc', true, 1, -1, {}, [], function(){}

[String] 'falsy' | [RegExp] /falsy/

  • The type 'falsy' or /falsy/ expects the passed argument to be like:
    • '', false, 0, null, undefined, NaN

[String] 'any' | [RegExp] /any/ | [Array] [] | [String] ""

  • The type 'any' or /any/ or empty array [] or empty string "" expects the passed argument to be of any type

callback [Function] (optional)

  • if not passed, the TypeError with default message will be thrown to the console, if the argument passed to the function is invalid.
  • The TypeError default message is eg.:
    • Invalid argument [0]. The [Number] argument has been passed, while the argument of type [String] is expected.
    • Invalid argument [2]. The [null] argument has been passed, while the argument of type matching string expression "boolean" is expected.
    • Invalid argument [1]. The [null] <<falsy>> argument has been passed, while the argument of type matching string expression "truthy|undefined" is expected.
    • Invalid argument [0]. The [undefined] argument has been passed, while the argument of type matching regular expression /string/i is expected.
  • if passed, the default TypeError will not be thrown to the console and the user can decide what to do inside the callback function.
  • Use callback function if you don't want to stop your code execution by default (no callback) throw statement!
  • the callback function is executed only if at least one argument passed through the enclosing function is of invalid type.
  • The one [Object] argument is passed through callback function with the following properties:
    • index
      indicates the [Number] index of the incorrect argument passed through the enclosing function, eg. 0, 1
    • actual
      indicates the actual type of the argument passed through the enclosing function, eg. "String"
    • expected
      indicates the type(s) expected by the user, eg. "Array", "Boolean|Number", "/array|object/i"
    • message
      is the default error [String] message, that you can use eg. to log in the console
    • textActual
      indicates the [String] textual actual type, eg. "[undefined] <<falsy>> argument"
    • textExpected
      indicates the [String] textual expected type, eg. "argument of type matching regular expression /String|null/"
const type = require('typeof-arguments');
 
hello('Nikola', 26);
 
function hello(name, age) {
  type(arguments, [String, 'string|number'], (o) => {
    console.error(o.message);
    /*
    console.error('Not good! Use ' + o.expected + ' instead of ' + o.actual + ' for argument ' + o.index);
    throw new Error("Aborted! " + o.message);
    */
  });
}

Return value

The function type() returns true when all arguments passed through the enclosing function are of valid types.
The function type() returns false when at least one of the arguments passed through the enclosing function is of invalid type.

const type = require('typeof-arguments');
 
hello('hello', 'world!');
 
function hello(paramA, paramB) {
  const valid = type(arguments, ['string', 'string'], () => { });
  if (!valid) return; //stop executing code if at least one argument is of invalid type
  //your code here...
}

Samples

const type = require('typeof-arguments');
 
function test(paramA, paramB, paramC) {
  type(arguments, ['number|string', 'any', 'null|array']);
}
 
test('hello', 'it\'s me!', null);
//no errors
 
test(10, 20, [1, 2, 3]);
//no errors
 
test(true, 20, null);
//Invalid argument [0]. The [Boolean] argument has been passed, while the argument of type matching string expression "number|string" is expected.
 
test({ name: 'Nikola' }, false, /test/);
//Invalid argument [0]. The [Object] argument has been passed, while the argument of type matching string expression "number|string" is expected.
//Invalid argument [2]. The [RegExp] argument has been passed, while the argument of type matching string expression "null|array" is expected.
 
test(10, 20, null, 30, 40, 50, 60, 70);
//no errors
 
test(10);
//Invalid argument [2]. The [undefined] argument has been passed, while the argument of type matching string expression "null|array" is expected.
const type = require('typeof-arguments');
 
function test(paramA, paramB) {
  type(arguments, ['truthy|string', /(regexp|falsy)/i]);
}
 
test();
//Invalid argument [0]. The [undefined] <<falsy>> argument has been passed, while the argument of type matching string expression "truthy" is expected.
 
test('', '');
//Invalid argument [0]. The [String] <<falsy>> argument has been passed, while the argument of type matching string expression "truthy" is expected.
 
test(1, 0);
//no errors
 
test(0, 1);
//Invalid argument [0]. The [Number] <<falsy>> argument has been passed, while the argument of type matching string expression "truthy" is expected.
//Invalid argument [1]. The [Number] <<truthy>> argument has been passed, while the argument of type matching regular expression /(regexp|falsy)/i is expected.
 
test([1, 2, 3], /test/);
//no errors
 
test('hello', null);
//no errors
const type = require('typeof-arguments');
 
function test(paramA, paramB) {
  type(arguments, [String, 'any', 'any', Number, /((syntax|type)error)|falsy/i]);
}
 
test();
//Invalid argument [0]. The [undefined] argument has been passed, while the argument of type [String] is expected.
 
test('Nikola', null, false, 10);
//no errors
 
test('Nikola', null, false, 10, new TypeError('error'));
//no errors
 
test('Nikola', null, false, 10, false);
//no errors
 
test('Nikola');
//Invalid argument [3]. The [undefined] argument has been passed, while the argument of type [Number] is expected.
 
test('Nikola', true, true, 10, new Error('error'));
//Invalid argument [4]. The [Error] <<truthy>> argument has been passed, while the argument of type matching regular expression /((syntax|type)error)|falsy/i is expected.
const type = require('typeof-arguments');
 
function test(paramA, paramB) {
  type(arguments, ['instance', 'Name', 'object', 'falsy']);
}
 
class Name{}
class Age{}
const name = new Name();
const age = new Age();
 
test();
//Invalid argument [0]. The [undefined] argument has been passed, while the argument of type matching string expression "instance" is expected.
 
test(name, name, {}, null);
//no errors
 
test(age, name, {}, NaN);
//no errors
 
test(age, age, {}, false);
//Invalid argument [1]. The [Age] argument has been passed, while the argument of type matching string expression "Name" is expected.
 
test({}, name, {}, NaN);
//Invalid argument [0]. The [Object] argument has been passed, while the argument of type matching string expression "instance" is expected.
 
test(name, {}, {}, 0);
//Invalid argument [1]. The [Object] argument has been passed, while the argument of type matching string expression "Name" is expected.
 
test(age, name, age, NaN);
//Invalid argument [2]. The [Age] argument has been passed, while the argument of type matching string expression "object" is expected.

Package Sidebar

Install

npm i typeof-arguments

Weekly Downloads

5,871

Version

5.1.3

License

MIT

Unpacked Size

21.2 kB

Total Files

4

Last publish

Collaborators

  • devrafalko