Reflow

> Babel plugin to transpile Flow types to
> TypeScript with CLI wrapper.

!Tests

#### I would love to receive feedback whether this plugin worked for you :)!

Reflow enables you to migrate a whole Flow based project to TypeScript by
transpiling the Flow type annotations to equivalent TypeScript code. While this
reduces the effort to move a large code base to TypeScript drastically, it is
still very likely that you will face new type errors after the migration due to
the differences between Flow and TypeScript. See this
repository for an excellent
overview of the differences and similarities of Flow and Typescript.

Why another plugin?

Of course, I am aware that other approaches exist to translate Flow to
TypeScript. For instance, there is
Kiikurage/babel-plugin-flow-to-typescript
and
Khan/flow-to-ts.
When I started this project in the course of my master thesis in February 2019,
the development of the first plugin seemed inactive and the second one did not
exist yet. Therefore this plugin was developed to solve the given problem of the
thesis in practice.

Advantages of Reflow

- can be used either as standalone Babel plugin or through the included CLI to
transpile whole code bases
- well tested with high code coverage
- proven to work with real React based projects (two code bases with 27 and 41
kLOC respectively were successfully migrated)
- generates well formatted output based on Prettier with focus on placing
comments at the correct position (Babel fails to do so)

Installation

``
yarn add --dev babel-plugin-reflow
`

Usage

$3

This package includes a small CLI wrapper for the Babel plugin to recursively
transpile whole directories or single files. Install the package as project
dependency and run npx reflow afterwards. Alternatively you might want to
install Reflow globally so you can simply type reflow:

`shell
yarn global add babel-plugin-reflow
`

Usage is as follows:

`shell
$ npx reflow --help

Usage: reflow [OPTION]...

REFLOW - Flow to TypeScript converter

Options:
-v Output the version number
-d, --dry-run Perform a trial run printing to stdout instead of writing a file
-e, --exclude-dirs Comma-separated list of directories to recursively exclude (default: ["node_modules"])
-i, --include-pattern Set the glob pattern for input files (default: "*/.{js,jsx}")
-r, --replace Process files in-place instead of creating new TS files next to the original JS files
-D, --replace-decorators Replace class @decorators with wrapped function calls to avoid TypeScript errors (default: false)
-h, --help Output ussage information

Examples:
$ reflow --replace src/
$ reflow -d -i '/__tests__//*.{js,jsx}' src/
$ reflow -exclude-patterns '/__tests__//','fixtures/.js' src/
`

$3

TODO

$3

TODO

Transformations

$3

Some Flow types are not equivalently expressible in TypeScript. See the list of
unsupported Flow features below.

| Type | Flow | TypeScript |
| ----------------------- | ------------------------------ | ------------------------------------ |
| Any type | any | any |
| Array type | Array | Array |
| Boolean literal type | true | true |
| Boolean type | boolean | boolean |
| Empty type | empty | never |
| Exact object type | {\| p: number \|} | { p: number } |
| Function type | (string, {}) => number | (p1: string, p2: {}) => number |
| Generic type annotation | let v: | let v: |
| Generics | type Generic = T | type Generic = T |
| Interface type | interface I { +p: number } | interface I { readonly p: number } |
| Intersection type | type Intersection = T1 & T2 | type Intersection = T1 & T2 |
| Mixed type | mixed | unknown |
| Null literal type | null | null |
| Nullable type (Maybe) | ?number | number \| null \| undefined |
| Number literal type | 42 | 42 |
| Number type | number | number |
| Object type | { [string]: number } | { [key: string]: number } |
| Opaque type | opaque type Opaque = number | type Opaque = number |
| String literal type | 'literal' | 'literal' |
| String type | string | string |
| This type | this | this |
| Tuple type | [Date, number] | [Date, number] |
| Type alias | type Type = | type Type = |
| Type casting | (t: T) | (t as T) |
| Type exports / imports | import type T from './types' | import T from './types |
| Typeof type | typeof undefined | undefined |
| Union type | number \| null | number \| null |
| Void type | void | void |

$3

| Utility Type | Flow | TypeScript |
| -------------------------- | --------------------- | ------------------------- |
| Call | $Call | ReturnType |
| Class | Class | typeof T |
| Difference | $Diff | Omit |
| Element type | $ElementType | T[k] |
| Exact | $Exact | T |
| Existential type | * | any |
| Keys | $Keys | keyof T |
| None maybe type | $NonMaybeType | NonNullable |
| Object map | $ObjMap | any |
| Object map with key | $ObjMapi | any |
| Property type | $PropertyType | T[k] |
| ReadOnly | $ReadOnly | Readonly |
| Rest | $Rest | Omit> |
| Shape | $Shape | Partial |
| Tuple map | $TupleMap | any |
| Values | $Values | T[keyof T] |
| Subtype | _deprecated_ | any |
| Supertype | _deprecated_ | any |

^\*

$3

| Declaration | Flow | TypeScript |
| ----------- | ------------------------------------- | -------------------------------------------------------- |
| Class | declare class C {} | declare class C {} |
| Export | declare export default () => string | const _default: () => string; export default _default; |
| Function | declare function f(number): any | declare function f(p: number): any |
| Interface | declare interface I {} | declare interface I {} |
| Module | declare module 'esmodule' {} | declare module 'esmodule' {} |
| Type alias | declare type T = number | declare type T = number |
| Variable | declare var v: any | declare var v: any |

Unsupported: CommonJS export declarations.

---

$3

Some Flow features are not equivalently expressible in TypeScript. The Reflow
CLI will output a warning with the source code location, whenever one of the
following cases are encountered:

- Constructor return types

TypeScript intentionally doesn't support return types for constructor
functions. These will be removed by Reflow.

- Existential Type

Flow's
existential type
has been deprecated and should be avoided. Still Reflow supports it and will
transform it to any.

- Function types with unnamed parameters

In contrast to TypeScript, parameter names can be omitted in Flow. Therefore
Reflow inserts parameter names automatically (p for a single parameter and
p{i} for multiple ones).

`
type FunctionType = ({}, Date) => string; // Flow
type FunctionType = (p1: {}, p2: Date) => string; // TypeScript
`

- Index signatures

Flow allows any type for keys in index signatures, but Typescript only accepts
string or number. Reflow will add index signatures both for string and
number if a different type is specified in Flow.

`
// Flow
declare type KeyType;
interface I = {
[key: KeyType]: number
}

// TypeScript
interface I = {
[key: number]: number;
[key: string]: number;
}
`

- Object type spread

Object types can be spread into other object types in Flow. Unfortunately this
syntax is not supported in TypeScript at the moment. Therefore, these
properties will be ommited in output. Please fix affected object types
manually.

`
// Flow
type ObjectWithSpread = {
prop: mixed;
...ObjectType;
};

// TypeScript
type ObjectWithSpread = {
prop: unknown;
};
`

- Opaque Type

Opaque types are not supported in TypeScript and are transformed to an
ordinary type alias.

`
opaque type T = number; // Flow
type T = number; // TypeScript
`

- Variance

Flow's contravariance sigil - is not expressible in Typescript and will be
omitted. However, TypeScript does support covariance for certain types (+
becomes readonly).

`
// Flow
interface I {
+covariant: any;
-contravariant: any;
}

// TypeScript
interface I {
readonly covariant: any;
contravariant: any;
}
`

- \$Call

The $Call utility type is transformed to TypeScript's
ReturnType. Since this type only accepts the function type and not the
function argument types, it is impossible to infer the return type of
polymorphic functions. TypeScript will assume an unknown type then.

Supported syntax

This Babel plugin enables a few other Babel plugins to support various kinds of
syntax:

- Class properties
- Decorators
- Dynamic imports
- Nullish coalescence
- Optional chaining
- React
- JSX

Development

Clone this repository and install the project dependencies:

`
yarn install
`

There are various npm scripts for different tasks:

`
yarn build # Create a production build
yarn dev # Build in development mode and watch for changes
yarn format # Format the code with Prettier
yarn lint # Run ESLint
yarn test # Run fixture tests
yarn test:coverage # Run the tests with coverage report
yarn tsc # Check the types (via TypeScript)
``