Road to Typescript

This is an issue is to discuss our plan to convert this library to TypeScript. Note: We will still continue to provide full Flow typings in the same package.

This effort is in line with the ongoing conversion of GraphQL IDE packages (GraphiQL, GraphQL LSP, etc.): https://github.com/graphql/graphiql/tree/convert-to-ts

Note this decision is not related to the technical aspect of Flow vs TS. GraphQL.js has complete Flow coverage and it is excellent for ongoing maintenance. But our goal is to increase the number of active contributors and by switching codebase to TypeScript we hope to make the codebase feel more familiar and easy to contribute to.

Big thanks to @JacksonKearl from Apollo team for making PoC for such conversion and exploring different conversion strategies.

Before we start discussing the action plan here is a few important points:

• 14.x.x is stable release so we shouldn’t do any potentially breaking things in this release.
• We need to do 15.0.0 anyway since it becomes hard to maintain support for Node6 since ESLint and other projects stop supporting it. Plus it allows us simply remove all deprecated stuff that was scheduled for removal in this release.
• Even after we release 15.0.0 we will still need to support 14.x.x as a branch and backport all critical or security-related bugfixes until 16.0.0.

Giving these constraints here is a plan I want to propose:

• 1. Freeze all non-critical merges for the duration of this conversion
• 2. I copied all *.d.ts from @types/graphql into tstypes folder and working on removing it from DefinetlyTyped. I included this typings in 14.5.0 release as the baseline for our future work.
• 3. Synchronize *.d.ts files with Flow types (some stuff is missing and a lot of types are based on 14.0.0 release) and identify all changes that were done in @types/graphql but weren’t reflected in Flow. We will release these changes as 14.5.1 release.
• 4. After we are sure that *.d.ts files are complete and don’t break existing TS libraries we can branch of 14.x.x and switch master to 15.0.0-alpha.1. Remove all stuff marked as deprecated and was scheduled for removal in v15.
• 5. We will start manually converting files one by one to TS and extract Flow typings into separate files. I propose first to convert all test files (should be pretty fast since they don’t use a lot of typings) and latter switch to converting the rest of the project. We can schedule frequent 15.0.0-alpha.x releases just to get the early feedback.
• 6. After we converted all files we can switch to 15.0.0-beta.x and ask the different project to test both our TS and Flow typings. After we fix all the issues we would release 15.0.0 and finish this conversion effort.

Also, I think it makes sense use this opportunity and fully convert our codebase to ES6 and idiomatic TypeScript. It means we can finally get rid of pre-ES6 classes constructs and also some weird constructs caused by Flow technical limitations and other similar artifacts.

CC: @kassens @Neitsch @jbaxleyiii @JacksonKearl @martijnwalraven @mjmahone @acao @19majkel94 @tgriesser @nodkz @benjie

[IvanGoncharov]

Closing since we successfully migrated main to TS. Big thanks to everyone who helped in that 🙌

[ephemer]

@mike-marcacci I have been working on this the last week and have a shim over the plain graphql that strongly types pretty much everything I can think of. It’s about 150 lines of (almost exclusively TypeScript) code + comments .

Ideally I would like to get this functionality into the plain graphql repo too, so I am happy to share thoughts and techniques on this if anyone finds it useful.