diff --git a/docs/docs/guides/developer-guide/cache/cache-service.webp b/docs/docs/guides/developer-guide/cache/cache-service.webp new file mode 100644 index 0000000000..6772ef4061 Binary files /dev/null and b/docs/docs/guides/developer-guide/cache/cache-service.webp differ diff --git a/docs/docs/reference/typescript-api/cache/cache-config.md b/docs/docs/reference/typescript-api/cache/cache-config.md new file mode 100644 index 0000000000..108ecb1dc5 --- /dev/null +++ b/docs/docs/reference/typescript-api/cache/cache-config.md @@ -0,0 +1,48 @@ +--- +title: "CacheConfig" +isDefaultIndex: false +generated: true +--- + +import MemberInfo from '@site/src/components/MemberInfo'; +import GenerationInfo from '@site/src/components/GenerationInfo'; +import MemberDescription from '@site/src/components/MemberDescription'; + + +## CacheConfig + + + +Configuration for a new Cache instance. + +```ts title="Signature" +interface CacheConfig { + getKey: (id: string | number) => string; + options?: SetCacheKeyOptions; +} +``` + +
+ +### getKey + + + +A function which generates a cache key from the given id. +This key will be used to store the value in the cache. + +By convention, the key should be namespaced to avoid conflicts. + +*Example* + +```ts +getKey: id => `MyStrategy:getProductVariantIds:${id}`, +``` +### options + + + +Options available when setting the value in the cache. + + +
diff --git a/docs/docs/reference/typescript-api/cache/cache-service.md b/docs/docs/reference/typescript-api/cache/cache-service.md new file mode 100644 index 0000000000..3935c3604f --- /dev/null +++ b/docs/docs/reference/typescript-api/cache/cache-service.md @@ -0,0 +1,80 @@ +--- +title: "CacheService" +isDefaultIndex: false +generated: true +--- + +import MemberInfo from '@site/src/components/MemberInfo'; +import GenerationInfo from '@site/src/components/GenerationInfo'; +import MemberDescription from '@site/src/components/MemberDescription'; + + +## CacheService + + + +The CacheService is used to cache data in order to optimize performance. + +Internally it makes use of the configured CacheStrategy to persist +the cache into a key-value store. + +```ts title="Signature" +class CacheService { + protected cacheStrategy: CacheStrategy; + constructor(configService: ConfigService) + createCache(config: CacheConfig) => Cache; + get(key: string) => Promise; + set(key: string, value: T, options?: SetCacheKeyOptions) => Promise; + delete(key: string) => Promise; + invalidateTags(tags: string[]) => Promise; +} +``` + +
+ +### cacheStrategy + +CacheStrategy`} /> + + +### constructor + + CacheService`} /> + + +### createCache + +CacheConfig) => Cache`} /> + +Creates a new Cache instance with the given configuration. + +The `Cache` instance provides a convenience wrapper around the `CacheService` +methods. +### get + + Promise<T | undefined>`} /> + +Gets an item from the cache, or returns undefined if the key is not found, or the +item has expired. +### set + + Promise<void>`} /> + +Sets a key-value pair in the cache. The value must be serializable, so cannot contain +things like functions, circular data structures, class instances etc. + +Optionally a "time to live" (ttl) can be specified, which means that the key will +be considered stale after that many milliseconds. +### delete + + Promise<void>`} /> + +Deletes an item from the cache. +### invalidateTags + + Promise<void>`} /> + +Deletes all items from the cache which contain at least one matching tag. + + +
diff --git a/docs/docs/reference/typescript-api/cache/cache-strategy.md b/docs/docs/reference/typescript-api/cache/cache-strategy.md new file mode 100644 index 0000000000..c7edd73fbb --- /dev/null +++ b/docs/docs/reference/typescript-api/cache/cache-strategy.md @@ -0,0 +1,62 @@ +--- +title: "CacheStrategy" +isDefaultIndex: false +generated: true +--- + +import MemberInfo from '@site/src/components/MemberInfo'; +import GenerationInfo from '@site/src/components/GenerationInfo'; +import MemberDescription from '@site/src/components/MemberDescription'; + + +## CacheStrategy + + + +The CacheStrategy defines how the underlying shared cache mechanism is implemented. + +It is used by the CacheService to take care of storage and retrieval of items +from the cache. + +```ts title="Signature" +interface CacheStrategy extends InjectableStrategy { + get>(key: string): Promise; + set>(key: string, value: T, options?: SetCacheKeyOptions): Promise; + delete(key: string): Promise; + invalidateTags(tags: string[]): Promise; +} +``` +* Extends: InjectableStrategy + + + +
+ +### get + + Promise<T | undefined>`} /> + +Gets an item from the cache, or returns undefined if the key is not found, or the +item has expired. +### set + + Promise<void>`} /> + +Sets a key-value pair in the cache. The value must be serializable, so cannot contain +things like functions, circular data structures, class instances etc. + +Optionally a "time to live" (ttl) can be specified, which means that the key will +be considered stale after that many milliseconds. +### delete + + Promise<void>`} /> + +Deletes an item from the cache. +### invalidateTags + + Promise<void>`} /> + +Deletes all items from the cache which contain at least one matching tag. + + +
diff --git a/docs/docs/reference/typescript-api/cache/request-context-cache-service.md b/docs/docs/reference/typescript-api/cache/request-context-cache-service.md new file mode 100644 index 0000000000..5104f9bec5 --- /dev/null +++ b/docs/docs/reference/typescript-api/cache/request-context-cache-service.md @@ -0,0 +1,58 @@ +--- +title: "RequestContextCacheService" +isDefaultIndex: false +generated: true +--- + +import MemberInfo from '@site/src/components/MemberInfo'; +import GenerationInfo from '@site/src/components/GenerationInfo'; +import MemberDescription from '@site/src/components/MemberDescription'; + + +## RequestContextCacheService + + + +This service is used to cache arbitrary data relative to an ongoing request. +It does this by using a WeakMap bound to the current RequestContext, so the cached +data is available for the duration of the request. Once the request completes, the +cached data will be automatically garbage-collected. + +This is useful for caching data which is expensive to compute and which is needed +multiple times during the handling of a single request. + +```ts title="Signature" +class RequestContextCacheService { + set(ctx: RequestContext, key: any, val: T) => void; + get(ctx: RequestContext, key: any) => T | undefined; + get(ctx: RequestContext, key: any, getDefault?: () => T) => T; + get(ctx: RequestContext, key: any, getDefault?: () => T) => T | Promise | undefined; +} +``` + +
+ +### set + +RequestContext, key: any, val: T) => void`} /> + +Set a value in the RequestContext cache. +### get + +RequestContext, key: any) => T | undefined`} /> + +Get a value from the RequestContext cache. If the value is not found, the `getDefault` +function will be called to get the value, which will then be cached and returned. +### get + +RequestContext, key: any, getDefault?: () => T) => T`} /> + + +### get + +RequestContext, key: any, getDefault?: () => T) => T | Promise<T> | undefined`} /> + + + + +