Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introduce infra to publish stable types #20275

Merged
merged 9 commits into from
Nov 22, 2022
Merged

Conversation

chriskrycho
Copy link
Contributor

@chriskrycho chriskrycho commented Nov 22, 2022

Provide a script which runs the compiler against a new tsconfig for generating types, wraps all the generated modules in declare module statements, and then creates an index.d.ts which uses side-effect style imports to expose them all, just the same as the preview types but generated from source.

Note

Critically, this infrastructure does not expose any stable types in and of itself. Instead, it introduces a list of all the types still in preview mode which acts as a filter, and currently all modules are in that filter. Stabilizing the types for a given module will mean removing modules from that list and removing the corresponding preview types definitions.

There are… some hacks involved in this, as was foretold in the PR introducing preview types (#20180). Because Ember does not ship the real packages people import from in a Node-resolveable way (and import maps are not yet stable and therefore not useful for TS in particular), the way this works is anything but preferable. Medium-term, we need to figure out how to generate module rollups which don’t require us to manually do this wrapping, but this will do the trick for now.

In support of this:

  • Restructure how we handle the root tsconfig.json file by introducing a base compiler-options file which it extends, which in turn we can further extend off of for future needs.
  • Fix a type error that was preventing type generation.

@chriskrycho chriskrycho added the TypeScript Work on Ember’s types label Nov 22, 2022
There are pre-existing runtime shenanigans in `@ember/object/internals`
to add debug-only errors to the class in dev builds. Those runtime
shenanigans produce the need for type-level shenanigans to match: TS
gets stuck here because the runtime shenanigans declare
`FrameworkObject` with a class expression (rather than the usual class
declaration form). That in turn means TS needs to be able to fully name
the type produced by the clsas expression, which includes the `OWNER`
symbol from `@glimmer/owner`.

By explicitly giving the declaration a type when assigning it the class
expression, instead of relying on inference, TS no longer needs to name
the `OWNER` property key from the super class, eliminating the private
name shenanigans.

Co-authored-by: Dan Freeman <dfreeman@salsify.com>
This lets each config specify *only* how it actually does a build (or
not!), while sharing the config explicitly.

It also fixes an existing bug in the compilation settings which was not
affecting *normal* TS compilation with `tsc`, but was generating noise
in the `broccoli-typescript-compiler` pipeline because the packages
happened to be resolved in a different order such that the `loader`
"package" definition, and its declaration of the `require` module, was
not present in the graph. Set it explicitly in `compilerOptiosn.paths`
to fix that.
Provide a script which runs the compiler against a new tsconfig for
generating types, wraps all the generated modules in `declare module`
statements, and then creates an `index.d.ts` which uses side-effect
style imports to expose them all, just the same as the preview types
but generated from source.

Critically, this infrastructure does not expose *any* stable types in
and of itself. Instead, it introduces a list of all the types still in
preview mode which acts as a filter, and currently *all* modules are in
that filter. Stabilizing the types for a given module will mean
removing modules from that list and removing the corresponding preview
types definitions.
Align the text with the module docs for the stable types, clarifying
the updated current status.
Copy link
Member

@wagenet wagenet left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems promising, but I haven't tested it yet.

@module
Makes Ember's types for the packages it publishes available by importing this
path from `ember-source`:
Provides stable type definitions for Ember.js. It is maintained by hand, and
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm a bit confused by the wording here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doh. Good catch. Copy-paste failure.

let moduleNameForDeclaration = moduleName.replace('/index.d.ts', '');

let string = new MagicString(contents);
string.indent(' ').prepend(`declare module '${moduleNameForDeclaration}' {\n`).append('}\n');
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Am I correct that you're just using MagicString for these indent methods? It doesn't look like you're writing a source map.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, right. We can (if we want) switch to a more manual approach and the indent-string package, which is a bit smaller and lighter weight. I ended up here after having started there because I was trying to keep around the existing source maps that TS was generating, but I cannot see a way to do that, unfortunately.

packages/@ember/object/-internals.ts Outdated Show resolved Hide resolved
types/publish.mjs Show resolved Hide resolved
@chriskrycho chriskrycho merged commit 38e5499 into master Nov 22, 2022
@chriskrycho chriskrycho deleted the stable-types-infra branch November 22, 2022 21:51
@chriskrycho chriskrycho changed the title [FEATURE] Stable types infra Internal: stable types infra Nov 22, 2022
@chriskrycho chriskrycho changed the title Internal: stable types infra Introduce infra to publish stable types Nov 23, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
internal TypeScript Work on Ember’s types
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants