@ember-data-mirror/store 5.5.0-alpha.19 → 5.5.0-alpha.21

package/dist/{many-array-CE2Jr4mQ.js → request-state-BrADgFy5.js}

@@ -3,11 +3,10 @@ import { macroCondition, getGlobalConfig, dependencySatisfies, importSync } from
 import { EnableHydration, SkipCache } from '@warp-drive-mirror/core-types/request';
 import { setLogging, getRuntimeConfig } from '@warp-drive-mirror/core-types/runtime';
 import { getOrSetGlobal, peekTransient, setTransient } from '@warp-drive-mirror/core-types/-private';
-import { _backburner } from '@ember/runloop';
-import { defineSubscription, notifySignal, defineSignal, createSignal, subscribe, createArrayTags, addToTransaction, addTransactionCB } from '@ember-data-mirror/tracking/-private';
+import { a as createSignal, b as consumeSignal, n as notifySignal, c as createMemo, w as willSyncFlushWatchers, A as ARRAY_SIGNAL } from "./configure-BfLLW6GY.js";
 import { CACHE_OWNER, DEBUG_STALE_CACHE_OWNER, DEBUG_IDENTIFIER_BUCKET, DEBUG_CLIENT_ORIGINATED } from '@warp-drive-mirror/core-types/identifier';
 import { dasherize } from '@ember-data-mirror/request-utils/string';
-import { compat } from '@ember-data-mirror/tracking';
+import { getPromiseResult, setPromiseResult } from '@ember-data-mirror/request';
 
 /**
   @module @ember-data-mirror/store
@@ -902,9 +901,245 @@ function _log(scope, prefix, subScop1, subScop2, subScop3, subScop4) {
   return [];
 }
 
+/**
+ * A WarpDriveSignal is a wrapper around a framework specific or TC39 signal
+ * that enables us to store and manage the signal in a universal way.
+ *
+ * WarpDrive uses signals to manage three separate concepts:
+ *
+ * - as a `storage` for a value local to the object that we want to be reactive
+ *   (see `@local` schema field for an example)
+ * - as a `gate` for a memoized getter that we want to act as a reactive property
+ *   but whose value is computed/pulled from a non-reactive source elsewhere
+ *   and whose latest value is stored in the signal
+ *   (see `field` schema field for an example)
+ * - as a `gate` with a manually managed value updated on pull when `isStale` is true
+ *
+ *
+ * It offers
+ *
+ * - a non-reactive way to access/update the current value
+ * - a non-reactive way to mark the signal as dirtied
+ * - a non-reactive way to store content for why the signal was dirtied
+ * - access to the underlying Signal(s) in-use
+ *
+ * For debugging:
+ * - the "key" or "name" of the signal
+ * - the "object identity" or "context" to which the signal is attached
+ *
+ * @internal
+ */
+
+/**
+ * We attach signals to their context object via
+ * a Map attached to the object via this symbol.
+ *
+ * This allows us to store multiple signals
+ * on the same object with smaller memory
+ * overhead and no WeakMap lookups.
+ *
+ * Performance sensitive objects should
+ * pre-warm their shape by assigning this
+ * during initialization.
+ *
+ * ```ts
+ * initializeSignalStore(obj);
+ * ```
+ *
+ * @internal
+ */
+const Signals = getOrSetGlobal('Signals', Symbol('Signals'));
+
+/**
+ * A util that will create a signal store on the object
+ * if it does not already exist and returns the associated
+ * signal store.
+ *
+ * @internal
+ */
+function withSignalStore(obj) {
+  if (obj[Signals] === undefined) {
+    initializeSignalStore(obj);
+  }
+  return obj[Signals];
+}
+
+/**
+ * A util that will create a signal store on the object
+ * if it does not already exist.
+ *
+ * Useful for pre-warming the shape of an object to ensure
+ * a key-transition to add it is not required later.
+ *
+ * @internal
+ */
+function initializeSignalStore(obj) {
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`Signal store already exists on object`);
+    }
+  })(obj[Signals] === undefined) : {};
+  obj[Signals] = new Map();
+}
+function createInternalSignal(signals, obj, key, initialValue) {
+  const warpDriveSignal = {
+    key,
+    context: obj,
+    signal: createSignal(obj, key),
+    value: initialValue,
+    isStale: false
+  };
+  signals.set(key, warpDriveSignal);
+  return warpDriveSignal;
+}
+function getOrCreateInternalSignal(signals, obj, key, initialValue) {
+  let signal = peekInternalSignal(signals, key);
+  if (!signal) {
+    signal = createInternalSignal(signals, obj, key, initialValue);
+  }
+  return signal;
+}
+function peekInternalSignal(signals, key) {
+  return signals?.get(key);
+}
+function consumeInternalSignal(signal) {
+  consumeSignal(signal.signal);
+}
+function notifyInternalSignal(signal) {
+  if (signal) {
+    signal.isStale = true;
+    notifySignal(signal.signal);
+  }
+}
+function entangleSignal(signals, obj, key, initialValue) {
+  let signal = peekInternalSignal(signals, key);
+  if (!signal) {
+    signal = createInternalSignal(signals, obj, key, initialValue);
+  }
+  consumeInternalSignal(signal);
+  return signal;
+}
+function createSignalDescriptor(key, intialValue) {
+  return {
+    enumerable: true,
+    configurable: false,
+    get() {
+      const signals = withSignalStore(this);
+      return entangleSignal(signals, this, key, intialValue).value;
+    },
+    set(value) {
+      const signals = withSignalStore(this);
+      const signal = getOrCreateInternalSignal(signals, this, key, intialValue);
+      if (signal.value !== value) {
+        signal.value = value;
+        notifyInternalSignal(signal);
+      }
+    }
+  };
+}
+
+/**
+ * define an enumerable signal property.
+ *
+ * Akin to Object.defineProperty.
+ *
+ * The signal will be lazily created when accessed and scoped to the
+ * instance of the object.
+ *
+ * @internal
+ */
+function defineSignal(obj, key, v) {
+  Object.defineProperty(obj, key, createSignalDescriptor(key, v));
+}
+
+/**
+ * Define a non-enumerable signal property.
+ *
+ * @internal
+ */
+function defineNonEnumerableSignal(obj, key, v) {
+  const desc = createSignalDescriptor(key, v);
+  desc.enumerable = false;
+  Object.defineProperty(obj, key, desc);
+}
+function memoized(target, key, descriptor) {
+  // Error on `@memoized()`, `@memoized(...args)`, and `@memoized propName = value;`
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error('You attempted to use @memoized(), which is not necessary nor supported. Remove the parentheses and you will be good to go!');
+    }
+  })(target !== undefined) : {};
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`You attempted to use @memoized on with ${arguments.length > 1 ? 'arguments' : 'an argument'} ( @memoized(${Array.from(arguments).map(d => `'${d}'`).join(', ')}), which is not supported. Dependencies are automatically tracked, so you can just use ${'`@memoized`'}`);
+    }
+  })(typeof target === 'object' && typeof key === 'string' && typeof descriptor === 'object' && arguments.length === 3) : {};
+  macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`The @memoized decorator must be applied to getters. '${key}' is not a getter.`);
+    }
+  })(typeof descriptor.get === 'function') : {};
+
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const getter = descriptor.get;
+  descriptor.get = function () {
+    const signals = withSignalStore(this);
+    let memoSignal = signals.get(key);
+    if (!memoSignal) {
+      memoSignal = createMemo(this, key, getter.bind(this));
+      signals.set(key, memoSignal);
+    }
+    return memoSignal();
+  };
+  return descriptor;
+}
+function gate(_target, key, desc) {
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const getter = desc.get;
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const setter = desc.set;
+  desc.get = function () {
+    const signals = withSignalStore(this);
+    let signal = peekInternalSignal(signals, key);
+    if (!signal) {
+      signal = createInternalSignal(signals, this, key, getter.call(this));
+    } else if (signal.isStale) {
+      signal.isStale = false;
+      signal.value = getter.call(this);
+    }
+    consumeInternalSignal(signal);
+    return signal.value;
+  };
+  if (setter) {
+    desc.set = function (v) {
+      const signals = withSignalStore(this);
+      let signal = peekInternalSignal(signals, key);
+      if (!signal) {
+        // we can't use `v` as initialValue here because setters don't
+        // return the value and the final value may be different
+        // than what the setter was called with.
+        signal = createInternalSignal(signals, this, key, undefined);
+        signal.isStale = true;
+      }
+      setter.call(this, v);
+      // when a gate is set, we do not notify the signal
+      // as its update is controlled externally.
+    };
+  }
+  return desc;
+}
+function defineGate(obj, key, desc) {
+  const options = Object.assign({
+    enumerable: true,
+    configurable: false
+  }, gate(obj, key, desc));
+  Object.defineProperty(obj, key, options);
+}
+
 /**
  * @module @ember-data-mirror/store
  */
+
 function urlFromLink(link) {
   if (typeof link === 'string') return link;
   return link.href;
@@ -981,6 +1216,7 @@ class ReactiveDocument {
     this._store = store;
     this._localCache = localCache;
     this.identifier = identifier;
+    const signals = withSignalStore(this);
 
     // TODO if we ever enable auto-cleanup of the cache, we will need to tear this down
     // in a destroy method
@@ -990,10 +1226,10 @@ class ReactiveDocument {
           case 'updated':
             // FIXME in the case of a collection we need to notify it's length
             // and have it recalc
-            notifySignal(this, 'data');
-            notifySignal(this, 'links');
-            notifySignal(this, 'meta');
-            notifySignal(this, 'errors');
+            notifyInternalSignal(peekInternalSignal(signals, 'data'));
+            notifyInternalSignal(peekInternalSignal(signals, 'links'));
+            notifyInternalSignal(peekInternalSignal(signals, 'meta'));
+            notifyInternalSignal(peekInternalSignal(signals, 'errors'));
             break;
         }
       });
@@ -1120,7 +1356,7 @@ class ReactiveDocument {
     return data;
   }
 }
-defineSubscription(ReactiveDocument.prototype, 'errors', {
+defineGate(ReactiveDocument.prototype, 'errors', {
   get() {
     const {
       identifier
@@ -1143,7 +1379,7 @@ defineSubscription(ReactiveDocument.prototype, 'errors', {
     return 'errors' in doc ? doc.errors : undefined;
   }
 });
-defineSubscription(ReactiveDocument.prototype, 'data', {
+defineGate(ReactiveDocument.prototype, 'data', {
   get() {
     const {
       identifier,
@@ -1170,7 +1406,7 @@ defineSubscription(ReactiveDocument.prototype, 'data', {
     }
   }
 });
-defineSubscription(ReactiveDocument.prototype, 'links', {
+defineGate(ReactiveDocument.prototype, 'links', {
   get() {
     const {
       identifier
@@ -1187,7 +1423,7 @@ defineSubscription(ReactiveDocument.prototype, 'links', {
     return data.links;
   }
 });
-defineSubscription(ReactiveDocument.prototype, 'meta', {
+defineGate(ReactiveDocument.prototype, 'meta', {
   get() {
     const {
       identifier
@@ -1209,6 +1445,10 @@ defineSubscription(ReactiveDocument.prototype, 'meta', {
   @module @ember-data-mirror/store
 */
 
+/**
+  @module @ember-data-mirror/store
+*/
+
 /**
    A `RecordReference` is a low-level API that allows users and
    addon authors to perform meta-operations on a record.
@@ -2624,10 +2864,6 @@ class CacheManager {
 function isCacheOperationValue(value) {
   return value === 'added' || value === 'state' || value === 'updated' || value === 'removed' || value === 'invalidated';
 }
-function runLoopIsFlushing() {
-  //@ts-expect-error
-  return !!_backburner.currentInstance && _backburner._autorun !== true;
-}
 function count(label) {
   // @ts-expect-error
   // eslint-disable-next-line
@@ -2823,11 +3059,11 @@ class NotificationManager {
   _scheduleNotify() {
     const asyncFlush = this.store._enableAsyncFlush;
     if (this._hasFlush) {
-      if (asyncFlush !== false && !runLoopIsFlushing()) {
+      if (asyncFlush !== false && !willSyncFlushWatchers()) {
         return false;
       }
     }
-    if (asyncFlush && !runLoopIsFlushing()) {
+    if (asyncFlush && !willSyncFlushWatchers()) {
       this._hasFlush = true;
       return false;
     }
@@ -2890,24 +3126,11 @@ class NotificationManager {
 */
 
 const NativeProxy = Proxy;
-function decorateMethodV2(prototype, prop, decorators) {
-  const origDesc = Object.getOwnPropertyDescriptor(prototype, prop);
-  let desc = {
-    ...origDesc
-  };
-  for (let decorator of decorators) {
-    desc = decorator(prototype, prop, desc) || desc;
-  }
-  if (desc.initializer !== void 0) {
-    desc.value = desc.initializer ? desc.initializer.call(prototype) : void 0;
-    desc.initializer = void 0;
-  }
-  Object.defineProperty(prototype, prop, desc);
-}
 
 /**
   @module @ember-data-mirror/store
 */
+
 const ARRAY_GETTER_METHODS = new Set([Symbol.iterator, 'concat', 'entries', 'every', 'fill', 'filter', 'find', 'findIndex', 'flat', 'flatMap', 'forEach', 'includes', 'indexOf', 'join', 'keys', 'lastIndexOf', 'map', 'reduce', 'reduceRight', 'slice', 'some', 'values']);
 const ARRAY_SETTER_METHODS = new Set(['push', 'pop', 'unshift', 'shift', 'splice', 'sort']);
 const SYNC_PROPS = new Set(['[]', 'length', 'links', 'meta']);
@@ -2920,14 +3143,9 @@ function isArraySetter(prop) {
 function isSelfProp(self, prop) {
   return prop in self;
 }
-const ARRAY_SIGNAL = getOrSetGlobal('#signal', Symbol('#signal'));
 const SOURCE = getOrSetGlobal('#source', Symbol('#source'));
 const MUTATE = getOrSetGlobal('#update', Symbol('#update'));
-const NOTIFY = getOrSetGlobal('#notify', Symbol('#notify'));
 const IS_COLLECTION = getOrSetGlobal('IS_COLLECTION', Symbol.for('Collection'));
-function notifyArray(arr) {
-  addToTransaction(arr[ARRAY_SIGNAL]);
-}
 function convertToInt(prop) {
   if (typeof prop === 'symbol') return null;
   const num = Number(prop);
@@ -2991,11 +3209,6 @@ class IdentifierArray {
   isDestroyed = false;
   _updatingPromise = null;
   identifier;
-  [IS_COLLECTION] = true;
-  [SOURCE];
-  [NOTIFY]() {
-    notifyArray(this);
-  }
 
   /**
     The store that created this record array.
@@ -3009,20 +3222,9 @@ class IdentifierArray {
     // changing the reference breaks the Proxy
     // this[SOURCE] = [];
     this[SOURCE].length = 0;
-    this[NOTIFY]();
+    notifyInternalSignal(this[ARRAY_SIGNAL]);
     this.isDestroyed = !clear;
   }
-
-  // length must be on self for proxied methods to work properly
-  get length() {
-    return this[SOURCE].length;
-  }
-  static {
-    decorateMethodV2(this.prototype, "length", [compat]);
-  }
-  set length(value) {
-    this[SOURCE].length = value;
-  }
   constructor(options) {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const self = this;
@@ -3031,10 +3233,13 @@ class IdentifierArray {
     this._manager = options.manager;
     this.identifier = options.identifier || null;
     this[SOURCE] = options.identifiers;
-    this[ARRAY_SIGNAL] = createSignal(this, 'length');
+    this[IS_COLLECTION] = true;
+
+    // we attach the signal storage to the class
+    // so that its easier to find debugging.
+    const signals = withSignalStore(this);
     const store = options.store;
     const boundFns = new Map();
-    const _SIGNAL = this[ARRAY_SIGNAL];
     const PrivateState = {
       links: options.links || null,
       meta: options.meta || null
@@ -3044,31 +3249,36 @@ class IdentifierArray {
     // when a mutation occurs
     // we track all mutations within the call
     // and forward them as one
-
+    let _SIGNAL = null;
     const proxy = new NativeProxy(this[SOURCE], {
       get(target, prop, receiver) {
         const index = convertToInt(prop);
-        if (_SIGNAL.shouldReset && (index !== null || SYNC_PROPS.has(prop) || isArrayGetter(prop))) {
+        if (_SIGNAL.isStale && (index !== null || SYNC_PROPS.has(prop) || isArrayGetter(prop))) {
           options.manager._syncArray(receiver);
-          _SIGNAL.t = false;
-          _SIGNAL.shouldReset = false;
+          _SIGNAL.isStale = false;
         }
         if (index !== null) {
           const identifier = target[index];
           if (!transaction) {
-            subscribe(_SIGNAL);
+            consumeInternalSignal(_SIGNAL);
           }
           return identifier && store._instanceCache.getRecord(identifier);
         }
-        if (prop === 'meta') return subscribe(_SIGNAL), PrivateState.meta;
-        if (prop === 'links') return subscribe(_SIGNAL), PrivateState.links;
-        if (prop === '[]') return subscribe(_SIGNAL), receiver;
+        if (prop === ARRAY_SIGNAL) {
+          return _SIGNAL;
+        }
+        if (prop === 'length') {
+          return consumeInternalSignal(_SIGNAL), target.length;
+        }
+        if (prop === 'meta') return consumeInternalSignal(_SIGNAL), PrivateState.meta;
+        if (prop === 'links') return consumeInternalSignal(_SIGNAL), PrivateState.links;
+        if (prop === '[]') return consumeInternalSignal(_SIGNAL), receiver;
         if (isArrayGetter(prop)) {
           let fn = boundFns.get(prop);
           if (fn === undefined) {
             if (prop === 'forEach') {
               fn = function () {
-                subscribe(_SIGNAL);
+                consumeInternalSignal(_SIGNAL);
                 transaction = true;
                 const result = safeForEach(receiver, target, store, arguments[0], arguments[1]);
                 transaction = false;
@@ -3076,7 +3286,7 @@ class IdentifierArray {
               };
             } else {
               fn = function () {
-                subscribe(_SIGNAL);
+                consumeInternalSignal(_SIGNAL);
                 // array functions must run through Reflect to work properly
                 // binding via other means will not work.
                 transaction = true;
@@ -3119,7 +3329,7 @@ class IdentifierArray {
           return fn;
         }
         if (isSelfProp(self, prop)) {
-          if (prop === NOTIFY || prop === ARRAY_SIGNAL || prop === SOURCE) {
+          if (prop === SOURCE) {
             return self[prop];
           }
           let fn = boundFns.get(prop);
@@ -3127,7 +3337,7 @@ class IdentifierArray {
           const outcome = self[prop];
           if (typeof outcome === 'function') {
             fn = function () {
-              subscribe(_SIGNAL);
+              consumeInternalSignal(_SIGNAL);
               // array functions must run through Reflect to work properly
               // binding via other means will not work.
               return Reflect.apply(outcome, receiver, arguments);
@@ -3135,7 +3345,7 @@ class IdentifierArray {
             boundFns.set(prop, fn);
             return fn;
           }
-          return subscribe(_SIGNAL), outcome;
+          return consumeInternalSignal(_SIGNAL), outcome;
         }
         return target[prop];
       },
@@ -3253,8 +3463,10 @@ class IdentifierArray {
         }
       });
     }
-    createArrayTags(proxy, _SIGNAL);
-    this[NOTIFY] = this[NOTIFY].bind(proxy);
+
+    // we entangle the signal on the returned proxy since that is
+    // the object that other code will be interfacing with.
+    _SIGNAL = entangleSignal(signals, proxy, ARRAY_SIGNAL, undefined);
     return proxy;
   }
 
@@ -3345,7 +3557,7 @@ const desc = {
     }
   }
 };
-compat(desc);
+// compat(desc);
 Object.defineProperty(IdentifierArray.prototype, '[]', desc);
 defineSignal(IdentifierArray.prototype, 'isUpdating', false);
 class Collection extends IdentifierArray {
@@ -3418,6 +3630,7 @@ function extractIdentifierFromRecord$2(record) {
 /**
   @module @ember-data-mirror/store
 */
+
 const FAKE_ARR = getOrSetGlobal('FAKE_ARR', {});
 const SLICE_BATCH_SIZE = 1200;
 /**
@@ -3519,9 +3732,11 @@ class RecordArrayManager {
 
     // then pull new state if required
     if (isRequestArray) {
-      const tag = array[ARRAY_SIGNAL];
-      if (tag.reason === 'cache-sync') {
-        tag.reason = null;
+      const signal = array[ARRAY_SIGNAL];
+
+      // we only need to rebuild the array from cache if a full sync is required
+      // due to notification that the cache has changed
+      if (signal.value === 'cache-sync') {
         const doc = this.store.cache.peek(array.identifier);
         macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
           if (!test) {
@@ -3604,15 +3819,13 @@ class RecordArrayManager {
     if (array === FAKE_ARR) {
       return;
     }
-    const tag = array[ARRAY_SIGNAL];
-    if (shouldSyncFromCache) {
-      tag.reason = 'cache-sync';
-    }
-    if (!tag.shouldReset) {
-      tag.shouldReset = true;
-      addTransactionCB(array[NOTIFY]);
-    } else if (delta > 0 && !tag.t) {
-      addTransactionCB(array[NOTIFY]);
+    const signal = array[ARRAY_SIGNAL];
+    if (!signal.isStale || delta > 0) {
+      notifyInternalSignal(signal);
+
+      // when the cache has updated for our array, we need to
+      // do a full rebuild of the array
+      signal.value = shouldSyncFromCache ? 'cache-sync' : 'patch';
     }
   }
   _getPendingFor(identifier, includeManaged, isRemove) {
@@ -3676,7 +3889,7 @@ class RecordArrayManager {
     fastPush(source, identifiers);
     this._set.set(array, new Set(identifiers));
     if (!isCollection(array)) {
-      notifyArray(array);
+      notifyInternalSignal(array[ARRAY_SIGNAL]);
       array.meta = payload?.meta || null;
       array.links = payload?.links || null;
     }
@@ -3979,7 +4192,7 @@ class RequestStateService {
    * @method subscribeForRecord
    * @public
    * @param {StableRecordIdentifier} identifier
-   * @param {(state: RequestState) => void} callback
+   * @param {(state: RequestCacheRequestState) => void} callback
    */
   subscribeForRecord(identifier, callback) {
     let subscriptions = this._subscriptions.get(identifier);
@@ -3996,7 +4209,7 @@ class RequestStateService {
    * @method getPendingRequestsForRecord
    * @public
    * @param {StableRecordIdentifier} identifier
-   * @return {RequestState[]} an array of request states for any pending requests for the given identifier
+   * @return {RequestCacheRequestState[]} an array of request states for any pending requests for the given identifier
    */
   getPendingRequestsForRecord(identifier) {
     return this._pending.get(identifier) || EMPTY_ARR;
@@ -4008,7 +4221,7 @@ class RequestStateService {
    * @method getLastRequestForRecord
    * @public
    * @param {StableRecordIdentifier} identifier
-   * @return {RequestState | null} the state of the most recent request for the given identifier
+   * @return {RequestCacheRequestState | null} the state of the most recent request for the given identifier
    */
   getLastRequestForRecord(identifier) {
     const requests = this._done.get(identifier);
@@ -6748,9 +6961,7 @@ class RelatedCollection extends IdentifierArray {
     }
   }
   notify() {
-    const signal = this[ARRAY_SIGNAL];
-    signal.shouldReset = true;
-    notifyArray(this);
+    notifyInternalSignal(this[ARRAY_SIGNAL]);
   }
 
   /**
@@ -6916,6 +7127,573 @@ function mutate(collection, mutation, _SIGNAL) {
     }
   })(typeof collection._manager.mutate === 'function') : {};
   collection._manager.mutate(mutation);
-  addToTransaction(_SIGNAL);
+  notifyInternalSignal(_SIGNAL);
+}
+const PromiseCache = new WeakMap();
+
+/**
+ * The state of a promise in the "pending"
+ * state. This is the default initial state.
+ *
+ * @typedoc
+ */
+
+/**
+ * The state of a promise in the "fulfilled" state.
+ * This is the state of a promise that has resolved
+ * successfully.
+ *
+ * @typedoc
+ */
+
+/**
+ * The state of a promise in the "rejected" state.
+ * This is the state of a promise that has rejected
+ * with an error.
+ *
+ * @typedoc
+ */
+
+/**
+ * The state of a promise. This is the type that is returned
+ * from `getPromiseState`.
+ *
+ * See also:
+ * - {@link PendingPromise}
+ * - {@link ResolvedPromise}
+ * - {@link RejectedPromise}
+ *
+ * @typedoc
+ */
+
+const PromiseStateProto = {};
+
+// TODO introduce a new mechanism for defining multiple properties
+// that share a common signal
+defineSignal(PromiseStateProto, 'reason', null);
+defineSignal(PromiseStateProto, 'value', null);
+defineSignal(PromiseStateProto, 'result', null);
+defineSignal(PromiseStateProto, 'error', null);
+defineSignal(PromiseStateProto, 'status', 'pending');
+defineSignal(PromiseStateProto, 'isPending', true);
+defineSignal(PromiseStateProto, 'isLoading', true);
+defineSignal(PromiseStateProto, 'isSuccess', false);
+defineSignal(PromiseStateProto, 'isError', false);
+function createPromiseState(promise) {
+  const state = getPromiseResult(promise);
+  const promiseState = Object.create(PromiseStateProto);
+  if (state) {
+    if (state.isError) {
+      promiseState.error = state.result;
+      promiseState.reason = state.result;
+      promiseState.status = 'rejected';
+      promiseState.isError = true;
+      promiseState.isPending = false;
+      promiseState.isLoading = false;
+    } else {
+      promiseState.result = state.result;
+      promiseState.value = state.result;
+      promiseState.status = 'fulfilled';
+      promiseState.isSuccess = true;
+      promiseState.isPending = false;
+      promiseState.isLoading = false;
+    }
+  } else {
+    void promise.then(result => {
+      setPromiseResult(promise, {
+        isError: false,
+        result
+      });
+      promiseState.result = result;
+      promiseState.value = result;
+      promiseState.status = 'fulfilled';
+      promiseState.isSuccess = true;
+      promiseState.isPending = false;
+      promiseState.isLoading = false;
+    }, error => {
+      setPromiseResult(promise, {
+        isError: true,
+        result: error
+      });
+      promiseState.error = error;
+      promiseState.reason = error;
+      promiseState.status = 'rejected';
+      promiseState.isError = true;
+      promiseState.isPending = false;
+      promiseState.isLoading = false;
+    });
+  }
+  return promiseState;
+}
+const LegacyPromiseProxy = Symbol.for('LegacyPromiseProxy');
+function isLegacyAwaitable(promise) {
+  return LegacyPromiseProxy in promise && 'promise' in promise && promise[LegacyPromiseProxy] === true;
+}
+function getPromise(promise) {
+  return isLegacyAwaitable(promise) ? promise.promise : promise;
+}
+
+/**
+ * Returns a reactive state-machine for the provided promise or awaitable.
+ *
+ * Repeat calls to `getPromiseState` with the same promise will return the same state object
+ * making is safe and easy to use in templates and JavaScript code to produce reactive
+ * behaviors around promises.
+ *
+ * `getPromiseState` can be used in both JavaScript and Template contexts.
+ *
+ * ```ts
+ * import { getPromiseState } from '@warp-drive-mirror/ember';
+ *
+ * const state = getPromiseState(promise);
+ * ```
+ *
+ * For instance, we could write a getter on a component that updates whenever
+ * the promise state advances or the promise changes, by combining the function
+ * with the use of `@cached`
+ *
+ * ```ts
+ * class Component {
+ *   @cached
+ *   get title() {
+ *     const state = getPromiseState(this.args.request);
+ *     if (state.isPending) {
+ *       return 'loading...';
+ *     }
+ *     if (state.isError) { return null; }
+ *     return state.result.title;
+ *   }
+ * }
+ * ```
+ *
+ * Or in a template as a helper:
+ *
+ * ```gjs
+ * import { getPromiseState } from '@warp-drive-mirror/ember';
+ *
+ * <template>
+ *   {{#let (getPromiseState @request) as |state|}}
+ *     {{#if state.isPending}} <Spinner />
+ *     {{else if state.isError}} <ErrorForm @error={{state.error}} />
+ *     {{else}}
+ *       <h1>{{state.result.title}}</h1>
+ *     {{/if}}
+ *   {{/let}}
+ * </template>
+ * ```
+ *
+ * If looking to use in a template, consider also the `<Await />` component.
+ *
+ * @typedoc
+ */
+function getPromiseState(promise) {
+  const _promise = getPromise(promise);
+  let state = PromiseCache.get(_promise);
+  if (!state) {
+    state = createPromiseState(_promise);
+    PromiseCache.set(_promise, state);
+  }
+  return state;
+}
+const RequestCache = new WeakMap();
+function isAbortError(error) {
+  return error instanceof DOMException && error.name === 'AbortError';
+}
+async function watchStream(stream, state) {
+  const reader = stream.getReader();
+  let bytesLoaded = 0;
+  let shouldForward = state._stream !== null && state._stream.readable.locked;
+  let isForwarding = shouldForward;
+  let writer = state._stream?.writable.getWriter();
+  const buffer = [];
+  state._isPending = false;
+  state._isStarted = true;
+  state._startTime = performance.now();
+  while (true) {
+    const {
+      value,
+      done
+    } = await reader.read();
+    if (done) {
+      break;
+    }
+    bytesLoaded += value.byteLength;
+    state._bytesLoaded = bytesLoaded;
+    state._lastPacketTime = performance.now();
+    shouldForward = shouldForward || state._stream !== null && state._stream.readable.locked;
+    if (shouldForward) {
+      if (!isForwarding) {
+        isForwarding = true;
+        writer = state._stream.writable.getWriter();
+        for (const item of buffer) {
+          await writer.ready;
+          await writer.write(item);
+        }
+        buffer.length = 0;
+      }
+      await writer.ready;
+      await writer.write(value);
+    } else {
+      buffer.push(value);
+    }
+  }
+
+  // if we are still forwarding, we need to close the writer
+  if (isForwarding) {
+    await writer.ready;
+    await writer.close();
+  } else if (state._stream) {
+    // if we are not forwarding, we need to cancel the stream
+    await state._stream.readable.cancel('The Stream Has Already Ended');
+    state._stream = null;
+  }
+  const endTime = performance.now();
+  state._endTime = endTime;
+  state._isComplete = true;
+  state._isStarted = false;
+}
+
+/**
+ * Lazily consumes the stream of a request, providing a number of
+ * reactive properties that can be used to build UIs that respond
+ * to the progress of a request.
+ *
+ * @typedoc
+ */
+class RequestLoadingState {
+  _stream = null;
+  _future;
+  _triggered = false;
+  _trigger() {
+    if (this._triggered) {
+      return;
+    }
+    this._triggered = true;
+    const future = this._future;
+    const promise = future.getStream();
+    if (promise.sizeHint) {
+      this._sizeHint = promise.sizeHint;
+    }
+    this.promise = promise.then(stream => {
+      if (!stream) {
+        this._isPending = false;
+        this._isComplete = true;
+        return;
+      }
+      return watchStream(stream, this);
+    }, error => {
+      this._isPending = false;
+      this._isStarted = false;
+      if (isAbortError(error)) {
+        this._isCancelled = true;
+        this._isComplete = true;
+      }
+      this._isErrored = true;
+      this._error = error;
+    });
+  }
+  promise = null;
+  get isPending() {
+    this._trigger();
+    return this._isPending;
+  }
+  get sizeHint() {
+    this._trigger();
+    return this._sizeHint;
+  }
+  get stream() {
+    this._trigger();
+    if (!this._stream) {
+      if (this._isComplete || this._isCancelled || this._isErrored) {
+        return null;
+      }
+      this._stream = new TransformStream();
+    }
+    return this._stream.readable;
+  }
+  get isStarted() {
+    this._trigger();
+    return this._isStarted;
+  }
+  get bytesLoaded() {
+    this._trigger();
+    return this._bytesLoaded;
+  }
+  get startTime() {
+    this._trigger();
+    return this._startTime;
+  }
+  get endTime() {
+    this._trigger();
+    return this._endTime;
+  }
+  get lastPacketTime() {
+    this._trigger();
+    return this._lastPacketTime;
+  }
+  get isComplete() {
+    this._trigger();
+    return this._isComplete;
+  }
+  get isCancelled() {
+    this._trigger();
+    return this._isCancelled;
+  }
+  get isErrored() {
+    this._trigger();
+    return this._isErrored;
+  }
+  get error() {
+    this._trigger();
+    return this._error;
+  }
+  get elapsedTime() {
+    return (this.endTime || this.lastPacketTime) - this.startTime;
+  }
+  get completedRatio() {
+    return this.sizeHint ? this.bytesLoaded / this.sizeHint : 0;
+  }
+  get remainingRatio() {
+    return 1 - this.completedRatio;
+  }
+  get duration() {
+    return this.endTime - this.startTime;
+  }
+  get speed() {
+    // bytes per second
+    return this.bytesLoaded / (this.elapsedTime / 1000);
+  }
+  constructor(future) {
+    this._future = future;
+  }
+  abort = () => {
+    this._future.abort();
+  };
+}
+defineNonEnumerableSignal(RequestLoadingState.prototype, '_isPending', true);
+defineNonEnumerableSignal(RequestLoadingState.prototype, '_isStarted', false);
+defineNonEnumerableSignal(RequestLoadingState.prototype, '_isComplete', false);
+defineNonEnumerableSignal(RequestLoadingState.prototype, '_isCancelled', false);
+defineNonEnumerableSignal(RequestLoadingState.prototype, '_isErrored', false);
+defineNonEnumerableSignal(RequestLoadingState.prototype, '_error', null);
+defineNonEnumerableSignal(RequestLoadingState.prototype, '_sizeHint', 0);
+defineNonEnumerableSignal(RequestLoadingState.prototype, '_bytesLoaded', 0);
+defineNonEnumerableSignal(RequestLoadingState.prototype, '_startTime', 0);
+defineNonEnumerableSignal(RequestLoadingState.prototype, '_endTime', 0);
+defineNonEnumerableSignal(RequestLoadingState.prototype, '_lastPacketTime', 0);
+
+/**
+ * The state of a request in the "pending"
+ * state. This is the default initial state.
+ *
+ * Extends the {@link PendingPromise} interface.
+ *
+ * @typedoc
+ */
+
+/**
+ * The state of a request in the "fulfilled" state.
+ * This is the state of a request that has resolved
+ * successfully.
+ *
+ * Extends the {@link ResolvedPromise} interface.
+ *
+ * @typedoc
+ */
+
+/**
+ * The state of a request in the "rejected" state.
+ * This is the state of a request that has rejected
+ * with an error.
+ *
+ * Extends the {@link RejectedPromise} interface.
+ *
+ * @typedoc
+ */
+
+/**
+ * The state of a request in the "cancelled" state.
+ * This is the state of a promise that has been
+ * cancelled.
+ *
+ * @typedoc
+ */
+
+/**
+ * RequestState extends the concept of PromiseState to provide a reactive
+ * wrapper for a request `Future` which allows you write declarative code
+ * around a Future's control flow.
+ *
+ * It is useful in both Template and JavaScript contexts, allowing you
+ * to quickly derive behaviors and data from pending, error and success
+ * states.
+ *
+ * The key difference between a Promise and a Future is that Futures provide
+ * access to a stream of their content, the identity of the request (if any)
+ * as well as the ability to attempt to abort the request.
+ *
+ * ```ts
+ * interface Future<T> extends Promise<T>> {
+ *   getStream(): Promise<ReadableStream>;
+ *   abort(): void;
+ *   lid: StableDocumentIdentifier | null;
+ * }
+ * ```
+ *
+ * These additional APIs allow us to craft even richer state experiences.
+ *
+ * To get the state of a request, use `getRequestState`.
+ *
+ * See also:
+ * - {@link PendingRequest}
+ * - {@link ResolvedRequest}
+ * - {@link RejectedRequest}
+ * - {@link CancelledRequest}
+ *
+ * @typedoc
+ */
+
+const RequestStateProto = {};
+
+// TODO introduce a new mechanism for defining multiple properties
+// that share a common signal
+defineSignal(RequestStateProto, 'reason', null);
+defineSignal(RequestStateProto, 'value', null);
+defineSignal(RequestStateProto, 'result', null);
+defineSignal(RequestStateProto, 'error', null);
+defineSignal(RequestStateProto, 'status', 'pending');
+defineSignal(RequestStateProto, 'isPending', true);
+defineSignal(RequestStateProto, 'isLoading', true);
+defineSignal(RequestStateProto, 'isSuccess', false);
+defineSignal(RequestStateProto, 'isError', false);
+defineSignal(RequestStateProto, 'request', null);
+defineSignal(RequestStateProto, 'response', null);
+Object.defineProperty(RequestStateProto, 'isCancelled', {
+  get() {
+    return this.isError && isAbortError(this.reason);
+  }
+});
+Object.defineProperty(RequestStateProto, 'loadingState', {
+  get() {
+    if (!this._loadingState) {
+      this._loadingState = new RequestLoadingState(this._request);
+    }
+    return this._loadingState;
+  }
+});
+function createRequestState(future) {
+  const state = getPromiseResult(future);
+  const promiseState = Object.create(RequestStateProto);
+  promiseState._request = future;
+  if (state) {
+    if (state.isError) {
+      promiseState.error = state.result;
+      promiseState.reason = state.result;
+      promiseState.status = 'rejected';
+      promiseState.isError = true;
+      promiseState.isPending = false;
+      promiseState.isLoading = false;
+      promiseState.request = state.result.request;
+      promiseState.response = state.result.response;
+    } else {
+      promiseState.result = state.result.content;
+      promiseState.value = state.result.content;
+      promiseState.status = 'fulfilled';
+      promiseState.isSuccess = true;
+      promiseState.isPending = false;
+      promiseState.isLoading = false;
+      promiseState.request = state.result.request;
+      promiseState.response = state.result.response;
+    }
+  } else {
+    void future.then(result => {
+      setPromiseResult(future, {
+        isError: false,
+        result
+      });
+      promiseState.result = result.content;
+      promiseState.value = result.content;
+      promiseState.status = 'fulfilled';
+      promiseState.isSuccess = true;
+      promiseState.isPending = false;
+      promiseState.isLoading = false;
+      promiseState.request = result.request;
+      promiseState.response = result.response;
+    }, error => {
+      setPromiseResult(future, {
+        isError: true,
+        result: error
+      });
+      promiseState.error = error;
+      promiseState.reason = error;
+      promiseState.status = 'rejected';
+      promiseState.isError = true;
+      promiseState.isPending = false;
+      promiseState.isLoading = false;
+      promiseState.request = error.request;
+      promiseState.response = error.response;
+    });
+  }
+  return promiseState;
+}
+
+/**
+ * `getRequestState` can be used in both JavaScript and Template contexts.
+ *
+ * ```ts
+ * import { getRequestState } from '@warp-drive-mirror/ember';
+ *
+ * const state = getRequestState(future);
+ * ```
+ *
+ * For instance, we could write a getter on a component that updates whenever
+ * the request state advances or the future changes, by combining the function
+ * with the use of `@cached`
+ *
+ * ```ts
+ * class Component {
+ *   @cached
+ *   get title() {
+ *     const state = getRequestState(this.args.request);
+ *     if (state.isPending) {
+ *       return 'loading...';
+ *     }
+ *     if (state.isError) { return null; }
+ *     return state.result.title;
+ *   }
+ * }
+ * ```
+ *
+ * Or in a template as a helper:
+ *
+ * ```gjs
+ * import { getRequestState } from '@warp-drive-mirror/ember';
+ *
+ * <template>
+ *   {{#let (getRequestState @request) as |state|}}
+ *     {{#if state.isPending}}
+ *       <Spinner />
+ *     {{else if state.isError}}
+ *       <ErrorForm @error={{state.error}} />
+ *     {{else}}
+ *       <h1>{{state.result.title}}</h1>
+ *     {{/if}}
+ *   {{/let}}
+ * </template>
+ * ```
+ *
+ * If looking to use in a template, consider also the `<Request />` component
+ * which offers a numbe of additional capabilities for requests *beyond* what
+ * `RequestState` provides.
+ *
+ * @typedoc
+ */
+function getRequestState(future) {
+  let state = RequestCache.get(future);
+  if (!state) {
+    state = createRequestState(future);
+    RequestCache.set(future, state);
+  }
+  return state;
 }
-export { ARRAY_SIGNAL as A, CacheHandler as C, IdentifierArray as I, MUTATE as M, RecordArrayManager as R, Store as S, _clearCaches as _, setIdentifierGenerationMethod as a, setIdentifierUpdateMethod as b, setIdentifierForgetMethod as c, setIdentifierResetMethod as d, setKeyInfoForResource as e, isDocumentIdentifier as f, constructResource as g, coerceId as h, isStableIdentifier as i, ensureStringId as j, Collection as k, SOURCE as l, fastPush as m, notifyArray as n, removeRecordDataFor as o, peekCache as p, setRecordIdentifier as q, recordIdentifierFor as r, storeFor as s, StoreMap as t, setCacheFor as u, normalizeModelName as v, RelatedCollection as w, log as x, logGroup as y };
+export { memoized as A, gate as B, CacheHandler as C, entangleSignal as D, defineSignal as E, defineNonEnumerableSignal as F, Signals as G, peekInternalSignal as H, IdentifierArray as I, withSignalStore as J, notifyInternalSignal as K, consumeInternalSignal as L, MUTATE as M, getOrCreateInternalSignal as N, RecordArrayManager as R, Store as S, _clearCaches as _, setIdentifierGenerationMethod as a, setIdentifierUpdateMethod as b, setIdentifierForgetMethod as c, setIdentifierResetMethod as d, setKeyInfoForResource as e, isDocumentIdentifier as f, constructResource as g, coerceId as h, isStableIdentifier as i, ensureStringId as j, Collection as k, SOURCE as l, fastPush as m, removeRecordDataFor as n, setRecordIdentifier as o, peekCache as p, StoreMap as q, recordIdentifierFor as r, storeFor as s, setCacheFor as t, normalizeModelName as u, RelatedCollection as v, log as w, logGroup as x, getPromiseState as y, getRequestState as z };