Home

Awesome

flotate

A portmanteau of flow and annotate, allows using the Flow type checker with standard JavaScript syntax, through inline annotation comments.

Build Status

.

.

.

.

.

IMPORTANT NOTE: As of Flow 0.4.0, the flotate syntax has been merged upstream into Flow itself, rendering this preprocessor unnecessary. Thanks to everyone who showed interest and support!

.

.

.

.

.

Introduction

Flow implements many useful type checks, but also requires you to opt into a custom JavaScript syntax. This in turn makes it hard to use many other useful tools (such as linters, preprocessors, etc) which assume standards compliant JavaScript. So instead of writing:

/* @flow */
function foo(x: string, y: number): boolean {
    return x.length * y === 5;
}
foo('Hello', 42);

...you can add the same type annotations with comments, either inline, in the exact positions Flow would have them:

/* @flow */
function foo(x /*: string */, y /*: number */) /*: boolean */ {
    return x.length * y === 5;
}
foo('Hello', 42);

...or immediately preceding an annotated function, to keep annotations and code separate:

/* @flow */
/*: (x: string, y: number): boolean */
function foo(x, y) {
    return x.length * y === 5;
}
foo('Hello', 42);

It's win-some-lose-some: you lose by having to type a bit more, but win by keeping your code interoperable. Whether that's a good ROI for you will vary. That said, you don't have to bring in Flow in one go: you can add annotations to a few modules here and there, and see how it works out. With flotate, you can do that evaluation without big commitments (say, to a non-standard JavaScript syntax).

The CLI tool aims to be a drop-in-compatible subset of the flow commands, e.g. flow check becomes flotate check, but otherwise works the same. Only the check command is currently supported, but starting a background server should be added in an upcoming release.

There's a related issue reported to Flow which was both an inspiration and a good problem statement.

Installation

First get Flow, then install through npm as per usual:

$ npm install -g flotate

Annotations

flotate defines 5 annotation types:

Examples

The following demonstrates how to use each annotation type, combined with an ES6 class definition.

/* @flow */

/*::
  type Message = {
    timestamp: number;
    payload: string;
  };
  type Messages = Array<Message>;
*/

class MessageStore {

  /*:: _msgs: Messages; */

  constructor() {
    this._msgs = [];
  }

  addMessages(newMessages /*: Message | Messages */) {
    this._msgs = this._msgs.concat(newMessages);
  }

}

var ms = new MessageStore();

/*flow-ignore-begin*/
ms.addMessages = function() {
  console.log('addMessages() called with', arguments);
  MessageStore.prototype.addMessages.apply(ms, arguments);
};
/*flow-ignore-end*/

ms.addMessages({
  payload: "Hello world!"
});

Some things worth pointing out:

Attempting to type-check this will give us errors:

$ flotate check .

/path/to/demo.js:4:17,7:2: property timestamp
Property not found in
  /path/to/demo.js:34:16,36:1: object literal

/path/to/demo.js:34:16,36:1: object literal
This type is incompatible with
  /path/to/demo.js:8:18,31: array type

/path/to/demo.js:34:16,36:1: object literal
This type is incompatible with
  /private/var/folders/k0/vy40jfp93d538th2y4hkzt7c0000gp/T/flow_jara/flowlib_b553107/lib/core.js:120:28,35: array type

Found 3 errors

We can fix the issue by adding the missing mandatory property timestamp:

ms.addMessages({
  timestamp: Date.now(),
  payload: "Hello world!"
});

Now our module type-checks:

$ flotate check .

Found 0 errors

For completeness, the following is what the above code is translated to, before being handed off to Flow for analysis:

/* @flow */


  type Message = {
    timestamp: number;
    payload: string;
  };
  type Messages = Array<Message>;


class MessageStore {

  _msgs: Messages;

  constructor() {
    this._msgs = [];
  }

  addMessages(newMessages : Message | Messages ) {
    this._msgs = this._msgs.concat(newMessages);
  }

}

var ms = new MessageStore();

/*
ms.addMessages = function() {
  console.log('addMessages() called with', arguments);
  MessageStore.prototype.addMessages.apply(ms, arguments);
};
*/

ms.addMessages({
  timestamp: Date.now(),
  payload: "Hello world!"
});

Dockerfile

You can also run flotate without installing anything locally, given you already have Docker.

Building

$ docker build -t flotate

Running

$ docker run --rm -it -v $(pwd):/src:ro flotate check .

How it works

This tool is fundamentally just a simple pre-processor for Flow, and mostly a combination of excellent existing tools. When type-checking code, the following happens:

  1. Check for the presence of the .flowconfig file. It marks Flow "workspaces".
  2. Create a temporary path, that's automatically cleaned up on exit (with temp).
  3. Recursively copy all files in the workspace to the temporary path (with wrench).
  4. Update paths in the temporary copy of the .flowconfig file, so they point back to the original workspace. This is only needed for paths which reach outside the workspace (e.g. ../../node_modules), and reduces the need to copy things around.
  5. Look for all files in the temporary workspace marked with @flow, and transform the comment annotations to their Flow counterparts (with esprima and falafel).
  6. Invoke the relevant flow check on the temporary workspace.
  7. Output whatever flow outputs, and exit with whatever it exits with.
  8. Clean up.

Acknowledgements

This project is a grateful recipient of the Futurice Open Source sponsorship program.

You guys rule. :bow:

License

This projected is licensed under the terms of the MIT license.