@warp-drive/core 5.9.0-alpha.16 → 5.9.0-alpha.18

package/dist/unpkg/prod-deprecated/{schema-h0nuUTCj.js → index-CZkDXZog.js}

@@ -1,12 +1,14 @@
-import { d as defineGate, w as withSignalStore, n as notifyInternalSignal, p as peekInternalSignal, b as willSyncFlushWatchers, e as getOrCreateInternalSignal, f as consumeInternalSignal, h as createInternalSignal, A as ARRAY_SIGNAL, S as Signals, i as createSignalDescriptor, j as defineSignal, k as entangleSignal, l as entangleInitiallyStaleSignal, O as OBJECT_SIGNAL, m as createInternalMemo } from "./-leaked-D_5Yrs5c.js";
+import { d as defineGate, w as withSignalStore, n as notifyInternalSignal, p as peekInternalSignal, b as willSyncFlushWatchers, e as getOrCreateInternalSignal, f as consumeInternalSignal, h as createInternalSignal, A as ARRAY_SIGNAL, S as Signals, i as createSignalDescriptor, j as defineSignal, k as entangleSignal, l as entangleInitiallyStaleSignal, O as OBJECT_SIGNAL, m as createInternalMemo } from "./-leaked-BNVttukY.js";
 import { EnableHydration, SkipCache, STRUCTURED } from './types/request.js';
-import { peekTransient, setTransient, getOrSetGlobal } from './types/-private.js';
-import { isResourceSchema } from './types/schema/fields.js';
+import { peekTransient, setTransient, getOrSetGlobal, peekUniversalTransient, setUniversalTransient } from './types/-private.js';
 import { D as Destroy, a as Context, S as SOURCE, C as Checkout, b as Commit } from "./-private-3C1OkYtZ.js";
-import { w as withBrand } from "./request-BrJSCG6r.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 { dasherize } from './utils/string.js';
-import './types/runtime.js';
+import { isResourceSchema } from './types/schema/fields.js';
 import { RecordStore, Type } from './types/symbols.js';
 import * as _importSync20 from '@ember/object';
 function urlFromLink(link) {
@@ -4242,6 +4244,337 @@ function upgradeInstanceCaches(cache) {
   }
   return withReferences;
 }
+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
+    }]
+  });
+}
 function isNonEmptyString(str) {
   return Boolean(str && typeof str === 'string');
 }
@@ -5081,14 +5414,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);
 }
@@ -5720,6 +6080,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,
@@ -6388,6 +6759,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',
@@ -6402,6 +6796,14 @@ const TypeField = {
     key: 'type'
   }
 };
+const IdentifierField = {
+  type: '@identity',
+  name: '$key',
+  kind: 'derived',
+  options: {
+    key: '^'
+  }
+};
 const DefaultIdentityField = {
   name: 'id',
   kind: '@id'
@@ -6570,6 +6972,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;
 }
@@ -6954,4 +7357,484 @@ function mergeMap(base, toApply) {
     base.set(key, value);
   }
 }
-export { setIdentifierResetMethod as A, setKeyInfoForResource as B, RecordArrayManager as R, SchemaService as S, _clearCaches as _, commit as a, Store as b, checkout as c, recordIdentifierFor as d, isRequestKey as e, fromIdentity as f, constructResource as g, coerceId as h, isResourceKey as i, ensureStringId as j, fastPush as k, assertPrivateStore as l, isPrivateStore as m, assertPrivateCapabilities as n, setRecordIdentifier as o, StoreMap as p, normalizeModelName as q, registerDerivations as r, storeFor as s, createLegacyManyArray as t, ReactiveResource as u, createReactiveDocument as v, withDefaults as w, setIdentifierGenerationMethod as x, setIdentifierUpdateMethod as y, setIdentifierForgetMethod 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 {
+    requestManager = new RequestManager().use([...(options.handlers ?? []), Fetch]).useCache(CacheHandler);
+    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 { setIdentifierUpdateMethod as A, setIdentifierForgetMethod as B, CacheHandler as C, setIdentifierResetMethod as D, setKeyInfoForResource as E, Fetch as F, RecordArrayManager as R, SchemaService as S, _clearCaches as _, commit as a, Store as b, checkout as c, recordIdentifierFor as d, isResourceKey as e, fromIdentity as f, isRequestKey as g, constructResource as h, instantiateRecord as i, coerceId as j, ensureStringId as k, fastPush as l, assertPrivateStore as m, isPrivateStore as n, assertPrivateCapabilities as o, setRecordIdentifier as p, StoreMap as q, registerDerivations as r, storeFor as s, teardownRecord as t, normalizeModelName as u, createLegacyManyArray as v, withDefaults as w, RequestManager as x, useRecommendedStore as y, setIdentifierGenerationMethod as z };