Flow: [libdef] declare module auto-export is too much magic

[ryyppy]

I see this all the time... people (including me initially) are really confused about the export handling of declare module.

If I do this:

declare module 'mylib' {
   declare type Foo = { bar: 'test' };
}

The type Foo will automatically be exported.
As soon as I use declare module.exports: ..., declare var exports: ... or export type Other = ...., flow will only export entities via the export mechanics.

IMO it should by default assume private scope and only export entities, which are explicitly exported (like ES6 or Node CJS do).

It causes a lot of confusion whenever someone submits flow-typed libdefs... people tend to use namespaces inside declare module, although they are using declare module.exports and just make libdefs hard to read (because of this $npm$whatever$MyType naming).

I wonder if the default behavior will be changed in the future?

[gcazaciuc]

i totally agree. i believe this is the biggest pain point in understanding flow atm for me and my team. To be honest after several months of using flow this is still not fully clear even after reading supplemental material like your presentationson the subject. I believe documentation is very lacking in this regard and besides that the behaviour is way too magic

[ryyppy]

@gcazaciuc I guess! Right now, the only way for me to onboard people on this topic is via PR reviews in flow-typed...

I am currently trying to contribute this whole "write your own libdefs & modules" docs... not sure how long I will take to get this to a nice useful state.

But I would really love to see a more sane export behavior in the long run... IMO it should behave like actual CommonJS / ES6 modules... I know that the export syntax came up with a later version and they probably didn't want to break compatibility...

I would definitely bite the bullet and fix the breaking libdefs for flow-typed, if we can have export and declare module.export as the only way to expose stuff... the later it gets, the more work it is to fix everything up, I guess.

[jeffmo]

I agree this is confusing. My plan after introducing declare module.exports: was to wait some period of time to let the old versions of Flow that don't support it fade into obscurity, then make a breaking change that disables the implicit-export behavior.

We introduced declare module.exports way back in 0.25, so it's probably safe to say that <0.25 is in obscure enough history at this point (that and flow-typed exists now) -- so I'll take this on.

Additionally I'd like to remove the long-deprecated declare var exports hack while we're at it