JavaScript was always a significant programming language, being the only language that runs reliably in the browser. Recent trends in front-end development as well as Node.js based back-end development have pushed the scale and complexity of JavaScript applications. 

Large applications developed by large teams can benefit from static type checking, which vanilla JavaScript lacks. Flow was developed by Facebook to address this issue. It is a static type checker that integrates into your development process, catches a lot of problems early, and helps you move fast.

What Is Flow?

Flow is a tool that checks your annotated JavaScript code and detects various issues that without it would be discovered only at runtime (or worse, not discovered and corrupt your data). Here is a quick example.

// @flow
function getGreeting(name: string): string {
  return `Hi, ${name}`;
}


const  http = require("http");
const  greeting = getGreeting("Gigi")
const port = 8888

console.log(`Listening on port ${port}...`)
http.createServer(function(request, response) {
  response.writeHead(200, {"Content-Type": "text/plain"});
  response.write(greeting);
  response.end();
}).listen(port);

Flow vs. TypeScript

Before diving into the nitty-gritty details of Flow, it's worthwhile to compare it against other alternatives, and in particular TypeScript. TypeScript is a strict superset of JavaScript developed by Microsoft. Any JavaScript program is also a TypeScript program. 

TypeScript adds optional type annotations and overall serves the same purpose as Flow. However, there are some important differences. TypeScript is a separate programming language that compiles to JavaScript, whereas Flow annotations must be removed to get back to valid JavaScript. 

TypeScript has great tool and IDE support. Flow is catching up (e.g. JetBrains WebStorm has native Flow integration).

The most important philosophical difference is that Flow puts an emphasis on soundness. TypeScript 1.0 didn't catch null errors; TypeScript 2.0 with strict null checks measured up to Flow in this regard. But in other aspects such as generic containers or typing, TypeScript is more permissive and lets various categories of errors through (only structural typing is checked, not nominal typing).

TypeScript as its own language adds concepts and language features such as classes, interfaces, visibility indicators (public, private, readonly), and decorators. Those features make it easier to understand and use for people coming from mainstream object-oriented languages like C++, Java, and C#.

Installation

Since Flow annotations are not standard JavaScript, they need to be removed before deploying your application. Here is how to install flow and flow-remove-types via yarn: yarn add --dev flow-bin flow-remove-types

You can add a couple of scripts to your package.json file to automate the process:

  "scripts": {
    "build": "flow-remove-types src/ -d lib/",
    "prepublish": "yarn run build"
  }

You should run the prepublish script before publishing your code to the npm registry.

For other installation options (e.g. using npm or babel), check out the Flow installation guide.

To finish the installation, type: yarn run flow init

This will create the required .flowconfig file.

Type System

Flow has two important goals: precision and speed. Its type system was designed to support these goals.

Precision

Precision is achieved by analyzing how the code interacts with types, either annotated or inferred. Any mismatch raises a type error. Annotated types support nominal typing, which means that two different types with the same attributes are distinguished from each other and can't be substituted. The type of a variable is defined as the set of runtime values the variable may receive. 

Speed

Flow is fast due to a combination of modularity and distributed processing. Files are analyzed in parallel, and the results are merged later via efficient shared memory to accomplish full-program type checking.

Supported Types

Flow supports many types. In addition to primitive types, it also supports the following:

• Object
• Array
• Any
• Maybe
• Variable
• Tuple
• Class
• Interface
• Generic

Type Annotations

Flow allows you to declare types as well as restrict variables and parameters to selected values:

type Two2Four = 2 | 3 | 4

function doubleIt(number: Two2Four) {
  return number * 2
}

console.log(doubleIt(3))

Output:

6

If you exceed the valid range, you'll get an error:

console.log(doubleIt(3))

Output:

Error: src/main.js:30
 30: console.log(doubleIt(5)) // error
                          ^ number. This type is incompatible with the expected param type of
 24: function doubleIt(number: Two2Four) {
                               ^^^^^^^^ number enum


Found 1 error

You can also define complex types, including subtyping. In the following code example, the Warrior type is a subtype of Person. This means it is OK to return a Warrior as a Person from the fight() function. However, returning null is forbidden.

type Person = { name: string, age: number }
type Warrior = { name: string, age: number, strength: number }

let redWolf : Warrior = { name: "Red Wolf", age: 24, strength: 10 }
let skullCrusher : Warrior = { name: "Skull Crusher", age: 27, strength: 11 }

function fight(w1: Warrior, w2: Warrior): Person {
  if (w1.strength > w2.strength) {
    return w1
  }
  if (w2.strength > w1.strength) {
    return w2
  }

  return null
}

Output:


Found 1 error
$ flow
Error: src/main.js:47
 47:   return null
              ^^^^ null. This type is incompatible with the
              expected return type of
 39: function fight(w1: Warrior, w2: Warrior): Person {
                                               ^^^^^^ object type


Found 1 error

To fix it, let's return the younger warrior if both warriors have the same strength:

function fight(w1: Warrior, w2: Warrior): Person {
  if (w1.strength > w2.strength) {
    return w1
  }
  if (w2.strength > w1.strength) {
    return w2
  }

  return (w1.age < w2.age ? w1 : w2)
}

let winner = fight(redWolf, skullCrusher)
console.log(winner.name)

Output:

Skull Crusher

Flow allows even more precise control via class extension, invariance, co-variance, and contra-variance. Check out the Flow documentation on variance.

Configuration

Flow uses the .flowconfig configuration file in the root directory of your projects. This file contains several sections that let you configure what files Flow should check and the many aspects of its operation. 

Include

The [include] section controls what directories and files should be checked. The root directory is always included by default. The paths in the [include] sections are relative. A single star is a wild-card for any filename, extension, or directory name. Two stars are a wild-card for any depth of directory. Here is a sample [include] section:

[include]
../externalFile.js
../externalDir/
../otherProject/*.js
../otherProject/**/coolStuff/

Ignore

The [ignore] section is the complement to [include]. Files and directories you specify here will not be checked by flow. Strangely, it uses a different syntax (OCaml regular expressions) and requires absolute paths. Changing this is on the roadmap of the Flow team.

Until then, remember that the include section is processed first, followed by the ignore section. If you include and ignore the same directory and/or file, it will be ignored. To address the absolute path issue, it is common to prefix every line with .*. If you want to ignore directories or files under the root, you can use the <PROJECT_ROOT> placeholder instead of .*. Here is a sample [ignore] section:

[ignore]
.*/__tests__/.*
.*/src/\(foo\|bar\)/.*
.*\.ignore\.js
<PROJECT_ROOT>/ignore_me.js

Libs

Any non-trivial JavaScript application uses lots of third-party libraries. Flow can check how your application is using these libraries if you provide special libdef files that contain type information about these libraries. 

Flow automatically scans the "flow-typed" sub-directory of your project for libdef files, but you may also provide the path of libdef files in the [libs] section. This is useful if you maintain a central repository of libdef files used by multiple projects.

Importing existing type definitions and creating your own if the target library doesn't provide its own type definitions is pretty simple. See:

• Flow Documentation: Library Definitions
• Flow Documentation: Creating Library Definitions
• GitHub: Importing and Using Library Definitions

Lints

Flow has several lint rules you can control and determine how to treat them. You can configure the rules from the command line, in code comments, or in the [lints] section of your config file. I'll discuss linting in the next section, but here is how to configure it using the [lints] section:

[lints]
all=warn
untyped-type-import=error
sketchy-null-bool=off

Options

The [options] section is where you get to tell Flow how to behave in a variety of cases that don't deserve their own section, so they are all grouped together.

There are too many options to list them all here. Some of the more interesting ones are:

• all: set to true to check all files, not just those with @flow
• emoji: set to true to add emojis to status messages
• module.use_strict: set to true if you use a transpiler that adds "use strict;"
• suppress_comment: a regex that defines a comment to suppress any flow errors on the following line (useful for in-progress code)

Check out all the options in the Flow guide to configuring options.

Version

Flow and its configuration file format evolve. The [version] section lets you specify which version of Flow the config file is designed for to avoid confusing errors.

If the version of Flow doesn't match the configured version, Flow will display an error message.

Here are a few ways to specify the supported versions:

[version]
0.22.0

[version]
>=0.13.0 <0.14.0

[version]
^1.2.3

The caret version keeps the first non-zero component of the version fixed. So ^1.2.3 expands to the range >=1.2.3 < 2.0.0, and ^0.4.5 expands to the range >= 0.4.5 < 0.5.0.

Using Flow From the Command Line

Flow is a client-server program. A Flow server must be running, and the client connects to it (or starts it if it's not running). The Flow CLI has many commands and options that are useful for maintenance and introspection purposes as well as for temporarily overriding configuration from .flowconfig.

Typing flow --help shows all the commands and options. To get help on a specific command, type flow <command> --help. For example:

$ flow ast --help
Usage: flow ast [OPTION]... [FILE]

e.g. flow ast foo.js
or   flow ast < foo.js

  --from    Specify client (for use by editor plugins)
  --help    This list of options
  --pretty  Pretty-print JSON output
  --tokens  Include a list of syntax tokens in the output
  --type    Type of input file (js or json)

Important commands are:

• init: generate an empty .flowconfig file
• check: do a full Flow check and print the results 
• ls: display files visible to Flow
• status (default): show current Flow errors from the Flow server

• suggest: suggest types for the target file

Linting With Flow

Flow has a linting framework that can be configured via the .flowconfig file as you saw earlier, through command-line arguments, or in code files using flowlint comments. All configuration methods consist of a list of key-value pairs where the key is a rule and the value is the severity. 

Rules

There are currently three rules: all, untyped-type-import, and sketchy-null. The "All" rule is really the default handling for any errors that don't have a more specific rule. The "untyped-type-import" rule is invoked when you import a type from an untyped file. The "sketchy-null" rule is invoked when you do existence check on a value that can be false or null/undefined. There are more granular rules for:

• sketchy-null-bool
• sketchy-null-number
• sketchy-null-string
• sketchy-null-mixed

Severity Levels

There are also three severity levels: off, warning, and error. As you can imagine, "off" skips the type check, "warn" produces warnings, which don't cause the type check to exit and don't show up by default in the CLI output (you can see them with --include-warnings), and "error" is handled just like flow errors and causes the type check to exit and display an error message.

Linting With Command-Line Arguments

Use the --lints command-line argument to specify multiple lint rules. For example:

flow --lints "all=warn, untyped-type-import=error, sketchy-null-bool=off"

Linting With flowlint Comments

There are three types of comments: flowlint, flowlint-line, and flowlint-next-line.

The "flowlint" comment applies a set of rules in a block until overridden by a matching comment:

import type {
  // flowlint untyped-type-import:off
  Foo,
  Bar,
  Baz,
  // flowlint untyped-type-import:error
} from './untyped.js';

If there is no matching comment, the settings simply apply until the end of the file.

The "flowlint-line" applies just to the current line:  

function (x: ?boolean) {
  if (x) { // flowlint-line sketchy-null-bool:off
    ...
  } else {
    ...
  }
}

The "flowlint-next-line" applies to the line following the comment:

function (x: ?boolean) {
  // flowlint-next-line sketchy-null-bool:off
  if (x) {
    ...
  } else {
    ...
  }
}

Conclusion

Large JavaScript projects developed by large teams can benefit a lot from static type checking. There are several solutions for introducing static type checking into a JavaScript codebase. 

JavaScript continues to grow in a variety of ways across the web. It’s not without its learning curves, and there are plenty of frameworks and libraries to keep you busy, as you can see. If you’re looking for additional resources to study or to use in your work, check out what we have available in the Envato marketplace.

Facebook's Flow is a recent and robust solution with excellent coverage, tooling, and documentation. Give it a try if you have a large JavaScript codebase.