From f297dc492f80bd344f9e92e279ae4be0ed089031 Mon Sep 17 00:00:00 2001 From: Michael Bromley Date: Wed, 18 Dec 2024 09:35:22 +0100 Subject: [PATCH] docs: Improve docs related to caching --- .../guides/developer-guide/cache/index.mdx | 54 +++++++++++++++++++ .../typescript-api/cache/cache-config.md | 2 +- .../typescript-api/cache/cache-service.md | 2 +- .../typescript-api/cache/cache-strategy.md | 49 ++++++++++++++++- .../cache/default-cache-plugin.md | 39 ++++++++++++-- .../cache/redis-cache-plugin.md | 44 +++++++++++++-- .../cache/redis-cache-strategy.md | 4 +- .../cache/sql-cache-strategy.md | 7 +-- .../entities/shipping-method.md | 8 ++- .../check-shipping-eligibility-checker-fn.md | 2 +- .../shipping/shipping-eligibility-checker.md | 6 +++ .../shipping/should-run-check-fn.md | 2 +- .../core/src/config/system/cache-strategy.ts | 17 ++++++ .../default-cache-plugin.ts | 14 +++++ .../sql-cache-strategy.ts | 4 +- .../redis-cache-plugin/redis-cache-plugin.ts | 2 + .../src/plugin/redis-cache-plugin/types.ts | 21 +++++++- 17 files changed, 256 insertions(+), 21 deletions(-) diff --git a/docs/docs/guides/developer-guide/cache/index.mdx b/docs/docs/guides/developer-guide/cache/index.mdx index b15df9ae5f..31c331d2cc 100644 --- a/docs/docs/guides/developer-guide/cache/index.mdx +++ b/docs/docs/guides/developer-guide/cache/index.mdx @@ -8,6 +8,60 @@ operations and reusing them when the same operation is requested again. Vendure uses caching in a number of places to improve performance, and the same caching mechanism is available for use in custom plugins. +## Setting up the cache + +In order to take advantage of Vendure distributed caching, you need to enable a cache plugin. + +:::note +If no cache plugin is specified, Vendure uses an in-memory cache which is not shared between instances. +This is suitable for development, but not recommended for production use. +::: + +### DefaultCachePlugin + +The [DefaultCachePlugin](/reference/typescript-api/cache/default-cache-plugin) uses the database to store the cache data. +This is a simple and effective cache strategy which has the advantage of not requiring any additional +infrastructure. + +```ts title="vendure-config.ts" +import { DefaultCachePlugin, VendureConfig } from '@vendure/core'; + +export const config: VendureConfig = { + // ... + plugins: [ + DefaultCachePlugin.init({ + // optional maximum number of items to + // store in the cache. Defaults to 10,000 + cacheSize: 20_000, + }), + ], +}; +``` + +After enabling the `DefaultCachePlugin`, you will need to [generate a migration](/guides/developer-guide/migrations/) to add the necessary +tables to the database. + +### RedisCachePlugin + +Vendure also provides a [RedisCachePlugin](/reference/typescript-api/cache/redis-cache-plugin) which uses a Redis +server to store the cache data and can have better performance characteristics. + +```ts title="vendure-config.ts" +import { RedisCachePlugin, VendureConfig } from '@vendure/core'; + +export const config: VendureConfig = { + // ... + plugins: [ + RedisCachePlugin.init({ + redisOptions: { + host: 'localhost', + port: 6379, + }, + }), + ], +}; +``` + ## CacheService The [`CacheService`](/reference/typescript-api/cache/cache-service) is the general-purpose API for interacting with the cache. diff --git a/docs/docs/reference/typescript-api/cache/cache-config.md b/docs/docs/reference/typescript-api/cache/cache-config.md index 108ecb1dc5..7ad63f32b4 100644 --- a/docs/docs/reference/typescript-api/cache/cache-config.md +++ b/docs/docs/reference/typescript-api/cache/cache-config.md @@ -40,7 +40,7 @@ getKey: id => `MyStrategy:getProductVariantIds:${id}`, ``` ### options - +SetCacheKeyOptions`} /> 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 index 3935c3604f..d92ad02d92 100644 --- a/docs/docs/reference/typescript-api/cache/cache-service.md +++ b/docs/docs/reference/typescript-api/cache/cache-service.md @@ -58,7 +58,7 @@ Gets an item from the cache, or returns undefined if the key is not found, or th item has expired. ### set - Promise<void>`} /> +SetCacheKeyOptions) => 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. diff --git a/docs/docs/reference/typescript-api/cache/cache-strategy.md b/docs/docs/reference/typescript-api/cache/cache-strategy.md index c7edd73fbb..e551543f63 100644 --- a/docs/docs/reference/typescript-api/cache/cache-strategy.md +++ b/docs/docs/reference/typescript-api/cache/cache-strategy.md @@ -11,13 +11,24 @@ 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. +If you are using the `DefaultCachePlugin` or the `RedisCachePlugin`, you will not need to +manually specify a CacheStrategy, as these plugins will automatically configure the +appropriate strategy. + +:::info + +This is configured via the `systemOptions.cacheStrategy` property of +your VendureConfig. + +::: + ```ts title="Signature" interface CacheStrategy extends InjectableStrategy { get>(key: string): Promise; @@ -40,7 +51,7 @@ Gets an item from the cache, or returns undefined if the key is not found, or th item has expired. ### set - Promise<void>`} /> +SetCacheKeyOptions) => 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. @@ -59,4 +70,38 @@ Deletes an item from the cache. Deletes all items from the cache which contain at least one matching tag. + + + +## SetCacheKeyOptions + + + +Options available when setting the value in the cache. + +```ts title="Signature" +interface SetCacheKeyOptions { + ttl?: number; + tags?: string[]; +} +``` + +
+ +### ttl + + + +The time-to-live for the cache key in milliseconds. This means +that after this time period, the key will be considered stale +and will no longer be returned from the cache. Omitting +this is equivalent to having an infinite ttl. +### tags + + + +An array of tags which can be used to group cache keys together. +This can be useful for bulk deletion of related keys. + +
diff --git a/docs/docs/reference/typescript-api/cache/default-cache-plugin.md b/docs/docs/reference/typescript-api/cache/default-cache-plugin.md index 6547696649..537f417769 100644 --- a/docs/docs/reference/typescript-api/cache/default-cache-plugin.md +++ b/docs/docs/reference/typescript-api/cache/default-cache-plugin.md @@ -11,10 +11,11 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## DefaultCachePlugin - + This plugin provides a simple SQL-based cache strategy SqlCacheStrategy which stores cached items in the database. + It is suitable for production use (including multi-instance setups). For increased performance you can also consider using the RedisCachePlugin. @@ -31,14 +32,46 @@ class DefaultCachePlugin { ### options - +DefaultCachePluginInitOptions`} /> ### init - `} /> +DefaultCachePluginInitOptions) => `} /> + + + + + + + +## DefaultCachePluginInitOptions + + + +Configuration options for the DefaultCachePlugin. + +```ts title="Signature" +interface DefaultCachePluginInitOptions { + cacheSize?: number; + cacheTtlProvider?: CacheTtlProvider; +} +``` + +
+ +### cacheSize + + + +The maximum number of items to store in the cache. Once the cache reaches this size, +the least-recently-used items will be evicted to make room for new items. +### cacheTtlProvider + +Optionally provide a custom CacheTtlProvider to control the TTL of cache items. +This is useful for testing.
diff --git a/docs/docs/reference/typescript-api/cache/redis-cache-plugin.md b/docs/docs/reference/typescript-api/cache/redis-cache-plugin.md index 91656889dc..7c927440dc 100644 --- a/docs/docs/reference/typescript-api/cache/redis-cache-plugin.md +++ b/docs/docs/reference/typescript-api/cache/redis-cache-plugin.md @@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## RedisCachePlugin - + This plugin provides a Redis-based RedisCacheStrategy which stores cached items in a Redis instance. This is a high-performance cache strategy which is suitable for production use, and is a drop-in @@ -32,14 +32,52 @@ class RedisCachePlugin { ### options - +RedisCachePluginInitOptions`} /> ### init - `} /> +RedisCachePluginInitOptions) => `} /> + + + +## RedisCachePluginInitOptions + + + +Configuration options for the RedisCachePlugin. + +```ts title="Signature" +interface RedisCachePluginInitOptions { + maxItemSizeInBytes?: number; + namespace?: string; + redisOptions?: import('ioredis').RedisOptions; +} +``` + +
+ +### maxItemSizeInBytes + + + +The maximum size of a single cache item in bytes. If a cache item exceeds this size, it will not be stored +and an error will be logged. +### namespace + + + +The namespace to use for all keys stored in Redis. This can be useful if you are sharing a Redis instance +between multiple applications. +### redisOptions + + + +Options to pass to the `ioredis` Redis client. + +
diff --git a/docs/docs/reference/typescript-api/cache/redis-cache-strategy.md b/docs/docs/reference/typescript-api/cache/redis-cache-strategy.md index 67cee035c1..237e133a46 100644 --- a/docs/docs/reference/typescript-api/cache/redis-cache-strategy.md +++ b/docs/docs/reference/typescript-api/cache/redis-cache-strategy.md @@ -35,7 +35,7 @@ class RedisCacheStrategy implements CacheStrategy { ### constructor - RedisCacheStrategy`} /> +RedisCachePluginInitOptions) => RedisCacheStrategy`} /> ### init @@ -55,7 +55,7 @@ class RedisCacheStrategy implements CacheStrategy { ### set - Promise<void>`} /> +SetCacheKeyOptions) => Promise<void>`} /> ### delete diff --git a/docs/docs/reference/typescript-api/cache/sql-cache-strategy.md b/docs/docs/reference/typescript-api/cache/sql-cache-strategy.md index d404f7d80f..fc615035ec 100644 --- a/docs/docs/reference/typescript-api/cache/sql-cache-strategy.md +++ b/docs/docs/reference/typescript-api/cache/sql-cache-strategy.md @@ -11,9 +11,10 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## SqlCacheStrategy - - + +A CacheStrategy that stores cached items in the database. This +is the strategy used by the DefaultCachePlugin. ```ts title="Signature" class SqlCacheStrategy implements CacheStrategy { @@ -72,7 +73,7 @@ class SqlCacheStrategy implements CacheStrategy { ### set - `} /> +SetCacheKeyOptions) => `} /> ### delete diff --git a/docs/docs/reference/typescript-api/entities/shipping-method.md b/docs/docs/reference/typescript-api/entities/shipping-method.md index bb9c5b7fd4..aa9790e6e3 100644 --- a/docs/docs/reference/typescript-api/entities/shipping-method.md +++ b/docs/docs/reference/typescript-api/entities/shipping-method.md @@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## ShippingMethod - + A ShippingMethod is used to apply a shipping price to an Order. It is composed of a ShippingEligibilityChecker and a ShippingCalculator. For a given Order, @@ -40,6 +40,7 @@ class ShippingMethod extends VendureEntity implements ChannelAware, SoftDeletabl customFields: CustomShippingMethodFields; apply(ctx: RequestContext, order: Order) => Promise; test(ctx: RequestContext, order: Order) => Promise; + toJSON() => any; } ``` * Extends: VendureEntity @@ -116,6 +117,11 @@ class ShippingMethod extends VendureEntity implements ChannelAware, SoftDeletabl RequestContext, order: Order) => Promise<boolean>`} /> +### toJSON + + any`} /> + + diff --git a/docs/docs/reference/typescript-api/shipping/check-shipping-eligibility-checker-fn.md b/docs/docs/reference/typescript-api/shipping/check-shipping-eligibility-checker-fn.md index be2dfd238e..7037507efe 100644 --- a/docs/docs/reference/typescript-api/shipping/check-shipping-eligibility-checker-fn.md +++ b/docs/docs/reference/typescript-api/shipping/check-shipping-eligibility-checker-fn.md @@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## CheckShippingEligibilityCheckerFn - + A function which implements logic to determine whether a given Order is eligible for a particular shipping method. Once a ShippingMethod has been assigned to an Order, this diff --git a/docs/docs/reference/typescript-api/shipping/shipping-eligibility-checker.md b/docs/docs/reference/typescript-api/shipping/shipping-eligibility-checker.md index e8ae9f3db5..fd1ac46cda 100644 --- a/docs/docs/reference/typescript-api/shipping/shipping-eligibility-checker.md +++ b/docs/docs/reference/typescript-api/shipping/shipping-eligibility-checker.md @@ -35,6 +35,7 @@ const minOrderTotalEligibilityChecker = new ShippingEligibilityChecker({ class ShippingEligibilityChecker extends ConfigurableOperationDef { constructor(config: ShippingEligibilityCheckerConfig) init(injector: Injector) => ; + toJSON() => ; } ``` * Extends: ConfigurableOperationDef<T> @@ -53,6 +54,11 @@ class ShippingEligibilityChecker extends Conf Injector) => `} /> +### toJSON + + `} /> + + diff --git a/docs/docs/reference/typescript-api/shipping/should-run-check-fn.md b/docs/docs/reference/typescript-api/shipping/should-run-check-fn.md index 25128405e5..4fe208b577 100644 --- a/docs/docs/reference/typescript-api/shipping/should-run-check-fn.md +++ b/docs/docs/reference/typescript-api/shipping/should-run-check-fn.md @@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## ShouldRunCheckFn - + An optional method which is used to decide whether to run the `check()` function. Returns a JSON-compatible object which is cached and compared between calls. diff --git a/packages/core/src/config/system/cache-strategy.ts b/packages/core/src/config/system/cache-strategy.ts index d680e5f935..8b0e65a6c1 100644 --- a/packages/core/src/config/system/cache-strategy.ts +++ b/packages/core/src/config/system/cache-strategy.ts @@ -5,6 +5,10 @@ import { InjectableStrategy } from '../../common/types/injectable-strategy'; /** * @description * Options available when setting the value in the cache. + * + * @since 3.1.0 + * @docsCategory cache + * @docsPage CacheStrategy */ export interface SetCacheKeyOptions { /** @@ -30,8 +34,21 @@ export interface SetCacheKeyOptions { * It is used by the {@link CacheService} to take care of storage and retrieval of items * from the cache. * + * If you are using the `DefaultCachePlugin` or the `RedisCachePlugin`, you will not need to + * manually specify a CacheStrategy, as these plugins will automatically configure the + * appropriate strategy. + * + * :::info + * + * This is configured via the `systemOptions.cacheStrategy` property of + * your VendureConfig. + * + * ::: + * * @since 3.1.0 * @docsCategory cache + * @docsPage CacheStrategy + * @docsWeight 0 */ export interface CacheStrategy extends InjectableStrategy { /** diff --git a/packages/core/src/plugin/default-cache-plugin/default-cache-plugin.ts b/packages/core/src/plugin/default-cache-plugin/default-cache-plugin.ts index e02731bb13..2356635b46 100644 --- a/packages/core/src/plugin/default-cache-plugin/default-cache-plugin.ts +++ b/packages/core/src/plugin/default-cache-plugin/default-cache-plugin.ts @@ -7,14 +7,25 @@ import { CacheTag } from './cache-tag.entity'; import { PLUGIN_INIT_OPTIONS } from './constants'; import { SqlCacheStrategy } from './sql-cache-strategy'; +/** + * @description + * Configuration options for the {@link DefaultCachePlugin}. + * + * @docsCategory cache + * @docsPage DefaultCachePlugin + * @since 3.1.0 + */ export interface DefaultCachePluginInitOptions { /** * @description * The maximum number of items to store in the cache. Once the cache reaches this size, * the least-recently-used items will be evicted to make room for new items. + * + * @default 10_000 */ cacheSize?: number; /** + * @description * Optionally provide a custom CacheTtlProvider to control the TTL of cache items. * This is useful for testing. */ @@ -25,10 +36,13 @@ export interface DefaultCachePluginInitOptions { * @description * This plugin provides a simple SQL-based cache strategy {@link SqlCacheStrategy} which stores cached * items in the database. + * * It is suitable for production use (including multi-instance setups). For increased performance * you can also consider using the {@link RedisCachePlugin}. * * @docsCategory cache + * @docsPage DefaultCachePlugin + * @docsWeight 0 * @since 3.1.0 */ @VendurePlugin({ diff --git a/packages/core/src/plugin/default-cache-plugin/sql-cache-strategy.ts b/packages/core/src/plugin/default-cache-plugin/sql-cache-strategy.ts index 09bee0df4e..04d13c78e9 100644 --- a/packages/core/src/plugin/default-cache-plugin/sql-cache-strategy.ts +++ b/packages/core/src/plugin/default-cache-plugin/sql-cache-strategy.ts @@ -10,7 +10,9 @@ import { CacheItem } from './cache-item.entity'; import { CacheTag } from './cache-tag.entity'; /** - * A {@link CacheStrategy} that stores cached items in the database. + * @description + * A {@link CacheStrategy} that stores cached items in the database. This + * is the strategy used by the {@link DefaultCachePlugin}. * * @since 3.1.0 * @docsCategory cache diff --git a/packages/core/src/plugin/redis-cache-plugin/redis-cache-plugin.ts b/packages/core/src/plugin/redis-cache-plugin/redis-cache-plugin.ts index 787b61fae3..4029488e84 100644 --- a/packages/core/src/plugin/redis-cache-plugin/redis-cache-plugin.ts +++ b/packages/core/src/plugin/redis-cache-plugin/redis-cache-plugin.ts @@ -12,6 +12,8 @@ import { RedisCachePluginInitOptions } from './types'; * replacement for the {@link DefaultCachePlugin}. * * @docsCategory cache + * @docsPage RedisCachePlugin + * @docsWeight 0 * @since 3.1.0 */ @VendurePlugin({ diff --git a/packages/core/src/plugin/redis-cache-plugin/types.ts b/packages/core/src/plugin/redis-cache-plugin/types.ts index 8ef39fbdb4..f5cdaad2a4 100644 --- a/packages/core/src/plugin/redis-cache-plugin/types.ts +++ b/packages/core/src/plugin/redis-cache-plugin/types.ts @@ -1,5 +1,11 @@ -import { CacheTtlProvider } from '../../cache/cache-ttl-provider'; - +/** + * @description + * Configuration options for the {@link RedisCachePlugin}. + * + * @docsCategory cache + * @docsPage RedisCachePlugin + * @since 3.1.0 + */ export interface RedisCachePluginInitOptions { /** * @description @@ -9,6 +15,17 @@ export interface RedisCachePluginInitOptions { * @default 128kb */ maxItemSizeInBytes?: number; + /** + * @description + * The namespace to use for all keys stored in Redis. This can be useful if you are sharing a Redis instance + * between multiple applications. + * + * @default 'vendure-cache' + */ namespace?: string; + /** + * @description + * Options to pass to the `ioredis` Redis client. + */ redisOptions?: import('ioredis').RedisOptions; }