niieani/typescript-vs-flowtype

Differences between Flowtype and TypeScript -- syntax and usability

TypeScript vs Flow

Both TypeScript and Flow are very similar products and they share most of their syntax with some important differences. In this document I've tried to compile the list of differences and similarities between Flowtype and TypeScript -- specifically the syntax, usage and usability.

Disclaimer

This document might be incomplete and/or contain mistakes and was last updated to describe TypeScript 3.7.0 and Flow 0.101.

I'm maintaining it in my spare time, so if you find mistakes, or learn about latest additions to either project, please help keep this repo up-to-date by contributing and editing this page.

Thanks!

Differences in usage and usability

Some of these differences are subjective (e.g. error readability), and I'd love to make this as scientific as possible — so please contribute to make it better. :)

	TypeScript	Flow
Leading Design Goal / North Star	identify errors in programs through a balance between correctness and productivity	enforce type soundness / safety
IDE integrations	top-notch: language server, built-in refactorings, type and typedoc information on hover, snappy go-to-definition	language server is a work in progress, some IDEs use the CLI and require saving the file to run the type-check, refactorings in alpha, only type information on hover, sketchy go-to-definition
type-checking speed (excluding transpilation)	benchmarks needed	benchmarks needed, in-depth description
autocomplete	both during declaration and usage feels instantaneous feels reliable	only for usage feels sluggish (often a second or more of delay) feels unreliable (sometimes does not show up at all)
expressiveness	great (since TS @ 2.1)	great
type safety	very good (7 / 10)	great (8 / 10)
specifying generic parameters during call-time (f<T>(x))	yes e.g.	yes (since Flow 0.72)
specifying generic parameters for type definitions	yes	yes
typings for public libraries	plenty of well maintained typings	a handful of mostly incomplete typings
unique features	autocomplete for object construction declarable this in functions (typing someFunction.bind()) large library of typings more flexible type mapping via iteration namespacing	variance existential types * (deprecated since 0.72) testing potential code-paths when types not declared for maximum inference $Diff<A, B> type
type spread operator	no (planned)	shipped >=0.42
support for nullish coalescing proposal	shipped > 3.7beta	yes
support for decorators proposal	yes, legacy proposal	only parsing of legacy proposal, no type-checking
support for extending built-in types	yes	no
userland plugins	basic, not effecting emitting yet (planned)	no
programmatic hooking	architecture prepared, work in progress	work in progress
documentation and resources	very good docs many books videos e-learning resources	incomplete, often vague docs
ease-of-understanding of errors	good	good in some, vague in other cases
transparency	meeting notes, leadership reasoning and roadmap happens mostly publicly	low transparency, roadmap developed behind closed doors
commercial support	no	no
nominal and structural typing	structural with plans to support nominal	mostly structural, nominal for classes and imported opaque type aliases
dynamic import types	import('module-name') since 2.9	undocumented $Exports<'module-name'>
utility size (not emitted JavaScript) (latest version)

Differences in syntax

bounded polymorphism

Flow

function fooGood<T: { x: number }>(obj: T): T {
  console.log(Math.abs(obj.x));
  return obj;
}

TypeScript

function fooGood<T extends { x: number }>(obj: T): T {
  console.log(Math.abs(obj.x));
  return obj;
}

Reference

https://flow.org/blog/2015/03/12/Bounded-Polymorphism/

maybe & nullable type

Flow

let a: ?string

// equivalent to:

let a: string | null | void

TypeScript

let a: string | null | undefined

Optional parameters implicitly add undefined:

function f(x?: number) { }
// is semantically the same as:
function f(x: number | undefined) { }
// and also same as (the `| undefined` is redundant):
function f(x?: number | undefined) { }

Optional properties implicitly add undefined

class A {
  foo?: string;
}

type casting

Flow

(1 + 1 : number);

TypeScript

(1 + 1) as number;

// OR (old version, not recommended):

<number> (1 + 1);

mapping dynamic module names

Flow

.flowconfig

[options]
module.name_mapper='^\(.*\)\.css$' -> '<PROJECT_ROOT>/CSSModule.js.flow'

CSSModule.js.flow

// @flow

// CSS modules have a `className` export which is a string
declare export var className: string;

TypeScript

declare module "*.css" {
  export const className: string;
}

Reference

• https://www.typescriptlang.org/docs/handbook/modules.html
• https://flow.org/en/docs/types/modules/

Exact/Partial Object Types

By default objects in Flow are not exact, i.e. they can contain more properties than declared, whereas in TypeScript they are always exact (must contain only declared properties). In future versions Flow plans to change this and make objects exact by default.

Flow

When using flow, { name: string } only means “an object with at least a name property”.

type ExactUser = {| name: string, age: number |};
type User = { name: string, age: number };
type OptionalUser = $Shape<User>; // all properties become optional

TypeScript

TypeScript is more strict here, in that if you want to use a property which is not declared, you must explicitly say so by defining the indexed property. It is possible to use dotted syntax to access indexed properties since TypeScript 2.2. This is mostly a design decision as it forces you to write the typings upfront.

type ExactUser = { name: string, age: number };
type User = { name: string, age: number, [otherProperty: string]: any };
type OptionalUser = Partial<ExactUser>; // all properties become optional

Reference

• https://flow.org/en/docs/types/objects/
• microsoft/TypeScript#2710

Importing types

Flow

import type {UserID, User} from "./User.js";
// equivalent:
import {type UserID, type User} from "./User.js";

TypeScript

TypeScript does not treat Types in any special way when importing.

import {UserID, User} from "./User.js";

typeof

Works the same in both cases, however Flow has an additional syntax to directly import a typeof:

Flow

import typeof {jimiguitar as GuitarT} from "./User";

// OR

import {typeof jimiguitar} from "./User.js";
type GuitarT = jimiguitar;

// OR (below also works in TypeScript)

import {jimiguitar} from "./User.js";
type GuitarT = typeof jimiguitar;

TypeScript

import {jimiguitar} from "./User";
type GuitarT = typeof jimiguitar;

Restrictive type

When you don't know a type, commonly you would use any type. A restrictive type accepts anything, like any but in order to use that variable you must ensure values type by refining it.

Flow

mixed

function stringifyNum(num: number) {
  // Do stuff
}

function stringify(value: mixed) {
  if (typeof value === 'string') {
    return '' + value; // Works!
  }
  if (typeof value === 'number') {
    return stringifyNum(value); // Works!
  }
  return '';
}

Reference: https://flow.org/en/docs/types/mixed/

Typescript

unknown

function stringifyNum(num: number) {
  // Do stuff
}

function stringify(value: unknown) {
  if (typeof value === 'string') {
    return '' + value; // Works!
  }
  if (typeof value === 'number') {
    return stringifyNum(value); // Works!
  }
  return '';
}

Reference: https://github.com/Microsoft/TypeScript/wiki/What%27s-new-in-TypeScript#new-unknown-top-type

Accessing the type of a Class

Classes are typed, so you don't need to define an explicit type for them. If you want to reference the type, you can do it the following way:

Flow

class Test {};
type TestType = typeof Test;

const instance = new Test();
type TestTypeFromInstance = Class<typeof instance>;

TypeScript

class Test {};
type TestType = typeof Test;

Nominal typing

Flow treats classes as nominal types, whereas TypeScript treats them as structural types.

Flow

class Foo {};
class Bar {};

const foo: Foo = new Bar();
// Cannot assign `new Bar()` to `foo` because `Bar` [1] is incompatible with `Foo` [2].

TypeScript

class Foo {};
class Bar {};

const foo: Foo = new Bar();
// No errors!

You can work around this with tricks like the following (declare only works in TypeScript >=3.7.0):

class Foo {
    declare private __nominal: void;
};
class Bar {
    declare private __nominal: void;
};

const foo: Foo = new Bar();
// Type 'Bar' is not assignable to type 'Foo'.
// Types have separate declarations of a private property '__nominal'.(2322)

Keys/Props Of Type

Flow

var props = {
  foo: 1,
  bar: 'two',
  baz: 'three',
}

type PropsType = typeof props;
type KeysOfProps = $Enum<PropsType>;

function getProp<T>(key: KeysOfProps): T {
  return props[key]
}

TypeScript

var props = {
  foo: 1,
  bar: 'two',
  baz: 'three',
}

type PropsType = typeof props
type KeysOfProps = keyof PropsType;

function getProp<T>(key: KeysOfProps): T {
  return props[key]
}

Records

Flow

type $Record<T, U> = {[key: $Enum<T>]: U}
type SomeRecord = $Record<{ a: number }, string>

TypeScript

type SomeRecord = Record<{ a: number }, string>

Lookup Types

Flow

type A = {
  thing: string
}

// when the property is a string constant use $PropertyType (i.e. you know it when typing)
type lookedUpThing = $PropertyType<A, 'thing'>

// when you want the property to be dynamic use $ElementType (since Flow 0.49)
function getProperty<T : Object, Key : string>(obj: T, key: Key): $ElementType<T, Key> {
    return obj[key];
}

Reference:

• facebook/flow#2952 (comment)
• https://github.com/facebook/flow/commit/968210c5887b5bdd47d17167300033d1e1077d1a
• facebook/flow#2464 (comment)
• flow/try

TypeScript

Arguably, it's a bit easier to type both cases in TS, since they follow the same pattern.

type A = {
  thing: string
}

type lookedUpThing = A['thing']

// and...

function getProperty<T, K extends keyof T>(obj: T, key: K) {
    return obj[key];  // Inferred type is T[K]
}

function setProperty<T, K extends keyof T>(obj: T, key: K, value: T[K]) {
    obj[key] = value;
}

Reference:

• https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-1.html
• facebook/flow#2310

Type-narrowing functions

These are functions that return a boolean, performing some logic to assert that a given input parameter is of a certain type.

The implementations differ between Flow and TypeScript:

In TypeScript, it ensures the mapping between: true and value is T, versus in the case of Flow, it ensures the value is "checked" against the logic within the body of the function (i.e. things like typeof, instanceof, value === undefined).

This means you cannot tell Flow that the tested parameter is of an arbitrary type, which closes the door to complex cases, e.g.:

• reusing logic from a different function
• library definitions, where there is no body at all (it is possible to specify the body in the declaration, however you are still limited by the type of assertions you may specify)

Flow

function isNil(value: mixed): boolean %checks {
  return value == null;
}

const thing = null;

if (!isNil(thing)) {
  const another = thing.something;
}

Reference:

• flow/try

Caveats

The current implementation in Flow is incomplete, which means you cannot yet use %checks in class methods.

Example showing the limitation in the respective playgrounds: TypeScript vs Flow

TypeScript

Type-narrowing functions are called type guard functions in TypeScript.

function isNil<T>(value: T | null): value is null {
  return value == null;
}

const thing: any = null;

if (!isNil(thing)) {
  const another = thing.something;
}

Getting the type of a function call return value

Flow

$Call utility type:

type Fn1 = <T>(T) => T;
type E = $Call<Fn1, number>;

declare var e: E; // E is number
(42: E); // OK

Reference: https://github.com/facebook/flow/commit/ac7d9ac68acc555973d495f0a3f1f97758eeedb4

TypeScript

ReturnType utility type:

type fn1<T> = (a: T) => T;

type E = ReturnType<fn1<number>>;

var e: E; // E is number

Mapped Types / Foreach Property

Flow

type InputType = { hello: string };
type MappedType = $ObjMap<InputType, ()=>number>;

Reference:

• https://gist.github.com/gabro/bb83ed574690645053b815da2082b937
• https://twitter.com/andreypopp/status/782192355206135808

TypeScript

A bit more flexibility here, as you have access to each individual key name and can combine with Lookup types and even do simple transformations.

type InputType = { hello: string };
type MappedType = {
  [P in keyof InputType]: number;
};

Function and method overloading

Flow

It is possible to declare multiple signatures for the same method (also called: overloading). This feature is undocumented, and only available in type declarations (.js.flow files or module statements), not inline/alongside your code.

declare function add(x: string, y: string): string;
declare function add(x: number, y: number): number;

declare class Adder {
  add(x: string, y: string): string;
  add(x: number, y: number): number;
}

However, it's possible to create function overloads inline for functions outside of classes, by using additional declarations.

declare function add(x: string, y: string): string;
declare function add(x: number, y: number): number;
function add(x, y) {
  return x + y;
}

add(1, 1); // Ok
add("1", "1"); // Ok
add(1, "1"); // Error

It is also possible to create function overloads using callable property syntax, see the section Object callable property.

TypeScript

TypeScript supports both function and method overloading, in both: type definitions (.d.ts) and inline alongside code.

class Adder {
  add(x: string, y: string): string;
  add(x: number, y: number): number;
  add(x, y) {
    return x + y;
  }
}


function add(x: string, y: string): string;
function add(x: number, y: number): number;
function add(x, y) {
  return x + y;
}

Read-only Types

Flow

type A = {
  +b: string
}

let a: A = { b: 'something' }
a.b = 'something-else'; // ERROR

TypeScript

type A = {
  readonly b: string
}

let a: A = { b: 'something' }
a.b = 'something-else'; // ERROR

One caveat that makes TypeScript's readonly less safe is that the same non-readonly property in a type is compatible with a readonly property. This essentially means that you can pass an object with readonly properties to a function which expects non-readonly properties and TypeScript will not throw errors: example.

"Impossible flow" type

Flow

empty

function returnsImpossible() {
  throw new Error();
}

// type of returnsImpossible() is 'empty'

TypeScript

never

function returnsImpossible() {
  throw new Error();
}

// type of returnsImpossible() is 'never'

Difference types

Flow

type C = $Diff<{ a: string, b: number }, { a: string }>
// C is { b: number}

It only works properly as lower bound, i.e. you can assign something to it, but can't use it after that.

(source)

Flow also has $Rest<>, which represents the result of the JS object rest operator ({ ...rest }).

type Props = { name: string, age: number };

const props: Props = {name: 'Jon', age: 42};
const {age, ...otherProps} = props;
(otherProps: $Rest<Props, {|age: number|}>);
otherProps.age;  // Error, since we removed it

Typescript

You can define your own filter type, but it does not have a helper type for that.

class A {
  a: string;
  b: number;
}

class B {
  a: string;
  c: boolean;
}

type Omit<T, U> = Pick<T, Exclude<keyof T, keyof U>>;
//  

type C = Omit<A, B>;
// C is { b: number }

However, Flow implementation is stricter in this case, as B have a property that A does not have, it would rise an error. In Typescript, however, they would be ignored.

Same syntax

Most of the syntax of Flow and TypeScript is the same. TypeScript is more expressive for certain use-cases (advanced mapped types with keysof, readonly properties), and Flow is more expressive for others (e.g. $Diff).

Object callable property

The basic syntax are the same, except Flow has special syntax for the internal call property slot.

Both can be used to annotate function statics.

Flow

You can use objects with callable properties as functions: Try Flow

type F = {
  (): string
};
const f: F = () => "hello";
const hello: string = f();

An overloaded function is a function with multiple call signatures. This is supported by Flow. And we list out the different syntaxes here: Try Flow

type F = {
  (): string,
  [[call]]: (number) => string,
  [[call]](string): string
}

const f: F = (x?: number | string) => {
  return x ? x.toString() : '';
}

Use call property to annotate function statics: Try Flow

type MemoizedFactorialType = {
  cache: {
    [number]: number,
  },
  [[call]](number): number,
}

const factorial: MemoizedFactorialType = n => {
  if (!factorial.cache) {
    factorial.cache = {}
  }
  if (factorial.cache[n] !== undefined) {
    return factorial.cache[n]
  }
  factorial.cache[n] = n === 0 ? 1 : n * factorial(n - 1)
  return factorial.cache[n]
}

Reference:

• Callable Objects
• immer.js uses it to overload the produce (default export) function which has multiple call signatures
• Styled Components uses it to separate cases of being called on a string and wrapping a component
• Reselect Library Definition contains massive chunks of overloaded call properties

TypeScript

You can use objects with callable properties as functions: TypeScript Playground

type F = {
  (): string;
}
const foo: F = () => "hello";
const bar: string = foo();

An overloaded function is a function with multiple call signatures. This is also supported by TypeScript: TypeScript Playground

type F = {
  (): string,
  (x: number): string,
  (x: string): string
}

const f: F = (x?: number | string) => {
  return x ? x.toString() : '';
}

Use call property to annotate function statics: TypeScript Playground

type MemoizedFactorialType = {
  cache?: {
    [n: number]: number,
  },
  (n: number): number,
}

const factorial: MemoizedFactorialType = n => {
  if (!factorial.cache) {
    factorial.cache = {}
  }
  else if (factorial.cache[n] !== undefined) {
    return factorial.cache[n]
  }
  factorial.cache[n] = n === 0 ? 1 : n * factorial(n - 1)
  return factorial.cache[n]
}

Reference:

• Callable on TypeScript Book

optional parameters

Flow and TypeScript

The syntax in either tool is the same - question mark: ? suffixing the parameter name:

function(a?: string) {}

call-time generic parameters

In TypeScript and Flow (since version 0.72) you may use specify the type of a generic when calling the generic function or the constructor.

const set = new Set<string>();

Or using a more complex behavior:

function makeTgenerator<T>() {
  return function(next: () => T) {
    const something = next();
    return something;
  }
}

const usage = makeTgenerator<string>()
// 'usage' is of type: (next: () => string) => string

Typing pure JS files (i.e. without transpilation)

Flow

Flow supports a comment-based syntax, by encapsulating type annotations in /* */-style comments:

const f = (x /*: number */, y /*: number */) /*: number */ => x + y

TypeScript

TypeScript can check types with JavaScript files annotated with JSDoc comments:

// JSDoc type syntax
/** @type {function(number, number): number} */
const f = (x, y) => x + y
// equivalent TypeScript type syntax
/** @type {(x: number, y: number) => number} */

JSDoc's overloaded function comment syntax is not supported:

/**
 * @param {string} input
 * @returns {string} result
 *//**
 * @param {number} input
 * @returns {string} result
 */
function notSupported(input) { /* omit */ }

However, we can express function overloading type in TypeScript's form in a tricky way:

/** @type {{
            (): void;
            (code: 0): void;
            (code: 1, msg: string): void
          }} */
const functionOverloads = (
  /** @type {0 | 1} */ code = 0,
  /** @type {string | undefined} */ msg = code === 0 ? undefined : ""
) => { /* omit */ }

However, it still lacks some features:

1. There is no way to pass type parameter when invoking generic functions.
2. TypeScript cannot parse conditional types in JSDoc comments correctly. #27424
3. There is no equivalent form of as const assertion. #30445

TypeScript-only concepts

Declarable arbitrary this in functions (outside of objects)

function something(this: { hello: string }, firstArg: string) {
  return this.hello + firstArg;
}

Private and Public properties in classes

class SomeClass {
  constructor(public prop: string, private prop2: string) {
    // transpiles to:
    // this.prop = prop;
    // this.prop2 = prop2;
  }
  private prop3: string;
}

Non-null assertion operator

Add ! to signify we know an object is non-null.

// Compiled with --strictNullChecks
function validateEntity(e?: Entity) {
  // Throw exception if e is null or invalid entity
}

function processEntity(e?: Entity) {
  validateEntity(e);
  let s = e!.name;  // Assert that e is non-null and access name
}

Conditional Typing

type XorY<T, U> = T extends U ? X : Y;

This alone, introduces new helper types, or types aliases.

type Exclude<T, U> = T extends U ? never : T;

/**
 * Extract from T those types that are assignable to U
 */
type Extract<T, U> = T extends U ? T : never;

/**
 * Exclude null and undefined from T
 */
type NonNullable<T> = T extends null | undefined ? never : T;

/**
 * Obtain the return type of a function type
 */
type ReturnType<T extends (...args: any[]) => any> =
    T extends (...args: any[]) => infer R ? R : any;

Mapped Type Modifiers

You can use + and - operators to modify mapped types.

type Mutable<T> = {
  -readonly [P in keyof T]: T[P]
}

interface Foo {
  readonly abc: number;
}

// 'abc' is no longer read-only.
type TotallyMutableFoo = Mutable<Foo>

Helper type modifiers

Required is a type mapper to make all properties of an object to be required.

Partial is a type mapper to make all properties of an object to be optional.

Readonly is a type mapper to make all properties of an object to be readonly.

Flow-only concepts

Inferred existential types

* as a type or a generic parameter signifies to the type-checker to infer the type if possible

Array<*>

However this type was deprecated in Flow 0.72.

TypeScript proposal

Variance

https://flow.org/en/docs/lang/variance/

function getLength(o: {+p: ?string}): number {
  return o.p ? o.p.length : 0;
}

TypeScript proposal

Bivariance is among the design decisions driving TypeScript.

Opaque Type Alias

https://flow.org/en/docs/types/opaque-types/

opaque type Alias = Type;
opaque type Alias: SuperType = Type; // with subtyping constrains

Within the same file the opaque type alias is defined, opaque type aliases behave exactly as type aliases.

Outside the defining file, i.e. when importing an opaque type alias, it behaves like a nominal type. If the opaque type alias is defined with subtyping constrains, it can be used as the super type when outside the defining file.

export opaque type Age: number = number;

function newAge(age: number): Age {
    return age; // ok within same file, not ok outside defining file
}

function incAge(age: Age): number {
    return age + 1; // ok
}

TypeScript dose not have opaque type, but we can define an utility type with intersection type to mimic the behavior of Flow's opaque type alias with subtyping constrains used outside the defining file.

type Opaque<T, U> = U & { readonly __TYPE__: T }
type Age = Opaque<'age', number>

function newAge(age: number): Age {
    return age; // not ok
}

function incAge(age: Age): number {
    return age + 1; // ok
}

Object type spread

Object type spread acts as object spread but for types. Unlike intersection types type spreads work with exact object types and overwrite existing properties.

type Foo = {| foo: string, bar: string |}
type Bar = {| bar: number |}

type FooBarIntersection = Foo & Bar
type FooBarSpread = {| ...Foo, ...Bar |}

const fooBarInterect: FooBarIntersection = { foo: '123', bar: 12 } // not ok
const fooBarString: FooBarSpread = { foo: '123', bar: 'string' } // not ok
const fooBar: FooBarSpread = { foo: '123', bar: 12 } // ok

While TypeScript does understand object spread, the support for object type spread is not implemented.

Useful References

• microsoft/TypeScript#1265
• Undocumented Flow modifiers facebook/flow#2464
• http://sitr.us/2015/05/31/advanced-features-in-flow.html

typescript-vs-flowtype's Issues

Adding overloading functions / methods?

They exist in both Flow and TypeScript. Though in Flow they are trickier to use, and there is no class method overloading as a non declared class.

Infinite loop detection

Where should I add something like this?

TypeScript:

function hello(): never { // ok
  while(true) {}
}

Flow:

function hello(): empty { // error, void is incompatible with empty
   while(true) {}
}

type spread operator

Could you clarify, what you mean by type spread operator?

Flowtype has extensive linting support through ESLint eslint-plugin-flowtype

Might worth including in comparison that unlike TypeScript (?), FlowType has extensive linting support through ESLint https://github.com/gajus/eslint-plugin-flowtype plugin.

Flow released roadmap

https://medium.com/flow-type/what-the-flow-team-has-been-up-to-54239c62004f

Write more about Object definition differences for the same code

[DRAFT]

In TS you don't get "loose" properties on your objects, since you can't assign more than your definition expects:

/* @flow */
type NonExact = {}
const a : NonExact = { extraProp: '123' } // error in TS, error in Flow if: type Exact = $Exact<{}>

TS's above object's-exact-by-default stance might get you to design better APIs, unless you want to go and slap $Exact everywhere in your Flow code. This doesn't mean Flow is less-type-safe, it's just that this default is less safe than in TS. There are other cases where the opposite is true (TS's defaults being weaker-typed) then Flow.

Update with TypeScript 3 features

I'm open this to remind myself to do so when TS3 comes out in July. The new language feature I really want from this release is the new unknown type. I think it will behave just like mixed type in Flow, so this should be a good place to discuss this too.

---

Thanks for having this excellent post about the similarities between TS and Flow.

Write about Flow not accepting more strict Arrays

function test(param : Array<number | string>) {
  return param
}

const compatibleVar : Array<number> = [1, 2, 3]

test(compatibleVar)

This works properly in TypeScript, but fails in Flow with the error:

3: function test(param : Array<number | string>) {
                                        ^ string. This type is incompatible with
7: const compatibleVar : Array<number> = [1, 2, 3]
                                ^ number

More links

Hi. Thank you for this document, it is very helpful.

I want to share some links to the similar repos:

• utility-types - Utility Types for TypeScript (provide migration from Flow's Utility Types). Kind of similar project.
• type-o-rama - JS type systems interportability
• https://github.com/tycho01/typical
• https://github.com/pelotom/type-zoo
• https://github.com/pelotom/hkts
• https://github.com/andnp/SimplyTyped

Benchmark performance

As mentioned in #16 (comment), it would be great to have single-file and multi-file typechecking performance comparisons.

TypeScript: partial type argument inference using the *

Add this link
microsoft/TypeScript#26349

Document contravariance and covariance

Flow supports contravariance (-), TypeScript doesn't.

Also, TypeScript doesn't support covariance (+) on all its types, but just some of them.

TypeScript speed does not "continue to be fast regardless of the size of the project"

See microsoft/TypeScript#13538

Miss important factor: Language services / language server protocol support

I don't know about flow but you forgot to mention an important aspect about TypeScript. Is more than a language, is a language server, similar to LSP (https://github.com/Microsoft/language-server-protocol)) but on its own. General users won't use that API, but TS architecture force users to use their server (tsserver) running in the IDE / editor. This new concept although could seem not KISS, I think in part is why TS UX is faster than flow cause server is managing the project. Also as user you can develop a plugin for refactor, suggestion, folding, fixes, etc and it will work out of the box on any IDE supporting tsserver,

Although there are no much plugins today and ts team is advancing slowly in this aspect I think is a good idea. Perhaps in time will be obsolete in favor of LSP, who now . I'm learning how to use TS Compiler API myself because I want refactor plugins like those you have in other strongly typed languages / IDEs ike Java/eclipse (like move this method to this other class) and these are some I have (WIP) https://github.com/cancerberoSgx/typescript-plugins-of-mine/tree/master/typescript-plugin-proactive-code-fixes

In the future, perhaps now, flow could tackle this implementing LSP (probably there is already one) but TS is in advantage because tsserver API is very close to the language and LSP is more generic since it needs to support all. On the other hand, depending on a server for managing the project could have negative consequences in large projects performance IMO

I think this aspect is very interesting in the comparison too.Nice work, keep it up, couple of links:

https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API
https://github.com/Microsoft/TypeScript/wiki/Standalone-Server-%28tsserver%29
https://github.com/Microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin

[WIP] Those little things, both systems

They don't make or break a deal, but a load of those little thing does add up... like:

TS:

• badass autocomplete with literals microsoft/TypeScript#13789

Flow:
...

Question: does Flow support dynamic import types

TypeScript 2.9 introduced a dynamic import() type feature. View Blog Post

Is there an equivalent in Flow?

Not up-to date comparison

Obviously, it's hard to keep staying on the bleeding edge, so it's understandable the table doesn't contain most up-to-date features. Thanks for you work anyway.
I think there's a a low-hanging fruit to help improving the situation, though.

Proposal: add latest versions compared (would be great to add date, month/year is enough).
Unfortunately, I'd not offer help with a PR here, because people who wrote existing things, know that better.

Mention References for Flow and TypeScript

Flow:

• https://medium.com/@raxwunter/secret-flow-types-86b2ebb30951#.u7j5ieab3
• https://github.com/facebook/flow/blob/master/src/typing/type_annotation.ml#L163
• http://www.saltycrane.com/blog/2016/06/flow-type-cheat-sheet/
• https://twitter.com/nodkz/status/870629967738155010
• https://www.youtube.com/watch?v=WgvAPzOmiP0
• https://qiita.com/coizmo/items/21578b7d13819bb26fc3#_reference-d4f1712e3e2a18b823ef
• https://qiita.com/kinzal/items/e1898c89af5618e18334#_reference-afb4a1e9c90d42e7cc28
• https://qiita.com/kinzal/items/8e2978be3ec78663c70b#_reference-5b1da19d077e0f5e7bfe

Both:

• https://redditblog.com/2017/06/30/why-we-chose-typescript/

Add objective error quality comparison

Flow 66 improved a lot error messages

https://medium.com/flow-type/better-flow-error-messages-for-the-javascript-ecosystem-73b6da948ae2

I think it got better than Typescript

Expand on "typings for public libraries"

TS: plenty of well maintained typings
Flow: a handful of mostly incomplete typings

For flow, this may be true for libraries but is an understatement for typings. Maybe this can be expanded to reference definitely-typed vs flow-typed.

Flow-typed is definitely lagging behind, but there's definitely support for commonly used libraries.

Typescript Enum

Typescript enums feature is very useful.
Its much better than literal types in most cases.
Its much easier to maintain. Renaming an enum value is possible out of the box, while a literal type requires a full project text search.

Mention lookup type differences

TypeScript's lookup types are quite a bit more powerful. The examples in the 2.1 release notes are not possible in flow yet.

import type {} ... now supported by TypeScript

Doc needs to reflect this change.

Add diff type for typescript

Now we can add diff type to the TS section

type Diff<T extends string, U extends string> = ({[P in T]: P } & {[P in U]: never } & { [x: string]: never })[T];  

New compiler flag will make TypeScript check function arguments contravariantly

Once this PR is merged: microsoft/TypeScript#18654

Install Size comparison

I would like to add a row to compare the npm install size of TS vs Flow.

Would you like me to use the versions listed in the readme (TypeScript 2.6 and Flow 0.65) or use the latest versions?

	TypeScript	Flow
Install Size (old)
Install Size (latest)

TypeScript 2.7 and 2.8 features

We need to update the readme to add the latest features from TS 2.7 and 2.8.

Help appreciated!

Mention external projects trade-offs

TS-only:

• using Closure Compiler thanks to type annotations https://github.com/angular/tsickle
• runtime type checking https://github.com/gcanti/io-ts

Flow-only:

• runtime type checking https://codemix.github.io/flow-runtime (future also possibly TS)

Remove "type-checking speed" sine it adds no value and might confuse people

The notes themselves say it:

(w/o transpilation, subjective, need benchmarks!)

Avik from the flow team mentioned its speed degrades with the number of files added about a year ago. These are all the facts.

1. This doesn't imply this is not the case with TypeScript (and in fact, it's not unlikely it is, given it's the most straightforward way to design a type-checker).
2. This doesn't imply it is still like this (the talk was from almost a year ago, and he mentioned they were looking to change this back then).
3. This gives no valuable information; if the speed of my software stays the same no matter how many files you throw at it, but that speed is a constant 5 days, yet there's other software that gets slower the more files you add, but it would need to be dealing with 50 billion files before taking 5 days to run, the time complexity at which the software runs is not enough to make an informed decision. This is an extreme example but benchmarks are everything.

Given there's no information whatsoever to compare the two, I do think it'd be better to delete this section to avoid misunderstanding and misguidance until someone builds a benchmark for both.

Expand on the generic function usage possible in TypeScript, but not in Flow

TypeScript allows for more powerful usage of generics by defining type instance during function invocation. To my knowledge, this is not possible with Flow, as it always needs to infer the generic types from usage, although I'd love to be proven wrong here.

Some mistakes

Some mistakes I found:

type safety can't be great for both. If Flow is great then TypeScript should be good.

Flow has never type, but it's called empty.

(1 + 1 : number) is not the same as (1 + 1) as number. It is 100% safe operation. Flow's equivalent for type assertions is ((x:any): number).

By default objects in flow are not strict, whereas in TypeScript they are always strict, unless set as partial.

That's not true, object type has the same semantics in Flow and TypeScript.

The TypeScript equivalent should be: type mixed = string | number | boolean

This is incorrect, mixed is a supertype of all types, not just primitives. The closest thing in TypeScript is type mixed = {};.

Lookup Types

In Flow:

type A = {
  thing: string
}


type lookedUpThing = $PropertyType<A, 'thing'>

Read-only Types

In Flow:

type A = {
   +b: string
}

let a: A = { b: 'something' }

Write about myths and misconceptions

mention some myths:

• easier to convert to when using flow
• flow better with React
• TS is different language vs Flow only adds typings

specifying generic parameters during call-time is available in flow 72

specifying generic parameters during call-time is available

https://github.com/facebook/flow/releases/tag/v0.72.0

Explicit type arguments in new and call expressions, e.g., f(x).

conditional typing in Flow

https://github.com/niieani/typescript-vs-flowtype#conditional-typing

You can the same, check this helper: https://gist.github.com/miyaokamarina/934887ac2aff863b9c73283acfb71cf0

type $If<X: boolean, Then, Else = empty> = $Call<
    & ((true, Then, Else) => Then)
    & ((false, Then, Else) => Else),
    X,
    Then,
    Else,
>;

type $Not<X: boolean> = $If<X, false, true>;
type $And<X: boolean, Y: boolean> = $If<X, Y, false>;
type $Or<X: boolean, Y: boolean> = $If<X, true, Y>;

type $Gte<X, Y> = $Call<
    & ($Subtype<X> => true)
    & (mixed => false),
    Y,
>;

////

declare var a: $Gte<number, string>;

/* error  1 */ (a: true);
/* ok       */ (a: false);

declare var b: $Gte<number, number>;

/* ok       */ (b: true);
/* error  2 */ (b: false);

declare var c: $If<true, 1, 2>;

/* ok       */ (c: 1);
/* error  3 */ (c: 2);

declare var d: $If<false, 1, 2>;

/* error  4 */ (d: 1);
/* ok       */ (d: 2);

////

declare var e: $If<$Gte<number, string>, 1, 2>;

/* error  5 */ (e: 1);
/* ok       */ (e: 2);

declare var f: $If<$Gte<number, number>, 1, 2>;

/* ok       */ (f: 1);
/* error  6 */ (f: 2);

////

type IsNumber<X> = $Gte<number, X>;

type NumberTo12<X> = $If<IsNumber<X>, 1, 2>;

declare var g: NumberTo12<string>;

/* error  7 */ (g: 1);
/* ok       */ (g: 2);

declare var h: NumberTo12<number>;

/* ok       */ (h: 1);
/* error  8 */ (h: 2);

Document Flow opaque types

There's no mention of Flow opaque types.

https://flow.org/en/docs/types/opaque-types/