Skip to content

Commit

Permalink
Updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@flow-bot
flow-bot committed May 2, 2024
0 parents commit 4e99988
Show file tree
Hide file tree
Showing 773 changed files with 471,588 additions and 0 deletions.
26 changes: 26 additions & 0 deletions 404.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<!doctype html>
<html lang="en" dir="ltr" class="plugin-native plugin-id-default">
<head>
<meta charset="UTF-8">
<meta name="generator" content="Docusaurus v2.4.1">
<title data-rh="true">Page Not Found | Flow</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://flow.org/404.html"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docusaurus_tag" content="default"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docsearch:docusaurus_tag" content="default"><meta data-rh="true" property="og:title" content="Page Not Found | Flow"><link data-rh="true" rel="icon" href="/img/favicon.png"><link data-rh="true" rel="canonical" href="https://flow.org/404.html"><link data-rh="true" rel="alternate" href="https://flow.org/404.html" hreflang="en"><link data-rh="true" rel="alternate" href="https://flow.org/404.html" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://P6T3E8XPGT-dsn.algolia.net" crossorigin="anonymous"><link rel="alternate" type="application/rss+xml" href="/blog/rss.xml" title="Flow RSS Feed">
<link rel="alternate" type="application/atom+xml" href="/blog/atom.xml" title="Flow Atom Feed">

<link rel="preconnect" href="https://www.google-analytics.com">
<script>window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)},ga.l=+new Date,ga("create","UA-49208336-4","auto"),ga("set","anonymizeIp",!0),ga("send","pageview")</script>
<script async src="https://www.google-analytics.com/analytics.js"></script>


<link rel="search" type="application/opensearchdescription+xml" title="Flow" href="/opensearch.xml"><link rel="stylesheet" href="/assets/css/styles.edb45c3d.css">
<link rel="preload" href="/assets/js/runtime~main.674ae595.js" as="script">
<link rel="preload" href="/assets/js/main.9c6220cd.js" as="script">
</head>
<body class="navigation-with-keyboard">
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}return t}()||function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}()</script>

<div style="display: none; text-align: center; background-color: white; color: black;" id="internaldocs-banner"></div><div id="__docusaurus">
<div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/logo.svg" alt="My Facebook Project Logo" class="themedImage_ToTc themedImage--light_HNdA"><img src="/img/logo.svg" alt="My Facebook Project Logo" class="themedImage_ToTc themedImage--dark_i4oU"></div></a><a class="navbar__item navbar__link" href="/en/docs/getting-started/">Getting Started</a><a class="navbar__item navbar__link" href="/en/docs/">Docs</a><a class="navbar__item navbar__link" href="/try/">Try</a><a class="navbar__item navbar__link" href="/blog/">Blog</a></div><div class="navbar__items navbar__items--right"><a href="https://twitter.com/flowtype" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link navbar__icon twitter__link" aria-label="Twitter"></a><a href="http://stackoverflow.com/questions/tagged/flowtype" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link navbar__icon stackoverflow__link" aria-label="Stack Overflow"></a><a href="https://github.com/facebook/flow" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link navbar__icon github__link" aria-label="GitHub"></a><div class="searchBox_ZlJk"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_z2l0"><main class="container margin-vert--xl"><div class="row"><div class="col col--6 col--offset-3"><h1 class="hero__title">Page Not Found</h1><p>We could not find what you were looking for.</p><p>Please contact the owner of the site that linked you to the original URL and let them know their link is broken.</p></div></div></main></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Learn</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/en/docs/getting-started/">Getting Started</a></li></ul></div><div class="col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://twitter.com/flowtype" target="_blank" rel="noopener noreferrer" class="footer__link-item">Twitter<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://discordapp.com/invite/8ezwRUK" target="_blank" rel="noopener noreferrer" class="footer__link-item">Discord<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div><div class="col footer__col"><div class="footer__title">More</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://medium.com/flow-type" target="_blank" rel="noopener noreferrer" class="footer__link-item">Medium</a></li><li class="footer__item"><a href="https://github.com/facebook/flow" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div><div class="col footer__col"><div class="footer__title">Legal</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://opensource.facebook.com/legal/privacy/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Privacy<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://opensource.facebook.com/legal/terms/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Terms<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://opensource.facebook.com/legal/data-policy/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Data Policy<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://opensource.facebook.com/legal/cookie-policy/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Cookie Policy<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div></div><div class="footer__bottom text--center"><div class="margin-bottom--sm"><a href="https://opensource.facebook.com" rel="noopener noreferrer" class="footerLogoLink_BH7S"><img src="/img/oss_logo.png" alt="Facebook Open Source Logo" class="themedImage_ToTc themedImage--light_HNdA footer__logo"><img src="/img/oss_logo.png" alt="Facebook Open Source Logo" class="themedImage_ToTc themedImage--dark_i4oU footer__logo"></a></div><div class="footer__copyright">Copyright © 2024 Meta Platforms, Inc. Built with Docusaurus.</div></div></div></footer></div>
<script src="/assets/js/runtime~main.674ae595.js"></script>
<script src="/assets/js/main.9c6220cd.js"></script>
</body>
</html>
1 change: 1 addition & 0 deletions CNAME
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
flow.org
80 changes: 80 additions & 0 deletions _src/cli/annotate-exports.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
---
title: Flow Annotate-Exports
slug: /cli/annotate-exports
---

Upgrading to [Types-First](../../lang/types-first) mode may require a substantial
number of type annotations at module boundaries. To help with the process of
upgrading large codebases, we are providing a codemod command, whose goal is to
fill in these missing annotations. This command is included in the Flow binary
in versions `>= 0.125`.

> Note: As of version 0.134, types-first is the default mode. If you are using a
version `>=0.134`, make sure you set `types_first=false` in your .flowconfig while
running this codemod.

This command uses types that Flow infers, to fill in positions that would otherwise
raise *signature-verification* failures. It will include the necessary type import
statements, as long as the respective types are exported from their defining modules.

It is designed for use on multiple files at once, rather than one file at a time.
For this reason it doesn't connect to an existing Flow server, but rather starts
a checking process of its own.

As is typical with such mechanized approaches, it comes with a few caveats:

1. It won’t be able to fill in every required type annotation. Some cases will
require manual effort.
2. Inserted annotations may cause new flow errors, since it’s not always possible
to match inferred type with types that can be written as annotations.
3. File formatting may be affected. If a code formatter (e.g. prettier) is used,
it is recommended that you run it after the codemod has finished running.


### How to apply the codemod {#toc-how-to-apply-the-codemod}

A typical way to invoke this command is

```
flow codemod annotate-exports \
--write \
--repeat \
--log-level info \
/path/to/folder \
2> out.log
```

This command will transform files under `/path/to/folder`. This does not need to
be the root directory (the one containing `.flowconfig`).

It uses the following flags:
* `--write` will update files that require annotations under `/path/to/folder`
in-place. Without this flag the resulting files will be printed on the command line.

* `--repeat` ensures that the transformation will be applied until no more files
change. This mode is necessary here, because each new type the codemod adds may
require new locations to be annotated.

* `--log-level info` outputs useful debugging information in the standard error stream.
This option might lead to verbose output, so we're redirecting the error output
to a log file `out.log`.

Another convenient way to provide the input is by passing the flag
```
--input-file file.txt
```
where `file.txt` contains a specific list of files to be transformed.

### Codemod output {#toc-codemod-output}

After each iteration of the codemod, a summary will be printed on the CLI. This
summary includes statistical information about the number of annotations that were
added, and how many locations were skipped. It also prints counts for various kinds
of errors that were encountered. These can be matched to the errors printed in the
logs.

A common error case is when a type `A`, defined in a file `a.js`, but not exported,
is inferred in file `b.js`. The codemod will skip adding this annotation and report
an error in the logs. The fix this case, you can export `A` in `a.js`. Note that
it is not necessary to manually import `A` in `b.js`. The codemod will do this
automatically.
128 changes: 128 additions & 0 deletions _src/cli/coverage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
---
title: Flow Coverage
slug: /cli/coverage
---
The coverage command provides a metric of the amount of checking that Flow has
performed on each part of your code. A program with high Flow coverage should
increase your confidence that Flow has detected any potential runtime errors.

The determining factor for this is the presence of [`any`](../../types/any/) in the
inferred type of each expression. An expression whose inferred type is `any` is
considered *uncovered*, otherwise it is considered *covered*.

To see why this metric was chosen for determining Flow's effectiveness, consider
the example

```js flow-check
const one: any = 1;
one();
```

This code leads to a runtime type error, since we are attempting to perform a call
on a number. Flow, however, does not flag an error here, because we have annotated
variable `one` as `any`. Flow's checking is effectively turned off whenever `any`
is involved, so it will silently allow the call. The use of this *unsafe* type has
rendered the type checker ineffective, and the coverage metric is here to surface
this, by reporting all instances of `one` as uncovered.

## Design Space {#toc-design-space}

**Which types should be "covered"?**

What was described above is a rather coarse grained way to determine coverage. One
could imagine a criterion that flags expressions as uncovered if *any* part of their
type includes `any`, for example `Array<any>`. While there is value in a metric like
this, the "uncovered" part of the type will typically be uncovered through various
operations on values of this type. For example, in the code

```js flow-check
declare const arr: Array<any>;
arr.forEach(x => {});
```

the parameter `x` will be flagged as uncovered. Also, in practice, a strict criterion
like this would be too noisy and rather expensive to compute on the fly.

**Union types**

An exception to this principle are union types: the type `number | any` is considered
*uncovered*, even though technically `any` is not the top-level constructor.
Unions merely encode an option among *a set of* other types. In that sense we are
conservatively viewing an expression as uncovered, when at least one possible type
of that expression causes limited checking. For example, in the code

```js flow-check
let x: number | any = 1;
x = "a";
```

Flow will let you assign anything to `x`, which reduces confidence in the use
of `x` as a number. Thus `x` is considered uncovered.

**The empty type**

An interesting type from a coverage perspective is the [`empty`](../../types/empty) type.
This type roughly corresponds to *dead code*. As such checking around expressions with
type `empty` is more relaxed, but for a good reason: this code will not be executed at
runtime. Since it is a common practice to clean up such code, Flow coverage will
also report code whose type is inferred to be `empty`, but distinguishes it from
the case of `any`.


## Command Line Use {#toc-command-line-use}

To find out the coverage of a file foo.js with the following contents

```js flow-check
function add(one: any, two: any): number {
return one + two;
}

add(1, 2);
```

you can issue the following command

```
$ flow coverage file.js
Covered: 50.00% (5 of 10 expressions)
```
This output means that 5 out of the 10 nodes of this program were inferred to have type
`any`. To see exactly which parts are uncovered you can also pass one of the following
flags:
* `--color`: This will print foo.js on the terminal with the uncovered locations in
red color. E.g. `flow coverage --color file.js`
* `--json`: This will list out all location spans that are uncovered under
the tag `"uncovered_locs"`. E.g. `flow coverage --json file.js`

Finally, as an example of dead code, consider the code:

```js flow-check
function f(x: 'a' | 'b') {
if (x === 'a') {
// ...
} else if (x === 'b') {
// ...
} else {
x;
}
}
```

The final `else` clause should never be reached, as we've already checked for both members of the union.
Because of this, `x` is inferred to have the type `empty` in that branch.

In the colored version of this command, these parts appear in blue color,
and in the JSON version they are under the field `"empty_locs"`.

**Use on multiple files**

If you want to check coverage of multiple files at once, Flow offers the
`batch-coverage` command:
```
$ flow batch-coverage dir/
```
will report coverage statistics for each file under `dir/`, as well as aggregate
results.

Note that `batch-coverage` requires a non-lazy Flow server.

0 comments on commit 4e99988

Please sign in to comment.