typed-function

What is typed-function?

The typed-function npm package allows you to define functions with typed arguments in JavaScript. It provides a way to enforce type checking at runtime, making your code more robust and easier to debug.

What are typed-function's main functionalities?

Define a typed function

This feature allows you to define a function with multiple signatures, each with different types of arguments. The function will execute the appropriate implementation based on the types of the provided arguments.

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

const add = typed({
  'number, number': function (a, b) {
    return a + b;
  },
  'string, string': function (a, b) {
    return a + b;
  }
});

console.log(add(2, 3)); // 5
console.log(add('Hello, ', 'world!')); // 'Hello, world!'

Type checking

This feature enforces type checking at runtime, throwing an error if the provided arguments do not match any of the defined signatures. This helps catch type-related bugs early in the development process.

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

const multiply = typed({
  'number, number': function (a, b) {
    return a * b;
  }
});

try {
  console.log(multiply(2, '3')); // Throws an error
} catch (err) {
  console.error(err.message); // 'TypeError: Unexpected type of argument in function multiply (expected: number, actual: string, index: 1)'
}

Default types

This feature allows you to define default types for your function arguments. If no arguments are provided or if they do not match any specific type, the function will fall back to the default implementation.

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

const greet = typed({
  'string': function (name) {
    return 'Hello, ' + name + '!';
  },
  'any': function () {
    return 'Hello, world!';
  }
});

console.log(greet('Alice')); // 'Hello, Alice!'
console.log(greet()); // 'Hello, world!'

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.

README

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

Changelog

2014-11-05, version 0.3.1

• Renamed module to typed-function.