typeof-arguments

Description

typeof-arguments is a module that validates arguments' types passed to the enclosing function.

• Any bugs found? Give me to know on [e-mail] or on GitHub
• Also check out of-type package that checks whether the given value is of particular type (typeof-arguments is based on of-type package).
• Also check out typeof-properties to validate value types of the properties of objects.

Installation

npm install typeof-arguments

var argType = require('typeof-arguments');

Usage

argType(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.

The expected Types

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

• by string expression values
• by regular expression values
• by constructor functions, null or undefined values

[Object:String]

• Possible values: 'null', 'undefined', or any value equal to constructor.name, eg: 'string', 'number', 'regexp', 'array', 'object', 'boolean','buffer', etc.
• The [String] value is case insensitive: 'String', 'string', 'StRiNg' checks if the argument is of type [String].
• The [String] value can contain multiple allowed types, separated with |. eg: 'array|object' checks if the argument is of type [Array] OR of type [Object].

test('Paul',26);

function test(){
  argType(arguments,['string', 'number|string|null']);
}

[Object:RegExp]

• Possible values: /null/, /undefined/, or any value matching the constructor.name, eg: /String/, /Number/, /RegExp/, /Array/, /Object/, /Boolean/,/Buffer/, /Promise/, etc.
• For the case insensitivity use i flag, eg: /string/i, /regexp/i, /typeerror/i
• For multiple values use regexp (x|y) expression, eg: /String|Number/, /TypeError|Error/
• Use another regexp features:
  • eg. /(Type|Range|Syntax)Error/ will match TypeError, RangeError and SyntaxError
  • eg. /[A-Z].+/ will match String, Array, but will not match undefined, null, etc.

test('Paul',26);

function test(){
  argType(arguments,[/string/i, /num|string|null/i]);
}

[Object:null|undefined|Function|Array]

• Possible values: null, undefined or any constructor object, eg: String, TypeError, Promise, Array, etc.
• For multiple values use array, eg: [String,Object,Array,null]

test('Paul',26);

function test(){
  argType(arguments,[String, [Number,String,null]]);
}

Extra types:

• The value can be: 'arguments' or /arguments/. It returns true if the argument is defined as the arguments Object
• The value can be: 'truthy' or /truthy/. It returns true if the argument has the value like: "abc", true, 1, {}, [],function(){}, etc.
• The value can be: 'falsy' or /falsy/. It returns true if the argument has the value like: "", false, 0, null, undefined, etc.
• The value can be: '' or 'any' or /any/ or [], It returns true if the argument is 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

var argType = require('typeof-arguments');

hello("Paul", 26);

function hello(name,age){
  argType(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 argType() returns true when all arguments passed through the enclosing function are of valid types.
The function argType() returns false when at least one of the arguments passed through the enclosing function is of invalid type.

var argType = require('typeof-arguments');

hello("hello","world!");

function hello(paramA,paramB){
  var areValid = argType(arguments,['string','string']);
  if(!areValid) return; //stop executing code if at least one argument is of invalid type
  //your code here...
}

Tests

> git clone https://github.com/devrafalko/typeof-arguments.git
> cd typeof-arguments
> npm install
> npm test
> npm test deep //displays error messages

Samples

var argType = require('typeof-arguments');

function test(paramA,paramB,paramC){
  argType(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:'Paul'},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.

more samples

var argType = require('typeof-arguments');

function test(paramA,paramB){
  argType(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

more samples

var argType = 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('Paul',null,false,10);
//no errors

test('Paul',null,false,10,new TypeError('error'));
//no errors

test('Paul',null,false,10,false);
//no errors

test('Paul');
//Invalid argument [3]. The [undefined] argument has been passed, while the argument of type [Number] is expected.

test('Paul',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.