way to extend/override flow/lib types

[blax]

Built-in node.js type declarations are still far from being complete, and filling the missing parts is very cumbersome as Flow doesn't allow to overwrite single modules.

For instance, if I want to fill in some gaps in HTTP types, I have to use flow with --no-flowlib flag, which forces me to copy all the remaining built-in interfaces to my project.

Although such workaround works for now, it's unmaintainable in the longer term, and not obvious to newcomers.

Would it be a problem to make custom declarations override the default ones?

[popham]

Why not edit the lib files in place and rebuild Flow? You could pull request your modifications eventually.

[gyzerok]

@popham why not to check types using your eyes?

+1 for topic

[nmn]

I propose the following syntax for overriding flow types:

Firstly, we need a way to extend types that are not classes. The syntax is obviously Object spread:

type A = {a: boolean, b: number, c: string}
type B = {...A, d: (...rest: any)=> any}

Next, it should be possible to reassign a declaration:

declare class Document extends Document {
  newProp: boolean;
}
// OR
type Document = {...Document, newProp: boolean}

[popham]

What's wrong with class MyDocument extends Document { newProp: boolean }? If your environment has a different Document than Flow's, then why did you use Flow's to begin with?

In these situations, my gut says that you should put the Flow libraries in your project somewhere under version control. When you need to override something, edit it. Any external libraries that you've incorporated into your project will be validated against your environment specification (the version controlled library files). (Corollary: If you're making a library, work against Flow's unaltered libraries.) I guess this could be facilitated by moving Flow's libraries to a separate repo so that users could shallow clone them into projects?

The counterargument goes: "I want my project to see updates to Flow's libraries." I say, "You want your environment specification to change at the whim of Flow's maintainers? You shouldn't." Sure Flow's libraries are still immature, but I think that the proper tact is to help improve them instead of implementing override support (this is low-hanging fruit for non-maintainers). Eventually they'll stabilize and track some ideal environment as it evolves with JS, popularity of Node, popularity of IE8, etc.

(I love the spread syntax, though. Although I would describe it as a non-disjoint union, not as an override.)

[samwgoldman]

@nmn For your A/B example, you should be able to use intersection types: type B = A & { d: Function } (btw, Function is identical to your (...rest: any) => any type).

[popham]

Whoops. Thanks @samwgoldman.

[nmn]

@samwgoldman Thanks for the clarification. I'm still wrapping my head around what intersections do. This makes a ton of sense. So I guess the only part is to be able to override types.

While I don't think there's anything wrong with

class MyDocument extends Document { newProp: boolean }

And I use it already. It would be nice to be able to add/modify properties on a type for specific environments.

By the way, I was wondering if the declare class syntax was pretty much redundant.
For example, the react type definitions have something that looks like this:

declare class ReactComponent<D, P, S> {
  getInitialState(): S;
  componentDidMount(): void;
  ...
}

type ReactClass = Class<ReactComponent>

Is that any different from defining it like so:

type ReactComponent<D, P, S> = {
  getInitialState(): S,
  componentDidMount(): void,
  ...
}

type ReactClass = Class<ReactComponent>

Also, as you mentioned above you can do extends by using intersection.

Just to clarify, I'm not hating on the class syntax (which can be a little confusing), but just trying to understand some of the subtleties of the type system.

[popham]

Second part first. The difference is that you cannot extend or new the type ReactComponent version. Flow accepts that the declareed version exists in your JS environment (it's newable and extendable).

First part. The scope of a declare is global, so if you could override, you would be overriding for the entire project. I would argue that as an anti-feature.

• If it's a class that you want to extend with additional or alternate methods, just extend it and add or override the relevant method.
• If you disagree with a method's signature (so Flow won't let you override), then use --no-flowlib and provide your own declarations or you can go upstream to Flow's project repo and fix it for the benefit of everybody.

[nmn]

@popham If i'm not wrong, this is what I think: (Second part first)
You can't use the extend keyword but still get the same result:

while you would generally do:

declare class ReactSubComponent extends ReactComponent {
  someProp: any;
}

now you can do:

type ReactSubComponent = ReactComponent & {someProp: any}

As for being able to use the new keyword, instead of using typeof ReactComponent you can use Class<ReactComponent> (I'm not sure about this last part)

---

Now to the first part. At first I really liked the idea of getting rid of global type definitions.
Though this has some big advantages, this also has the huge downside of adding a ton of work to import types for every file. Project-wide type definitions actually make a lot of sense when you consider cross module inter-op. Having fewer type definitions is always better and will let flow do more type checking for you. So, I'm not sure it's going to be easy to get rid of the global declare method any time soon.

[popham]

I'm having trouble understanding you. I've used Flow, I've used React, but I've never used them together, so I'll probably be a little sloppy. The following are coherent, independent narratives:

• Suppose that I anticipate a bunch of React components that will have a someProp: string property. I'm going to explicate that shared structure by defining a type type ReactSubComponent = ReactComponent & {someProp: string}. Here's a couple of classes that satisfy my ReactSubComponent type:

class MyComponent extends ReactComponent {
  someProp: string;
  constructor() {
    super(...);
    this.someProp = "MyComponent";
  }
}

class YourComponent extends ReactComponent {
  someProp: string;
  constructor() {
    super(...);
    this.someProp = "YourComponent";
  }
}

Now I can create a function that rejects non-ReactComponents and rejects ReactComponents without a someProp: string property:

function printSubComponent(sc: ReactSubComponent): void {
  console.log(sc.someProp);
}

printSubComponent(new MyComponent());
printSubComponent(new YourComponent());
printSubComponent({someProp: "a string"}); // No good.  The object is not an instance of `ReactComponent`.
printSubComponent(new ReactComponent()); // No good.  This instance is missing the `someProp` property.

This subcomponent is just a type. If I try to create an instance, I'll get an error: var noGood1 = new ReactSubComponent();. If I try to extend this type, I'll get an error: class NoGood2 extends ReactSubComponent {...}.

• Instead, suppose that I have a ReactSubComponent class that extends ReactComponent with a someProp: any property, but Flow doesn't have access to the class:

// Flow doesn't have access to this class.
// It is injected into the JS environment *somehow*.
class ReactSubComponent extends ReactComponent {
  constructor() {
    super(...);
    this.someProp = "ReactSubComponent"; // or `15` or `{randomProperty: ["three"]}`
  }
}

I'm going to attach this class to the global scope of my environment; the identifier ReactSubComponent provides my class from anywhere in my project (as long as it isn't masked). To instruct Flow of my class's existence, I've added a declaration:

declare class ReactSubComponent extends ReactComponent {
  someProp: any;
}

This declaration is not type checked by Flow; it is inside a library file referenced from the .flowconfig file. Now from anywhere in my project (where the identifier isn't masked), I can get a ReactSubComponent:

var sc = new ReactSubComponent();
class MySubSubComponent extends ReactSubComponent {...}

[nmn]

This subcomponent is just a type. If I try to create an instance, I'll get an error: var noGood1 = new ReactSubComponent();. If I try to extend this type, I'll get an error: class NoGood2 extends ReactSubComponent {...}.

You're right about this. ReactSubComponent is just a type so you can't use it in your code at all! but you can use it to annotate classes you may define:

class someClass {...}
var x: ReactSubComponent = someClass