Set up static typing

[stubailo]

I think the complexity of this code is reaching the point where having static type error detection would really help with development speed and documentation. There are a couple of concepts - selection sets, query ASTs, cache objects, etc - that are being passed around constantly and it can be hard to figure out errors where those objects aren't properly formatted. If there's a solution to this problem that doesn't involve static typing, I'm all ears.

As far as I can tell, there are two options for static typing in JavaScript:

1. TypeScript: http://www.typescriptlang.org/
2. Flow type: http://flowtype.org/

TypeScript seems to be an all-in-one solution that also covers transpilation of new JS features in addition to type annotations. It also has integration into IDEs like visual studio code, which might be nice to use to avoid having to set up a bunch of stuff.

On the other hand, Flow is used in Facebook so it might be possible to take advantage of existing definitions in the GraphQL and Relay codebases.

On the third hand, TypeScript is starting to become a thing in the Angular/Angular 2 community.

What about contributors?

I think the core of this project will be pretty hard to contribute to anyway. I think the best thing we can do is have very clean APIs and as minimal a core as possible so that people can easily build extensions. IMO it would be OK if a contributor to the core caching logic has to understand static typing, as long as we keep this core as small as possible (I think this repo won't include router integrations, view integrations, etc - just the caching, diffing, fetching, and aggregation of queries).

Really interested to get feedback about this from some people - @jbaxleyiii, @arunoda, @Urigo, @benjamn?

[jbaxleyiii]

@stubailo I'm all for it. I think we should go with flow since we can dot things import type { Document } from 'graphql/language/ast'; (as far as I can tell, I'm new to flow). I've started work on adding it here #8

[stubailo]

Whoooooa if you can import like that, that is a killer feature.

[jbaxleyiii]

@stubailo https://github.com/graphql/graphql-js/blob/master/src/language/ast.js#L71-L75

[martijnwalraven]

I'm a big fan of static typing, and I really miss it in JavaScript. As you mention, it is not just about correctness, but it also improves documentation of the code and avoids too many ad-hoc structures with slightly different semantics to be passed around. Just spent two days debugging issues in the Meteor build tool and constraint solver, and I feel typing would really have helped there.

[mquandalle]

I definitely agree that typing will help avoiding errors and writing better APIs. Typescript vs flowtypes is sadly a difficult topic.

I’ve been playing with Typescript because I found it easier to set up and it works on Windows, Mac, and Linux. The DefinitelyTyped repository also have typing definitions for a lot of popular libraries (including Meteor APIs), and I never had to write these definitions myself. On the other side, Flowtype supporters argue that Flowtype better support null and undefined handling, but that’s also coming very soon to Typescript (microsoft/TypeScript#7140). VSCode integration is also awesome (I haven’t tried Facebook’s Nuclide though).

BTW @jbaxleyiii it’s also possible to import a type or an interface from another file in typescript.

[jbaxleyiii]

@mquandalle that sounds great. I'll probably do the same conversion I did with flow using typescript so we can evaluate both of them fairly.

[mquandalle]

I didn’t see #8!

Trying to do the same thing in Typescript sounds like a good idea, unfortunately I haven’t found Typescript interfaces for GraphQL. (BTW with flow are you able to import types for lodash for instance, or do the original source has to contains the flowtypes?)

[jbaxleyiii]

@mquandalle from what I understand, the original source has to contain and export flow types. Otherwise you can create them. Flow actually uses underscore as an example so writing it for lodash would be pretty easy. http://flowtype.org/docs/third-party.html#example

[stubailo]

I feel like using TypeScript with the VS Code IDE, etc, is a pretty big selling point. We should see what it's like with Nuclide as well.

[fabiodr]

Tooling welcomes enterprise apps, an introducing team feels more confortable for experimenting and enjoying. TypeScript would bring many static typing friends.
+1

[stubailo]

To be clear, let's make sure we separate two related issues:

1. Which type system we use internally to develop this library, and
2. Which type system people consuming the library can use

Ideally, (2) would be both TS and Flow. So it's just a question of which one we use internally first.

[mquandalle]

Well, for the moment it’s difficult for libraries authors to provide both typescript and flow types to consumers because of the slight differences in their respective type system (this is discussed a bit in facebook/flow#7), Unless of course we are willing to maintain both interfaces manually. But at least while the Apollo stack evolves quickly, we should expect lib consumers to use the type system of lib authors.

[jbaxleyiii]

@stubailo @mquandalle after about 30 minutes with typescript + VSCode (and atom) I'm 1000% supportive of typescript. I should have a PR done tonight for it. Its incredible

[stubailo]

Hahahah awesome. Let's try it! I've heard it's pretty magical. And it replaces our Babel build process too right?

[mquandalle]

Yes (but if for some reason we want to keep Babel, we can ask Typescript to target ES6 and then run Babel on the Typescript result. Obviously relying on Typescript for the entire compilation is more efficient).

Also to address one point in your original post @stubailo:

What about contributors? I think the core of this project will be pretty hard to contribute to anyway. [...]

I haven’t tried Flow, but with Typescript I can say for sure that it makes third-party contributions easier, not harder. It’s like GraphQL introspection capabilities. You underline a function call in VSCode and you can read its signature and its documentation inline, typing an object name and see all its methods, and get all your beginner errors linted in a reliable way. I’m sure you will agree, but I just wanted to make the point that typing + good editor support (either VSCode or SublimeText or Atom with the appropriate extension) actually help contributors diving into the code—I did the experience with VSCode open-source code base and I felt empowered!

[stubailo]

sure, I think we should have a small guide about tools - like how to import the project into vs code etc. I should try it soon.

[jbaxleyiii]

@stubailo @mquandalle I've got a start on typescript but have run into a few issues. They are detailed on #10

[stubailo]

@jbaxleyiii sorry for flip-flopping, but it just took me like 10 seconds to set up Visual Studio code and typescript and it "just works". I still haven't been able to set up Nuclide/Flow properly. And I've already found some bugs because the type checking works really well.... maybe we should go with TypeScript after all?

[jbaxleyiii]

@stubailo no worries! Its why I did both branches 👍 Play around with typescript while I get flow back working. I know I had it at one point haha. That way you can easily evaluate both options.

Fwiw, I prefer the forcefulness of typescript if its configured. Its a good example of slow down to speed up. But the concerns around typescript and .ts is 100% valid.

[stubailo]

Yeah there are also issues like:

microsoft/TypeScript#2103

Where TypeScript doesn't support certain language features that are trivial to use with Babel. So we have to restrict ourselves to the subset of JavaScript supported by TypeScript.

[mquandalle]

Well I also miss the spread operator syntactic sugar, but the reason the Typescript team hasn’t implemented it yet is because it is not a part of the ES6 specification. So I wouldn’t say that Typescript users have to restrict to a subset of Javascript, actually if you take a Javascript program (ES5 or ES6) program, there wouldn’t be any syntax error in Typescript (only potential type errors). The problem is about features that aren’t part of the spec, like decorators (even if in this case typescript has experimental support) or object spreads (which should be implemented soon due to the high demand).

[stubailo]

language features that are trivial to use with Babel

Right, I'm not referring to "real" language features. It's just a fact that they work with Babel but not TS, regardless of their standards track status. Just something to consider.

[stubailo]

We're done here!

I got the testing and test coverage to work as well! So now Travis CI is happy.

[nmn]

I know this discussion ended. But I want to make a few quick points:

1. Flow handles Null and Undefined Better, which is very important, but then Typescript will get it soon enough.
2. There are linter-flow and autocomplete-flow plugins for atom if Nuclide is being a pain.
3. Flow is much better at inferring types automatically, and better handling dynamic code.

On the other hand, the fact that typescript runs at compile time has one big advantage over the background checking that flow does:

1. With some work, by providing the GraphQL schema, you can auto generate type definitions from graphQL queries which can then be checked by typescript. Angular 2 is doing something similar with its templates.

[stubailo]

This thread has no relation to what users of the library need to do - it's just for the internal development.

[nmn]

@stubailo I know. Just couldn't find another place to reach out to the team about this.

[tonyxiao]

@stubailo I remember you wrote a post (maybe on Medium?) about choosing TypeScript vs. Flow for Apollo. I can't seem to find a link to it anymore. Do you remember where it is?

[ciszak]

@tonyxiao There is a medium post mentioned in readme: https://dev-blog.apollodata.com/javascript-code-quality-with-free-tools-9a6d80e29f2d Maybe it's the one you're trying to find (if you haven't found it already, as I'm 3 weeks late;).