next
Version:
The React Framework
94 lines (92 loc) • 4.48 kB
TypeScript
/**
* A specialized data type for storing multi-key cache entries.
*
* The basic structure is a map whose keys are tuples, called the keypath.
* When querying the cache, keypaths are compared per-element.
*
* Example:
* set(map, ['https://localhost', 'foo/bar/baz'], 'yay');
* get(map, ['https://localhost', 'foo/bar/baz']) -> 'yay'
*
* The parts of the keypath represent the different inputs that contribute
* to the entry value. To illustrate, if you were to use this data type to store
* HTTP responses, the keypath would include the URL and everything listed by
* the Vary header.
*
* The order of elements in a keypath must be consistent between lookups to
* be considered the same, but besides that, the order of the keys is not
* semantically meaningful.
*
* Keypaths may include a special kind of key called Fallback. When an entry is
* stored with Fallback as part of its keypath, it means that the entry does not
* vary by that key. When querying the cache, if an exact match is not found for
* a keypath, the cache will check for a Fallback match instead. Each element of
* the keypath may have a Fallback, so retrieval is an O(n ^ 2) operation, but
* it's expected that keypaths are relatively short.
*
* Example:
* set(cacheMap, ['store', 'product', 1], PRODUCT_PAGE_1);
* set(cacheMap, ['store', 'product', Fallback], GENERIC_PRODUCT_PAGE);
*
* // Exact match
* get(cacheMap, ['store', 'product', 1]) -> PRODUCT_PAGE_1
*
* // Fallback match
* get(cacheMap, ['store', 'product', 2]) -> GENERIC_PRODUCT_PAGE
*
* Because we have the Fallback mechanism, we can impose a constraint that
* regular JS maps do not have: a value cannot be stored at multiple keypaths
* simultaneously. These cases should be expressed with Fallback keys instead.
*
* Additionally, because values only exist at a single keypath at a time, we can
* optimize successive lookups by caching the internal map entry on the value
* itself, using the `ref` field. This is especially useful because it lets us
* skip the O(n ^ 2) lookup that occurs when Fallback entries are present.
*
* How to decide if stuff belongs in here, or in cache.ts?
* -------------------------------------------------------
*
* Anything to do with retrival, lifetimes, or eviction needs to go in this
* module because it affects the fallback algorithm. For example, when
* performing a lookup, if an entry is stale, it needs to be treated as
* semantically equivalent to if the entry was not present at all.
*
* If there's logic that's not related to the fallback algorithm, though, we
* should prefer to put it in cache.ts.
*/
type MapEntryShared<K extends readonly unknown[], V extends MapValue> = {
parent: MapEntry<K, V> | null;
key: any;
map: Map<any, MapEntry<K, V>> | null;
prev: MapEntry<any, any> | null;
next: MapEntry<any, any> | null;
size: number;
};
type EmptyMapEntry<K extends readonly unknown[], V extends MapValue> = MapEntryShared<K, V> & {
value: null;
};
type FullMapEntry<K extends readonly unknown[], V extends MapValue> = MapEntryShared<K, V> & {
value: V;
};
export type MapEntry<K extends readonly unknown[], V extends MapValue> = EmptyMapEntry<K, V> | FullMapEntry<K, V>;
export type CacheMap<K extends readonly unknown[], V extends MapValue> = MapEntry<K, V>;
export interface MapValue {
ref: MapEntry<any, any> | null;
size: number;
staleAt: number;
version: number;
}
type KeyWithFallback<K extends readonly unknown[]> = {
[I in keyof K]: K[I] | FallbackType;
};
export type FallbackType = {
__brand: 'Fallback';
};
export declare const Fallback: FallbackType;
export declare function createCacheMap<Keypath extends Array<any>, V extends MapValue>(): CacheMap<Keypath, V>;
export declare function getFromCacheMap<K extends readonly unknown[], V extends MapValue>(now: number, currentCacheVersion: number, rootEntry: CacheMap<K, V>, keys: KeyWithFallback<K>, isRevalidation: boolean): V | null;
export declare function isValueExpired<V extends MapValue>(now: number, currentCacheVersion: number, value: V): boolean;
export declare function setInCacheMap<K extends readonly unknown[], V extends MapValue>(cacheMap: CacheMap<K, V>, keys: K, value: V, isRevalidation: boolean): void;
export declare function deleteFromCacheMap<V extends MapValue>(value: V): void;
export declare function setSizeInCacheMap<V extends MapValue>(value: V, size: number): void;
export {};