[DRAFT!!!] QUEST: Let's type the Ember.js ecosystem! about ember-cli-typescript

[mike-north]

I would raise this with the learning team. The code documentation tools they use require some non-trivial finesse to fix this kind of thing.

As far as the types go, because this is a "synthetic" package that's not really in the /packages folder of the ember monorepo, it should be done via a module declaration within the @types/ember__string source.

Also, for there to be any value in having a @ember/template package, developers should actually be importing stuff from it. The individual functions isHtmlSafe and htmlSafe sugest that these functions should be imported from @ember/string anyway.

in the future this may change, but we may want to wait until a beta is cut with the deprecation before leading people in this direction.

At least for the ember 3.x release series, we need to also maintain the existing means of importing htmlSafe and isHTMLSafe

[kratiahuja]

@chriskrycho what's the story on linting with typescript? Will this addon support tslint or does eslint work well right now?

[chriskrycho]

@kratiahuja the short version is: this add-on leaves that to the user entirely, but we will (for the moment) recommend TSLint, because the TS support in ESLint isn't mature enough yet.

[kratiahuja]

@chriskrycho awesome! thanks for the super quick response. Appreciate it!

[dwickern]

It would be nice to document what steps an addon author should take to add typings for their addon.

[chriskrycho]

@dwickern that's a great idea and I'm planning to include it in the writeup. (I'd also like to land #47 first so that authors who are actually writing TS can do that automagically.)

[chriskrycho]

Closing in favor of typed-ember/ember-typings#14, since we're driving Ember type definition development through that respository.

[chriskrycho]

Reopening since we've deprecated typed-ember/ember-typings. I've copied the body of the quest. Important comments from that thread:

@sdhawley (comment):

Has any work been done on ember-simple-auth? I'm getting complaints when building:

app/controllers/application.ts(3,28): error TS2307: Cannot find module 'ember-simple-auth/services/session'.

and (comment):

I've started creating an ember-simple-auth.d.ts locally as I run into things, happy to share it.

@championswimmer (comment):

Regarding ember-moment I think we do not need typedefinitions. Mostly it is hbs helpers. The Javascript API is same as moment itself, which ships with typedefinitions itself.

@denzo (comment):

https://github.com/dockyard/ember-one-way-controls is deprecated

[AvremelM]

Is this doc intended to cover contributing to core typings (e.g., @ember/*)? Is there anywhere else where that would be documented?

[chriskrycho]

No: those types all already exist and are largely complete! (We are of course continuing to tighten them up as we find issues or think of better ways to express things.) They live in the DefinitelyTyped repo.

[AvremelM]

Sorry, I meant contributing to those existing typings. For example, correcting issues like API changes or types that match the Ember API docs, but where those docs are incomplete/incorrect. E.g., @ember/template is not in DefinitelyTyped at all.

Should I even be trying to contribute to those, or just reporting issues and letting the experts handle those?

[chriskrycho]

We’d welcome help! We mostly want to make more experts, not hoard expertise. Please open bugs on this repo (there’s a template for type definition bugs you can choose when you click the Create Issue button!). We’re very happy to mentor people through contributing fixes for them.

[mike-north]

@HodofHod thanks for your desire to jump in and help!

E.g., @ember/template is not in DefinitelyTyped at all.

At the highest level, we want to ensure that the type information tells the truth about Ember's public API. In the case of this package, it's not represented anywhere in the docs, so it should not be in the types.

If you believe that this is part of Ember's public API, the first step would be to correct the documentation. Only then can we use an authorized documentation change as an idication of "this is public", and then add it to types.

If you're not familiar with the best practices for writing and testing declaration files, I have a blog article here that may be helpful https://medium.com/@mikenorth/guide-to-typescript-ambient-declarations-717ef6da6514

[AvremelM]

Hey, I just (already) created #342

You're correct that it doesn't appear in the sidebar, but it actually is listed in the docs for @ember/string, so I'm not sure about editing the API docs.

That makes a lot of sense regarding making sure the types match the docs, I'm just not sure about this case

[AvremelM]

That makes sense. I'd just add that based on this I'd say that @ember/template is already the "correct" location to import from, though of course @ember/string should continue to work. (Edit: interestingly, it seems that at the time, importing from @ember/template wasn't working at all, though it definitely works for me on 3.3)

The ember-modules-codemod is already making this change for people, which is how I stumbled on this.

[Panman82]

Been a while, any movement here? Maybe there is another direction that I'm not aware of.?. Thanks!

[chriskrycho]

No, and we should probably rethink this whole approach. I am closing (and unpinning) this issue and folks should feel free to approach types organically. Typed Ember folks are of course happy to provide guidance and recommendations, though!