babel-plugin-flow-runtime

Babel Plugin Flow Runtime

A babel plugin which transforms Flow annotations into Type instances available at runtime, and optionally checks values against those types.

Supports all of flow's syntax, aims for full compatibilty with flow, found a bug? Please report it.

What?

Turns code like this:

type User = {
  id: number;
  name: string;
};

Into code like this:

import t from 'flow-runtime';
const User = t.type('User', t.object(
  t.property('id', t.number()),
  t.property('name', t.string())
));

Which you can then use like this:

User.assert({id: 123, name: 'Sally'}); // ok
User.assert({id: false, name: 'Bob'}); // throws

Installation

This plugin has a runtime dependency on flow-runtime, so make sure you install that along with this package:

npm install --save-dev babel-plugin-flow-runtime
npm install --save flow-runtime

Next, add the following to your babel configuration or .babelrc:

{
  "plugins": [["flow-runtime", {
    "assert": true,
    "annotate": true
  }]]
}

Options

The plugin supports the following options:

• assert - Boolean, indicates whether types should be asserted at runtime. Defaults to true if process.env.NODE_ENV === 'development', otherwise false.
• annotate - Boolean, indicates whether object or function values that have type annotations should be decorated with those types at runtime. Defaults to true.
• libraryName - String, indicates which runtime to use. Defaults to flow-runtime

If assert is true, the following code:

const add = (a: number, b: number): number => a + b;

will be transformed into:

import t from 'flow-runtime';
const add = (a, b) => {
  let _aType = t.number();
  let _bType = t.number();
  const _returnType = t.return(t.number());
  t.param('a', _aType).assert(a);
  t.param('b', _bType).assert(b);
  return _returnType.assert(a + b);
};

Which is very safe, and can be very useful during development, but has a non-trivial performance overhead. It's usually a good idea to disable this feature in production.

If annotate is true, the following:

const add = (a: number, b: number): number => a + b;

will be transformed into:

import t from 'flow-runtime';
const add = t.annotate(
  (a, b) => a + b,
  t.function(
    t.param('a', t.number()),
    t.param('b', t.number()),
    t.return(t.number())
  )
);

Now invoking add(x, y) does not incur any overhead, as the parameters are not checked, but the type information is preserved and available for inspection:

console.log(String(t.typeOf(add))); // (a: number, b: number) => number

If both assert and annotate are false then value annotations are ignored, but type aliases are still transformed:

type User = {
  id: number;
  name: string;
};

turns into:

import t from 'flow-runtime';
const User = t.type('User', t.object(
  t.property('id', t.number()),
  t.property('name', t.string())
));

React Prop Types

When the plugin encounters a React component with a props type annotation, the annotation is converted to react prop types:

import React from 'react';

type Props = {
  name: string;
};

export class App extends React.Component<void, Props, void> {
  render () {
    return <h1>{this.props.name}</h1>;
  }
}

Becomes

import t from 'flow-runtime';
import React from 'react';

const Props = t.type('Props', t.object(
  t.property('name', t.string())
));

export class App extends React.Component {
  static propTypes = t.propTypes(Props);
  render () {
    return <h1>{this.props.name}</h1>;
  }
}