typed-function

typed-function

Type checking for JavaScript functions.

Features:

• Type-checking of input arguments.
• Automatic type conversion of arguments.
• Compose a function from multiple sub-functions with different signatures.

Supported environments: node.js, Chrome, Firefox, Safari, Opera, IE9+.

Load

Install via npm:

npm install typed-function

Usage

Example usage:

var typed = require('typed-function');

// create a typed function
var fn = typed({
  'number': function (a) {
    return 'a is a number';
  },
  'number, boolean': function (a, b) {
    return 'a is a number, b is a boolean';
  },
  'number, number': function (a, b) {
    return 'a is a number, b is a number';
  }
});

// use the function
console.log(fn(2, true));      // outputs 'a is a number, b is a boolean'
console.log(fn(2));            // outputs 'a is a number'

// calling the function with a non-supported type signature will throw an error
try {
  fn('hello world');
}
catch (err) {
  console.log(err.toString()); // outputs: 'TypeError: Wrong function signature'
}

Performance

Type checking input arguments adds some overhead to a function. For very small functions this overhead can be larger than the function execution itself is, but for any non-trivial function the overhead is typically small to neglectable. You need to keep in mind though that you probably would have to do the type checking done by typed-function anyway.

API

Construction

A function is constructed as:

typed(signatures: Object.<string, function>) : function
typed(name: string, signatures: Object.<string, function>) : function

Properties

• typed.types: Object A map with the object types as key and a type checking test as value. Custom types can be added like:

  function Person(...) {
    ...
  }
  
  typed.types['Person'] = function (x) {
    return x instanceof Person;
  };
  

• typed.conversions: Array An Array with built-in conversions. Empty by default. Can be used for example to defined conversions from boolean to number. For example:

  typed.conversions.push({
    from: 'boolean',
    to: 'number',
    convert: function (x) {
      return +x;
  });
  

Types

typed-function has the following built-in types:

• null
• boolean
• number
• string
• function
• Array
• Date
• RegExp
• Object
• * (anytype)

Output

The functions generated with typed({...}) have:

• A toString() function which returns well readable code, giving insight in what the function exactly does.
• A property signatures, which holds a map with the (normalized) signatures as key and the original sub-functions as value.

Roadmap

Version 1

• Extend function signatures:
  • Any type arguments like '*, boolean'
  • Ellipsis like 'string, ...'
  • Optional arguments like 'number?, array'
  • Multiple types per argument like number | string, number'
• Detailed error messages.
• Create a good benchmark, to get insight in the overhead.
• Allow conversions not to be able to convert any input (for example string to number is not always possible).

Version 2

• Extend function signatures:
  • Constants like '"linear" | "cubic"'.
  • Object definitions like '{name: string, age: number}'
  • Object definitions like 'Object.<string, Person>'
  • Array definitions like 'Array.<Person>'

Test

To test the library, run:

npm test

Minify

To generate the minified version of the library, run:

npm run minify

Similar packages

Other packages similar to typed-function

io-ts

io-ts is a runtime type system for IO decoding/encoding in TypeScript. It allows you to define types and validate data at runtime. Compared to typed-function, io-ts is more focused on data validation and transformation rather than function overloading.

runtypes

Runtypes provides a way to define and validate types at runtime in TypeScript. It offers a similar type-checking functionality but is more geared towards defining and validating data structures rather than function signatures.

ts-runtime

ts-runtime is a TypeScript transformer that adds runtime type checks to your TypeScript code. It provides a more integrated approach to type checking in TypeScript, whereas typed-function is a standalone library for JavaScript.