Ember v4 TypeScript Assist Replace

The Typed Ember group—Chris Krycho (@chriskrycho), Dan Freeman (@dfreeman), and James Davis (@jamescdavis)—is completely satisfied to announce that the @varieties sort definition packages, maintained on Positively Typed, now have full assist for Ember 4.x!

TypeScript is “JavaScript with syntax for varieties.… a strongly typed programming language that builds on JavaScript, providing you with higher tooling at any scale.” Utilizing Ember won’t ever require utilizing TypeScript, however we goal to supply a best-in-class expertise of utilizing TypeScript, with advantages for JavaScript customers too. Need to attempt it out? Comply with the docs for ember-cli-typescript.

This replace for Ember v4 varieties brings two main modifications with two huge advantages.

The 2 main modifications:

• All APIs which have been deprecated throughout the 3.x cycle and eliminated in Ember v4.0.0 have been dropped from the categories. Amusingly, this consists of plenty of issues which have been deprecated in 2.x and eliminated at 3.0, and even a couple of which have been deprecated the 1.x period and eliminated at 2.0! Moreover, plenty of varieties representing non-public API have been eliminated, in step with our standing coverage of offering varieties for under public APIs.

• The minimal supported TypeScript model is 4.4. This aligns with our upcoming proposal for Ember’s personal TypeScript assist coverage, the place main releases will typically undertake a current TypeScript model as their minimal supported model, and with a assist coverage just like that for browsers and Node LTS releases. (Maintain your eyes open for a forthcoming RFC tackling these particulars!)

The 2 huge advantages:

1. For those who’re a JavaScript Ember consumer, your editor tooling could get a bit smarter and higher. VS Code (and different editors) can benefit from these varieties to give you higher autocomplete, docs, and many others. and people will appropriately mirror Ember v4 APIs.

2. For those who’re a TypeScript Ember consumer, now you can use v4 in your @varieties dependencies. That will provide you with the identical advantages as JavaScript customers get by way of the up-to-date definitions for Ember itself, however it should additionally catch extra errors and supply a lot higher suggestions in lots of circumstances, as a result of we at the moment are utilizing the most recent and best options of TypeScript for these varieties.

Be aware that we’ve got not but eliminated the v3 deprecations or up to date the strictness of the Ember Information v4 varieties, however we have up to date Ember Information’s varieties to make use of the identical minimal TypeScript model and to be suitable with the modifications made in Ember’s varieties. (Sadly, not one of the Typed Ember maintainers has deep familiarity with Ember Information!) For those who’d like to assist get these updated, attain out to us in #e-typescript on the Ember Discord!

Notable modifications

• The kinds now use "strict": true of their compiler choices. Basically, this is not going to trigger you any work; as a substitute, it signifies that internally the categories should be extra strong, which ought to trigger you fewer points when working in strict mode your self. Nonetheless, in a couple of circumstances, it meant we caught sort security bugs throughout the improve, which can present up in modifications like these listed under.

• Breaking: The kinds now use unknown in lots of locations the place any was previouly used.

• Breaking: most of the API varieties have been improved and lots of bugs fastened. Which means they’re prone to reject plenty of invocations which have been allowed beforehand, however which might produce bugs at runtime, have been deceptive or complicated, and many others.

  Just a few notable examples:

  • The beforeModel and afterModel hooks on Routes have been up to date to require that you simply return both a Promise or nothing, since return values are in any other case ignored. For those who have been returning non-Promise values beforehand, you need to take away these return statements.
  • The @ember/runloop capabilities now robustly verify their arguments. For those who have been passing invalid arguments for the callbacks, the compiler will now catch that.

• Breaking: The TestContext for the callbacks utilized in module, beforeEach, afterEach, check, and many others. has moved from ember-test-helpers to @ember/test-helpers. Having almost every little thing be in @ember/test-helpers however not TestContext has been a persistent supply of confusion over time, and was only a little bit of historic baggage left over from earlier than @ember/test-helpers existed. If RFC #0785 is merged, we can even be capable to transfer away from utilizing the TestContext in any respect!

Upgrading

To make use of these varieties, comply with these improve steps:

1. Replace your challenge to make use of TypeScript 4.4 or later. Repair any sort errors this identifies (particularly in case you are utilizing the beneficial "strict": true settings).

2. Replace to Ember 4.0 or later. This itself would require eradicating all of the deprecated code paths, which would be the main effort.

3. Replace to Ember Information 4.0 or later.

4. Replace the core Ember and Ember Information varieties. This may occasionally imply doing a good bit of cleanup throughout your code base to carry issues in step with the stricter and extra strong varieties we now provide.

   • Improve @varieties/ember to "~4.0".

   • Improve all @varieties/ember__* besides @varieties/ember__string and @varieties/ember__test-helpers to "~4.0".

   • Improve @varieties/ember-data__* to "~4.0".

5. Replace associated varieties packages. Some @ember/* packages are versioned individually from the packages in ember-source and so want their very own updates:

6. Replace testing infrastructure. Whereas these packages are technically impartial of the Ember main model, coordinating this explicit improve required updating them in parallel.

   • Improve to ember-qunit@^5 and @varieties/ember-qunit@^5.

   • Wherever you have got imported TestContext from ember-test-helpers, substitute it with import { sort TestContext } from '@ember/test-helpers';. You’ll probably be capable to merge this with current imports from @ember/test-helpers.

   • Take away all references to ember-test-helpers out of your challenge, and take away @varieties/ember-test-helpers out of your dependencies.

As soon as every little thing is compiling once more, you may be good to go!

Be aware: you should generate a brand new lockfile, use yarn resolutions, or manually delete all of those @varieties package deal variations out of your current lock file when doing the improve, or you’ll definitely see conflicts between current (transitive) dependencies on these varieties and your up to date variations. That is the results of two issues that are cheap on their very own however don’t work collectively properly:

• TypeScript can solely sort verify efficiently if there’s solely a single illustration of a given sort (for instance, EmberObject). If it finally ends up with conflicting definitions of the identical sort, it has to surrender as a result of it doesn’t know what it ought to select.

• npm and Yarn each attempt to protect current transitive dependencies and putting in new copies while you bump a model. That is the most secure conduct for runtime dependencies! It signifies that should you replace a top-level dependency, if another package deal is relying on a unique model of it transitively, that different package deal doesn’t break.

What if I get caught?

You could hit fascinating challenges in coping with the improved sort strictness in locations the place your code relied on the unfastened (or misguided!) varieties earlier than. In case you are having a tough time, please attain out in #e-typescript on Discord or begin a Dialogue on the ember-cli-typescript-repo. The Typed Ember group is completely satisfied to assist, and lots of different folks locally are as properly.

Additionally, whereas we’ve executed our highest to make this completely bug-free, it’s fully attainable that we missed one thing or made a mistake! Please be happy to verify in with us on Discord or to file a bug. We encourage you to verify with us first, although: in lots of circumstances issues which appear to be bugs are literally the sort system catching errors the earlier varieties couldn’t catch!

The long run

We hope (and totally anticipate!) this to be the final main launch of Ember’s varieties on DefinitelyTyped. Throughout the 4.x sequence, we goal to complete the work to formally assist TypeScript. That can make it a lot simpler for TypeScript customers and maintainers to cope with each main and minor updates:

• Deprecations will robotically be current in each varieties and run-time code, and they are going to be eliminated proper alongside runtime modifications when prepping for a significant launch.

• The design of deprecations or modifications will embrace easy migration paths for varieties in addition to for the runtime conduct of the app.

• Extra typically, having varieties as first-class elements of each design dialogue signifies that new APIs shall be TypeScript-friendly robotically. (Many older Ember APIs are very unfriendly to TypeScript!)

• The supported TypeScript variations shall be documented clearly, identical to with Node and browsers, making it simpler so that you can know what you need to do to remain updated.

• Breaking modifications in a single package deal is not going to essentially trigger breaking modifications in different packages. The updates to the check infrastructure varieties, for instance, is not going to breaking sooner or later!

And as at all times, these advantages will prolong to much more of our JavaScript customers, as a result of many extra editors benefit from varieties which ship natively with packages than implicitly benefit from the categories from DefinitelyTyped.

Maintain your eyes open for an RFC within the subsequent few weeks tackling all of those sorts of issues and extra. Completely satisfied TypeScripting!