Missing Types for (undocumented) setComponentTemplate API

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
• @types/ember__object
• @types/ember__utils
• @types/ember__array
• @types/ember__engine
• @types/ember__debug
• @types/ember__runloop
• @types/ember__error
• @types/ember__controller
• @types/ember__component
• @types/ember__routing
• @types/ember__application
• @types/ember__test
• @types/ember__test-helpers
• @types/ember__service
• @types/ember-data
• @types/rsvp
• 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]

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]

@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!)