Built in tracking utilities for promises

[NullVoxPopuli]

Propose Built in tracking utilities for promises

Rendered

Summary

This pull request is proposing a new RFC.

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.

[jrjohnson]

I love having an "ember" way to do this. We're in our third or fourth iteration of refactoring our ten year old app to handle asynchronous data better. Having this be awaitable and being able to access the value are both excellent improvements on TrackedAsyncData which we're very happy with, but sometimes feels a little bit difficult to do things without adding a boilerplate.

Couple of questions:
First, I can't see the difference between trackPromise and TrackedPromise. Is trackPromise just a nice way to create a new TrackedPromise?

Second, the method signature looks like it would only accept a Promise. It would be nice if I pass in a value if that value was returned, just like a resolved promise. This unlocks things like

get comments()
  return trackPromise(this.args.post?.comments ?? []);
}

Where maybe you want to handle a few different kinds of input, but get a consistent output without needing to wrap each case in some sort of cluttery Promise.

[NullVoxPopuli]

First, I can't see the difference between trackPromise and TrackedPromise. Is trackPromise just a nice way to create a new TrackedPromise?

mostly, yea, it's a shorthand -- if I were PRing this to ember today, this would probably be the implementation:

export function trackPromise<Value>(
  existingPromise: Promise<Value> | Value
): TrackedPromise<Value> {
  return new TrackedPromise(existingPromise);
}

This form is also more easily invoked from templates, whereas new-ing is not possible.

Second, the method signature looks like it would only accept a Promise. It would be nice if I pass in a value if that value was returned, just like a resolved promise. This unlocks things like

This is a good point -- I've updated the type signature for trackPromise above (I'll get to updating the RFC shortly -- but also, specifics of the type signatures are implementation details, imo. TS will keep us honest, and there is no type-checking in markdown haha)

get comments()
  return trackPromise(this.args.post?.comments ?? []);
}

Unrelated to your question, but perhaps for others: note that forgetting @cached on this getter would mean that every access to this.commentns would result in a new TrackedPromise instance (same behavior as with TrackedObject, etc)

[johanrd]

Nice, good writeup – thanks!

I would maybe expect to be able to import { tracked } … from the same path, eventually?

Wether that should be at at the 'old' @glimmer/tracking path (with polyfill), or in a new path I am not sure, as you write.

Most/all exports are called something with 'tracked', so a simple alternative could be:

import { tracked, TrackedPromise, TrackedArray } from '@ember/tracking'

I am also a bit unsure if the word 'reactive' is used lot in the built-in ember docs/guides at the moment. On the other hand, @ember/reactive can be nice if we more strongly want to 'embed' (in the import path) the story of "(auto)tracking is how Ember's reactivity model works" (Autotracking In-Depth)

[NullVoxPopuli]

would maybe expect to be able to import { tracked } … from the same path, eventually?
Most/all exports are called something with 'tracked', so a simple alternative could be:

Yeah, my current plan, pending other comments and other RFCs, to group imports by importance, so that folks without tree shaking (all of us) only pay for what they import, leaving the needed imports in by default at the top-level import.

All of this would need varying RFCs outside of what is prosed in this RFC PR

import { 
  // state containers
  TrackedPromise, TrackedArray, TrackedObject,
  // wrappers (1 line implementations)
  trackPromise, trackArray, trackObject,
  // core utilities
  tracked, cached, localCopy, ...
  // low-level
  cell, resource, sync
} from '@ember/reactive'; // also willing to use '@ember/tracking', 
                          // however, I think reactive may more more sense for the sub-paths


////////////////
// The rest of this is "pay only for what you import"

import { 
  TrackedMap, TrackedWeakMap,
  TrackedSet, TrackedWeakSet,
  trackMap, trackWeakMap, 
  trackSet, trackWeakSet
} from '@ember/reactive/collections';

import {
  TrackedURL, TrackedURLSearchParams,
  trackURL, trackURLSearchParams
} from '@ember/reactive/url';

// these would be low level _Cells_ or _Resources_, 
// and would have a .current property
import {
  devicePixelRatio,
  innerHeight,
  innerWidth,
  online,
  outerHeight,
  outerWidth, 
  screenLeft,
  screenTop,
  scrollX,
  scrollY, 
} from '@ember/reactive/window';

[runspired]

One of the reasons I'm against a built-in reactive promise is actually exactly this. I don't think that something that exposes additional values that the native primitive does not have should also pretend to be the native primitive in this way, because at that point you are a whole different thing.

e.g. this isn't ReactivePromise, this is AsyncData

conceptually, a reactive promise would wrap the original promises' methods in one that subscribes to a signal, then finally the original promise and use that to update the signal once the resolution was complete so that consuming code would repull. Obviously that's far less useful than the state-machine approach taken here and by many of these primitives.

[NullVoxPopuli]

Thanks, i agree actually. I've updated the name of the thing so it doesn't imply that it's trying to masquerade as a native promise

[runspired]

this is why https://github.com/emberjs/data/blob/2f7d94a812ad02ce0979bb1e07940e45fae8a38c/packages/ember/src/-private/promise-state.ts#L8 is so limited too: e.g it exposes the underlying states and the result and nothing more.

[sukima]

TrackedAsyncState chould have an internal flag that watches for access to error. This way if a consumer ignores the rejection the system can log (onerror) unhandled TrackedAsyncState errors.

Also, TrackedAsyncState could register a test waiter to make sure it allows glimmer a chance to show the intermediate results of the derived states. As part of making it easier to teach maybe we could provide some tooling to allow testing the isPending state without the need to explicitly wait for a requestAnimationFrame loop? Unless, this later part is out of scope for this RFC.

class TrackedPromiseState<TResolve = unknown, TReason = unknown> {
  @tracked _value?: TResolve;
  @tracked _reason?: TReason;
  @tracked _state: 'pending' | 'resolved' | 'rejected' = 'pending';

  #rejectionHandled = false;

  get value(): TResolve | undefined {
    return this._value;
  }

  get reason(): TReason | undefined {
    this.#rejectionHandled = true;
    return this._reason;
  }

  get isPending(): boolean {
    return this._state === 'pending';
  }

  get isFulfilled(): boolean {
    return this._state !== 'pending';
  }

  get isResolved(): boolean {
    return this._state === 'resolved';
  }

  get isRejected(): boolean {
    return this._state === 'rejected';
  }

  constructor(readonly promise: Promise<TResolve, TReason>) {
    waitForPromise(promise.then(
      (value: TResolve) => {
        this._state = 'resolved';
        this._value = value;
      },
      (reason: TReason) => {
        this._state = 'rejected';
        this._reason = reason;
        queueMicrotask(() => this.unhandledException());
      },
    ));
  }

  private unhandledException(): void {
    if (this.#rejectionHandled) return;
    console.log('Unhandled promise rejection', this._reason);
  }
}

[NullVoxPopuli]

o allow testing the isPending state without the need to explicitly wait for a requestAnimationFrame loop?

This part of the RFC feels relevant:

Note

Key behaviors:

• if the passed promise is resolved, or a non-promise, we do not await, this allows
  values to not block render (or cause a re-render if they don't need to)
• no @dependentKeyCompat
• promise states are all mutually exclusive

In particular, there is no need to explicitly wait for any timing -- requsetAnimationFrame or otherwise.

if a promise is resolved, you synchronously get the value back (isPending false, in your case, if I understand your concern correctly?)

Unless, this later part is out of scope for this RFC.

yeah - implementation details are out of scope -- i want to be more goal and behavior defining in the RFC, rather box us in to specific code too early, if that makes sense

TrackedAsyncState chould have an internal flag that watches for access to error. This way if a consumer ignores the rejection the system can log (onerror) unhandled TrackedAsyncState errors.

I really like this idea, however, it would have to work via side-effect -- which.. for ergo probably not a bad thing -- and would allow Sentry/whatever tool to capture uncaught errors still (if folks configure it that way)

1. Promise rejects
2. Choose:
   1. error attempts to be rendered
      1. set flag
      2. don't queue up a timeout or animation frame
      3. no need to log
   2. error is not rendered
      1. flag unset
      2. queue up a timeout or animation frame
      3. logs the error if the flag is still not set during this time.

(I could draw this as a statechart, easily, but I'm being lazy right now, and don't want to leave this page as I'm typing)

[ef4]

Initial thoughts on a first reading:

1. The name TrackedPromise feels off to me. In terms of mental model, it's more a kind of Resource than a kind of Promise. Same goes for making it implement PromiseLike. I see a lot of bad code written by developers who are confused about whether they should be using a resource-like pattern (you get objects right away and just derive from them reactively) vs an async function-like pattern (you must await things and then use them, and it's not reactive, it all happens once). Attempting mid-stream to go from resource-like to promise-like is almost always a mistake, and usually also results in bad lifetimes and memory leaks.

2. This RFC feels like half a Resources RFC. It's the reactivity without the lifetimes. If we did a resources RFC, I think it would achieve the ecosystem harmonization goal that this RFC is trying to achieve, but also for lifetimes.

3. This choice:

   Unlike TrackedAsyncData, all properties are accessible at throughout the the lifecycle of the promise. This is to reduce the pit-of-frustration and eliminate extraneous errors when working with promise-data. While ember-async-data can argue that it doesn't make sense to even try accessing value until a promise is resolved, the constraint completely prevents UI patterns where you want value and loading state to be separate, and not part of a single whollistic if/else-if set of blocks.

   would make me absolutely miserable as a TypeScript user. It makes it impossible to access .value as type Value rather than Value | null. In TS this is merely risky and inelegant by forcing use of the ! operator. In the template, it's just straight up impossible because ! doesn't work there.

   I'm curious what the UI patterns are you're referring to that don't properly check state before attempting to access value or error. Surely those patterns are Bad Actually?

[ef4]

A followup to my last point: if you want to just access .value immediately without worrying about the state, that case is better served by a variant that accepts the initial placeholder value as an argument. In that variant, accessing .value during state === 'pending' would necessarily be legal because you provided said value. Since the placeholder must be a Value type, the signature of .value itself would then be just Value and not Value | null.

[ef4]

And if somebody wants immediate access to .value and they want their placeholder to be undefined, that's also fine because they can say so explicitly like TrackedPromise<string | undefined>.

[NullVoxPopuli]

would make me absolutely miserable as a TypeScript user.

We can have the types behave strictly without throwing hard runtime errors.
For example, using never for value before the promise is resolved

[ef4]

We can have the types behave strictly without throwing hard runtime errors.

I could probably live with that as a compromise, and as a TS user it wouldn't matter to me whether the runtime cases throw (because the compiler won't let me use those cases). But I would still wonder why we think it's OK to let JS users write code that TypeScript would forbid.

[NullVoxPopuli]

most of JS patterns are forbidden when using TS 😉