Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support for TypeScript definition files #7

Open
mbektimirov opened this issue Nov 18, 2014 · 56 comments
Open

Support for TypeScript definition files #7

mbektimirov opened this issue Nov 18, 2014 · 56 comments

Comments

@mbektimirov
Copy link

@mbektimirov mbektimirov commented Nov 18, 2014

After the first look on Flow I can say it is inlined Typescript. Are you planning to support .d.ts definitions to make type headers unified? And what about es6 state? Does flow support it?

@benjamingr
Copy link

@benjamingr benjamingr commented Nov 18, 2014

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
Copy link
Contributor

@cirocosta cirocosta commented Nov 18, 2014

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
Copy link
Contributor

@avikchaudhuri avikchaudhuri commented Nov 18, 2014

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

@samwgoldman samwgoldman changed the title Support for typescript and es6 Support for TypeScript definition files Jun 24, 2015
@samwgoldman
Copy link
Member

@samwgoldman samwgoldman commented Jun 24, 2015

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
Copy link

@0xR 0xR commented Jun 26, 2015

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

jeffmo pushed a commit to jeffmo/flow that referenced this issue Jul 31, 2015
Add support for XML/XJS identifier namespaces
@clentfort
Copy link
Contributor

@clentfort clentfort commented Oct 20, 2015

Is there any progress/roadmap on this issue?

@gcazaciuc
Copy link

@gcazaciuc gcazaciuc commented Oct 22, 2015

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
Copy link

@gitawego gitawego commented Oct 29, 2015

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
Copy link

@mattmo mattmo commented Dec 2, 2015

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
Copy link

@dumconstantin dumconstantin commented Dec 2, 2015

+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...

@jeffmo
Copy link
Member

@jeffmo jeffmo commented Dec 9, 2015

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!

@dumconstantin
Copy link

@dumconstantin dumconstantin commented Dec 9, 2015

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
Copy link
Contributor

@dckc dckc commented Dec 11, 2015

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
Copy link
Contributor

@dckc dckc commented Dec 11, 2015

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

@jeffmo
Copy link
Member

@jeffmo jeffmo commented Dec 11, 2015

@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
Copy link
Contributor

@dckc dckc commented Dec 13, 2015

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
Copy link
Member

@jeffmo jeffmo commented Dec 15, 2015

@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
Copy link
Contributor

@henridf henridf commented Dec 23, 2015

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
Copy link
Member

@jeffmo jeffmo commented Dec 24, 2015

@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
Copy link
Contributor

@bassettsj bassettsj commented Feb 23, 2016

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
Copy link

@gregegan gregegan commented Feb 23, 2016

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

@bsr203
Copy link

@bsr203 bsr203 commented Mar 16, 2016

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

@sheerun
Copy link

@sheerun sheerun commented Aug 21, 2016

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.

@amilajack
Copy link

@amilajack amilajack commented Aug 21, 2016

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

@Kegsay
Copy link

@Kegsay Kegsay commented Sep 21, 2016

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.

@mweststrate
Copy link

@mweststrate mweststrate commented Nov 2, 2016

@Kegsay any update on the converter?

@bsr203
Copy link

@bsr203 bsr203 commented Nov 2, 2016

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

@mweststrate
Copy link

@mweststrate mweststrate commented Nov 2, 2016

Feeling stupid now :) Thanks!

@Kegsay
Copy link

@Kegsay Kegsay commented Nov 3, 2016

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

@joarwilk
Copy link

@joarwilk joarwilk commented Nov 18, 2016

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.

@Kegsay
Copy link

@Kegsay Kegsay commented Nov 18, 2016

@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
Copy link

@joarwilk joarwilk commented Nov 18, 2016

@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
Copy link

@andreawyss andreawyss commented Dec 12, 2016

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

@joarwilk
Copy link

@joarwilk joarwilk commented Jan 4, 2017

@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.

@btipling
Copy link

@btipling btipling commented Mar 7, 2017

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.

@sheerun
Copy link

@sheerun sheerun commented Jul 1, 2017

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

@rattrayalex
Copy link

@rattrayalex rattrayalex commented Jul 7, 2017

@vojtatranta
Copy link

@vojtatranta vojtatranta commented Nov 21, 2017

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?

@idanilt
Copy link

@idanilt idanilt commented Dec 4, 2017

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
Copy link
Contributor

@mrkev mrkev commented Sep 10, 2018

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

@mgcrea
Copy link

@mgcrea mgcrea commented Oct 15, 2018

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.

@dckc
Copy link
Contributor

@dckc dckc commented Oct 16, 2018

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
Copy link

@mgcrea mgcrea commented Oct 16, 2018

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.

@dvins
Copy link

@dvins dvins commented Oct 25, 2018

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.

@goodmind
Copy link
Collaborator

@goodmind goodmind commented Apr 9, 2019

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

@goodmind
Copy link
Collaborator

@goodmind goodmind commented Jul 16, 2019

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

@dannyharding10
Copy link

@dannyharding10 dannyharding10 commented Dec 6, 2019

@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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
You can’t perform that action at this time.