Document advanced Utility Types

[gabro]

In the process of learning Flow and adopting it at work, I've often needed "advanced" operators that are completely missing from the documentation.

So far I relied on this blog post (now slightly outdated) http://sitr.us/2015/05/31/advanced-features-in-flow.html and code found in the Flow and React codebases.

I think I'd be nice to have this features explained in the official documentation.

The features I'd like to see documented are:

• $Keys
• $Diff<A, B>
• $Supertype (deprecated)
• $Subtype (deprecated)
• $Abstract (removed)
• Class
• $PropertyType<T, x>
• * (existential types)
• $ObjMap / $TupleMap
• $ObjMapi
• $Shape
• $ReadOnlyArray
• $Compose
• $ComposeReverse
• $CharSet
• $NonMaybeType
• $Rest<A, B>

And maybe (they look like internal features though):

• $Exports
• $Pred (experimental)
• $Refine (experimental)

Am I missing something?

In order to get the ball rolling, I've sketched a documentation page for "dynamic" enums using $Keys (aka $Enum). I have a PR almost ready that I will submit soon.

Is this something that you guys are already working on?
I'd be glad to help (provided that I understand the features first 😅).

Let me know!

[gabro]

PR submitted, feedbacks are very welcome!

[anmonteiro]

@gabro I think $Exact is also missing docs, as well as its literal ({| |}) notation?

[gabro]

@anmonteiro yes, it's on my radar but I didn't include it there as I wasn't sure $Exact is an internal-only representation of {| |} or not. Along the same lines, we could also document $All $Either and similar utility types that have an ad-hoc syntactic sugar.

Long story short, are $Exact, $All, $Either (and others?) also intended for client's use, or are they just internal representations? This is a question for the Flow team, though. /cc @mroch @thejameskyle

[gabro]

@anmonteiro about the documentation for {| |}, yes, it's missing, although I'm not sure it would fit this issue, which is about "advanced" features, named "Utility Types" in the first related PR. Maybe we should open another issue?

[anmonteiro]

@gabro IMO I agree it's a different concern so another issue is necessary. I should have clarified my initial intent, which was to bring up the fact that it wasn't documented, not to include in a PR for this one.

[STRML]

Can anyone elaborate on usage of $Abstract? We were subclassing React.Component and had a surprising number of bugs disappear (and new, good type errors) once I realized the builtin uses $Abstract<State> and $Abstract<DefaultProps>.

[gabro]

@STRML from what I was able to "reverse engineer", it looks like $Abstract imposes a constraint on a subclass, forcing it to provide that field. Here's a few examples that helped me clarifying the concept:

class MyAbstract<T> {
  foo: $Abstract<T>
}

class MyConcrete extends MyAbstract<string> {} // error, foo is missing
class MyConcrete2 extends MyAbstract<string> {
  foo = 'bar' // ok
}
class MyConcrete3 extends MyAbstract<string> {
  foo = 42 // error, foo must be a string
}

class MyAbstract2<T> {
  foo: T
}
class MyConcrete4 extends MyAbstract2<string> {} // no problemo

From the examples above, the most notable difference between T and $Abstract<T> is that the former allows for a missing field, whereas the latter requires the subclass to provide it.

I would love if anyone from the Flow team could confirm my "hypothesis" (so that we can document this!)

[STRML]

Interesting insight. It's odd, though, that you're not required to actually define static defaultProps or state when extending React.Component.

[gabro]

@STRML I think you are required to, if you specify a type for it. Meaning

class MyComponent extends React.Component { } // ok
class MyComponent extends React.Component<{ x: string }, any, any> { } // error
class MyComponent extends React.Component<{ x: string  }, any, any> {
  static defaultProps = { x: 'foo' };
} // ok

Here's some example from the tests: https://github.com/facebook/flow/blob/master/tests/new_react/bad_default_props.js

[STRML]

Gotcha. So if you just don't specify the type parameters at all, there isn't a difference? Strange.

Still, I wonder why updating our React.Component extension to use $Abstract<DefaultProps> and $Abstract<State> (from non-$Abstract versions) uncovered so many previously-ignored type errors. There must be more to it.

[gabro]

So if you just don't specify the type parameters at all, there isn't a difference?

I think as long as the type is unbound anything is accepted, including void, i.e. missing.

But again, I'm just guessing here. Either I'll learn some OCaml and start reading the source code, or someone from the Flow team can shed some light! 😄

[gabro]

Just to clarify my void point before:

class MyAbstract<T> {
  foo: $Abstract<T>
}

class MyConcrete extends MyAbstract<void> {} // ok!