build: add tsc type checks and emit declarations in the ci/test pipeline

[lance]

This commit introduces TypeScript checks and generates type declarations for the existing JavaScript codebase using tsc prior to running the linter task. This is similar to @grant's pull request, but keeps the code base as pure JS mainly by just keeping the entry point index.js instead of .ts.

I am proposing this as a very slight alternative. Since I'm not fully familiar with the TypeScript tooling, I wasn't sure if the type declaration files should live side-by-side with the JS or not, but I assume they should be kept in SCM. Feedback welcome.

Ref: #9

[helio-frota]

I have limited knowledge in TS.
But since I was requested to review the PR I'm approving based on:
but keeps the code base as pure JS mainly by just keeping the entry point index.js

[lance]

/cc @johnm @cwallsfdc @erikerikson @loopingz @DavidWells - feedback from you all is welcome.

[grant]

If we're going the "never change .js to .ts at all costs" route, I would at least do the following:

• Git ignore all generated files. These .d.ts files are not hand-written, they are generated.

I'm surprised that we're ok with generated .ts file bloat, but not normal .ts files that would do the exact same thing. We're even using tsc – how are we fine using tsc but not .ts? It's literally part of TypeScript. If you just renamed the files, you wouldn't see duplicated files and large PRs...

[lance]

@grant again I think you are not representing my position in good faith. I have never said that we are going the "never change .js to .ts at all costs" route. Or if I did say it early in this debate, I think it's pretty clear that I have proposed a gradual path. That said, thanks for your feedback.

I humbly asked what was the right thing to do with those .d.ts files, so there's no need to be snarky about bloat and again dismissive of my other concerns such as existing maintainer alienation and the potential pool of contributors.

[grant]

@lance Oh, I'm not trying to be snarky. I'm trying to get TypeScript support here.

It's common to not include generated code in git repositories, as it can simply be generated from the source code again. In this case, we are generating files with the extension .d.ts. These files should not be included with the PR.

Emitting declarations is fine for local development but shouldn't be seen on GitHub or npm.

Again, this is a weird way to beat around the bush and use legacy TypeScript features for unideal projects. Ideally, like most modules, we don't need any .d.ts files.

See the handbook for more details:
https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html

[grant]

Ideally we don't need .d.ts files.
But if we have them, they shouldn't be checked into source control.

[lance]

It's common to not include generated code in git repositories, as it can simply be generated from the source code again. In this case, we are generating files with the extension .d.ts. These files should not be included with the PR.

OK - I will update it.

Emitting declarations is fine for local development but shouldn't be seen on GitHub or npm.

The handbook you link to is all about publishing your .d.ts files to npm, so I'm confused by this statement.

[grant]

The handbook you link to is all about publishing your .d.ts files to npm, so I'm confused by this statement.

Yes. The link has really useful guides in using TypeScript, including best practices. The issue about files on npm is just one of the comments on the added dependencies in this PR. I recommend reading it.

It will clearly recommend using TypeScript .ts files for dozens of benefits.

[grant]

Are we planning on ignoring #137? Can we merge it?
This Pull Request, #155 will clearly conflict with that one.

I don't understand.

[lance]

I don't understand.

As I wrote in the description 🤷‍♂️

I am proposing this as a very slight alternative.

[grant]

We can't just ignore people's pull requests and create/merge your own without discussion!

Why can't we just pool together experience and collaborate!

[lance]

@grant I'm not ignoring your PR - I'm proposing an alternative because we have been doing nothing but discussing this for a while now. There has been a lot of discussion. I wish you could acknowledge that I'm at least trying to find some common ground here.

[grant]

Thanks Lance for listening through these discussions.

Can you review the PR and not create new PRs that conflict with old ones?

[erikerikson]

Thank you @lance for providing this as an alternative and clearly marking it as such.

@grant it's not clear where Lance has merged his own PRs (although pretty obvious he created this one). As he's indicated the point of this is to give substance to the discussion that has been ongoing and he does seem to be acting in good faith.

[cwallsfdc]

@lance, I appreciate that you are compromising. But, if you are willing to run tsc and are now familiar w/ tsconfig.json and also understand the value of typings, I think we should favor @grant's PR.

Can we move to .ts and relax typical Typescript requirements in tsconfig.json so that those who contribute as JS authors still feel empowered to do so? Is it possible to be .ts and still follow JS constructs? If so, I'm confident that JS developers can still be productive in .ts files. And, my hope is that, over time, they'll appreciate the value-add that Typescript bring.

[lance]

@cwallsfdc can you help me understand what doing that actually achieves if the stated intent is to stick with pure JS syntax? Why go through the transpilation step if we're going from pure JS in a .ts file to pure JS in a .js file? Does the enabling of code completion through type definitions and quality JSdoc not get us to a user experience like the one that Grant has been looking for?

I realize that you and others may find it hard to understand why I don't want to immediately move to .ts and code transpilation, although I have stated that I see this as a first step on a possible continuum. But similarly, I find it hard to understand what that next step gets us. What is gained?

Isn't the goal to have a better experience for users of this SDK? If so, how does my alternative approach not achieve that in an equivalent way while also allowing room to move forward with something further along the continuum later?

[lance]

help me understand what doing that actually achieves if the stated intent is to stick with pure JS syntax?

It seems that this is a fundamental misunderstanding on my part. It's become quite clear that this is not the actual intent.

[lance]

Just so it's tangible, here is code completion in the IDE.

[erikerikson]

Including the JsDocs for immediately answering semantic questions non-experts and those trying out the SDK may have. Regardless of the final approach to tooling, I expect that enriched JsDocs will be a positive addition to support adoption and ongoing usage.

[grant]

help me understand what doing that actually achieves if the stated intent is to stick with pure JS syntax?

It seems that this is a fundamental misunderstanding on my part. It's become quite clear that this is not the actual intent.

It is the intent. What do you mean it became quite clear that intention changed? You are insinuating malintent.

I can imagine we could add a TS interface for a CloudEvent object in the future if agreed upon. How else will we see object autocompletion without getters and setters?

[grant]

This looks pretty good. Thanks for the PR @lance!
Let's go with this.

[lance]

@grant I honestly do appreciate you making this compromise, helping us both find a path forward towards making this project what we both want it to be -- a high quality, stable and and user-friendly module. Though our conversation has been heated at times, I look forward to putting all of that behind us and working together with you and the rest of the community to make that happen.