@warp-drive/core 5.8.0-alpha.4 → 5.8.0-alpha.41

package/dist/unpkg/prod/handler-EU_8ncB2.js

@@ -0,0 +1,1619 @@
+import { i as isResourceKey, h as isRequestKey, C as CacheKeyManager, R as RecordArrayManager, I as InstanceCache, o as normalizeModelName, g as coerceId, q as getNewRecord, t as peekResourceKey, j as ensureStringId, a as recordIdentifierFor, u as createReactiveDocument } from "./schema-BSkHyoWz.js";
+import { getOrSetGlobal } from './types/-private.js';
+import { w as willSyncFlushWatchers } from "./-leaked-DUONXQDB.js";
+import { EnableHydration, SkipCache } from './types/request.js';
+import './types/runtime.js';
+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);
+}
+const Touching = getOrSetGlobal('Touching', Symbol('touching'));
+const RequestPromise = getOrSetGlobal('RequestPromise', Symbol('promise'));
+const EMPTY_ARR = [];
+function hasRecordIdentifier(op) {
+  return 'recordIdentifier' in op;
+}
+
+/**
+ * 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 */
+  _pending = new Map();
+  /** @internal */
+  _done = new Map();
+  /** @internal */
+  _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 = [];
+  }
+
+  /** @internal */
+  _flushRequest(req) {
+    req[Touching].forEach(identifier => {
+      const subscriptions = this._subscriptions.get(identifier);
+      if (subscriptions) {
+        subscriptions.forEach(callback => callback(req));
+      }
+    });
+  }
+
+  /** @internal */
+  _dequeue(identifier, request) {
+    const pending = this._pending.get(identifier);
+    this._pending.set(identifier, pending.filter(req => req !== request));
+  }
+
+  /** @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);
+    });
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * 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 */
+
+  /**
+   * 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(properties[prop]);
+        } else if (field.kind === 'belongsTo') {
+          properties[prop] = extractIdentifierFromRecord(properties[prop]);
+        }
+      }
+    }
+  }
+  return properties;
+}
+function extractIdentifiersFromRecords(records) {
+  return records.map(record => extractIdentifierFromRecord(record));
+}
+function extractIdentifierFromRecord(recordOrPromiseRecord) {
+  if (!recordOrPromiseRecord) {
+    return null;
+  }
+  const extract = recordIdentifierFor;
+  return extract(recordOrPromiseRecord);
+}
+const MUTATION_OPS = new Set(['createRecord', 'updateRecord', 'deleteRecord']);
+function calcShouldFetch(store, request, hasCachedValue, identifier) {
+  const {
+    cacheOptions
+  } = request;
+  return request.op && MUTATION_OPS.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.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
+    }]
+  });
+}
+export { CacheHandler as C, Store as S, assertPrivateStore as a, isPrivateStore as i };