@warp-drive/core 5.8.0-alpha.30 → 5.8.0-alpha.34

package/dist/unpkg/dev/declarations/store/-private/default-cache-policy.d.ts

@@ -0,0 +1,387 @@
+import type { Cache } from "@warp-drive/core/types/cache";
+import type { RequestKey, ResourceKey } from "@warp-drive/core/types/identifier";
+import type { ImmutableRequestInfo, ResponseInfo, StructuredDocument } from "@warp-drive/core/types/request";
+import type { ResourceDocument } from "@warp-drive/core/types/spec/document";
+import type { CachePolicy } from "../-private.js";
+type UnsubscribeToken = object;
+type CacheOperation = "added" | "removed" | "updated" | "state";
+type DocumentCacheOperation = "invalidated" | "added" | "removed" | "updated" | "state";
+export interface NotificationCallback {
+	(resourceKey: ResourceKey, notificationType: "attributes" | "relationships", key?: string): void;
+	(resourceKey: ResourceKey, notificationType: "errors" | "meta" | "identity" | "state"): void;
+}
+interface ResourceOperationCallback {
+	(resourceKey: ResourceKey, notificationType: CacheOperation): void;
+}
+interface DocumentOperationCallback {
+	(cacheKey: RequestKey, notificationType: DocumentCacheOperation): void;
+}
+type NotificationManager = {
+	subscribe(resourceKey: ResourceKey, callback: NotificationCallback): UnsubscribeToken;
+	subscribe(cacheKey: "resource", callback: ResourceOperationCallback): UnsubscribeToken;
+	subscribe(cacheKey: "document" | RequestKey, callback: DocumentOperationCallback): UnsubscribeToken;
+	notify(cacheKey: ResourceKey, value: "attributes" | "relationships", key?: string): boolean;
+	notify(cacheKey: ResourceKey, value: "errors" | "meta" | "identity" | "state"): boolean;
+	notify(cacheKey: ResourceKey, value: CacheOperation): boolean;
+	notify(cacheKey: RequestKey, value: DocumentCacheOperation): boolean;
+};
+type Store = {
+	cache: Cache;
+	notifications: NotificationManager;
+};
+/**
+* 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)
+*/
+export interface CacheControlValue {
+	immutable?: boolean;
+	"max-age"?: number;
+	"must-revalidate"?: boolean;
+	"must-understand"?: boolean;
+	"no-cache"?: boolean;
+	"no-store"?: boolean;
+	"no-transform"?: boolean;
+	"only-if-cached"?: boolean;
+	private?: boolean;
+	"proxy-revalidate"?: boolean;
+	public?: boolean;
+	"s-maxage"?: number;
+	"stale-if-error"?: number;
+	"stale-while-revalidate"?: number;
+}
+/**
+*  Parses a string Cache-Control header value into an object with the following structure:
+*
+* ```ts
+* interface CacheControlValue {
+*   immutable?: boolean;
+*   'max-age'?: number;
+*   'must-revalidate'?: boolean;
+*   'must-understand'?: boolean;
+*   'no-cache'?: boolean;
+*   'no-store'?: boolean;
+*   'no-transform'?: boolean;
+*   'only-if-cached'?: boolean;
+*   private?: boolean;
+*   'proxy-revalidate'?: boolean;
+*   public?: boolean;
+*   's-maxage'?: number;
+*   'stale-if-error'?: number;
+*   'stale-while-revalidate'?: number;
+* }
+* ```
+*
+* See also {@link CacheControlValue} and [Response Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#response_directives)
+*
+* @public
+*/
+export declare function parseCacheControl(header: string): CacheControlValue;
+/**
+* The constraint options for {@link PolicyConfig.constraints}
+*/
+export interface PolicyConfigConstraints {
+	/**
+	* Headers that should be checked for expiration.
+	*
+	*/
+	headers?: {
+		/**
+		* Whether the `Cache-Control` header should be checked for expiration.
+		* If `true`, then the `max-age` and `s-maxage` directives are used alongside
+		* the `Age` and `Date` headers to determine if the expiration time has passed.
+		*
+		* Other directives are ignored.
+		*
+		* 'Cache-Control' will take precedence over 'Expires' if both are present
+		* and both configured to be checked.
+		*
+		*/
+		"Cache-Control"?: boolean;
+		/**
+		* Whether the `Expires` header should be checked for expiration.
+		*
+		* If `true`, then the `Expires` header is used to caclulate the expiration time
+		* and determine if the expiration time has passed.
+		*
+		* 'Cache-Control' will take precedence over 'Expires' if both are present.
+		*
+		*/
+		Expires?: boolean;
+		/**
+		* Whether the `X-WarpDrive-Expires` header should be checked for expiration.
+		*
+		* If `true`, then the `X-WarpDrive-Expires` header is used to caclulate the expiration time
+		* and determine if the expiration time has passed.
+		*
+		* This header will take precedence over 'Cache-Control' and 'Expires' if all three are present.
+		*
+		* The header's value should be a [UTC date string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toUTCString).
+		*
+		*/
+		"X-WarpDrive-Expires"?: boolean;
+	};
+	/**
+	* A function that should be called to determine if the request is expired.
+	*
+	* If present, this function will be called with the request and should return
+	* `true` if the request is expired, `false` if it is not expired, and
+	* `null` if the expiration status is unknown.
+	*
+	* If the function does not return `null`,
+	*
+	*/
+	isExpired?: (request: StructuredDocument<ResourceDocument>) => boolean | null;
+}
+/**
+* The configuration options for the {@link DefaultCachePolicy}
+*
+* ```ts [app/services/store.ts]
+* import { Store } from '@warp-drive/core';
+* import { DefaultCachePolicy } from '@warp-drive/core/store'; // [!code focus]
+*
+* export default class AppStore extends Store {
+*   lifetimes = new DefaultCachePolicy({ // [!code focus:3]
+*     // ... PolicyConfig Settings ... //
+*   });
+* }
+* ```
+*
+*/
+export interface PolicyConfig {
+	/**
+	* the number of milliseconds after which a request is considered
+	* stale. If a request is issued again after this time, the request
+	* will respond from cache immediately while a background request
+	* is made to update the cache.
+	*
+	* This is calculated against the `date` header of the response.
+	*
+	* If your API does not provide a `date` header, the {@link Fetch} handler
+	* will automatically add it to responses if it is not present. Responses
+	* without a `date` header will be considered stale immediately.
+	*
+	*/
+	apiCacheSoftExpires: number;
+	/**
+	* the number of milliseconds after which a request is considered
+	* expired and should be re-fetched. If a request is issued again
+	* after this time, the request will disregard the cache and
+	* wait for a fresh response from the API.
+	*
+	* This is calculated against the `date` header of the response.
+	*
+	* If your API does not provide a `date` header, the {@link Fetch} handler
+	* will automatically add it to responses if it is not present. Responses
+	* without a `date` header will be considered hard expired immediately.
+	*
+	*/
+	apiCacheHardExpires: number;
+	/**
+	* In Testing environments, the `apiCacheSoftExpires` will always be `false`
+	* and `apiCacheHardExpires` will use the `apiCacheSoftExpires` value.
+	*
+	* This helps reduce flakiness and produce predictably rendered results in test suites.
+	*
+	* Requests that specifically set {@link RequestInfo.cacheOptions.backgroundReload | cacheOptions.backgroundReload }
+	* will still be background reloaded in tests.
+	*
+	* This behavior can be opted out of by setting this value to `true`.
+	*
+	*/
+	disableTestOptimization?: boolean;
+	/**
+	* In addition to the simple time-based expiration strategy, CachePolicy
+	* supports various common server-supplied expiration strategies via
+	* headers, as well as custom expiration strategies via the {@link PolicyConfigConstraints.isExpired | isExpired}
+	* function.
+	*
+	* Requests will be validated for expiration against these constraints.
+	* If any of these constraints are not met, the request will be considered
+	* expired. If all constraints are met, the request will be considered
+	* valid and the time based expiration strategy will NOT be used.
+	*
+	* Meeting a constraint means BOTH that the properties the constraint
+	* requires are present AND that the expiration time indicated by those
+	* properties has not been exceeded.
+	*
+	* In other words, if the properties for a constraint are not present,
+	* this does not count either as meeting or as not meeting the constraint,
+	* the constraint simply does not apply.
+	*
+	* The `isExpired` function is called with the request and should return
+	* `true` if the request is expired, `false` if it is not expired, and
+	* `null` if the expiration status is unknown.
+	*
+	* In order constraints are checked:
+	*
+	* - isExpired function
+	* -  ↳ (if null) X-WarpDrive-Expires header
+	* -  ↳ (if null) Cache-Control header
+	* -  ↳ (if null) Expires header
+	*
+	* See {@link PolicyConfigConstraints} for configuration options.
+	*/
+	constraints?: PolicyConfigConstraints;
+}
+/**
+* A basic {@link CachePolicy} that can be added to the Store service.
+*
+* ```ts [app/services/store.ts]
+* import { Store } from '@warp-drive/core';
+* import { DefaultCachePolicy } from '@warp-drive/core/store'; // [!code focus]
+*
+* export default class AppStore extends Store {
+*   lifetimes = new DefaultCachePolicy({ // [!code focus:5]
+*     apiCacheSoftExpires: 30_000,
+*     apiCacheHardExpires: 60_000,
+*     // ... Other PolicyConfig Settings ... //
+*   });
+* }
+* ```
+*
+* :::tip 💡 TIP
+* Date headers do not have millisecond precision, so expiration times should
+* generally be larger than 1000ms.
+* :::
+*
+* See also {@link PolicyConfig} for configuration options.
+*
+* ### The Mechanics
+*
+* This policy determines staleness based on various configurable constraints falling back to a simple
+* check of the time elapsed since the request was last received from the API using the `date` header
+* from the last response.
+*
+* :::tip 💡 TIP
+* The {@link Fetch} handler provided by `@warp-drive/core` will automatically
+* add the `date` header to responses if it is not present.
+* :::
+*
+* - For manual override of reload see {@link CacheOptions.reload | cacheOptions.reload}
+* - For manual override of background reload see {@link CacheOptions.backgroundReload | cacheOptions.backgroundReload}
+*
+* In order expiration is determined by:
+*
+* ```md
+* Is explicitly invalidated by `cacheOptions.reload`
+*   ↳ (if falsey) if the request has been explicitly invalidated
+*      since the last request (see Automatic Invalidation below)
+*   ↳ (if false) (If Active) isExpired function
+*   ↳ (if null) (If Active) X-WarpDrive-Expires header
+*   ↳ (if null) (If Active) Cache-Control header
+*   ↳ (if null) (If Active) Expires header
+*   ↳ (if null) Date header + apiCacheHardExpires < current time
+*
+*   -- <if above is false, a background request is issued if> --
+*
+*   ↳ is invalidated by `cacheOptions.backgroundReload`
+*   ↳ (if falsey) Date header + apiCacheSoftExpires < current time
+* ```
+*
+* ### Automatic Invalidation / Entanglement
+*
+* It also invalidates any request with an {@link RequestInfo.op | OpCode} of `"query"`
+* for which {@link CacheOptions.types | cacheOptions.types} was provided
+* when a request with an `OpCode` of `"createRecord"` is successful and also includes
+* a matching type in its own `cacheOptions.types` array.
+
+* :::tip 💡 TIP
+* Abstracting this behavior via builders is recommended to ensure consistency.
+* :::
+*
+* ### Testing
+*
+* In Testing environments:
+*
+* - `apiCacheSoftExpires` will always be `false`
+* - `apiCacheHardExpires` will use the `apiCacheSoftExpires` value.
+*
+* This helps reduce flakiness and produce predictably rendered results in test suites.
+*
+* Requests that specifically set `cacheOptions.backgroundReload = true` will
+* still be background reloaded in tests.
+*
+* This behavior can be opted out of by setting `disableTestOptimization = true`
+* in the policy config.
+*
+* @public
+*/
+export declare class DefaultCachePolicy implements CachePolicy {
+	constructor(config: PolicyConfig);
+	/**
+	* Invalidate a request by its CacheKey for the given store instance.
+	*
+	* While the store argument may seem redundant, the CachePolicy
+	* is designed to be shared across multiple stores / forks
+	* of the store.
+	*
+	* ```ts
+	* store.lifetimes.invalidateRequest(store, cacheKey);
+	* ```
+	*
+	* @public
+	*/
+	invalidateRequest(cacheKey: RequestKey, store: Store): void;
+	/**
+	* Invalidate all requests associated to a specific type
+	* for a given store instance.
+	*
+	* While the store argument may seem redundant, the CachePolicy
+	* is designed to be shared across multiple stores / forks
+	* of the store.
+	*
+	* This invalidation is done automatically when using this service
+	* for both the {@link CacheHandler} and the [NetworkHandler](/api/@warp-drive/legacy/compat/variables/LegacyNetworkHandler).
+	*
+	* ```ts
+	* store.lifetimes.invalidateRequestsForType(store, 'person');
+	* ```
+	*
+	* @public
+	*/
+	invalidateRequestsForType(type: string, store: Store): void;
+	/**
+	* Invoked when a request has been fulfilled from the configured request handlers.
+	* This is invoked by the CacheHandler for both foreground and background requests
+	* once the cache has been updated.
+	*
+	* Note, this is invoked by the {@link CacheHandler} regardless of whether
+	* the request has a cache-key.
+	*
+	* This method should not be invoked directly by consumers.
+	*
+	* @public
+	*/
+	didRequest(request: ImmutableRequestInfo, response: Response | ResponseInfo | null, cacheKey: RequestKey | null, store: Store): void;
+	/**
+	* Invoked to determine if the request may be fulfilled from cache
+	* if possible.
+	*
+	* Note, this is only invoked by the {@link CacheHandler} if the request has
+	* a cache-key.
+	*
+	* If no cache entry is found or the entry is hard expired,
+	* the request will be fulfilled from the configured request handlers
+	* and the cache will be updated before returning the response.
+	*
+	* @public
+	* @return true if the request is considered hard expired
+	*/
+	isHardExpired(cacheKey: RequestKey, store: Store): boolean;
+	/**
+	* Invoked if `isHardExpired` is false to determine if the request
+	* should be update behind the scenes if cache data is already available.
+	*
+	* Note, this is only invoked by the {@link CacheHandler} if the request has
+	* a cache-key.
+	*
+	* If true, the request will be fulfilled from cache while a backgrounded
+	* request is made to update the cache via the configured request handlers.
+	*
+	* @public
+	* @return true if the request is considered soft expired
+	*/
+	isSoftExpired(cacheKey: RequestKey, store: Store): boolean;
+}
+export {};

package/dist/unpkg/dev/declarations/store/-private/managers/cache-capabilities-manager.d.ts

@@ -0,0 +1,34 @@
+import type { RequestKey, ResourceKey } from "../../../types/identifier.js";
+import type { SchemaService } from "../../../types/schema/schema-service.js";
+import type { CacheCapabilitiesManager as StoreWrapper } from "../../-types/q/cache-capabilities-manager.js";
+import type { PrivateStore, Store } from "../store-service.js";
+import type { CacheKeyManager } from "./cache-key-manager.js";
+import type { NotificationType } from "./notification-manager.js";
+export interface CacheCapabilitiesManager {
+	/** @deprecated - use {@link CacheCapabilitiesManager.schema} */
+	getSchemaDefinitionService(): SchemaService;
+}
+export declare class CacheCapabilitiesManager implements StoreWrapper {
+	constructor(_store: Store);
+	get cacheKeyManager(): CacheKeyManager;
+	/** @deprecated use {@link CacheCapabilitiesManager.cacheKeyManager} */
+	get identifierCache(): CacheKeyManager;
+	notifyChange(identifier: ResourceKey, namespace: "added" | "removed", key: null): void;
+	notifyChange(identifier: RequestKey, namespace: "added" | "updated" | "removed", key: null): void;
+	notifyChange(identifier: ResourceKey, namespace: NotificationType, key: string | null): void;
+	get schema(): SchemaService;
+	setRecordId(identifier: ResourceKey, id: string): void;
+	hasRecord(identifier: ResourceKey): boolean;
+	disconnectRecord(identifier: ResourceKey): void;
+}
+/**
+* This type exists for internal use only for
+* where intimate contracts still exist either for
+* the Test Suite or for Legacy code.
+*
+* @private
+*/
+export interface PrivateCacheCapabilitiesManager extends CacheCapabilitiesManager {
+	_store: PrivateStore;
+}
+export declare function assertPrivateCapabilities(manager: unknown): asserts manager is PrivateCacheCapabilitiesManager;