Support for TypeScript definition files about flow

[kegsay]

Author of flow-jsdoc here: I might have a stab at writing an automatic converter from .d.ts to Flowtype. In most cases, 95% conversions are "good enough" and if you really care you can just hand roll after conversion. This works really well for my personal projects with JSDoc -> Flowtype annotations, so I imagine the same usefulness will apply here. Will pingback here if/when I get something usable.

[sheerun]

As I suspected, devs are choosing TypeScript instead of Flow because of DefinitelyTyped: https://redditblog.com/2017/06/30/why-we-chose-typescript/

[rattrayalex]

Flow seems like a generally better tool than TypeScript – it has better support for gradual typing and ties in with the terrific Babel ecosystem.

That said, TypeScript has a stronger community – DefinitelyTyped and the TypeScript IDE tools are incredible. It doesn't make much sense to go with Flow if you'll have to write all those definition files yourself for third party libraries.

What would it take for Flow to take advantage of DefinitelyTyped? Is this likely to be prioritized by the core team at Facebook?

[michaelmesser]

This issue is a deal breaker

[STRML]

These repos are great, but it's tough to replicate the number of man-hours that have gone into very extensive definitions like lodash.

Is anyone still working on automatic conversion? It seems a shame to redo all of this work just because Flow's syntax and semantics are slightly different.

[rattrayalex]

I've been thinking about creating a bot that would send PR's to npm packages with both Flow and TypeScript type definitions, with instructions on how to keep them updated manually. I was thinking of taking the types from DT and converting them to Flow for the Flow versions. For libraries that don't have DT defs, it might be possible to have Flow infer the types as they are, solidify those, and then convert those definitions to TSC. This way library authors and their contributors can maintain the types themselves, as their code changes. Would anyone be interested in something like this?

…

On Sat, Jul 1, 2017 at 9:22 AM Adam Stankiewicz ***@***.***> wrote: As I suspected, devs are choosing TypeScript instead of Flow because of DefinitelyTyped: https://redditblog.com/2017/06/30/why-we-chose-typescript/ — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#7 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAq_LuDpbOqUDMJ2G13GUiGKm-VYCpa-ks5sJnJhgaJpZM4C9Tob> .

[sheerun]

Absence of ts2flow converter is going to kill flow, as typescript community gains momentum. The plans to release flow2ts don't make it better as it'll be even easier to switch from flow to typescript.

Instead, please make it easier to switch from "less sound" typescript system to "more sound" flow, by creating a definition converter, and let developers fill the blanks. Only then flow2ts converter makes any sense. As others stated, there aren't lot of people willing to replicate definitely typed efforts. Currently, with just flow2ts converter, there isn't much to convert from.

Introducing ts2flow converter could potentially bring this little list of flow definitions from 90 entries to 1900 in a matter of few weeks!

[goodmind]

https://github.com/joarwilk/flowgen is the right tool for this

[goodmind]

flow-typed just landed with flow-typed create-stub package-name --typescript option which would create stubs for packages with https://github.com/joarwilk/flowgen

[dvins]

Quite the opposite, getting started with Flow is easier and less impactful than TypeScript, however without the definitions adoption is painful. Lack of JSON Schema -> Flow definition support is also a factor for API/contract first development.

[joarwilk]

I had a go at it here: https://github.com/joarwilk/flowgen

It's somewhat close to being finished and all help is appreciated - I'll add the remaining things as issues as soon as I can. There's a couple of not-super-trivial definitions it can translate with 100% accuracy, but it still struggles with most cases.

It's based on d.ts -> ast -> flow as discussed above.

[bsr203]

Anyone like me who is looking for an update on this may found this repo and discussion useful flow-typed/flow-typed#4

Also

https://github.com/marudor/flowInterfaces

[joarwilk]

@andreawyss have you tried running tsc -d on your library files? Works decently for me.

Regarding TS->Flow: I have updated my repo and moved it to https://github.com/joarwilk/flowgen.

There's a PR to flow-typed here which shows the current state of the converter.

[sheerun]

If anyone has time to implement this, I think the best way is to modify typescript's declarationEmitter to output flow declarations instead.

You can try d.ts -> ast -> d.ts conversion with following:

npm install -g typings typescript@next
typings install dt~jquery --save --global
cp typings/globals/jquery/index.d.ts index.ts
tsc -d index.ts
diff typings/globals/jquery/index.d.ts index.d.ts
# Results in a lot of style-only changes

After modifying declarationsEmitter you might achieve d.ts -> ast -> js.flow

[vojtatranta]

Babel can read Typescript https://medium.com/@jdolle/babel-7-beta-instructions-aed5cf17048b

Then we could use Babylon to convert it to AST and them analyze it with flow or not?

[danny-does-stuff]

@goodmind When using flow-typed with the --typescript flag, where does it look for the typescript definitions? It would be great if there were a way to generate flow definition files and then send them straight to flow-typed repo

[jeffmo]

Update: We've spent some time circling our options and here's where we're at:

There are two perspectives we have to consider when approaching this problem: Library-definition authors (who would prefer to write a single library definition rather than two) and library-definition consumers (who would like to have somewhere like DefinitelyTyped to go and grab or contribute to a pre-existing libdef).

At the moment the biggest blocker to supporting .d.ts outright is the number of differences (both past and future) between the two systems. Nullability is one issue, nominal/structural subtyping is a second, there are others still. If we don't address these things carefully then library authors will find it difficult to write libdefs that work well in both systems and library consumers will have a difficult time figuring out which .d.ts files are best suited for whichever typechecker they are using.

So the options for dealing with this are as follows:

(a) Have Flow consume only libdefs that contain the most common subset of features and error on any features or syntax that don't properly map to Flow.

Given differing features as pervasive as nullability, nominal (vs structural) type annotations, some of Flow's built-in types like Class and mixed, etc: It's pretty clear this would not be a very practical option. In all likelihood we'd end up with a constrained subset leaving the best option for many libdef authors as just writing system-specific definition formats in order to be maximally expressive. At this point we're back to square one with our two formats :(

(b) Have Flow parse .d.ts files and just ignore any features that Flow doesn't understand or that don't map well to Flow's version of the feature.

This is problematic when any features that Flow has to ignore are vital to the interface definition (type-guard functions in TS are one example, nominal vs structural class types is another, lack of nullibility intent in the syntax is yet another). As a result the interface definition ends up working very well with one system and very poorly for the other.

(c) Built a best effort two-way converter between Flow libdefs and .d.ts files.

The purpose of this converter would be to take one format and do it's absolute best to convert to the other. Lossiness in the conversion would be expected (i.e. it wouldn't be able to predict the nullability characteristics of a type written for TypeScript, etc), but the benefit is that the output file can be tweaked and saved for future use.

(c) seems like our most practical option at the moment. It makes life easier for libdef authors who wish to support both systems and it makes it easy for libdef consumers to convert existing .d.ts files with minimal tweaking if some Flow library definition doesn't already exist.

I don't think the core Flow team will have enough time to work on a tool like this for at least the next several months, but it would be really cool to see something more refined than flow convert surface out of the community and beat us to it!

[mgcrea]

Any chances we could have a somehow official update on this?

In my case, I would love to use flow on the backend but the lack of type definitions is really a burden, and I'm forced to go with typescript. And I don't see this trend reversing anytime soon due too network effects & momentum inertia.

Having support for @types packages out-of-the box would be really awesome. Even if we end up with a lossy conversion.

And such a tool would allow developers to easily push "pure" flow typings very fast. We could also imagine adding warnings when the converter detects a lossy conversion, and hints how the converted definition could be manually improved.

[rajington]

Is it possible to maybe use JsDoc/Closure Compiler annotations? It's a common syntax that hopefully both sides could agree/expand on. Here's TypeScript's JsDoc feature and here's some comparisons:

@STRML's lodash example for _.size:

    //_.size
    interface LoDashStatic {
        /**
         * Gets the size of collection by returning its length for array-like values or the number of own enumerable
         * properties for objects.
         *
         * @param collection The collection to inspect.
         * @return Returns the size of collection.
         */
        size<T>(collection: List<T>|Dictionary<T>): number;

        /**
         * @see _.size
         */
        size(collection: string): number;
    }

lodash JsDoc example for _.size:

/**
   * Gets the size of `collection` by returning its length for array-like
   * values or the number of own enumerable string keyed properties for objects.
   *
   * @static
   * @memberOf _
   * @since 0.1.0
   * @category Collection
   * @param {Array|Object} collection The collection to inspect.
   * @returns {number} Returns the collection size.
   * @example
   *
   * _.size([1, 2, 3]);
   * // => 3
   *
   * _.size({ 'a': 1, 'b': 2 });
   * // => 2
   *
   * _.size('pebbles');
   * // => 7
   */

[amilajack]

@thejameskyle I've just saw your on comment on migrating typescript definitions to flow. Has anything changed since you posted that?

[mweststrate]

Feeling stupid now :) Thanks!

[alshdavid]

This is surprising, I thought Flow was interoperable with TypeScript types sourced in node_modules. Given how rare Flow types are in libraries, the lack of support essentially makes Flow more of a liability than a help

[Conaclos]

#8989 tracks some improvements to be made for compatibility.

[benjamingr]

Supporting importing of .d.ts could be awesome, even if it'd only work 95% of the time. Especially if the type system is easier to migrate to than with TS (kind of like PHP and hack)

What do you mean by ES6 state?

[cirocosta]

Regarding ES6, there's something on their blog post: https://code.facebook.com/posts/1505962329687926/flow-a-new-static-type-checker-for-javascript/#compatibility

It already supports various ES6 features such as destructuring, classes, extended objects, optional function parameters, and core API extensions (e.g., Map, Set, Promise, and new methods on Object, Array, and Math). Other features (notably modules) are on the way. Flow supports modules organized following the CommonJS / Node.js specification.

[avikchaudhuri]

This is on our short-term todo list. See http://flowtype.org/docs/coming-soon.html#_

[samwgoldman]

I'm going to split off the ES6 part of the original question into another issue & merge other TypeScript-related issues with this one.

[0xR]

+1 This would make flow a lot more viable as a type checking system for our production code.

[clentfort]

Is there any progress/roadmap on this issue?

[gcazaciuc]

Is "flow convert" command currently considered usable ? I'm not sure if there is currently an official way to convert .d.ts files but i know there has been some work into supporting this kind of conversion.

[gitawego]

that would be much better for third party definitions, with a simple tsd install react --save, I could easily use either flowtype or typescript

[mattmo]

Wanted to bump this again since it's been over a month with no response. Is this in progress at all? Are there reasons for it not being in progress? Is this a good candidate for someone in the community to build?

[dumconstantin]

+1
to have this implemented. Until then, is there any repo with Flow declaration files? At least for common things like mocha, gulp, etc.

I found this https://github.com/ptmt/flow-declarations, and it seems to have a lot of work done but there's no activity for the past 11 months...

[dumconstantin]

Nice breakdown of the situation, thank you!

I've been digging a bit and came to the conclusion (which can be completely wrong, please correct me!) that Typescript and Flow serve different purposes:

Typescript: developer productivity and structure
Flow: dynamic program analysis (although the initial scope was different in Facebook's ecosystem)

The above describes a concurrent situation instead of a competing one. As such, compatibility between them is something for the Flow and Typescript teams to agree on and not the developers.

My understanding is that the two are compatible syntax wise and a program written in either (disregarding the definition files) should be parsable by both.

In my opinion both libraries should define a common standard (and maybe other typecheckers can emerge from that) for how types should be used in JavaScript. (dunno if one exists)

Type declaration is very much up to how each engine is implemented (and geared at serving the purpose of those engines as defined above) so I don't see (ever) a Flow <-> Typescript converter with a 100% match.

I'm looking forward to the next generation of analysis tools that will emerge from Flow and as for .d.ts, they seem to become the standard due to Typescript's much richer syntax for type declaration and community adoption.

In the meantime, I tried using Flow but without a massive investment in time for writing declaration files for all the libraries I use it doesn't provide much value.

What I did eventually is have Typescript just type checking and keep webpack/babel etc for transpiling my code (using gulp):

gulp.task('typecheck', function () {
  return gulp.src('src/**/*')
      .pipe(ext_replace('.tsx', '.js'))
      .pipe(ts()) //typescript gulp plugin
});

If ever Flow changes direction and supports .d.ts declarations I can just change the ts() call with a flow() one without any change to my codebase.

[dckc]

Regarding delegating to the community, i.e. option (c), would the core developers be willing to take care of the lexical details? i.e. add "flow parse" and "flow serialize" that read and write an AST in JSON format along the lines of https://github.com/estree/estree ?

Maybe this already exists?

Given that level of support, I can see myself tackling special cases of the "flow convert" problem as a way of exploring the design space.

[dckc]

Looks like getting an AST for a .d.ts file is supported.

[jeffmo]

@dckc: There is flow ast which will emit a JSON ESTree* AST given some file content.

* Two minor caveats to calling the output "ESTree": 1) Flow obviously has syntax extensions, so those extensions are a part of the structure and 2) Some of the details of the ast are probably a bit outdated per the latest version of the ESTree spec (i.e. I think we still have old-style nodes for import/export, there are probably other things that could be more up to date). Otherwise the ast is just a JSON representation of the same AST Flow uses internally, so it's guaranteed to be complete.

Since flow ast taps Flow's internal parser directly, it's probably your most sure-fire way to parse any Flow code, but it's also worth noting that there is also Babylon (Babel's parser) which we are fairly dependent on for purposes of general transforms. So Babylon + babel-plugin-syntax-flow would be another option for parsing Flow-inclusive syntax that tracks the internal Flow parser very closely

[dckc]

I'm more interested in converting from .d.ts files to flow definitions than the other way around (since .d.ts files are more widely available and the flow type system is better in some critical ways). Is there a dual of flow ast that consumes JSON and produces flow declarations?

[jeffmo]

@sebmck: Do you think the codegen utils in Babel that work with the Babylon AST would work for @dckc? If so, do you have any pointers to them?

I was thinking .d.ts AST -> Babylon AST -> codegen...

[henridf]

Is there a plan to support imports in libdefs? (Couldn't find anything in the issues). For example like the ones done here: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/node/node.d.ts#L440

I bring this up here because it will otherwise be necessary to do the module resolution in this conversion utility. If it's going to happen soon in core flow, then the converter should just be able to pass through module imports.

[jeffmo]

@henridf: I'd like to make declare module body toplevels more directly correlate with the possible toplevels in a normal ES module -- so yea, I think having import in there makes sense just as much as having export does.

Switching declare modules to use explicit exports will be a pretty reasonably-sized breaking change -- but I think we still have time for such changes since we don't have a huge libdef ecosystem yet.

[bassettsj]

Would love to work on getting some way of being able to use TypeScript definition files or starting a flow specific repository of declaration files. In the meantime, it is taking a long time, especially as a newbie, to start taking advantage of flow. I really hope this feature can be prioritized somehow. I think it is way beyond my means to be able to contribute a PR back for this though.

Thanks for all the great work!

[gregegan]

Please TypeScript definition files or a flow specific repository of declaration files!

[amilajack]

@sheerun What do you mean by 'style-only changes'?

[sheerun]

Different whitespace

[amilajack]

But would the converted form still work correctly?

[sheerun]

It converts d.ts to ast, and back to d.ts, so it works as intended.

A task to volunteer is to implement conversion from ast to js.flow.

[mweststrate]

@kegsay any update on the converter?

[bsr203]

@mweststrate I see this on the author'ss github page https://github.com/Kegsay/ProbablyFlowTyped

[kegsay]

I haven't announced it yet since it really is still a WIP - It barely works :)

[kegsay]

@joarwilk That sounds a lot more comprehensive than my one which I still haven't found time to work on. I'm more than happy for someone other than me to do this: though it would be nice to get some tests in there. You should just be able to thieve the test runner and drop in the .d.ts and .js.flow files in defs, running it using this command. Thank you for your hard work on it!

[joarwilk]

@kegsay Yeah adding tests would be super beneficial, the problem with that solution though is that I don't actually know what the flowtype exports are going to look like. It's a very experimental phase.

It'd be interesting to use the test runner + tests from flow-typed and use those as a benchmark.

[andreawyss]

When will it be possible to generate all the necessary TypeScript Definition files from the Flow definitions of a ES6 library project?

[btipling]

As Flow supports and sometimes requires variance annotation and TypeScript does not, I doubt that a converter could be successful in all cases. I think that such a converter would at least sometimes not find enough information in a typescript definition file to satisfy flow's compiler requirements.

[idanilt]

I am keep straggling with this issue, when I am creating a lib and I need to support TS & flow I end up maintaining two definition manually
I searched and searched the web and didn't find anything solving me this problem.

If anybody can shade some light on this issue it will be amusing

[mrkev]

This project goes the other direction, but might be helpful as reference https://github.com/bcherny/flow-to-typescript/tree/recursive-descent

[dckc]

I have no official standing, but I'm curious: what would you want flow to do with @types packages, @mgcrea? What would "support for @types packages out-of-the box" mean for something as different from typescript as flow is? #7 (comment) gives 3 options; only the first two seem to match your use case, and both of them have down-sides that border on infeasible.

If I were in a bigger team, I expect the balance would tip toward Typescript for the same network effect and inertia reasons you cite, but I most code on hobby projects where I control the horizontal and the vertical; I'm getting by with, for example, flow-typed install express. Yes, there aren't as many of these as there are @types packages, but I'm sufficiently hooked on flow (comment annotations, emacs flycheck integration that's really fast, refinement types...) that I deal with it. The typescript type system seems to be catching up with flow; I haven't studied it as thoroughly as perhaps I should. I'm really reluctant to add a build step to my projects. That might be the biggest thing that keeps me off typescript.

[mgcrea]

I would personally not mind having dumbed-down version @types support that sacrifices soundness for practicality, as most of the benefits I get from typings is having instant in-place API documentation and catching trivial errors (missing member, etc.), and I guess that's what appealing to most typing "beginners". But I can understand that developers with way more typing-related experience find it not worth the trouble.

I guess I'm just afraid that flow won't survive as a viable typing tool if this trend continues, and I'd really hate to evolve in a TypeScript-only world.

[kaushalyap]

@samwgoldman , @jeffmo Any plans to support Typescript type definitions?