@warp-drive-mirror/core 5.10.0-alpha.10 → 5.10.0-alpha.13

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

@@ -1,3 +1,3 @@
-import { A as normalizeModelName, C as isRequestKey, F as recordIdentifierFor, I as setRecordIdentifier, L as storeFor, M as ensureStringId, N as StoreMap, P as _clearCaches, R as assertPrivateCapabilities, S as fieldValueIdentity, _ as Store, b as RecordArrayManager, f as log, g as CacheHandler, h as constructResource, j as coerceId, m as createLegacyManyArray, p as logGroup, v as assertPrivateStore, w as isResourceKey, x as fastPush, y as isPrivateStore } from "../src-DGB6WvXW.js";
+import { A as normalizeModelName, C as isRequestKey, F as recordIdentifierFor, I as setRecordIdentifier, L as storeFor, M as ensureStringId, N as StoreMap, P as _clearCaches, R as assertPrivateCapabilities, S as fieldValueIdentity, _ as Store, b as RecordArrayManager, f as log, g as CacheHandler, h as constructResource, j as coerceId, m as createLegacyManyArray, p as logGroup, v as assertPrivateStore, w as isResourceKey, x as fastPush, y as isPrivateStore } from "../src-CoSpuocQ.js";
 
 export { CacheHandler, RecordArrayManager, Store, StoreMap, _clearCaches, normalizeModelName as _deprecatingNormalize, assertPrivateCapabilities, assertPrivateStore, coerceId, constructResource, createLegacyManyArray, ensureStringId, fastPush, fieldValueIdentity, isPrivateStore, isRequestKey, isResourceKey, log, logGroup, recordIdentifierFor, setRecordIdentifier, storeFor };

package/dist/unpkg/{prod-deprecated/store-BWhmb7Ob.js → prod/store-CQOsqdST.js}

@@ -5,6 +5,9 @@ import { LRUCache } from "./utils/string.js";
 * 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)
+*
+* @summary The directives of a `Cache-Control` header as an object of flags and second counts, as
+* returned by `parseCacheControl`.
 */
 const NUMERIC_KEYS = /* @__PURE__ */ new Set([
 	"max-age",
@@ -36,6 +39,8 @@ const NUMERIC_KEYS = /* @__PURE__ */ new Set([
 *
 * See also {@link CacheControlValue} and [Response Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#response_directives)
 *
+* @summary Parses a `Cache-Control` header string into a `CacheControlValue` object, caching results
+* per header string.
 * @public
 */
 function parseCacheControl(header) {
@@ -109,6 +114,9 @@ function isExpired(cacheKey, request, config) {
 /**
 * The configuration options for the {@link DefaultCachePolicy}
 *
+* The [Advanced Store Configuration](/guides/configuration/advanced#decide-how-long-requests-are-valid-for-with-a-cachepolicy)
+* guide shows a policy configured with them.
+*
 * ```ts [app/services/store.ts]
 * import { Store } from '@warp-drive-mirror/core';
 * import { DefaultCachePolicy } from '@warp-drive-mirror/core/store'; // [!code focus]
@@ -120,10 +128,15 @@ function isExpired(cacheKey, request, config) {
 * }
 * ```
 *
+* @summary Options for `DefaultCachePolicy`: soft and hard expiration times, header-based expiration
+* constraints, and test-mode behavior.
 */
 /**
 * A basic {@link CachePolicy} that can be added to the Store service.
 *
+* The [Advanced Store Configuration](/guides/configuration/advanced#decide-how-long-requests-are-valid-for-with-a-cachepolicy)
+* guide shows how to configure it.
+*
 * ```ts [app/services/store.ts]
 * import { Store } from '@warp-drive-mirror/core';
 * import { DefaultCachePolicy } from '@warp-drive-mirror/core/store'; // [!code focus]
@@ -202,6 +215,8 @@ function isExpired(cacheKey, request, config) {
 * This behavior can be opted out of by setting `disableTestOptimization = true`
 * in the policy config.
 *
+* @summary The built-in cache policy, which expires cached requests using expiration headers or time
+* since the response `date`, and invalidates queries after matching creates.
 * @public
 */
 var DefaultCachePolicy = class {
@@ -356,4 +371,4 @@ var DefaultCachePolicy = class {
 
 //#endregion
 export { parseCacheControl as n, DefaultCachePolicy as t };
-//# sourceMappingURL=store-BWhmb7Ob.js.map
+//# sourceMappingURL=store-CQOsqdST.js.map

package/dist/unpkg/prod/store-CQOsqdST.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-CQOsqdST.js","names":["LRUCache","NUMERIC_KEYS","Set","parseCacheControl","header","CACHE_CONTROL_CACHE","get","key","value","isParsingKey","cacheControlValue","i","length","char","charAt","has","parseCacheControlValue","stringToParse","parsedValue","Number","parseInt","isNaN","isExpired","cacheKey","request","config","constraints","result","headers","response","now","Date","date","xWarpDriveExpires","expirationTime","getTime","cacheControl","age","maxAge","ageValue","dateValue","Expires","expires","apiCacheHardExpires","time","deadline","DefaultCachePolicy","_getStore","store","set","_stores","invalidated","types","Map","constructor","WeakMap","_config","arguments","console","warn","invalidateRequest","add","invalidateRequestsForType","type","storeCache","notifications","forEach","id","notify","didRequest","op","statusNumber","status","records","map","r","additionalTypes","cacheOptions","delete","isHardExpired","cache","cached","peekRequest","isSoftExpired","apiCacheSoftExpires"],"sources":["../../../src/store/-private/default-cache-policy.ts"],"sourcesContent":["import { deprecate } from '@ember/debug';\n\nimport { LOG_CACHE_POLICY } from '@warp-drive-mirror/core/build-config/debugging';\nimport { TESTING } from '@warp-drive-mirror/core/build-config/env';\nimport { assert } from '@warp-drive-mirror/core/build-config/macros';\n\n// oxlint-disable-next-line no-unused-vars\nimport type { CacheHandler, CachePolicy } from '../-private';\n// oxlint-disable-next-line no-unused-vars\nimport type { Fetch } from '../../request/-private/fetch';\nimport type { Cache } from '../../types/cache';\nimport type { RequestKey, ResourceKey } from '../../types/identifier';\nimport type {\n  // oxlint-disable-next-line no-unused-vars\n  CacheOptions,\n  ImmutableRequestInfo,\n  // oxlint-disable-next-line no-unused-vars\n  RequestInfo,\n  ResponseInfo,\n  StructuredDocument,\n} from '../../types/request';\nimport type { ResourceDocument } from '../../types/spec/document';\nimport { LRUCache } from '../../utils/string';\n\ntype UnsubscribeToken = object;\ntype CacheOperation = 'added' | 'removed' | 'updated' | 'state';\ntype DocumentCacheOperation = 'invalidated' | 'added' | 'removed' | 'updated' | 'state';\n\nexport interface NotificationCallback {\n  (resourceKey: ResourceKey, notificationType: 'attributes' | 'relationships', key?: string): void;\n  (resourceKey: ResourceKey, notificationType: 'errors' | 'meta' | 'identity' | 'state'): void;\n  // (resourceKey: ResourceKey, notificationType: NotificationType, key?: string): void;\n}\n\ninterface ResourceOperationCallback {\n  // resource updates\n  (resourceKey: ResourceKey, notificationType: CacheOperation): void;\n}\n\ninterface DocumentOperationCallback {\n  // document updates\n  (cacheKey: RequestKey, notificationType: DocumentCacheOperation): void;\n}\n\ntype NotificationManager = {\n  subscribe(resourceKey: ResourceKey, callback: NotificationCallback): UnsubscribeToken;\n  subscribe(cacheKey: 'resource', callback: ResourceOperationCallback): UnsubscribeToken;\n  subscribe(cacheKey: 'document' | RequestKey, callback: DocumentOperationCallback): UnsubscribeToken;\n\n  notify(cacheKey: ResourceKey, value: 'attributes' | 'relationships', key?: string): boolean;\n  notify(cacheKey: ResourceKey, value: 'errors' | 'meta' | 'identity' | 'state'): boolean;\n  notify(cacheKey: ResourceKey, value: CacheOperation): boolean;\n  notify(cacheKey: RequestKey, value: DocumentCacheOperation): boolean;\n};\n\ntype Store = {\n  cache: Cache;\n  notifications: NotificationManager;\n};\n\n/**\n * Interface of a parsed Cache-Control header value.\n *\n * - [MDN Cache-Control Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control)\n *\n * @summary The directives of a `Cache-Control` header as an object of flags and second counts, as\n * returned by `parseCacheControl`.\n */\nexport interface CacheControlValue {\n  /** Indicates the response will never change; parsed but not currently used by this cache policy's expiration logic. */\n  immutable?: boolean;\n  /** Seconds since the response's `Date` that it is considered fresh; combined with the `Age` header to determine expiration. */\n  'max-age'?: number;\n  /** Indicates a stale response must be revalidated before use; parsed but not currently used by this cache policy's expiration logic. */\n  'must-revalidate'?: boolean;\n  /** Indicates the client must understand the response's status code semantics before caching; parsed but not currently used by this cache policy's expiration logic. */\n  'must-understand'?: boolean;\n  /** Indicates the response must be revalidated before being reused from cache; parsed but not currently used by this cache policy's expiration logic. */\n  'no-cache'?: boolean;\n  /** Indicates the response must not be stored in any cache; parsed but not currently used by this cache policy's expiration logic. */\n  'no-store'?: boolean;\n  /** Indicates the response must not be transformed by intermediaries; parsed but not currently used by this cache policy's expiration logic. */\n  'no-transform'?: boolean;\n  /** Indicates only an already-cached response should be used; parsed but not currently used by this cache policy's expiration logic. */\n  'only-if-cached'?: boolean;\n  /** Indicates the response is intended for a single user and should not be stored by shared caches; parsed but not currently used by this cache policy's expiration logic. */\n  private?: boolean;\n  /** Like `must-revalidate` but only for shared caches; parsed but not currently used by this cache policy's expiration logic. */\n  'proxy-revalidate'?: boolean;\n  /** Indicates the response may be stored by any cache; parsed but not currently used by this cache policy's expiration logic. */\n  public?: boolean;\n  /** Seconds since the response's `Date` that it is considered fresh for shared caches; used as a fallback for `max-age` when determining expiration. */\n  's-maxage'?: number;\n  /** Seconds a stale response may be reused if an error occurs while revalidating; parsed but not currently used by this cache policy's expiration logic. */\n  'stale-if-error'?: number;\n  /** Seconds a stale response may be reused while a revalidation happens in the background; parsed but not currently used by this cache policy's expiration logic. */\n  'stale-while-revalidate'?: number;\n}\n\ntype CacheControlKey = keyof CacheControlValue;\n\nconst NUMERIC_KEYS = new Set(['max-age', 's-maxage', 'stale-if-error', 'stale-while-revalidate']);\n\n/**\n *  Parses a string Cache-Control header value into an object with the following structure:\n *\n * ```ts\n * interface CacheControlValue {\n *   immutable?: boolean;\n *   'max-age'?: number;\n *   'must-revalidate'?: boolean;\n *   'must-understand'?: boolean;\n *   'no-cache'?: boolean;\n *   'no-store'?: boolean;\n *   'no-transform'?: boolean;\n *   'only-if-cached'?: boolean;\n *   private?: boolean;\n *   'proxy-revalidate'?: boolean;\n *   public?: boolean;\n *   's-maxage'?: number;\n *   'stale-if-error'?: number;\n *   'stale-while-revalidate'?: number;\n * }\n * ```\n *\n * See also {@link CacheControlValue} and [Response Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#response_directives)\n *\n * @summary Parses a `Cache-Control` header string into a `CacheControlValue` object, caching results\n * per header string.\n * @public\n */\nexport function parseCacheControl(header: string): CacheControlValue {\n  return CACHE_CONTROL_CACHE.get(header);\n}\n\nconst CACHE_CONTROL_CACHE = new LRUCache((header: string) => {\n  let key: CacheControlKey = '' as CacheControlKey;\n  let value = '';\n  let isParsingKey = true;\n  const cacheControlValue: CacheControlValue = {};\n\n  for (let i = 0; i < header.length; i++) {\n    const char = header.charAt(i);\n    if (char === ',') {\n      assert(`Invalid Cache-Control value, expected a value`, !isParsingKey || !NUMERIC_KEYS.has(key));\n      assert(\n        `Invalid Cache-Control value, expected a value after \"=\" but got \",\"`,\n        i === 0 || header.charAt(i - 1) !== '='\n      );\n      isParsingKey = true;\n      // @ts-expect-error TS incorrectly thinks that optional keys must have a type that includes undefined\n      cacheControlValue[key] = NUMERIC_KEYS.has(key) ? parseCacheControlValue(value) : true;\n      key = '' as CacheControlKey;\n      value = '';\n      continue;\n    } else if (char === '=') {\n      assert(`Invalid Cache-Control value, expected a value after \"=\"`, i + 1 !== header.length);\n      isParsingKey = false;\n    } else if (char === ' ' || char === `\\t` || char === `\\n`) {\n      continue;\n    } else if (isParsingKey) {\n      key += char;\n    } else {\n      value += char;\n    }\n\n    if (i === header.length - 1) {\n      // @ts-expect-error TS incorrectly thinks that optional keys must have a type that includes undefined\n      cacheControlValue[key] = NUMERIC_KEYS.has(key) ? parseCacheControlValue(value) : true;\n    }\n  }\n\n  return cacheControlValue;\n}, 200);\n\nfunction parseCacheControlValue(stringToParse: string): number {\n  const parsedValue = Number.parseInt(stringToParse);\n  assert(`Invalid Cache-Control value, expected a number but got - ${stringToParse}`, !Number.isNaN(parsedValue));\n  assert(`Invalid Cache-Control value, expected a number greater than 0 but got - ${stringToParse}`, parsedValue >= 0);\n  if (Number.isNaN(parsedValue) || parsedValue < 0) {\n    return 0;\n  }\n\n  return parsedValue;\n}\n\nfunction isExpired(cacheKey: RequestKey, request: StructuredDocument<ResourceDocument>, config: PolicyConfig): boolean {\n  const { constraints } = config;\n\n  if (constraints?.isExpired) {\n    const result = constraints.isExpired(request);\n    if (result !== null) {\n      if (LOG_CACHE_POLICY) {\n        // oxlint-disable-next-line no-console\n        console.log(\n          `CachePolicy: ${cacheKey.lid} is ${result ? 'EXPIRED' : 'NOT expired'} because constraints.isExpired returned ${result}`\n        );\n      }\n      return result;\n    }\n  }\n\n  const { headers } = request.response!;\n\n  if (!headers) {\n    if (LOG_CACHE_POLICY) {\n      // oxlint-disable-next-line no-console\n      console.log(`CachePolicy: ${cacheKey.lid} is EXPIRED because no headers were provided`);\n    }\n\n    // if we have no headers then both the headers based expiration\n    // and the time based expiration will be considered expired\n    return true;\n  }\n\n  // check for X-WarpDrive-Expires\n  const now = Date.now();\n  const date = headers.get('Date');\n\n  if (constraints?.headers) {\n    if (constraints.headers['X-WarpDrive-Expires']) {\n      const xWarpDriveExpires = headers.get('X-WarpDrive-Expires');\n      if (xWarpDriveExpires) {\n        const expirationTime = new Date(xWarpDriveExpires).getTime();\n        const result = now >= expirationTime;\n        if (LOG_CACHE_POLICY) {\n          // oxlint-disable-next-line no-console\n          console.log(\n            `CachePolicy: ${cacheKey.lid} is ${result ? 'EXPIRED' : 'NOT expired'} because the time set by X-WarpDrive-Expires header is ${result ? 'in the past' : 'in the future'}`\n          );\n        }\n        return result;\n      }\n    }\n\n    // check for Cache-Control\n    if (constraints.headers['Cache-Control']) {\n      const cacheControl = headers.get('Cache-Control');\n      const age = headers.get('Age');\n\n      if (cacheControl && age && date) {\n        const cacheControlValue = parseCacheControl(cacheControl);\n\n        // max-age and s-maxage are stored in\n        const maxAge = cacheControlValue['max-age'] || cacheControlValue['s-maxage'];\n\n        if (maxAge) {\n          // age is stored in seconds\n          const ageValue = parseInt(age, 10);\n          assert(`Invalid Cache-Control value, expected a number but got - ${age}`, !Number.isNaN(ageValue));\n          assert(`Invalid Cache-Control value, expected a number greater than 0 but got - ${age}`, ageValue >= 0);\n\n          if (!Number.isNaN(ageValue) && ageValue >= 0) {\n            const dateValue = new Date(date).getTime();\n            const expirationTime = dateValue + (maxAge - ageValue) * 1000;\n            const result = now >= expirationTime;\n\n            if (LOG_CACHE_POLICY) {\n              // oxlint-disable-next-line no-console\n              console.log(\n                `CachePolicy: ${cacheKey.lid} is ${result ? 'EXPIRED' : 'NOT expired'} because the time set by Cache-Control header is ${result ? 'in the past' : 'in the future'}`\n              );\n            }\n\n            return result;\n          }\n        }\n      }\n    }\n\n    // check for Expires\n    if (constraints.headers.Expires) {\n      const expires = headers.get('Expires');\n      if (expires) {\n        const expirationTime = new Date(expires).getTime();\n        const result = now >= expirationTime;\n        if (LOG_CACHE_POLICY) {\n          // oxlint-disable-next-line no-console\n          console.log(\n            `CachePolicy: ${cacheKey.lid} is ${result ? 'EXPIRED' : 'NOT expired'} because the time set by Expires header is ${result ? 'in the past' : 'in the future'}`\n          );\n        }\n        return result;\n      }\n    }\n  }\n\n  // check for Date\n  if (!date) {\n    if (LOG_CACHE_POLICY) {\n      // oxlint-disable-next-line no-console\n      console.log(`CachePolicy: ${cacheKey.lid} is EXPIRED because no Date header was provided`);\n    }\n    return true;\n  }\n\n  let expirationTime = config.apiCacheHardExpires;\n  if (TESTING) {\n    if (!config.disableTestOptimization) {\n      expirationTime = config.apiCacheSoftExpires;\n    }\n  }\n\n  const time = new Date(date).getTime();\n  const deadline = time + expirationTime;\n  const result = now >= deadline;\n\n  if (LOG_CACHE_POLICY) {\n    // oxlint-disable-next-line no-console\n    console.log(\n      `CachePolicy: ${cacheKey.lid} is ${result ? 'EXPIRED' : 'NOT expired'} because the apiCacheHardExpires time since the response's Date header is ${result ? 'in the past' : 'in the future'}`\n    );\n  }\n\n  return result;\n}\n\n/**\n * The constraint options for {@link PolicyConfig.constraints}\n */\nexport interface PolicyConfigConstraints {\n  /**\n   * Headers that should be checked for expiration.\n   *\n   */\n  headers?: {\n    /**\n     * Whether the `Cache-Control` header should be checked for expiration.\n     * If `true`, then the `max-age` and `s-maxage` directives are used alongside\n     * the `Age` and `Date` headers to determine if the expiration time has passed.\n     *\n     * Other directives are ignored.\n     *\n     * 'Cache-Control' will take precedence over 'Expires' if both are present\n     * and both configured to be checked.\n     *\n     */\n    'Cache-Control'?: boolean;\n\n    /**\n     * Whether the `Expires` header should be checked for expiration.\n     *\n     * If `true`, then the `Expires` header is used to caclulate the expiration time\n     * and determine if the expiration time has passed.\n     *\n     * 'Cache-Control' will take precedence over 'Expires' if both are present.\n     *\n     */\n    Expires?: boolean;\n\n    /**\n     * Whether the `X-WarpDrive-Expires` header should be checked for expiration.\n     *\n     * If `true`, then the `X-WarpDrive-Expires` header is used to caclulate the expiration time\n     * and determine if the expiration time has passed.\n     *\n     * This header will take precedence over 'Cache-Control' and 'Expires' if all three are present.\n     *\n     * The header's value should be a [UTC date string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toUTCString).\n     *\n     */\n    'X-WarpDrive-Expires'?: boolean;\n  };\n\n  /**\n   * A function that should be called to determine if the request is expired.\n   *\n   * If present, this function will be called with the request and should return\n   * `true` if the request is expired, `false` if it is not expired, and\n   * `null` if the expiration status is unknown.\n   *\n   * If the function does not return `null`,\n   *\n   */\n  isExpired?: (request: StructuredDocument<ResourceDocument>) => boolean | null;\n}\n\n/**\n * The configuration options for the {@link DefaultCachePolicy}\n *\n * The [Advanced Store Configuration](/guides/configuration/advanced#decide-how-long-requests-are-valid-for-with-a-cachepolicy)\n * guide shows a policy configured with them.\n *\n * ```ts [app/services/store.ts]\n * import { Store } from '@warp-drive-mirror/core';\n * import { DefaultCachePolicy } from '@warp-drive-mirror/core/store'; // [!code focus]\n *\n * export default class AppStore extends Store {\n *   lifetimes = new DefaultCachePolicy({ // [!code focus:3]\n *     // ... PolicyConfig Settings ... //\n *   });\n * }\n * ```\n *\n * @summary Options for `DefaultCachePolicy`: soft and hard expiration times, header-based expiration\n * constraints, and test-mode behavior.\n */\nexport interface PolicyConfig {\n  /**\n   * the number of milliseconds after which a request is considered\n   * stale. If a request is issued again after this time, the request\n   * will respond from cache immediately while a background request\n   * is made to update the cache.\n   *\n   * This is calculated against the `date` header of the response.\n   *\n   * If your API does not provide a `date` header, the {@link Fetch} handler\n   * will automatically add it to responses if it is not present. Responses\n   * without a `date` header will be considered stale immediately.\n   *\n   */\n  apiCacheSoftExpires: number;\n  /**\n   * the number of milliseconds after which a request is considered\n   * expired and should be re-fetched. If a request is issued again\n   * after this time, the request will disregard the cache and\n   * wait for a fresh response from the API.\n   *\n   * This is calculated against the `date` header of the response.\n   *\n   * If your API does not provide a `date` header, the {@link Fetch} handler\n   * will automatically add it to responses if it is not present. Responses\n   * without a `date` header will be considered hard expired immediately.\n   *\n   */\n  apiCacheHardExpires: number;\n  /**\n   * In Testing environments, the `apiCacheSoftExpires` will always be `false`\n   * and `apiCacheHardExpires` will use the `apiCacheSoftExpires` value.\n   *\n   * This helps reduce flakiness and produce predictably rendered results in test suites.\n   *\n   * Requests that specifically set {@link RequestInfo.cacheOptions.backgroundReload | cacheOptions.backgroundReload }\n   * will still be background reloaded in tests.\n   *\n   * This behavior can be opted out of by setting this value to `true`.\n   *\n   */\n  disableTestOptimization?: boolean;\n\n  /**\n   * In addition to the simple time-based expiration strategy, CachePolicy\n   * supports various common server-supplied expiration strategies via\n   * headers, as well as custom expiration strategies via the {@link PolicyConfigConstraints.isExpired | isExpired}\n   * function.\n   *\n   * Requests will be validated for expiration against these constraints.\n   * If any of these constraints are not met, the request will be considered\n   * expired. If all constraints are met, the request will be considered\n   * valid and the time based expiration strategy will NOT be used.\n   *\n   * Meeting a constraint means BOTH that the properties the constraint\n   * requires are present AND that the expiration time indicated by those\n   * properties has not been exceeded.\n   *\n   * In other words, if the properties for a constraint are not present,\n   * this does not count either as meeting or as not meeting the constraint,\n   * the constraint simply does not apply.\n   *\n   * The `isExpired` function is called with the request and should return\n   * `true` if the request is expired, `false` if it is not expired, and\n   * `null` if the expiration status is unknown.\n   *\n   * In order constraints are checked:\n   *\n   * - isExpired function\n   * -  ↳ (if null) X-WarpDrive-Expires header\n   * -  ↳ (if null) Cache-Control header\n   * -  ↳ (if null) Expires header\n   *\n   * See {@link PolicyConfigConstraints} for configuration options.\n   */\n  constraints?: PolicyConfigConstraints;\n}\n\n/**\n * A basic {@link CachePolicy} that can be added to the Store service.\n *\n * The [Advanced Store Configuration](/guides/configuration/advanced#decide-how-long-requests-are-valid-for-with-a-cachepolicy)\n * guide shows how to configure it.\n *\n * ```ts [app/services/store.ts]\n * import { Store } from '@warp-drive-mirror/core';\n * import { DefaultCachePolicy } from '@warp-drive-mirror/core/store'; // [!code focus]\n *\n * export default class AppStore extends Store {\n *   lifetimes = new DefaultCachePolicy({ // [!code focus:5]\n *     apiCacheSoftExpires: 30_000,\n *     apiCacheHardExpires: 60_000,\n *     // ... Other PolicyConfig Settings ... //\n *   });\n * }\n * ```\n *\n * :::tip 💡 TIP\n * Date headers do not have millisecond precision, so expiration times should\n * generally be larger than 1000ms.\n * :::\n *\n * See also {@link PolicyConfig} for configuration options.\n *\n * ### The Mechanics\n *\n * This policy determines staleness based on various configurable constraints falling back to a simple\n * check of the time elapsed since the request was last received from the API using the `date` header\n * from the last response.\n *\n * :::tip 💡 TIP\n * The {@link Fetch} handler provided by `@warp-drive-mirror/core` will automatically\n * add the `date` header to responses if it is not present.\n * :::\n *\n * - For manual override of reload see {@link CacheOptions.reload | cacheOptions.reload}\n * - For manual override of background reload see {@link CacheOptions.backgroundReload | cacheOptions.backgroundReload}\n *\n * In order expiration is determined by:\n *\n * ```md\n * Is explicitly invalidated by `cacheOptions.reload`\n *   ↳ (if falsey) if the request has been explicitly invalidated\n *      since the last request (see Automatic Invalidation below)\n *   ↳ (if false) (If Active) isExpired function\n *   ↳ (if null) (If Active) X-WarpDrive-Expires header\n *   ↳ (if null) (If Active) Cache-Control header\n *   ↳ (if null) (If Active) Expires header\n *   ↳ (if null) Date header + apiCacheHardExpires < current time\n *\n *   -- <if above is false, a background request is issued if> --\n *\n *   ↳ is invalidated by `cacheOptions.backgroundReload`\n *   ↳ (if falsey) Date header + apiCacheSoftExpires < current time\n * ```\n *\n * ### Automatic Invalidation / Entanglement\n *\n * It also invalidates any request with an {@link RequestInfo.op | OpCode} of `\"query\"`\n * for which {@link CacheOptions.types | cacheOptions.types} was provided\n * when a request with an `OpCode` of `\"createRecord\"` is successful and also includes\n * a matching type in its own `cacheOptions.types` array.\n\n * :::tip 💡 TIP\n * Abstracting this behavior via builders is recommended to ensure consistency.\n * :::\n *\n * ### Testing\n *\n * In Testing environments:\n *\n * - `apiCacheSoftExpires` will always be `false`\n * - `apiCacheHardExpires` will use the `apiCacheSoftExpires` value.\n *\n * This helps reduce flakiness and produce predictably rendered results in test suites.\n *\n * Requests that specifically set `cacheOptions.backgroundReload = true` will\n * still be background reloaded in tests.\n *\n * This behavior can be opted out of by setting `disableTestOptimization = true`\n * in the policy config.\n *\n * @summary The built-in cache policy, which expires cached requests using expiration headers or time\n * since the response `date`, and invalidates queries after matching creates.\n * @public\n */\nexport class DefaultCachePolicy implements CachePolicy {\n  /**\n   * @internal\n   */\n  declare private config: PolicyConfig;\n  /**\n   * @internal\n   */\n  declare private _stores: WeakMap<Store, { invalidated: Set<RequestKey>; types: Map<string, Set<RequestKey>> }>;\n\n  /**\n   * @internal\n   */\n  private _getStore(store: Store): {\n    invalidated: Set<RequestKey>;\n    types: Map<string, Set<RequestKey>>;\n  } {\n    let set = this._stores.get(store);\n    if (!set) {\n      set = { invalidated: new Set(), types: new Map() };\n      this._stores.set(store, set);\n    }\n    return set;\n  }\n\n  constructor(config: PolicyConfig) {\n    this._stores = new WeakMap();\n\n    const _config = arguments.length === 1 ? config : (arguments[1] as unknown as PolicyConfig);\n    deprecate(\n      `Passing a Store to the CachePolicy is deprecated, please pass only a config instead.`,\n      arguments.length === 1,\n      {\n        id: 'ember-data-mirror:request-utils:lifetimes-service-store-arg',\n        since: {\n          enabled: '5.4',\n          available: '4.13',\n        },\n        for: '@ember-data-mirror/request-utils',\n        until: '6.0',\n      }\n    );\n    assert(`You must pass a config to the CachePolicy`, _config);\n    assert(`You must pass a apiCacheSoftExpires to the CachePolicy`, typeof _config.apiCacheSoftExpires === 'number');\n    assert(`You must pass a apiCacheHardExpires to the CachePolicy`, typeof _config.apiCacheHardExpires === 'number');\n    this.config = _config;\n  }\n\n  /**\n   * Invalidate a request by its CacheKey for the given store instance.\n   *\n   * While the store argument may seem redundant, the CachePolicy\n   * is designed to be shared across multiple stores / forks\n   * of the store.\n   *\n   * ```ts\n   * store.lifetimes.invalidateRequest(store, cacheKey);\n   * ```\n   *\n   * @public\n   */\n  invalidateRequest(cacheKey: RequestKey, store: Store): void {\n    this._getStore(store).invalidated.add(cacheKey);\n  }\n\n  /**\n   * Invalidate all requests associated to a specific type\n   * for a given store instance.\n   *\n   * While the store argument may seem redundant, the CachePolicy\n   * is designed to be shared across multiple stores / forks\n   * of the store.\n   *\n   * This invalidation is done automatically when using this service\n   * for both the {@link CacheHandler} and the [NetworkHandler](/api/@warp-drive-mirror/legacy/compat/variables/LegacyNetworkHandler).\n   *\n   * ```ts\n   * store.lifetimes.invalidateRequestsForType(store, 'person');\n   * ```\n   *\n   * @public\n   */\n  invalidateRequestsForType(type: string, store: Store): void {\n    const storeCache = this._getStore(store);\n    const set = storeCache.types.get(type);\n    const notifications = store.notifications;\n\n    if (set) {\n      // TODO batch notifications\n      set.forEach((id) => {\n        storeCache.invalidated.add(id);\n        // @ts-expect-error\n        notifications.notify(id, 'invalidated', null);\n      });\n    }\n  }\n\n  /**\n   * Invoked when a request has been fulfilled from the configured request handlers.\n   * This is invoked by the CacheHandler for both foreground and background requests\n   * once the cache has been updated.\n   *\n   * Note, this is invoked by the {@link CacheHandler} regardless of whether\n   * the request has a cache-key.\n   *\n   * This method should not be invoked directly by consumers.\n   *\n   * @public\n   */\n  didRequest(\n    request: ImmutableRequestInfo,\n    response: Response | ResponseInfo | null,\n    cacheKey: RequestKey | null,\n    store: Store\n  ): void {\n    // if this is a successful createRecord request, invalidate the cacheKey for the type\n    if (request.op === 'createRecord') {\n      const statusNumber = response?.status ?? 0;\n      if (statusNumber >= 200 && statusNumber < 400) {\n        const types = new Set(request.records?.map((r) => r.type));\n        const additionalTypes = request.cacheOptions?.types;\n        additionalTypes?.forEach((type) => {\n          types.add(type);\n        });\n\n        types.forEach((type) => {\n          this.invalidateRequestsForType(type, store);\n        });\n      }\n\n      // add this document's cacheKey to a map for all associated types\n      // it is recommended to only use this for queries\n    } else if (cacheKey && request.cacheOptions?.types?.length) {\n      const storeCache = this._getStore(store);\n      request.cacheOptions?.types.forEach((type) => {\n        const set = storeCache.types.get(type);\n        if (set) {\n          set.add(cacheKey);\n          storeCache.invalidated.delete(cacheKey);\n        } else {\n          storeCache.types.set(type, new Set([cacheKey]));\n        }\n      });\n    }\n  }\n\n  /**\n   * Invoked to determine if the request may be fulfilled from cache\n   * if possible.\n   *\n   * Note, this is only invoked by the {@link CacheHandler} if the request has\n   * a cache-key.\n   *\n   * If no cache entry is found or the entry is hard expired,\n   * the request will be fulfilled from the configured request handlers\n   * and the cache will be updated before returning the response.\n   *\n   * @public\n   * @return true if the request is considered hard expired\n   */\n  isHardExpired(cacheKey: RequestKey, store: Store): boolean {\n    // if we are explicitly invalidated, we are hard expired\n    const storeCache = this._getStore(store);\n    if (storeCache.invalidated.has(cacheKey)) {\n      return true;\n    }\n    const cache = store.cache;\n    const cached = cache.peekRequest(cacheKey);\n\n    if (!cached?.response) {\n      if (LOG_CACHE_POLICY) {\n        // oxlint-disable-next-line no-console\n        console.log(`CachePolicy: ${cacheKey.lid} is EXPIRED because no cache entry was found`);\n      }\n      return true;\n    }\n\n    return isExpired(cacheKey, cached, this.config);\n  }\n\n  /**\n   * Invoked if `isHardExpired` is false to determine if the request\n   * should be update behind the scenes if cache data is already available.\n   *\n   * Note, this is only invoked by the {@link CacheHandler} if the request has\n   * a cache-key.\n   *\n   * If true, the request will be fulfilled from cache while a backgrounded\n   * request is made to update the cache via the configured request handlers.\n   *\n   * @public\n   * @return true if the request is considered soft expired\n   */\n  isSoftExpired(cacheKey: RequestKey, store: Store): boolean {\n    if (TESTING) {\n      if (!this.config.disableTestOptimization) {\n        return false;\n      }\n    }\n    const cache = store.cache;\n    const cached = cache.peekRequest(cacheKey);\n\n    if (cached?.response) {\n      const date = cached.response.headers.get('date');\n\n      if (!date) {\n        if (LOG_CACHE_POLICY) {\n          // oxlint-disable-next-line no-console\n          console.log(`CachePolicy: ${cacheKey.lid} is STALE because no date header was found`);\n        }\n        return true;\n      } else {\n        const time = new Date(date).getTime();\n        const now = Date.now();\n        const deadline = time + this.config.apiCacheSoftExpires;\n        const result = now >= deadline;\n\n        if (LOG_CACHE_POLICY) {\n          // oxlint-disable-next-line no-console\n          console.log(\n            `CachePolicy: ${cacheKey.lid} is ${result ? 'STALE' : 'NOT stale'}. Expiration time: ${deadline}, now: ${now}`\n          );\n        }\n\n        return result;\n      }\n    }\n\n    if (LOG_CACHE_POLICY) {\n      // oxlint-disable-next-line no-console\n      console.log(`CachePolicy: ${cacheKey.lid} is STALE because no cache entry was found`);\n    }\n\n    return true;\n  }\n}\n"],"mappings":"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"}

package/dist/unpkg/prod/store.js

@@ -1,3 +1,3 @@
-import { n as parseCacheControl, t as DefaultCachePolicy } from "./store-BWhmb7Ob.js";
+import { n as parseCacheControl, t as DefaultCachePolicy } from "./store-CQOsqdST.js";
 
 export { DefaultCachePolicy, parseCacheControl };

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

@@ -1,6 +1,6 @@
 //#region src/types/-private.ts
 const name = "@warp-drive-mirror/core";
-const version = "5.10.0-alpha.10";
+const version = "5.10.0-alpha.13";
 const GlobalRef = globalThis;
 const UniversalCache = GlobalRef.__warpDrive_universalCache = GlobalRef.__warpDrive_universalCache ?? {};
 GlobalRef[name] = GlobalRef[name] ?? { __version: version };

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

@@ -1,5 +1,10 @@
 //#region src/types/identifier.ts
 /**
+* @module
+* @summary Types for the stable keys that reference cached data, `ResourceKey` for resources and `RequestKey` for
+* request documents, plus their deprecated identifier aliases.
+*/
+/**
 * @private
 */ const DEBUG_CLIENT_ORIGINATED = Symbol("record-originated-on-client");
 /**
@@ -21,6 +26,8 @@ const CACHE_OWNER = ProdSymbol("__$co", "CACHE_OWNER");
 * Identifies which "bucket" of the cache a key belongs to: resources
 * (`'record'`, see {@link ResourceKey}) or request documents
 * (`'document'`, see {@link RequestKey}).
+*
+* @summary Which cache bucket a key belongs to: `'record'` for resource keys or `'document'` for request keys.
 */
 /**
 * A referentially stable object with a unique string (lid) that can be used
@@ -29,9 +36,17 @@ const CACHE_OWNER = ProdSymbol("__$co", "CACHE_OWNER");
 * Only requests that are assigned a RequestKey are retrievable/replayable from
 * the cache, though requests without RequestKeys may still update cache state.
 *
+* The [Key Terminology](/guides/the-manual/caching/key-terms#documents) guide explains
+* the documents it identifies.
+*
+* @summary Stable object with a unique `lid` that references a cached request document, letting that request's
+* result be retrieved or replayed.
 * @public
 */
-/** @deprecated use {@link RequestKey} */
+/**
+* @summary Deprecated alias for `RequestKey`, the stable cache reference to a request document.
+* @deprecated use {@link RequestKey}
+*/
 /**
 * Used when an ResourceKey is known to be the stable version
 */
@@ -42,8 +57,13 @@ const CACHE_OWNER = ProdSymbol("__$co", "CACHE_OWNER");
 * 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.
+*
+* @summary Resource key whose `id` is a known string, the form keys for server-loaded resources take.
+*/
+/**
+* @summary Deprecated alias for `PersistedResourceKey`, a resource key whose `id` is known.
+* @deprecated use {@link PersistedResourceKey}
 */
-/** @deprecated use {@link PersistedResourceKey} */
 /**
 * Used when a ResourceKey was created locally
 * (by a call to store.createRecord).
@@ -52,6 +72,8 @@ const CACHE_OWNER = ProdSymbol("__$co", "CACHE_OWNER");
 * 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.
+*
+* @summary Resource key for a record created locally with `store.createRecord`, whose `id` may still be `null`.
 */
 /**
 * A referentially stable object with a unique string (lid) that can be used
@@ -60,9 +82,17 @@ const CACHE_OWNER = ProdSymbol("__$co", "CACHE_OWNER");
 * Every resource has a unique ResourceKey, and ResourceKeys may refer
 * to data that has never been loaded (for instance, in an async relationship).
 *
+* The [Key Terminology](/guides/the-manual/caching/key-terms#resources) guide explains
+* the resources it identifies.
+*
+* @summary Stable object with a unique `lid` plus `type` and `id` that uniquely references one resource's data in
+* the cache, loaded or not.
 * @public
 */
-/** @deprecated use {@link ResourceKey} */
+/**
+* @summary Deprecated alias for `ResourceKey`, the stable cache reference to a single resource.
+* @deprecated use {@link ResourceKey}
+*/
 //#endregion
 export { CACHE_OWNER, DEBUG_CLIENT_ORIGINATED, DEBUG_KEY_TYPE, DEBUG_STALE_CACHE_OWNER };
 //# sourceMappingURL=identifier.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"identifier.js","names":["DEBUG_CLIENT_ORIGINATED","Symbol","DEBUG_KEY_TYPE","DEBUG_STALE_CACHE_OWNER","ProdSymbol","str","debugStr","CACHE_OWNER"],"sources":["../../../../src/types/identifier.ts"],"sourcesContent":["import { DEBUG } from '@warp-drive-mirror/core/build-config/env';\n\n// provided for additional debuggability\n/**\n * @private\n */\nexport const DEBUG_CLIENT_ORIGINATED: unique symbol = Symbol('record-originated-on-client');\n/**\n * @private\n */\nexport const DEBUG_KEY_TYPE: unique symbol = Symbol('key-type');\n/**\n * @private\n */\nexport const DEBUG_STALE_CACHE_OWNER: unique symbol = Symbol('warpDriveStaleCache');\n\nfunction ProdSymbol<T extends string>(str: T, debugStr: string): T {\n  return DEBUG ? (Symbol(debugStr) as unknown as T) : str;\n}\n\n// also present in production\n/**\n * @private\n */\nexport const CACHE_OWNER: '__$co' = ProdSymbol('__$co', 'CACHE_OWNER');\n\n/**\n * Identifies which \"bucket\" of the cache a key belongs to: resources\n * (`'record'`, see {@link ResourceKey}) or request documents\n * (`'document'`, see {@link RequestKey}).\n */\nexport type CacheKeyType = 'record' | 'document';\n\n/**\n * A referentially stable object with a unique string (lid) that can be used\n * as a reference to request data in the cache.\n *\n * Only requests that are assigned a RequestKey are retrievable/replayable from\n * the cache, though requests without RequestKeys may still update cache state.\n *\n * @public\n */\nexport interface RequestKey {\n  /**\n   * A string representing a unique identity.\n   */\n  lid: string;\n  /**\n   * Discriminates a {@link RequestKey} from a {@link ResourceKey}.\n   */\n  type: '@document';\n  /** @internal */\n  [CACHE_OWNER]: number | undefined;\n}\n\n/** @deprecated use {@link RequestKey} */\nexport type StableDocumentIdentifier = RequestKey;\n\n/**\n * Used when an ResourceKey is known to be the stable version\n */\ninterface ResourceKeyBase<T extends string = string> {\n  /**\n   * A string representing a unique identity.\n   *\n   * @public\n   */\n  lid: string;\n\n  /**\n   * the primary `ResourceType` or \"model name\" this ResourceKey belongs to.\n   *\n   * @public\n   */\n  type: T;\n\n  /** @internal */\n  [CACHE_OWNER]: number | undefined;\n\n  /** @internal */\n  [DEBUG_CLIENT_ORIGINATED]?: boolean;\n  /** @internal */\n  [DEBUG_STALE_CACHE_OWNER]?: number | undefined;\n}\n\n/**\n * Used when a ResourceKey was not created locally as part\n * of a call to store.createRecord\n *\n * Distinguishing between this ResourceKey and one for a client created\n * resource that was created with an ID is generally speaking not possible\n * at runtime, so anything with an ID typically narrows to this.\n */\nexport interface PersistedResourceKey<T extends string = string> extends ResourceKeyBase<T> {\n  /**\n   * the PrimaryKey for the resource this ResourceKey represents.\n   *\n   * @public\n   */\n  id: string;\n}\n\n/** @deprecated use {@link PersistedResourceKey} */\nexport type StableExistingRecordIdentifier<T extends string = string> = PersistedResourceKey<T>;\n\n/**\n * Used when a ResourceKey was created locally\n * (by a call to store.createRecord).\n *\n * It is possible in rare circumstances to have a ResourceKey\n * that is not for a new record but does not have an ID. This would\n * happen if a user intentionally created one for use with a secondary-index\n * prior to the record having been fully loaded.\n */\nexport interface NewResourceKey<T extends string = string> extends ResourceKeyBase<T> {\n  /**\n   * the PrimaryKey for the resource this ResourceKey represents. `null`\n   * if not yet assigned a PrimaryKey value.\n   *\n   * @public\n   */\n  id: string | null;\n}\n\n/**\n * A referentially stable object with a unique string (lid) that can be used\n * as a reference to data in the cache.\n *\n * Every resource has a unique ResourceKey, and ResourceKeys may refer\n * to data that has never been loaded (for instance, in an async relationship).\n *\n * @public\n */\nexport type ResourceKey<T extends string = string> = PersistedResourceKey<T> | NewResourceKey<T>;\n\n/** @deprecated use {@link ResourceKey} */\nexport type StableRecordIdentifier<T extends string = string> = ResourceKey<T>;\n"],"mappings":";;;GAMA,MAAaA,0BAAyCC,OAAO,6BAA6B;;;;AAI1F,MAAaC,iBAAgCD,OAAO,UAAU;;;;AAI9D,MAAaE,0BAAyCF,OAAO,qBAAqB;AAElF,SAASG,WAA6BC,KAAQC,UAAqB;CACjE,OAAoDD;AACtD;;;;AAMA,MAAaE,cAAuBH,WAAW,SAAS,aAAa"}
+{"version":3,"file":"identifier.js","names":["DEBUG_CLIENT_ORIGINATED","Symbol","DEBUG_KEY_TYPE","DEBUG_STALE_CACHE_OWNER","ProdSymbol","str","debugStr","CACHE_OWNER"],"sources":["../../../../src/types/identifier.ts"],"sourcesContent":["/**\n * @module\n * @summary Types for the stable keys that reference cached data, `ResourceKey` for resources and `RequestKey` for\n * request documents, plus their deprecated identifier aliases.\n */\n\nimport { DEBUG } from '@warp-drive-mirror/core/build-config/env';\n\n// provided for additional debuggability\n/**\n * @private\n */\nexport const DEBUG_CLIENT_ORIGINATED: unique symbol = Symbol('record-originated-on-client');\n/**\n * @private\n */\nexport const DEBUG_KEY_TYPE: unique symbol = Symbol('key-type');\n/**\n * @private\n */\nexport const DEBUG_STALE_CACHE_OWNER: unique symbol = Symbol('warpDriveStaleCache');\n\nfunction ProdSymbol<T extends string>(str: T, debugStr: string): T {\n  return DEBUG ? (Symbol(debugStr) as unknown as T) : str;\n}\n\n// also present in production\n/**\n * @private\n */\nexport const CACHE_OWNER: '__$co' = ProdSymbol('__$co', 'CACHE_OWNER');\n\n/**\n * Identifies which \"bucket\" of the cache a key belongs to: resources\n * (`'record'`, see {@link ResourceKey}) or request documents\n * (`'document'`, see {@link RequestKey}).\n *\n * @summary Which cache bucket a key belongs to: `'record'` for resource keys or `'document'` for request keys.\n */\nexport type CacheKeyType = 'record' | 'document';\n\n/**\n * A referentially stable object with a unique string (lid) that can be used\n * as a reference to request data in the cache.\n *\n * Only requests that are assigned a RequestKey are retrievable/replayable from\n * the cache, though requests without RequestKeys may still update cache state.\n *\n * The [Key Terminology](/guides/the-manual/caching/key-terms#documents) guide explains\n * the documents it identifies.\n *\n * @summary Stable object with a unique `lid` that references a cached request document, letting that request's\n * result be retrieved or replayed.\n * @public\n */\nexport interface RequestKey {\n  /**\n   * A string representing a unique identity.\n   */\n  lid: string;\n  /**\n   * Discriminates a {@link RequestKey} from a {@link ResourceKey}.\n   */\n  type: '@document';\n  /** @internal */\n  [CACHE_OWNER]: number | undefined;\n}\n\n/**\n * @summary Deprecated alias for `RequestKey`, the stable cache reference to a request document.\n * @deprecated use {@link RequestKey}\n */\nexport type StableDocumentIdentifier = RequestKey;\n\n/**\n * Used when an ResourceKey is known to be the stable version\n */\ninterface ResourceKeyBase<T extends string = string> {\n  /**\n   * A string representing a unique identity.\n   *\n   * @public\n   */\n  lid: string;\n\n  /**\n   * the primary `ResourceType` or \"model name\" this ResourceKey belongs to.\n   *\n   * @public\n   */\n  type: T;\n\n  /** @internal */\n  [CACHE_OWNER]: number | undefined;\n\n  /** @internal */\n  [DEBUG_CLIENT_ORIGINATED]?: boolean;\n  /** @internal */\n  [DEBUG_STALE_CACHE_OWNER]?: number | undefined;\n}\n\n/**\n * Used when a ResourceKey was not created locally as part\n * of a call to store.createRecord\n *\n * Distinguishing between this ResourceKey and one for a client created\n * resource that was created with an ID is generally speaking not possible\n * at runtime, so anything with an ID typically narrows to this.\n *\n * @summary Resource key whose `id` is a known string, the form keys for server-loaded resources take.\n */\nexport interface PersistedResourceKey<T extends string = string> extends ResourceKeyBase<T> {\n  /**\n   * the PrimaryKey for the resource this ResourceKey represents.\n   *\n   * @public\n   */\n  id: string;\n}\n\n/**\n * @summary Deprecated alias for `PersistedResourceKey`, a resource key whose `id` is known.\n * @deprecated use {@link PersistedResourceKey}\n */\nexport type StableExistingRecordIdentifier<T extends string = string> = PersistedResourceKey<T>;\n\n/**\n * Used when a ResourceKey was created locally\n * (by a call to store.createRecord).\n *\n * It is possible in rare circumstances to have a ResourceKey\n * that is not for a new record but does not have an ID. This would\n * happen if a user intentionally created one for use with a secondary-index\n * prior to the record having been fully loaded.\n *\n * @summary Resource key for a record created locally with `store.createRecord`, whose `id` may still be `null`.\n */\nexport interface NewResourceKey<T extends string = string> extends ResourceKeyBase<T> {\n  /**\n   * the PrimaryKey for the resource this ResourceKey represents. `null`\n   * if not yet assigned a PrimaryKey value.\n   *\n   * @public\n   */\n  id: string | null;\n}\n\n/**\n * A referentially stable object with a unique string (lid) that can be used\n * as a reference to data in the cache.\n *\n * Every resource has a unique ResourceKey, and ResourceKeys may refer\n * to data that has never been loaded (for instance, in an async relationship).\n *\n * The [Key Terminology](/guides/the-manual/caching/key-terms#resources) guide explains\n * the resources it identifies.\n *\n * @summary Stable object with a unique `lid` plus `type` and `id` that uniquely references one resource's data in\n * the cache, loaded or not.\n * @public\n */\nexport type ResourceKey<T extends string = string> = PersistedResourceKey<T> | NewResourceKey<T>;\n\n/**\n * @summary Deprecated alias for `ResourceKey`, the stable cache reference to a single resource.\n * @deprecated use {@link ResourceKey}\n */\nexport type StableRecordIdentifier<T extends string = string> = ResourceKey<T>;\n"],"mappings":";;;;;;;;GAYA,MAAaA,0BAAyCC,OAAO,6BAA6B;;;;AAI1F,MAAaC,iBAAgCD,OAAO,UAAU;;;;AAI9D,MAAaE,0BAAyCF,OAAO,qBAAqB;AAElF,SAASG,WAA6BC,KAAQC,UAAqB;CACjE,OAAoDD;AACtD;;;;AAMA,MAAaE,cAAuBH,WAAW,SAAS,aAAa"}

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

@@ -1,5 +1,10 @@
 //#region src/types/record.ts
 /**
+* @module
+* @summary Types for records that declare their resource type via the `[Type]` symbol, including `TypedRecordInstance`,
+* `Includes`, `Mask` and the `createIncludeValidator` helper.
+*/
+/**
 * Records may be anything, They don't even
 * have to be objects.
 *
@@ -8,17 +13,21 @@
 * and WarpDrive to provide better type safety and
 * intellisense.
 *
+* @summary Shape of a record type that declares its resource type via the `[Type]` symbol, letting WarpDrive APIs
+* infer types for better type safety.
 * @class TypedRecordInstance
 */
 /**
 * A type utility that extracts the Type if available,
 * otherwise it returns never.
 *
+* @summary Type utility giving a record type's `[Type]` resource type string, or `never` if it declares none.
 */
 /**
 * A type utility that extracts the Type if available,
 * otherwise it returns string
 *
+* @summary Type utility giving a record type's `[Type]` resource type string, or `string` if it declares none.
 */
 /**
 * A Utility that extracts either resource types or resource paths from a TypedRecordInstance.
@@ -41,6 +50,8 @@
 * A utility that provides the union of all ResourceName for all potential
 * includes for the given TypedRecordInstance.
 *
+* @summary Type utility giving the union of resource types reachable from a typed record through its
+* relationships, up to a max depth.
 */
 /**
 * A utility that provides the union type of all valid include paths for the given
@@ -48,10 +59,14 @@
 *
 * Cyclical paths are filtered out.
 *
+* @summary Type utility giving the union of valid dot-separated `include` relationship paths for a typed record,
+* excluding cycles.
 */
 /**
 * A type-erased placeholder for a record instance, used where the
 * specific record type is not known or not relevant.
+*
+* @summary Type-erased (`unknown`) stand-in for a record instance where its specific type is unknown or irrelevant.
 */
 /**
 * @internal
@@ -63,6 +78,8 @@
 * TypeScript cannot autocomplete against this type; prefer {@link createIncludeValidator}
 * for a better development experience unless you are writing a similar wrapper utility.
 *
+* @summary Type utility that checks a comma-separated `include` string contains only paths from an allowed union,
+* resolving to `never` otherwise.
 * @example
 * ```ts
 * import type { StringSatisfiesIncludes, Includes } from '@warp-drive-mirror/core/types/record';
@@ -78,6 +95,8 @@
 * ensuring at compile time that only valid paths for `T` (per {@link Includes})
 * are supplied.
 *
+* @summary Returns a function that type-checks a comma-separated `include` string against the valid relationship paths
+* of a record type and returns it unchanged.
 * @example
 * ```ts
 * import { createIncludeValidator } from '@warp-drive-mirror/core/types/record';
@@ -164,6 +183,9 @@ function createIncludeValidator() {
 *
 * But what if your app has data with massive interfaces such that the TypeScript performance of this
 * approach becomes a problem? In that case, see {@link Validate}
+*
+* @summary Type utility that builds a preview type from `T` by replacing selected fields with narrower subset types
+* from `K`, resolving to `never` where a field is not compatible.
 */
 /**
 * A utility that takes two types, K and T, and ensures that K is a valid subset of T.
@@ -215,6 +237,9 @@ function createIncludeValidator() {
 * ```
 *
 * For help creating subsets of types, see {@link Mask}
+*
+* @summary Type utility that checks a hand-written preview type `K` is a valid subset of the full type `T`, resolving
+* to `K` if so and `never` otherwise.
 */
 //#endregion
 export { createIncludeValidator };

package/dist/unpkg/prod/types/record.js.map

@@ -1 +1 @@
-{"version":3,"file":"record.js","names":["createIncludeValidator","validateIncludes","includes"],"sources":["../../../../src/types/record.ts"],"sourcesContent":["import type { Type } from './symbols.ts';\n\n/**\n * Records may be anything, They don't even\n * have to be objects.\n *\n * Whatever they are, if they have a Type\n * property, that property will be used by WarpDrive\n * and WarpDrive to provide better type safety and\n * intellisense.\n *\n * @class TypedRecordInstance\n */\nexport interface TypedRecordInstance {\n  /**\n   * The type of the resource.\n   *\n   * This is an optional feature that can be used by\n   * record implementations to provide a typescript\n   * hint for the type of the resource.\n   *\n   * When used, WarpDrive APIs can\n   * take advantage of this to provide better type\n   * safety and intellisense.\n   *\n   * @property [Type]\n   * @type {Type}\n   * @type {String}\n   */\n  [Type]: string;\n}\n\n/**\n * A type utility that extracts the Type if available,\n * otherwise it returns never.\n *\n */\nexport type TypeFromInstance<T> = T extends TypedRecordInstance ? T[typeof Type] : never;\n\n/**\n * A type utility that extracts the Type if available,\n * otherwise it returns string\n *\n */\nexport type TypeFromInstanceOrString<T> = T extends TypedRecordInstance ? T[typeof Type] : string;\n\ntype IsUniqueSymbol<T> = T extends `___(unique) Symbol(${string})` ? true : false;\ntype Unpacked<T> = T extends (infer U)[] ? U : T;\ntype NONE = { __NONE: never };\n\ntype __InternalExtract<\n  MAX_DEPTH extends _DEPTHCOUNT,\n  T extends TypedRecordInstance,\n  V extends TypedRecordInstance,\n  IncludePrefix extends boolean,\n  Ignore,\n  Pre extends string,\n  DEPTH extends _DEPTHCOUNT,\n> =\n  // if we extend T, we return the leaf value\n  V extends T\n    ? IncludePrefix extends false\n      ? V[typeof Type]\n      : Pre\n    : // else if we are in Ignore we add the lead and exit\n      V extends Ignore\n      ? IncludePrefix extends false\n        ? V[typeof Type]\n        : Pre\n      : // else if we are at max depth, we return never\n        IS_MAX_DEPTH<DEPTH, MAX_DEPTH> extends true\n        ? Pre\n        : // else add T to Ignore and recurse\n          ExtractUnion<MAX_DEPTH, V, IncludePrefix, Ignore | T, Pre, INC_DEPTH<DEPTH>>;\n\ntype __ExtractIfRecord<\n  MAX_DEPTH extends _DEPTHCOUNT,\n  T extends TypedRecordInstance,\n  V,\n  IncludePrefix extends boolean,\n  Ignore,\n  Pre extends string,\n  DEPTH extends _DEPTHCOUNT,\n> = V extends TypedRecordInstance ? __InternalExtract<MAX_DEPTH, T, V, IncludePrefix, Ignore, Pre, DEPTH> : never;\n\ntype _ExtractUnion<\n  MAX_DEPTH extends _DEPTHCOUNT,\n  T extends TypedRecordInstance,\n  IncludePrefix extends boolean,\n  Ignore,\n  Pre,\n  DEPTH extends _DEPTHCOUNT,\n> = {\n  // for each string key in the record,\n  [K in keyof T]: IsUniqueSymbol<K> extends true\n    ? never\n    : K extends string\n      ? // we recursively extract any values that resolve to a TypedRecordInstance\n        __ExtractIfRecord<\n          MAX_DEPTH,\n          T,\n          Unpacked<Awaited<T[K]>>,\n          IncludePrefix,\n          Ignore,\n          Pre extends string ? `${Pre}.${K}` : K,\n          DEPTH\n        >\n      : never;\n  // then we return any value that is not 'never'\n}[keyof T];\n\n/**\n * A Utility that extracts either resource types or resource paths from a TypedRecordInstance.\n *\n * Its limitations are mostly around its intentional non-recursiveness. It presumes that APIs which\n * implement includes will not allow cyclical include paths, and will collapse includes by type.\n *\n * This follows closer to the JSON:API fields spec than to the includes spec in nature, but in\n * practice it is so impracticle for an API to allow z-algo include paths that this is probably\n * reasonable.\n *\n * We may need to revisit this in the future, opting to either make this restriction optional or\n * to allow for other strategies.\n *\n * There's a 90% chance this particular implementation belongs being in the JSON:API package instead\n * of core-types, but it's here for now.\n *\n */\ntype ExtractUnion<\n  MAX_DEPTH extends _DEPTHCOUNT,\n  T extends TypedRecordInstance,\n  IncludePrefix extends boolean = false,\n  Ignore = NONE,\n  Pre = NONE,\n  DEPTH extends _DEPTHCOUNT = 1,\n> = Exclude<\n  IncludePrefix extends true\n    ? // if we want to include prefix, we union with the prefix. Outer Exclude will filter any \"NONE\" types\n      _ExtractUnion<MAX_DEPTH, T, IncludePrefix, Ignore, Pre, DEPTH> | Pre\n    : // Else we just union the types.\n      _ExtractUnion<MAX_DEPTH, T, IncludePrefix, Ignore, Pre, DEPTH> | T[typeof Type],\n  NONE\n>;\n\ntype _DEPTHCOUNT = 1 | 2 | 3 | 4 | 5;\ntype INC_DEPTH<START extends _DEPTHCOUNT> = START extends 1 ? 2 : START extends 2 ? 3 : START extends 3 ? 4 : 5;\ntype IS_MAX_DEPTH<\n  DEPTH extends _DEPTHCOUNT,\n  MAX_DEPTH extends _DEPTHCOUNT = DEFAULT_MAX_DEPTH,\n> = DEPTH extends MAX_DEPTH ? true : false;\ntype DEFAULT_MAX_DEPTH = 3;\n/**\n * A utility that provides the union of all ResourceName for all potential\n * includes for the given TypedRecordInstance.\n *\n */\nexport type ExtractSuggestedCacheTypes<\n  T extends TypedRecordInstance,\n  MAX_DEPTH extends _DEPTHCOUNT = DEFAULT_MAX_DEPTH,\n> = ExtractUnion<MAX_DEPTH, T>; // ToPaths<ExpandIgnore<T, true>, false>;\n\n/**\n * A utility that provides the union type of all valid include paths for the given\n * TypedRecordInstance.\n *\n * Cyclical paths are filtered out.\n *\n */\nexport type Includes<T extends TypedRecordInstance, MAX_DEPTH extends _DEPTHCOUNT = DEFAULT_MAX_DEPTH> = ExtractUnion<\n  MAX_DEPTH,\n  T,\n  true\n>;\n\n/**\n * A type-erased placeholder for a record instance, used where the\n * specific record type is not known or not relevant.\n */\nexport type OpaqueRecordInstance = unknown;\n\n/**\n * @internal\n */\nexport type _StringSatisfiesIncludes<T extends string, SET extends string, FT extends string> = T extends SET\n  ? FT\n  : T extends `${infer U},${infer V}`\n    ? U extends SET\n      ? _StringSatisfiesIncludes<V, Exclude<SET, U>, FT>\n      : never\n    : never;\n\n/**\n * Validates that the comma-separated-string `T` (e.g. `'company,company.ceo,friends'`)\n * only contains paths present in the union `SET` (typically {@link Includes}).\n *\n * TypeScript cannot autocomplete against this type; prefer {@link createIncludeValidator}\n * for a better development experience unless you are writing a similar wrapper utility.\n *\n * @example\n * ```ts\n * import type { StringSatisfiesIncludes, Includes } from '@warp-drive-mirror/core/types/record';\n *\n * const includes: StringSatisfiesIncludes<\n *   'company,company.ceo,friends',\n *   Includes<User>\n * > = 'company,company.ceo,friends';\n * ```\n */\nexport type StringSatisfiesIncludes<T extends string, SET extends string> = _StringSatisfiesIncludes<T, SET, T>;\n\n/**\n * Creates a runtime validator function for comma-separated `include` strings,\n * ensuring at compile time that only valid paths for `T` (per {@link Includes})\n * are supplied.\n *\n * @example\n * ```ts\n * import { createIncludeValidator } from '@warp-drive-mirror/core/types/record';\n *\n * const userIncludesValidator = createIncludeValidator<User>;\n *\n * userIncludesValidator('company,company.ceo,friends');\n * ```\n */\nexport function createIncludeValidator<T extends TypedRecordInstance>() {\n  return function validateIncludes<U extends string>(includes: StringSatisfiesIncludes<U, Includes<T>>): U {\n    return includes;\n  };\n}\n\n/**\n * A utility that takes two types, K and T, and produces a new type that is a \"mask\" of T based on K.\n *\n * That's a mouthful, so let's break it down:\n *\n * Let's say you have a User type and an Address type.\n *\n * ```ts\n * interface Address {\n *   street: string;\n *   city: string;\n *   state: string;\n *   zip: string;\n * }\n *\n * interface User {\n *   name: string;\n *   title: string;\n *   address: Address;\n * }\n * ```\n *\n * Now, imagine you want to load a preview of the user with some information about their address,\n * but you don't want to load the entire user or address. You probably want to still ensure\n * the type of the data you do load matches the underlying Address and User types, but doesn't\n * include everything.\n *\n * If you did this manually, you might do something like this:\n *\n * ```ts\n * interface UserPreview {\n *   name: string;\n *   address: AddressPreview;\n * }\n *\n * interface AddressPreview {\n *   city: string;\n * }\n * ```\n *\n * From a TypeScript performance perspective, this is the best way to approach these preview\n * types, but this is also tedious and error-prone, especially if the User or Address types change.\n *\n * For Address, we could create a validated type using `Pick`:\n *\n * ```ts\n * type AddressPreview = Pick<Address, 'city'>;\n * ```\n *\n * This ensures that if the Address type changes, our AddressPreview will still be valid.\n * However, for UserPreview, we can't just use `Pick` because the `address` property is of type `Address`,\n * not `AddressPreview`. This is where the `Mask` type comes in.\n *\n * With `Mask`, we define the `UserPreview` in two parts\n * - first, we define the subset of fields we want to include from `User`, using `Pick` or an interface.\n * - then, we use `Mask` to replace the related types of fields like Address with their more limited subset.\n *\n * Here's how we can do it:\n *\n * ```ts\n * // First, we define the base of UserPreview with Pick\n * type UserPreviewBase = Pick<User, 'name' | 'address'>;\n * // Then, we use Mask to replace Address with AddressPreview\n * type UserPreview = Mask<{ address: AddressPreview }, UserPreviewBase>;\n * ```\n *\n * Now, `UserPreview` will have the `name` field from `User` and the `address` field will be of type `AddressPreview`.\n * This way, if the `User` or `Address` types change, TypeScript will ensure that our `UserPreview` and `AddressPreview`\n * types remain valid and consistent with the underlying types.\n *\n * But what if your app has data with massive interfaces such that the TypeScript performance of this\n * approach becomes a problem? In that case, see {@link Validate}\n */\nexport type Mask<K extends object, T extends K> = {\n  [P in keyof T]: P extends keyof K ? (T[P] extends K[P] ? K[P] : never) : T[P];\n};\n\n/**\n * A utility that takes two types, K and T, and ensures that K is a valid subset of T.\n *\n * That's a mouthful, so let's break it down:\n *\n * Let's say you have a User type and an Address type.\n *\n * ```ts\n * interface Address {\n *   street: string;\n *   city: string;\n *   state: string;\n *   zip: string;\n * }\n *\n * interface User {\n *   name: string;\n *   title: string;\n *   address: Address;\n * }\n * ```\n *\n * Now, imagine you want to load a preview of the user with some information about their address,\n * but you don't want to load the entire user or address. You probably want to still ensure\n * the type of the data you do load matches the underlying Address and User types, but doesn't\n * include everything.\n *\n * You might do something like this:\n *\n * ```ts\n * interface UserPreview {\n *   name: string;\n *   address: AddressPreview;\n * }\n *\n * interface AddressPreview {\n *   city: string;\n * }\n * ```\n *\n * From a TypeScript performance perspective, this is the best way to approach these preview\n * types, but this is also error-prone, especially if the User or Address types change.\n *\n * Validate can help ensure that your preview types remain valid.\n *\n * ```ts\n * type IsValidUserPreview = Validate<UserPreview, User>; // This will be valid\n * ```\n *\n * For help creating subsets of types, see {@link Mask}\n */\nexport type Validate<K extends object, T extends K> = T extends K ? K : never;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgOA,SAAgBA,yBAAwD;CACtE,OAAO,SAASC,iBAAmCC,UAAsD;EACvG,OAAOA;CACT;AACF"}
+{"version":3,"file":"record.js","names":["createIncludeValidator","validateIncludes","includes"],"sources":["../../../../src/types/record.ts"],"sourcesContent":["/**\n * @module\n * @summary Types for records that declare their resource type via the `[Type]` symbol, including `TypedRecordInstance`,\n * `Includes`, `Mask` and the `createIncludeValidator` helper.\n */\n\nimport type { Type } from './symbols.ts';\n\n/**\n * Records may be anything, They don't even\n * have to be objects.\n *\n * Whatever they are, if they have a Type\n * property, that property will be used by WarpDrive\n * and WarpDrive to provide better type safety and\n * intellisense.\n *\n * @summary Shape of a record type that declares its resource type via the `[Type]` symbol, letting WarpDrive APIs\n * infer types for better type safety.\n * @class TypedRecordInstance\n */\nexport interface TypedRecordInstance {\n  /**\n   * The type of the resource.\n   *\n   * This is an optional feature that can be used by\n   * record implementations to provide a typescript\n   * hint for the type of the resource.\n   *\n   * When used, WarpDrive APIs can\n   * take advantage of this to provide better type\n   * safety and intellisense.\n   *\n   * @property [Type]\n   * @type {Type}\n   * @type {String}\n   */\n  [Type]: string;\n}\n\n/**\n * A type utility that extracts the Type if available,\n * otherwise it returns never.\n *\n * @summary Type utility giving a record type's `[Type]` resource type string, or `never` if it declares none.\n */\nexport type TypeFromInstance<T> = T extends TypedRecordInstance ? T[typeof Type] : never;\n\n/**\n * A type utility that extracts the Type if available,\n * otherwise it returns string\n *\n * @summary Type utility giving a record type's `[Type]` resource type string, or `string` if it declares none.\n */\nexport type TypeFromInstanceOrString<T> = T extends TypedRecordInstance ? T[typeof Type] : string;\n\ntype IsUniqueSymbol<T> = T extends `___(unique) Symbol(${string})` ? true : false;\ntype Unpacked<T> = T extends (infer U)[] ? U : T;\ntype NONE = { __NONE: never };\n\ntype __InternalExtract<\n  MAX_DEPTH extends _DEPTHCOUNT,\n  T extends TypedRecordInstance,\n  V extends TypedRecordInstance,\n  IncludePrefix extends boolean,\n  Ignore,\n  Pre extends string,\n  DEPTH extends _DEPTHCOUNT,\n> =\n  // if we extend T, we return the leaf value\n  V extends T\n    ? IncludePrefix extends false\n      ? V[typeof Type]\n      : Pre\n    : // else if we are in Ignore we add the lead and exit\n      V extends Ignore\n      ? IncludePrefix extends false\n        ? V[typeof Type]\n        : Pre\n      : // else if we are at max depth, we return never\n        IS_MAX_DEPTH<DEPTH, MAX_DEPTH> extends true\n        ? Pre\n        : // else add T to Ignore and recurse\n          ExtractUnion<MAX_DEPTH, V, IncludePrefix, Ignore | T, Pre, INC_DEPTH<DEPTH>>;\n\ntype __ExtractIfRecord<\n  MAX_DEPTH extends _DEPTHCOUNT,\n  T extends TypedRecordInstance,\n  V,\n  IncludePrefix extends boolean,\n  Ignore,\n  Pre extends string,\n  DEPTH extends _DEPTHCOUNT,\n> = V extends TypedRecordInstance ? __InternalExtract<MAX_DEPTH, T, V, IncludePrefix, Ignore, Pre, DEPTH> : never;\n\ntype _ExtractUnion<\n  MAX_DEPTH extends _DEPTHCOUNT,\n  T extends TypedRecordInstance,\n  IncludePrefix extends boolean,\n  Ignore,\n  Pre,\n  DEPTH extends _DEPTHCOUNT,\n> = {\n  // for each string key in the record,\n  [K in keyof T]: IsUniqueSymbol<K> extends true\n    ? never\n    : K extends string\n      ? // we recursively extract any values that resolve to a TypedRecordInstance\n        __ExtractIfRecord<\n          MAX_DEPTH,\n          T,\n          Unpacked<Awaited<T[K]>>,\n          IncludePrefix,\n          Ignore,\n          Pre extends string ? `${Pre}.${K}` : K,\n          DEPTH\n        >\n      : never;\n  // then we return any value that is not 'never'\n}[keyof T];\n\n/**\n * A Utility that extracts either resource types or resource paths from a TypedRecordInstance.\n *\n * Its limitations are mostly around its intentional non-recursiveness. It presumes that APIs which\n * implement includes will not allow cyclical include paths, and will collapse includes by type.\n *\n * This follows closer to the JSON:API fields spec than to the includes spec in nature, but in\n * practice it is so impracticle for an API to allow z-algo include paths that this is probably\n * reasonable.\n *\n * We may need to revisit this in the future, opting to either make this restriction optional or\n * to allow for other strategies.\n *\n * There's a 90% chance this particular implementation belongs being in the JSON:API package instead\n * of core-types, but it's here for now.\n *\n */\ntype ExtractUnion<\n  MAX_DEPTH extends _DEPTHCOUNT,\n  T extends TypedRecordInstance,\n  IncludePrefix extends boolean = false,\n  Ignore = NONE,\n  Pre = NONE,\n  DEPTH extends _DEPTHCOUNT = 1,\n> = Exclude<\n  IncludePrefix extends true\n    ? // if we want to include prefix, we union with the prefix. Outer Exclude will filter any \"NONE\" types\n      _ExtractUnion<MAX_DEPTH, T, IncludePrefix, Ignore, Pre, DEPTH> | Pre\n    : // Else we just union the types.\n      _ExtractUnion<MAX_DEPTH, T, IncludePrefix, Ignore, Pre, DEPTH> | T[typeof Type],\n  NONE\n>;\n\ntype _DEPTHCOUNT = 1 | 2 | 3 | 4 | 5;\ntype INC_DEPTH<START extends _DEPTHCOUNT> = START extends 1 ? 2 : START extends 2 ? 3 : START extends 3 ? 4 : 5;\ntype IS_MAX_DEPTH<\n  DEPTH extends _DEPTHCOUNT,\n  MAX_DEPTH extends _DEPTHCOUNT = DEFAULT_MAX_DEPTH,\n> = DEPTH extends MAX_DEPTH ? true : false;\ntype DEFAULT_MAX_DEPTH = 3;\n/**\n * A utility that provides the union of all ResourceName for all potential\n * includes for the given TypedRecordInstance.\n *\n * @summary Type utility giving the union of resource types reachable from a typed record through its\n * relationships, up to a max depth.\n */\nexport type ExtractSuggestedCacheTypes<\n  T extends TypedRecordInstance,\n  MAX_DEPTH extends _DEPTHCOUNT = DEFAULT_MAX_DEPTH,\n> = ExtractUnion<MAX_DEPTH, T>; // ToPaths<ExpandIgnore<T, true>, false>;\n\n/**\n * A utility that provides the union type of all valid include paths for the given\n * TypedRecordInstance.\n *\n * Cyclical paths are filtered out.\n *\n * @summary Type utility giving the union of valid dot-separated `include` relationship paths for a typed record,\n * excluding cycles.\n */\nexport type Includes<T extends TypedRecordInstance, MAX_DEPTH extends _DEPTHCOUNT = DEFAULT_MAX_DEPTH> = ExtractUnion<\n  MAX_DEPTH,\n  T,\n  true\n>;\n\n/**\n * A type-erased placeholder for a record instance, used where the\n * specific record type is not known or not relevant.\n *\n * @summary Type-erased (`unknown`) stand-in for a record instance where its specific type is unknown or irrelevant.\n */\nexport type OpaqueRecordInstance = unknown;\n\n/**\n * @internal\n */\nexport type _StringSatisfiesIncludes<T extends string, SET extends string, FT extends string> = T extends SET\n  ? FT\n  : T extends `${infer U},${infer V}`\n    ? U extends SET\n      ? _StringSatisfiesIncludes<V, Exclude<SET, U>, FT>\n      : never\n    : never;\n\n/**\n * Validates that the comma-separated-string `T` (e.g. `'company,company.ceo,friends'`)\n * only contains paths present in the union `SET` (typically {@link Includes}).\n *\n * TypeScript cannot autocomplete against this type; prefer {@link createIncludeValidator}\n * for a better development experience unless you are writing a similar wrapper utility.\n *\n * @summary Type utility that checks a comma-separated `include` string contains only paths from an allowed union,\n * resolving to `never` otherwise.\n * @example\n * ```ts\n * import type { StringSatisfiesIncludes, Includes } from '@warp-drive-mirror/core/types/record';\n *\n * const includes: StringSatisfiesIncludes<\n *   'company,company.ceo,friends',\n *   Includes<User>\n * > = 'company,company.ceo,friends';\n * ```\n */\nexport type StringSatisfiesIncludes<T extends string, SET extends string> = _StringSatisfiesIncludes<T, SET, T>;\n\n/**\n * Creates a runtime validator function for comma-separated `include` strings,\n * ensuring at compile time that only valid paths for `T` (per {@link Includes})\n * are supplied.\n *\n * @summary Returns a function that type-checks a comma-separated `include` string against the valid relationship paths\n * of a record type and returns it unchanged.\n * @example\n * ```ts\n * import { createIncludeValidator } from '@warp-drive-mirror/core/types/record';\n *\n * const userIncludesValidator = createIncludeValidator<User>;\n *\n * userIncludesValidator('company,company.ceo,friends');\n * ```\n */\nexport function createIncludeValidator<T extends TypedRecordInstance>() {\n  return function validateIncludes<U extends string>(includes: StringSatisfiesIncludes<U, Includes<T>>): U {\n    return includes;\n  };\n}\n\n/**\n * A utility that takes two types, K and T, and produces a new type that is a \"mask\" of T based on K.\n *\n * That's a mouthful, so let's break it down:\n *\n * Let's say you have a User type and an Address type.\n *\n * ```ts\n * interface Address {\n *   street: string;\n *   city: string;\n *   state: string;\n *   zip: string;\n * }\n *\n * interface User {\n *   name: string;\n *   title: string;\n *   address: Address;\n * }\n * ```\n *\n * Now, imagine you want to load a preview of the user with some information about their address,\n * but you don't want to load the entire user or address. You probably want to still ensure\n * the type of the data you do load matches the underlying Address and User types, but doesn't\n * include everything.\n *\n * If you did this manually, you might do something like this:\n *\n * ```ts\n * interface UserPreview {\n *   name: string;\n *   address: AddressPreview;\n * }\n *\n * interface AddressPreview {\n *   city: string;\n * }\n * ```\n *\n * From a TypeScript performance perspective, this is the best way to approach these preview\n * types, but this is also tedious and error-prone, especially if the User or Address types change.\n *\n * For Address, we could create a validated type using `Pick`:\n *\n * ```ts\n * type AddressPreview = Pick<Address, 'city'>;\n * ```\n *\n * This ensures that if the Address type changes, our AddressPreview will still be valid.\n * However, for UserPreview, we can't just use `Pick` because the `address` property is of type `Address`,\n * not `AddressPreview`. This is where the `Mask` type comes in.\n *\n * With `Mask`, we define the `UserPreview` in two parts\n * - first, we define the subset of fields we want to include from `User`, using `Pick` or an interface.\n * - then, we use `Mask` to replace the related types of fields like Address with their more limited subset.\n *\n * Here's how we can do it:\n *\n * ```ts\n * // First, we define the base of UserPreview with Pick\n * type UserPreviewBase = Pick<User, 'name' | 'address'>;\n * // Then, we use Mask to replace Address with AddressPreview\n * type UserPreview = Mask<{ address: AddressPreview }, UserPreviewBase>;\n * ```\n *\n * Now, `UserPreview` will have the `name` field from `User` and the `address` field will be of type `AddressPreview`.\n * This way, if the `User` or `Address` types change, TypeScript will ensure that our `UserPreview` and `AddressPreview`\n * types remain valid and consistent with the underlying types.\n *\n * But what if your app has data with massive interfaces such that the TypeScript performance of this\n * approach becomes a problem? In that case, see {@link Validate}\n *\n * @summary Type utility that builds a preview type from `T` by replacing selected fields with narrower subset types\n * from `K`, resolving to `never` where a field is not compatible.\n */\nexport type Mask<K extends object, T extends K> = {\n  [P in keyof T]: P extends keyof K ? (T[P] extends K[P] ? K[P] : never) : T[P];\n};\n\n/**\n * A utility that takes two types, K and T, and ensures that K is a valid subset of T.\n *\n * That's a mouthful, so let's break it down:\n *\n * Let's say you have a User type and an Address type.\n *\n * ```ts\n * interface Address {\n *   street: string;\n *   city: string;\n *   state: string;\n *   zip: string;\n * }\n *\n * interface User {\n *   name: string;\n *   title: string;\n *   address: Address;\n * }\n * ```\n *\n * Now, imagine you want to load a preview of the user with some information about their address,\n * but you don't want to load the entire user or address. You probably want to still ensure\n * the type of the data you do load matches the underlying Address and User types, but doesn't\n * include everything.\n *\n * You might do something like this:\n *\n * ```ts\n * interface UserPreview {\n *   name: string;\n *   address: AddressPreview;\n * }\n *\n * interface AddressPreview {\n *   city: string;\n * }\n * ```\n *\n * From a TypeScript performance perspective, this is the best way to approach these preview\n * types, but this is also error-prone, especially if the User or Address types change.\n *\n * Validate can help ensure that your preview types remain valid.\n *\n * ```ts\n * type IsValidUserPreview = Validate<UserPreview, User>; // This will be valid\n * ```\n *\n * For help creating subsets of types, see {@link Mask}\n *\n * @summary Type utility that checks a hand-written preview type `K` is a valid subset of the full type `T`, resolving\n * to `K` if so and `never` otherwise.\n */\nexport type Validate<K extends object, T extends K> = T extends K ? K : never;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoPA,SAAgBA,yBAAwD;CACtE,OAAO,SAASC,iBAAmCC,UAAsD;EACvG,OAAOA;CACT;AACF"}

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

@@ -2,15 +2,26 @@ import { getOrSetGlobal, getOrSetUniversal } from "./-private.js";
 
 //#region src/types/request.ts
 /**
+* @module
+* @summary Types for requests and responses: `RequestInfo`, the request shapes builders return, cache options, the
+* handler context and the documents a request's `Future` settles with.
+*/
+/**
 * A {@link RequestInfo.cacheOptions | cacheOptions} flag which, when set,
 * signals that a request should never be handled by the cache-manager and
 * thus will never resolve from cache nor update the cache.
+*
+* @summary Symbol key for a request's `cacheOptions` that, when true, makes the request bypass the CacheHandler so it
+* neither resolves from nor updates the cache.
 */
 const SkipCache = getOrSetUniversal("SkipCache", Symbol.for("wd:skip-cache"));
 /**
 * A {@link RequestInfo} flag which, when set, signals to the store's
 * `instantiateRecord` hook that the resolved content should be hydrated
 * into reactive records rather than returned as raw data.
+*
+* @summary Symbol flag on a request that makes the CacheHandler return reactive records instead of raw cache
+* documents; `store.request` sets it automatically.
 */
 const EnableHydration = getOrSetUniversal("EnableHydration", Symbol.for("wd:enable-hydration"));
 /**
@@ -23,61 +34,104 @@ const IS_FUTURE = getOrSetGlobal("IS_FUTURE", Symbol("IS_FUTURE"));
 const STRUCTURED = getOrSetGlobal("DOC", Symbol("DOC"));
 /**
 * The HTTP methods WarpDrive's request layer supports.
+*
+* @summary Union of the HTTP method strings, including `QUERY`, that a WarpDrive request's `method` may be set to.
 */
 /**
 * Use these options to adjust {@link CacheHandler} behavior for a request
 * via {@link RequestInfo.cacheOptions}.
 *
+* @summary Per-request settings on `cacheOptions` that control the cache key, forced or background reloads,
+* invalidation by resource type, and cache bypass.
 */
 /**
 * The request shape produced by the `findRecord` request builders, for
 * use with {@link Store.request}.
+*
+* @summary Shape of the `GET` request object that `findRecord` builders return for `store.request`, carrying the url,
+* headers, and requested resource identifier.
 */
 /**
 * The request shape produced by the `query` request builders, for
 * use with {@link Store.request}.
+*
+* @summary Shape of the `GET` request object that `query` builders return for `store.request`, carrying the url,
+* headers, and cache options.
 */
 /**
 * The request shape produced by the `postQuery` request builders, for
 * use with {@link Store.request}.
+*
+* @summary Shape of the `POST` or `QUERY` request object that `postQuery` builders return, with a body and a required
+* cache key since the url cannot serve as one.
 */
 /**
 * The request shape produced by the `deleteRecord` request builders, for
 * use with {@link Store.request}.
+*
+* @summary Shape of the `DELETE` request object that `deleteRecord` builders return for `store.request`, identifying
+* the resource being deleted.
 */
 /**
 * The request shape produced by the `updateRecord` request builders, for
 * use with {@link Store.request}.
+*
+* @summary Shape of the `PATCH` or `PUT` request object that `updateRecord` builders return for `store.request`,
+* identifying the resource being saved.
 */
 /**
 * The request shape produced by the `createRecord` request builders, for
 * use with {@link Store.request}.
+*
+* @summary Shape of the `POST` request object that `createRecord` builders return for `store.request`, identifying the
+* new resource being saved.
 */
 /**
 * The immutable, handler-facing form of {@link DeleteRequestOptions}.
+*
+* @summary Read-only view of a `deleteRecord` request as a handler receives it, with immutable headers and `records`
+* as resource keys.
 */
 /**
 * The immutable, handler-facing form of {@link UpdateRequestOptions}.
+*
+* @summary Read-only view of an `updateRecord` request as a handler receives it, with immutable headers and `records`
+* as resource keys.
 */
 /**
 * The immutable, handler-facing form of {@link CreateRequestOptions}.
+*
+* @summary Read-only view of a `createRecord` request as a handler receives it, with immutable headers and `records`
+* as resource keys.
 */
 /**
 * A minimal reference to a resource sufficient to build a URL for it,
 * as accepted by the request builders.
+*
+* @summary A resource reference with a persisted `id` and `type` and an optional `lid`, which is enough for request
+* builders to construct its url.
 */
 /**
 * Options accepted by the request builders for constraining how a
 * request's url is constructed and how the request interacts with the cache.
+*
+* @summary Options the request builders accept to set reload behavior and override the url's host, namespace, resource
+* path, and query param serialization.
 */
 /**
 * Options accepted by the `findRecord` request builders.
+*
+* @summary Options the `findRecord` request builders accept: the shared url and reload options plus the relationship
+* paths to `include`.
 */
 /**
 * When a {@link Future} resolves, it returns an object
 * containing the original {@link RequestInfo | request},
 * the {@link Response | response} set by the handler chain (if any), and
 * the processed content.
+*
+* @summary The `{ request, response, content }` object that a request's `Future` resolves with when the request
+* succeeds.
 */
 /**
 * When a {@link Future} rejects, it throws either an {@link Error}
@@ -87,16 +141,24 @@ const STRUCTURED = getOrSetGlobal("DOC", Symbol("DOC"));
 *
 * If using the error originates from the {@link Fetch | Fetch Handler}
 * the error will be a {@link FetchError}
+*
+* @summary The Error a request's `Future` rejects with when the request fails, carrying the `request`, `response`,
+* `error`, and any `content` received.
 */
 /**
 * A union of the resolve/reject data types for the {@link Future}
 * returned by {@link Store.request | request}
 *
+* The [Using The Response](/guides/the-manual/requests/using-the-response) guide shows
+* how to read one.
+*
 * See also the docs for:
 *
 * - {@link Future}
 * - {@link StructuredDataDocument} (resolved/successful requests)
 * - {@link StructuredErrorDocument} (rejected/failed requests)
+*
+* @summary Union of the success and error documents that a request's `Future` resolves or rejects with.
 */
 /**
 * The {@link RequestInit} interface accepted by the native {@link fetch} API.
@@ -112,6 +174,9 @@ const STRUCTURED = getOrSetGlobal("DOC", Symbol("DOC"));
 /**
 * A read-only {@link Headers} instance, as passed to {@link Handler | Handlers}
 * via {@link ImmutableRequestInfo.headers}.
+*
+* @summary Read-only `Headers` that handlers see on a request, adding `toJSON` to serialize them as `[key, value]`
+* pairs and an optional mutable `clone`.
 */
 /**
 * Extends JavaScript's native {@link fetch} {@link NativeRequestInit | RequestInit} with additional
@@ -120,6 +185,11 @@ const STRUCTURED = getOrSetGlobal("DOC", Symbol("DOC"));
 * This interface is used to define the shape of a request that can be made via
 * either the {@link RequestManager.request} or {@link Store.request} methods.
 *
+* The [Making Requests](/guides/the-manual/requests/#request-options) guide explains
+* its options.
+*
+* @summary Describes a request for `store.request` or `RequestManager.request`: native fetch options plus cache
+* options, operation name, records, data, and the store.
 * @privateRemarks
 * - [MDN Reference (fetch)](https://developer.mozilla.org/docs/Web/API/Window/fetch)
 * - [MDN Reference (RequestInit)](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)
@@ -131,15 +201,25 @@ const STRUCTURED = getOrSetGlobal("DOC", Symbol("DOC"));
 /**
 * Immutable version of {@link RequestInfo}. This is what is passed to handlers.
 *
+* @summary Read-only form of a request as handlers receive it, with frozen headers, data, options, and cache options
+* and no `controller`.
 */
 /**
 * An immutable, JSON-serializable subset of the native {@link Response}
 * interface.
+*
+* @summary Immutable, JSON-serializable snapshot of a fetch `Response`'s headers, status, url, and type, usable in
+* place of a `Response` in request results.
 */
 /**
 * The object a {@link Handler} uses to fulfill a request: it provides a
 * readonly view of the {@link RequestContext.request | request} and methods
 * for supplying the {@link Future}'s stream and final response.
+*
+* The [Handlers](/guides/the-manual/requests/handlers) guide shows a handler using it.
+*
+* @summary Object passed to each request handler with the immutable request, a request id, and methods for setting the
+* response stream and the response.
 */
 //#endregion
 export { EnableHydration, IS_FUTURE, STRUCTURED, SkipCache };