[Proposal] [Typescript] Generate Typescript definition files dynamically

[franklixuefei]

Hi,

material-ui has become my favorite opensource project since early this year. The community is really active and responsive, thanking to all the contributors and members, especially @oliviertassinari for maintaining the repo and developing new features, and @pelotom for maintaining the Typescript definition files, and most importantly, it implements the Material Design so well.

Recently I've been taking a deep look at devextreme-reactive's work on the material-ui grid, and they support Typescript projects by dynamically generating the .d.ts files. Those type definition files are generated with each release by parsing the .md files that define the types for all the components across the project. I think this approach is really appealing for two reasons.

1. It completely eliminates the need to proactively maintain the type definition files, except for occasional type fixes in the .md files.
2. Defining types in .md files will not only be beneficial for generating the type definition files, but it's also great as a documentation because that's what .md files are for. In the future, if we need to add new features or components, we just need to remember to also include them and their types correctly in the corresponding .md files, and boom, the type definition files will automatically be generated in the next release. One stone, two birds.

FYI - this is their .d.ts file generating script - https://github.com/DevExpress/devextreme-reactive/blob/master/scripts/ts-generator.js

I know this would be some work if we ever want to go on this path, because we need to write the .md file for each component and then write the script to parse them into .d.ts files, but it would definitely pay off.

[pelotom]

Hi @franklixuefei, thanks for the kind words. I confess I'm a little confused by this approach... to me it's counterintuitive to start with a completely free text format like .md and then parse it to generate type files, rather than start with the well-constrained form of TypeScript files and generate .md documentation from them. We already had that technique working with the old Flow typings, and there exist similar tools to do it in TypeScript. I'm not sure what sort of types can be expressed in this .md DSL, but I feel confident that TypeScript types are best written in TypeScript itself. As far as stones and birds, it seems to me there are 3 birds:

1. Implementation code - currently written in .js files
2. Typings - currently written in .d.ts files
3. Documentation - currently generated from the Flow comments in .js files?

I believe we can kill all these birds with one stone: write the implementation in .ts, and generate docs for them using typedoc. @rosskevin made an attempt to achieve this convergence but it stalled at some point, maybe he can remind us of where that stands and what the difficulties are.

[oliviertassinari]

Documentation - currently generated from the Flow comments in .js files?

@pelotom The documentation is generated by the propTypes definitions. We do no longer use flow. Don't forget the fourth bird: the flow type definition that would be ideally automatically generated.

[pelotom]

Don't forget the fourth bird: the flow type definition that would be ideally automatically generated.

Do you mean proptypes?

[oliviertassinari]

I mean https://github.com/flowtype/flow-typed/tree/master/definitions/npm/material-ui_v1.x.x

[pelotom]

Ah, I thought we had given up on supporting Flow.

In that case it seems like we have 5 birds, because we'd ideally generate propTypes too, no?

[oliviertassinari]

@pelotom Yeah, it's not a priority to support Flow. But exploring the field of automatically generating the types. Someone might be interested in jumping in to do the job with Flow.

because we'd ideally generate prop-types too, no?

Yeah sure :). Given we have to make tradeoffs, here is how I think each bird relates to each other. The sum of the priorities equals 100. By priority, I mean, how much value I think it brings to the project. Of course, the execution is a way different story:

• 40: The api.md. At some point, we had the propTypes not working for months, nobody complained about it.
• 30: The propTypes, I believe TypeScript market share is at most 20%.
• 20: TypeScript, we had many issues with Flow. Also, editors can pick up the TypeScript definitions even if you write your code in raw JS 😍 .
• 10: Flow

[franklixuefei]

@pelotom Writing in pure ts would definitely solve the type definition issues for good, given that we do not support Flow anymore. But I can imagine that would be a lot of work porting to typescript. I think it's a tradeoff. I agree with @oliviertassinari regarding the priority, but I think we should still give Typescript a bit more priority :-D. Look at the numbers:


It's even greater than react-redux.

[rosskevin]

This is the last progress update on prototyping typescript: #9561

• istanbul issue is now fixed
• nextjs issue is now fixed

I believe it to be possible now to accomplish the incremental switch.

There may be one or two issues with the way we stub/replace methods in testing, but otherwise the PR mentioned above is the right direction with babel 7. We need to use babel 7 for the optimizations for a bundled build, but we do not if we are going to just build/release ES modules.

Regardless, I worked out a lot of kinks in the build/test process that could be referenced easily from the old fork and applied to a new effort. I don't a rebase will have any use, but eyeballing a merge against v1-beta might be interesting.

As you might expect - I am in support of moving to typescript.

[oliviertassinari]

I'm closing, we have started to go in the other direction: use TypeScript as the source of truth to generate the prop-types and API docs. A big thanks to @merceyz for starting this effort. I think that we can close now.