Babel Typecheck
This is a Babel plugin for static and runtime type checking using flow type annotations.
Note: Now requires babel 6.1, babel 5 users see the 2.x branch.
What?
Turns code like this:
: boolean { return socket;}
into code like this:
{ var _socket$send; if !to instanceof User throw "Value of argument 'to' violates contract."; if typeof message !== "string" throw "Value of argument 'message' violates contract."; _socket$send = socket; if typeof _socket$send !== "boolean" throw "Function 'sendMessage' return value violates contract."; return _socket$send;}
And guards against some silly mistakes, for example the following code will fail to compile with a SyntaxError
, because the function can return the wrong type.
: boolean { if Math > 05 return "yes"; // <-- SyntaxError - string is not boolean else return false; } : string { // <-- SyntaxError: default value is not string return input + "456";}
Installation
First, install via npm.
npm install --save-dev babel-plugin-typecheck
Then, in your babel configuration (usually in your .babelrc
file), add "typecheck"
to your list of plugins:
The example configuration will disable typecheck when NODE_ENV=production
which is usually preferable for performance reasons.
Important: This plugin has a dependency on babel-plugin-syntax-flow
and babel-plugin-transform-flow-strip-types
.
Without syntax-flow
, babel will be unable to parse the flow annotation syntax.
Without transform-flow-strip-types
, the type annotations will be included in the output which will make it unparsable by JS engines.
If you are not already using the babel-preset-react
plugin, you must install those plugins and include them in your babel configuration (usually .babelrc
). Put them after typecheck
in the list, e.g.
If you are using babel-preset-react
you can ignore this warning.
Note Depending on your babel configuration you may encounter issues where typecheck interferes with other transformations. This can almost always be fixed by adjusting your preset order and setting
"passPerPreset": true
in your.babelrc
.
Examples
The basic format is similar to Flow Type Annotations.
Here are a few examples of annotations this plugin supports:
Importing and Exporting types.
You can reuse types across modules using an extension of the ES6 module syntax:
places.js:
;;
widget.js:
; // You can now use CsvDataType and LocationType just like any other type.
Note that in contrast to flow, an imported type must be an actual type and cannot be a class or other concrete value.
Optimization
In cases where typecheck can statically verify that the return value is of the correct type, no type checks will be inserted, for instance:
: string|Object { if Math > 05 return "yes"; else return message: "no" ; }
will produce no type checks at all, because we can trivially tell that the function can only return one of the two permitted types. This is also true for simple cases like:
: User { return ; // <-- no typecheck required}
This is currently quite limited though, as the plugin can only statically infer the types of literals and very simple expressions, it can't (yet) statically verify e.g. the result of a function call. In those cases a runtime type check is required:
: User { return User; // <-- produces runtime typecheck}
Changes in 3.5.0
Supports various number types:
- int8
- uint8
- int16
- uint16
- int32
- uint32
- float32
- float16
Example:
: uint16 { return input * input;} ; // ok; // ok; // ok; // TypeError; // TypeError; // TypeError; // TypeError
Changes in 3.0.0
Supports type aliases:
type Foo = string|number; : string { return input + ' world';} ; // ok; // ok; // fails
Better static type inference
: string[] { return ; // no return type check required, knows that makeArray is compatible} : string[] { return input;}
Type propagation
: User { const user = name: input; return user; // No check required, knows that user is the correct type}
Assignment tracking
let name: string = "bob"; name = "Bob"; // okname = ; // okname = 123; // SyntaxError, expected string not number : string { return "Sally";}
Type casting
let name: string = "bob"; name = "Bob";name: number = 123;name = 456;name = "fish"; // SyntaxError, expected number;
Array type parameters
: number { return inputlength;} ; // ok; // TypeError
Shape tracking
type User = name: string; email: string;; : string { return inputname;} ; // TypeError; // TypeError; // ok
Pragmas
Sometimes you might need to disable type checking for a particular file or section of code. To ignore an entire file, add a comment at the top level scope of the file:
// typecheck: ignore file: boolean { return input + ' nope';}
To ignore a particular statement:
let foo: string = "hello world";// typecheck: ignore statementfoo = 123;
Note: Because of how typecheck works, it's not possible to ignore individual lines, only entire statements or files. So if you ignore e.g. an if statement, the entire body of that statement will be ignored.
You can also control the disabling and enabling of type checking using the plugin options and the @typecheck
pragma. Type checking will be enabled only for files where any of the configured only
values are found in the @typecheck
pragma. With babel configuration:
"plugins": [
["typecheck", { only: ["production", "test"] }],
...
]
This file would have typechecks enabled
// @typecheck: production, some
Whereas this file would not:
// @typecheck: any, some
License
Published by codemix under a permissive MIT License, see LICENSE.md.