We are changing this behavior.

What is arity?​

A function's arity is the number of arguments it expects. Since some functions have optional parameters and some use rest parameters, we can define the minimum arity as the smallest number of arguments it expects and the maximum arity as the largest number of arguments it expects.

function no_args() {} // arity of 0
function two_args(a, b) {} // arity of 2
function optional_args(a, b?) {} // min arity of 1, max arity of 2
function many_args(a, ...rest) {} // min arity of 1, no max arity

Motivation​

Consider the following code:

function add(a, b) { return a + b; }
const sum = add(1, 1, 1, 1);

The author apparently thought the add() function adds up all its arguments, and that sum will have the value 4. However, only the first two arguments are summed, and sum actually will have the value 2. This is obviously a bug, so why doesn't JavaScript or Flow complain?

And while the error in the above example is easy to see, in real code it's often a lot harder to notice. For example, what is the value of total here:

const total = parseInt("10", 2) + parseFloat("10.1", 2);

"10" in base 2 is 2 in decimal and "10.1" in base 2 is 2.5 in decimal. So the author probably thought that total would be 4.5. However, the correct answer is 12.1. parseInt("10", 2) does evaluates to 2, as expected. However, parseFloat("10.1", 2) evaluates to 10.1. parseFloat() only takes a single argument. The second argument is ignored!

Why JavaScript allows extraneous arguments​

At this point, you might feel like this is just an example of JavaScript making terrible life decisions. However, this behavior is very convenient in a bunch of situations!

Callbacks​

If you couldn't call a function with more arguments than it handles, then mapping over an array would look like

const doubled_arr = [1, 2, 3].map((element, index, arr) => element * 2);

When you call Array.prototype.map, you pass in a callback. For each element in the array, that callback is invoked and passed 3 arguments:

1. The element
2. The index of the element
3. The array over which you're mapping

However, your callback often only needs to reference the first argument: the element. It's really nice that you can write

const doubled_arr = [1, 2, 3].map(element => element * 2);

Stubbing​

Sometimes I come across code like this

let log = () => {};
if (DEBUG) {
  log = (message) => console.log(message);
}
log("Hello world");

The idea is that in a development environment, calling log() will output a message, but in production it does nothing. Since you can call a function with more arguments than it expects, it is easy to stub out log() in production.

Variadic functions using arguments​

A variadic function is a function that can take an indefinite number of arguments. The old-school way to write variadic functions in JavaScript is by using arguments. For example

function sum_all() {
  let ret = 0;
  for (let i = 0; i < arguments.length; i++) { ret += arguments[i]; }
  return ret;
}
const total = sum_all(1, 2, 3); // returns 6

For all intents and purposes, sum_all appears like it takes no arguments. So even though it appears to have an arity of 0, it is convenient that we can call it with more arguments.

Changes to Flow​

We think we have found a compromise which catches the motivating bugs without breaking the convenience of JavaScript.

Calling a function​

If a function has a maximum arity of N, then Flow will start complaining if you call it with more than N arguments.

test:1
  1: const num = parseFloat("10.5", 2);
                                    ^ unused function argument
   19: declare function parseFloat(string: mixed): number;
                                  ^^^^^^^^^^^^^^^^^^^^^^^ function type expects no more than 1 argument. See lib: <BUILTINS>/core.js:19

Function subtyping​

Flow will not change its function subtyping behavior. A function with a smaller maximum arity is still a subtype of a function with a larger maximum arity. This allows callbacks to still work as before.

class Array<T> {
  ...
  map<U>(callbackfn: (value: T, index: number, array: Array<T>) => U, thisArg?: any): Array<U>;
  ...
}
const arr = [1,2,3].map(() => 4); // No error, evaluates to [4,4,4]

In this example, () => number is a subtype of (number, number, Array<number>) => number.

Stubbing and variadic functions​

This will, unfortunately, cause Flow to complain about stubs and variadic functions which are written using arguments. However, you can fix these by using rest parameters

let log (...rest) => {};

function sum_all(...rest) {
  let ret = 0;
  for (let i = 0; i < rest.length; i++) { ret += rest[i]; }
  return ret;
}

Rollout plan​

Flow v0.46.0 will ship with strict function call arity turned off by default. It can be enabled via your .flowconfig with the flag

experimental.strict_call_arity=true

Flow v0.47.0 will ship with strict function call arity turned on and the experimental.strict_call_arity flag will be removed.

Why turn this on over two releases?​

This decouples the switch to strict checking of function call arity from the release.

Why not keep the experimental.strict_call_arity flag?​

This is a pretty core change. If we kept both behaviors, we'd have to test that everything works with and without this change. As we add more flags, the number of combinations grows exponentially, and Flow's behavior gets harder to reason about. For this reason, we're choosing only one behavior: strict checking of function call arity.

What do you think?​

This change was motivated by feedback from Flow users. We really appreciate all the members of our community who take the time to share their feedback with us. This feedback is invaluable and helps us make Flow better, so please keep it coming!

The goal of this project is to grow an ecosystem of libdefs that allows Flow's type inference to shine and that aligns with Flow's mission: To extract precise and accurate types from real-world JavaScript. We've learned a lot from similar efforts like DefinitelyTyped for TypeScript and we want to bring some of the lessons we've learned to the Flow ecosystem.

Here are some of the objectives of this project:

• Libdefs should be versioned — both against the libraries they describe and against the version(s) of Flow they are compatible with.
• Libdefs should meet a high quality bar, including libdef tests to ensure that their quality persists over time.
• There must be a straightforward way to contribute libdef improvements over time and for developers to benefit from those improvements over time.
• The process of managing libdefs for a Flow project should be automated, simple, and easy to get right.

Versioned & Tested Libdefs​

Anyone can contribute a libdef (or improve on an existing one), but when doing so it's important that we maintain a high quality bar so that all developers feel confident in the libdefs they are using. To address this, flow-typed requires that all libdef contributions are explicitly versioned against both the version of the library they are describing and the version(s) of Flow the libdef is compatible with.

Additionally, all libdefs must be accompanied by tests that exercise the important parts of the API and assert that they yield the correct types. By including both version information and tests with each libdef, we can automatically verify in Travis that the tests work as expected for all versions of Flow a libdef is compatible with. Tests also help to ensure that future changes to the libdef don't regress its features over time.

Automating Libdef Installation​

We've built a simple CLI tool called flow-typed that helps to automate the process of finding, installing, and upgrading libdefs in your Flow projects. It uses the explicit version info associated with each libdef to find all necessary libdefs based on your project's package.json dependencies. This minimizes the work you need to do in order to pull in and update libdefs in your projects.

You can get the flow-typed CLI using either yarn (yarn global add flow-typed) or npm (npm install -g flow-typed).

Installing Libdefs​

Installing libdefs from the flow-typed repository is a matter of running a single command on your project after installing your dependencies:

> yarn install # Or `npm install` if you're old-school :)
> flow-typed install

The flow-typed install command reads your project's package.json file, queries the flow-typed repository for libdefs matching your dependencies, and installs the correctly-versioned libdefs into the flow-typed/ directory for you. By default, Flow knows to look in the flow-typed/ directory for libdefs — so there is no additional configuration necessary.

Note that it's necessary to run this command after running yarn or npm install. This is because this command will also generate stub libdefs for you if one of your dependencies doesn't have types.

Once libdefs have been installed, we recommend that you check them in to your project's repo. Libdefs in the flow-typed repository may be improved over time (fixing a bug, more precise types, etc). If this happens for a libdef that you depend on, you'll want to have control over when that update is applied to your project. Periodically you can run flow-typed update to download any libdef updates, verify that your project still typechecks, and the commit the updates.

Why Not Just Use Npm To Distribute Libdefs?​

Over time libdefs in the flow-typed repo may be updated to fix bugs, improve accuracy, or make use of new Flow features that better describe the types of the library. As a result, there are really 3 versions that apply to each libdef: The version of the library being described, the current version of the libdef in the flow-typed repo, and the version(s) of Flow the libdef is compatible with.

If an update is made to some libdef that you use in your project after you've already installed it, there's a good chance that update may find new type errors in your project that were previously unknown. While it is certainly a good thing to find errors that were previously missed, you'll want to have control over when those changes get pulled in to your project.

This is the reason we advise that you commit your installed libdefs to version control rather than rely on a system like npm+semver to download and install a non-deterministic semver-ranged version from npm. Checking in your libdefs ensures that all collaborators on your project have consistent output from Flow at any given commit in version history.

Building a Community​

This is first and foremost a community project. It was started by a community member (hey @splodingsocks!) and has already benefitted from hours of work by many others. Moreover, this will continue to be a community effort: Anyone can create and/or help maintain a libdef for any npm library. Authors may create libdefs for their packages when publishing, and/or consumers can create them when someone else hasn't already done so. Either way, everyone benefits!

We'd like to send a big shout-out to @marudor for contributing so many of his own libdefs and spending time helping others to write and contribute libdefs. Additionally we'd like to thank @ryyppy for helping to design and iterate on the CLI and installation workflow as well as manage libdef reviews.

The Flow core team intends to stay invested in developing and improving this project, but in order for it to truly succeed we need your help! If you've already written some libdefs for Flow projects that you work on, we encourage you to contribute them for others to benefit from them as well. By managing libdefs in a community-driven repository, the community as a whole can work together to extend Flow's capabilities beyond just explicitly-typed JS.

It's still early days and there's still a lot to do, so we're excited to hear your ideas/feedback and read your pull requests! :)

Happy typing!

• property variance,
• invariant-by-default dictionary types,
• covariant-by-default method types,
• and more flexible getters and setters.

What is Variance?​

Defining the subtype relationship between types is a core responsibility of Flow as a type system. These relationships are determined either directly for simple types or, for complex types, defined in terms of their parts.

Variance describes the subtyping relationship for complex types as it relates to the subtyping relationships of their parts.

For example, Flow directly encodes the knowledge that string is a subtype of ?string. Intuitively, a string type contains string values while a ?string type contains null, undefined, and also string values, so membership in the former naturally implies membership in the later.

The subtype relationships between two function types is not as direct. Rather, it is derived from the subtype relationships between the functions' parameter and return types.

Let's see how this works for two simple function types:

type F1 = (x: P1) => R1;
type F2 = (x: P2) => R2;

Whether F2 is a subtype of F1 depends on the relationships between P1 and P2 and R1 and R2. Let's use the notation B <: A to mean B is a subtype of A.

It turns out that F2 <: F1 if P1 <: P2 and R2 <: R1. Notice that the relationship for parameters is reversed? In technical terms, we can say that function types are "contravariant" with respect to their parameter types and "covariant" with respect to their return types.

Let's look at an example:

function f(callback: (x: string) => ?number): number {
  return callback("hi") || 0;
}

What kinds of functions can we pass to f? Based on the subtyping rule above, then we can pass a function whose parameter type is a supertype of string and whose return type is a subtype of ?number.

function g(x: ?string): number {
  return x ? x.length : 0;
}
f(g);

The body of f will only ever pass string values into g, which is safe because g takes at least string by taking ?string. Conversely, g will only ever return number values to f, which is safe because f handles at least number by handling ?number.

Input and Output​

One convenient way to remember when something is covariant vs. contravariant is to think about "input" and "output."

Parameters are in an input position, often called a "negative" position. Complex types are contravariant in their input positions.

Return is an output position, often called a "positive" position. Complex types are covariant in their output positions.

Property Invariance​

Just as function types are composed of parameter and return types, so too are object types composed of property types. Thus, the subtyping relationship between objects is derived from the subtyping relationships of their properties.

However, unlike functions which have input parameters and an output return, object properties can be read and written. That is, properties are both input and output.

Let's see how this works for two simple object types:

type O1 = {p: T1};
type O2 = {p: T2};

As with function types, whether O2 is a subtype of O1 depends on the relationship between its parts, T1 and T2.

Here it turns out that O2 <: O1 if T2 <: T1 and T1 <: T2. In technical terms, object types are "invariant" with respect to their property types.

Let's look at an example:

function f(o: {p: ?string}): void {
  // We can read p from o
  let len: number;
  if (o.p) {
    len = o.p.length;
  } else {
    len = 0;
  }

  // We can also write into p
  o.p = null;
}

What kinds of objects can we pass into f, then? If we try to pass in an object with a subtype property, we get an error:

var o1: {p: string} = {p: ""};
f(o1);

function f(o: {p: ?string}) {}
                   ^ null. This type is incompatible with
var o1: {p: string} = {p: ""};
            ^ string
function f(o: {p: ?string}) {}
                   ^ undefined. This type is incompatible with
var o1: {p: string} = {p: ""};
            ^ string

Flow has correctly identified an error here. If the body of f writes null into o.p, then o1.p would no longer have type string.

If we try to pass an object with a supertype property, we again get an error:

var o2: {p: ?(string|number)} = {p: 0};
f(o2);

var o1: {p: ?(string|number)} = {p: ""};
                     ^ number. This type is incompatible with
function f(o: {p: ?string}) {}
                   ^ string

Again, Flow correctly identifies an error, because if f tried to read p from o, it would find a number.

Property Variance​

So objects have to be invariant with respect to their property types because properties can be read from and written to. But just because you can read and write, doesn't mean you always do.

Consider a function that gets the length of an nullable string property:

function f(o: {p: ?string}): number {
  return o.p ? o.p.length : 0;
}

We never write into o.p, so we should be able to pass in an object where the type of property p is a subtype of ?string. Until now, this wasn't possible in Flow.

With property variance, you can explicitly annotate object properties as being covariant and contravariant. For example, we can rewrite the above function:

function f(o: {+p: ?string}): number {
  return o.p ? o.p.length : 0;
}

var o: {p: string} = {p: ""};
f(o); // no type error!

It's crucial that covariant properties only ever appear in output positions. It is an error to write to a covariant property:

function f(o: {+p: ?string}) {
  o.p = null;
}

o.p = null;
^ object type. Covariant property `p` incompatible with contravariant use in
o.p = null;
^ assignment of property `p`

Conversely, if a function only ever writes to a property, we can annotate the property as contravariant. This might come up in a function that initializes an object with default values, for example.

function g(o: {-p: string}): void {
  o.p = "default";
}
var o: {p: ?string} = {p: null};
g(o);

Contravariant properties can only ever appear in input positions. It is an error to read from a contravariant property:

function f(o: {-p: string}) {
  o.p.length;
}

o.p.length;
^ object type. Contravariant property `p` incompatible with covariant use in
o.p.length;
^ property `p`

Invariant-by-default Dictionary Types​

The object type {[key: string]: ?number} describes an object that can be used as a map. We can read any property and Flow will infer the result type as ?number. We can also write null or undefined or number into any property.

In Flow 0.33 and earlier, these dictionary types were treated covariantly by the type system. For example, Flow accepted the following code:

function f(o: {[key: string]: ?number}) {
  o.p = null;
}
declare var o: {p: number};
f(o);

This is unsound because f can overwrite property p with null. In Flow 0.34, dictionaries are invariant, like named properties. The same code now results in the following type error:

function f(o: {[key: string]: ?number}) {}
                               ^ null. This type is incompatible with
declare var o: {p: number};
                   ^ number
function f(o: {[key: string]: ?number}) {}
                               ^ undefined. This type is incompatible with
declare var o: {p: number};
                   ^ number

Covariant and contravariant dictionaries can be incredibly useful, though. To support this, the same syntax used to support variance for named properties can be used for dictionaries as well.

function f(o: {+[key: string]: ?number}) {}
declare var o: {p: number};
f(o); // no type error!

Covariant-by-default Method Types​

ES6 gave us a shorthand way to write object properties which are functions.

var o = {
  m(x) {
    return x * 2
  }
}

Flow now interprets properties which use this shorthand method syntax as covariant by default. This means it is an error to write to the property m.

If you don't want covariance, you can use the long form syntax:

var o = {
  m: function(x) {
    return x * 2;
  }
}

More Flexible Getters and Setters​

In Flow 0.33 and earlier, getters and setters had to agree exactly on their return type and parameter type, respectively. Flow 0.34 lifts that restriction.

This means you can write code like the following:

// @flow
declare var x: string;

var o = {
  get x(): string {
    return x;
  },
  set x(value: ?string) {
    x = value || "default";
  }
}


Getting Flow working on Windows was not easy, and it was made possible by the hard work of Grégoire, Çagdas and Fabrice from OCamlPro.

Getting Started with Windows​

Getting Started with flow-bin on Windows​

Does your JavaScript project use npm to manage dependencies? Well, then the easiest way for you to install Flow is with npm! Just run

> npm install --save-dev flow-bin

(Note: on Windows, it is recommended to use npm v3, to avoid the long node_modules paths that npm v2 creates)

This will install the flow-bin npm package and automatically add it to your package.json. Once installed, there are a few ways to use the Flow binary. One is to use ./node_modules/.bin/flow directly. For example, every Flow project needs a .flowconfig file in the root directory. If you don't already have a .flowconfig, you could create it with Powershell, like

> New-Item .flowconfig

or you could run the flow init command, using ./node_modules/.bin/flow

> ./node_modules/.bin/flow init

Another way to run Flow is via an npm script. In your package.json file, there is a "scripts" section. Maybe it looks like this:

"scripts": {
  "test": "make test"
}

You can run the Flow binary directly from a script by referencing flow in a script, like so:

"scripts": {
  "test": "make test",
  "flow_check": "flow check || exit 0"
}

and then running that script via npm run

> npm run flow_check

(Note: the || exit 0 part of the script is optional, but npm run will show an error message if the script finishes with a non-zero exit code)

You can also install flow-bin globally with

> npm install --global flow-bin

Getting Started with flow.exe​

Each GitHub release of Flow starting with v0.30.0 will have a zipped Windows binary. For example, the v0.30.0 release includes flow-win64-v0.30.0.zip. If you download and unzip that, you will find a flow/ directory, which contains flow.exe. flow.exe is the Flow binary, so if you put that somewhere in your path, and you should be good to go.

> mkdir demo
> cd demo
> flow.exe init
> "/* @flow */ var x: number = true;" | Out-File -Encoding ascii test.js
> flow.exe check
test.js:1
  1: /* @flow */ var x: number = true;
                                 ^^^^ boolean. This type is incompatible with

  1: /* @flow */ var x: number = true;
                        ^^^^^^ number

Before Flow 0.28, the implementation of union/intersection types had serious bugs and was the root cause of a lot of weird behaviors you may have run into with Flow in the past. These bugs have now been addressed in a diff landing in 0.28.

As you might expect after a major rewrite of a tricky part of the type system implementation, there will be a short period of adjustment: you may run into kinks that we will try to iron out promptly, and you may run into some unfamiliar error messages.

New Error Messages​

<error location> Could not decide which case to select
<location of union/intersection type>

  Case 1 may work:
  <location of 1st case of union/intersection type>

  But if it doesn't, case 2 looks promising too:
  <location of 2nd case of union/intersection type>

  Please provide additional annotation(s) to determine whether case 1 works
  (or consider merging it with case 2):
  <location to annotate>
  <location to annotate>
  ...

What this means is that at <error location>, Flow needs to make a choice: one of the members of the union/intersection type at <location of union/intersection type> must be applied, but Flow can't choose safely based on available information. In particular, it cannot decide between case 1 and 2, so Flow lists a bunch of annotations that can help it disambiguate the two cases.

Actions Needed​

You can fix the errors in two ways:

• Actually go and annotate the listed locations. This should be by far the most common fix.
• Discover that there is real, unintentional ambiguity between case 1 and 2, and rewrite the two cases in the union type to remove the ambiguity. When this happens, typically it will fix a large number of errors.

There are two more possibilities, however:

• There's no real ambiguity and Flow is being too conservative / dumb. In this case, go ahead and do the annotations anyway and file an issue on GitHub. We plan to do a lot of short-term follow-up work to disambiguate more cases automatically, so over time you should see less of (3).
• You have no idea what's going on. The cases being pointed to don't make sense. They don't correspond to what you have at <error location>. Hopefully you won't run into (4) too often, but if you do please file an issue, since this means there are still latent bugs in the implementation.

If you file an issue on GitHub, please include code to reproduce the issue. You can use Try Flow to share your repro case easily.

If you're curious about the whys and hows of these new error messages, here's an excerpt from the commit message of the "fate of the union" diff:

Problem​

Flow's inference engine is designed to find more errors over time as constraints are added...but it is not designed to backtrack. Unfortunately, checking the type of an expression against a union type does need backtracking: if some branch of the union doesn't work out, the next branch must be tried, and so on. (The same is true for checks that involve intersection types.)

The situation is further complicated by the fact that the type of the expression may not be completely known at the point of checking, so that a branch that looks promising now might turn out to be incorrect later.

Solution​

The basic idea is to delay trying a branch until a point where we can decide whether the branch will definitely fail or succeed, without further information. If trying a branch results in failure, we can move on to the next branch without needing to backtrack. If a branch succeeds, we are done. The final case is where the branch looks promising, but we cannot be sure without adding constraints: in this case we try other branches, and bail when we run into ambiguities...requesting additional annotations to decide which branch to select. Overall, this means that (1) we never commit to a branch that might turn out to be incorrect and (2) can always select a correct branch (if such exists) given enough annotations.

JSX Intrinsics​

If you're writing JSX, it's probably a mix of your own React Components and some intrinsics. For example, you might write

render() {
  return <div><FluffyBunny name="Fifi" /></div>;
}

In this example, FluffyBunny is a React Component you wrote and div is a JSX intrinsic. Lower-cased JSX elements are assumed to be intrinsics by React and by Flow. Up until Flow v0.21.0, Flow ignored intrinsics and gave them the type any. This meant Flow let you set any property on JSX intrinsics. Flow v0.21.0 will, by default, do the same thing as v0.20.0, However now you can also configure Flow to properly type your JSX intrinsics!

Example of how to use JSX intrinsics​

.flowconfig

[libs]
myLib.js

myLib.js

// JSXHelper is a type alias to make this example more concise.
// There's nothing special or magic here.
// JSXHelper<{name: string}> is a React component
// with the single string property "name", which has a default
type JSXHelper<T> = Class<ReactComponent<T,T,mixed>>;

// $JSXIntrinsics is special and magic.
// This declares the types for `div` and `span`
type $JSXIntrinsics = {
  div: JSXHelper<{id: string}>,
  span: JSXHelper<{id: string, class: string}>,
};

myCode.js

<div id="asdf" />; // No error
<div id={42} />; // Error: `id` prop is a string, not a number!

What is going on here?​

The new bit of magic is this $JSXIntrinsics type alias. When Flow sees <foo /> it will look to see if $JSXIntrinsics exists and if so will grab the type of $JSXIntrinsics['foo']. It will use this type to figure out which properties are available and need to be set.

We haven't hardcoded the intrinsics into Flow since the available intrinsics will depend on your environment. For example, React native would have different intrinsics than React for the web would.

Smarter string refinements​

One of the main ways that we make Flow smarter is by teaching it to recognize more ways that JavaScript programmers refine types. Here's an example of a common way to refine nullable values:

class Person {
  name: ?string;
  ...
  getName(): string {
    // Before the if, this.name could be null, undefined, or a string
    if (this.name != null) {
      // But now the programmer has refined this.name to definitely be a string
      return this.name;
    }
    // And now we know that this.name is null or undefined.
    return 'You know who';
  }
}

New string refinements​

In v0.21.0, one of the refinements we added is the ability to refine types by comparing them to strings.

This is useful for refining unions of string literals into string literals

function test(x: 'foo' | 'bar'): 'foo' {
  if (x === 'foo') {
    // Now Flow understands that x has the type 'foo'
    return x;
  } else {
    return 'foo';
  }
}

And can also narrow the value of strings:

function test(x: string): 'foo' {
  if (x === 'foo') {
    // Now Flow knows x has the type 'foo'
    return x;
  } else {
    return 'foo';
  }
}

This is one of the many refinements that Flow currently can recognize and follow, and we'll keep adding more! Stay tuned!

@noflow​

Flow is opt-in by default (you add @flow to a file). However we noticed that sometimes people would add Flow annotations to files that were missing @flow. Often, these people didn't notice that the file was being ignored by Flow. So we decided to stop allowing Flow syntax in non-Flow files. This is easily fixed by adding either @flow or @noflow to your file. The former will make the file a Flow file. The latter will tell Flow to completely ignore the file.

Declaration files​

Files that end with .flow are now treated specially. They are the preferred provider of modules. That is if both foo.js and foo.js.flow exist, then when you write import Foo from './foo', Flow will use the type exported from foo.js.flow rather than foo.js.

We imagine two main ways people will use .flow files.

1. As interface files. Maybe you have some library coolLibrary.js that is really hard to type with inline Flow types. You could put coolLibrary.js.flow next to it and declare the types that coolLibrary.js exports.

   // coolLibrary.js.flow
   declare export var coolVar: number;
   declare export function coolFunction(): void;
   declare export class coolClass {}
   

2. As the original source. Maybe you want to ship the minified, transformed version of awesomeLibrary.js, but people who use awesomeLibrary.js also use Flow. Well you could do something like

   cp awesomeLibraryOriginalCode.js awesomeLibrary.js.flow
   babel awesomeLibraryOriginalCode --out-file awesomeLibrary.js
   

Order of precedence for lib files​

Now your local lib files will override the builtin lib files. Is one of the builtin flow libs wrong? Send a pull request! But then while you're waiting for the next release, you can use your own definition! The order of precedence is as follows:

1. Any paths supplied on the command line via --lib
2. The files found in the paths specified in the .flowconfig [libs] (in listing order)
3. The Flow core library files

For example, if I want to override the builtin definition of Array and instead use my own version, I could update my .flowconfig to contain

// .flowconfig
[libs]
myArray.js

// myArray.js
declare class Array<T> {
  // Put whatever you like in here!
}

Deferred initialization​

Previously the following code was an error, because the initialization of myString happens later. Now Flow is fine with it.

function foo(someFlag: boolean): string {
  var myString:string;
  if (someFlag) {
    myString = "yup";
  } else {
    myString = "nope";
  }
  return myString;
}

So much wonderful material has already been produced describing generators. I am going to focus on the interaction of static typing with generators. Please refer to the following materials for information about generators:

• Jafar Husain gave an incredibly lucid and well-illustrated talk that covers generators. I have linked to the point where he gets into generators, but I highly recommend the entire talk.
• Exploring ES6, a comprehensive book by Axel Rauschmayer, who has generously made the contents available for free online, has a chapter on generators.
• The venerable MDN has a useful page describing the Iterator interface and generators.

In Flow, the Generator interface has three type parameters: Yield, Return, and Next. Yield is the type of values which are yielded from the generator function. Return is the type of the value which is returned from the generator function. Next is the type of values which are passed into the generator via the next method on the Generator itself. For example, a generator value of type Generator<string,number,boolean> will yield strings, return a number, and will receive booleans from its caller.

For any type T, a Generator<T,void,void> is both an Iterable<T> and an Iterator<T>.

The unique nature of generators allows us to represent infinite sequences naturally. Consider the infinite sequence of natural numbers:

function *nats() {
  let i = 0;
  while (true) {
    yield i++;
  }
}

Because generators are also iterators, we can manually iterate the generator:

const gen = nats();
console.log(gen.next()); // { done: false, value: 0 }
console.log(gen.next()); // { done: false, value: 1 }
console.log(gen.next()); // { done: false, value: 2 }

When done is false, value will have the generator's Yield type. When done is true, value will have the generator's Return type or void if the consumer iterates past the completion value.

function *test() {
  yield 1;
  return "complete";
}
const gen = test();
console.log(gen.next()); // { done: false, value: 1 }
console.log(gen.next()); // { done: true, value: "complete" }
console.log(gen.next()); // { done: true, value: undefined }

Because of this behavior, manually iterating poses typing difficulties. Let's try to take the first 10 values from the nats generator through manual iteration:

const gen = nats();
const take10: number[] = [];
for (let i = 0; i < 10; i++) {
  const { done, value } = gen.next();
  if (done) {
    break;
  } else {
    take10.push(value); // error!
  }
}

test.js:13
 13:   const { done, value } = gen.next();
                               ^^^^^^^^^^ call of method `next`
 17:     take10.push(value); // error!
                     ^^^^^ undefined. This type is incompatible with
 11: const take10: number[] = [];
                   ^^^^^^ number

Flow is complaining that value might be undefined. This is because the type of value is Yield | Return | void, which simplifies in the instance of nats to number | void. We can introduce a dynamic type test to convince Flow of the invariant that value will always be number when done is false.

const gen = nats();
const take10: number[] = [];
for (let i = 0; i < 10; i++) {
  const { done, value } = gen.next();
  if (done) {
    break;
  } else {
    if (typeof value === "undefined") {
      throw new Error("`value` must be a number.");
    }
    take10.push(value); // no error
  }
}

There is an open issue which would make the dynamic type test above unnecessary, by using the done value as a sentinel to refine a tagged union. That is, when done is true, Flow would know that value is always of type Yield and otherwise of type Return | void.

Even without the dynamic type test, this code is quite verbose and it's hard to see the intent. Because generators are also iterable, we can also use for...of loops:

const take10: number[] = [];
let i = 0;
for (let nat of nats()) {
  if (i === 10) break;
  take10.push(nat);
  i++;
}

That's much better. The for...of looping construct ignores completion values, so Flow understands that nat will always be number. Let's generalize this pattern further using generator functions:

function *take<T>(n: number, xs: Iterable<T>): Iterable<T> {
  if (n <= 0) return;
  let i = 0;
  for (let x of xs) {
    yield x;
    if (++i === n) return;
  }
}

for (let n of take(10, nats())) {
  console.log(n); // 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
}

Note that we explicitly annotated the parameters and return type of the take generator. This is necessary to ensure Flow understands the fully generic type. This is because Flow does not currently infer a fully generic type, but instead accumulates lower bounds, resulting in a union type.

function identity(x) { return x }
var a: string = identity(""); // error
var b: number = identity(0);  // error

The above code produces errors because Flow adds string and number as lower bounds to the type variable describing the type of the value bound by x. That is, Flow believes the type of identity is (x: string | number) => string | number because those are the types which actually passed through the function.

Another important feature of generators is the ability to pass values into the generator from the consumer. Let's consider a generator scan, which reduces values passed into the generator using a provided function. Our scan is similar to Array.prototype.reduce, but it returns each intermediate value and the values are provided imperatively via next.

As a first pass, we might write this:

function *scan<T,U>(init: U, f: (acc: U, x: T) => U): Generator<U,void,T> {
  let acc = init;
  while (true) {
    const next = yield acc;
    acc = f(acc, next);
  }
}

We can use this definition to implement an imperative sum procedure:

let sum = scan(0, (a,b) => a + b);
console.log(sum.next());  // { done: false, value: 0 }
console.log(sum.next(1)); // { done: false, value: 1 }
console.log(sum.next(2)); // { done: false, value: 3 }
console.log(sum.next(3)); // { done: false, value: 6 }

However, when we try to check the above definition of scan, Flow complains:

test.js:7
  7:     acc = f(acc, next);
               ^^^^^^^^^^^^ function call
  7:     acc = f(acc, next);
                      ^^^^ undefined. This type is incompatible with
  3: function *scan<T,U>(init: U, f: (acc: U, x: T) => U): Generator<U,void,T> {
     ^ some incompatible instantiation of T

Flow is complaining that our value, next, may be void instead of the expected T, which is number in the sum example. This behavior is necessary to ensure type safety. In order to prime the generator, our consumer must first call next without an argument. To accommodate this, Flow understands the argument to next to be optional. This means Flow will allow the following code:

let sum = scan(0, (a,b) => a + b);
console.log(sum.next());  // first call primes the generator
console.log(sum.next());  // we should pass a value, but don't need to

In general, Flow doesn't know which invocation is "first." While it should be an error to pass a value to the first next, and an error to not pass a value to subsequent nexts, Flow compromises and forces your generator to deal with a potentially void value. In short, given a generator of type Generator<Y,R,N> and a value x of type Y, the type of the expression yield x is N | void.

We can update our definition to use a dynamic type test that enforces the non-void invariant at runtime:

function *scan<T,U>(init: U, f: (acc: U, x: T) => U): Generator<U,void,T> {
  let acc = init;
  while (true) {
    const next = yield acc;
    if (typeof next === "undefined") {
      throw new Error("Caller must provide an argument to `next`.");
    }
    acc = f(acc, next);
  }
}

There is one more important caveat when dealing with typed generators. Every value yielded from the generator must be described by a single type. Similarly, every value passed to the generator via next must be described by a single type.

Consider the following generator:

function *foo() {
  yield 0;
  yield "";
}

const gen = foo();
const a: number = gen.next().value; // error
const b: string = gen.next().value; // error

This is perfectly legal JavaScript and the values a and b do have the correct types at runtime. However, Flow rejects this program. Our generator's Yield type parameter has a concrete type of number | string. The value property of the iterator result object has the type number | string | void.

We can observe similar behavior for values passed into the generator:

function *bar() {
  var a = yield;
  var b = yield;
  return {a,b};
}

const gen = bar();
gen.next(); // prime the generator
gen.next(0);
const ret: { a: number, b: string } = gen.next("").value; // error

The value ret has the annotated type at runtime, but Flow also rejects this program. Our generator's Next type parameter has a concrete type of number | string. The value property of the iterator result object thus has the type void | { a: void | number | string, b: void | number | string }.

While it may be possible to use dynamic type tests to resolve these issues, another practical option is to use any to take on the type safety responsibility yourself.

function *bar(): Generator {
  var a = yield;
  var b = yield;
  return {a,b};
}

const gen = bar();
gen.next(); // prime the generator
gen.next(0);
const ret: void | { a: number, b: string } = gen.next("").value; // OK

(Note that the annotation Generator is equivalent to Generator<any,any,any>.)

Phew! I hope that this will help you use generators in your own code. I also hope this gave you a little insight into the difficulties of applying static analysis to a highly dynamic language such as JavaScript.

To summarize, here are some of the lessons we've learned for using generators in statically typed JS:

• Use generators to implement custom iterables.
• Use dynamic type tests to unpack the optional return type of yield expressions.
• Avoid generators that yield or receive values of multiple types, or use any.


This should hopefully help our command line users understand many errors without having to refer to their source code. We'll keep iterating on this format, so tell us what you like and what you don't like! Thanks to @frantic for building this feature!

There are a whole bunch of other features and fixes in this release! Head on over to our Release for the full list!

As always, the Changelog is best at summing up the big changes.

Check out the Changelog to see what's new.

So here is Flow v0.14.0! Check out the Changelog for the canonical list of what has changed.

• Specifying such data by a set of disjoint cases, distinguished by “tags”, where each tag is associated with a different “record” of properties. (These descriptions are called “disjoint union” or “variant” types.)
• Doing case analysis on such data, by checking tags and then directly accessing the associated record of properties. (The common way to do such case analysis is by pattern matching.)

Examples of programs that analyze or transform such data range from compilers working with abstract syntax trees, to operations that may return exceptional values, with much more in between!

As of Flow 0.13.1 it is now possible to program in this style in JavaScript in a type-safe manner. You can define a disjoint union of object types and do case analysis on objects of that type by switching on the value of some common property (called a "sentinel") in those object types.

Flow's syntax for disjoint unions looks like:

type BinaryTree =
  { kind: "leaf", value: number } |
  { kind: "branch", left: BinaryTree, right: BinaryTree }

function sumLeaves(tree: BinaryTree): number {
  if (tree.kind === "leaf") {
    return tree.value;
  } else {
    return sumLeaves(tree.left) + sumLeaves(tree.right);
  }
}

The problem​

Consider the following function that returns different objects depending on the data passed into it:

type Result = { status: string, errorCode?: number }

function getResult(op): Result {
  var statusCode = op();
  if (statusCode === 0) {
    return { status: 'done' };
  } else {
    return { status: 'error', errorCode: statusCode };
  }
}

The result contains a status property that is either 'done' or 'error', and an optional errorCode property that holds a numeric status code when the status is 'error'.

One may now try to write another function that gets the error code from a result:

function getErrorCode(result: Result): number {
  switch (result.status) {
    case 'error':
      return result.errorCode;
    default:
      return 0;
  }
}

Unfortunately, this code does not typecheck. The Result type does not precisely capture the relationship between the status property and the errorCode property. Namely it doesn't capture that when the status property is 'error', the errorCode property will be present and defined on the object. As a result, Flow thinks that result.errorCode in the above function may return undefined instead of number.

Prior to version 0.13.1 there was no way to express this relationship, which meant that it was not possible to check the type safety of this simple, familiar idiom!

The solution​

As of version 0.13.1 it is possible to write a more precise type for Result that better captures the intent and helps Flow narrow down the possible shapes of an object based on the outcome of a dynamic === check. Now, we can write:

type Result = Done | Error
type Done = { status: 'done' }
type Error = { status: 'error', errorCode: number }

In other words, we can explicitly list out the possible shapes of results. These cases are distinguished by the value of the status property. Note that here we use the string literal types 'done' and 'error'. These match exactly the strings 'done' and 'error', which means that === checks on those values are enough for Flow to narrow down the corresponding type cases. With this additional reasoning, the function getErrorCode now typechecks, without needing any changes to the code!

In addition to string literals, Flow also supports number literals as singleton types so they can also be used in disjoint unions and case analyses.

Why we built this​

Disjoint unions are at the heart of several good programming practices pervasive in functional programming languages. Supporting them in Flow means that JavaScript can use these practices in a type-safe manner. For example, disjoint unions can be used to write type-safe Flux dispatchers. They are also heavily used in a recently released reference implementation of GraphQL.

class BagOfBones<T: Bone> { ... }
function eat<T: Food>(meal: T): Indigestion<T> { ... }

The problem​

Consider the following code that defines a polymorphic function in Flow:

function fooBad<T>(obj: T): T {
  console.log(Math.abs(obj.x));
  return obj;
}

This code does not (and should not!) type check. Not all values obj: T have a property x, let alone a property x that is a number, given the additional requirement imposed by Math.abs().

But what if you wanted T to not range over all types, but instead over only the types of objects with an x property that has the type number? Intuitively, given that condition, the body should type check. Unfortunately, the only way you could enforce this condition prior to Flow 0.5.0 was by giving up on polymorphism entirely! For example you could write:

// Old lame workaround
function fooStillBad(obj: { x: number }): {x: number } {
  console.log(Math.abs(obj.x));
  return obj;
}

But while this change would make the body type check, it would cause Flow to lose information across call sites. For example:

// The return type of fooStillBad() is {x: number}
// so Flow thinks result has the type {x: number}
var result = fooStillBad({x: 42, y: "oops"});

// This will be an error since result's type
// doesn't have a property "y"
var test: {x: number; y: string} = result;

The solution​

As of version 0.5.0, such typing problems can be solved elegantly using bounded polymorphism. Type parameters such as T can specify bounds that constrain the types that the type parameters range over. For example, we can write:

function fooGood<T: { x: number }>(obj: T): T {
  console.log(Math.abs(obj.x));
  return obj;
}

Now the body type checks under the assumption that T is a subtype of { x: number }. Furthermore, no information is lost across call sites. Using the example from above:

// With bounded polymorphism, Flow knows the return
// type is {x: number; y: string}
var result = fooGood({x: 42, y: "yay"});

// This works!
var test: {x: number; y: string} = result;

Of course, polymorphic classes may also specify bounds. For example, the following code type checks:

class Store<T: { x: number }> {
  obj: T;
  constructor(obj: T) { this.obj = obj; }
  foo() { console.log(Math.abs(this.obj.x)); }
}

Instantiations of the class are appropriately constrained. If you write

var store = new Store({x: 42, y: "hi"});

Then store.obj has type {x: number; y: string}.

Any type may be used as a type parameter's bound. The type does not need to be an object type (as in the examples above). It may even be another type parameter that is in scope. For example, consider adding the following method to the above Store class:

class Store<T: { x: number }> {
  ...
  bar<U: T>(obj: U): U {
    this.obj = obj;
    console.log(Math.abs(obj.x));
    return obj;
  }
}

Since U is a subtype of T, the method body type checks (as you may expect, U must also satisfy T's bound, by transitivity of subtyping). Now the following code type checks:

  // store is a Store<{x: number; y: string}>
  var store = new Store({x: 42, y: "yay"});

  var result = store.bar({x: 0, y: "hello", z: "world"});

  // This works!
  var test: {x: number; y: string; z: string } = result;

Also, in a polymorphic definition with multiple type parameters, any type parameter may appear in the bound of any following type parameter. This is useful for type checking examples like the following:

function copyArray<T, S: T>(from: Array<S>, to: Array<T>) {
  from.forEach(elem => to.push(elem));
}

Why we built this​

The addition of bounded polymorphism significantly increases the expressiveness of Flow's type system, by enabling signatures and definitions to specify relationships between their type parameters, without having to sacrifice the benefits of generics. We expect that the increased expressiveness will be particularly useful to library writers, and will also allow us to write better declarations for framework APIs such as those provided by React.

Transformations​

Like type annotations and other Flow features, polymorphic function and class definitions need to be transformed before the code can be run. The transforms are available in react-tools 0.13.0, which was recently released

This feature introduces 3 special comments: /*:, /*::, and /*flow-include. Flow will read the code inside these special comments and treat the code as if the special comment tokens didn't exist. These special comments are valid JavaScript block comments, so your JavaScript engine will ignore the code inside the comments.

The Flow Comment Syntax​

There are 3 special comments that Flow currently supports. You may recognize this syntax from Jarno Rantanen's excellent project, flotate.

1. /*:​

/*: <your code> */ is interpreted by Flow as : <your code>

function foo(x/*: number*/)/* : string */ { ... }

is interpreted by Flow as

function foo(x: number): string { ... }

but appears to the JavaScript engine (ignoring comments) as

function foo(x) { ... }

2. /*::​

/*:: <your code> */ is interpreted by Flow as <your code>

/*:: type foo = number; */

is interpreted by Flow as

type foo = number;

but appears to the runtime (ignoring comments) as

3. /*flow-include​

/*flow-include <your code> */ is interpreted by Flow as <your code>. It behaves the same as /*::

/*flow-include type foo = number; */

is interpreted by Flow as

type foo = number;

but appears to the runtime (ignoring comments) as

Note: whitespace is ignored after the /* but before the :, ::, or flow-include. So you can write things like

/* : number */
/* :: type foo = number */
/* flow-include type foo = number */

Future Work​

We plan to update our Flow transformation to wrap Flow syntax with these special comments, rather than stripping it away completely. This will help people write Flow code but publish code that works with or without Flow.

Thanks​

Special thanks to Jarno Rantanen for building flotate and supporting us merging his syntax upstream into Flow.

Motivation​

Has this ever happened to you:

// @flow

// Post-transformation lint error: Unused variable 'URI'
import URI from "URI";

// But if you delete the require you get a Flow error:
// identifier URI - Unknown global name
module.exports = function(x: URI): URI {
  return x;
}

Now you have an out! To solve this problem (and with an eye toward a near future with ES6 module syntax), we've added the new import type syntax. With import type, you can convey what you really mean here — that you want to import the type of the class and not really the class itself.

Enter Import Type​

So instead of the above code, you can now write this:

// @flow

import type URI from 'URI';
module.exports = function(x: URI): URI {
  return x;
};

If you have a module that exports multiple classes (like, say, a Crayon and a Marker class), you can import the type for each of them together or separately like this:

// @flow

import type {Crayon, Marker} from 'WritingUtensils';
module.exports = function junkDrawer(x: Crayon, y: Marker): void {}

Transformations​

Like type annotations and other Flow features, import type need to be transformed away before the code can be run. The transforms will be available in react-tools 0.13.0 when it is published soon, but for now they're available in 0.13.0-beta.2, which you can install with

npm install react-tools@0.13.0-beta.2

Anticipatory Q&A​

Wait, but what happens at runtime after I've added an import type declaration?​

Nothing! All import type declarations get stripped away just like other flow syntax.

Can I use import type to pull in type aliases from another module, too?​

EDIT: Yes! As of Flow 0.10 you can use the export type MyType = ... ; syntax to compliment the import type syntax. Here's a trivial example:

// @flow

// MyTypes.js
export type UserID = number;
export type User = {
  id: UserID,
  firstName: string,
  lastName: string
};

// @flow

// User.js
import type {UserID, User} from "MyTypes";

function getUserID(user: User): UserID {
  return user.id;
}

Note that we only support the explicit named-export statements for now (i.e. export type UserID = number;). In a future version we can add support for latent named-export statements (i.e. type UserID = number; export {UserID};) and default type exports (i.e. export default type MyType = ... ;)...but for now these forms aren't yet supported for type exports.

A typecast expression is a simple way to type-annotate any JavaScript expression. Here are some examples of typecasts:

(1 + 1 : number);
var a = { name: (null: ?string) };
([1, 'a', true]: Array<mixed>).map(fn);

For any JavaScript expression <expr> and any Flow type <type>, you can write

(<expr> : <type>)

Note: the parentheses are necessary.

How Typecasts Work​

To evaluate a typecast expression, Flow will first check that <expr> is a <type>.

(1+1: number); // this is fine
(1+1: string); // but this is is an error

Second, Flow will infer that the typecast expression (<expr>: <type>) has the type <type>.

[(0: ?number)]; // Flow will infer the type Array<?number>
[0];            // Without the typecast, Flow infers the type Array<number>

Safety​

Typecasts obey the same rules as other type annotations, so they provide the same safety guarantees. This means they are safe unless you explicitly use the any type to defeat Flow's typechecking. Here are examples of upcasting (which is allowed), downcasting (which is forbidden), and using any.

class Base {}
class Child extends Base {}
var child: Child = new Child();

// Upcast from Child to Base, a more general type: OK
var base: Base = new Child();

// Upcast from Child to Base, a more general type: OK
(child: Base);

// Downcast from Base to Child: unsafe, ERROR
(base: Child);

// Upcast base to any then downcast any to Child.
// Unsafe downcasting from any is allowed: OK
((base: any): Child);

More examples​

Typecasts are particularly useful to check assumptions and help Flow infer the types you intend. Here are some examples:

(x: number) // Make Flow check that x is a number
(0: ?number) // Tells Flow that this expression is actually nullable.
(null: ?number) // Tells Flow that this expression is a nullable number.

Transformations​

Like type annotations and other Flow features, typecasts need to be transformed away before the code can be run. The transforms will be available in react-tools 0.13.0 when it is published soon, but for now they're available in 0.13.0-beta.2, which you can install with

npm install react-tools@0.13.0-beta.2