Saying the Official TypeScript Sorts Public Preview

As of ember-source@4.8.0-beta.2, Ember is delivery a public preview of our official TypeScript help for the framework itself. That is the following step in implementing RFC 0724: Official TypeScript Assist and RFC 0800: TypeScript Adoption Plan. Anybody utilizing TypeScript with Ember 4.8.0 Beta 2 or later can decide into utilizing these preview varieties by eradicating the corresponding @varieties packages and including the next import in your varieties/<your app>/index.d.ts file:

import 'ember-source/varieties';
import 'ember-source/varieties/preview';

In the event you’re curious concerning the particulars of how this strategy to publishing TypeScript varieties for Ember works, try the PR which launched help!

How the preview interval will work

There are two type-only modules you import: 'ember-source/varieties' and 'ember-source/varieties/preview'. These characterize the secure and preview varieties respectively. At the beginning of the preview interval, there may be nothing in any respect within the secure module: all the kinds are within the preview module.

The important thing distinction between the secure and preview varieties is: our secure varieties should be generated from Ember’s personal TypeScript supply code, whereas the preview varieties are hand-written kind definitions. The hand-written definitions match up carefully to the precise code, however small gaps are inevitable. Sorts revealed instantly from Ember’s personal supply code is not going to have that drawback!

Over the course of the preview interval, we can be doing two issues:

1. We can be fixing bugs in these varieties as they’re recognized, and releasing bug repair releases the identical approach we’d for runtime errors. (This would be the new regular for Ember: fixes to varieties are precisely like fixes to runtime errors, as a result of each are bugs!)

2. We can be engaged on Ember’s construct infrastructure and the construction of its internals to make it doable to publish varieties instantly from the supply, as a substitute of utilizing hand-authored varieties. These are the kinds which can be uncovered through the import 'ember-source/varieties'; assertion.

As soon as we’re totally minimize over to publishing varieties from Ember’s supply code, we are going to declare them “secure” and subsequently topic to Ember’s regular SemVer coverage. For particulars on how we’re dealing with SemVer for TypeScript, try the related part of RFC 0800 and the Semantic Versioning for TypeScript spec we authored and observe. We’ll even be updating the web site with these particulars within the subsequent few weeks.

We’ll make a finest effort to keep away from breaking modifications within the varieties throughout the preview interval, however the transition to the secure varieties will inevitably contain many bug fixes which can really feel like breaking modifications!

Additionally, on condition that these are preview varieties, we are going to proceed to keep up the kinds on DefinitelyTyped till we stabilize these. In the event you attempt them out and hit points you can not resolve, that’s completely tremendous! There are two issues we predict it’s best to do in that case:

1. File a problem on the ember.js repo with a report concerning the situation you had.
2. Change again to the @varieties packages!

We’ll be certain that there aren’t any blocking bugs earlier than stabilizing.

Migrating from DefinitelyTyped

This part solely applies in case you are an present Ember TypeScript consumer who has been utilizing the @varieties packages from DefinitelyTyped. In the event you’re making an attempt out TypeScript for the primary time now, you possibly can skip it!

There are 4 steps concerned in switching from the prevailing varieties revealed on DefinitelyTyped to those preview varieties.

1. Take away the next packages out of your package deal.json:

   • @varieties/ember
   • @varieties/ember__application
   • @varieties/ember__array
   • @varieties/ember__component
   • @varieties/ember__controller
   • @varieties/ember__debug
   • @varieties/ember__destroyable
   • @varieties/ember__engine
   • @varieties/ember__error
   • @varieties/ember__helper
   • @varieties/ember__modifier
   • @varieties/ember__object
   • @varieties/ember__owner
   • @varieties/ember__polyfills
   • @varieties/ember__routing
   • @varieties/ember__runloop
   • @varieties/ember__service
   • @varieties/ember__string
   • @varieties/ember__template
   • @varieties/ember__test
   • @varieties/ember__utils

2. Set up a model of ember-source larger than 4.8.0-beta.2. You must decide the newest beta of 4.8 or any secure model beginning with 4.8.0 as soon as it is out!

3. Within the varieties/<your-app>/index.d.ts file generated for you robotically by ember-cli-typescript, add the brand new imports as the primary objects within the file, and take away the array prototype extensions help from the file. With the defaults generated for you, the end result would seem like this:

   +import 'ember-source/varieties';
   +import 'ember-source/varieties/preview';
   -import Ember from 'ember';
   -
   -declare international {
   - // Prevents ESLint from "fixing" this through its auto-fix to show it into a kind
   - // alias (e.g. after operating any Ember CLI generator)
   - // eslint-disable-next-line @typescript-eslint/no-empty-interface
   - interface Array extends Ember.ArrayPrototypeExtensions {}
   - // interface Perform extends Ember.FunctionPrototypeExtensions {}
   -}
   
   export {};

4. Account for the variations between the preview varieties and the definitions on DefinitelyTyped. These variations all fall into one among these broad classes:

   • Fixes to issues within the present definitions.
   • Removing of our (poor!) help for Ember Basic class options in favor of native courses.
   • Modifications to kind registry dealing with
   • Removing of legacy (non-public) routing APIs

For the preview varieties, we began by copying over the community-maintained kind definitions from DefinitelyTyped. We then up to date them to make use of extra sturdy kind testing instruments that DefinitelyTyped permits, which uncovered a bunch of bugs to repair. We additionally did a primary comparability of the kinds we’re publishing with the corresponding varieties in Ember’s personal code, which has been written in TypeScript for years and obtained an enormous enchancment from @wagenet earlier this 12 months.

Consequently, it’s possible you’ll discover some variations if you swap over. In each case, these characterize bug fixes, however we acknowledge they could contain some work!

Introducing a Resolver kind

The categories on DefinitelyTyped provide a definition of Resolver from ember-resolver, which is the place most Ember customers get their resolver. Nonetheless, ember-resolver and different resolvers work as a result of they implement Ember’s contract for what a resolver is. A future RFC will introduce a public kind import for this. (It was missed throughout the work on RFC 0821 as a result of the kind presently does not come from Ember!)

For now, the kind exists at @ember/-internals/resolver, and is launched to be type-compatible with the kind for ember-resolver on DefinitelyTyped. (See this situation for a problem monitoring publishing varieties from ember-resolver, which is probably going gated on a public kind import from Ember, however till we ship secure varieties, will be managed through cautious varieties work on DefinitelyTyped.)

Eradicating help for Array prototype extensions

This work additionally uncovered numerous errors within the present varieties, particularly round Array prototype extensions. Consequently, these varieties don’t help Array prototype extensions, and it’s unlikely that future work will be capable to add that help. (The help offered through the kinds on DefinitelyTyped solely labored as a result of the kinds had been outlined incorrectly, leading to a wide range of sorts of unsafety.)

Notably, Array prototype extensions are being deprecated, so transferring off of them is figure you will have to do anyway.

Ember Basic help

As laid out in RFC 0800, there are additionally numerous breaking modifications from the kinds in DefinitelyTyped concerning help for Ember Basic options:

Per the version help coverage, we are going to present minimal help for Ember Basic options:

• Ember’s traditional class system: we are going to present minimal definitions for the .create(), .prolong(), .reopen(), .reopenClass(), strategies, which make no try to make use of them to truly replace the varieties of the objects they modify.…

• Ember’s get and set helpers: we is not going to present varieties to make get and set type-safe past property lookups on objects—i.e. no help for nested path lookups.…

• Basic computed property dealing with: we is not going to present “protected” varieties for the traditional type of computed properties.

Ember’s traditional class system

The definitions on DefinitelyTyped tried to make .create() and .prolong() really create up to date varieties, and tried to make .create(), .prolong(), .reopen(), and .reopenClass() have the right kind for this inside their our bodies. These had been all the time extraordinarily fragile and largely didn’t work. Since Ember 3.6, Ember customers have been ready to make use of native courses as a substitute of Ember’s traditional class system, and this has been the beneficial approach of writing Ember code because the launch of the Octane version in Ember 3.15.

Within the preview varieties, these strategies are current and are protected to make use of since they’re nonetheless a part of Ember’s public API. Nonetheless, .create() and .prolong() don’t create new varieties. The .create() technique does nonetheless verify that the values you go match these outlined on the category physique, however the varieties don’t try to make this have the correct kind inside the our bodies of .create(), .prolong(), .reopen(), or .reopenClass().

Emigrate, it’s best to:

• Convert all your individual traditional courses to native courses.
• Get rid of your use of mixins.

(Most Ember TypeScript customers have already achieved this, as a result of these labored so poorly with TypeScript.)

The .create() name can all the time get replaced with a traditional class definition in JavaScript. For every of the others, you can too use declaration merging to characterize the conduct of the strategy in query.

.prolong()

For the case the place you might be solely defining a brand new class, convert to a local class as a substitute. Nonetheless, when you’ve got code which nonetheless depends on mixins like Evented, you possibly can characterize it utilizing interface merging like this:

import EmberObject from '@ember/object';
import Evented from '@ember/object/evented';
import kind Proprietor from '@ember/proprietor';

// A local class which nonetheless applies the Evented mixin
class ExtendsDemo extends EmberObject.prolong(Evented) {
  moreStuff = true;

  constructor(proprietor: Proprietor) {
    tremendous(proprietor);
    this.on('customized', this, 'boundMethod');
  }

  willDestroy(): void {
    this.off('customized', this, 'boundMethod');
  }

  boundMethod = () => {
    alert('do one thing');
  };
}

// Make that work for the *kind* by merging the kind of the category
// (`interface ExtendsDemo`) with the kind of the mixin (`Evented`)
interface ExtendsDemo extends Evented {}

const occasion = ExtendsDemo.create({
  moreStuff: false,
});

occasion.set off('customized');

import Mixin from '@ember/object/mixin';

// Creates the runtime mixin code
const Alertable = Mixin.create({
  alert(worth: string) {
    alert(`The worth is ${worth}`);
  }
})

// Creates the kind for TypeScript to see.
interface Alertable extends Mixin {
  alert(worth: string): void;
}

// Exports them as a single identify in each worth and sort house.
export default Alertable;

import EmberObject from '@ember/object';

class Foo extends EmberObject {
  someProp = 123;
}

// That is what makes the change work at runtime...
Foo.reopen({
  additional: 'whats up',
});

// ...whereas that is what makes it seen to the kind system.
interface Foo {
  additional: string;
}

// Now when calling `Foo.create`, or when working with an occasion of the
// class, each `someProp` and `additional` can be checked.
const occasion = Foo.create({
  someProp: 456,
  additional: 'goodbye',
});

import EmberObject from '@ember/object';

class Foo extends EmberObject {
  static someStatic = true;
}

// This provides the strategy to the Foo class at runtime...
Foo.reopenClass({
  anotherStatic(): string {
    return 'whats up';
  },
});

// ...and this makes it seen to TypeScript as a static technique.
declare namespace Foo {
  export operate anotherStatic(): string;
}

if (Foo.someStatic) {
  Foo.anotherStatic().size;
}

These varieties, as a reasonably direct extraction from DefinitelyTyped, at the moment keep the service and controller kind registries. Given the shortage of help for traditional computed properties, that are the principle option to make the most of these at current, it’s pretty doubtless some or all of those can be eliminated earlier than stabilizing the kinds. The foremost remaining use case is type-safe lookup utilizing the Proprietor.lookup APIs, so when you’ve got ideas on that, please attain out in #dev-typescript.

Legacy routing kind areas

According to RFC 0821: Public API for Kind-Solely Imports, this PR additionally removes help for importing the kinds for Transition, RouteInfo, and RouteInfoWithMetadata from the non-public areas that DefinitelyTyped presently helps for backwards compatibility. Customers might want to migrate to utilizing the right import paths when switching to make use of these imports.

• import Transition from '@ember/routing/-private/transition' → import Transition from '@ember/routing/transition'
• import RouteInfo from '@ember/routing/-private/route-info' → import RouteInfo from '@ember/routing/route-info'
• import { RouteInfoWithMetadata } from '@ember/routing/-private/route-info-with-metadata' → import { RouteInfoWithMetadata } from '@ember/routing/route-info'

New TypeScript customers

This part solely applies in case you are making an attempt out the kinds for the primary time!

For the second, the easiest way to get began with these varieties is to put in ember-cli-typescript and use its turbines, then take away plenty of what it does. We can be fixing this within the weeks forward!

Right here’s the method as of as we speak:

1. Arrange ember-cli-typescript by operating ember set up ember-cli-typescript.

2. Take away the next newly-added packages out of your package deal.json:

   • @varieties/ember
   • @varieties/ember__application
   • @varieties/ember__array
   • @varieties/ember__component
   • @varieties/ember__controller
   • @varieties/ember__debug
   • @varieties/ember__destroyable
   • @varieties/ember__engine
   • @varieties/ember__error
   • @varieties/ember__helper
   • @varieties/ember__modifier
   • @varieties/ember__object
   • @varieties/ember__owner
   • @varieties/ember__polyfills
   • @varieties/ember__routing
   • @varieties/ember__runloop
   • @varieties/ember__service
   • @varieties/ember__string
   • @varieties/ember__template
   • @varieties/ember__test
   • @varieties/ember__utils

3. Set up a model of ember-source larger than 4.8.0-beta.2. You must decide the newest beta of 4.8 or any secure model beginning with 4.8.0 as soon as it is out!

4. Within the varieties/<your-app>/index.d.ts file generated for you robotically by ember-cli-typescript, add the brand new imports as the primary objects within the file, and take away the array prototype extensions help from the file. With the defaults generated for you, the end result would seem like this:

   +import 'ember-source/varieties';
   +import 'ember-source/varieties/preview';
   -import Ember from 'ember';
   -
   -declare international {
   - // Prevents ESLint from "fixing" this through its auto-fix to show it into a kind
   - // alias (e.g. after operating any Ember CLI generator)
   - // eslint-disable-next-line @typescript-eslint/no-empty-interface
   - interface Array extends Ember.ArrayPrototypeExtensions {}
   - // interface Perform extends Ember.FunctionPrototypeExtensions {}
   -}
   
   export {};

We’re additionally engaged on a “quest” situation for getting the remainder of RFC 0800 applied. There are a lot of different core packages which must publish varieties for us to get all the best way to our objective of getting first-class TypeScript help for the ecosystem. We might use your assist! In the event you’d prefer to pitch in, try the monitoring situation and attain out in #dev-typescript on Discord!

In parallel, there are two different massive efforts in flight:

1. The Ember TypeScript staff is making regular progress on getting Glint to its 1.0 launch.

   • We just lately shipped primary help for TypeScript challenge references, i.e. the --build command, and count on to complete that up by supporting --build --watch mode within the subsequent month or two.

   • We supported Framework Core staff member emeritus @chadhietala in touchdown full help for GlimmerX in Glint.

   • We recognized a big refactor we are able to make which can allow us to give a lot higher kind errors and remove numerous tough edge circumstances. (In the event you’ve hit the “Anticipated 3 arguments however obtained 2” error for an merchandise which solely has two arguments, this can repair that and a bunch of others as nicely!)

2. The Ember Studying staff is working carefully with the Ember TypeScript staff and to construct out help for TypeScript in our API docs and the Guides. The trouble is being led by a neighborhood member, @ttbach—and she or he might additionally use your assist, too! Many of the work right here does not require TypeScript experience, solely the power to work on Node instruments, so it’s one other good spot to leap in. Attain out to @thaobach in #dev-ember-learning if you need to contribute!

That’s it for now, however preserve your eyes open for additional weblog posts concerning the TypeScript effort and different components of Polaris!