Typescript definition generation added to tsconfig.json

[mlegenhausen]

You already write postgraphql in typescript with this pull request all other typescript programmers (like me) can benefit from this when they use postgraphql as library instead as cli tool.

I just enabled declaration in the tsconfig.json and added some needed exports to get the .d.ts generation working.

[calebmer]

Why did you remove allowJs? Some of PostGraphQL’s files like createPostGraphQLHttpRequestHandler.js are written in plain JavaScript as it is more convenient, and we naturally play a little more loosely with types.

[mlegenhausen]

The problem is you can not use declaration: true with allowJS: true thats why I removed it form the configuration.

Compiling with TypeScript
error TS5053: Option 'allowJs' cannot be specified with option 'declaration'.

Thanks for the hint I checked the result the http folder is missing in the build. There are already open issues for solving this problem: microsoft/TypeScript#7546

As alternative would you be ok to switch completely to TS? Cause for the file you described there is already an external .d.ts file. Wouldn't it much easier to maintain when both files would be combined? Beside that there are only 3 other JS files left (except the tests).

[calebmer]

The reason I avoided going full TypeScript is that we would have to install a lot of typings packages that would only be used in that one file 😣

If it’s not too hard, and we don’t have to add too many packages, I’d be fine with going for it. Another thing to note is that a lot of tests are written in plain JS and they would be very hard to convert. I think you wouldn’t need to convert them because they are executed by Jest. You may just need to add a custom transformer for Jest and test .js files.

Another alternative is we could just provide declarations for our exports, which while duplicative is a valid approach (their equivalence can be tested). Or do you want declarations for internal modules as well?

[mlegenhausen]

With the recent typescript version there is no need at all to define declaration files for packages. There are totally optional now. See https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-1.html and the "Untyped Imports" section.

I don't think that the tests needs to be ported to typescript cause there irrelevant for the production build. Maybe the way to go would be two different tsconfig.json files one for testing and one for building where we enable/disable what is needed?

[calebmer]

We do turn on noImplicitAny, though 😣

Yeah. The tests really shouldn’t be ported. I don’t think we’ll need two tsconfig.json files, but if you can get us running with two we can see about shuffling them around 👍

[mlegenhausen]

I will give it a try.

[calebmer]

Nit: could you put this bellow line 4? I like to put all of the file output options together 😊

[mlegenhausen]

Sure :)

[calebmer]

Nice! Just a couple of comments, but we’d be happy to share the types with everyone 😊

[benjie]

@calebmer Is this good to merge?

[zopf]

+1 for making PostGraphQL directly importable into TypeScript projects. I'm using a typings workaround for it now in my project, but would love not to have to do that.

[murpyslaw]

@benjie @calebmer any updates on this? we're using postgraphql in our project, and we have a sizable dev team. This pull request would be excellent, instead of having to npm install directly from github. If it could also be merged into @types that would be great.

I have sufficient time to do this, but it seems done already. Could y'all please merge if it's acceptable?

Cheers
rivanov

[benjie]

Hi @murpyslaw,

v4 is moving over to using Flow (slowly - currently all the graphile-build tools that generate the schema are in Flow but the PostGraphQL wrapper is still TypeScript) so I fear merging TypeScript support now only to have it deprecated very shortly thereafter would be annoying.

I'd rather export explicit hand-written library typings than auto-generated ones from the code so that we can easily move between type systems without breaking people's code. If you wanted to craft these you'd be most welcome to.

(Incidentally are you using v3 or v4?)

Cheers,

Benjie.

[murpyslaw]

@benjie

I see. I was not aware of this change. I've never worked with Flow before, nor am I familiar with whether or not it can output type definition files or if it just checks against the JS code.

Incidentally, our whole stack is in TS. Could you comment on how this architectural change could possibly affect our project, and why postgraphql has chosen to move away from TS? I am wondering whether, at this early stage of our project, this might be a good move to follow.

Postgraphql is an integral part of it, one which we've grown very fond of. I'd really dislike having to rewrite resolvers in TS or POJO, and move all of our business logic out of the DB, which is something which we've recently committed to.

Thanks for your time,
and
Cheers
rivanov

P.S. We are on 3.5.0

[zopf]

My $0.02: I'm agnostic to using Flow or TypeScript... they end up being quite similar in structure anyway, and the nice thing about Flow is that you can upgrade your own codebase to being typed gradually, rather than needing to type the whole thing immediately (if working with a legacy codebase).

I would actually support the move to Flow... our devs are using it with React and React Native and enjoying it... wouldn't be the worst to have a standard toolset across the whole codebase 😄

@murpyslaw in the meantime, I'm not sure how much typing you need, but if you just need types for the middleware, please consider using my simple workaround for the postgraphql middleware: https://gist.github.com/zopf/36770cbe73ecb2617c5fa7da99fc8ed6 -- just put tsconfig.json in the root of your project next to your package.json and put postgraphql.d.ts in typings/ (or whatever route you'd like to configure in the typeRoots field of tsconfig.json)

[benjie]

If someone wants to maintain a typings package for PostGraphQL that would be very welcome 👍

Could you comment on how this architectural change could possibly affect our project

Regarding how it affects your app, so long as you just use the public interfaces I don't think it should.

Honestly I'd just treat all packages on npm as "JavaScript" and add typings for whatever language you choose to use at the application level (e.g. by pulling them in from typings repos or writing them myself). So long as our code runs on Node.js and exposes the same interface I don't see any reason that we shouldn't be able to move to BuckleScript or Elm or any other language. And the great thing about implementing independent typings files is that we can have typings for all the different languages and if we later change to a different language the typings should still be valid (so long as we expose the same interface).

and why postgraphql has chosen to move away from TS?

As for why:

1. Most importantly: I'm more familiar with Flow, and I'm writing the bulk of the code
2. I don't personally trust TypeScript, I've had a number of issues in the past that turned out to be issues with how TypeScript parsed my code, this is just my personal experience
3. Caleb, who I trust on matters of TypeScript vs Flow given he has a fair amount of experience with TypeScript and now works on Flow, has hinted before that Flow is technically superior to TypeScript in a few areas, for example: https://twitter.com/calebmer/status/893855996161826817

Postgraphql is an integral part of it, one which we've grown very fond of.

Happy to hear that!

I'd really dislike having to rewrite resolvers in TS or POJO, and move all of our business logic out of the DB, which is something which we've recently committed to.

I use PostGraphQL from vanilla JS projects just fine; I don't see any reason you'd need to move away.

If you were to move away, there'd be no need to move your business logic out of the DB - just call that same logic from your new implementation! That's one of the great things about PostGraphQL - there's no lock-in because all the important parts will remain - we're just the thing that exposes that. I've used this to enable microservices to talk directly to the DB before and have the same access constraints as PostGraphQL would have.

[murpyslaw]

@zopf Thanks for the link, unfortunately these are not all the types that this MR provides, hence the thread here.
@benjie I'm not sure which is "superior", but have you seen this talk?

Yes we do use the public interfaces, it's just that they're not exposed. I suppose I rely so heavily on this package, that I could volunteer to do the DefinitelyTyped for it, which will automatically pull it in to @types/postgraphql. I'm not sure when I'll do this though, but it seems like a great option to contribute to a fantastically done project.

@calebmer @benjie is this mergeable into 3.5.0 master? The travis build was successful.

Also can't dts-gen be run over the codebase to produce the required .d.ts files? All that would need to happen is this MR goes through and exports all the relevant types, the rest can be automated, without any human interaction.

Cheers
rivanov

[benjie]

So reading through Caleb's comments from before; the issue preventing this from being merged seems to be the removal of "allowJs": true because we're not 100% TypeScript.

I'd definitely support you doing the DefinitelyTyped for it.

I have no experience with dts-gen.

[benjie]

[semi-automated message] Hi, there has been no activity in this issue for over 8 weeks so I'm closing it to keep the issues/pull request manageable. If this is still an issue, please re-open with a comment explaining why.

[devuxer]

This is a really exciting project. Thanks to @benjie for all his work on this. I get that maintaining typings is a lot of work, but having them available via @types/postgraphile would really reduce the friction in getting started for typescript users. It seems that TypeScript has reached critical mass, as it's pretty rare these days to find a library that doesn't have a typings package available. Anyway, I'd definitely like to see this issue reopened.

[benjie]

This is about adding typings directly to the library. I'd definitely support someone writing/maintaining typings via DefinitelyTyped. You can send PRs to them directly, I think 👍

[devuxer]

@benjie, ahh, I see now. I originally came to this thread via #520, and I think I got confused as to which was proposing which. I have another follow-up comment, but I'll post that there.