def.js

def.js

A multiple-dispatch function overloading library for JavaScript.

Examples

Function overloading:

var def = require('def.js');

var fibonacci = def(Number       , function(n) { return fibonacci(n-1) + fibonacci(n-2); })
               .def(Number.max(1), function(n) { return 1; });

fibonacci(0); // 1
fibonacci(1); // 1
fibonacci(2); // 2
fibonacci(3); // 3

Simple router for node.js HTTP servers:

var http = require('http'),
    def = require('def.js'),
    handler = def();

handler.def({url : '/hello'}, function (req, res) {
  res.writeHead(200, {'Content-Type': 'text/plain'});
  res.end('Hello\n');
});

handler.def({url : '/world'}, function (req, res) {
  res.writeHead(200, {'Content-Type': 'text/plain'});
  res.end('World\n');
});

http.createServer(handler).listen(1337, '127.0.0.1');

Usage

Overloaded functions can be created using the def function. It returns a dispatcher function, which will later check the function arguments, and call the appropriate implementation functions. Implementation functions are always associated with a function signature, and can be defined with the def method of the dispatcher. The first implementation and signature may be defined when initally calling the standalone def function.

The first parameters of the def function are called the function signature or the filters. Filters are described as JS schema. The first filter applies to the first argument, the second applies to the second, etc. A typical function overloading with signature definitions looks like this:

f = def(Number, String        , function(n, s) { console.log(n, s); })
   .def(42    , /The Answer.*/, function(n, s) { console.log('The answer is: ' + s); });

Function call order

The most generic implementation must come first, then the special cases. It is explained by the way def.js executes the implementation functions. It goes like this:

1. Select the last defined unchecked function implementation and signature
2. Check the function signature against the function call's arguments and the value of this
3. If the signature matches the arguments and the value of this:

• Execute the implementation function with the given arguments and this
• If the return value ret is not undefined then stop executing and return ret

1. Go to step 1 if there are unchecked implementations left

Filter for this

The filter for this is also part of the function signature. To define a filter for the value of this, use def.call or def.apply.

print = def.call(Number, function(comment) { console.log('Number: ' + this + ' (' + comment + ')'); })
       .def.call(String, function(comment) { console.log('String: ' + this + ' (' + comment + ')'); });

print.call(1, 'an important number'); // Number: 1 (an important number)
print.call('a', 'the first letter');  // String: a (the first letter)

Installation

Using npm:

npm install def.js

License

The MIT License

Copyright (C) 2012 Gábor Molnár [e-mail]