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

[STRML]

What is the preferred method for dealing with errors like this, when the built-in typedef is just incomplete?

 63:   http.globalAgent.maxSockets = settings.maxSockets;
            ^^^^^^^^^^^ property `globalAgent`. Property not found in
 63:   http.globalAgent.maxSockets = settings.maxSockets;
       ^^^^ module `http`

[nmn]

@STRML that's a problem with the type definitions library. You'll have to manually override the type definition for http.

Maybe something like:

var http: CustomHttpType = require('http');

[STRML]

Is there any way to do it globally, say in an interfaces file, so I don't have to pollute the code? On Dec 3, 2015 2:26 AM, "Naman Goel" notifications@github.com wrote:

@STRML https://github.com/STRML that's a problem with the type definitions library. You'll have to manually override the type definition for http.

Maybe something like:

var http: CustomHttpType = require('http');

— Reply to this email directly or view it on GitHub https://github.com/facebook/flow/issues/396#issuecomment-161549085.

[phpnode]

In node it's very common to promisify the fs module with Bluebird, which adds methods like fs.openAsync(), fs.readdirAsync() etc. This pattern happens with a lot of other libraries too. It would be nice to have:

declare module fs extends fs {
  declare function openAsync(filename: string, mode: string): Promise<number>;
}

[STRML]

:+1: to this suggestion. It would really help when a definition file is just missing a few methods, rather than having to copy/paste the whole thing from the repo and edit.

[ELLIOTTCABLE]

:+1: here, as well.

My use-case is that I wish to Flow-typecheck my tests (or rather, to flip that on its' head, I wish to typecheck my library, using my tests.); but I always use Chai / should.js style assertions when not targeting ancient engines like IE6.

Tests/giraphe.tests.es6.js:23
 23:          Walker.should.be.a('function')
                     ^^^^^^ property `should`. Property not found in
 28: export { Walker }
              ^^^^^^ statics of class expr `Walker`. See: giraphe.es6.js:28

Basically, while I understand some of the above arguments against such things (hell, this back-and-forth goes back more than a decade, in some ways.), I'd say it boils down to … “Are you really telling me I simply can't use Flow, if my library extends another system's prototypes?” Whether that's extending Object.prototype, testing with should.js-style assertions, using npm modules that extend existing flow-typed libraries with new functionality, or simply dislocating behaviour of a conceptual ‘module’ in your own project across multiple files, using prototype-extension … this happens in the JavaScript world. A lot.

I really, really think Flow should include a mechanism to support it, even if it's felt necessary to add warnings in the documentation that it's considered an anti-pattern, or exceptionally dangerous, or …

[jussi-kalliokoski]

another reason to consider this is that one could generate flow type definitions from WebIDL (there's a lot of partial stuff in WebIDL)

[cchamberlain]

Trying to add flow to my library that makes extensive use of chai's should object prototype extension. Is there really no way to extend Object.prototype when chai is imported (via a chai.js module declaration in [libs])?

As @ELLIOTTCABLE mentioned, prototype extension is fundamental and should not make the project incompatible.

These are the types of errors I get:

 41:   initialState.should.be.an('object')
                    ^^^^^^ property `should`. Property not found in
 41:   initialState.should.be.an('object')
       ^^^^^^^^^^^^ object type

[hon2a]

@popham (I'm new to Flow, so bear with me.) Seems to me that there's an obvious example of why this is a much needed feature - jQuery plugins. Type definition for jQuery is huge and looks like this:

declare class JQueryStatic {
  (selector: string, context?: Element | JQuery): JQuery;
  // ...
}

declare class JQuery {
  addClass(className: string): JQuery;
  // ...
}

declare var $: JQueryStatic;

When I use a jQuery plugin, e.g. Highcharts, it is added as a new method on the JQuery "class". Its use looks like this:

const chart = $('#myCoolChart', contextNode).highcharts({ ... });

There's no var to re-declare (as shown here), I need to extend the class contract. In this case if I copy the whole type definition into my project and edit it, there's no question of it being useful to anybody else in the future, as you suggested in other scenarios, because it's got nothing to do with jQuery itself. And I do want to get updates of the base definition and it's not an anti-pattern in this case - it's just a clean extension.

[le0nik]

Yeap. Decided not to use flow because of issues like this:

element.style.msOverflowStyle = 'scrollbar';

// Error:(12, 15) Flow: property 'msOverflowStyle'. Property not found in CSSStyleDeclaration.

Whenever flow sees property it doesn't know, it throws an error.

Is there a way to work around this?

[vkurchatkin]

@le0nik

(element.style: any).msOverflowStyle = 'scrollbar';

[le0nik]

@vkurchatkin thank you, it worked!

[iam-peekay]

@vkurchatkin nice!

[jagreehal]

@vkurchatkin I've used the any workaround. Would you happen to know if a resolution is being worked on?

[siebertm]

I'm running into quite the same problem with flowtype and chai plugins:

var chai = require("chai");
var chaiAsPromised = require("chai-as-promised");

chai.use(chaiAsPromised);

var expect = chai.expect;

describe('Something', function() {
  it('returns a Promise', function() {
    return (expect(Promise.resolve()).to.eventually.resolve()
  })
})

Since the eventually property is injected by the chai-as-promised plugin, it is not known by flow.

Can this be somehow resolved?

[pichillilorenzo]

I agree with @hon2a! For example i want add type definition of cordova's camera plugin. The problem is that the camera plugin attaches to the global navigator object the camera object but i can't add this property on Navigator class dynamically. I can only extend it.

[jefflindholm]

I must be the only person using Flow that wants to add to something simple like string.

in TypeScript you can do interface String { toCamelCase(): string; } String.propotype.toCamelCase(): string { // do the code } and you can do 'make_me_camel'.toCamelCase()

Can you do this in flow? I like flow better than TS because I can just use babel, jest, etc. and move on. But without something like this it is a non-starter since I don't want to find in all my code where I did something.toCamelCase() and change it to toCamelCase(something) - honestly this would not be too hard, but all the other methods I added to string make it harder.

[idan]

I'm having the same issues as others (@siebertm, @cchamberlain, @ELLIOTTCABLE) in the thread around chai plugins. There's a flowtype libdef for base chai, but not for the various plugins (chai-as-promised, chai-enzyme, et al). I don't mind writing my own libdefs if I had some inkling of how to do this properly.

Right now, it simply looks like the libdef for chai includes additions for popular plugins, and I can go ahead an hack mine right in there. Is there a better way?

[cchamberlain]

@idan I've since moved to a TypeScript project so not sure what the current landscape looks like, although skimming the thread it doesn't look like there is a way to extend prototypes well (aside from the any thing which isn't a real solution).

[lll000111]

My use case is a union type.

I have a few built-in objects (with a "type" string property used for the union type) but I want to let applications using the library add their own object types to the union (and benefit from Flow if they use it).

Can the application using my library extend the union type?

It has to be an extension, they can't just use their own types, because the library doesn't know about the application's types, only its own, of course.

[smendola]

+1 on this. I'm eval'ing Flow against TS currently. I have found numerous places where I would have needed to extend some incomplete library .d.js file, and a couple where we extend a prototype, and I'm having to use $FlowFixMe for these.

Whereas in TS I can do:

// From coreUtilities.js
interface Array<T> {
    removeIf (cond: (x: T) => boolean): T[];
}

// Chrome specific implementation
interface Console {
    group(...x : any[]): void;
}

// Neither TS nor Flow libs seem to know about Function.name
// https://goo.gl/tJMykL
interface Function {
    name: string;
}

which works perfectly.

[reednj]

Its a real shame that flow doesn't support this like TS does, as it is better than TS in most other ways. The easy solution is as the previous poster says (and how TS does it) - to be able to declare interface multiple times for the same type, and merge them all together.

Its very useful and easy to be able to extend types from external libraries through prototype, but there is no way to tell flow about it.

[TrySound]

@reednj It's not a shame. It's protection from implicit features from anywhere in favour of explicit class extending. Just define empty class with typed properties and assign it as a type. You don't even need to instantiate it.

class ExtendedElement extends Element {
  fullScreen: boolean
}
const element: ExtendedElement = (el: any);
element.fullScreen // works fine

Sure, it's a hack. But isn't it a hack to use browser specific features?

[reednj]

@TrySound: I understand that it makes it harder to reason about the classes, and that I can get around it with subclassing+casting, thats probably why C# and Java didn't have them at the start - they all added extension methods eventually though, because they are just so damn useful.

Edit: just to expand on my particular use case. I would like to be able to extend the native types, not add definitions for browser specific features.

For example it is much easier to do something like this n.sqrt().format(".02f"), than this NumberExtensions.format(Math.sqrt(n), ".02f")). Its no problem to create these methods by extending Number.prototype in js, but there is no way that I know of to make flow accept this (except by just casting everything to any). I want to be able to extend the type definitions to tell flow that these methods will exist at run time.

I understand this is dangerous, because it is possible for the definition and implementation to get out of sync without flow knowing about it. However I think the danger is worth it, which is probably why TypeScript supports it already.

[lll000111]

@TrySound Please read my use case three posts above your response. It has nothing to do with classes and needs the possibility to add to a union. I see no way around it, and the use case is legit and not even close to what one could call a "hack" IMO.

[TrySound]

@reednj Extending built in stuff was always bad practice, so it will never be a use case for flow. @lll000111 Pass types via generics. Extend unions with type Custom = Builtin | UserExtension.

[lll000111]

@TrySound How does that help in my scenario? I use a disjoint union,. I tried the same scenario with generics before (spending months and a significant amount of effort in trying to get this to work since I too loved the concept) - there is a reason I went to disjoint unions. Whenever I plugged a hole soon a new one would open up, and the errors were very hard to track (suddenly 200 errors out of nowhere, all hard to track to any one single location). It was significantly harder and the code kept blowing up. Not because there is anything wrong with the code (yes you have to take my word, or don't) but because the scenario is just not well supported by these type systems. I will not go back to generics because it just does not work nearly as well. Extending the union types would be easy and pain-free. Trying to put the round thing into the rectangular generics hole is pain, I've tried.

There is only so much value in not discussing the actual problem but instead trying to tell people of other options without knowing their situation. Reminds of of StackOverflow... I'm not saying there is no value, thanks for the suggestions, but knowing my way around I still see the extension as the way to go.

There are plenty of issues with my overall scenario of providing a package with Flow-annotations in .js.flow files. Not infrequently I get errors in the calling package that I don't get when I run flow in the library package itself. For example, I finally included the test files in the flow configuration - they use the after-built files not the source files. Quite a few issues here too. Lots of hacks and workarounds all over the place. So we all struggle with the often shitty compromise of a 3rd party type system, and a huge number of open tickets and slow progress because the makers of the tool have their use case covered (nothing wrong with that). And some of us have come to the conclusion that our use cases would best be served by being able to extend types - which in addition seems to be a minimal coding effort. We did think this through, this isn't an impulse wish.

Since giving complete and thorough background information about our respective projects and a full discussion would be a lot of trouble for everyone (not to mention the effort of building code examples to show to the public - which in the end nobody is probably going to look at anyway, or how much time do even you want to spend on my specific scenario?) we have to have a little bit of trust in that what people say they need is what they need. So if we can just look at the number of upvotes here, this does not look like a fringe issue and I think we should keep the ticket on the original topic. If github would allow a side-tracking discussion to take place without the whole thread becoming unreadable I would certainly welcome this type of discussion, it's just that I think this place here is not well-suited. It is just not constructive.

I have objects which differ in one text property ("type") -- the ideal use case for disjoint unions, look at the documentation for that type of type. The only problem is that users of the library introduce new type strings. An extensible union type would solve the problem cleanly and cheaply (which includes considerations about effort and side-effects in Flow).

[TrySound]

Well, you want hell of implicity.

[hon2a]

Extending built in stuff was always bad practice, so it will never be a use case for flow.

@TrySound See my post above. Though opinionated, this might be understandable in case of extending natives. But when some libraries (e.g. jQuery) are based on extension, the argument simply doesn't hold.

[STRML]

...the argument simply doesn't hold.

Agreed, 100%. In a world where all the built-in and community libdefs were perfectly written, this argument would hold water. At the moment it's impossible to fix a single missing or mis-stated property or function without redefining a large chunk.

[lll000111]

@STRML Just to add a concrete example: https://github.com/websockets/ws/issues/1173

Here we have THREE different types for a Websocket onerror callback function parameter:

• Officially according to the specs the type can be Event or ErrorEvent (DOM types)
• In the current Flow library definitions there only is Event
• The most popular node.js package for websockets "ws" actually sends an Error object, which is hard to change because it would be a breaking change and apparently nobody has complained yet.

And now? I'm stuck with not declaring a type in my callback function as a workaround, no way to reconcile those conflicts (especially with "ws" because the code would have to be changed). The real world is all about compromise and muddling through because perfection is neither achievable nor even necessary.

And that's just the example for actually broken code/lib.defs, not even a main argument made for this feature.

[ELLIOTTCABLE]

Just throwing this back into the discussion, as above, to prevent more responses like @TrySound's. This is literally a highlighted feature, on the landing page for Flow:

JAVASCRIPT, YOUR WAY

Flow is designed to understand idiomatic JavaScript. It understands common JavaScript patterns and many of the weird things we JavaScript developers love to do.

Flow isn't TypeScript, the reason it exists (or at least, one major reason) — at least as far as I can tell from the documentation and advertising copy — is to support existing JavaScript idioms.

And, you may not like it, but extending prototypes is what peak performance l— er, I mean, extending prototypes is a very common JavaScript idiom, utilized in a host of ways, across a host of (extremely popular) libraries!

We all know the advantages of avoiding doing this, the arguments against it, so on, and so forth. This isn't the place to discuss those.

[ELLIOTTCABLE]

Personal (depressing) opinion, the above being considered: until Flow handles this, Flow is completely and utterly useless. Use TypeScript instead. /=

[natew]

Flow doesn't cover a lot of new es7 features that are released in current browsers and Node 8. Object.getOwnPropertyDescriptors being a great example.

Can't really do Object extends Object so you're stuck.

Another use is functions that change the prototype or properties of a React.Component.

One example that may be relevant is we use a component() decorator that actually merges together a variety of helpers (all in different modules). One example is a decorator that changes render() to accept render(props, state, context), another is one that adds minor helpers like this.setTimeout and this.setInterval, which ensure these things don't break on unmount. And so on. Some of them modify prototype functions, some add properties. These patterns are massively helpful for us. I suppose there may be a way to do many extends here, and maybe this is just something that I'm not clear on, but it seems unclear how do it in flow.

Basically, a big +1 to this issue, it's blocking almost all our valuable types from working.

[natew]

Actually, to articulate the last paragraph a bit more clearly. The problem is we export these decorators from modules that should each export a type.

So an example is a SubscribableClass that adds a subscribable: CompositeDisposable property. There's a variety of these.

Now you want to later put them all together. I suppose Redux does things like this.

Seems like you'd force the end user to write something like:

declare class X extends SubType {}
declare class Y extends X extends OtherSubType {}

Or something? I'm actually not certain how you'd do it, again, I'm likely just in the dark here, but also seems like this area is not very flexible.

[hrgdavor]

Yeah, I agree with all here requesting this feature, and especially @ELLIOTTCABLE with his quote main marketing phrase of the flow

Flow is designed to understand idiomatic JavaScript. It understands common JavaScript patterns and many of the weird things we JavaScript developers love to do.

I have added notifications for this issue and postoning using flow until this is resolved.

[jcready]

Flow is designed to understand idiomatic JavaScript. It understands common JavaScript patterns and many of the weird things we JavaScript developers love to do.

Speaking of common idiomatic JavaScript patterns that Flow doesn't support (any longer): When creating classes which extend another class you can no longer override the type signature of methods or static properties of classes you're extending:

declare class Foo extends Object { // error
  static bind(): Foo;              // error
  valueOf(): "flow, you're drunk"; // error
};

class Bar extends Object {         // error
  static bind() { return new Bar } // error
  valueOf() { return 'go home' }   // error
}

Try Flow

Side note, it's weird that the issue has the label Closed: wontfix yet it hasn't actually been closed.

[qm3ster]

5018 Still not possible to extend using &...

[aleclarson]

Has the Flow team addressed this issue anywhere?

We need a solution for extending an existing type, while keeping the property list immutable by default.

declare interface Point {
  x: number;
  y: number;
}

const point: Point = {x: 0, y: 1}
point.z = 2 // Error!

Here's my proposal: #5364