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.