@warp-drive/core 5.9.0-alpha.17 → 5.9.0-alpha.19

package/dist/unpkg/prod/{schema-BdC3DirM.js → index-C-AhVafS.js}

@@ -1,11 +1,13 @@
-import { d as defineGate, a as withSignalStore, n as notifyInternalSignal, p as peekInternalSignal, g as getOrCreateInternalSignal, c as consumeInternalSignal, b as createInternalSignal, A as ARRAY_SIGNAL, S as Signals, e as createSignalDescriptor, f as defineSignal, h as entangleSignal, i as entangleInitiallyStaleSignal, O as OBJECT_SIGNAL, j as createInternalMemo } from "./-leaked-BHLmJyaw.js";
-import { EnableHydration, STRUCTURED } from './types/request.js';
 import { D as Destroy, C as Context, S as SOURCE, a as Checkout, b as Commit } from "./-private-sql1_mdx.js";
-import { isResourceSchema } from './types/schema/fields.js';
-import { setTransient, peekTransient, getOrSetGlobal } from './types/-private.js';
-import './types/runtime.js';
-import { w as withBrand } from "./request-BrJSCG6r.js";
+import { d as defineGate, w as withSignalStore, n as notifyInternalSignal, p as peekInternalSignal, a as willSyncFlushWatchers, g as getOrCreateInternalSignal, c as consumeInternalSignal, b as createInternalSignal, A as ARRAY_SIGNAL, S as Signals, e as createSignalDescriptor, f as defineSignal, h as entangleSignal, i as entangleInitiallyStaleSignal, O as OBJECT_SIGNAL, j as createInternalMemo } from "./-leaked-DgjQ5X55.js";
+import { setTransient, peekTransient, getOrSetGlobal, peekUniversalTransient, setUniversalTransient } from './types/-private.js';
+import { EnableHydration, SkipCache, STRUCTURED } from './types/request.js';
+import { setIsMaybeMirage } from './types/runtime.js';
+import { w as withBrand, c as cloneResponseProperties, I as IS_CACHE_HANDLER, e as executeNextHandler, u as upgradePromise } from "./request-eb7Zm-oS.js";
+import { b as getRequestResult, a as setPromiseResult, c as clearRequestResult } from "./promise-cache-DUblkX-U.js";
+import { DefaultCachePolicy } from './store.js';
 import { CACHE_OWNER } from './types/identifier.js';
+import { isResourceSchema } from './types/schema/fields.js';
 import { RecordStore, Type } from './types/symbols.js';
 function urlFromLink(link) {
   if (typeof link === 'string') return link;
@@ -1211,6 +1213,212 @@ function unloadRecord(instances, identifier) {
   }
   instances.store._requestCache._clearEntries(identifier);
 }
+function isCacheOperationValue(value) {
+  return value === 'added' || value === 'state' || value === 'updated' || value === 'removed' || value === 'invalidated';
+}
+function _unsubscribe(token, cache) {
+  const cacheKey = token.for;
+  if (cacheKey) {
+    const callbacks = cache.get(cacheKey);
+    if (!callbacks) {
+      return;
+    }
+    const index = callbacks.indexOf(token);
+    if (index === -1) {
+      return;
+    }
+    callbacks.splice(index, 1);
+  }
+}
+
+/**
+ * The NotificationManager provides the ability to subscribe to
+ * changes to Cache state.
+ *
+ * This Feature is what allows WarpDrive to create subscriptions that
+ * work with any framework or change-notification system.
+ *
+ * @hideconstructor
+ * @public
+ */
+class NotificationManager {
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  constructor(store) {
+    this.store = store;
+    this.isDestroyed = false;
+    this._buffered = new Map();
+    this._hasFlush = false;
+    this._cache = new Map();
+  }
+
+  /**
+   * Subscribe to changes for a given ResourceKey, RequestKey, or addition/removal of any resource
+   * or document.
+   *
+   * ```ts
+   * export type CacheOperation = 'added' | 'removed' | 'updated' | 'state';
+   *
+   * export interface NotificationCallback {
+   *   (cacheKey: ResourceKey, notificationType: 'attributes' | 'relationships', key?: string): void;
+   *   (cacheKey: ResourceKey, notificationType: 'errors' | 'meta' | 'identity' | 'state'): void;
+   *   (cacheKey: ResourceKey, notificationType: NotificationType, key?: string): void;
+   * }
+   * export interface ResourceOperationCallback {
+   *   // resource updates
+   *   (cacheKey: ResourceKey, notificationType: CacheOperation): void;
+   * }
+   * export interface DocumentOperationCallback {
+   *   // document updates
+   *   (cacheKey: RequestKey, notificationType: CacheOperation): void;
+   * }
+   * ```
+   *
+   * @public
+   * @return an opaque token to be used with unsubscribe
+   */
+
+  subscribe(cacheKey, callback) {
+    let callbacks = this._cache.get(cacheKey);
+    // we use the callback as the cancellation token
+    //@ts-expect-error
+    callback.for = cacheKey;
+    if (!callbacks) {
+      callbacks = [];
+      this._cache.set(cacheKey, callbacks);
+    }
+    callbacks.push(callback);
+    return callback;
+  }
+
+  /**
+   * remove a previous subscription
+   *
+   * @public
+   */
+  unsubscribe(token) {
+    if (!this.isDestroyed) {
+      _unsubscribe(token, this._cache);
+    }
+  }
+
+  /**
+   * Custom Caches and Application Code should not call this method directly.
+   *
+   * @private
+   */
+
+  notify(cacheKey, value, key) {
+    if (this.isDestroyed) {
+      return false;
+    }
+    if (!isResourceKey(cacheKey) && !isRequestKey(cacheKey)) {
+      return false;
+    }
+    const _hasSubscribers = hasSubscribers(this._cache, cacheKey, value);
+    if (_hasSubscribers) {
+      let buffer = this._buffered.get(cacheKey);
+      if (!buffer) {
+        buffer = [];
+        this._buffered.set(cacheKey, buffer);
+      }
+      buffer.push([value, key || null]);
+      if (!this._scheduleNotify()) ;
+    }
+    return _hasSubscribers;
+  }
+
+  /** @internal */
+  _onNextFlush(cb) {
+    this._onFlushCB = cb;
+  }
+
+  /** @internal */
+  _scheduleNotify() {
+    const asyncFlush = this.store._enableAsyncFlush;
+    if (this._hasFlush) {
+      if (asyncFlush !== false && !willSyncFlushWatchers()) {
+        return false;
+      }
+    }
+    if (asyncFlush && !willSyncFlushWatchers()) {
+      this._hasFlush = true;
+      return false;
+    }
+    this._flush();
+    return true;
+  }
+
+  /** @internal */
+  _flush() {
+    const buffered = this._buffered;
+    if (buffered.size) {
+      this._buffered = new Map();
+      for (const [cacheKey, states] of buffered) {
+        for (let i = 0; i < states.length; i++) {
+          // @ts-expect-error
+          _flushNotification(this._cache, cacheKey, states[i][0], states[i][1]);
+        }
+      }
+    }
+    this._hasFlush = false;
+    this._onFlushCB?.();
+    this._onFlushCB = undefined;
+  }
+
+  /** @internal */
+  destroy() {
+    this.isDestroyed = true;
+    this._cache.clear();
+  }
+}
+
+/**
+ * This type exists for internal use only for
+ * where intimate contracts still exist either for
+ * the Test Suite or for Legacy code.
+ *
+ * @private
+ */
+
+function _flushNotification(cache, cacheKey, value, key) {
+  // TODO for documents this will need to switch based on Identifier kind
+  if (isCacheOperationValue(value)) {
+    const callbackMap = cache.get(isRequestKey(cacheKey) ? 'document' : 'resource');
+    if (callbackMap) {
+      callbackMap.forEach(cb => {
+        cb(cacheKey, value);
+      });
+    }
+  }
+  const callbacks = cache.get(cacheKey);
+  if (!callbacks || !callbacks.length) {
+    return false;
+  }
+  callbacks.forEach(cb => {
+    // @ts-expect-error overload doesn't narrow within body
+    cb(cacheKey, value, key);
+  });
+  return true;
+}
+function hasSubscribers(cache, cacheKey, value) {
+  const hasSubscriber = Boolean(cache.get(cacheKey)?.length);
+  if (hasSubscriber || !isCacheOperationValue(value)) {
+    return hasSubscriber;
+  }
+  const callbackMap = cache.get(isRequestKey(cacheKey) ? 'document' : 'resource');
+  return Boolean(callbackMap?.length);
+}
 function update() {
   if (this.isUpdating) {
     return this._updatingPromise;
@@ -1578,7 +1786,7 @@ const ArrayHandler = {
       return false;
     }
     const original = target[index];
-    const newIdentifier = extractIdentifierFromRecord$1(value);
+    const newIdentifier = extractIdentifierFromRecord$2(value);
     // We generate "transactions" whenever a setter method on the array
     // is called and might bulk update multiple array cells. Fundamentally,
     // all array operations decompose into individual cell replacements.
@@ -1649,7 +1857,7 @@ function createReactiveResourceArray(options) {
 // Ensure instanceof works correctly
 // Object.setPrototypeOf(IdentifierArray.prototype, Array.prototype);
 
-function extractIdentifierFromRecord$1(record) {
+function extractIdentifierFromRecord$2(record) {
   if (!record) {
     return null;
   }
@@ -2447,93 +2655,1169 @@ function isLegacyLiveArray(array) {
   const context = array[Context];
   return context.features !== null && context.features.DEPRECATED_CLASS_NAME === 'LiveArray';
 }
+const Touching = getOrSetGlobal('Touching', Symbol('touching'));
+const RequestPromise = getOrSetGlobal('RequestPromise', Symbol('promise'));
+const EMPTY_ARR = [];
+function hasRecordIdentifier(op) {
+  return 'recordIdentifier' in op;
+}
 
 /**
-   A `RecordReference` is a low-level API that allows users and
-   addon authors to perform meta-operations on a record.
-
-   @hideconstructor
-   @public
-*/
-class RecordReference {
+ * The RequestStateService is used to track the state of requests
+ * for fetching or updating known resource identifies that are inflight.
+ *
+ * @hideconstructor
+ * @public
+ */
+class RequestStateService {
   /** @internal */
-
-  // unsubscribe token given to us by the notification manager
+  _pending = new Map();
   /** @internal */
-  ___token;
+  _done = new Map();
   /** @internal */
-  ___identifier;
+  _subscriptions = new Map();
+  /** @internal */
+  _toFlush = [];
+  /** @internal */
+  _store;
+  constructor(store) {
+    this._store = store;
+  }
+  /** @internal */
+  _clearEntries(identifier) {
+    this._done.delete(identifier);
+  }
+  /** @internal */
+  _enqueue(promise, queryRequest) {
+    const query = queryRequest.data[0];
+    if (hasRecordIdentifier(query)) {
+      const identifier = query.recordIdentifier;
+      const type = query.op === 'saveRecord' ? 'mutation' : 'query';
+      if (!this._pending.has(identifier)) {
+        this._pending.set(identifier, []);
+      }
+      const request = {
+        state: 'pending',
+        request: queryRequest,
+        type
+      };
+      request[Touching] = [query.recordIdentifier];
+      request[RequestPromise] = promise;
+      this._pending.get(identifier).push(request);
+      this._triggerSubscriptions(request);
+      return promise.then(result => {
+        this._dequeue(identifier, request);
+        const finalizedRequest = {
+          state: 'fulfilled',
+          request: queryRequest,
+          type,
+          response: {
+            data: result
+          }
+        };
+        finalizedRequest[Touching] = request[Touching];
+        this._addDone(finalizedRequest);
+        this._triggerSubscriptions(finalizedRequest);
+        return result;
+      }, error => {
+        this._dequeue(identifier, request);
+        const finalizedRequest = {
+          state: 'rejected',
+          request: queryRequest,
+          type,
+          response: {
+            data: error
+          }
+        };
+        finalizedRequest[Touching] = request[Touching];
+        this._addDone(finalizedRequest);
+        this._triggerSubscriptions(finalizedRequest);
+        throw error;
+      });
+    }
+  }
+
+  /** @internal */
+  _triggerSubscriptions(req) {
+    if (req.state === 'pending') {
+      this._flushRequest(req);
+      return;
+    }
+    this._toFlush.push(req);
+    if (this._toFlush.length === 1) {
+      this._store.notifications._onNextFlush(() => {
+        this._flush();
+      });
+    }
+  }
+
   /** @internal */
+  _flush() {
+    this._toFlush.forEach(req => {
+      this._flushRequest(req);
+    });
+    this._toFlush = [];
+  }
 
-  constructor(store, identifier) {
-    this.store = store;
-    this.___identifier = identifier;
-    this.___token = store.notifications.subscribe(identifier, (_, bucket, notifiedKey) => {
-      if (bucket === 'identity' || bucket === 'attributes' && notifiedKey === 'id') {
-        this._ref++;
+  /** @internal */
+  _flushRequest(req) {
+    req[Touching].forEach(identifier => {
+      const subscriptions = this._subscriptions.get(identifier);
+      if (subscriptions) {
+        subscriptions.forEach(callback => callback(req));
       }
     });
   }
 
   /** @internal */
-  destroy() {
-    this.store.notifications.unsubscribe(this.___token);
+  _dequeue(identifier, request) {
+    const pending = this._pending.get(identifier);
+    this._pending.set(identifier, pending.filter(req => req !== request));
   }
-  get type() {
-    return this.identifier().type;
+
+  /** @internal */
+  _addDone(request) {
+    request[Touching].forEach(identifier => {
+      // TODO add support for multiple
+      const requestDataOp = request.request.data[0].op;
+      let requests = this._done.get(identifier);
+      if (requests) {
+        requests = requests.filter(req => {
+          // TODO add support for multiple
+          let data;
+          if (Array.isArray(req.request.data)) {
+            data = req.request.data[0];
+          } else {
+            data = req.request.data;
+          }
+          return data.op !== requestDataOp;
+        });
+      }
+      requests = requests || [];
+      requests.push(request);
+      this._done.set(identifier, requests);
+    });
   }
 
   /**
-     The `id` of the record that this reference refers to.
-      Together, the `type` and `id` properties form a composite key for
-     the identity map.
-      Example
-      ```javascript
-     let userRef = store.getReference('user', 1);
-      userRef.id(); // '1'
-     ```
-     @public
-    @return The id of the record.
-  */
-  id() {
-    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
-    this._ref; // consume the tracked prop
-    return this.___identifier.id;
+   * Subscribe to requests for a given resource identity.
+   *
+   * The callback will receive the current state of the request.
+   *
+   * ```ts
+   * interface RequestState {
+   *   state: 'pending' | 'fulfilled' | 'rejected';
+   *   type: 'query' | 'mutation';
+   *   request: Request;
+   *   response?: { data: unknown };
+   * }
+   * ```
+   *
+   * Note: It should be considered dangerous to use this API for more than simple
+   * state derivation or debugging. The `request` and `response` properties are poorly
+   * spec'd and may change unexpectedly when shifting what Handlers are in use or how
+   * requests are issued from the Store.
+   *
+   * We expect to revisit this API in the near future as we continue to refine the
+   * RequestManager ergonomics, as a simpler but more powerful direct integration
+   * with the RequestManager for these purposes is likely to be a better long-term
+   * design.
+   *
+   * @public
+   * @param {ResourceKey} identifier
+   * @param {(state: RequestCacheRequestState) => void} callback
+   */
+  subscribeForRecord(identifier, callback) {
+    let subscriptions = this._subscriptions.get(identifier);
+    if (!subscriptions) {
+      subscriptions = [];
+      this._subscriptions.set(identifier, subscriptions);
+    }
+    subscriptions.push(callback);
   }
 
   /**
-     The `identifier` of the record that this reference refers to.
-      Together, the `type` and `id` properties form a composite key for
-     the identity map.
-      Example
-      ```javascript
-     let userRef = store.getReference('user', 1);
-      userRef.identifier(); // '1'
-     ```
-     @public
-    @return The identifier of the record.
-  */
-  identifier() {
-    return this.___identifier;
+   * Retrieve all active requests for a given resource identity.
+   *
+   * @public
+   * @param {ResourceKey} 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;
   }
 
   /**
-     How the reference will be looked up when it is loaded. Currently
-     this always returns `identity` to signify that a record will be
-     loaded by its `type` and `id`.
-      Example
-      ```javascript
-     const userRef = store.getReference('user', 1);
-      userRef.remoteType(); // 'identity'
-     ```
-      @public
-  */
-  remoteType() {
-    return 'identity';
+   * Retrieve the last completed request for a given resource identity.
+   *
+   * @public
+   * @param {ResourceKey} identifier
+   * @return {RequestCacheRequestState | null} the state of the most recent request for the given identifier
+   */
+  getLastRequestForRecord(identifier) {
+    const requests = this._done.get(identifier);
+    if (requests) {
+      return requests[requests.length - 1];
+    }
+    return null;
   }
+}
+
+/**
+ * This type exists for internal use only for
+ * where intimate contracts still exist either for
+ * the Test Suite or for Legacy code.
+ *
+ * @private
+ */
+
+// this import location is deprecated but breaks in 4.8 and older
+
+// `AwaitedKeys` is needed here to resolve any promise types like `PromiseBelongsTo`.
+
+/**
+ * Currently only records that extend object can be created via
+ * store.createRecord. This is a limitation of the current API,
+ * but can be worked around by creating a new identifier, running
+ * the cache.clientDidCreate method, and then peeking the record
+ * for the identifier.
+ *
+ * To assign primary key to a record during creation, only `id` will
+ * work correctly for `store.createRecord`, other primary key may be
+ * handled by updating the record after creation or using the flow
+ * described above.
+ *
+ * TODO: These are limitations we want to (and can) address. If you
+ * have need of lifting these limitations, please open an issue.
+ *
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class
+const EmptyClass = class {
+  // eslint-disable-next-line @typescript-eslint/no-useless-constructor
+  constructor(args) {}
+};
+const _BaseClass = EmptyClass;
+const BaseClass = _BaseClass.default ? _BaseClass.default : _BaseClass;
+/**
+ * ```ts
+ * import { Store } from '@warp-drive/core';
+ * ```
+ *
+ * The `Store` is the central piece of the ***Warp*Drive** experience. It connects
+ * requests for data with schemas, caching and reactivity.
+ *
+ * While it's easy to use ***just*** ***Warp*Drive**'s request management, most projects will find they
+ * require far more than basic fetch management. For this reason it's often best to start with a `Store`
+ * even when you aren't sure yet.
+ *
+ * Most projects will only have a single `Store`, though using multiple distinct stores
+ * is possible.
+ *
+ * @public
+ * @hideconstructor
+ */
+class Store extends BaseClass {
+  /** @internal */
 
   /**
-    This API allows you to provide a reference with new data. The
+   * Provides access to the {@link NotificationManager} associated
+   * with this Store instance.
+   *
+   * The NotificationManager can be used to subscribe to
+   * changes to the cache.
+   *
+   * @public
+   */
+
+  /**
+   * Provides access to the SchemaService instance
+   * for this Store instance.
+   *
+   * The SchemaService can be used to query for
+   * information about the schema of a resource.
+   *
+   * @public
+   */
+  get schema() {
+    if (!this._schema) {
+      this._schema = this.createSchemaService();
+    }
+    return this._schema;
+  }
+  /** @internal */
+
+  /**
+   * Provides access to the CacheKeyManager
+   * for this store.
+   *
+   * The CacheKeyManager can be used to generate or
+   * retrieve a stable unique CacheKey for any resource
+   * or request.
+   *
+   * @public
+   */
+
+  /**
+   * Provides access to the {@link RequestManager} instance associated
+   * with this Store instance.
+   *
+   * See also:
+   * - {@link Fetch}
+   * - {@link CacheHandlerInterface | CacheHandler (Interface)}
+   * - {@link CacheHandler | CacheHandler (Class)}
+   *
+   * ```ts
+   * import { CacheHandler, Fetch, RequestManager, Store } from '@warp-drive/core';
+   *
+   * class AppStore extends Store {
+   *   requestManager = new RequestManager()
+   *    .use([Fetch])
+   *    .useCache(CacheHandler);
+   * }
+   * ```
+   *
+   * @public
+   */
+
+  /**
+   * A Property which an App may set to provide a CachePolicy
+   * to control when a cached request becomes stale.
+   *
+   * Note, when defined, these methods will only be invoked if a
+   * cache key exists for the request, either because the request
+   * contains `cacheOptions.key` or because the {@link CacheKeyManager}
+   * was able to generate a key for the request using the configured
+   * {@link setIdentifierGenerationMethod | generation method}.
+   *
+   * `isSoftExpired` will only be invoked if `isHardExpired` returns `false`.
+   *
+   * ```ts
+   * store.lifetimes = {
+   *   // make the request and ignore the current cache state
+   *   isHardExpired(key: RequestKey): boolean {
+   *     return false;
+   *   }
+   *
+   *   // make the request in the background if true, return cache state
+   *   isSoftExpired(key: RequestKey): boolean {
+   *     return false;
+   *   }
+   * }
+   * ```
+   *
+   * @public
+   */
+
+  // Private
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /**
+   * Async flush buffers notifications until flushed
+   * by finalization of a future configured by store.request
+   *
+   * This is useful for ensuring that notifications are delivered
+   * prior to the promise resolving but without risk of promise
+   * interleaving.
+   *
+   * @internal
+   */
+
+  /**
+   * Available in DEBUG Only
+   * @internal
+   */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @private */
+  get isDestroying() {
+    return this._isDestroying;
+  }
+  /** @internal */
+  set isDestroying(value) {
+    this._isDestroying = value;
+  }
+  /** @private */
+  get isDestroyed() {
+    return this._isDestroyed;
+  }
+  /** @internal */
+  set isDestroyed(value) {
+    this._isDestroyed = value;
+  }
+
+  /** @deprecated use {@link Store.cacheKeyManager} */
+  get identifierCache() {
+    return this.cacheKeyManager;
+  }
+
+  /**
+    @private
+  */
+  constructor(createArgs) {
+    super(createArgs);
+    Object.assign(this, createArgs);
+    this.cacheKeyManager = new CacheKeyManager();
+    this.notifications = new NotificationManager(this);
+
+    // private but maybe useful to be here, somewhat intimate
+    this.recordArrayManager = new RecordArrayManager({
+      store: this
+    });
+
+    // private
+    this._requestCache = new RequestStateService(this);
+    this._instanceCache = new InstanceCache(this);
+    this.isDestroying = false;
+    this.isDestroyed = false;
+  }
+
+  /** @internal */
+  _run(cb) {
+    const _cbs = this._cbs = {};
+    {
+      cb();
+      if (_cbs.coalesce) {
+        _cbs.coalesce();
+      }
+      if (_cbs.sync) {
+        _cbs.sync();
+      }
+      if (_cbs.notify) {
+        _cbs.notify();
+      }
+      this._cbs = null;
+    }
+  }
+
+  /**
+   * Executes the callback, ensurng that any work that calls
+   * store._schedule is executed after in the right order.
+   *
+   * When queues already exist, scheduled callbacks will
+   * join the existing queue.
+   *
+   * @internal
+   */
+  _join(cb) {
+    if (this._cbs) {
+      cb();
+    } else {
+      this._run(cb);
+    }
+  }
+
+  /** @internal */
+  _schedule(name, cb) {
+    this._cbs[name] = cb;
+  }
+
+  /**
+   * Retrieve the RequestStateService instance
+   * associated with this Store.
+   *
+   * This can be used to query the status of requests
+   * that have been initiated for a given identifier.
+   *
+   * @return {RequestStateService}
+   * @public
+   */
+  getRequestStateService() {
+    return this._requestCache;
+  }
+
+  /** @internal */
+  _getAllPending() {}
+
+  /**
+   * ::: tip 💡 For a more complete overview see the [Request Guide](/guides/2-requests/1-overview)
+   * :::
+   *
+   * Issue a request via the configured {@link RequestManager},
+   * inserting the response into the {@link Store.cache | cache} and handing
+   * back a {@link Future} which resolves to a {@link ReactiveDocument | ReactiveDocument}
+   *
+   * #### Request Cache Keys
+   *
+   * Only {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods/GET | GET} requests with a url or requests with an explicit
+   * {@link CacheOptions.key | cache key} will have the request result
+   * and document cached.
+   *
+   * The cache key used is {@link RequestInfo.cacheOptions.key | RequestInfo.cacheOptions.key}
+   * if present, falling back to {@link RequestInfo.url}.
+   *
+   * Params are not serialized as part of the cache-key, so
+   * either ensure they are already in the url or utilize
+   * `requestConfig.cacheOptions.key`. For queries issued
+   * via the {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods/POST | POST} method `requestConfig.cacheOptions.key`
+   * MUST be supplied for the document to be cached.
+   *
+   * #### Requesting Without a Cache Key
+   *
+   * Resource data within the request is always updated in the cache,
+   * regardless of whether a cache key is present for the request.
+   *
+   * #### Fulfilling From Cache
+   *
+   * When a cache-key is determined, the request may fulfill
+   * from cache provided the cache is not stale.
+   *
+   * Cache staleness is determined by the configured {@link CachePolicy}
+   * with priority given to the  {@link CacheOptions.reload} and
+   * {@link CacheOptions.backgroundReload} on the request if present.
+   *
+   * If the cache data has soft expired or the request asks for a background
+   * reload, the request will fulfill from cache if possible and
+   * make a non-blocking request in the background to update the cache.
+   *
+   * If the cache data has hard expired or the request asks for a reload,
+   * the request will not fulfill from cache and will make a blocking
+   * request to update the cache.
+   *
+   * #### The Response
+   *
+   * The primary difference between {@link RequestManager.request} and `store.request`
+   * is that `store.request` will convert the response into a {@link ReactiveDocument}
+   * containing {@link Store.instantiateRecord | ReactiveResources}.
+   *
+   * @public
+   */
+  request(requestConfig) {
+    // we lazily set the cache handler when we issue the first request
+    // because constructor doesn't allow for this to run after
+    // the user has had the chance to set the prop.
+    const opts = {
+      store: this,
+      [EnableHydration]: requestConfig[EnableHydration] ?? true
+    };
+    if (requestConfig.records) {
+      const cacheKeyManager = this.cacheKeyManager;
+      opts.records = requestConfig.records.map(r => cacheKeyManager.getOrCreateRecordIdentifier(r));
+    }
+    const request = Object.assign({}, requestConfig, opts);
+    const future = this.requestManager.request(request);
+    future.onFinalize(() => {
+      // skip flush for legacy belongsTo
+      if (requestConfig.op === 'findBelongsTo' && !requestConfig.url) {
+        return;
+      }
+      this.notifications._flush();
+    });
+    return future;
+  }
+
+  /**
+    Creates a new record in the current store.
+     > [!CAUTION]
+    > This should not be used to mock records or to create
+    > a record representing data that could be fetched from
+    > the API.
+     The properties passed to this method are set on
+    the newly created record.
+     For instance: to create a new `post`:
+     ```js
+    store.createRecord('post', {
+      title: 'WarpDrive is Stellar!'
+    });
+    ```
+     Relationships can be set during create. For instance,
+    to create a new `post` that has an existing user as
+    it's author:
+     ```js
+    const user = store.peekRecord('user', '1');
+     store.createRecord('post', {
+      title: 'WarpDrive is Stellar!',
+      user: user
+    });
+    ```
+     ### lid handling
+     All new records are assigned an `lid` that can be used to handle
+    transactional saves of multiple records, or to link the data to
+    other data in scenarios involving eventual-consistency or remote
+    syncing.
+     ```ts
+    const post = store.createRecord('post', {
+      title: 'WarpDrive is Stellar!'
+    });
+    const { lid } = recordIdentifierFor(post);
+    ```
+     The `lid` defaults to a uuidv4 string.
+     In order to support receiving knowledge about unpersisted creates
+    from other sources (say a different tab in the same web-browser),
+    createRecord allows for the `lid` to be provided as part of an
+    optional third argument. **If this lid already exists in the store
+    an error will be thrown.**
+     ```ts
+    const post = store.createRecord(
+      'post',
+      { title: 'WarpDrive is Stellar!' },
+      { lid: '4d47bb88-931f-496e-986d-c4888cef7373' }
+    );
+    ```
+     @public
+    @param type the name of the resource
+    @param inputProperties a hash of properties to set on the
+      newly created record.
+    @return a record in the "isNew" state
+  */
+
+  createRecord(type, inputProperties, context) {
+    // This is wrapped in a `run.join` so that in test environments users do not need to manually wrap
+    //   calls to `createRecord`. The run loop usage here is because we batch the joining and updating
+    //   of record-arrays via ember's run loop, not our own.
+    //
+    //   to remove this, we would need to move to a new `async` API.
+    let record;
+    this._join(() => {
+      const normalizedModelName = normalizeModelName(type);
+      const properties = {
+        ...inputProperties
+      };
+
+      // If the passed properties do not include a primary key,
+      // give the adapter an opportunity to generate one. Typically,
+      // client-side ID generators will use something like uuid.js
+      // to avoid conflicts.
+      let id = null;
+      if (properties.id === null || properties.id === undefined) {
+        const adapter = this.adapterFor?.(normalizedModelName, true);
+        if (adapter && adapter.generateIdForRecord) {
+          id = properties.id = coerceId(adapter.generateIdForRecord(this, normalizedModelName, properties));
+        } else {
+          id = properties.id = null;
+        }
+      } else {
+        id = properties.id = coerceId(properties.id);
+      }
+      const resource = {
+        type: normalizedModelName,
+        id
+      };
+      if (resource.id) {
+        this.cacheKeyManager.peekResourceKey(resource);
+      }
+      if (context?.lid) {
+        this.cacheKeyManager.peekResourceKey({
+          lid: context?.lid
+        });
+        resource.lid = context.lid;
+      }
+      const identifier = this.cacheKeyManager.createIdentifierForNewRecord(resource);
+      const cache = this.cache;
+      const createOptions = normalizeProperties(this, identifier, properties);
+      const resultProps = cache.clientDidCreate(identifier, createOptions);
+      record = getNewRecord(this._instanceCache, identifier, resultProps);
+    });
+    return record;
+  }
+
+  /**
+    For symmetry, a record can be deleted via the store.
+     Example
+     ```javascript
+    let post = store.createRecord('post', {
+      title: 'Ember is awesome!'
+    });
+     store.deleteRecord(post);
+    ```
+     @public
+    @param {unknown} record
+  */
+  deleteRecord(record) {
+    const identifier = peekResourceKey(record);
+    const cache = this.cache;
+    this._join(() => {
+      cache.setIsDeleted(identifier, true);
+      if (cache.isNew(identifier)) {
+        this._instanceCache.unloadRecord(identifier);
+      }
+    });
+  }
+
+  /**
+    For symmetry, a record can be unloaded via the store.
+    This will cause the record to be destroyed and freed up for garbage collection.
+     Example
+     ```javascript
+    const { content: { data: post } } = await store.request(findRecord({ type: 'post', id: '1' }));
+    store.unloadRecord(post);
+    ```
+     @public
+    @param {Model} record
+  */
+  unloadRecord(record) {
+    const identifier = peekResourceKey(record);
+    if (identifier) {
+      this._instanceCache.unloadRecord(identifier);
+    }
+  }
+
+  /**
+    Get a record by a given type and ID without triggering a fetch.
+     This method will synchronously return the record if it is available in the store,
+    otherwise it will return `null`. A record is available if it has been fetched earlier, or
+    pushed manually into the store.
+     **Example 1**
+     ```ts
+    const post = store.peekRecord('post', '1');
+     post.id; // '1'
+    ```
+     `peekRecord` can be called with a single identifier argument instead of the combination
+    of `type` (modelName) and `id` as separate arguments. You may recognize this combo as
+    the typical pairing from [JSON:API](https://jsonapi.org/format/#document-resource-object-identification)
+     **Example 2**
+     ```ts
+    const post = store.peekRecord({ type: 'post', id: '1' });
+    post.id; // '1'
+    ```
+     If you have previously received an lid from an Identifier for this record, you can lookup the record again using
+    just the lid.
+     **Example 3**
+     ```js
+    let post = store.peekRecord({ lid });
+    post.id; // '1'
+    ```
+     @since 1.13.0
+    @public
+    @param type - either a string representing the modelName or a ResourceIdentifier object containing both the type (a string) and the id (a string) for the record or an lid (a string) of an existing record
+    @param id - optional only if the first param is a ResourceIdentifier, else the string id of the record to be retrieved.
+  */
+
+  peekRecord(identifier, id) {
+    if (arguments.length === 1 && isMaybeIdentifier(identifier)) {
+      const stableIdentifier = this.cacheKeyManager.peekResourceKey(identifier);
+      const isLoaded = stableIdentifier && this._instanceCache.recordIsLoaded(stableIdentifier);
+      // TODO come up with a better mechanism for determining if we have data and could peek.
+      // this is basically an "are we not empty" query.
+      return isLoaded ? this._instanceCache.getRecord(stableIdentifier) : null;
+    }
+    const type = normalizeModelName(identifier);
+    const normalizedId = ensureStringId(id);
+    const resource = {
+      type,
+      id: normalizedId
+    };
+    const stableIdentifier = this.cacheKeyManager.peekResourceKey(resource);
+    const isLoaded = stableIdentifier && this._instanceCache.recordIsLoaded(stableIdentifier);
+    return isLoaded ? this._instanceCache.getRecord(stableIdentifier) : null;
+  }
+
+  /**
+    This method returns the {@link LegacyLiveArray} that contains all of the
+    known records for a given type in the store. Each ResourceType has only
+    one LiveArray instance, so multiple calls to `peekAll` with the same type
+    will always return the same instance.
+     Note that because it's a LiveArray, the result will contain any
+    locally created records of the type, however, it will not make a
+    request to the backend to retrieve additional records.
+     Example
+     ```ts
+    const allPosts = store.peekAll('post');
+    ```
+     @since 1.13.0
+    @public
+    @param type the name of the resource
+  */
+
+  peekAll(type) {
+    return this.recordArrayManager.liveArrayFor(normalizeModelName(type));
+  }
+
+  /**
+    This method unloads all records in the store.
+    It schedules unloading to happen during the next run loop.
+     Optionally you can pass a type which unload all records for a given type.
+     ```javascript
+    store.unloadAll();
+    store.unloadAll('post');
+    ```
+     @param {String} type the name of the resource
+    @public
+  */
+
+  unloadAll(type) {
+    this._join(() => {
+      this._enableAsyncFlush = true;
+      if (type === undefined) {
+        this.recordArrayManager.pause();
+        // destroy the graph before unloadAll
+        // since then we avoid churning relationships
+        // during unload
+        this._graph?.identifiers.clear();
+        this.recordArrayManager.clear();
+        this._instanceCache.clear();
+      } else {
+        this._instanceCache.clear(normalizeModelName(type));
+      }
+      this._enableAsyncFlush = null;
+      this.notifications._flush();
+      if (type === undefined) {
+        this.recordArrayManager.resume();
+      }
+    });
+  }
+
+  /**
+    Push some data for a given type into the store.
+     This method expects normalized [JSON API](http://jsonapi.org/) document. This means you have to follow [JSON API specification](http://jsonapi.org/format/) with few minor adjustments:
+    - record's `type` should always be in singular, dasherized form
+    - members (properties) should be camelCased
+     [Your primary data should be wrapped inside `data` property](http://jsonapi.org/format/#document-top-level):
+     ```js
+    store.push({
+      data: {
+        // primary data for single record of type `Person`
+        id: '1',
+        type: 'person',
+        attributes: {
+          firstName: 'Daniel',
+          lastName: 'Kmak'
+        }
+      }
+    });
+    ```
+     [Demo.](http://ember-twiddle.com/fb99f18cd3b4d3e2a4c7)
+     `data` property can also hold an array (of records):
+     ```js
+    store.push({
+      data: [
+        // an array of records
+        {
+          id: '1',
+          type: 'person',
+          attributes: {
+            firstName: 'Daniel',
+            lastName: 'Kmak'
+          }
+        },
+        {
+          id: '2',
+          type: 'person',
+          attributes: {
+            firstName: 'Tom',
+            lastName: 'Dale'
+          }
+        }
+      ]
+    });
+    ```
+     [Demo.](http://ember-twiddle.com/69cdbeaa3702159dc355)
+     There are some typical properties for `JSONAPI` payload:
+    * `id` - mandatory, unique record's key
+    * `type` - mandatory string which matches `model`'s dasherized name in singular form
+    * `attributes` - object which holds data for record attributes - `attr`'s declared in model
+    * `relationships` - object which must contain any of the following properties under each relationships' respective key (example path is `relationships.achievements.data`):
+      - [`links`](http://jsonapi.org/format/#document-links)
+      - [`data`](http://jsonapi.org/format/#document-resource-object-linkage) - place for primary data
+      - [`meta`](http://jsonapi.org/format/#document-meta) - object which contains meta-information about relationship
+     For this model:
+     ```js [app/models/person.js]
+    import Model, { attr, hasMany } from '@warp-drive/legacy/model';
+     export default class PersonRoute extends Route {
+      @attr('string') firstName;
+      @attr('string') lastName;
+       @hasMany('person') children;
+    }
+    ```
+     To represent the children as IDs:
+     ```js
+    {
+      data: {
+        id: '1',
+        type: 'person',
+        attributes: {
+          firstName: 'Tom',
+          lastName: 'Dale'
+        },
+        relationships: {
+          children: {
+            data: [
+              {
+                id: '2',
+                type: 'person'
+              },
+              {
+                id: '3',
+                type: 'person'
+              },
+              {
+                id: '4',
+                type: 'person'
+              }
+            ]
+          }
+        }
+      }
+    }
+    ```
+     [Demo.](http://ember-twiddle.com/343e1735e034091f5bde)
+     To represent the children relationship as a URL:
+     ```js
+    {
+      data: {
+        id: '1',
+        type: 'person',
+        attributes: {
+          firstName: 'Tom',
+          lastName: 'Dale'
+        },
+        relationships: {
+          children: {
+            links: {
+              related: '/people/1/children'
+            }
+          }
+        }
+      }
+    }
+    ```
+     If you're streaming data, or implementing response handling, make sure
+    that you have converted the incoming data into this form.
+     This method can be used both to push in brand new
+    records, as well as to update existing records.
+     See also {@link Cache.patch}
+     @public
+    @param data
+    @return the primary record(s) that created or updated.
+  */
+
+  push(data) {
+    const pushed = this._push(data, false);
+    if (Array.isArray(pushed)) {
+      return pushed.map(identifier => this._instanceCache.getRecord(identifier));
+    }
+    if (pushed === null) {
+      return null;
+    }
+    return this._instanceCache.getRecord(pushed);
+  }
+
+  /**
+    Push some data in the form of a json-api document into the store,
+    without creating materialized records.
+     @private
+    @return identifiers for the primary records that had data loaded
+  */
+  _push(jsonApiDoc, asyncFlush) {
+    if (asyncFlush) {
+      this._enableAsyncFlush = true;
+    }
+    let ret;
+    this._join(() => {
+      ret = this.cache.put({
+        content: jsonApiDoc
+      });
+    });
+    this._enableAsyncFlush = null;
+    return 'data' in ret ? ret.data : null;
+  }
+
+  /**
+   * Returns the cache instance associated to this Store, instantiates the Cache
+   * if necessary via `Store.createCache`
+   *
+   * @public
+   */
+  get cache() {
+    let {
+      cache
+    } = this._instanceCache;
+    if (!cache) {
+      cache = this._instanceCache.cache = this.createCache(this._instanceCache._storeWrapper);
+    }
+    return cache;
+  }
+
+  /** @private */
+  destroy() {
+    if (this.isDestroyed) {
+      // @ember/test-helpers will call destroy multiple times
+      return;
+    }
+    this.isDestroying = true;
+    this._graph?.destroy();
+    this._graph = undefined;
+    this.notifications.destroy();
+    this.recordArrayManager.destroy();
+    this.cacheKeyManager.destroy();
+    this._instanceCache.clear();
+    this.isDestroyed = true;
+  }
+
+  /**
+   * This method
+   *
+   * @private
+   */
+  static create(args) {
+    return new this(args);
+  }
+}
+
+/**
+ * This type exists for internal use only for
+ * where intimate contracts still exist either for
+ * the Test Suite or for Legacy code.
+ *
+ * @private
+ */
+
+/**
+ * Upgrade the type for Store to PrivateStore, which will also
+ * upgrade any associated types to their private equivalents.
+ *
+ * @private
+ */
+function assertPrivateStore(store) {}
+/**
+ * Upgrade the type for Store to PrivateStore, which will also
+ * upgrade any associated types to their private equivalents.
+ *
+ * @private
+ */
+function isPrivateStore(store) {
+  return store;
+}
+function isMaybeIdentifier(maybeIdentifier) {
+  return Boolean(maybeIdentifier !== null && typeof maybeIdentifier === 'object' && ('id' in maybeIdentifier && 'type' in maybeIdentifier && maybeIdentifier.id && maybeIdentifier.type || maybeIdentifier.lid));
+}
+function normalizeProperties(store, identifier, properties) {
+  // assert here
+  if (properties !== undefined) {
+    const {
+      type
+    } = identifier;
+
+    // convert relationship Records to RecordDatas before passing to RecordData
+    const defs = store.schema.fields({
+      type
+    });
+    if (defs.size) {
+      const keys = Object.keys(properties);
+      for (let i = 0; i < keys.length; i++) {
+        const prop = keys[i];
+        const field = defs.get(prop);
+        if (!field) continue;
+        if (field.kind === 'hasMany') {
+          properties[prop] = extractIdentifiersFromRecords$1(properties[prop]);
+        } else if (field.kind === 'belongsTo') {
+          properties[prop] = extractIdentifierFromRecord$1(properties[prop]);
+        }
+      }
+    }
+  }
+  return properties;
+}
+function extractIdentifiersFromRecords$1(records) {
+  return records.map(record => extractIdentifierFromRecord$1(record));
+}
+function extractIdentifierFromRecord$1(recordOrPromiseRecord) {
+  if (!recordOrPromiseRecord) {
+    return null;
+  }
+  const extract = recordIdentifierFor;
+  return extract(recordOrPromiseRecord);
+}
+
+/**
+   A `RecordReference` is a low-level API that allows users and
+   addon authors to perform meta-operations on a record.
+
+   @hideconstructor
+   @public
+*/
+class RecordReference {
+  /** @internal */
+
+  // unsubscribe token given to us by the notification manager
+  /** @internal */
+  ___token;
+  /** @internal */
+  ___identifier;
+  /** @internal */
+
+  constructor(store, identifier) {
+    this.store = store;
+    this.___identifier = identifier;
+    this.___token = store.notifications.subscribe(identifier, (_, bucket, notifiedKey) => {
+      if (bucket === 'identity' || bucket === 'attributes' && notifiedKey === 'id') {
+        this._ref++;
+      }
+    });
+  }
+
+  /** @internal */
+  destroy() {
+    this.store.notifications.unsubscribe(this.___token);
+  }
+  get type() {
+    return this.identifier().type;
+  }
+
+  /**
+     The `id` of the record that this reference refers to.
+      Together, the `type` and `id` properties form a composite key for
+     the identity map.
+      Example
+      ```javascript
+     let userRef = store.getReference('user', 1);
+      userRef.id(); // '1'
+     ```
+     @public
+    @return The id of the record.
+  */
+  id() {
+    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+    this._ref; // consume the tracked prop
+    return this.___identifier.id;
+  }
+
+  /**
+     The `identifier` of the record that this reference refers to.
+      Together, the `type` and `id` properties form a composite key for
+     the identity map.
+      Example
+      ```javascript
+     let userRef = store.getReference('user', 1);
+      userRef.identifier(); // '1'
+     ```
+     @public
+    @return The identifier of the record.
+  */
+  identifier() {
+    return this.___identifier;
+  }
+
+  /**
+     How the reference will be looked up when it is loaded. Currently
+     this always returns `identity` to signify that a record will be
+     loaded by its `type` and `id`.
+      Example
+      ```javascript
+     const userRef = store.getReference('user', 1);
+      userRef.remoteType(); // 'identity'
+     ```
+      @public
+  */
+  remoteType() {
+    return 'identity';
+  }
+
+  /**
+    This API allows you to provide a reference with new data. The
     simplest usage of this API is similar to `store.push`: you provide a
     normalized hash of data and the object represented by the reference
     will update.
@@ -2627,7 +3911,338 @@ class RecordReference {
     }
   }
 }
-defineSignal(RecordReference.prototype, '_ref');
+defineSignal(RecordReference.prototype, '_ref');
+const MUTATION_OPS$1 = new Set(['createRecord', 'updateRecord', 'deleteRecord']);
+function calcShouldFetch(store, request, hasCachedValue, identifier) {
+  const {
+    cacheOptions
+  } = request;
+  return request.op && MUTATION_OPS$1.has(request.op) || cacheOptions?.reload || !hasCachedValue || (store.lifetimes && identifier ? store.lifetimes.isHardExpired(identifier, store) : false);
+}
+function calcShouldBackgroundFetch(store, request, willFetch, identifier) {
+  const {
+    cacheOptions
+  } = request;
+  return cacheOptions?.backgroundReload || (store.lifetimes && identifier ? store.lifetimes.isSoftExpired(identifier, store) : false);
+}
+function isMutation(request) {
+  return Boolean(request.op && MUTATION_OPS$1.has(request.op));
+}
+function isCacheAffecting(document) {
+  if (!isMutation(document.request)) {
+    return true;
+  }
+  // a mutation combined with a 204 has no cache impact when no known records were involved
+  // a createRecord with a 201 with an empty response and no known records should similarly
+  // have no cache impact
+
+  if (document.request.op === 'createRecord' && document.response?.status === 201) {
+    return document.content ? Object.keys(document.content).length > 0 : false;
+  }
+  return document.response?.status !== 204;
+}
+function isAggregateError(error) {
+  return error instanceof AggregateError || error.name === 'AggregateError' && Array.isArray(error.errors);
+}
+// TODO @runspired, consider if we should deep freeze errors (potentially only in debug) vs cloning them
+function cloneError(error) {
+  const isAggregate = isAggregateError(error);
+  const cloned = isAggregate ? new AggregateError(structuredClone(error.errors), error.message) : new Error(error.message);
+  cloned.stack = error.stack;
+  cloned.error = error.error;
+
+  // copy over enumerable properties
+  Object.assign(cloned, error);
+  return cloned;
+}
+function getPriority(identifier, deduped, priority) {
+  if (identifier) {
+    const existing = deduped.get(identifier);
+    if (existing) {
+      return existing.priority;
+    }
+  }
+  return priority;
+}
+
+/**
+ * A CacheHandler that adds support for using an WarpDrive Cache with a RequestManager.
+ *
+ * This handler will only run when a request has supplied a `store` instance. Requests
+ * issued by the store via `store.request()` will automatically have the `store` instance
+ * attached to the request.
+ *
+ * ```ts
+ * requestManager.request({
+ *   store: store,
+ *   url: '/api/posts',
+ *   method: 'GET'
+ * });
+ * ```
+ *
+ * When this handler elects to handle a request, it will return the raw `StructuredDocument`
+ * unless the request has `[EnableHydration]` set to `true`. In this case, the handler will
+ * return a `Document` instance that will automatically update the UI when the cache is updated
+ * in the future and will hydrate any identifiers in the StructuredDocument into Record instances.
+ *
+ * When issuing a request via the store, [EnableHydration] is automatically set to `true`. This
+ * means that if desired you can issue requests that utilize the cache without needing to also
+ * utilize Record instances if desired.
+ *
+ * Said differently, you could elect to issue all requests via a RequestManager, without ever using
+ * the store directly, by setting [EnableHydration] to `true` and providing a store instance. Not
+ * necessarily the most useful thing, but the decoupled nature of the RequestManager and incremental-feature
+ * approach of WarpDrive allows for this flexibility.
+ *
+ * ```ts
+ * import { EnableHydration } from '@warp-drive/core/types/request';
+ *
+ * requestManager.request({
+ *   store: store,
+ *   url: '/api/posts',
+ *   method: 'GET',
+ *   [EnableHydration]: true
+ * });
+ *
+ */
+const CacheHandler = {
+  request(context, next) {
+    // if we have no cache or no cache-key skip cache handling
+    if (!context.request.store || context.request.cacheOptions?.[SkipCache]) {
+      return next(context.request);
+    }
+    const {
+      store
+    } = context.request;
+    const identifier = store.cacheKeyManager.getOrCreateDocumentIdentifier(context.request);
+    if (identifier) {
+      context.setIdentifier(identifier);
+    }
+
+    // used to dedupe existing requests that match
+    const DEDUPE = store.requestManager._deduped;
+    const activeRequest = identifier && DEDUPE.get(identifier);
+    const peeked = identifier ? store.cache.peekRequest(identifier) : null;
+
+    // determine if we should skip cache
+    if (calcShouldFetch(store, context.request, !!peeked, identifier)) {
+      if (activeRequest) {
+        activeRequest.priority = {
+          blocking: true
+        };
+        return activeRequest.promise;
+      }
+      let promise = fetchContentAndHydrate(next, context, identifier, {
+        blocking: true
+      });
+      if (identifier) {
+        promise = promise.finally(() => {
+          DEDUPE.delete(identifier);
+          store.notifications.notify(identifier, 'state', null);
+        });
+        DEDUPE.set(identifier, {
+          priority: {
+            blocking: true
+          },
+          promise
+        });
+        queueMicrotask(() => {
+          store.notifications.notify(identifier, 'state', null);
+        });
+      }
+      store.requestManager._pending.set(context.id, promise);
+      return promise;
+    }
+
+    // if we have not skipped cache, determine if we should update behind the scenes
+    if (calcShouldBackgroundFetch(store, context.request, false, identifier)) {
+      let promise = activeRequest?.promise || fetchContentAndHydrate(next, context, identifier, {
+        blocking: false
+      });
+      if (identifier && !activeRequest) {
+        promise = promise.finally(() => {
+          DEDUPE.delete(identifier);
+          store.notifications.notify(identifier, 'state', null);
+        });
+        DEDUPE.set(identifier, {
+          priority: {
+            blocking: false
+          },
+          promise
+        });
+        queueMicrotask(() => {
+          store.notifications.notify(identifier, 'state', null);
+        });
+      }
+      store.requestManager._pending.set(context.id, promise);
+    }
+    const shouldHydrate = context.request[EnableHydration] || false;
+    context.setResponse(peeked.response);
+    if ('error' in peeked) {
+      const content = shouldHydrate ? maybeUpdateUiObjects(store, context.request, {
+        shouldHydrate,
+        identifier
+      }, peeked.content) : peeked.content;
+      const newError = cloneError(peeked);
+      newError.content = content;
+      throw newError;
+    }
+    const result = shouldHydrate ? maybeUpdateUiObjects(store, context.request, {
+      shouldHydrate,
+      identifier
+    }, peeked.content) : peeked.content;
+    return result;
+  }
+};
+function maybeUpdateUiObjects(store, request, options, document) {
+  const {
+    identifier
+  } = options;
+  if (!document || !options.shouldHydrate) {
+    return document ?? null;
+  }
+  if (identifier) {
+    return store._instanceCache.getDocument(identifier);
+  }
+
+  // if we don't have an identifier, we give the document
+  // its own local cache
+  return createReactiveDocument(store, null, {
+    request,
+    document
+  });
+}
+function updateCacheForSuccess(store, request, options, document) {
+  let response = null;
+  if (isMutation(request)) {
+    if (Array.isArray(request.records)) {
+      response = store.cache.didCommit(request.records, document);
+    } else if (request.data?.record) {
+      // legacy fallback, the data option should no longer be used for this
+      response = store.cache.didCommit(request.data.record, document);
+
+      // a mutation combined with a 204 has no cache impact when no known records were involved
+      // a createRecord with a 201 with an empty response and no known records should similarly
+      // have no cache impact
+    } else if (isCacheAffecting(document)) {
+      response = store.cache.put(document);
+    }
+  } else {
+    response = store.cache.put(document);
+  }
+  return maybeUpdateUiObjects(store, request, options, response);
+}
+function handleFetchSuccess(store, context, options, document) {
+  const {
+    request
+  } = context;
+  store.requestManager._pending.delete(context.id);
+  store._enableAsyncFlush = true;
+  let response;
+  store._join(() => {
+    response = updateCacheForSuccess(store, request, options, document);
+  });
+  store._enableAsyncFlush = null;
+  if (store.lifetimes?.didRequest) {
+    store.lifetimes.didRequest(context.request, document.response, options.identifier, store);
+  }
+  const finalPriority = getPriority(options.identifier, store.requestManager._deduped, options.priority);
+  if (finalPriority.blocking) {
+    return response;
+  } else {
+    store.notifications._flush();
+  }
+}
+function updateCacheForError(store, context, options, error) {
+  let response;
+  if (isMutation(context.request)) {
+    // TODO similar to didCommit we should spec this to be similar to cache.put for handling full response
+    // currently we let the response remain undefiend.
+    const errors = error && error.content && typeof error.content === 'object' && 'errors' in error.content && Array.isArray(error.content.errors) ? error.content.errors : undefined;
+    if (Array.isArray(context.request.records)) {
+      store.cache.commitWasRejected(context.request.records, errors);
+    } else if (context.request.data?.record) {
+      // legacy fallback, the data option should no longer be used for this
+      store.cache.commitWasRejected(context.request.data.record, errors);
+    } else {
+      store.cache.put(error);
+    }
+  } else {
+    response = store.cache.put(error);
+    return maybeUpdateUiObjects(store, context.request, options, response);
+  }
+}
+function handleFetchError(store, context, options, error) {
+  store.requestManager._pending.delete(context.id);
+  if (context.request.signal?.aborted) {
+    throw error;
+  }
+  store._enableAsyncFlush = true;
+  let response;
+  store._join(() => {
+    response = updateCacheForError(store, context, options, error);
+  });
+  store._enableAsyncFlush = null;
+  if (options.identifier && store.lifetimes?.didRequest) {
+    store.lifetimes.didRequest(context.request, error.response, options.identifier, store);
+  }
+  if (isMutation(context.request)) {
+    throw error;
+  }
+  const finalPriority = getPriority(options.identifier, store.requestManager._deduped, options.priority);
+  if (finalPriority.blocking) {
+    const newError = cloneError(error);
+    newError.content = response;
+    throw newError;
+  } else {
+    store.notifications._flush();
+  }
+}
+function fetchContentAndHydrate(next, context, identifier, priority) {
+  const {
+    store
+  } = context.request;
+  const shouldHydrate = context.request[EnableHydration] || false;
+  const options = {
+    shouldHydrate,
+    identifier,
+    priority
+  };
+  let isMut = false;
+  if (isMutation(context.request)) {
+    isMut = true;
+    if (Array.isArray(context.request.records)) {
+      context.request.records.forEach(record => {
+        store.cache.willCommit(record, context);
+      });
+    } else if (context.request.data?.record) {
+      // legacy fallback, the data option should no longer be used for this
+      store.cache.willCommit(context.request.data.record, context);
+    }
+  }
+  if (store.lifetimes?.willRequest) {
+    store.lifetimes.willRequest(context.request, identifier, store);
+  }
+  const promise = next(context.request).then(document => {
+    return handleFetchSuccess(store, context, options, document);
+  }, error => {
+    return handleFetchError(store, context, options, error);
+  });
+  if (!isMut) {
+    return promise;
+  }
+
+  // for mutations we need to enqueue the promise with the requestStateService
+  // TODO should we enque a request per record in records?
+  const record = context.request.data?.record || context.request.records?.[0];
+  return store._requestCache._enqueue(promise, {
+    data: [{
+      op: 'saveRecord',
+      recordIdentifier: record,
+      options: undefined
+    }]
+  });
+}
 
 /**
   A `ManyArray` is a `MutableArray` that represents the contents of a has-many
@@ -3385,14 +5000,41 @@ function getBelongsToField(context) {
 }
 function setBelongsToField(context) {
   const {
+    field,
+    resourceKey,
     store
   } = context;
   const {
-    schema
+    schema,
+    cache
   } = store;
+
+  /**
+   * We currently only allow editing sync belongsTo relationships
+   * in PolarisMode
+   */
+  const isValidPolarisConfig = field.options.linksMode && !field.options.async;
+  if (!context.legacy && isValidPolarisConfig) {
+    const name = context.path.at(-1);
+    cache.mutate({
+      op: 'replaceRelatedRecord',
+      record: resourceKey,
+      field: name,
+      value: getResourceKey(context.value)
+    },
+    // @ts-expect-error
+    true);
+    return true;
+  }
   schema._kind('@legacy', 'belongsTo').set(store, context.record, context.resourceKey, context.field, context.value);
   return true;
 }
+function getResourceKey(record) {
+  if (!record) {
+    return null;
+  }
+  return recordIdentifierFor(record);
+}
 function getCollectionField(context) {
   entangleSignal(context.signals, context.record, context.path.at(-1), null);
 }
@@ -4024,6 +5666,17 @@ function setSchemaObjectField(context) {
   // }
   return true;
 }
+
+/**
+ * A ReactiveResource context object passed to
+ * the get/set functions of a field kind implementation.
+ *
+ * This provides all the necessary information for
+ * the field kind to perform its operations.
+ *
+ * @internal
+ */
+
 const DefaultMode = {
   '@hash': {
     get: getHashField,
@@ -4294,6 +5947,9 @@ class ReactiveResource {
         if (prop === Destroy || prop === Checkout) {
           return true;
         }
+        if (prop === identityField?.name) {
+          return true;
+        }
         return fields.has(prop);
       },
       getOwnPropertyDescriptor(target, prop) {
@@ -4692,6 +6348,29 @@ function checkout(resource) {
 function commit(record) {
   return record[Commit]();
 }
+function instantiateRecord(store, identifier, createArgs) {
+  const schema = store.schema;
+  const resourceSchema = schema.resource(identifier);
+  const legacy = resourceSchema?.legacy ?? false;
+  const editable = legacy;
+  const record = new ReactiveResource({
+    store,
+    resourceKey: identifier,
+    modeName: legacy ? 'legacy' : 'polaris',
+    legacy: legacy,
+    editable: editable,
+    path: null,
+    field: null,
+    value: null
+  });
+  if (createArgs && editable) {
+    Object.assign(record, createArgs);
+  }
+  return record;
+}
+function teardownRecord(record) {
+  record[Destroy]();
+}
 const Support = getOrSetGlobal('Support', new WeakMap());
 const ConstructorField = {
   type: '@constructor',
@@ -4706,6 +6385,14 @@ const TypeField = {
     key: 'type'
   }
 };
+const IdentifierField = {
+  type: '@identity',
+  name: '$key',
+  kind: 'derived',
+  options: {
+    key: '^'
+  }
+};
 const DefaultIdentityField = {
   name: 'id',
   kind: '@id'
@@ -4874,6 +6561,7 @@ function withDefaults(schema) {
   // we add TypeField to the beginning so that it will
   // appear right next to the identity field
   schema.fields.unshift(TypeField);
+  schema.fields.unshift(IdentifierField);
   schema.fields.push(ConstructorField);
   return schema;
 }
@@ -4958,6 +6646,18 @@ class SchemaService {
 
   /** @internal */
 
+  /**
+   * Tracks, per abstract type, the relationship fields that concrete
+   * implementers have contributed via `options.as`, along with the type
+   * that contributed each one (for assertion messages). This is
+   * independent of whatever schema (synthesized or user-registered)
+   * currently occupies `_schemas` for that type, so that these fields
+   * survive regardless of the order in which the abstract type's
+   * implementers and its own (optional) concrete schema are registered.
+   *
+   * @internal
+   */
+
   /** @internal */
 
   /** @internal */
@@ -4969,6 +6669,7 @@ class SchemaService {
     this._derivations = new Map();
     this._traits = new Map();
     this._modes = new Map();
+    this._abstractImplementerFields = new Map();
     this._extensions = {
       object: new Map(),
       array: new Map()
@@ -5014,12 +6715,33 @@ class SchemaService {
     const fields = new Map();
     const relationships = {};
     const attributes = {};
+    const abstractImplementations = [];
     for (const field of schema.fields) {
       fields.set(field.name, field);
       if (field.kind === 'attribute') {
         attributes[field.name] = field;
       } else if (field.kind === 'belongsTo' || field.kind === 'hasMany') {
         relationships[field.name] = field;
+        if (field.options?.as) {
+          abstractImplementations.push(field);
+        }
+      }
+    }
+
+    // This type may already be known as an abstract polymorphic type,
+    // implemented by other concrete types via `options.as`, from before it
+    // ever had a schema of its own (see `_registerAbstractTypeImplementation`).
+    // Carry those previously-contributed fields forward so that registering
+    // a "real" schema for the type - whenever that happens to occur - never
+    // erases the relationships its implementers depend on.
+    const implementerFields = this._abstractImplementerFields.get(schema.type);
+    if (implementerFields) {
+      for (const [name, contribution] of implementerFields) {
+        const ownField = fields.get(name);
+        if (!ownField) {
+          fields.set(name, contribution.field);
+          relationships[name] = contribution.field;
+        }
       }
     }
     const cacheFields = null;
@@ -5038,6 +6760,92 @@ class SchemaService {
       internalSchema.cacheFields = getCacheFields(internalSchema);
     }
     this._schemas.set(schema.type, internalSchema);
+
+    // A relationship field's `as` option marks it as a valid concrete
+    // implementer of an abstract polymorphic type (e.g. `as: 'commentable'`).
+    // That abstract type may never be given its own schema by the user - it
+    // may exist only to be implemented by concrete types like this one - or
+    // it may already have (or later receive) a schema of its own, e.g. if it
+    // turns out to also be a real, directly-resolvable resource. Either way,
+    // ensure it has a schema with this field present, so that it behaves
+    // like any other registered resource (`hasResource`, `fields`, etc.)
+    // instead of requiring special-casing wherever abstract relationship
+    // types are resolved.
+    for (const field of abstractImplementations) {
+      this._registerAbstractTypeImplementation(field, schema.type);
+    }
+  }
+
+  /** @internal */
+  _registerAbstractTypeImplementation(field, implementer) {
+    const abstractType = field.options.as;
+    let implementerFields = this._abstractImplementerFields.get(abstractType);
+    if (!implementerFields) {
+      implementerFields = new Map();
+      this._abstractImplementerFields.set(abstractType, implementerFields);
+    }
+
+    // Unlike the original approach this replaced, `as` is *not* stripped here:
+    // the field as synthesized onto the abstract type's own schema keeps
+    // `options.as === abstractType`, redundant/self-referential as that is.
+    // This keeps every contributor - implementers and the abstract type's
+    // own schema alike - declaring the same thing, which is what
+    // `assertConsistentAbstractFieldShape` checks, and it is also what lets
+    // `assertPolymorphicType` (which reads a field's declared `as` off
+    // whatever `schema.fields()` serves for its type) correctly permit the
+    // abstract type itself to be pushed directly into this relationship.
+    const abstractField = {
+      ...field
+    };
+    const contribution = {
+      field: abstractField,
+      source: implementer
+    };
+
+    // all concrete implementations of an abstract type are required to
+    // share the same shape for the field that implements it, so the first
+    // one registered is as good a canonical source as any - but a later,
+    // differently-shaped one is almost certainly a mistake rather than an
+    // intentional override, so we catch it rather than silently ignoring it.
+    const existingImplementer = implementerFields.get(field.name);
+    if (existingImplementer) {
+      return;
+    }
+    implementerFields.set(field.name, contribution);
+    let abstractSchema = this._schemas.get(abstractType);
+    if (!abstractSchema) {
+      abstractSchema = {
+        original: {
+          legacy: true,
+          identity: {
+            kind: '@id',
+            name: 'id'
+          },
+          type: abstractType,
+          fields: []
+        },
+        finalized: true,
+        fields: new Map(),
+        cacheFields: new Map(),
+        relationships: {},
+        attributes: {},
+        traits: new Set()
+      };
+      this._schemas.set(abstractType, abstractSchema);
+    }
+    const existingAbstractField = abstractSchema.fields.get(field.name);
+    if (existingAbstractField) {
+      return;
+    }
+    abstractSchema.fields.set(field.name, abstractField);
+    abstractSchema.relationships[field.name] = abstractField;
+
+    // If the schema is mid-finalization (traits pending), finalizeResource
+    // will recompute cacheFields from the current `fields` map anyway; avoid
+    // doing so prematurely from a partially-resolved set of fields.
+    if (abstractSchema.finalized) {
+      abstractSchema.cacheFields = getCacheFields(abstractSchema);
+    }
   }
 
   /**
@@ -5234,4 +7042,506 @@ function mergeMap(base, toApply) {
     base.set(key, value);
   }
 }
-export { CacheKeyManager as C, InstanceCache as I, RecordArrayManager as R, SchemaService as S, _clearCaches as _, recordIdentifierFor as a, setIdentifierGenerationMethod as b, setIdentifierUpdateMethod as c, setIdentifierForgetMethod as d, setIdentifierResetMethod as e, setKeyInfoForResource as f, coerceId as g, isRequestKey as h, isResourceKey as i, ensureStringId as j, fastPush as k, assertPrivateCapabilities as l, setRecordIdentifier as m, StoreMap as n, normalizeModelName as o, createLegacyManyArray as p, getNewRecord as q, registerDerivations as r, storeFor as s, peekResourceKey as t, createReactiveDocument as u, ReactiveResource as v, checkout as w, withDefaults as x, fromIdentity as y, commit as z };
+
+// Lazily close over fetch to avoid breaking Mirage
+const _fetch = typeof fetch !== 'undefined' ? (...args) => fetch(...args) : typeof FastBoot !== 'undefined' ? (...args) => FastBoot.require('node-fetch')(...args) : () => {
+  throw new Error('No Fetch Implementation Found');
+};
+
+// clones a response in a way that should still
+// allow it to stream
+function cloneResponse(response, overrides) {
+  const props = cloneResponseProperties(response);
+  return new Response(response.body, Object.assign(props, overrides));
+}
+function withDateHeader(response) {
+  const headers = new Headers(response.headers);
+  headers.set('date', new Date().toUTCString());
+  return cloneResponse(response, {
+    headers
+  });
+}
+const MUTATION_OPS = new Set(['updateRecord', 'createRecord', 'deleteRecord']);
+const ERROR_STATUS_CODE_FOR = new Map([[400, 'Bad Request'], [401, 'Unauthorized'], [402, 'Payment Required'], [403, 'Forbidden'], [404, 'Not Found'], [405, 'Method Not Allowed'], [406, 'Not Acceptable'], [407, 'Proxy Authentication Required'], [408, 'Request Timeout'], [409, 'Conflict'], [410, 'Gone'], [411, 'Length Required'], [412, 'Precondition Failed'], [413, 'Payload Too Large'], [414, 'URI Too Long'], [415, 'Unsupported Media Type'], [416, 'Range Not Satisfiable'], [417, 'Expectation Failed'], [419, 'Page Expired'], [420, 'Enhance Your Calm'], [421, 'Misdirected Request'], [422, 'Unprocessable Entity'], [423, 'Locked'], [424, 'Failed Dependency'], [425, 'Too Early'], [426, 'Upgrade Required'], [428, 'Precondition Required'], [429, 'Too Many Requests'], [430, 'Request Header Fields Too Large'], [431, 'Request Header Fields Too Large'], [450, 'Blocked By Windows Parental Controls'], [451, 'Unavailable For Legal Reasons'], [500, 'Internal Server Error'], [501, 'Not Implemented'], [502, 'Bad Gateway'], [503, 'Service Unavailable'], [504, 'Gateway Timeout'], [505, 'HTTP Version Not Supported'], [506, 'Variant Also Negotiates'], [507, 'Insufficient Storage'], [508, 'Loop Detected'], [509, 'Bandwidth Limit Exceeded'], [510, 'Not Extended'], [511, 'Network Authentication Required']]);
+
+/**
+ * ```ts
+ * import { Fetch } from '@warp-drive/core';
+ * ```
+ *
+ * A basic Fetch Handler which converts a request into a
+ * `fetch` call presuming the response to be `json`.
+ *
+ * ```ts
+ * import { RequestManager, Fetch } from '@warp-drive/core';
+ *
+ * const manager = new RequestManager()
+ *   .use([Fetch]);
+ * ```
+ *
+ * @public
+ */
+const Fetch = {
+  async request(context) {
+    let response;
+    try {
+      ({});
+      response = await _fetch(context.request.url, context.request);
+    } catch (e) {
+      if (e instanceof DOMException && e.name === 'AbortError') {
+        e.statusText = 'Aborted';
+        e.status = 20;
+        e.isRequestError = true;
+      } else {
+        e.statusText = 'Unknown Network Error';
+        e.status = 0;
+        if (!(e instanceof DOMException)) {
+          e.code = 0;
+        }
+        e.isRequestError = true;
+      }
+      throw e;
+    }
+    const isError = !response.ok || response.status >= 400;
+    const op = context.request.op;
+    const isMutationOp = Boolean(op && MUTATION_OPS.has(op));
+    if (!isError && !isMutationOp && response.status !== 204 && !response.headers.has('date')) {
+      {
+        response = withDateHeader(response);
+      }
+    }
+    context.setResponse(response);
+    if (response.status === 204 || context.request.method === 'HEAD') {
+      return null;
+    }
+    let text = '';
+    // if we are in a mirage context, we cannot support streaming
+    {
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let isStreaming = context.hasRequestedStream;
+      let stream = isStreaming ? new TransformStream() : null;
+      let writer = stream?.writable.getWriter();
+      if (isStreaming) {
+        // Listen for the abort event on the AbortSignal
+        context.request.signal?.addEventListener('abort', () => {
+          if (!isStreaming) {
+            return;
+          }
+          void stream.writable.abort('Request Aborted');
+          void stream.readable.cancel('Request Aborted');
+        });
+        context.setStream(stream.readable);
+      }
+      while (true) {
+        // we manually read the stream instead of using `response.json()`
+        // or `response.text()` because if we need to stream the body
+        // we need to be able to pass the stream along efficiently.
+        const {
+          done,
+          value
+        } = await reader.read();
+        if (done) {
+          if (isStreaming) {
+            isStreaming = false;
+            await writer.ready;
+            await writer.close();
+          }
+          break;
+        }
+        text += decoder.decode(value, {
+          stream: true
+        });
+
+        // if we are streaming, we want to pass the stream along
+        if (isStreaming) {
+          await writer.ready;
+          await writer.write(value);
+        } else if (context.hasRequestedStream) {
+          const encode = new TextEncoder();
+          isStreaming = true;
+          stream = new TransformStream();
+          // Listen for the abort event on the AbortSignal
+          // eslint-disable-next-line @typescript-eslint/no-loop-func
+          context.request.signal?.addEventListener('abort', () => {
+            if (!isStreaming) {
+              return;
+            }
+            void stream.writable.abort('Request Aborted');
+            void stream.readable.cancel('Request Aborted');
+          });
+          context.setStream(stream.readable);
+          writer = stream.writable.getWriter();
+          await writer.ready;
+          await writer.write(encode.encode(text));
+          await writer.ready;
+          await writer.write(value);
+        }
+      }
+      if (isStreaming) {
+        isStreaming = false;
+        await writer.ready;
+        await writer.close();
+      }
+    }
+    // if we are an error, we will want to throw
+    if (isError) {
+      let errorPayload;
+      try {
+        errorPayload = JSON.parse(text);
+      } catch {
+        // void;
+      }
+      // attempt errors discovery
+      const errors = Array.isArray(errorPayload) ? errorPayload : isDict(errorPayload) && Array.isArray(errorPayload.errors) ? errorPayload.errors : null;
+      const statusText = response.statusText || ERROR_STATUS_CODE_FOR.get(response.status) || 'Unknown Request Error';
+      const msg = `[${response.status} ${statusText}] ${context.request.method ?? 'GET'} (${response.type}) - ${response.url}`;
+      const error = errors ? new AggregateError(errors, msg) : new Error(msg);
+      error.status = response.status;
+      error.statusText = statusText;
+      error.isRequestError = true;
+      error.code = error.status;
+      error.name = error.statusText.replaceAll(' ', '') + 'Error';
+      error.content = errorPayload;
+      throw error;
+    } else {
+      return JSON.parse(text);
+    }
+  }
+};
+function isDict(v) {
+  return v !== null && typeof v === 'object';
+}
+
+/**
+ * ## Import
+ *
+ * ```js
+ * import { RequestManager } from '@warp-drive/core';
+ * ```
+ *
+ * For complete usage guide see the [RequestManager Documentation](/guides/).
+ *
+ * ## How It Works
+ *
+ * ```ts
+ * interface RequestManager {
+ *   request<T>(req: RequestInfo): Future<T>;
+ * }
+ * ```
+ *
+ * A RequestManager provides a request/response flow in which configured
+ * handlers are successively given the opportunity to handle, modify, or
+ * pass-along a request.
+ *
+ * <img src="/images/handlers-all-labeled.gif" alt="RequestManager Flow Animation" width="100%" />
+ *
+ * For example:
+ *
+ * ::: code-group
+ *
+ * ```ts [Setup.ts]
+ * import { RequestManager, Fetch } from '@warp-drive/core';
+ * import { AutoCompress } from '@warp-drive/utilities/handlers';
+ * import Auth from 'ember-simple-auth/handler';
+ *
+ * // ... create manager
+ * const manager = new RequestManager()
+ *    .use([Auth, new AutoCompress(), Fetch]); // [!code focus]
+ * ```
+ *
+ * ```ts [Usage.ts]
+ * import Config from './config';
+ *
+ * const { apiUrl } = Config;
+ *
+ * // ... execute a request
+ * const response = await manager.request({
+ *   url: `${apiUrl}/users`
+ * });
+ * ```
+ *
+ * :::
+ *
+ * ### Futures
+ *
+ * The return value of `manager.request` is a `Future`, which allows
+ * access to limited information about the request while it is still
+ * pending and fulfills with the final state when the request completes.
+ *
+ * A `Future` is cancellable via `abort`.
+ *
+ * Handlers may optionally expose a `ReadableStream` to the `Future` for
+ * streaming data; however, when doing so the future should not resolve
+ * until the response stream is fully read.
+ *
+ * ```ts
+ * interface Future<T> extends Promise<StructuredDocument<T>> {
+ *   abort(): void;
+ *
+ *   async getStream(): ReadableStream | null;
+ * }
+ * ```
+ *
+ * ### StructuredDocuments
+ *
+ * A Future resolves with a `StructuredDataDocument` or rejects with a `StructuredErrorDocument`.
+ *
+ * ```ts
+ * interface StructuredDataDocument<T> {
+ *   request: ImmutableRequestInfo;
+ *   response: ImmutableResponseInfo;
+ *   content: T;
+ * }
+ * interface StructuredErrorDocument extends Error {
+ *   request: ImmutableRequestInfo;
+ *   response: ImmutableResponseInfo;
+ *   error: string | object;
+ * }
+ * type StructuredDocument<T> = StructuredDataDocument<T> | StructuredErrorDocument;
+ * ```
+ *
+ * @public
+ */
+class RequestManager {
+  /** @internal */
+
+  /** @internal */
+
+  /**
+   * A map of pending requests from request.id to their
+   * associated CacheHandler promise.
+   *
+   * This queue is managed by the CacheHandler
+   *
+   * @internal
+   */
+
+  /** @internal */
+
+  constructor(options) {
+    Object.assign(this, options);
+    this._pending = new Map();
+    this._deduped = new Map();
+    this._handlers = [];
+  }
+
+  /**
+   * Register a handler to use for primary cache intercept.
+   *
+   * Only one such handler may exist. If using the same
+   * RequestManager as the Store instance the Store
+   * registers itself as a Cache handler.
+   *
+   * @public
+   */
+  useCache(cacheHandler) {
+    cacheHandler[IS_CACHE_HANDLER] = true;
+    this._handlers.unshift(cacheHandler);
+    return this;
+  }
+
+  /**
+   * Register handler(s) to use when a request is issued.
+   *
+   * Handlers will be invoked in the order they are registered.
+   * Each Handler is given the opportunity to handle the request,
+   * curry the request, or pass along a modified request.
+   *
+   * @public
+   */
+  use(newHandlers) {
+    const handlers = this._handlers;
+    handlers.push(...newHandlers);
+    return this;
+  }
+
+  /**
+   * Issue a Request.
+   *
+   * Returns a Future that fulfills with a StructuredDocument
+   *
+   * @public
+   */
+  request(request) {
+    const handlers = this._handlers;
+    const controller = request.controller || new AbortController();
+    if (request.controller) {
+      delete request.controller;
+    }
+    const requestId = peekUniversalTransient('REQ_ID') ?? 0;
+    setUniversalTransient('REQ_ID', requestId + 1);
+    const context = {
+      controller,
+      response: null,
+      stream: null,
+      hasRequestedStream: false,
+      id: requestId,
+      identifier: null,
+      requester: request[EnableHydration] && request.store ? request.store : this
+    };
+    const promise = executeNextHandler(handlers, request, 0, context);
+
+    // the cache handler will set the result of the request synchronously
+    // if it is able to fulfill the request from the cache
+    const cacheResult = getRequestResult(requestId);
+    // const promise1 = store.request(myRequest);
+    // const promise2 = store.request(myRequest);
+    // promise1 === promise2; // false
+    // either we need to make promise1 === promise2, or we need to make sure that
+    // we need to have a way to key from request to result
+    // such that we can lookup the result here and return it if it exists
+    const finalPromise = upgradePromise(promise.then(result => {
+      setPromiseResult(finalPromise, {
+        isError: false,
+        result
+      });
+      clearRequestResult(requestId);
+      return result;
+    }, error => {
+      setPromiseResult(finalPromise, {
+        isError: true,
+        result: error
+      });
+      clearRequestResult(requestId);
+      throw error;
+    }), promise);
+    if (cacheResult) {
+      setPromiseResult(finalPromise, cacheResult);
+    }
+    return finalPromise;
+  }
+
+  /**
+   * This method exists so that the RequestManager can be created
+   * can be created by container/factory systems that expect to
+   * call a static `create` method to instantiate the class.
+   *
+   * Using `new RequestManager()` directly is preferred.
+   *
+   * @private
+   */
+  static create(options) {
+    return new this(options);
+  }
+}
+
+/**
+ * This type exists for internal use only for
+ * where intimate contracts still exist either for
+ * the Test Suite or for Legacy code.
+ *
+ * @private
+ */
+
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+
+// Mirage (or another Pretender-based fetch mock) may be used outside of a
+// `TESTING` build (e.g. `ember serve` in dev mode), so this override is
+// exposed unconditionally rather than gated to the `TESTING` env.
+// @ts-expect-error adding to globalThis
+globalThis.setWarpDriveIsMaybeMirage = setIsMaybeMirage;
+
+/**
+ * Options for setting up a Store instance with `useRecommendedStore`.
+ */
+
+/**
+ * Creates a configured Store class with recommended defaults
+ * for schema handling, reactivity, caching, and request management.
+ *
+ * ```ts
+ * import { useRecommendedStore } from '@warp-drive/core';
+ * import { JSONAPICache } from '@warp-drive/json-api';
+ *
+ * export const Store = useRecommendedStore({
+ *   cache: JSONAPICache,
+ *   schemas: [],
+ * });
+ * ```
+ */
+function useRecommendedStore(options, StoreKlass = Store) {
+  return class AppStore extends StoreKlass {
+    constructor(createArgs) {
+      super(createArgs);
+      // installed via defineProperty (rather than a class field/accessor) so that
+      // this lazy override of the inherited `requestManager` field does not
+      // conflict with the documented pattern of assigning it directly on
+      // consumer-authored Store subclasses. The setter preserves the ability
+      // to replace `requestManager` outright after construction.
+      let requestManager;
+      Object.defineProperty(this, 'requestManager', {
+        configurable: true,
+        enumerable: true,
+        get: () => {
+          if (!requestManager) {
+            const handlers = typeof options.handlers === 'function' ? options.handlers(this) : options.handlers ?? [];
+            requestManager = new RequestManager().use([...handlers, Fetch]).useCache(CacheHandler);
+          }
+          return requestManager;
+        },
+        set: value => {
+          requestManager = value;
+        }
+      });
+    }
+    lifetimes = options.policy ?? new DefaultCachePolicy({
+      apiCacheHardExpires: 15 * 60 * 1000,
+      // 15 minutes
+      apiCacheSoftExpires: 1 * 30 * 1000,
+      // 30 seconds
+      constraints: {
+        headers: {
+          'X-WarpDrive-Expires': true,
+          'Cache-Control': true,
+          Expires: true
+        }
+      }
+    });
+    createSchemaService() {
+      const schema = new SchemaService();
+      registerDerivations(schema);
+      if (options.schemas) schema.registerResources(options.schemas);
+      if (options.traits) {
+        for (const trait of options.traits) {
+          schema.registerTrait(trait);
+        }
+      }
+      if (options.derivations) {
+        for (const derivation of options.derivations) {
+          schema.registerDerivation(derivation);
+        }
+      }
+      if (options.transformations) {
+        for (const transformation of options.transformations) {
+          schema.registerTransformation(transformation);
+        }
+      }
+      if (options.hashFns) {
+        for (const hashFn of options.hashFns) {
+          schema.registerHashFn(hashFn);
+        }
+      }
+      if (options.CAUTION_MEGA_DANGER_ZONE_extensions) {
+        for (const extension of options.CAUTION_MEGA_DANGER_ZONE_extensions) {
+          schema.CAUTION_MEGA_DANGER_ZONE_registerExtension(extension);
+        }
+      }
+      return schema;
+    }
+    createCache(capabilities) {
+      // eslint-disable-next-line new-cap
+      return new options.cache(capabilities);
+    }
+    instantiateRecord(key, createArgs) {
+      return instantiateRecord(this, key, createArgs);
+    }
+    teardownRecord(record) {
+      return teardownRecord(record);
+    }
+  };
+}
+export { setIdentifierForgetMethod as A, setIdentifierResetMethod as B, CacheHandler as C, setKeyInfoForResource as D, Fetch as F, RecordArrayManager as R, Store as S, _clearCaches as _, isRequestKey as a, assertPrivateStore as b, coerceId as c, isPrivateStore as d, ensureStringId as e, fastPush as f, assertPrivateCapabilities as g, setRecordIdentifier as h, isResourceKey as i, StoreMap as j, createLegacyManyArray as k, checkout as l, instantiateRecord as m, normalizeModelName as n, SchemaService as o, fromIdentity as p, registerDerivations as q, recordIdentifierFor as r, storeFor as s, teardownRecord as t, commit as u, RequestManager as v, withDefaults as w, useRecommendedStore as x, setIdentifierGenerationMethod as y, setIdentifierUpdateMethod as z };