tcomb

% tcomb

tcomb is a library for Node.js and the browser which allows you to check the types of JavaScript values at runtime with a simple syntax. It's great for Domain Driven Design, for testing and for adding safety to your internal code.

Contents

• Features
• Quick Examples
• Setup
• Requirements
• Tests
• The Idea
• Api
  • options
    • options.onFail
    • options.update
  • assert
  • structs
  • unions
  • maybe
  • enums
  • subtypes
  • lists
  • dicts
  • functions
• sweet.js macros (experimental)
• Articles on tcomb

Features

• write complex domain models in a breeze and with small code footprint
• easy debugging
• instances are immutables by default
• encode/decode of domain models to/from JSON for free

The library provides a built-in assert function, if an assert fails the debugger kicks in so you can inspect the stack and quickly find out what's wrong.

You can handle:

JavaScript native types

• Nil: null and undefined
• Str: strings
• Num: numbers
• Bool: booleans
• Arr: arrays
• Obj: plain objects
• Func: functions
• Err: errors
• Re: regular expressions
• Dat: dates
• Any: *

type combinators (build new types from those already defined)

• struct (i.e. classes)
• union
• maybe
• enums
• tuple
• subtype
• list
• dict
• function type

Quick Examples

Let's build a product model

var Product = struct({
    name: Str,                  // required string
    desc: maybe(Str),           // optional string, can be null
    home: Url,                  // a subtype of a string
    shippings: list(Str),       // a list of shipping methods
    category: Category,         // enum, one of [audio, video]
    price: union([Num, Price]), // a price (dollars) OR in another currency
    size: tuple([Num, Num]),    // width x height
    warranty: dict(Num)         // a dictionary country -> covered years
});

var Url = subtype(Str, function (s) {
    return s.indexOf('http://') === 0;
});

var Category = enums.of('audio video');

var Price = struct({ currency: Str, amount: Num });

// JSON of a product
var json = {
    name: 'iPod',
    desc: 'Engineered for maximum funness.',
    home: 'http://www.apple.com/ipod/',
    shippings: ['Same Day', 'Next Businness Day'],
    category: 'audio',
    price: {currency: 'EUR', amount: 100},
    size: [2.4, 4.1],
    warranty: {
      US: 2,
      IT: 1
    }
};

// get an immutable instance, `new` is optional
var ipod = Product(json);

You have existing code and you want to add safety

// your code: plain old JavaScript class
function Point (x, y) {
    this.x = x;
    this.y = y;
}

var p = new Point(1, 'a'); // silent error

in order to "tcombify" your code you can simply add some asserts

function Point (x, y) {
    assert(Num.is(x));
    assert(Num.is(y));
    this.x = x;
    this.y = y;
}

var p = new Point(1, 'a'); // => fail! debugger kicks in

Setup

Node

npm install tcomb

Browser

bower install tcomb

or download the tcomb.min.js file.

Requirements

This library uses a few ES5 methods

• Array.forEach()
• Array.map()
• Array.some()
• Array.every()
• Object.keys()
• Object.freeze()
• JSON.stringify()

you can use es5-shim, es5-sham and json2 to support old browsers

<!--[if lt IE 9]>
<script src="json2.js"></script>
<script src="es5-shim.min.js"></script>
<script src="es5-sham.min.js"></script>
<![endif]-->
<script type="text/javascript" src="tcomb.js"></script>
<script type="text/javascript">
    console.log(t);
</script>

Tests

Run mocha or npm test in the project root.

The Idea

What's a type? In tcomb a type is a function T such that

1. T has signature T(value, [mut]) where value depends on the nature of T and the optional boolean mut makes the instance mutable (default false)
2. T is idempotent: T(T(value, mut), mut) === T(value, mut)
3. T owns a static function T.is(x) returning true if x is an instance of T

Note: 2. implies that T can be used as a default JSON decoder

Api

options

options.onFail

In production envs you don't want to leak failures to the user

// override onFail hook
options.onFail = function (message) {
    try {
        // capture stack trace
        throw new Error(message);
    } catch (e) {
        // use you favourite JavaScript error logging service
        console.log(e.stack);
    }
};

options.update

Adds to structs, tuples, lists and dicts a static method update that returns a new instance without modifying the original.

Example

// see http://facebook.github.io/react/docs/update.html
options.update = function (x, updates) {
  return React.addons.update(mixin({}, x), updates);
};
var p1  = Point({x: 0, y: 0});
var p2 = Point.update(p1, {x: {$set: 1}}); // => Point({x: 1, y: 0})

assert

assert(guard, [message], [values...]);

If guard !== true the debugger kicks in.

• guard boolean condition
• message optional string useful for debugging, formatted with values like util.format in Node

Example

assert(1 === 2); // throws 'assert(): failed'
assert(1 === 2, 'error!'); // throws 'error!'
assert(1 === 2, 'error: %s !== %s', 1, 2); // throws 'error: 1 !== 2'

To customize failure behaviour, see options.onFail.

structs

struct(props, [name])

Defines a struct like type.

• props hash name -> type
• name optional string useful for debugging

Example

"use strict";
  
// defines a struct with two numerical props
var Point = struct({
    x: Num,
    y: Num
});
  
// methods are defined as usual
Point.prototype.toString = function () {
    return '(' + this.x + ', ' + this.y + ')';
};
  
// costructor usage, p is immutable
var p = Point({x: 1, y: 2});
  
p.x = 2; // => TypeError
  
p = Point({x: 1, y: 2}, true); // now p is mutable
  
p.x = 2; // ok

is(x)

Returns true if x is an instance of the struct.

Point.is(p); // => true

unions

union(types, [name])

Defines a union of types.

• types array of types
• name optional string useful for debugging

Example

var Circle = struct({
    center: Point,
    radius: Num
});
  
var Rectangle = struct({
    bl: Point, // bottom left vertex
    tr: Point  // top right vertex
});
  
var Shape = union([
    Circle, 
    Rectangle
]);

is(x)

Returns true if x belongs to the union.

Shape.is(Circle({center: p, radius: 10})); // => true

maybe

maybe(type, [name])

Same as union([Nil, type]).

// the value of a radio input where null = no selection
var Radio = maybe(Str);
  
Radio.is('a');     // => true
Radio.is(null);    // => true
Radio.is(1);       // => false

enums

enums(map, [name])

Defines an enum of strings.

• map hash enum -> value
• name optional string useful for debugging

Example

var Direction = enums({
    North: 'North', 
    East: 'East',
    South: 'South', 
    West: 'West'
});

is(x)

Returns true if x belongs to the enum.

Direction.is('North'); // => true

enums.of(keys, [name])

Returns an enums of an array of keys, useful when you don't mind to define custom values for the enums.

• keys array (or string) of keys
• name optional string useful for debugging

Example

// result is the same as the main example
var Direction = enums.of(['North', 'East', 'South', 'West']);
  
// or..
Direction = enums.of('North East South West');

tuples

tuple(types, [name])

Defines a tuple whose coordinates have the specified types.

• types array of coordinates types
• name optional string useful for debugging

Example

var Area = tuple([Num, Num]);
  
// constructor usage, area is immutable
var area = Area([1, 2]);

is(x)

Returns true if x belongs to the tuple.

Area.is([1, 2]);      // => true
Area.is([1, 'a']);    // => false, the second element is not a Num
Area.is([1, 2, 3]);   // => false, too many elements

subtypes

subtype(type, predicate, [name])

Defines a subtype of an existing type.

• type the supertype
• predicate a function with signature (x) -> boolean
• name optional string useful for debugging

Example

// points of the first quadrant
var Q1Point = subtype(Point, function (p) {
    return p.x >= 0 && p.y >= 0;
});
  
// costructor usage, p is immutable
var p = Q1Point({x: 1, y: 2});
  
p = Q1Point({x: -1, y: -2}); // => fail!

Note. You can't add methods to Q1Point prototype, add them to the supertype prototype if needed.

is(x)

Returns true if x belongs to the subtype.

var Int = subtype(Num, function (n) {
    return n === parseInt(n, 10);
});
  
Int.is(2);      // => true
Int.is(1.1);    // => false

lists

list(type, [name])

Defines an array where all the elements are of type T.

• type type of all the elements
• name optional string useful for debugging

Example

var Path = list(Point);
  
// costructor usage, path is immutable
var path = Path([
    {x: 0, y: 0}, 
    {x: 1, y: 1}
]);

is(x)

Returns true if x belongs to the list.

var p1 = Point({x: 0, y: 0});
var p2 = Point({x: 1, y: 2});
Path.is([p1, p2]); // => true

dicts

dict(type, [name])

Defines a dictionary Str -> type.

• type the type of the values
• name optional string useful for debugging

Example

// defines a dictionary of numbers
var Tel = dict(Num);

is(x)

Returns true if x is an instance of the dict.

Tel.is({'jack': 4098, 'sape': 4139}); // => true

functions

func(Arguments, f, [Return], [name])

Defines a function where the arguments and the return value are checked.

• Arguments the type of arguments (can be a list of types)
• f the function to execute
• Return optional, check the type of the return value
• name optional string useful for debugging

Example

var sum = func([Num, Num], function (a, b) {
    return a + b;
}, Num);
  
sum(1, 2); // => 3
sum(1, 'a'); // => fail!

Macros

Experimental. I added a tcomb.sjs file containing some sweet.js macros, here some examples:

// structs
type Point struct {
  x: Num,
  y: Num
}

// unions
type Shape union {
  Circle,
  Rectangle
}

// tuples
type Coords tuple {
  Num,
  Num
}

// enums
type Direction enums {
  'North', 
  'East',
  'South', 
  'West'
}

// enums with specified values 
type Direction enums {
  'North': 0, 
  'East': 1,
  'South': 2, 
  'West': 3
}

// subtypes
type Positive subtype<Num> n {
  return n > 0;
}

// irriducibles types, like JavaScript primitives
type Irriducible irriducible x {
  return typeof x === 'function';
}

// maybe
type Maybe maybe<Str>

// lists
type List list<Str>

// dictionaries
type Dict dict<Str>

// functions
fn add (x: Num, y: Num) {
    return x + y;
}

// functions with checked return value
fn add (x: Num, y: Num) -> Num {
    return x + y;
}

Articles on tcomb

• What if your domain model could validate the UI for free?
• JSON Deserialization Into An Object Model
• JSON API Validation In Node.js

Contribution

If you do have a contribution for the package feel free to put up a Pull Request or open an Issue.

License (MIT)

The MIT License (MIT)

Copyright (c) 2014 Giulio Canti

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.