more documentation

[nmn]

The documentation for flow hasn't been updated much in a long time, and the project itself has moved quite a bit. I think it would be great to have a section explaining these parts in more detail —

1. how to annotate functions as value. var x : (number) => string
2. How type imports and exports work. import type x from 'y'
3. Documentation covering unions and the recently added disjoint unions.

I'd be more than willing to create pull request if you can help me figure out 2.
(short answers here, or links will do) :)

[popham]

Since you're importing, I'll assume that you're using ES6 modules. On (2), to type x from 'y', there must be a y.js with

export default class K {...} // I would import this with a capital letter for its alias
// or
export default function k {...}
// or
export type k = number | { someKey: string };
// or
export var k = 5; // I'm not sure if this works; `x` would alias number

If you're playing around, I would suggest relative imports, i.e. import x from './y'. I recently arrived at #644 (comment) for absolute imports, if that helps.

On (3), don't forget about intersections. I've had some success with intersecting classes against objects to impose: (1) is an instance of the class and (2) satisfies the structural constraints of the object. (In my use case, obj & cls works, while cls & obj does not.)

[nmn]

@samwgoldman Thanks for the help. I recently managed to use type imports and exports at work. Though most of them were named imports, I can try export default for more clarity. (One reason for my confusion was simply that I was using an older version of Babel)

On (3) I've personally not used too many class types in practice. Instead I define all classes as objects instead. So I will do some more research on that as well.

In regards to that, could you be so kind to also tell me something particular about declarations? Let's say, I have a commonJS project that happens to have a global variable called OT. window has a type definition already defined in flow. Is there a way for me to do declaration that would 'extend' that declaration.

To say something like. This object is of type T but with these additions (modifications)?

---

Thanks for the help though. I'll make a PR with some documentation soon.

[popham]

See #396 for the non-answer to your window question. See #31 (comment) for a helpful suggestion.

[nmn]

I just read some more documentation, and it turns out that what I really want is Classes, and extends.
I was a little confused about how typeof worked in flow, but I just figured it out.

[nmn]

About intersections, I did some research and an intersection between a class and an object works either way. Though it is a little strange to actually use in practice. It ends up making a smaller object. A union seems to be the correct tool for what you were describing.

[popham]

No, I mentioned the 'extends from' and 'implements' constraint. As long as your interface doesn't have any static members, you can have implements support by leveraging intersections. (I'm currently working on a straw man that adds statics to mix--I expect that "proper" interfaces can desugar to this.)

[nmn]

@popham I'm probably still confused about how intersections works exactly. I'll keep reading.

[nmn]

In #679 I ran into a limitation in Flow. It turns out it's been covered elsewhere in: #282
In both issues, there is a simple workaround for the problem.

Another common issue I run into is with decorator functions on React Classes:

class X extends React.Component{
  render(){...}
}
export default X

exporting X asks you for annotations. Then these annotations help flow catch errors across module boundaries.

However doing this instead erases all those errors:

class X extends React.Component{
  render(){...}
}
export default decorate(X)

Now flow has no idea what the type of the export is, and any type benefits across module boundaries are lost.

The workaround to fix this problem is simple as well:

class X extends React.Component{
  render(){...}
}
var toExport: typeof X = decorate(X)
export default toExport

---

So my question is, is it a good idea put a collection of these common workarounds in the documentation. Some of them may not be needed in the near future.

[samwgoldman]

The heap refinement thing should absolutely be documented. Maybe someone will get really clever and limit the scope of the refinement havoc, but I don't think it'll happen any time soon, and when it does we can update the docs.

The second issue you identified might be a bug. You mentioned it in #520 (comment) but I think it's worth opening an issue, because it's separate from autocomplete. I don't think anyone has really looked into the behavior you saw, so I wouldn't document that yet.

[samwgoldman]

I spent a bit of time improving (hopefully) the documentation around dynamic type tests and refinements. I added a "caveats" section that describes the scenarios in which flow will throw away a refinement. Hopefully we can use that to stem the tide of issues related to that behavior. Ref #711.

[jeffmo]

Closing per @samwgoldman's docs improvements