// denotes that add() accepts two numbers and returns a third:
add = t('n,n n', function(a, b) { return a + b });
add(3, 7);
// => 10
add('3', '7');
// => Taxa: Expected number as argument 0, given string (3) instead.
Taxa is a small metaprogramming experiment that introduces a minimal grammar for
type annotations to JavaScript (and by extension, CoffeeScript).
Unlike other projects of this nature, Taxa is purely a runtime type checker
rather than a static analyzer. When a Taxa-wrapped function receives or returns
arguments of the wrong type, an exception is thrown.
Further unlike other type declaration projects for JavaScript, Taxa’s DSL lives
purely within the syntax of the language. There is no intermediary layer and no
preprocessing is required.
Grammar
Taxa type signatures are intended to be quick to type and to occupy few additional
columns in your code.
Following this spirit of brevity, examples are also shown in CoffeeScript as it’s
a natural fit to Taxa’s style.
In the following, Taxa is aliased as t (though $ or taxa feel natural as well):
t = require 'taxa'
# or in a browser without a module loader:
t = window.taxa
var t = require('taxa');
// or in a browser without a module loader:
var t = window.taxa;
A type signature is composed of two halves: the argument types and the return
type, separated by a space.
pluralize = t 'String String', (word) -> word + 's'
var pluralize = t('String String', function(word) {
return word + 's';
});
The above signature indicates a function that expects a single string argument
and is expected to return a string as a result. If any other types are passed to
it, an informative error will be thrown:
pluralize 7
# => Taxa: Expected string as argument 0, given number (7) instead.
pluralize(7);
// => Taxa: Expected string as argument 0, given number (7) instead.
Shorthand
Taxa provides a shorthand for built-in types, indicated by their first letter.
The following is equivalent to the previous example:
exclaim = t 's s', (word) -> word + '!'
var exclaim = t('s s', function(word) {
return word + '!';
});
Capital letter shorthand works as well:
exclaim = t 'S S', (word) -> word + '!'
var exclaim = t('S S', function(word) {
return word + '!';
});
The shorthand mapping is natural, with the exception of null:
0 => nulla => arrayb => booleanf => functionn => numbero => objects => stringu => undefined
Multiple arguments are separated by commas:
add = t 'n,n n', (a, b) -> a + b
var add = t('n,n n', function(a, b) {
return a + b;
});
The above function is expected to take two numbers as arguments and return a third.
Ignores
Occasionally you may want to ignore type checking on a particular argument.
Use the _ character to mark it as ignored in the signature. For example, you may
have a method that produces effects without returning a value:
Population::setCount = t 'n _', (@count) ->
Population.prototype.setCount = t('n _', function(count) {
this.count = count;
});
Or a function that computes a result without input:
t '_ n', -> Math.PI / 2
t('_ n', function() {
return Math.PI / 2;
});
Optionals
Similarly you can specify arguments as optional and their type will only be
checked if a value is present:
t 's,n? n', (string, radix = 10) -> parseInt string, radix
t('s,n? n', function(string, radix) {
if (radix == null) {
radix = 10;
}
return parseInt(string, radix);
});
Ors
For polymorphic functions that accept different types of arguments, you can use
the | character to separate types.
combine = t 'n|s,n|s n|s', (a, b) -> a + b
var combine = t('n|s,n|s n|s', function(a, b) {
return a + b;
});
For each argument and return type in the above function, either a number or a
string is accepted.
Complex Types
If you’d like to enforce types that are more specific than primitives, objects,
and arrays, you’re free to do so:
makeDiv = t '_ HTMLDivElement', -> document.createElement 'div'
var makeDiv = t('_ HTMLDivElement', function() {
return document.createElement('div');
});
makeBuffer = t 'n Buffer', (n) -> new Buffer n
var makeBuffer = t('n Buffer', function(n) {
return new Buffer(n);
});
Since all non-primitive types are objects, specifying o in your signatures will
of course match complex types as well. However, passing a plain object or an
object of another type to a function that expects a specific type (e.g. WeakMap)
will correctly throw an error.
Keep in mind that Taxa is strict with these signatures and will not walk up an
object’s inheritance chain to match ancestral types.
Partial Application
Like any other function, those annotated with Taxa carry a bind method, which
works as expected with the additional promise of modifying the output function’s
Taxa signature.
For example:
add = t 'n,n n', (a, b) -> a + b
add2 = add.bind @, 2
add2 3
# => 5
var add = t('n,n n', function(a, b) {
return a + b;
});
var add2 = add.bind(this, 2);
add2(3);
// => 5
Under the covers, add2‘s type signature was changed to n n.
Aliases
You can add your own custom shorthand aliases like this:
t.addAlias 'i8', 'Int8Array'
t.addAlias('i8', 'Int8Array');
And remove them as well:
t.removeAlias 'i8'
t.removeAlias('i8');
Disabling
You can disable Taxa’s type enforcement behavior globally by calling t.disable()
(where t is whatever you’ve aliased Taxa as). This will cause calls to t() to
perform a no-op wherein the original function is returned unmodified.
This is convenient for switching between environments without modifying code.
Its counterpart is naturally t.enable().
Further Examples
Take a look at the test cases in ./test/main.coffee for more examples of
Taxa signatures.
Caveats
When a function is modified by Taxa, its arity is not preserved as most JS
environments don’t allow modifying a function’s length property. Workarounds to
this problem would involve using the Function constructor which would introduce
its own problems. This only has implications if you’re working with higher order
functions that work by inspecting arity.
It should go without saying, but this library is experimental and has obvious
performance implications.
Taxa is young and open to suggestions / contributors.
Name
From the Ancient Greek τάξις (arrangement, order).
