Repository files navigation

"Si vis pacem, para bellum" - (Vegetius 5th century)

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

You may want to check outio-ts

tcomb is supposed to be used indevelopment and isdisabled in production.If you want type checks in production you may use

• tcomb-validation
• io-ts

npm install tcomb --save

Code example

A type-checked function:

importtfrom'tcomb';functionsum(a,b){t.Number(a);t.Number(b);returna+b;}sum(1,'s');// throws '[tcomb] Invalid value "s" supplied to Number'// using babel-plugin-tcombfunctionsum(a:number,b:number){returna+b;}

A user defined type:

constInteger=t.refinement(t.Number,(n)=>n%1===0,'Integer');

A type-checked class:

constPerson=t.struct({name:t.String,// required stringsurname:t.maybe(t.String),// optional stringage:t.Integer,// required integertags:t.list(t.String)// a list of strings},'Person');// methods are defined as usualPerson.prototype.getFullName=function(){return`${this.name}${this.surname}`;};constperson=Person({surname:'Canti'});// throws '[tcomb] Invalid value undefined supplied to Person/name: String'

Chrome DevTools:

• API
• A little guide to runtime type checking and runtime type introspection (Work in progress)

Lightweight

3KB gzipped, no dependencies.

Type safety

All models defined withtcomb are type-checked.

Note. Instancesare not boxed, this means thattcomb works great with lodash, Ramda, etc. And you can of course use them as props to React components.

Based on set theory

• Blog post:JavaScript, Types and Sets - Part I
• Blog post:JavaScript, Types and Sets - Part II

Domain Driven Design

Write complex domain models in a breeze and with a small code footprint. Supported types / combinators:

• user defined types
• structs
• lists
• enums
• refinements
• unions
• intersections
• the option type
• tuples
• dictionaries
• functions
• recursive and mutually recursive types
• interfaces

Immutability and immutability helpers

Instances are immutable usingObject.freeze. This means you can use standard JavaScript objects and arrays. You don't have to change how you normally code. You can update an immutable instance with the providedupdate(instance, spec) function:

constperson2=Person.update(person,{name:{$set:'Guido'}});

wherespec is an object containingcommands. The following commands are compatible with theFacebook Immutability Helpers:

• $push
• $unshift
• $splice
• $set
• $apply
• $merge

SeeUpdating immutable instances for details.

Speed

Object.freeze calls and asserts are executed only in development and stripped out in production (usingprocess.env.NODE_ENV !== 'production' tests).

Runtime type introspection

All models are inspectable at runtime. You can read and reuse the information stored in your types (in themeta static member). SeeThe meta object in the docs for details.

Libraries exploiting tcomb's RTI:

• tcomb-validation
• tcomb-form
• Blog post:JSON API Validation In Node.js

Easy JSON serialization / deserialization

Encodes / decodes your domain models to / from JSON for free.

• Blog post:JSON Deserialization Into An Object Model

Debugging with Chrome DevTools

You can customize the behavior when an assert fails leveraging the power of Chrome DevTools.

// use the default...t.fail=functionfail(message){thrownewTypeError('[tcomb] '+message);// set "Pause on exceptions" on the "Sources" panel for a great DX};// .. or define your own behaviort.fail=functionfail(message){console.error(message);};

Pattern matching

constresult=t.match(1,t.String,()=>'a string',t.Number,()=>'a number');console.log(result);// => 'a number'

Babel plugin

Usingbabel-plugin-tcomb you can also write (Flow compatible) type annotations:

functionsum(a:number,b:number):number{returna+b;}

TypeScript definition file

index.d.ts

• Giulio Canti maintainer
• Becky Conningfunc combinator ideas and documentation
• Andrea Lattuadadeclare combinator

git clone git@github.com:gcanti/tcomb.gitcd tcombnpm installnpm run dist

Will output 2 files:

• dist/tcomb.js (development)
• dist/tcomb.min.js (production)Object.freeze calls and asserts stripped out

• tcomb-doc Documentation tool for tcomb
• tcomb-validation Validation library based on type combinators
• tcomb-json-schema Transforms a JSON Schema to a tcomb type
• reactuate React/Redux stack (not a boilerplate kit)
• tcomb-react Alternative syntax for PropTypes
• mongorito-tcomb Bring schema validation to Mongorito thanks to tcomb
• tcomb-form Forms library for react
• tcomb-form-types Adds Types/Validations to tcomb-form
• tcomb-form-native Forms library for react-native
• tcomb-generate Generates random data by tcomb type for property-based testing
• tcomb-additional-types Provides additional predefined types for your existing tcomb setup
• tcomb-builder An immutable syntax for defining tcomb types and forms

• typed-immutable
• immu
• immutable
• mori
• seamless-immutable
• deep-freeze
• freezer
• icedam
• ObjectModel
• rfx

The MIT License (MIT)