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

package/dist/unpkg/prod/store.js

@@ -0,0 +1,437 @@
+import { LRUCache } from './utils/string.js';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+
+/**
+ * Interface of a parsed Cache-Control header value.
+ *
+ * - [MDN Cache-Control Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control)
+ */
+
+const NUMERIC_KEYS = new Set(['max-age', 's-maxage', 'stale-if-error', 'stale-while-revalidate']);
+
+/**
+ *  Parses a string Cache-Control header value into an object with the following structure:
+ *
+ * ```ts
+ * interface CacheControlValue {
+ *   immutable?: boolean;
+ *   'max-age'?: number;
+ *   'must-revalidate'?: boolean;
+ *   'must-understand'?: boolean;
+ *   'no-cache'?: boolean;
+ *   'no-store'?: boolean;
+ *   'no-transform'?: boolean;
+ *   'only-if-cached'?: boolean;
+ *   private?: boolean;
+ *   'proxy-revalidate'?: boolean;
+ *   public?: boolean;
+ *   's-maxage'?: number;
+ *   'stale-if-error'?: number;
+ *   'stale-while-revalidate'?: number;
+ * }
+ * ```
+ *
+ * See also {@link CacheControlValue} and [Response Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#response_directives)
+ *
+ * @public
+ */
+function parseCacheControl(header) {
+  return CACHE_CONTROL_CACHE.get(header);
+}
+const CACHE_CONTROL_CACHE = new LRUCache(header => {
+  let key = '';
+  let value = '';
+  let isParsingKey = true;
+  const cacheControlValue = {};
+  for (let i = 0; i < header.length; i++) {
+    const char = header.charAt(i);
+    if (char === ',') {
+      isParsingKey = true;
+      // @ts-expect-error TS incorrectly thinks that optional keys must have a type that includes undefined
+      cacheControlValue[key] = NUMERIC_KEYS.has(key) ? parseCacheControlValue(value) : true;
+      key = '';
+      value = '';
+      continue;
+    } else if (char === '=') {
+      isParsingKey = false;
+    } else if (char === ' ' || char === `\t` || char === `\n`) {
+      continue;
+    } else if (isParsingKey) {
+      key += char;
+    } else {
+      value += char;
+    }
+    if (i === header.length - 1) {
+      // @ts-expect-error TS incorrectly thinks that optional keys must have a type that includes undefined
+      cacheControlValue[key] = NUMERIC_KEYS.has(key) ? parseCacheControlValue(value) : true;
+    }
+  }
+  return cacheControlValue;
+}, 200);
+function parseCacheControlValue(stringToParse) {
+  const parsedValue = Number.parseInt(stringToParse);
+  if (Number.isNaN(parsedValue) || parsedValue < 0) {
+    return 0;
+  }
+  return parsedValue;
+}
+function isExpired(cacheKey, request, config) {
+  const {
+    constraints
+  } = config;
+  if (constraints?.isExpired) {
+    const result = constraints.isExpired(request);
+    if (result !== null) {
+      return result;
+    }
+  }
+  const {
+    headers
+  } = request.response;
+  if (!headers) {
+    // if we have no headers then both the headers based expiration
+    // and the time based expiration will be considered expired
+    return true;
+  }
+
+  // check for X-WarpDrive-Expires
+  const now = Date.now();
+  const date = headers.get('Date');
+  if (constraints?.headers) {
+    if (constraints.headers['X-WarpDrive-Expires']) {
+      const xWarpDriveExpires = headers.get('X-WarpDrive-Expires');
+      if (xWarpDriveExpires) {
+        const expirationTime = new Date(xWarpDriveExpires).getTime();
+        const result = now >= expirationTime;
+        return result;
+      }
+    }
+
+    // check for Cache-Control
+    if (constraints.headers['Cache-Control']) {
+      const cacheControl = headers.get('Cache-Control');
+      const age = headers.get('Age');
+      if (cacheControl && age && date) {
+        const cacheControlValue = parseCacheControl(cacheControl);
+
+        // max-age and s-maxage are stored in
+        const maxAge = cacheControlValue['max-age'] || cacheControlValue['s-maxage'];
+        if (maxAge) {
+          // age is stored in seconds
+          const ageValue = parseInt(age, 10);
+          if (!Number.isNaN(ageValue) && ageValue >= 0) {
+            const dateValue = new Date(date).getTime();
+            const expirationTime = dateValue + (maxAge - ageValue) * 1000;
+            const result = now >= expirationTime;
+            return result;
+          }
+        }
+      }
+    }
+
+    // check for Expires
+    if (constraints.headers.Expires) {
+      const expires = headers.get('Expires');
+      if (expires) {
+        const expirationTime = new Date(expires).getTime();
+        const result = now >= expirationTime;
+        return result;
+      }
+    }
+  }
+
+  // check for Date
+  if (!date) {
+    return true;
+  }
+  let expirationTime = config.apiCacheHardExpires;
+  const time = new Date(date).getTime();
+  const deadline = time + expirationTime;
+  const result = now >= deadline;
+  return result;
+}
+
+/**
+ * The constraint options for {@link PolicyConfig.constraints}
+ */
+
+/**
+ * The configuration options for the {@link DefaultCachePolicy}
+ *
+ * ```ts [app/services/store.ts]
+ * import { Store } from '@warp-drive/core';
+ * import { DefaultCachePolicy } from '@warp-drive/core/store'; // [!code focus]
+ *
+ * export default class AppStore extends Store {
+ *   lifetimes = new DefaultCachePolicy({ // [!code focus:3]
+ *     // ... PolicyConfig Settings ... //
+ *   });
+ * }
+ * ```
+ *
+ */
+
+/**
+ * A basic {@link CachePolicy} that can be added to the Store service.
+ *
+ * ```ts [app/services/store.ts]
+ * import { Store } from '@warp-drive/core';
+ * import { DefaultCachePolicy } from '@warp-drive/core/store'; // [!code focus]
+ *
+ * export default class AppStore extends Store {
+ *   lifetimes = new DefaultCachePolicy({ // [!code focus:5]
+ *     apiCacheSoftExpires: 30_000,
+ *     apiCacheHardExpires: 60_000,
+ *     // ... Other PolicyConfig Settings ... //
+ *   });
+ * }
+ * ```
+ *
+ * :::tip 💡 TIP
+ * Date headers do not have millisecond precision, so expiration times should
+ * generally be larger than 1000ms.
+ * :::
+ *
+ * See also {@link PolicyConfig} for configuration options.
+ *
+ * ### The Mechanics
+ *
+ * This policy determines staleness based on various configurable constraints falling back to a simple
+ * check of the time elapsed since the request was last received from the API using the `date` header
+ * from the last response.
+ *
+ * :::tip 💡 TIP
+ * The {@link Fetch} handler provided by `@warp-drive/core` will automatically
+ * add the `date` header to responses if it is not present.
+ * :::
+ *
+ * - For manual override of reload see {@link CacheOptions.reload | cacheOptions.reload}
+ * - For manual override of background reload see {@link CacheOptions.backgroundReload | cacheOptions.backgroundReload}
+ *
+ * In order expiration is determined by:
+ *
+ * ```md
+ * Is explicitly invalidated by `cacheOptions.reload`
+ *   ↳ (if falsey) if the request has been explicitly invalidated
+ *      since the last request (see Automatic Invalidation below)
+ *   ↳ (if false) (If Active) isExpired function
+ *   ↳ (if null) (If Active) X-WarpDrive-Expires header
+ *   ↳ (if null) (If Active) Cache-Control header
+ *   ↳ (if null) (If Active) Expires header
+ *   ↳ (if null) Date header + apiCacheHardExpires < current time
+ *
+ *   -- <if above is false, a background request is issued if> --
+ *
+ *   ↳ is invalidated by `cacheOptions.backgroundReload`
+ *   ↳ (if falsey) Date header + apiCacheSoftExpires < current time
+ * ```
+ *
+ * ### Automatic Invalidation / Entanglement
+ *
+ * It also invalidates any request with an {@link RequestInfo.op | OpCode} of `"query"`
+ * for which {@link CacheOptions.types | cacheOptions.types} was provided
+ * when a request with an `OpCode` of `"createRecord"` is successful and also includes
+ * a matching type in its own `cacheOptions.types` array.
+
+ * :::tip 💡 TIP
+ * Abstracting this behavior via builders is recommended to ensure consistency.
+ * :::
+ *
+ * ### Testing
+ *
+ * In Testing environments:
+ *
+ * - `apiCacheSoftExpires` will always be `false`
+ * - `apiCacheHardExpires` will use the `apiCacheSoftExpires` value.
+ *
+ * This helps reduce flakiness and produce predictably rendered results in test suites.
+ *
+ * Requests that specifically set `cacheOptions.backgroundReload = true` will
+ * still be background reloaded in tests.
+ *
+ * This behavior can be opted out of by setting `disableTestOptimization = true`
+ * in the policy config.
+ *
+ * @public
+ */
+class DefaultCachePolicy {
+  /**
+   * @internal
+   */
+
+  /**
+   * @internal
+   */
+
+  /**
+   * @internal
+   */
+  _getStore(store) {
+    let set = this._stores.get(store);
+    if (!set) {
+      set = {
+        invalidated: new Set(),
+        types: new Map()
+      };
+      this._stores.set(store, set);
+    }
+    return set;
+  }
+  constructor(config) {
+    this._stores = new WeakMap();
+    const _config = arguments.length === 1 ? config : arguments[1];
+    this.config = _config;
+  }
+
+  /**
+   * Invalidate a request by its CacheKey for the given store instance.
+   *
+   * While the store argument may seem redundant, the CachePolicy
+   * is designed to be shared across multiple stores / forks
+   * of the store.
+   *
+   * ```ts
+   * store.lifetimes.invalidateRequest(store, cacheKey);
+   * ```
+   *
+   * @public
+   */
+  invalidateRequest(cacheKey, store) {
+    this._getStore(store).invalidated.add(cacheKey);
+  }
+
+  /**
+   * Invalidate all requests associated to a specific type
+   * for a given store instance.
+   *
+   * While the store argument may seem redundant, the CachePolicy
+   * is designed to be shared across multiple stores / forks
+   * of the store.
+   *
+   * This invalidation is done automatically when using this service
+   * for both the {@link CacheHandler} and the [NetworkHandler](/api/@warp-drive/legacy/compat/variables/LegacyNetworkHandler).
+   *
+   * ```ts
+   * store.lifetimes.invalidateRequestsForType(store, 'person');
+   * ```
+   *
+   * @public
+   */
+  invalidateRequestsForType(type, store) {
+    const storeCache = this._getStore(store);
+    const set = storeCache.types.get(type);
+    const notifications = store.notifications;
+    if (set) {
+      // TODO batch notifications
+      set.forEach(id => {
+        storeCache.invalidated.add(id);
+        // @ts-expect-error
+        notifications.notify(id, 'invalidated', null);
+      });
+    }
+  }
+
+  /**
+   * Invoked when a request has been fulfilled from the configured request handlers.
+   * This is invoked by the CacheHandler for both foreground and background requests
+   * once the cache has been updated.
+   *
+   * Note, this is invoked by the {@link CacheHandler} regardless of whether
+   * the request has a cache-key.
+   *
+   * This method should not be invoked directly by consumers.
+   *
+   * @public
+   */
+  didRequest(request, response, cacheKey, store) {
+    // if this is a successful createRecord request, invalidate the cacheKey for the type
+    if (request.op === 'createRecord') {
+      const statusNumber = response?.status ?? 0;
+      if (statusNumber >= 200 && statusNumber < 400) {
+        const types = new Set(request.records?.map(r => r.type));
+        const additionalTypes = request.cacheOptions?.types;
+        additionalTypes?.forEach(type => {
+          types.add(type);
+        });
+        types.forEach(type => {
+          this.invalidateRequestsForType(type, store);
+        });
+      }
+
+      // add this document's cacheKey to a map for all associated types
+      // it is recommended to only use this for queries
+    } else if (cacheKey && request.cacheOptions?.types?.length) {
+      const storeCache = this._getStore(store);
+      request.cacheOptions?.types.forEach(type => {
+        const set = storeCache.types.get(type);
+        if (set) {
+          set.add(cacheKey);
+          storeCache.invalidated.delete(cacheKey);
+        } else {
+          storeCache.types.set(type, new Set([cacheKey]));
+        }
+      });
+    }
+  }
+
+  /**
+   * Invoked to determine if the request may be fulfilled from cache
+   * if possible.
+   *
+   * Note, this is only invoked by the {@link CacheHandler} if the request has
+   * a cache-key.
+   *
+   * If no cache entry is found or the entry is hard expired,
+   * the request will be fulfilled from the configured request handlers
+   * and the cache will be updated before returning the response.
+   *
+   * @public
+   * @return true if the request is considered hard expired
+   */
+  isHardExpired(cacheKey, store) {
+    // if we are explicitly invalidated, we are hard expired
+    const storeCache = this._getStore(store);
+    if (storeCache.invalidated.has(cacheKey)) {
+      return true;
+    }
+    const cache = store.cache;
+    const cached = cache.peekRequest(cacheKey);
+    if (!cached?.response) {
+      return true;
+    }
+    return isExpired(cacheKey, cached, this.config);
+  }
+
+  /**
+   * Invoked if `isHardExpired` is false to determine if the request
+   * should be update behind the scenes if cache data is already available.
+   *
+   * Note, this is only invoked by the {@link CacheHandler} if the request has
+   * a cache-key.
+   *
+   * If true, the request will be fulfilled from cache while a backgrounded
+   * request is made to update the cache via the configured request handlers.
+   *
+   * @public
+   * @return true if the request is considered soft expired
+   */
+  isSoftExpired(cacheKey, store) {
+    const cache = store.cache;
+    const cached = cache.peekRequest(cacheKey);
+    if (cached?.response) {
+      const date = cached.response.headers.get('date');
+      if (!date) {
+        return true;
+      } else {
+        const time = new Date(date).getTime();
+        const now = Date.now();
+        const deadline = time + this.config.apiCacheSoftExpires;
+        const result = now >= deadline;
+        return result;
+      }
+    }
+    return true;
+  }
+}
+export { DefaultCachePolicy, parseCacheControl };

package/dist/unpkg/prod/types/-private.js

@@ -0,0 +1,49 @@
+const name = "@warp-drive/core";
+const version = "5.8.0-alpha.40";
+
+// in testing mode, we utilize globals to ensure only one copy exists of
+// these maps, due to bugs in ember-auto-import
+
+const GlobalRef = globalThis;
+const UniversalCache = GlobalRef.__warpDrive_universalCache = GlobalRef.__warpDrive_universalCache ?? {};
+
+// in order to support mirror packages, we ensure that each
+// unique package name has its own global cache
+GlobalRef[name] = GlobalRef[name] ?? {
+  __version: version
+};
+const GlobalSink = GlobalRef[name];
+const ModuleScopedCaches = GlobalSink.__warpDrive_ModuleScopedCaches ?? {};
+{
+  if (GlobalSink.__warpDrive_hasOtherCopy) {
+    throw new Error('Multiple copies of WarpDrive detected, the application will malfunction.');
+  }
+  GlobalSink.__warpDrive_hasOtherCopy = true;
+}
+function getOrSetGlobal(key, value) {
+  {
+    return value;
+  }
+}
+function peekTransient(key) {
+  const globalKey = `(transient) ${key}`;
+  return ModuleScopedCaches[globalKey] ?? null;
+}
+function setTransient(key, value) {
+  const globalKey = `(transient) ${key}`;
+  return ModuleScopedCaches[globalKey] = value;
+}
+function getOrSetUniversal(key, value) {
+  {
+    return value;
+  }
+}
+function peekUniversalTransient(key) {
+  const globalKey = `(transient) ${key}`;
+  return UniversalCache[globalKey] ?? null;
+}
+function setUniversalTransient(key, value) {
+  const globalKey = `(transient) ${key}`;
+  return UniversalCache[globalKey] = value;
+}
+export { getOrSetGlobal, getOrSetUniversal, peekTransient, peekUniversalTransient, setTransient, setUniversalTransient };

package/dist/unpkg/prod/types/identifier.js

@@ -0,0 +1,61 @@
+// provided for additional debuggability
+const DEBUG_CLIENT_ORIGINATED = Symbol('record-originated-on-client');
+const DEBUG_KEY_TYPE = Symbol('key-type');
+const DEBUG_STALE_CACHE_OWNER = Symbol('warpDriveStaleCache');
+function ProdSymbol(str, debugStr) {
+  return str;
+}
+
+// also present in production
+const CACHE_OWNER = ProdSymbol('__$co');
+
+/**
+ * A referentially stable object with a unique string (lid) that can be used
+ * as a reference to request data in the cache.
+ *
+ * Only requests that are assigned a RequestKey are retrievable/replayable from
+ * the cache, though requests without RequestKeys may still update cache state.
+ *
+ * @public
+ */
+
+/** @deprecated use {@link RequestKey} */
+
+/**
+ * Used when an ResourceKey is known to be the stable version
+ */
+
+/**
+ * Used when a ResourceKey was not created locally as part
+ * of a call to store.createRecord
+ *
+ * Distinguishing between this ResourceKey and one for a client created
+ * resource that was created with an ID is generally speaking not possible
+ * at runtime, so anything with an ID typically narrows to this.
+ */
+
+/** @deprecated use {@link PersistedResourceKey} */
+
+/**
+ * Used when a ResourceKey was created locally
+ * (by a call to store.createRecord).
+ *
+ * It is possible in rare circumstances to have a ResourceKey
+ * that is not for a new record but does not have an ID. This would
+ * happen if a user intentionally created one for use with a secondary-index
+ * prior to the record having been fully loaded.
+ */
+
+/**
+ * A referentially stable object with a unique string (lid) that can be used
+ * as a reference to data in the cache.
+ *
+ * Every resource has a unique ResourceKey, and ResourceKeys may refer
+ * to data that has never been loaded (for instance, in an async relationship).
+ *
+ * @public
+ */
+
+/** @deprecated use {@link ResourceKey} */
+
+export { CACHE_OWNER, DEBUG_CLIENT_ORIGINATED, DEBUG_KEY_TYPE, DEBUG_STALE_CACHE_OWNER };