TypeScript types about sdk-javascript HOT 87 CLOSED

Honestly, I think a better approach is to convert to Typescript and include the typings in the cloudevents-sdk npm module. This way the lib and typing stay aligned. Migrating to Typescript shouldn't disrupt users.

If in agreement, I can post a PR w/ Typescript changes. We'd then publish a new cloudevents-sdk version w/ typings.

Thoughts?

from sdk-javascript.

b is so much better and easier.
This is what Google does with all JavaScript libraries.

from sdk-javascript.

To make it more "real" I did migrate the whole repo to typescript: https://github.com/loopingz/sdk-javascript
For the sake of rapidity, I took a few shortcut (it compiles and requires a bit more to be cleaner, use your formatter etc)

from sdk-javascript.

Yes, sure. I hope to find some time to write the declarations also of the remaining classes, hopefully in a couple of weeks :)

from sdk-javascript.

@micheleangioni, I had to change the typing to the following to match cloudevents.js's single export of Cloudevent.

https://gist.github.com/cwallsfdc/183c2df8dad88964efa957217b12c496

from sdk-javascript.

Google Cloud Functions uses it's own TypeScript types because this SDK does not have them.

Google Cloud Functions Framework:
https://github.com/GoogleCloudPlatform/functions-framework-nodejs/blob/v1.0.0/src/invoker.ts#L63

from sdk-javascript.

In order for me to contribute, I need master to not change as fast as it is. The commits made to master are not PRs, they are direct to master.

I would like to convert this repo to typescript, so that I can use the SDK with Cloud Functions, but last time I tried, there were commits to master that conflicted with my conversion.

All commits in this repo should be tied to a PR and all PRs are squashed so we can see the history change.

Aside, I don't really understand why we should have exceptions for reviews with certain import repos.

from sdk-javascript.

I would like to join migrating cloudevents to typescript!

from sdk-javascript.

A remark from a (rather inexperienced) typescript user: the provided types are not really flexible as they are more of an interface than a type definition. I think the whole structure would be much more versatile (i.e. usable in / connectable to other libraries) if you split the event builder pattern from the bare data model and use basic object attributes instead of getters and setters in the type definition.

In my case, I wanted to receive the events from rabbitmq and store them in mongodb but both libraries expect type definitions with bare objects (and for instance iterate over their keys).

from sdk-javascript.

@grant @fabiojose I would like to request that this repository NOT be converted to TypeScript. It is a mistake, in my opinion to assume that JavaScript and TypeScript are interchangeable.

@lance Can you please describe more? The library will still be compatible with JavaScript. I strongly recommend using TypeScript. What specific concerns do you have?

from sdk-javascript.

JS is OK for small projects, but CloudEvents and Node are used by large projects.

Additionally, types are super important for this project as the CloudEvent spec is very specific and has multiple versions.

Super important points.

Typescript, because of its inherent typing, is:

• more maintainable,
• reduces bugs (estimation that typing results in a 15% decrease of bugs),
• better for collaboration,
• better for 3pp use.

Typescript with generated type declarations, please.

from sdk-javascript.

Yeah, I guess it just depends on preference.

Personally, I prefer just javascript because there is a wider audience of developers who author code in JS. So in theory, the larger opportunity for OS contributions lies in pure JS. Additionally, I think Typescript has a larger learning curve and can be trickier for folks to pick up.

Both work and I have no dog in this fight 😃. Pros and cons both ways

from sdk-javascript.

@grant Can you explain the specifics of the Typescript requirement? Are guaranteed to be correct typescript types are not enough?

The js=>ts renaming doesn't seem to be necessary with the proper tsconfig and the addition of watch/build using tsc and enforced by CI has largely been ceded. Do I appear wrong on these points? Insisting on these two points despite direct statement that they are not the concern is a curious behavior.

You seem to be implying that only JavaScript features would be used. I'm curious how you expect that could be affected. Do you expect contributors from across the internet to forgo using TypeScript features despite project conversion and labeling as typescript? Is there a mechanism you have in mind for enforcing that? Are you willing to agree to it's use?

from sdk-javascript.

@micheleangioni Could you make a PR with this? If you can't, please write an example using some piece of code from sdk.

from sdk-javascript.

I do not have the complete library definitions. I have the definitions of the Spec01, Spec02 and Cloudevent classes.

These are the definitions I wrote:

declare module 'cloudevents-sdk' {
  export type SpecPayload = {
    [key: string]: any,
  };

  export class Spec01 {
    public payload: SpecPayload & {
      cloudEventsVersion: '0.1',
      eventID: string,
    };

    public check(): void;

    public type(type: string): Spec01;
    public getType(): string|undefined;

    public getSpecversion(): string;

    public eventTypeVersion(eventTypeVersion: string): Spec01;
    public getEventTypeVersion(): string|undefined;

    public source(source: string): Spec01;
    public getSource(): string|undefined;

    public id(id: string): Spec01;
    public getId(): string|undefined;

    public schemaurl(schemaurl: string): Spec01;
    public getSchemaurl(): string|undefined;

    public contenttype(contenttype: string): Spec01;
    public getContenttype(): string|undefined;

    public data(data: any): Spec01;
    public getData(): any;

    public time(time: Date): Spec01;
    public getTime(): string|undefined;

    public addExtension(key: string, value: any): Spec01;
  }

  export class Spec02 {
    public payload: SpecPayload & {
      specversion: '0.2',
      id: string,
    };

    public check(): void;

    public type(type: string): Spec02;
    public getType(): string|undefined;

    public getSpecversion(): string;

    public eventTypeVersion(eventTypeVersion: string): Spec02;
    public getEventTypeVersion(): string|undefined;

    public source(source: string): Spec02;
    // public getSource(): string|undefined; // TODO Missing getter, to be added. See https://github.com/cloudevents/sdk-javascript/pull/8

    public id(id: string): Spec02;
    public getId(): string|undefined;

    public time(time: Date): Spec02;
    public getTime(): string|undefined;

    public schemaurl(schemaurl: string): Spec02;
    public getSchemaurl(): string|undefined;

    public contenttype(contenttype: string): Spec02;
    public getContenttype(): string|undefined;

    public data(data: any): Spec02;
    public getData(): any;

    public addExtension(key: string, value: any): Spec02;
  }

  export type Extensions = {
    [key: string]: any,
  };

  export class JSONFormatter01 {
    public format(payload: SpecPayload): SpecPayload;
    public toString(payload: SpecPayload): string;
  }

  export default class Cloudevent {
    public static specs: {
      0.1: Spec01,
      0.2: Spec02,
    };

    public static formats: {
      'json': JSONFormatter01,
      'json0.1': JSONFormatter01,
    };

    public static bindings: {
      'http-structured': any,
      'http-structured0.1': any,
      'http-structured0.2': any,
      'http-binary0.1': any,
      'http-binary0.2': any,
    };

    public constructor(spec?: Spec01|Spec02, formatter?: JSONFormatter01);

    public format(): SpecPayload;
    public toString(): string;

    public type(type: string): Cloudevent;
    public getType(): string|undefined;

    public getSpecversion(): string;

    public source(type: string): Cloudevent;
    public getSource(): string|undefined;

    public id(id: string|number): Cloudevent;
    public getId(): string|undefined;

    public time(type: Date): Cloudevent;
    public getTime(): string|undefined;

    public schemaurl(schemaurl: string): Cloudevent;
    public getSchemaurl(): string|undefined;

    public contenttype(contenttype: string): Cloudevent;
    public getContenttype(): string|undefined;

    public data(data: any): Cloudevent;
    public getData(): any;

    public addExtension(key: string, value: any): Cloudevent;
    public getExtensions(): Extensions;
  }
}

from sdk-javascript.

@micheleangioni Now I understood. Do you want to join us and work in this issue?

from sdk-javascript.

@micheleangioni, would be awesome!

Novice question, how to use the type definition above w/ cloudevents-sdk? I placed the type definition here lib/@types/cloudevents-sdk/index.d.ts, but it's unclear how to create a Cloudevent with a JSON string.

Thanks.

from sdk-javascript.

@cwallsfdc Can you help us in how to publish this typing in NPM?

from sdk-javascript.

LGTM!

@cwallsfdc, go ahead! Perform your PR!

from sdk-javascript.

Answering questions from email:

When the sdk converted to ts, we can use it in pure js projects?

Yes. When we publish to npm, we publish pure js and we have files for TypeScript types for autocompletion.

I am comfortable with this approach, using definitely typed.

We can publish this npm module instead of using DefinitelyTyped. See https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html

Just let me know when master and dev are the same so I can do the conversion without new changes in the middle. It will take a bit of time.

from sdk-javascript.

@grant Thanks for the answers.

Because of the changes that are coming from the spec, I think that is more prudence to publish the types using Definitely Typed. This will help the projects written in TypeScript and we save time to model the stuff for the future of the sdk (writing in ts) and to work in the incoming spec changes.

It's fair if we make voting:

• Vote a if you are in favor of to create just the types and publish to DefinitelyTyped
• Vote b if you are in favor of to migrate the entire codebase from JavaScript to TypeScript

What do you thing about that @grant ?

rigth now, master and develop remains the same

from sdk-javascript.

@micheleangioni
@cwallsfdc

from sdk-javascript.

Thanks for leading this charge @fabiojose.

I agree with @grant. b. TypeScript is natural and well supported.

from sdk-javascript.

b wins!

Vote b if you are in favor of to migrate the entire codebase from JavaScript to TypeScript

@grant Thanks for your contribution! Let's code?

from sdk-javascript.

@grant

Will you code for this issue? Just to know.

from sdk-javascript.

I can't continue since this repo doesn't seem to follow the CNCF standards of having reviews. Need to check on Slack and with others first.

from sdk-javascript.

Nice!

This is a great opportunity. You can become a new commiter and helps us to review. At this moment I am the only one: maintainer and commiter.

Because of that, I guess, you got that impression of loose standards.

Come, join us! Make this better!

from sdk-javascript.

this repo doesn't seem to follow the CNCF standards of having reviews

@grant can you elaborate? As @fabiojose mentioned, we do try to follow "normal" review processes (see the golang repo, it has more people involved) but if there's only one person active in the repo then it's hard to require multiple people for reviews :-)

from sdk-javascript.

In order for me to contribute, I need master to not change as fast as it is. The commits made to master are not PRs, they are direct to master.

I would like to convert this repo to typescript, so that I can use the SDK with Cloud Functions, but last time I tried, there were commits to master that conflicted with my conversion.

All commits in this repo should be tied to a PR and all PRs are squashed so we can see the history change.

Aside, I don't really understand why we should have exceptions for reviews with certain import repos.

@grant, in the early days I used gitflow to merge to master, without PRs. Never commit directly.

Now we are using PRs, but I must approve by myself. You can help us in the review of that PRs.

Is that makes senses to you?

from sdk-javascript.

Now we are using PRs, but I must approve by myself. You can help us in the review of that PRs.
Is that makes senses to you?

Makes sense. I can look into converting this package again. It needs a lot of major changes though.

from sdk-javascript.

Folks, it's not the best, but now we have types for version 1.0.0

from sdk-javascript.

Nice!

This is a great opportunity. You can become a new commiter and helps us to review. At this moment I am the only one: maintainer and commiter.

Because of that, I guess, you got that impression of loose standards.

Come, join us! Make this better!

Hi @fabiojose,
Do you mind making me a collaborator to this repo? I have an expertise in JavaScript/TypeScript and would really like to make this project better.

At Google, we don't use this CloudEvent SDK (even though we use CloudEvents with Node) because of some of the issues described above. I would like to improve this situation but I need to be able to contribute to this repo and use best practices.

To restart trying with this repo, I've created a simple PR:
#63

After that, I would love to help with doing things like simplifying the multiple versions we have in this repo and conversion to modern TypeScript.

from sdk-javascript.

For me, it's ok.

Please, file an issue requesting to be a collaborator and I will ask someone to add you.

from sdk-javascript.

For me, it's ok.

Please, file an issue requesting to be a collaborator and I will ask someone to add you.

Ok, I filed an issue:
#64

from sdk-javascript.

@grant @fabiojose I would like to request that this repository NOT be converted to TypeScript. It is a mistake, in my opinion to assume that JavaScript and TypeScript are interchangeable.

from sdk-javascript.

@grant @fabiojose I would like to request that this repository NOT be converted to TypeScript. It is a mistake, in my opinion to assume that JavaScript and TypeScript are interchangeable.

@lance there is a channel at slack. Join us to discuss this issue. More heads, more thoughts

#cloudeventssdk

from sdk-javascript.

@grant I understand that the library can be used with Node.js if it's TypeScript and I'm fine with adding types to this module. But I personally do not use TypeScript and don't particularly want to completely change my projects to use TypeScript just to parse CloudEvents, whether or not you strongly recommend that I do. I also will stop contributing to this project if it's converted to TypeScript and instead write another Node.js module. Of course, my contributions can be replaced - and there won't be any hard feelings - but over the last month I am by far the most prolific contributor here.

¯_(ツ)_/¯

from sdk-javascript.

@fabiojose I've sent a request to join the Slack

from sdk-javascript.

My TS knowledge still limited to start/continue contributing

from sdk-javascript.

Hi @lance, I think there may be some confusion, which is completely understandable.

You don't need to change any of your projects to use TypeScript. We don't expect anybody to do that. I assume many projects will just use vanilla Node now and in the future.

I understand as a personal (and large) contributor to this project who might not be using TypeScript, it might seem like we are coming from left-field asking for this. I thought the same before I used TypeScript too.

JavaScript is valid TypeScript. It's a strict superset. The first step would be very simple:

• Change .js files to .ts
• Add a watch/build step (npm run build)
• Develop in Node as normal

All contributors can use Node as they have been used to, but need to run the watch command. There may be some cases where we will want to add types or interfaces, but I don't think that will be an issue.

from sdk-javascript.

Hi @grant - just to be clear, I have used TypeScript and understand that it's valid JavaScript.

However

• Change .js files to .ts
• Add a watch/build step (npm run build)

This is exactly what I object to. That and the verbose non-intuitive syntax of TypeScript. And the added code size.

With good linting, proper use of class, private fields, and complete test coverage (all things any modern JavaScript project should have) the benefits of TypeScript just don't seem very persuasive to me.

Respectfully, I understand that you may like TypeScript more than vanilla JavaScript. But I don't accept that it's a de facto improvement and I have not seen any real justification for completely rewriting this module. I will be right there with you in saying that the module needs improvement. But this is not the path I want to take in order to do that.

from sdk-javascript.

Just wanted to add... I realize that in some circles this is not a popular opinion. I don't mean to be abrasive about it. I'm just a purist and do not believe TypeScript is by default an improvement.

from sdk-javascript.

Can you be more specific as to what you object? I said we don't have to use any special TS syntax to start. The code size would not be different, there is no impact on user-executed code. Do you not want to have a different file extension? Do you not want to run the watch command?

If I told you that Google, Microsoft, Lyft, Slack, Asana, and others use TypeScript because of clear benefits with tooling, testability, refactorability, navigation, would that make a difference?

In the above comment, we're threatening to stop contributing to this project and saying that we're the most prolific contributor here. That isn't what the CloudEvent format and CNCF community is about. We're creating an open-source community tool.

Are there specific incompatibilities at Red Hat that this would cause? Is it just personal opinion? If a majority of folks wanted TS support, would you allow it?

from sdk-javascript.

Let's be clear - I can't allow or disallow anything. I'm just a community contributor who has become invested in this project. I don't have write permission on this repository or any level of contributor status other than as a community member. I haven't even submitted an issue asking to be added as a collaborator.

I apologize for my apparent self-aggrandizement as the most prolific contributor in the last month. It had seemed to me that the project was not being very well maintained, so I jumped in and started contributing code. And while my contributions have been slow to land, I feel invested in the project and would like to make it successful. I too would like to create a widely used and high quality open source community tool. I'm not unfamiliar with the paradigm.

It was not meant as a threat that I would stop contributing. It's just the way it is. I don't have to use this module. I would like to, but if it changes to TypeScript I will likely move away from it. I'm sorry if it came across as threatening.

I know that lots of big companies use TypeScript. Lots of big companies use COBOL. This argument doesn't persuade me.

Regarding Red Hat... I'm not speaking for the company, though I am using this module in support of our objectives. I know that among the peers in my immediate circle at Red Hat, most prefer not to use TypeScript. I don't know what you mean by "a majority of folks". It's not clear that many people are using this module. So if there are 4 people in favor of TypeScript and myself against it, I guess I'm out numbered.

Now, just in case I misunderstand what you are saying, I should be clear. I have no objection to declaring and publishing types such as this: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/opossum/index.d.ts#L5. What I object to is writing my code like this: https://github.com/GoogleCloudPlatform/functions-framework-nodejs/blob/master/src/invoker.ts.

from sdk-javascript.

OK, thanks for the response. And thanks for your contributions.

I hope we don't have unreadable code. I hope we have a more usable module with active developers like yourself that can improve the CloudEvent ecosystem.

There are a few logistics/issues we need to solve before adding TypeScript type support anyhow. I'm curious as to how you're using this module currently, and perhaps how it could be improved. I'll be keeping the usage of this module in https://github.com/boson-project/faas-js-runtime in mind.

from sdk-javascript.

@grant good deal. I don’t want unreadable code either. I want this to be high quality idiomatic JavaScript and of course, with Typescript type support. :) IMO one good improvement might be this: #65

from sdk-javascript.

@lance I've been only recently picking up typescript so please excuse my ignorance. Is there an automated process in opossum (or an example elsewhere) that validates that as changes occur that the type declarations do not drift or more pointedly that the typescript consumers aren't caught out?

from sdk-javascript.

@lance I've been only recently picking up typescript so please excuse my ignorance. Is there an automated process in opossum (or an example elsewhere) that validates that as changes occur that the type declarations do not drift or more pointedly that the typescript consumers aren't caught out?

The problem with separate type declarations is that they are not updated with the source code.

This is what was done in the repo before, but they were not updated with the source. Thus, the types were inaccurate and unusable. See #9 (comment)

As this repo changes too much, the only option would be to use TypeScript to generate types.

from sdk-javascript.

Thanks @grant I hear that concern. If the automated validation means I am asking about was in place, I wouldn't expect type drift to have occurred.

from sdk-javascript.

@grant there is not anything automated for opossum type generation. I agree this is not ideal. The types for that module are mostly maintained by external contributors who have an interest in using TS.

I just skimmed this article, but it looks promising. https://dev.to/open-wc/generating-typescript-definition-files-from-javascript-5bp2

They are auto generating types from JavaScript functions which contain valid jsdoc (which we of course need anyway).

from sdk-javascript.

FWIW - I would like ultimately for the user-facing API to be a little more stable and expose far less. Ideally, we have this:

const { CloudEvent, HTTPReceiver, HTTPEmitter } = require('cloudevents-sdk');

There's not much more that a developer needs to be concerned with IMO. All of the parsers and unmarshallers and all of that are internal to the module and don't need to be exposed. Keeping the API footprint small and clean should also help quite a bit.

from sdk-javascript.

Hi @lance - pretty sure it was me that asked about automation ;D Would you be willing to add the automation for validating that drift doesn't happen? It appears that the relevant PR called out by that article has landed (it targeted 3.7 but 3.8 is out and 3.9 is RC). Is it working? If so is this really going to provide the same level of type validation or does it move responsibility off of the compiler to the maintainers and reviewers?

@grant it's not clear to me that js-docs are less arduous than typescript but if this solution generated the necessary *.d.ts files and validation of type declaration and safety were part of an automated CI process run against all PRs in this repo, would it satisfy your needs if not preferences?

from sdk-javascript.

Unfortunately JSDoc comments don't satisfy deep accurate autocompletion or other benefits of TypeScript such as optional static typing. Besides, code comments aren't enforced or always complete/accurate. Generating .d.ts files doesn't sound great even if it could be done.

Converting to ES6 gets some autocompletion, but not as thorough or deep as TypeScript. The IDE experience is awesome. We could dramatically reduce tests while ensuring increased safety. Example in TS:

Again, we don't need to change anything besides renaming .js files to .ts to get this benefit.

from sdk-javascript.

@erikerikson sorry for the misattribution! :)
@grant JSDoc can be enforced with eslint. We already have a very basic linting rule that enforces valid JSDoc if JSDoc exists. This can be changed to require JSDoc. I think we'd want to clarify exactly what API should be exposed and only enforce it on those files. But I think it might not be as difficult as you imagine to enforce this if we keep the surface area of the API much smaller than it is today.

from sdk-javascript.

@lance Yes, JSDoc can be enforced, and we can write the params twice, once in docs and once in code. Some completion will work but not all, and there aren't great linters. We could add tooling and use/write/maintain custom IDE plug-ins.

With JS, we can't rename variables, have deep autocompletion or autocompletion of objects, or move functions between files. If anyone has a solution using pure JS rather than TS, I'm all ears!

JS is OK for small projects, but CloudEvents and Node are used by large projects.

Additionally, types are super important for this project as the CloudEvent spec is very specific and has multiple versions.

The TypeScript's and Code's Twitter has loads of benefits and gifs of IDE support if anyone isn't convinced:
https://twitter.com/typescript
https://twitter.com/code

If you use VS Code, you're using an editor built on TypeScript. VS Code does it's best with plain JS autocompletion, but it's not as great.

Anyways, we can't convince everyone to use TS. Big Javascript users like Google, Microsoft, Netflix have used it for 3+ years at least and given many supportive talks. Small companies love it as well. There are hundreds of supporting blogposts too. It's one of the world's most loved programming languages. This GitHub issue is the largest issue in the repo and it directly asks for TypeScript support – so I'm not sure why we don't just do it.

As Lance mentioned on Slack, code talks. See #137. I don't think it'll interrupt anyone's dev flow too much and could be merged.

If we can't make progress on that PR, it's best to just create a new project at this point, where we can solve other issues such as idiomatic non-Java-like builders for CloudEvent objects. This can be done after the CNCF call next week.

from sdk-javascript.

@cwallsfdc

Typescript, because of its inherent typing, is:

more maintainable,

Do you have empirical data showing this? And by whom? I mean, I'm pretty good at maintaining JS projects - a personal project of mine gets about 34k downloads a week from NPM, has a very low bug count, several active maintainers, etc... Your statement is subjective.

reduces bugs (estimation that typing results in a 15% decrease of bugs),

Again, let's see some empirical data. I'm not convinced. Here's a good article covering that issue (and many others with TS vs. JS).

Type safety doesn’t seem to make a big difference. TypeScript proponents frequently talk about the benefits of type safety, but there is little evidence that type safety makes much difference (really, static types seem to have very little impact) to production bug density. This is important because code review and TDD make a very big difference (40% — 80% for TDD alone). Pair TDD with design review, spec review, and code review, and you’re looking at 90%+ reductions in bug density. Many of those processes (particularly TDD) are capable of catching all of the same class of bugs that TypeScript catches, as well as many bugs that TypeScript will never be able to catch.

better for collaboration,

According to whom? Everyone that I work with who is currently contributing to this repository would probably disagree. None of them are TS developers. Again, this is highly subjective.

better for 3pp use.

I'll say this is highly subjective - again. There is some benefit in developer tooling, but it's not huge. Also from the article linked above.

The development tool choice isn’t TypeScript vs native JavaScript and no tooling. It’s between TypeScript and the entire rich ecosystem of JavaScript developer tools. Native JavaScript autocomplete and error detection gets you 80% — 90% of the benefits of TypeScript when you use autocomplete, type inference, and lint tooling. When you’re running type inference, and you use ES6 default parameters, you get type hints just like you would with type-annotated TypeScript code.

Typescript with generated type declarations, please.

We are working on a solution with @grant's PR. #137

But you need to understand that TypeScript is not JavaScript, and asking the maintainers to completely change the repository to be written fully in TS is just too much to ask, in my opinion. That is, unless there are a lot of contributors who know and love to write TS. At this point, there is one. All of the rest are pure JavaScript developers. So, I encourage you to become more actively involved in code contributions if you feel so strongly about it.

from sdk-javascript.

@lance regarding

Everyone that I work with who is currently contributing to this repository would probably disagree.

and

asking the maintainers to completely change the repository to be written fully in TS is just too much to ask

I am not a maintainer here so I am not attempting to assert a preference but I have been a part of CloudEvents for sometime and have written a fair bit of JavaScript over recent years. In response to these particular comments of yours I'd like to call out that there was a vote in this issue and the outcome seems to support switching. All stakeholders may not have participated. However, if we weighted by commits, fabiojose's would be the only vote that matters and they seem to be in support.

I appreciate that the language switch strongly contradicts your preference and I can empathize with the pain of having a project you are invested in changed in ways that you dislike (I have left positions and taken breaks from the industry over this sort of thing). However, I bring up the vote and relative investments because asserting that it is too much to ask for a language expansion (the superset thing) from the maintainers seems strongly contradicted by the fact that the most prolific maintainer brought up the vote and so far along with other committers appears to support the change.

I wouldn't care or spend my attention on this conflict except that this is an official repository of CloudEvents and owned by the CNCF. I am concerned that this conflict over personal preferences could likely lead to a confusing experience and unnecessary decisions for engineers who don't understand the implication of choices they didn't or shouldn't have to think about. The costs and impacts of this project are those that will happen at scale across the industry.

It seems important that the group here can make this decision in a decisive but fair manner. A vote from maintainers seems a reasonable approach and it was attempted. So far yours is the single dissenting voice that I've read. Perhaps other maintainers of the project you know would like to speak up against typescript? Maybe you have alternative mechanisms to making the decision that you would like to suggest?

from sdk-javascript.

@erikerikson

I'd like to call out that there was a vote in this issue and the outcome seems to support switching

This vote occurred 9 months ago, prior to the release of 1.0, and garnered a total of 6 votes. Surely that can't be interpreted as a fair representation.

Fabio was quite active in the repository then, and I agree, at that time his was the only vote that matters. Today, however, he is not very active. Michele was a committer at the time but also has not been active in months. It does not appear to me that any of the remaining three voters have contributed at all, but I could be mistaken. In any case, if it was considered so important, I would assume that someone would have actually contributed code over the last nine months to make that happen. That was not the case.

Help me understand how switching to TypeScript is a benefit to the consumer of this SDK. As I see it, the benefits are mostly aimed at repository maintainers who are writing the code. For the end user, the main benefit is type checking in their IDE, which can be achieved through JSDoc and type definitions. In an effort to make a compromise, I have suggested these as alternatives and they were rejected. I don't think I'm being unreasonable. Frankly, I think Grant is.

Regarding personal preference, I guess I summed up my position pretty well on Slack.

I just don't know what else to say. It's true, I will not maintain a repository in a language that I don't use. TBQH, I haven't seen a single contribution to the repository from anyone pushing for TypeScript by anyone except yourself [Grant]. If there were a lot of contributors doing so, it might be different. But that's not the case. I have been fixing bugs, improving the API, updating documentation and preparing a release and honestly, this conversation is quite tedious.
I have tried to find common ground - generated type definitions, your existing PR. I don't think I'm being unreasonable.
I am not working on this just for fun. It's part of my job at Red Hat, and we will be using this repository as a part of a product we are developing to sell to our customers. I and the others in my group who are currently contributing to the repository are pure JS developers. If it's converted to TypeScript we cannot continue to contribute to it because we cannot support it for our customers.
I believe in community. I just don't believe in a handful of people coming in and completely changing an existing project because that's just what they feel like doing. Please, continue to contribute to the project. As it evolves, it might steer in your direction. But days on end of discussion around a complete overhaul is a waste of time.

If you want to call another vote - by current contributors - that's fine with me. I'm not convinced that a nine month old poll with 6 voters, half of whom have not contributed code, is reasonable.

from sdk-javascript.

Thank you for pointing out the timestamp on the vote. Thank you also for sharing a richer picture of the contribution history than I can get on the repo listing.

My concern is the splitting of the repository as was agreed on the weekly call. Having two official JavaScript SDKs, one written in vanilla JavaScript and the other in TypeScript would result in two npm packages and two sets of documentation. Contradictory questions and answers about the official CloudEvents JavaScript would be likely on stackoverflow and the like. I imagine that we can all predict some of the funny (and not so) ways that could play out. Unfortunately, I think this perhaps raises the stakes here. I apologize for adding complexity to the discussion.

So long as the concerns of both communities are satisfied in a dependable manner, I don't feel I get an assertion on the matter despite a prediction that it may well impact me latter.

To be frank myself, I would agree that there has been little steelmanning in this discussion and that beliefs have been written from an assumption of their universal acceptance as truth. In the end, this is making the whole discussion harder and less efficient for everyone.

from sdk-javascript.

Looking into CloudEvents system as a newbie the first thing I looked at was this sdk-javascript repository, and my first impression was this is a bummer it is not typescript as it would bring a clean type.

I have no rights or voice as I did not contribute to this repo at all, so just adding my 2 cents. As @grant said, moving to Typescript is not a revolution and could probably benefit everyone. If some help are needed I might be able to help a bit.

Reading @erikerikson last comment, splitting repo seems like a bad idea to me.

from sdk-javascript.

@erikerikson Thanks for considering my point of view. I too want to avoid splintering this community. Code talks, in my opinion, and if people really want to make change, they are empowered to do so through the wonder of FOSS. This repository is open to pull requests, and I don't think something reasonable will just be dismissed out of hand. Small steps towards stated end goals makes sense and is good. But I don't want that end goal to be "let's change it to TypeScript". It should rather be, "let's make this repository great for end users like @loopingz by ensuring they have type support in commonly used IDE and development tools". Those goals may seem the same, but they are not. There are many ways to get to the second without requiring the first.

I want this repository to be a high quality example of FOSS. I want it to be well tested, documented, easy to use, accessible, work well with modern tooling, and make it so that TypeScript users like @loopingz feel good about it. All of that. I just don't think that simply converting to TypeScript gets us that. There's more than one way to shave a yak.

Rather than focus on changing the technology right now, I'd much rather focus on improving the code as it is today and evolve it over time to meet everyone's needs.

from sdk-javascript.

This vote occurred 9 months ago, prior to the release of 1.0, and garnered a total of 6 votes. Surely that can't be interpreted as a fair representation.

This is directly attacking the validity of a popular vote and is adding recency bias. CE 1.0 just came out recently and more vendors are joining CloudEvents. Saying there hasn't been that many contributors in the last few months should weight no meaning. We are building this SDK for end-users, not contributors.

Moreover, by commenting that another vote is fine by you, you're not suggesting an actual solution, just creating churn. Would you fully accept a popular vote? What would it take?

I'm pretty sure trying to use TypeScript will get rid of a lot of need for discussion. Can you please just try it? Please?

Your RedHat customers using @redhat/faas-js-runtime will be able to have autocompletion when creating/consuming CloudEvent objects, even if they use vanilla JavaScript. Missing CloudEvent object properties will linted with links to the source code. It will really benefit you and RedHat.

The alternatives mentioned aren't great:

• JSDoc: Documentation gets old fast and is not 100% accurate. You can't rename variables for example.
• Type Definitions: Please tell me about the type definitions and validation tool that you mention will solve this problem. Suggest in PRs to compromise. TypeScript is just one solution for type definitions that is popular.
  • I don't recall your generated type definitions as you mention.

All in all,
Lance, I recommend reading this if you have 5 minutes:

https://www.typescriptlang.org/v2/docs/handbook/typescript-in-5-minutes.html

We need everyone to be on board with adopting TypeScript to achieve the maximum benefit. It will positively impact thousands of developers in creating a great developer experience for Node developers consuming CloudEvents.

from sdk-javascript.

I'm pretty sure trying to use TypeScript will get rid of a lot of need for discussion. Can you please just try it? Please?

@loopingz Wow! Thanks for doing this - I really do appreciate it. As @grant mentioned earlier, quoting me on Slack, code talks. I much prefer this approach over all of this discussion. I will try and pull your commit this weekend (or Monday at the latest) to play with it. And if you want to submit a pull request, that's totally fine.

As an aside, there are currently a few in-flight PRs that really should land in the next week. If you do submit a PR, there will be a few conflicts once these are on master. We're releasing 2.0.0 soon with some bug fixes and API improvements.

from sdk-javascript.

Yes, I can do PR next week, with a bit more time, was supposed to be offgrid for a few days :)

I think I've seen there were weekly calls, if it is open to public, I'll try to join. As in-person conversations are usually always easier.

No worries about adapting other PRs, please be aware this is a first pass, we should then add more type specifications etc. What is good with those switch JS to TS is that you can do it gradually to improve the overall project step-by-step.

Will join the slack as well

from sdk-javascript.

@loopingz yes feel free to join the calls and slack. I haven't applied your commit yet, but read through the code changes and have some comments/questions on your fork. We can discuss there or in Slack.

from sdk-javascript.

For what its worth, It's possible to use JSdocs to generate full typescript types into [whatever].d.ts files

This means you can use vanilla JS, annotate with JS docs and typescript users get all the IDE autocompletion goodies. Everyone wins!? 😃

For an example of this see my analytics project. Using Jsdocs the build step reads them & generates typescript definition files. Additionally, the doc blocks are used to generate 99% of the docs site.

from sdk-javascript.

@DavidWells I discovered this recently, and commented on it above in the thread. How has it been using this?

I just skimmed this article, but it looks promising. https://dev.to/open-wc/generating-typescript-definition-files-from-javascript-5bp2 They are auto generating types from JavaScript functions which contain valid jsdoc (which we of course need anyway).

from sdk-javascript.

@lance the setup works great IMO. example

Basically, I get type checking in VSCode via JSdocs when working on the project and consumers of the project get IDE autocompletion. (From what I can tell the main benefits of using typescript).

Additionally, I get to use (IMO) more human-readable docs with inline doc blocks with usage examples etc. The doc blocks are used to automatically generate docs & keep them in sync. For example, this docblock generates the docs in github and on the site

from sdk-javascript.

@DavidWells that's great. I'm familiar with the benefits of JSDoc and whatever route we take, I think we need to address that in this repo. I guess what I'm curious about is whether this solution fully addresses the concerns voiced in this thread and how different/similar it would be from a maintainer's perspective as compared to what @loopingz has shown.

from sdk-javascript.

Using jsdoc to generate typescript types sounds a good idea but on the long run i would expect code to be updated with forgotten jsdoc block etc. That is why typescript came to life and why it is spreading that much.

from sdk-javascript.

I finally found time to read this whole thread! oy vey! :-)

To make sure I understand things since (as I've said) I don't know TS at all and don't do anything with JS outside of a browser, early on in the thread it seemed like there were two concerns from @lance w.r.t. the proposed direction:
1 - it would require users of the SDK to rename their files form *.js to *.ts
2 - it would require users of the SDK to add a watch/build step

And, as I understand it, TS is a compiled language in the sense that it needs to be converted from TS to JS before it is executed (interpreted) at runtime.

Sound ok so far?

If so, I have just a couple of questions:

• since TS is a superset of JS, would it make sense (or be possible) to have a JS SDK be leveraged by a TS user in a way that makes sense to them? Or would they expect things to be there (like static typing) that the JS SDK would not have?
• Assuming a JS SDK wouldn't be a good fit for a TS user, would the TS SDK need (or want) to leverage the JS SDK code at all? Meaning, would it ever make sense for the TS SDK to be a layer on top of the JS SDK or is that just an extra layer without a purpose and the TS SDK would be better written to be a native CE processor?
• If a layering approach makes no sense, which implies to me that there's basically no code sharing, would there be any benefit to both code bases being in the same repo? The only thing that comes to mind is a shared conceptual model/design but we (sort of) try to do that today across the various SDK already.

I'm guessing the answer to all 3 bullets is basically "no" which is why we landed on the "new SDK" decision. But I wanted to make sure I'm up to speed.

How far off am I? :-)

from sdk-javascript.

I finally found time to read this whole thread! oy vey! :-)

Thanks for taking the time - and on a Friday night, even. 😄

it seemed like there were two concerns from @lance w.r.t. the proposed direction:
1 - it would require users of the SDK to rename their files form *.js to *.ts
2 - it would require users of the SDK to add a watch/build step

Not really - those were concerns that were attributed to me by others. Really what I care about is maintainer productivity and the larger pool of potential contributors (and alienating existing contributors who have only recently started to submit code (including myself)).

And, as I understand it, TS is a compiled language in the sense that it needs to be converted from TS to JS before it is executed (interpreted) at runtime.

Correct.

since TS is a superset of JS, would it make sense (or be possible) to have a JS SDK be leveraged by a TS user in a way that makes sense to them?

Yes - see David's comment above. Personally, I think this is the best path forward for a possible migration to TypeScript in the future. This is the compromise I have recently suggested. I honestly do not want this community fractured and I'm trying to be open about this. My preference is pure JS. Clearly, that feeling is not universal. ☯️. I personally would be most comfortable with a graduated approach using the methods suggested by David.

Concerns about doc comments drifting from implementation are valid, but there are ways to deal with this using tools and processes.

from sdk-javascript.

I have limited TS knowledge and I have no room for TS learning in my free time to be able to be comfortable in contributing.

from sdk-javascript.

1 - it would require users of the SDK to rename their files form *.js to *.ts
2 - it would require users of the SDK to add a watch/build step
Sound ok so far?

Yes. Those are the two main points, .ts files and running watch/build. Adding tools/processes on top of this is fine. I think another fear of developers is that TS has a steep learning curve (it does not, there is literally no difference if you only use JS features).

TypeScript is required for many projects including those at Google and Microsoft.

The best path forward is a separate implementation with TypeScript. If there is value in merging projects at a later point, that sounds fine.

from sdk-javascript.

@grant Can you explain the specifics of the Typescript requirement? Are guaranteed to be correct typescript types are not enough?

Sure. As a developer:

• I must know the exact properties of a CloudEvent before execution.
• I must never see "undefined" is not a function or equivalent for SDK users.
• I must have autocompletion in my developer tooling/IDE for CloudEvents.
• I must be able to click to definition to see the source code of the SDK.
• I must see linting errors in my code if I use the CloudEvent SDK incorrectly (i.e. invalid type).

There are a few projects that could use an SDK for CloudEvents in Node.

Here is an example project that could use the SDK with TypeScript:

Example at Google

https://www.npmjs.com/package/@google-cloud/functions-framework

It powers serverless functions for Google Cloud. We don't use this module to accept/parse HTTP requests with CloudEvents due to a few issues, one being lack of TS support.

We require autocompletion and static checks to ensure that the module is running correctly. It's vital for ensuring we don't crash our product for thousands of customers on a bad deploy. Many other companies use this superset language.

It's Literally Node

It's literally no different, please browse the code of the TypeScript version:
https://github.com/loopingz/sdk-javascript
This is the literal code change that we're talking about...

It's Incremental

You don't need to learn a new language. We can enforce not using non-JS features.

It's an industry-wide standard that you're probably using right now

If someone was to magically enforce types and IDE integration with types that are not from TypeScript, that's fine. That's really the point of TypeScript though. There is a whole ecosystem and company support around TypeScript.

Example players supporting TS: https://tsconf.io/

I can't find any project that does anything similar.

I assume many people use VS Code for code editing right? That heavily uses TypeScript.

Other Questions

The js=>ts renaming doesn't seem to be necessary with the proper tsconfig and the addition of watch/build using tsc and enforced by CI has largely been ceded. Do I appear wrong on these points? Insisting on these two points despite direct statement that they are not the concern is a curious behavior.

Editors like VS Code will do it's best with just js files or just a tsconfig. You're really using TypeScript under-the-hood. At that point, you're really just avoiding the filename rename for some reason. 🤷

You seem to be implying that only JavaScript features would be used. I'm curious how you expect that could be affected. Do you expect contributors from across the internet to forgo using TypeScript features despite project conversion and labeling as typescript? Is there a mechanism you have in mind for enforcing that? Are you willing to agree to it's use?

I am saying that the main issue we're facing is the fear of change. We don't have to change any of the JavaScript if we don't want to to use TypeScript. There aren't that many contributors to this project for us to know to not accept PRs with extra TS features. We don't even consistently use ES6. I'm willing to agree on not using TypeScript features and we can add a simple lint file to enforce this via tslint.

from sdk-javascript.

Finally, caught up with all of this thread and the slack discussion. :-) As I brought up the concern in last week's call and now will say more strongly... I'm against having two separate, "official" "Javascript" sdks. That's just plain bad optics and makes for confusion, bugs, interop, support, etc. issues for users/consumers/providers of CE.

from sdk-javascript.

If I understand the camps' positions, @loopingz's code translation and some simple policies such as the tslint enforcement seem like a fair place to start so that we can remain as single JS SDK for CE. As someone who has no personal stake in the pure-JS vs. TS approach, I personally hope that people in the various camps are willing to at least try a joint approach openly before splitting into two separate, competing efforts.

from sdk-javascript.

As I brought up the concern in last week's call and now will say more strongly... I'm against having two separate, "official" "Javascript" sdks.

Hi @johnm, thanks for your opinion, but there are a couple issues. I literally cannot use this project unless it fully supports TypeScript. I oppose two separate JS-like repos too on the surface. I'm happy to merge separate repos if possible.

What do you expect me to do? This is a deal-blocker.

We currently have separate efforts, literal code duplication already, since there is no TypeScript support.

I'm obviously not as happy to continue a separate effort outside of a this repo or outside of this GitHub org.

from sdk-javascript.

@grant

I am saying that the main issue we're facing is the fear of change.

Two concerns I have heard are exclusion (or even just reduced welcome) and a potentially reduced contributor pool and thereby speed of improvement and community inclusion.

I understand that typescript is a superset and have indicated personal comfort with it (by admitting use). To be transparent I would welcome a full transition an use of typescript constructs personally but my personal mores are unimportant in this case. Depending on how we introduce typescript (if we do at all) we could create externalities. This includes factors such as a subset of the population seeing unexpected constructs and be put off regardless of what size the learning curve might be.

Thank you for sharing the ability of tslint to enforce sticking to core JavaScript. I'm curious if using that sufficient compromise for those who would like to stick with vanilla JavaScript (@lance or anyone else?). I'm also a bit mystified by the assertion that the technical/concrete requirements would care at all about a file name. If we look at loopingz's repo there are a couple further changes in it but they also seem pretty reasonably limited.

What do you expect me to do? This is a deal-blocker.

It turns out that (as a stand in for an important subset of users) your needs matter too. What we are talking through are the deal-making constraints and options. I apologize that my ignorance is forcing me to ask you to explain options and a bit of how our potential choices interact and what the choices available to us are. I can imagine it is a little frustrating but I can only be where I am, please apply patience as you can.

from sdk-javascript.

As I brought up the concern in last week's call and now will say more strongly... I'm against having two separate, "official" "Javascript" sdks.

Hi @johnm, thanks for your opinion, but there are a couple issues. I literally cannot use this project unless it fully supports TypeScript. I oppose two separate JS-like repos too on the surface. I'm happy to merge separate repos if possible.

What do you expect me to do? This is a deal-blocker.

We currently have separate efforts, literal code duplication already, since there is no TypeScript support.

I'm obviously not as happy to continue a separate effort outside of a this repo or outside of this GitHub org.

Hm... Did you respond before reading my second comment? I hope that made clear, as I also commented in the call, was that it seems that there's a combined approach place to come together other. Based on that, are there still deal breakers?

from sdk-javascript.

Well, thanks for all the replies and trying to figure this out @erikerikson.

Sorry @johnm, I was reacting a bit. This issue has been open for over a year with hundreds of commits to this project directly to master and no progress on issues like this one despite PRs, forks, Slack discussions, calls, etc. The comment of immediately positioning against making progress on this issue via separate repos was surprising and did not suggest a way forward.

from sdk-javascript.

38% of bugs at Airbnb could have been prevented by TypeScript according to postmortem analysis

To type or not to type: quantifying detectable bugs in JavaScript

from sdk-javascript.

Sorry @johnm, I was reacting a bit. This issue has been open for over a year with hundreds of commits to this project directly to master and no progress on issues like this one despite PRs, forks, Slack discussions, calls, etc. The comment of immediately positioning against making progress on this issue via separate repos was surprising and did not suggest a way forward.

No worries, I understand the frustration as I've been in similar situations previously.

FWIW, I separated the two different aspects on purpose. There are the problems at technology level but also at the project level (of the impact on the users/etc). I think the context of the project should be keep in mind when dealing with the tradeoffs in making the technology decisions.

from sdk-javascript.

38% of bugs at Airbnb could have been prevented by TypeScript according to postmortem analysis

To type or not to type: quantifying detectable bugs in JavaScript

May I come in and talk with you about our strongly typed savior, Rust & Wasm? ;-) :-)

from sdk-javascript.

• I must know the exact properties of a CloudEvent before execution.
• I must never see "undefined" is not a function or equivalent for SDK users.
• I must have autocompletion in my developer tooling/IDE for CloudEvents.
• I must be able to click to definition to see the source code of the SDK.
• I must see linting errors in my code if I use the CloudEvent SDK incorrectly (i.e. invalid type).

I was under the belief that using tsc and JSDoc would ensure that all of this is possible. Is that not the case?

Editors like VS Code will do it's best with just js files or just a tsconfig. You're really using TypeScript under-the-hood. At that point, you're really just avoiding the filename rename for some reason.

If type checking is enabled with tsc and there is a valid tsconfig, then VSCode should be satisfied, I think. I've recently been experimenting with this on my fork, and have found that it's quite effective.

I am saying that the main issue we're facing is the fear of change.

I might say reluctance to change. There are existing contributors (including myself) who are reluctant to switch fully to TS for a number of reasons. But I don't know that you are representing them in good faith. A reduced contributor pool and alienation of existing contributors are what I care most about. I really don't like the required transpilation stage in order to actually have a JavaScript engine be capable of reading my code, but I can live with that, I suppose. I do like the fact that tslint can enforce pure JS. But I wonder, what's the point of actually converting to TS in that case if we can achieve the user-facing goals (knowing the properties of a CE, autocompletion, linting, etc) with tsc, JSDoc and other tooling?

As @johnm has suggested, I would like to consider a path forward that starts small, using tsc to check the code, jsdoc to enable both IDE autocomplete and help tsc, and type declaration generation. Do this with an eye towards eventually moving to TS when this whole thing has simmered down a bit. I understand that there are potential benefits to TS. But there are reasons to take it slowly. I would like to think that this is a fair compromise.

To be quite honest, I would be surprised if Google immediately started using this project if we did nothing but switch to TypeScript by changing file names and adding a watch command. Those first compromising steps seem necessary in any case.

Rather than a switch to TypeScript, my most pressing concerns are:

• Reduce the surface area of the API to be much simpler, e.g. const { CloudEvent, HTTPEmitter, HTTPReceiver } = require('cloudevents-sdk');
• Add JSDoc to the entire public facing API (those classes above)
• Design the API so that it is more consistent with the spec
• Release 2.0.0 soon.

Honestly, I think these add much more value than renaming a bunch of files. I'd like to focus on these before making any major repository-wide changes if possible.

from sdk-javascript.

tsc is just a tool to transpile TypeScript to JavaScript.

One of the big point of TypeScript is to not have to duplicate your code inside of docs. Right now we don't have many comments in the code. The suggestion here is to add JSDoc and annotate types everywhere. That's going to create a lot of boilerplate.

There are 2 options:

1. Add JSDoc everywhere. Keep them up-to-date with refactors.
2. Rename files from .js to .ts and automatically understand types (even without annotations).

The above comment chooses option 1. I'm suggesting 2.

Again, switching to TypeScript is not a big change that will prevent you from having to write all that JSDoc.

To be quite honest, I would be surprised if Google immediately started using this project if we did nothing but switch to TypeScript by changing file names and adding a watch command. Those first compromising steps seem necessary in any case.

I literally work for Google, for Events, and have said multiple times I'd use this module if it was useful and supported TypeScript. See #9 (comment)

from sdk-javascript.

Fixed in: #155

from sdk-javascript.