TypeScript support

[danielkcz]

I am curious if it's planned? From my experience, it is so much easier to have a project written in Typescript instead of creating ad-hoc typings and maintaining those (same way as react-apollo does it).

It's not a problem to use .mjs, the TypeScript is able to emit full ESM module, although it will be with .js extension so there would need to be an extra step of renaming those, but that should be easy.

[jaydenseric]

Thanks for the suggestion, but not being typed is an intentional differentiation from Relay and Apollo. We won't use TypeScript here for a few reasons:

1. It limits the ability to contribute to a very small group who are familiar with TypeScript.
2. It makes the source code illegible to most people. They might not understand it and they might not have TypeScript syntax highlighting configured. Lots of consumers like to read the source code just to understand it, without the intention of modifying anything.
3. For people willing to learn to make a contribution, fiddling with types can make what would have been a quick PR a complex effort. I experienced this a lot when I began contributing to Apollo.
4. TypeScript is not friendly to .mjs with several issues. For example, it outputs invalid ESM by mixing in require. Apollo has given up trying for now.
5. "type safety" is an illusion when the typed code you write is dwarfed by the untyped code bundled from node_modules. DefinitelyTyped and flow-typed are the worst idea ever: Third parties chasing the end of the rainbow documenting code isolated from the source. Importing a dependency and using it is no longer a simple exercise. Neither is updating dependencies.
6. Trying to hack JS into a cumbersome, strictly typed language prevents using elegant and useful patterns that take advantage of the flexible nature of JS for minimal bundle size.
7. Unlike TypeScript types, radically updating JSDoc (renaming types, etc.) is not a breaking change.
8. Being able to avoid the TypeScript compiler with Babel v7 is a big step in the right direction, but it's still early days. The TypeScript compiler is far behind the evolution of Babel regarding transpiling for the environment a la @babel/preset-env. Chaining a second Babel compile after TS is pretty inefficient and it can get in the way of fine-grained optimizations via Babel plugin config.

My intention is to only reduce the code we have now, and never exceed around 1-2 KB source. JSDoc is manageable at this scale and documentation.js is working well to keep the API in the readme up to date.

Where possible I strip transpilation from projects once Node.js and browsers are able to handle the APIs and language features used natively. Once IE11 dies off a lot will change fast. Everyone should be working towards a native, standards based web and I don't believe in TypeScript as a permanent fixture.

[danielkcz]

Thanks for your detailed explanation, at least now I know I can safely ignore this project ;)

I am not going to try to convince you, but I think you are kinda biased against TypeScript right now, so I will just leave a few pointers. I would like to you invite to read my recent article about TypeScript.

1. TypeScript adoption is growing and with its ability to infer a lot of things, you might not even spot a difference.
2. Pretty much same as 1) With eg. VSCode everything works out of the box. And GH already has syntax highlight for TypeScript, no problem there.
3. Of course, there is some extra effort needed, but often it gives you a lot of benefits back.
4. I am not sure why is Apollo struggling with that, haven't investigated, but TypeScript is able to emit ESM module (without require) just fine.
5. Do you realize that if adoption of this module will grow, somebody will create separate typings to it anyway? There are people who like the convenience of typed code and they would rather "chase the end of the rainbow" or not to use the module at all.
6. This is definitely just a bias without any proof.
7. There is my response to the article about JSDoc comparison.. The biggest hurdle with JSDoc is that it's easy to get unmaintained and misleading. You are also missing out on a lot of useful tools like automated refactoring that comes with VSCode.
8. Are you sure about that? :D I would say it's quite opposite way. For example I can use <></> (fragments) in TypeScript right now instead of using some beta of Babel which lacks general support in other areas. I haven't found a single feature that Babel would have and TypeScript would not. Well, except decorators, but given those are still lacking proper spec, I don't care about that.

Frankly, I couldn't work anymore without TypyScript telling me the result of my queries or what variables are required for a mutation. You can never achieve that level of conveniece with JSDoc.

[vladshcherbin]

Just came to see if this package is written in TS and was pleasantly surprised it's not.

@jaydenseric I share all your thoughts, contributing to a TS project (even a small one) and reading its source code is a hell for non-TS person.

I'll definitely give this package a shot next project instead of apollo. Huge 👍 from me for your choices.

[Risbot]

@jaydenseric But you can write code in javascript. For the support typescript is needed only add d.ts file.

[joelgetaction]

@jaydenseric I share your reasoning - I avoid Typescript in my projects so I welcome your decision to avoid Typescript here! :-)

[mike-marcacci]

Types are now available by adding the @types/graphql-react package.

[mike-marcacci]

Also, just to be clear, I am completely in agreement with the decision to keep this codebase in js and not ts.

I'm frustrated by the explosion of brittle, cobbled-together build systems acting as gate keepers to open source projects. Adding these definitions to the DefinitelyTyped repo was just excruciating, and epitomized the pain points described above.

All that said, I did write definitions for a project and figured I should share them.

[ecwyne]

Thanks for the the typings @mike-marcacci! Am I missing something or is there no type information for GraphQLProvider?

[ecwyne]

Ah I see. It's <GraphQLContext.Provider value={this.props.graphql}>

[jaydenseric]

This situation has changed considerably since 2018, now it's possible to support TypeScript (cutting-edge versions at least) via TypeScript flavoured JSDoc comments within .mjs ESM modules. For both authoring and consuming my packages, here are some goals moving forwards:

• Standard ESM. Published modules universally run in Node.js, Deno, and browsers.
• Zero builds. The code we write is the code that runs. People can optionally "optimize" modules in their projects if they so choose (e.g. via CDNs that minify on the fly), but it shouldn't be a requirement to reasonably efficiently run the code.
• Type safety. Package code is type checked in GitHub Actions CI, and high quality types are automatically available to consumers of the packages in their projects without additional work such as installing type definitions or annotating imports with @deno-types comments.
• Highest quality intellisense. All public exports have detailed JSDoc descriptions and rich content such as examples and links to other relevant parts of the API using JSDoc @link, @linkcode, @see, and @example tags.

Unfortunately, using the TypeScript flavour of JSDoc means the API docs in the readme can no longer be automatically generated using jsdoc-md, so for now these docs will be written by hand. Hopefully In the future Deno doc will support import maps (see denoland/docland#85) and then our readme for each exported module will just need to link to the module docs at https://doc.deno.land .

Because there are 30 exported modules, it might not be worth the effort to repeat by hand in the readme markdown the documentation already available by reading the source code JSDoc comments or using intellisense. In that case, we might just list in the readme the exported modules and skip documenting their contents.