Missing Types for (undocumented) setComponentTemplate API

[NullVoxPopuli]

trafficstars

Edit by @chriskrycho 2022/02/10: original title was "Missing Types for new APIs". Updated to reflect current state.

---

Which package(s) does this problem pertain to?

• [ ] @types/ember
• [ ] @types/ember__string
• [ ] @types/ember__polyfills
• [x] @types/ember__object
• [ ] @types/ember__utils
• [ ] @types/ember__array
• [ ] @types/ember__engine
• [ ] @types/ember__debug
• [ ] @types/ember__runloop
• [ ] @types/ember__error
• [ ] @types/ember__controller
• [x] @types/ember__component
• [ ] @types/ember__routing
• [ ] @types/ember__application
• [ ] @types/ember__test
• [ ] @types/ember__test-helpers
• [ ] @types/ember__service
• [ ] @types/ember-data
• [ ] @types/rsvp
• [x] Other
• [ ] I don't know

What are instructions we can follow to reproduce the issue?

Try to use any of:

• import { dependentKeyCompat } from '@ember/object/compat';
  • docs
• import { setComponentTemplate } from '@ember/component';
  • rfc
  • code
• all of ember-cli-htmlbars (but only hbs used)
  • see issue

Reproduction Case

If you can, please try to fork this codesandbox, and give us an example that demonstrates the problem. Paste the link below so that we can see what's going on

• Clone: https://github.com/NullVoxPopuli/emberclear/
• Checkout: resolve-sidebar-performance-issues
• cd packages/frontend/
• Delete:
  • types/@ember/
  • types/ember-cli-htmlbars
• in types/index.d.ts
  • Delete:

    declare module '@ember/component' {
     // TODO:  remove when this is actually a thing that exists?
     export function setComponentTemplate(template: string, klass: any): any;
    }
    

• Run yarn lint:types
  • notice type errors raised about
    • hbs from ember-cli-htmlbars
    • setComponentTemplate from @ember/component
    • dependentKeyCompat from @ember/object/compat

tests/integration/routing/feature-flags-test.ts:4:21 - error TS7016: Could not find a declaration file for module 'ember-cli-htmlbars'. 'C:/Users/Preston/Documents/Development/NullVoxPopuli/emberclear/packages/frontend/node_modules/ember-cli-htmlbars/lib/index.js' implicitly has an 'any' type.
  Try `npm install @types/ember-cli-htmlbars` if it exists or add a new declaration (.d.ts) file containing `declare module 'ember-cli-htmlbars';`

4 import { hbs } from 'ember-cli-htmlbars';
                      ~~~~~~~~~~~~~~~~~~~~

app/components/pod/index/begin-button.ts:2:10 - error TS2614: Module '"../../../../../../../../../../../../Users/Preston/Documents/Development/NullVoxPopuli/emberclear/packages/frontend/node_modules/@types/ember__component"' has no exported member 'setComponentTemplate'. Did you mean to use 'import setComponentTemplate from "../../../../../../../../../../../../Users/Preston/Documents/Development/NullVoxPopuli/emberclear/packages/frontend/node_modules/@types/ember__component"' instead?

2 import { setComponentTemplate } from '@ember/component';

app/components/app/sidebar/chats/index.ts:4:36 - error TS2307: Cannot find module '@ember/object/compat'.

4 import { dependentKeyCompat } from '@ember/object/compat';
     

[chriskrycho]

• hbs is covered b/c ember-cli-htmlbars publishes types
• dependentKeyCompat has been in there for quite some time now
• there are still no docs for setComponentTemplate – the second someone opens a PR documenting that (wink wink nudge nudge) we can publish types for it a well

[NullVoxPopuli]

I am not really a fan of waiting to add types until there are docs.

setComponentTemplate doesn't exist in ember (it's in @glimmer/manager), and going through all the loop holes to get docs to show up in the api docs for packages that aren't acutally in ember-source... is a lot. :cry:

tldr: I don't know what to do. adding:

// eslint-disable-next-line no-ts-whatever
// @ts-expect-error

everywhere for setComponentTemplate, getValue, and all the other new apis from 3.25+ is.. :weary:

[NullVoxPopuli]

tho, I just had an idea...

[NullVoxPopuli]

I think this'll work: https://github.com/emberjs/ember.js/pull/19953

[chriskrycho]

@NullVoxPopuli

I am not really a fan of waiting to add types until there are docs.

While I can understand the sentiment, there is very good reason we do not provide types for undocumented APIs. We’ve maintained that policy for a very long time because we’re not just interested in what’s convenient now, but what is good for the long term healthy of the entire ecosystem. We have earned the trust of the Ember community and Ember’s leadership in this entirely-community-maintained (and always, remember, completely unsupported any Core team!) project by being extremely careful about things like that. In particular, we have made sure that we do not step on other people’s toes by over-specifying things which Ember itself hasn’t—and we have thereby avoided ever teaching the community to rely on TS-only features, TS-only docs, etc.

Disagreement is totally reasonable! There are tradeoffs here!—but that’s our policy and we’re not going to change it, so please accept it as a given going forward.

Happily, in the medium-term, this problem goes away because those types will be published by Ember itself, which will keep us in line much more automatically. (And I hope that Ember will also continue to improve on its discipline of documenting all of its public API!)

[ef4]

FWIW, setComponentTemplate is a thoroughly RFC'd, very intentionally public API.

The docs have both technical and thematic limitations that make it challenging to categorize an API like setComponentTemplate which is public-but-low-level. I would suggest that written RFCs are equivalently good evidence to support policy choices about what to include in the types.

[chriskrycho]

Philosophically, I mostly agree!

Practically, there are very good reasons we haven’t allowed RFCs to be the source of truth for what we publish in our types, including that they historically haven’t necessarily matched what’s actually shipped! That’s become less a problem recently, as folks have tried to be more diligent about updating the RFC in that case, but even so, RFCs have been a poor source of truth for us.

(Here, I think with the review I did earlier today, we should be unblocked to publish the docs.)

[chriskrycho]

I believe this is now resolved since Ember ships its own types. :)