Branching in JavaScript can be a pain. switch? Full of footguns. Nested conditional ternary expressions? Unreadable. Initializing a let over a bunch of if/else? Verbose. That weird chain of && in your JSX? No thanks. And none of these handle complex structures or check if you handled every case.

If you haven’t looked at Flow recently: its syntax has grown so close to TypeScript that most code is hard to tell apart (here’s a side-by-side for TypeScript users). But Flow isn’t just type annotations: it adds first-class language features built for safety.

match expressions and statements are the newest. They branch on a value: the first pattern that matches maps to a result. match destructures as it matches, and it's exhaustively checked. If you forget a case of the input, Flow tells you what's missing and prevents that bug from hitting production.

An expression, not just a statement

switch is a statement. It can't produce a value, so the moment you want one you're back to a let you assign across cases, or a conditional ternary chain. match is both a statement and an expression. As an expression, it gives you the value directly:

const description = match (action) {
  {type: 'add', const text} => `Add: ${text}`,
  {type: 'toggle', const id} => `Toggle ${id}`,
  {type: 'remove', const id} => `Remove ${id}`,
};

Each pattern matches and extracts values at the same time. {type: 'add', const text} checks that type is 'add' and binds text in one step, no separate destructuring.

Exhaustively checked by default

Drop a case and Flow tells you exactly which one is missing:

type Action =
  | {type: 'add', text: string}
  | {type: 'toggle', id: string}
  | {type: 'remove', id: string};
declare const action: Action;

const description = match (action) {
  {type: 'add', const text} => `Add: ${text}`,
  {type: 'toggle', const id} => `Toggle ${id}`,
  // ERROR: add the missing pattern `{type: 'remove', id: _}`
};

Add a new variant to Action during a later refactor, and every match that doesn't handle it lights up. Delete a variant and Flow points at the now-dead patterns to remove.

A better switch

When you want a statement, match is a switch without the footguns. Cases don't fall through, so there's no break to forget. Each case is its own block, so use those lets and consts without worry. And just like the expression form, it's exhaustively checked.

// Before
switch (command) {
  case 'delete':
  case 'remove':
    data.pop();
    break;
  case 'add':
    data.push(1);
    break;
  default:
    show(data);
}
// After
match (command) {
  'delete' | 'remove' => {
    data.pop();
  }
  'add' => {
    data.push(1);
  }
  _ => {
    show(data);
  }
}

'delete' | 'remove' is an or-pattern: one block for several patterns. _ is the wildcard, matching anything left over.

Patterns go deep

Patterns aren’t limited to single values. They reach into nested objects and arrays, binding as they go:

const name = match (entity) {
  {type: 'user', details: {const name}} => name,
  {type: 'page', pageInfo: {const pageName}} => pageName,
  {type: 'employee', const preferredName} => preferredName,
};

They match arrays and tuples by shape, so you can branch on several values at once. Exhaustiveness works here too: leave a combination out and Flow tells you the fix.

const style = match ([align, position]) {
  ['start', 'above'] => styles.alignTopLeft,
  ['start', 'below'] => styles.alignBottomLeft,
  ['end', 'above'] => styles.alignTopRight,
  // ERROR: add the missing pattern `['end', 'below']`
};

Conditional React rendering, finally readable

Conditional rendering in React is exactly what match expressions are for:

function Page({tab}: {tab: 'home' | 'details' | 'settings'}) {
  return match (tab) {
    'home' => <Home />,
    'details' => <DetailsPane />,
    'settings' => <Settings />,
  };
}

No ternary nest, no stray &&, and if a new tab is added to the union, Flow makes you handle it.

Try it

match brings exhaustiveness, destructuring, and readable branching together in one construct. It's the kind of language-level feature Flow exists to add: not just describing the JavaScript you already write, but giving you better JavaScript to write.

It’s available now.

• Read the docs on match, including if guards, as patterns, and more
• Moving off switch? See the migration guide
• Coming from TypeScript? See Flow for TypeScript Users
• Try it live in the Flow playground

JavaScript Pattern Matching with Flow was originally published in Flow on Medium, where people are continuing the conversation by highlighting and responding to this story.

In 2026 Flow has changed in three ways that matter:

• Flow’s syntax has converged with TypeScript’s: if you know TypeScript, you already know most of Flow.
• Flow has features TypeScript lacks: match expressions and first-class component/hook/renders.
• Where the two diverge, Flow keeps the safer default: catching patterns TypeScript accepts that can throw at runtime, silently corrupt values, or cause logic bugs.

Flow and TypeScript syntax have converged

Is it Flow or TypeScript? You can’t tell:

type User = {
  readonly name: string,
  readonly age: number,
  readonly metadata: unknown,
};

function get<K extends keyof User>(user: User, key: K): User[K] {
  return user[key];
}

declare const user: User;
const age: number = get(user, 'age');

If you know TypeScript, this all looks familiar. The example above uses keyof, readonly props, unknown, indexed access (T[K]), and extends bounds - and there's also conditional types, mapped types, type guards, and as const.

The rest of this post is where Flow goes beyond TypeScript.

Flow-only features

Flow has features TypeScript lacks:

match expressions and statements

Flow has match: pattern matching as an expression. It's exhaustively checked, with structural patterns that destructure as they match. Forget a case, like type: 'remove', and match flags it and tells you what to add.

type Action = 
  | {type: 'add', text: string}
  | {type: 'toggle', id: string}
  | {type: 'remove', id: string};

declare const action: Action;

const description = match (action) { // ERROR: 'remove' case missing
  {type: 'add', const text} => `Add: ${text}`,
  {type: 'toggle', const id} => `Toggle ${id}`,
};

match also has a statement form: a safer switch with no fall-through and all the features of match expressions.

React: component, hook, renders

• component syntax: React components as a first-class language construct. Direct prop declaration as named parameters, and React-specific correctness the type-checker can enforce.
• renders types: declare composition contracts for components. Design systems and libraries can specify what slots accept and what components produce, with the type checker enforcing the contracts across wrapper components.
• hook syntax: declares hooks as a first-class kind, distinct from regular functions. Flow enforces the Rules of React in the type checker: catching conditional calls, hook/function conflation, and unsafe mutations of hook return values during render, without a separate ESLint plugin.

component Header(text: string, color: string) {
  return <div style={{color}}>{text}</div>;
}
component MainHeader(text: string) renders Header {
  return <Header text={text} color="red" />;
}

component Layout(header: renders Header) {
  return <div>
    {header}
    <section>Content</section>
  </div>;
}

const ok = <Layout header={<MainHeader text="Flow" />} />;
const bad = <Layout header={<footer />} />; // ERROR

Four runtime crashes TypeScript doesn’t catch — but Flow does

This is where the two still part ways. Each example below type-checks in TypeScript 6.0.3 with strict enabled - then crashes at runtime.

1. Extracting a method from an instance loses its this binding in TypeScript

class Counter {
  count: number = 0;
  increment(): number {
    return ++this.count;
  }
}
const counter = new Counter();
const tick = counter.increment;  // TS accepts. Flow rejects.
tick();  // Runtime crash! `this` is undefined inside `increment`

Pulling counter.increment off the instance detaches the method from counter, so the later tick() runs with this undefined and ++this.count throws. TypeScript types the extracted method as a plain function and waves the call through. Flow rejects the unbound method extraction at the point where this is lost.

2. TypeScript lets extra properties slip through indirect assignment

type Prices = {apple: number, banana: number};
const items = {apple: 1.5, banana: 0.5, sample: "free"};
const prices: Prices = items;  // TS accepts. Flow rejects.
Object.values(prices).map(
  price => price.toFixed(2), // Runtime crash! `sample` isn't a number
);

TypeScript’ object types allow extra properties at the type level — the “excess property check” that could catch {apple: 1.5, sample: "free"} only fires on direct object literal assignment. Indirect paths (like assigning through a variable) lose that check, and the extra sample property slips through. Flow's object types are exact by default: extra properties are always rejected.

3. TypeScript lets you push a wider value into a narrower mutable array

// TypeScript: accepted.
function appendError(errs: Array<string | Error>) {
  errs.push(new Error("oops"));
}
const errors: Array<string> = [];
appendError(errors);  // TS accepts. Flow rejects.
errors[0].toUpperCase();  // Runtime crash! `errors[0]` isn't a string

TypeScript treats Array<string> as a subtype of Array<string | Error> (mutable arrays are covariant in TS), so the call goes through and the push inside appendError adds an Error in the caller's string-typed array. Flow's mutable-array invariance blocks the widening at the call site. If the function doesn't actually need to mutate, the fix is ReadonlyArray<string | Error>: removing the possibility of mutation makes the widening safe.

4. Type-guard bodies aren’t validated in TypeScript

// TypeScript: accepted, but this body is true for numbers, not strings.
function isString(x: unknown): x is string {
  return typeof x === "number";  // TS accepts. Flow rejects.
}
const data: unknown = 1;
if (isString(data)) {
  data.toUpperCase();  // Runtime crash! `data` isn't a string
}

TypeScript checks the signature of a predicate, not the body. Flow validates the body in both directions: every return must actually refine to the guard type, and the negation must refine the guard type away. It rejects predicates that lie about what they check.

Read the full comparison

The full doc, Flow for TypeScript Users in 2026, has 20+ side-by-side Flow vs. TypeScript comparisons.

Flow for TypeScript Users in 2026 was originally published in Flow on Medium, where people are continuing the conversation by highlighting and responding to this story.

🌿 We are announcing Natural Inference for Flow, an improved way to infer types for primitive values, that resolves a long-standing correctness gap and source of confusion.

🌟 We are also introducing const-expressions and const-type parameters, two new features that can help address Flow errors related to this change.

What was the problem before?

Prior to Natural Inference, you could write the following code without Flow complaining

const shape = {
  type: 'circle',
  radius: 42,
};

if (condition) {
  shape.type = 'square'; // ⚠️ this was allowed
};
shape.type as 'circle'; // no error here ☹️
//    ^
//    hover type returns `string`

In other words, Flow allowed both

• the assignment of 'square' to shape.type, and
• the unsafe assertion that shape.type is still 'circle' in the end.

To add insult to injury, when hovering over shape.type Flow would show string, which was a lie, since a string-typed expression is not compatible with the type 'circle'.

How does Natural Inference fix this?

In code like the above, Flow will now truly infer the type {type: string, radius: number} for shape. This means that

• assigning shape.type = 'square' is still allowed, but
• asserting shape.type as 'circle' will now be an error.

This change comes at the cost of Flow potentially erroring in code that rightfully did not error before. For example, if we remove the update in the code above

const shape = {
  type: 'circle',
  radius: 42,
};

shape.type as 'circle';

Flow will still error because shape.type is truly inferred as a string. We will later see how to address this kind of errors.

How does Natural Inference work?

At the core of the outgoing problematic behavior was the internal type representation for string, number and boolean literal values. These types were a hybrid between the general primitive types (string, number, boolean), and the respective literal values as types (abc, 42, etc.). Flow would opportunistically pick either version of these type at each use-site, without ensuring they were used consistently.

Natural Inference fixes this by deciding on one of the two versions at the point where the literal is introduced (get assigned to a variable, gets passed to a function, etc.). This type is then used consistently for the rest of the program.

This decision mainly relies on the presence of type annotations around the literal. Some key rules are the following:

To see the rationale behind the last rule consider calls to React.useState:

const [state, setState] = React.useState('a');
setState('b');

Calls to setState will only be meaningful if they accept state as string, instead of the very restrictive 'a'.

Migration

Natural inference is available as of version 0.271.0 by adding the following line in the [options] section of the .flowconfig:

experimental.natural_inference.local_primitive_literals=full

In version 0.273.0 and forward it will be enabled by default.

How to fix errors caused by Natural Inference

Most new errors can be resolved by adding some annotation to guide inference around primitive values. Consider the following example:

type Shape = {
  type: 'circle',
  radius: number,
} | {
  type: 'square',
  side: number,
};

function takesShape(shape: Shape): void { ... };

The following call will now be an error

const circle = {
  type: 'circle',
  radius: 42,
};

takesShape(circle); // error: string (inferred type for "circle" value)
                    // is incompatible with both 'circle' and 'square' types

A. Fix with const-expressions [docs] 🌟

Use 'circle' as const to declare that you want 'circle' to be inferred as the singleton type 'circle'. This will allow circle to be inferred as the part of Shape that corresponds to a circle:

const circle = {
  type: "circle" as const,
  radius: 42,
}; // circle inferred as {type: 'circle', radius: number}

takesShape(circle); // okay

Note that as const can be used to annotate containers too (objects and arrays). Its effect is applied to the parts of the container.

For example, definitions that before looked like this

const ACTION = {
  SELL: 'SELL',
  BUY: 'BUY',
};

type ActionType = $Values<typeof ACTION>;

will now work as expected, ie. ActionType will be 'SELL'|'BUY', if ACTION is defined as

const ACTION = {
  SELL: 'SELL',
  BUY: 'BUY',
} as const;

Otherwise ActionType will just be string.

B. Fix using a type annotation

When an annotation like Shape is available, you can also use it to initialize circle:

const circle: Shape = {
  type: 'circle',
  radius: 42,
};

takesShape(circle); // okay

Note that Flow will infer 'circle' with its precise type so that the check of the initializer object against the annotation Shape succeeds.

C. Fix with Const-Type Parameters [Docs] 🌟

In some cases, it is useful to specify that an argument to a function is always expected to be a const-expression. You can do so by annotating the type parameter with the const modifier. For example, in

declare function takesConst<const X>(x: X): [X];
const x = takesConst({prop: 42});

Variable x will be inferred as [{+prop: 42}], instead of [{prop: number}] that we would otherwise get.

D. Annotate the Container

When adding elements, say strings, to a container, e.g. an array, then Flow will now infer a type based on the general form of the elements being added. Consider, for example

function foo(): $ReadOnlyArray<'a'|'b'> {
  const arr = [];
  arr.push('a');
  arr.push('b');
  return arr;
}

Flow used to not complain about this code, but did so in a problematic way, since the following signature was also allowed:

function foo(): $ReadOnlyArray<'a'> { ... }

Now, Flow will error in the above code, since it will truly infer the type Array<string> for arr. To fix this example, all you need to do is add an annotation to arr to indicate the target type of the array:

function foo(): $ReadOnlyArray<'a'|'b'> {
  const arr: Array<'a'|'b'> = [];
  arr.push('a');
  arr.push('b');
  return arr;
}

Flow Natural Inference for Primitives was originally published in Flow on Medium, where people are continuing the conversation by highlighting and responding to this story.

tl;dr: Mapped types allow you to transform object types into other object types. We have added definitions for Pick, Omit, and Record utility types to our library definitions. Docs here.

Mapped Types are enabled by default as of Flow v0.212. To use them, make sure you are following our recommended setup in our docs. Mapped Types (inspired by TypeScript) provide an elegant syntax for transforming object types:

type Obj = {
  foo: number,
  bar: string,
  baz: boolean,
};

type Accessor<+T> = () => T;

type ObjWithAccessors = {[key in keyof Obj]: Accessor<Obj[key]>};

function f(o: ObjWithAccessors): number {
  return o.foo();
}

In this example, ObjWithAccessors is a Mapped Type that turns each property of Obj into a function returning the type defined in Obj. It does this all without requiring you to list out the property names again, and changes to the definition of Obj will be reflected in ObjWithAccessors.

We’ve also implemented the highly requested utility types Pick, Omit, and Record using Mapped Types and Conditional Types. We’ve added them to our library definitions.

Mapped Types bring several improvements over $ObjMap, our previous solution for mapping object types:

1. The syntax is cleaner and easier to both read and write
2. The expressive power is increased, allowing you to add optionality and variance modifiers in addition to the value type transformation
3. The underlying representation is crisp and principled, which creates a more reliable and consistent experience

You can find documentation for the feature on our website.

Basic Usage

Mapped Types have syntax similar to indexed object types but use the in keyword:

type O = {foo: number, bar: string};
type Boxify<T> = {contents: T};
type MappedType = {[key in keyof O]: Boxify<O[key]>};

Combined with the keyof keyword, MappedType has all of the keys from O with all of the value types transformed by Boxify<O[key]>. The key variable is substituted for each key in O when creating the property, so this type evaluates to:

{
foo: Boxify<O['foo']>,
bar: Boxify<O['bar']>,
}
= {
foo: {contents: number},
bar: {contents: string},
}

In addition to transforming the value types, you can also add optionality and variance modifiers:

type ReadOnlyOptionalBoxes = {+[key in keyof O]?: Boxify<O[key]>};
// = {+foo?: {contents: number}, +bar?: {contents: string}

Generating Objects from Keys

You can also use mapped types to turn a string literal union into an object type by using in with a union of valid key types (no keyof needed!)

type Union = 'mapped' | 'types' | 'rock';
type Obj = {[key in Union]: number};
// = {mapped: number, types: number, rock: number}

Announcing: Mapped Types + Pick, Omit, and Record was originally published in Flow on Medium, where people are continuing the conversation by highlighting and responding to this story.

We have thousands of engineers committing React code every day to Meta’s largest codebases. Part of our responsibility on the Flow team is to make it as easy as possible for anyone to contribute, from design system React experts to C++ engineers making one-off internal pages to support their backend services. Over the last year, we’ve built several new language features to make it easier than ever to write high-quality React code, and we’ve built powerful new tools for design system owners to express their design constraints in the type system itself.

Flow is excited to announce Component Syntax, adding first-class support for React primitives such as components and hooks to the Flow language. These features bring improved ergonomics, expressiveness, and static enforcement for many of the Rules of React.

We’ve already adopted Component Syntax across all our codebases at Meta, and the results have been incredible: we’ve seen a massive reduction in boilerplate for writing components, we’ve caught thousands of violations of the Rules of React, and we’ve seen design systems codify their stylistic rules in the type system. Most importantly, our engineers love the new features. We’re excited to share these features with the broader community.

If you’re already using React in your own Flow projects, you can enable these new features by upgrading to Flow v0.233.0 or later.

None of this is required to use React, but if you’re already using Flow these features may be interesting to you.

Component Syntax Features

Component Syntax introduces several new features:

• New Component declaration. Dedicated syntax for defining components that is ergonomic to use, reduces boilerplate code, and provides greater safety by enforcing many of the Rules of React.
• New Hook declaration. Dedicated syntax for defining hooks that provides additional safety by enforcing the rules of hooks.
• Statically enforced Design System rules with render types. We’ve introduced render types, a powerful tool for design systems that makes it simple to express stylistic constraints through types.

A Tour of Component Syntax

Code today 😴

type Props = $ReadOnly<{
  text?: string,
  onClick: () => void,
}>;

export default function HelloWorld({
  text = 'Hello!',
  onClick,
}: Props): React.MixedElement {
  return <div onClick={onClick}>{text}</div>;
}

Component Syntax 🔥

export default component HelloWorld(
  text: string = 'Hello!',
  onClick: () => void,
) {
  return <div onClick={onClick}>{text}</div>;
}

The Basics

As you can see, components are quite similar to functions, but with a few differences:

• Replace the function keyword with component.
• Use individual params instead of a props object, specifying default values inline is supported.
  – This removes the duplication required when using object destructuring and removes the need for modifiers like $ReadOnly<{…}>.
• No return type is needed unless using render types. Flow enforces the returned value will always be a subtype of React.Node.

Full compatibility

Components are designed to fully replace their functional counterparts. To achieve this, we’ve added a few more features to support all prop types, include rest parameters, and props that use invalid JavaScript identifiers, as with html data attributes (data-<attr>).

export default component HelloWorld(
  'data-testid' as testid: string, // [1]
  ...otherProps: OtherProps // [2]
) {
  return <div data-testid={testid} {...otherProps} /></div>;
}

1. String props are allowed but must be renamed via as.
2. Creating props objects via rest params is also supported.

Improved Safety

Beyond the obvious syntactic advantages, Component Syntax also introduces new capabilities that allow Flow to better understand your code and enforce React best practices to help avoid common pitfalls. In the next sections we’ll cover a few of these features.

Ensuring props are deep read-only

One of the basic rules of React is that a component’s props shouldn’t be mutated. Historically, this behavior has been partially enforced by the common practice of wrapping prop types with $ReadOnly<>. With Component Syntax, all props are checked to ensure they are not mutated during render. This means that you won’t need to add $ReadOnly<> anymore (including on rest props), and you’ll get additional Flow coverage to ensure that properties are deeply protected from writes as well.

type Item = { 
  itemName: string,
  arr: Array<number>,
};
type OtherProps = {
  userId: number,
};

component UserItem(userItem: Item, ...props: OtherProps) {
  props.userId = 0; // Error: react-rule-unsafe-mutation
  userItem.itemName = "Cool New Laptop";  // Error: react-rule-unsafe-mutation

  const copiedObj = {...userItem};
  copiedObj.arr[0] = 3; // Error: Deep checking catches error through copied object
}

The last error above was particularly exciting for us to catch! We’ve seen many cases where the programmer clearly understood the Rules of React and would copy objects instead of mutating them directly, but they would still erroneously mutate values that were only aliased, not copied. Immutability can be subtle even for experienced developers.

This feature helps prevent a common class of bugs while removing the need for boilerplate that was previously universal. This feature does have its limits, though. At present Flow is only able to detect mutations of props in a component or hook, and we optimistically assume that method calls do not cause mutations.

Enforcing best practices with Refs

Another pattern we enforce in component bodies is that refs are not read or written to during render. This is another common pitfall that can lead to unintended behavior. Check out the React documentation for more information. Here is an example of this in action:

component MyComponent() {
  const renderCount = useRef<number>(0);
  renderCount.current += 1; // error
  return <div>{renderCount.current}</div> // error
}

In order to safely use refs in your components, you can read or write to refs from event handlers or effects instead:

component MyComponent() {
  const renderCount = useRef<number>(0);
  const [count, setCount] = useState(0);
  useEffect(() => {
    renderCount.current += 1; // ok
    setCount(renderCount.current); // ok
  }, [renderCount]);
  return <div>{count}</div>
}

In total, these features make it easier for programmers and reviewers to focus on the business logic instead of writing bug-free code. Let Flow sort out the details– you can focus on impact.

Hook Syntax

Hooks are another fundamental abstraction in React that can benefit from improved type checking validation. We’ve introduced the hook keyword that can be used in place of function when declaring custom hooks. This allows flow to enforce that hooks adhere to the React programming model:

• Hooks must be called in the same order on every render (which implies that hooks may not be called conditionally).
• Hooks must operate under the same restrictions as component bodies, such as not reading ref.current or mutating any passed in parameters.
• When called, hooks must obey the useFoonaming convention. For example, use_foo() or myHook() would lead to a flow error.
• As the converse of the above, non-hook functions used within components or other hooks should not have names that match the useFoo pattern.

Many of these rules are already enforced by React’s ESLint plugin, but we also apply the validations discussed in the components section to hooks.

As you can see from the examples below, the only change necessary to adopt hook syntax is to replace function with hook.

Code Today 😴

function useOnlineStatus(initial: boolean): boolean {
  const [isOnline, setIsOnline] = useState(initial);
  useEffect(() => {
    // ...
  }, []);
  return isOnline;
}

Hook Syntax 🔥

hook useOnlineStatus(initial: boolean): boolean {
  const [isOnline, setIsOnline] = useState(initial);
  useEffect(() => {
    // ...
  }, []);
  return isOnline;
}

Check out the hooks documentation for more information.

Render Types

Render types are a powerful new feature providing an ergonomic way to define how components should be composed. We designed render types to make working with component libraries safer and easier. At its core, render types consist of a new renders type annotation that can be used to specify what a component ultimately renders. Here is an example:

// Component library
export component Header() { ... }

export component Layout(
  header: renders Header,  // Library components can specify what props should render
) { ... }


// Product code
component MyHeader() renders Header { // Components can describe what they will ultimately render
  // ...
  return <Header />;
}

export component MyLayout() {
  // OK! MyHeader renders Header
  return <Layout header={<MyHeader />} />; 
}

Remember, not everyone at Meta who needs to write React code is a front-end expert. Design systems make it easy for people with relatively little experience to make beautiful cohesive UIs. Render types let the design system owners codify their design rules in the type system, which helps all the downstream users build even more delightful experiences without having to know much about UX or UI design.

With render types, you can also:

• Describe optional rendering, or rendering a list of items with the renders? and renders* variants.
• Use component names as shorthand for easily referring to component types. For example, Header is equivalent to React.Element<typeof Header>.

Check out the render types documentation for a lot more information on render types.

Try it out

To see Component Syntax in action or try it out for yourself, check out our example app on GitHub.

Conclusion

Component Syntax introduces a novel approach to building React UIs, offering enhanced type safety, readability, and developer efficiency. It reduces boilerplate for components, enforces React best practices, and allows developers to safely express common design-system patterns.

We designed component Syntax in coordination with the React team, and are already using it across our codebases at Meta. We plan to continue expanding Flow’s understanding of React in the future and improve safety and expressivity when working with React.

—

Written by Alex Taylor and Jordan Brown

New Flow Language Features for React was originally published in Flow on Medium, where people are continuing the conversation by highlighting and responding to this story.

Flow now lets you define a function that encodes a type predicate over its parameter. This predicate, which we refer to as a type guard, is annotated in place of a return type annotation as x is PredicateType. It declares that if the function returns true then its parameter x is of type PredicateType.

The syntax for such a function, similar to how it appears in TypeScript, is

function predicate(x: InputType): x is PredicateType {
  return <some_expression>;
}

The library definition for Array .filter has also been updated to recognize callbacks with type (x: Input) => x is PredType and refine arrays of type Array<Input> to Array<PredType>.

Background

The ability to use Array .filter to produce arrays with refined types has been one of the most commonly requested features in feedback that the team has gathered over the past several years.

Predicate functions based on the %checks annotation are not a good fit for higher order functions, such as Array’s .filter method, and so they do not support this use case. A feature that relies on typing, such as type guards, is a more natural way of expressing this refinement.

At the same time, the refinement based on %checks functions has been known to be hard-to-understand and spotty. Robust support for refining using function predicates is essential for a dynamic language like JavaScript.

Basic Usage

Let's see a simple example where we define a type guard function over a data type

type A = { type: "A"; data: string };
type B = { type: "B"; data: number };
type AorB = A | B;

function isA(value: AorB): value is A {
  return value.type === "A";
}

Function isA will return true if (and only if) its input value has type A. It can therefore be used to refine values of type AorB down to A:

function test(x: AorB) {
  if (isA(x)) {
    // `x` has now been refined to type A.
    // We can assign to it variables of type A ...
    const y: A = x;
    // ...and access A's properties through `x`
    const stringData: string = x.data;

    // As a sanity check, the following assignment to B will error
    const error: B = x;
  }
}

Array .filter

Flow now recognizes when you call filter on an array of type Array<T>, with a callback function with type (value: T) => value is S. It returns an array of type Array<S>. Note that S needs to be a subtype of the type of the array element T.

Here are some examples

const isNonMaybe = <A>(x: ?A): x is A => x != null;  

function filterNull(response: Array<?number>): Array<number> {
  return response.filter(isNonMaybe); // no error
}

// Using the definitions from above

function filterAs(response: Array<AorB>): Array<A> {
  return response.filter(isA); // no error
}

With proper filtering support, it is now possible to move away from the error-prone pattern of using arr.filter(Boolean) to filter out non-null values from array arr. Instead, a more correct arr.filter(isNonMaybe) can be used. The difference here is that Boolean will also remove from the array all falsy values (including for example 0, "", false), instead of just null and undefined.

Defining Type Guard Functions

Flow runs a number of checks to ensure that type guard functions respect their declared predicate. Most of them are unsurprising and you can find details about them in the docs.

The most interesting check is that of consistency of the declared predicate type with the check happening in the body of the function. Specifically Flow establishes two things:

1. The type of the refined parameter after the predicate of the return expression has been applied is a subtype of the guard type.
2. The refined parameter is not reassigned in the function body.

The following examples will be errors:

function numOrStrError(x: mixed): x is number | string {
  return (typeof x === "number"
       || typeof x === "boolean"); // error boolean ~> string
}

function isNumberError1(x: mixed): x is number {
  x = 1;
  return typeof x === "number"; // error x is written to
}

function isNumberError2(x: mixed): x is number { // error x is reassigned
  function foo() {
    x = 1;
  }
  foo();
  return typeof x === "number";
}

Note that TypeScript does not perform such check.

Migration From %checks

Developers are encouraged to convert existing instances of %checks to the more robust and feature-rich type guard syntax when possible.

This should be straightforward in most cases. For example,

const isA = (x: mixed): boolean %checks => x instanceof A;
const isNonMaybe = (x: mixed): boolean %checks => x != null;

can respectively be written as

const isA = (x: mixed): x is A => x instanceof A;
const isNonMaybe = <A>(x: ?A): x is A => x != null;

A couple cases where a larger refactoring needs to happen:

• %checks-functions that refine multiple input parameters, since type-guard syntax can only refine a single parameter. (try-Flow)
• Negations of complex predicates, since type-guards need to refer to the entire condition at once. See this code for example.

Adoption

See this section of our docs for what versions of tooling support the new syntax.

Announcing User Defined Type Guards in Flow was originally published in Flow on Medium, where people are continuing the conversation by highlighting and responding to this story.

Conditional types allow you to choose between two different output types by inspecting an input type. The syntax (inspired by TypeScript) is similar to a ternary expression:

type T = CheckType extends ExtendsType ? TrueType : FalseType;

If CheckType is a subtype of ExtendsType, the result is TrueType, otherwise it is FalseType.

We’ve also added new built-in utility types which make use of conditional types, like ReturnType<F>, Parameters<F>, Exclude<T, U>, and Extract<T, U>.

Basic Usage

The evaluating of the following conditional type is very similar to that of ternary expression:

CheckType extends ExtendsType ? TrueType : FalseType

You perform a type-level test of whether CheckType is a subtype of ExtendsType. If that’s the case, it will be evaluated to TrueType. Otherwise, it will be evaluated to FalseType.

As part of the same project, we also support infer types. Combined with generics, we can finally write down a utility type that reliably extracts the return type of a function:

type ReturnType<T: (...args: $ReadOnlyArray<empty>) => mixed> = 
  T extends (...args: $ReadOnlyArray<empty>) => infer Return 
    ? Return 
    : any;

New Utility Types

Advanced utility types like conditional types are generally not useful for product code, but it is very expressive to let us create utility types in the user land. With conditional types, we can now provide the following types as Flow built-ins, without any special-cased support:

• ReturnType<F>: Obtain the return type of a function type F. e.g. ReturnType<(string, number)=>boolean> = boolean
• Parameters<F>: Obtain the parameters of a function type F in a tuple. e.g. Parameters<(string, number)=>boolean> = [string, number]
• Exclude<T, U>: Exclude from T those types that are assignable to U. e.g. Exclude<1 | 2 | 3 | 4, 1 | 3> = 2 | 4
• Extract<T, U>: Extract from T those types that are assignable to U. e.g. Extract<Car | Dog | Cat, Animal> = Dog | Cat
• ThisParameterType<F>: Extracts the type of the this parameter of a function type F. e.g. ThisParameterType<(this: foo, bar: string) => void> = foo
• OmitThisParameter<F>: Removes the this parameter from a function type F. e.g. OmitThisParameterType<(this: foo, bar: string) => void> = (bar: string) => void

In addition, the Exclude type is necessary to power another long requested Omit type. Combined with mapped types, we hope to help you get rid of most of the confusing $Diff and $Rest, and $ObjMap type usages.

Fixed Array.flat typing

Through the distributive property of conditional type, we are finally able to fix the typing of Array.prototype.flat. Now, the following code is correctly inferred to have type Array<number>:

[1, [2, 3], 42, [65535]].flat()

Migration

The new utility types will be better replacements for most of the existing $Call use cases. In most cases, we found that people are using $Call only for extraction purposes. e.g.

type ExtractedPart = $Call<
  <T>(($ReadOnlyArray<$ReadOnly<{foo: {bar: T}}>>) => string) => T,
  SomeBigImportedType,
>;

can be rewritten as the following with much clearer intention with a combination of indexed access types and some of the new utility types:

type Extracted = Parameters<SomeBigImportedType>[0][number]['foo']['bar'];

Since conditional type is much clearer than $Call, we have deprecated $Call since v0.224.0. You can turn on deprecated-type lint to find all existing uses of $Call and replace them with appropriate types.

To support the new syntax, you need to update your version of Prettier, hermes-parser Babel plugin, hermes-eslint and more. Check out the adoption section in the docs for more details.

Announcing Conditional Types was originally published in Flow on Medium, where people are continuing the conversation by highlighting and responding to this story.

To make it easier for new users to get started with Flow, we’re updating our type casting syntax to use “as”, like TypeScript, Hack, Swift, and others. Say goodbye to the old colon-and-parens syntax:

// Before:
(1: number);
// After:
1 as number;

It’s safe, unlike TypeScript

Our new type casting syntax behaves just like the old one — no unsafe downcasts allowed, unlike TypeScript’s “as” cast:

const fooObj = {foo: 1};
// The following errors in Flow, but is allowed in TypeScript!
const otherObj = fooObj as {foo: number, bar: string};  // Uh oh
const s: string = otherObj.bar; // Oh dear

As before, and like TypeScript, “as” performs a type-checking cast, not a runtime one.

Adoption

To use the new as casting syntax, you need to update your tooling to support the new syntax:

• Flow and Flow Parser: 0.220+
• Prettier: 3.1+
• Babel: use the babel-plugin-syntax-hermes-parser plugin version 0.19+, see our Babel guide for more details.
• ESLint: use hermes-eslint plugin version 0.19+, see our ESLint guide for more details.

Update your codebase:

• Add “casting_syntax=both” to the “[options]” section of your .flowconfig (“both” will become the default value as of Flow version 0.229). This allows you to use both the old colon-cast and the “as” casting syntax.
• To codemod your code, get flow-upgrade version 2.3.0+, and run “yarn run flow-codemod typeCastToAsExpression”.
• When you have completed codemodding your codebase, you can update the option to “casting_syntax=as” — this will turn using the old casting syntax into an error, with a quickfix to the “as” casting syntax.
• At some point in the future we will remove the option and only support “as” casts, so code update your codebase!

New type casting syntax for Flow: “as” was originally published in Flow on Medium, where people are continuing the conversation by highlighting and responding to this story.

Documentation

Over the past 6 months, we’ve reviewed and updated almost every page of our documentation, and added new docs for features previously missing. If you’ve looked at our docs in the past and found them outdated, now is the time to take another look!

Some page highlights:

• The page on refinements has been completely redone to explain the different ways you can refine.
• We’ve added a page visualizing our type hierarchy:

After we enabled exact object types by default, Try Flow and all documentation examples have been updated to use exact object types by default.

Finally, our website is now built with Docusaurus — this should make loading and navigation snappy.

Try Flow

Try Flow now allows you to enable and disable options and Flow lints! This configuration is saved in the link you share (along with the Flow version you’ve selected). Select the “Config” tab on flow.org/try.

We’ll warn you if you open a link specifying an older version of Flow.

$FlowFixMe suppression comments and types now work in Try Flow.

Improved Flow Docs and Try Flow was originally published in Flow on Medium, where people are continuing the conversation by highlighting and responding to this story.

1. Labeled tuple elements: type T = [foo: number, bar: string]
2. Variance (read-only/write-only) annotations for tuple elements: type T = [+foo: number, -bar: string]
3. Optional tuple elements: type T = [foo?: number, bar?: string]
4. Tuple spread type T = [number, string, ...OtherTuple]
5. Refinement on tuple length

Read the full docs.

Labeled tuple elements

You can now add a label to tuple elements. Labels do not affect the type of the tuple element, but are useful in self-documenting the purpose of the tuple elements, especially when multiple elements have the same type.

type Range = [x: number, y: number];

Labels are also necessary to add variance annotations or optionality modifiers to elements.

Variance annotations on tuple elements and read-only tuples

You can add variance annotations (to denote read-only/write-only) on labeled tuple elements, just like on object properties:

type T = [+foo: number, -bar: string];

This allows you to mark elements as read-only or write-only. For example:

function f(readOnlyTuple: [+foo: number, +bar: string]) {
  const n: number = readOnlyTuple[0]; // OK to read
  readOnlyTuple[1] = 1; // ERROR! Cannot write
}

You can also use the $ReadOnly on tuple types as a shorthand for marking each property as read-only:

type T = $ReadOnly<[number, string]>; // Same as `[+a: number, +b: string]`

Optional tuple elements

You can mark tuple elements as optional with ? after an element’s label. This allows you to omit the optional elements. Optional elements must be at the end of the tuple type, after all required elements.

type T = [foo: number, bar?: string];
([1, "s"]: T); // OK: has all elements
([1]: T); // OK: skipping optional element

You cannot write undefined to the optional element - add | void to the element type if you want to do so:

type T = [foo?: number, bar?: number | void];
declare const x: T;
x[0] = undefined; // ERROR
([undefined]: T); // ERROR

x[1] = undefined; // OK: we've added `| void` to the element type

You can also use the Partial and Required utility types to make all elements optional or required respectively:

type AllRequired = [number, string];
([]: Partial<AllRequired>); // OK: like `[a?: number, b?: string]` now

type AllOptional = [a?: number, b?: string];
([]: Required<AllOptional>); // ERROR: like `[a: number, b: string]` now

Tuples with optional elements have an arity (length) that is a range rather than a single number. For example, [number, b?: string] has an length of 1-2.

Tuple type spread

You can spread a tuple type into another tuple type to make a longer tuple type:

type A = [number, string];
type T = [...A, boolean]; // Same as `[number, string, boolean]`
([1, "s", true]: T); // OK

Tuple spreads preserve variance and optionality. You cannot spread arrays into tuples, only other tuples.

Refinement on length

You can refine a union of tuples by their length:

type Union = [number, string] | [boolean];
function f(x: Union) {
  if (x.length === 2) {
    // `x` is `[number, string]`
    const n: number = x[0]; // OK
    const s: string = x[1]; // OK
  } else {
    // `x` is `[boolean]`
    const b: boolean = x[0];
  }
}

Technically this is not a newly added feature, but one not previously announced.

Adoption

To use labeled tuple elements (including optional elements and variance annotations on elements) and tuple spread elements, you need to upgrade your infrastructure so that it supports the syntax:

• flow and flow-parser: 0.212.0
• prettier: 3
• babel with babel-plugin-syntax-hermes-parser. See our Babel guide for setup instructions.
• eslint with hermes-eslint. See our ESLint guide for setup instructions.

Bonus: declare const & declare let

Flow now supports declare const and declare let (in addition to the existing declare var). These allow you to declare a variable with a type, but without an implementation. They are useful for writing library definitions or creating reproductions of issues in Try Flow, while using the modern const and let instead of the legacy var. Both declare const and declare let are block-scoped, like their non-declare equivalents.

if (cond) {
  declare const foo: number;
}
foo; // ERROR: cannot resolve `foo` (as it's block-scoped)

Announcing 5 new Flow tuple type features was originally published in Flow on Medium, where people are continuing the conversation by highlighting and responding to this story.