Flow Static Type Checker

Flow and TypeScript share significant overlap in syntax and vocabulary, including conditional types, mapped types, type guards, keyof, as const, unknown, and Readonly. While Flow's syntax has aligned closely with TypeScript over time, Flow often makes deliberate choices to provide stronger static guarantees, rejecting certain patterns that TypeScript allows but which might cause runtime errors or logic bugs.

Key Differences:

• React Integration: Flow features first-class syntax for React, specifically component, hook, and renders.
• Tooling Scope: Unlike tsc, the flow binary is a typechecker only and does not emit JavaScript. You must use separate build tools to compile Flow syntax to runtime JS.

Note: TypeScript claims in this documentation are verified against version 6.0.3 with strict enabled.

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');

In Flow, tuples and arrays are distinct types and are not interchangeable in most cases:

1. Array to Tuple: An Array<T> cannot be passed into a tuple because Flow cannot guarantee the array's length.
2. Tuple to Array: A tuple cannot be passed into an Array<T> because it would allow unsafe mutations like .push().
3. Tuple to ReadonlyArray: You can pass a tuple into a ReadonlyArray<T> type because mutation is disallowed.

TypeScript Comparison Note:

• Flow does not support spreading a tuple with optional elements in a way that TS does (Flow may error with invalid tuple arity).
• Flow requires labeled forms for optional unlabeled elements (e.g., [a: number, b?: string]), whereas TS allows [number, string?].
• Flow does not support the readonly [T, S] shorthand; use Readonly<[T, S]> instead.

const array: Array<number> = [1, 2];
const tuple: [number, number] = array; // Error!

const tuple2: [number, number] = [1, 2];
const readonlyArray: ReadonlyArray<number> = tuple2; // Works!

Flow enforces strict rules to prevent runtime crashes caused by this being undefined when a method is extracted or called.

1. Method extraction from Classes

Flow bans extracting methods from class instances to prevent them from being called without their original context.

• Error: [method-unbinding] ("Cannot get counter.incr because property incr cannot be unbound...")
• The Flow rewrite: Wrap the call in an arrow function to capture the this context.

2. this inside Object Literals

Flow bans the use of this inside object literal definitions to prevent unsafe extraction.

• Error: [object-this-reference]
• The Flow rewrite: Use the name of the object literal binding directly instead of this.

// 1. Class Method Extraction
class Counter {
  count: number = 0;
  incr(): number { return ++this.count; }
}
const counter = new Counter();
const tick = counter.incr; // ERROR: [method-unbinding]

const tickFixed = () => counter.incr(); // OK

// 2. Object Literal `this` usage
const counterObj = {
  count: 0,
  incr(): number { return ++this.count; } // ERROR: [object-this-reference]
};

// Correct Flow rewrite for object literals:
const counterObjFixed = {
  count: 0,
  incr(): number { return ++counterObjFixed.count; }
};
const tickObj = counterObjFixed.incr; // OK