Deprecate Events System

[wagenet]

Propose Deprecating Evented Mixin

Rendered

Summary

This pull request is proposing a new RFC for Deprecating the Evented Mixin.

To succeed, it will need to pass into the Exploring Stage, followed by the Accepted Stage.

A Proposed or Exploring RFC may also move to the Closed Stage if it is withdrawn by the author or if it is rejected by the Ember team. This requires an "FCP to Close" period.

An FCP is required before merging this PR to advance to Accepted.

Upon merging this PR, automation will open a draft PR for this RFC to move to the Ready for Released Stage.

Exploring Stage Description

This stage is entered when the Ember team believes the concept described in the RFC should be pursued, but the RFC may still need some more work, discussion, answers to open questions, and/or a champion before it can move to the next stage.

An RFC is moved into Exploring with consensus of the relevant teams. The relevant team expects to spend time helping to refine the proposal. The RFC remains a PR and will have an Exploring label applied.

An Exploring RFC that is successfully completed can move to Accepted with an FCP is required as in the existing process. It may also be moved to Closed with an FCP.

Accepted Stage Description

To move into the "accepted stage" the RFC must have complete prose and have successfully passed through an "FCP to Accept" period in which the community has weighed in and consensus has been achieved on the direction. The relevant teams believe that the proposal is well-specified and ready for implementation. The RFC has a champion within one of the relevant teams.

If there are unanswered questions, we have outlined them and expect that they will be answered before Ready for Release.

When the RFC is accepted, the PR will be merged, and automation will open a new PR to move the RFC to the Ready for Release stage. That PR should be used to track implementation progress and gain consensus to move to the next stage.

Checklist to move to Exploring

• The team believes the concepts described in the RFC should be pursued.
• The label S-Proposed is removed from the PR and the label S-Exploring is added.
• The Ember team is willing to work on the proposal to get it to Accepted

Checklist to move to Accepted

• This PR has had the Final Comment Period label has been added to start the FCP
• The RFC is announced in #news-and-announcements in the Ember Discord.
• The RFC has complete prose, is well-specified and ready for implementation.
  • All sections of the RFC are filled out.
  • Any unanswered questions are outlined and expected to be answered before Ready for Release.
  • "How we teach this?" is sufficiently filled out.
• The RFC has a champion within one of the relevant teams.
• The RFC has consensus after the FCP period.

[kategengler]

Needs deprecation guide

[wagenet]

The RFC currently recommends switching to the internal addListener/removeListener APIs. I'm thinking we should probably deprecate these too and just entirely discourage using Ember for handling listeners period. Do we have any suggestions for alternate libraries we should recommend?

[NullVoxPopuli]

Probably:

• CustomEvent (built in)
• eve
• rxjs

[wagenet]

According to ember-observer, some addons importing from @ember/object/evented (as opposed to the methods on EmberObject) include:

• ember-data / warp-drive (Maybe)
• ember-moment - 1
• fleetbase - 1 2 3
• ember-select - 1
• ember-simple-auth - 1
• ember-flexberry - 1
• ember-drag-drop - 1
• ember-stereo - 1 2 3
• ember-modal-dialog - 1

[wagenet]

emittery looks like the best alternative library for cases that can't use the built in CustomEvent.

[wagenet]

However, if we do deprecate support entirely, I think we may need to keep it around for the RouterService as an exception.

[NullVoxPopuli]

I think we can kill have of the evented mixin tho / inline what we need in to the RouterService (we probably don't even need addListener / removeListener)

[ef4]

The deprecation guide looks good, the text of the RFC needs updating to match (it mentions using @ember/object/events, whereas the deprecation guide says that is deprecated).

[NullVoxPopuli]

This RFC can be ready for FCP pending updates to the recommendation of what to use instead of the Evented mixin -- more closely matching what is in the PR'd deprecation guide ember-learn/deprecation-app#1404

[bendemboski]

I don't think this RFC is really complete without a description of how the RouterService events will work since today people might be (are, I know, because I am 😆) using @ember/object/events methods to listen on the RouterService. So I think this RFC either needs to describe how that will be replaced, including migration guide, or needs to reference another RFC describing the changes to the RouterService?

[wagenet]

@bendemboski the RFC says:

Exception: The methods will continue to be supported (not deprecated) on the RouterService, since key parts of its functionality are difficult to reproduce without them. This RFC does not propose deprecating those usages.

What further clarification do you need? Maybe if you can provide some example code that would be helpful.

[bendemboski]

What further clarification do you need? Maybe if you can provide some example code that would be helpful.

If I have code that looks like this:

import { service } from '@ember/service';
import type RouterService from '@ember/routing/router-service';
import type Transition from '@ember/routing/transition';
import { addListener, removeListener } from '@ember/object/events';
import { registerDestructor } from '@ember/destroyable';

export default class SomeComponentOrWhatever {
  @service('router') declare private router: RouterService;

  constructor(/*...*/) {
    super(/*...*/);
    addListener(this.router, 'routeWillChange', this.onRouteWillChange);
    registerDestructor(
      this,
      () => removeListener(this.router, 'routeWillChange', this.onRouteWillChange)
    );
  }

  private readonly onRouteWillChange = (transition: Transition) => {
      if (this.isUnsaved()) {
        alert("Please save or cancel your changes.");
        transition.abort();
      }
  };
}

how do I rewrite it to not use @ember/object/events?

[bendemboski]

I also really think we should be recommending a synchronous alternative to emittery. I don't think it's a very reasonable expectation that most applications that use @ember/object/events will be ready to refactor/rearchitect everything to use asynchronous events. So IMO we should embrace the idea that the audience of this RFC includes people that will be moving from @ember/object/events to an asynchronous events model and people that will be staying on a synchronous events model (or progressively migrating).

Therefore if we think it's within the scope of this RFC to recommend a specific alternative (which it doesn't have to be -- we could just say go pick your own library from among all the various options in the ecosystem), I think we should make both an asynchronous and synchronous recommendation. Or neither.

It's possible that my perspective here is skewed because my 10+ year old application makes fairly heavy use of events that must be synchronous because of the application architecture, but I suspect I'm not alone.

[bendemboski]

Oh, you already added synchronous recommendations to the deprecation guide -- great, thanks! Disregard my last comment 😄

[wagenet]

@bendemboski for the router, you could use the methods that will continue to live on it: on, one, trigger, off, and has. We can make a point of calling this out in the deprecation guide.

[BobrImperator]

I somehow stumbled upon this and would like to share my 2 cents and experience when migrating an addon that makes use of events internally and also exposes them to the users.

The RFC doesn't mention NodeJS as a target which is essentially Fastboot. Evented API supports nodejs, and while the proposed Emittery also supports it, because it's not explicitly mentioned, it feels like the NodeJS support is accidental here.
In ember-simple-auth's case which is an addon, we also tried hard not to introduce any external dependencies.
However naively using Browser's EventTarget API will fail in fastboot (nodejs) case. So the transition to support both while staying in Ember-land was to create an emitter on top of Evented.
I think that this PR could showcase what an addon author needs to do during migration mainmatter/ember-simple-auth#2887.

[kategengler]

We will try to address SSR in the deprecation guide when this progresses.