@warp-drive/core 5.8.0-alpha.3 → 5.8.0-alpha.5

package/dist/store/-private.js

@@ -1,2 +1,2 @@
-export { C as CacheHandler, D as DISPOSE, R as RecordArrayManager, E as Signals, S as Store, k as StoreMap, _ as _clearCaches, n as _deprecatingNormalize, h as assertPrivateCapabilities, d as assertPrivateStore, b as coerceId, c as constructResource, J as consumeInternalSignal, G as createInternalMemo, l as createLegacyManyArray, q as createRequestSubscription, A as defineGate, B as defineNonEnumerableSignal, z as defineSignal, e as ensureStringId, y as entangleInitiallyStaleSignal, x as entangleSignal, f as fastPush, w as gate, K as getOrCreateInternalSignal, p as getPromiseState, t as getRequestState, g as isPrivateStore, a as isRequestKey, i as isResourceKey, m as log, o as logGroup, v as memoized, I as notifyInternalSignal, F as peekInternalSignal, r as recordIdentifierFor, j as setRecordIdentifier, u as signal, s as storeFor, H as withSignalStore } from "../request-state-CUuZzgvE.js";
+export { C as CacheHandler, D as DISPOSE, R as RecordArrayManager, E as Signals, S as Store, k as StoreMap, _ as _clearCaches, n as _deprecatingNormalize, h as assertPrivateCapabilities, d as assertPrivateStore, b as coerceId, c as constructResource, J as consumeInternalSignal, G as createInternalMemo, l as createLegacyManyArray, q as createRequestSubscription, A as defineGate, B as defineNonEnumerableSignal, z as defineSignal, e as ensureStringId, y as entangleInitiallyStaleSignal, x as entangleSignal, f as fastPush, w as gate, K as getOrCreateInternalSignal, p as getPromiseState, t as getRequestState, g as isPrivateStore, a as isRequestKey, i as isResourceKey, m as log, o as logGroup, v as memoized, I as notifyInternalSignal, F as peekInternalSignal, r as recordIdentifierFor, j as setRecordIdentifier, u as signal, s as storeFor, H as withSignalStore } from "../index-MiSBsI57.js";
 export { A as ARRAY_SIGNAL, O as OBJECT_SIGNAL, w as waitFor } from "../configure-C3x8YXzL.js";

package/dist/store.js

@@ -1,6 +1,12 @@
 import { deprecate } from '@ember/debug';
 import { LRUCache } from './utils/string.js';
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
+
+/**
+ * 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']);
 
 /**
@@ -25,6 +31,8 @@ const NUMERIC_KEYS = new Set(['max-age', 's-maxage', 'stale-if-error', 'stale-wh
  * }
  * ```
  *
+ * See also {@link CacheControlValue} and [Response Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#response_directives)
+ *
  * @public
  * @param {String} header
  * @return {CacheControlValue}
@@ -231,73 +239,91 @@ function isExpired(cacheKey, request, config) {
 /**
  * The configuration options for the {@link DefaultCachePolicy}
  *
- * ```ts
- * import { DefaultCachePolicy } from '@warp-drive/core/store';
+ * ```ts [app/services/store.ts]
+ * import { Store } from '@warp-drive/core';
+ * import { DefaultCachePolicy } from '@warp-drive/core/store'; // [!code focus]
  *
- * new DefaultCachePolicy({
- *   // ... PolicyConfig Settings ... //
- * });
+ * export default class AppStore extends Store {
+ *   lifetimes = new DefaultCachePolicy({ // [!code focus:3]
+ *     // ... PolicyConfig Settings ... //
+ *   });
+ * }
  * ```
  *
  */
 
 /**
- * A basic CachePolicy that can be added to the Store service.
- *
- * Determines staleness based on time since the request was last received from the API
- * using the `date` header.
+ * A basic {@link CachePolicy} that can be added to the Store service.
  *
- * Determines expiration based on configured constraints as well as a time based
- * expiration strategy based on the `date` header.
- *
- * In order expiration is determined by:
+ * ```ts [app/services/store.ts]
+ * import { Store } from '@warp-drive/core';
+ * import { DefaultCachePolicy } from '@warp-drive/core/store'; // [!code focus]
  *
- * - Is explicitly invalidated
- * -  ↳ (if null) isExpired function \<IF Constraint Active>
- * -  ↳ (if null) X-WarpDrive-Expires header \<IF Constraint Active>
- * -  ↳ (if null) Cache-Control header \<IF Constraint Active>
- * -  ↳ (if null) Expires header \<IF Constraint Active>
- * -  ↳ (if null) Date header + apiCacheHardExpires \< current time
+ * export default class AppStore extends Store {
+ *   lifetimes = new DefaultCachePolicy({ // [!code focus:5]
+ *     apiCacheSoftExpires: 30_000,
+ *     apiCacheHardExpires: 60_000,
+ *     // ... Other PolicyConfig Settings ... //
+ *   });
+ * }
+ * ```
  *
- * Invalidates any request for which `cacheOptions.types` was provided when a createRecord
- * request for that type is successful.
+ * :::tip 💡 TIP
+ * Date headers do not have millisecond precision, so expiration times should
+ * generally be larger than 1000ms.
+ * :::
  *
- * For this to work, the `createRecord` request must include the `cacheOptions.types` array
- * with the types that should be invalidated, or its request should specify the ResourceKeys
- * of the records that are being created via `records`. Providing both is valid.
+ * See also {@link PolicyConfig} for configuration options.
  *
- * > [!NOTE]
- * > only requests that had specified `cacheOptions.types` and occurred prior to the
- * > createRecord request will be invalidated. This means that a given request should always
- * > specify the types that would invalidate it to opt into this behavior. Abstracting this
- * > behavior via builders is recommended to ensure consistency.
+ * ### The Mechanics
  *
- * This allows the Store's CacheHandler to determine if a request is expired and
- * should be refetched upon next request.
+ * 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.
  *
- * The `Fetch` handler provided by `@warp-drive/core` will automatically
+ * :::tip 💡 TIP
+ * The {@link Fetch} handler provided by `@warp-drive/core` will automatically
  * add the `date` header to responses if it is not present.
+ * :::
  *
- * > [!NOTE]
- * > Date headers do not have millisecond precision, so expiration times should
- * > generally be larger than 1000ms.
+ * - For manual override of reload see {@link RequestInfo.cacheOptions.reload | cacheOptions.reload}
+ * - For manual override of background reload see {@link RequestInfo.cacheOptions.backgroundReload | cacheOptions.backgroundReload}
  *
- * Usage:
+ * In order expiration is determined by:
  *
- * ```ts
- * import { Store } from '@warp-drive/core';
- * import { DefaultCachePolicy } from '@warp-drive/core/store';
+ * ```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
  *
- * export class AppStore extends Store {
- *   lifetimes = new DefaultCachePolicy({
- *     apiCacheSoftExpires: 30_000,
- *     apiCacheHardExpires: 60_000
- *   });
- * }
+ *   -- <if above is false, a background request is issued if> --
+ *
+ *   ↳ is invalidated by `cacheOptions.backgroundReload`
+ *   ↳ (if falsey) Date header + apiCacheSoftExpires < current time
  * ```
  *
- * In Testing environments, the `apiCacheSoftExpires` will always be `false`
- * and `apiCacheHardExpires` will use the `apiCacheSoftExpires` value.
+ * ### Automatic Invalidation / Entanglement
+ *
+ * It also invalidates any request with an {@link RequestInfo.op | OpCode} of `"query"`
+ * for which {@link RequestInfo.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.
  *
@@ -310,6 +336,17 @@ function isExpired(cacheKey, request, config) {
  * @public
  */
 class DefaultCachePolicy {
+  /**
+   * @internal
+   */
+
+  /**
+   * @internal
+   */
+
+  /**
+   * @internal
+   */
   _getStore(store) {
     let set = this._stores.get(store);
     if (!set) {

package/dist/types/-private.js

@@ -1,6 +1,6 @@
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
 const name = "@warp-drive/core";
-const version = "5.8.0-alpha.3";
+const version = "5.8.0-alpha.5";
 
 // in testing mode, we utilize globals to ensure only one copy exists of
 // these maps, due to bugs in ember-auto-import

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warp-drive/core",
-  "version": "5.8.0-alpha.3",
+  "version": "5.8.0-alpha.5",
   "description": "Core package for WarpDrive | All the Universal Basics",
   "keywords": [
     "ember-addon"
@@ -37,13 +37,13 @@
   },
   "dependencies": {
     "@embroider/macros": "^1.18.1",
-    "@warp-drive/build-config": "5.8.0-alpha.3"
+    "@warp-drive/build-config": "5.8.0-alpha.5"
   },
   "devDependencies": {
     "@babel/core": "^7.28.3",
     "@babel/plugin-transform-typescript": "^7.28.0",
     "@babel/preset-typescript": "^7.27.1",
-    "@warp-drive/internal-config": "5.8.0-alpha.3",
+    "@warp-drive/internal-config": "5.8.0-alpha.5",
     "decorator-transforms": "^2.3.0",
     "ember-source": "~6.6.0",
     "expect-type": "^1.2.2",