Discussion/pre-RFC: what is the right long-term home for environment types?

[chriskrycho]

Today, Glint supplies all of the type definitions it requires to work via a combination of the @glint/template package (the baseline for the rest) and the various environments which extend that appropriately for their own context. This is serving us well so far, but it has the potential to cause some issues down the line, which I want to note down as I'm thinking about them today.

One of the frustrations with DefinitelyTyped is that there is no good way to match the versioning between the types on DT with the actual version of any given package, particularly around new features added in minor releases. For example, we recently had a very annoyed user complaining about the Ember 3.x types including all APIs released up through 3.28 on types which worked for any Ember 3.x consumer, and thereby providing some misleading suggestions for APIs which do not exist on the version he was on. (I do not want to over-index on that particular complaint, of course, but it is illustrative of the challenge.) We have the same potential issue for every item which appears in the globals list for any given environment.

Consider the introduction—hopefully soon!—of the equality and comparison keywords: these will need to be added to the globals/built-ins list in environment-ember-loose, but they will only actually work correctly in Ember on a version which actually includes that functionality.¹ We do not have any particularly good way to signal which versions of Glint environment types are compatible with a given Ember version. We can (and, as long as we are taking this tack, definitely should) document it, but we also then have the problem of figuring out how to handle bug fix releases—do we end up having @glint/template with 1.1.x and 1.2.x maintenance streams ongoing, where 1.2.x supports Ember 4.10+, while 1.1.x does not? Etc.

Net, I propose that medium-to-long-term, the Glint environments should move out of Glint to the packages which they represent. Now, that has its own potential problems in that we could end up with Glint depending on types from those packages and those packages depending on types from Glint. One way to cut that knot is to make sure that @ember/glint (hypothetical future package) is a real package which is versioned in lockstep with and published out of the same repo as ember-source, and to then guarantee that the direction of dependencies only ever running these ways:

• ember-source ← @glint/template
• ember-source ← @ember/glint
• @glint/template ← @ember/glint

I believe that would resolve that particular thorny issue, while giving us the ability to make sure we keep the definitions for the environment in sync—but it’s very possible there’s a piece of it I’m not seeing! Also, it still has a relatively annoying issue around versioning of @glint/template and ember-source (and the relation of both to the underlying @glimmer/* bits: because they are intimately and inextricably connected to at least some degree).

Thoughts, @dfreeman @jamescdavis?

Footnotes

1. or via polyfill, of course, but the point is generally the same. ↩

[dfreeman]

Net, I propose that medium-to-long-term, the Glint environments should move out of Glint to the packages which they represent.

I think this makes sense, particularly as first-class TS support is approaching reality in Ember itself. Everything that follows is just sifting through the details.

ember-source ← @glint/template
ember-source ← @ember/glint
@glint/template ← @ember/glint

I think in this scenario (if I'm understanding correctly), ember-source and @glint/template would be mutually unaware of each other, and @ember/glint would be solely responsible for tying the two together.

@ember/glint (hypothetical future package)

From a naming perspective, we might go with @ember/glint-environment. That would open the door to do the same thing Babel and ESLint both do for their plugin packages and accept environment: "@scope" as shorthand for environment: "@scope/glint-environment".

Then we could have environment: "@ember", environment: "@glimmerx", and so on to refer to Glint integration provided by the toolkit in question.

Also, it still has a relatively annoying issue around versioning of @glint/template and ember-source

Agreed we would need to think carefully about the semver policy here, but I expect after the changes under discussion in #396 land that @glint/template will be fairly stable for the foreseeable future.

We also need to worry some about the touchpoint between @ember/glint-environment and @glint/core, as we've so far been able to treat the environment interface as essentially an implementation detail. I think stabilizing that interface and declaring it public is feasible, it will just require us to be a little more thoughtful about any changes to it going forward.

(and the relation of both to the underlying @glimmer/* bits: because they are intimately and inextricably connected to at least some degree)

Glint does of course have a connection to the underlying @glimmer packages in terms of how it represents template semantics and what's valid there, but since that's mediated by Ember (or whatever environment), I think Glint itself can remain fairly decoupled on that front.

Off the top of my head, the only tight binding I know we have currently outside of an environment package is the use of ExpandSignature from @glimmer/component in @glint/template, and that's already caused some consternation in other areas since it forces a peer dependency.

I think our reasoning for making @glimmer/component the source of truth made sense, but we might just want to cut that knot and define our own ExpandComponentSignature type in @glint/template. Technically the @glimmer/component package doesn't even care about anything other than Args anyway!