shuboc / flow-typed

A central repository for Flow library definitions

flow-typed is a repository of third-party library interface definitions for use with Flow.

You can grab definitions directly from this GitHub repo, or you can use the CLI (currently in beta) to install a libdef for a given library:

$ npm install -g flow-typed

$ cd /path/to/my/project
$ npm install
$ flow-typed install
'rxjs_v5.0.x.js' installed at /path/to/my/project/flow-typed/npm/rxjs_v5.0.xjs

Huh?

When you start a project with Flow, you likely want to use some third-party libraries that were not written with Flow. By default, Flow will just ignore these libraries leaving them untyped. As a result, Flow can't give errors if you accidentally mis-use the library (nor will it be able to auto-complete the library).

To address this, Flow supports library definitions which allow you to describe the interface of a module or library separate from the implementation of that module/library.

The flow-typed repo is a collection of high-quality library definitions, tests to ensure that definitions remain high quality, and tooling to make it as easy as possible to import them into your project.

All you have to do when you add a one or more new dependencies to your project is run flow-typed install. This will search the libdef repo and download all the libdefs that are relevant for your project and install them for you. After that, simply check them in and be on your way!

Why do I need to commit the libdefs that flow-typed installs for my project?

Libdefs in flow-typed are tagged at both Flow and library version when they are installed, but libdefs themselves can improve over time. For example, they may have a bug or there may be an improvement to their accuracy or completeness.

When a libdef is improved or updated in flow-typed, there's some chance that the change could introduce new Flow errors into your project. As good as it is to find new issues, we also want to make sure that Flow-errors in your project are consistent and predictable over time.

So if/when you wish to upgrade a libdef that you've already checked in to your project's version control, you can do so explicitly with the flow-typed install --overwrite command.

How Do I Contribute Library Definitions?

Just send a pull request!

All definitions sit under the /definitions directory. They all must follow the following directory structure and naming format:

└ definitions/npm/
  ├ yargs_v4.x.x/           # <-- The name of the library, followed by _v<VERSION>
  | |
  | ├ flow_v0.23.x/         # <-- A folder containing libdefs tested against the 
  | | |                     #     specified version(s) of Flow (v0.23.x in this
  | | |                     #     case).
  | | |
  | | └ yargs_v4.x.x.js     # <-- The libdef file meant for the Flow version 
  | |                       #     specified by the containing directory's name. 
  | |                       #     Must be named `<LIB>_v<VERSION>.js`.
  | |
  | ├ flow_v0.19.x-v0.22.x/ # <-- A folder containing libdefs tested against a 
  | | |                     #     different range of Flow versions: 
  | | |                     #     Anything from v0.19.x to v0.22.x (inclusive)
  | | |
  | | ├ yargs_v4.x.x.js     # <-- The libdef file for versions of Flow from 
  | | |                     #     v0.19.x to v0.22.x (inclusive)
  | | |
  | | └ test_yargs.js       # <-- Tests in this directory only apply to the 
  | |                       #     adjacent libdef (and thus, are specific to
  | |                       #     the libdefs for this specific Flow version) 
  | |
  | └ test_yargs.js         # <-- Tests in this directory apply to libdefs for
  |                         #     all versions of Flow. 
  ├ color_v0.7.x/
  ├ ...

Versions are semver versions with some restrictions:

• All of MAJOR, MINOR, and PATCH versions must be specified. It's acceptable to specify x in place of a number for MINOR and PATCH, but MAJOR cannot be x.
• Library versions may not specify a semver range, but Flow versions can of the following forms:
  • flow_v0.22.x-: Flow v0.22.x and above
  • flow_v0.22.x-v0.28.x: Flow versions v0.22.x up to v0.28.x (inclusive)
  • flow_-v0.22.x: Every version under (and including) Flow v0.22.x

We structure files this way to enable automated testing and tooling. Tests ensure that library definitions continue to work as expected and the flow-typed tooling ensures that it's as easy as possible to find and install library definitions.

Writing LibDef Tests

When you contribute a new library definition (or make a change to an existing one), you must include tests with your change.

Tests are simply test_*.js files that sit next to the library definition file. They are normal @flow-ified .js files that import from and use the types declared in the libdef in a way they are expected to be used. Flow-typed CI will then run all applicable versions of Flow against the test file to be sure that only expected errors occur.

In order to write code where you expect an error, you can put // $ExpectError on the line above one of the lines listed in the error. This tells the test runner to ignore errors that mention that line. We require at least 1 // $ExpectError in each test. This helps to ensure that the test is actually exercising types like the author expects it to be.

FAQs

When I install the flow-typed CLI, I get an error that mentions OpenSSL or Libgcrypt

You may need to install Libgcrypt. Try setting up homebrew and running brew install libgcrypt.

This issue was first reported here: #336

When I install the flow-typed CLI, I get an error immediately after [configuring libssh2]

You may need to install OpenSSL. Try setting up homebrew and running brew install openssl.

This issue was first reported here: 331

flow-typed CLI

The flow-typed npm package provides a CLI that provides several commands for working with this repository:

flow-typed validate-defs

Verifies that all files under the /definitions/ directory are structured and named properly. It does not run tests, it only asserts that file and directory names match the expected conventions.

This command is run during CI.

flow-typed run-tests [optional-pattern]

For each libdef, find each test and run it with all compatible versions of Flow. If any errors arise that are not // $ExpectError, the test has failed.

Note that this command assumes that the /definitions/ directory is correctly structured. It should be run after running flow-typed validate-defs.

flow-typed update-cache [--debug]

By default flow-typed retrieves all available libdefs from its related upstream repository. To make this process more efficient, those libdefs are cached once on your local filesystem. Usually, the cache will automatically be updated after a short grace period during a libdef installation, but sometimes it is useful to do this update manually. Use this command if you want to download the most recent definitions into the cache for yourself.

The debug flag will output additional (error) information, which can be useful for bug-reports.