docs: Improve docs related to caching

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.

docs/docs/reference/typescript-api/cache/cache-config.md

@@ -40,7 +40,7 @@ getKey: id => `MyStrategy:getProductVariantIds:${id}`,
 ```
 ### options
 
-<MemberInfo kind="property" type={`SetCacheKeyOptions`}   />
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/cache/cache-strategy#setcachekeyoptions'>SetCacheKeyOptions</a>`}   />
 
 Options available when setting the value in the cache.
 

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
 
-<MemberInfo kind="method" type={`(key: string, value: T, options?: SetCacheKeyOptions) => Promise&#60;void&#62;`}   />
+<MemberInfo kind="method" type={`(key: string, value: T, options?: <a href='/reference/typescript-api/cache/cache-strategy#setcachekeyoptions'>SetCacheKeyOptions</a>) => Promise&#60;void&#62;`}   />
 
 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.

docs/docs/reference/typescript-api/cache/cache-strategy.md

@@ -11,13 +11,24 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## CacheStrategy
 
-<GenerationInfo sourceFile="packages/core/src/config/system/cache-strategy.ts" sourceLine="36" packageName="@vendure/core" since="3.1.0" />
+<GenerationInfo sourceFile="packages/core/src/config/system/cache-strategy.ts" sourceLine="53" packageName="@vendure/core" since="3.1.0" />
 
 The CacheStrategy defines how the underlying shared cache mechanism is implemented.
 
 It is used by the <a href='/reference/typescript-api/cache/cache-service#cacheservice'>CacheService</a> 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<T extends JsonCompatible<T>>(key: string): Promise<T | undefined>;
@@ -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
 
-<MemberInfo kind="method" type={`(key: string, value: T, options?: SetCacheKeyOptions) => Promise&#60;void&#62;`}   />
+<MemberInfo kind="method" type={`(key: string, value: T, options?: <a href='/reference/typescript-api/cache/cache-strategy#setcachekeyoptions'>SetCacheKeyOptions</a>) => Promise&#60;void&#62;`}   />
 
 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.
 
 
+</div>
+
+
+## SetCacheKeyOptions
+
+<GenerationInfo sourceFile="packages/core/src/config/system/cache-strategy.ts" sourceLine="13" packageName="@vendure/core" since="3.1.0" />
+
+Options available when setting the value in the cache.
+
+```ts title="Signature"
+interface SetCacheKeyOptions {
+    ttl?: number;
+    tags?: string[];
+}
+```
+
+<div className="members-wrapper">
+
+### ttl
+
+<MemberInfo kind="property" type={`number`}   />
+
+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
+
+<MemberInfo kind="property" type={`string[]`}   />
+
+An array of tags which can be used to group cache keys together.
+This can be useful for bulk deletion of related keys.
+
+
 </div>

docs/docs/reference/typescript-api/cache/default-cache-plugin.md

@@ -11,10 +11,11 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## DefaultCachePlugin
 
-<GenerationInfo sourceFile="packages/core/src/plugin/default-cache-plugin/default-cache-plugin.ts" sourceLine="34" packageName="@vendure/core" since="3.1.0" />
+<GenerationInfo sourceFile="packages/core/src/plugin/default-cache-plugin/default-cache-plugin.ts" sourceLine="48" packageName="@vendure/core" since="3.1.0" />
 
 This plugin provides a simple SQL-based cache strategy <a href='/reference/typescript-api/cache/sql-cache-strategy#sqlcachestrategy'>SqlCacheStrategy</a> 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 <a href='/reference/typescript-api/cache/redis-cache-plugin#rediscacheplugin'>RedisCachePlugin</a>.
 
@@ -31,14 +32,46 @@ class DefaultCachePlugin {
 
 ### options
 
-<MemberInfo kind="property" type={`DefaultCachePluginInitOptions`}   />
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/cache/default-cache-plugin#defaultcacheplugininitoptions'>DefaultCachePluginInitOptions</a>`}   />
 
 
 ### init
 
-<MemberInfo kind="method" type={`(options: DefaultCachePluginInitOptions) => `}   />
+<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/cache/default-cache-plugin#defaultcacheplugininitoptions'>DefaultCachePluginInitOptions</a>) => `}   />
+
+
+
+
+</div>
+
+
+## DefaultCachePluginInitOptions
+
+<GenerationInfo sourceFile="packages/core/src/plugin/default-cache-plugin/default-cache-plugin.ts" sourceLine="18" packageName="@vendure/core" since="3.1.0" />
+
+Configuration options for the <a href='/reference/typescript-api/cache/default-cache-plugin#defaultcacheplugin'>DefaultCachePlugin</a>.
+
+```ts title="Signature"
+interface DefaultCachePluginInitOptions {
+    cacheSize?: number;
+    cacheTtlProvider?: CacheTtlProvider;
+}
+```
+
+<div className="members-wrapper">
+
+### cacheSize
+
+<MemberInfo kind="property" type={`number`} default={`10_000`}   />
+
+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
 
+<MemberInfo kind="property" type={`CacheTtlProvider`}   />
 
+Optionally provide a custom CacheTtlProvider to control the TTL of cache items.
+This is useful for testing.
 
 
 </div>

docs/docs/reference/typescript-api/cache/redis-cache-plugin.md

@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## RedisCachePlugin
 
-<GenerationInfo sourceFile="packages/core/src/plugin/redis-cache-plugin/redis-cache-plugin.ts" sourceLine="17" packageName="@vendure/core" since="3.1.0" />
+<GenerationInfo sourceFile="packages/core/src/plugin/redis-cache-plugin/redis-cache-plugin.ts" sourceLine="19" packageName="@vendure/core" since="3.1.0" />
 
 This plugin provides a Redis-based <a href='/reference/typescript-api/cache/redis-cache-strategy#rediscachestrategy'>RedisCacheStrategy</a> 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
 
-<MemberInfo kind="property" type={`RedisCachePluginInitOptions`}   />
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/cache/redis-cache-plugin#rediscacheplugininitoptions'>RedisCachePluginInitOptions</a>`}   />
 
 
 ### init
 
-<MemberInfo kind="method" type={`(options: RedisCachePluginInitOptions) => `}   />
+<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/cache/redis-cache-plugin#rediscacheplugininitoptions'>RedisCachePluginInitOptions</a>) => `}   />
 
 
 
 
+</div>
+
+
+## RedisCachePluginInitOptions
+
+<GenerationInfo sourceFile="packages/core/src/plugin/redis-cache-plugin/types.ts" sourceLine="9" packageName="@vendure/core" since="3.1.0" />
+
+Configuration options for the <a href='/reference/typescript-api/cache/redis-cache-plugin#rediscacheplugin'>RedisCachePlugin</a>.
+
+```ts title="Signature"
+interface RedisCachePluginInitOptions {
+    maxItemSizeInBytes?: number;
+    namespace?: string;
+    redisOptions?: import('ioredis').RedisOptions;
+}
+```
+
+<div className="members-wrapper">
+
+### maxItemSizeInBytes
+
+<MemberInfo kind="property" type={`number`} default={`128kb`}   />
+
+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
+
+<MemberInfo kind="property" type={`string`} default={`'vendure-cache'`}   />
+
+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
+
+<MemberInfo kind="property" type={`import('ioredis').RedisOptions`}   />
+
+Options to pass to the `ioredis` Redis client.
+
+
 </div>

docs/docs/reference/typescript-api/cache/redis-cache-strategy.md

@@ -35,7 +35,7 @@ class RedisCacheStrategy implements CacheStrategy {
 
 ### constructor
 
-<MemberInfo kind="method" type={`(options: RedisCachePluginInitOptions) => RedisCacheStrategy`}   />
+<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/cache/redis-cache-plugin#rediscacheplugininitoptions'>RedisCachePluginInitOptions</a>) => RedisCacheStrategy`}   />
 
 
 ### init
@@ -55,7 +55,7 @@ class RedisCacheStrategy implements CacheStrategy {
 
 ### set
 
-<MemberInfo kind="method" type={`(key: string, value: T, options?: SetCacheKeyOptions) => Promise&#60;void&#62;`}   />
+<MemberInfo kind="method" type={`(key: string, value: T, options?: <a href='/reference/typescript-api/cache/cache-strategy#setcachekeyoptions'>SetCacheKeyOptions</a>) => Promise&#60;void&#62;`}   />
 
 
 ### delete

docs/docs/reference/typescript-api/cache/sql-cache-strategy.md

@@ -11,9 +11,10 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## SqlCacheStrategy
 
-<GenerationInfo sourceFile="packages/core/src/plugin/default-cache-plugin/sql-cache-strategy.ts" sourceLine="18" packageName="@vendure/core" since="3.1.0" />
-
+<GenerationInfo sourceFile="packages/core/src/plugin/default-cache-plugin/sql-cache-strategy.ts" sourceLine="20" packageName="@vendure/core" since="3.1.0" />
 
+A <a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a> that stores cached items in the database. This
+is the strategy used by the <a href='/reference/typescript-api/cache/default-cache-plugin#defaultcacheplugin'>DefaultCachePlugin</a>.
 
 ```ts title="Signature"
 class SqlCacheStrategy implements CacheStrategy {
@@ -72,7 +73,7 @@ class SqlCacheStrategy implements CacheStrategy {
 
 ### set
 
-<MemberInfo kind="method" type={`(key: string, value: T, options?: SetCacheKeyOptions) => `}   />
+<MemberInfo kind="method" type={`(key: string, value: T, options?: <a href='/reference/typescript-api/cache/cache-strategy#setcachekeyoptions'>SetCacheKeyOptions</a>) => `}   />
 
 
 ### delete

docs/docs/reference/typescript-api/entities/shipping-method.md

@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## ShippingMethod
 
-<GenerationInfo sourceFile="packages/core/src/entity/shipping-method/shipping-method.entity.ts" sourceLine="33" packageName="@vendure/core" />
+<GenerationInfo sourceFile="packages/core/src/entity/shipping-method/shipping-method.entity.ts" sourceLine="34" packageName="@vendure/core" />
 
 A ShippingMethod is used to apply a shipping price to an <a href='/reference/typescript-api/entities/order#order'>Order</a>. It is composed of a
 <a href='/reference/typescript-api/shipping/shipping-eligibility-checker#shippingeligibilitychecker'>ShippingEligibilityChecker</a> and a <a href='/reference/typescript-api/shipping/shipping-calculator#shippingcalculator'>ShippingCalculator</a>. For a given Order,
@@ -40,6 +40,7 @@ class ShippingMethod extends VendureEntity implements ChannelAware, SoftDeletabl
     customFields: CustomShippingMethodFields;
     apply(ctx: RequestContext, order: Order) => Promise<ShippingCalculationResult | undefined>;
     test(ctx: RequestContext, order: Order) => Promise<boolean>;
+    toJSON() => any;
 }
 ```
 * Extends: <code><a href='/reference/typescript-api/entities/vendure-entity#vendureentity'>VendureEntity</a></code>
@@ -116,6 +117,11 @@ class ShippingMethod extends VendureEntity implements ChannelAware, SoftDeletabl
 <MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, order: <a href='/reference/typescript-api/entities/order#order'>Order</a>) => Promise&#60;boolean&#62;`}   />
 
 
+### toJSON
+
+<MemberInfo kind="method" type={`() => any`}   />
+
+
 
 
 </div>

docs/docs/reference/typescript-api/shipping/check-shipping-eligibility-checker-fn.md

@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## CheckShippingEligibilityCheckerFn
 
-<GenerationInfo sourceFile="packages/core/src/config/shipping-method/shipping-eligibility-checker.ts" sourceLine="130" packageName="@vendure/core" />
+<GenerationInfo sourceFile="packages/core/src/config/shipping-method/shipping-eligibility-checker.ts" sourceLine="138" packageName="@vendure/core" />
 
 A function which implements logic to determine whether a given <a href='/reference/typescript-api/entities/order#order'>Order</a> is eligible for
 a particular shipping method. Once a ShippingMethod has been assigned to an Order, this

docs/docs/reference/typescript-api/shipping/shipping-eligibility-checker.md

@@ -35,6 +35,7 @@ const minOrderTotalEligibilityChecker = new ShippingEligibilityChecker({
 class ShippingEligibilityChecker<T extends ConfigArgs = ConfigArgs> extends ConfigurableOperationDef<T> {
     constructor(config: ShippingEligibilityCheckerConfig<T>)
     init(injector: Injector) => ;
+    toJSON() => ;
 }
 ```
 * Extends: <code><a href='/reference/typescript-api/configurable-operation-def/#configurableoperationdef'>ConfigurableOperationDef</a>&#60;T&#62;</code>
@@ -53,6 +54,11 @@ class ShippingEligibilityChecker<T extends ConfigArgs = ConfigArgs> extends Conf
 <MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />
 
 
+### toJSON
+
+<MemberInfo kind="method" type={`() => `}   />
+
+
 
 
 </div>

docs/docs/reference/typescript-api/shipping/should-run-check-fn.md

@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## ShouldRunCheckFn
 
-<GenerationInfo sourceFile="packages/core/src/config/shipping-method/shipping-eligibility-checker.ts" sourceLine="165" packageName="@vendure/core" />
+<GenerationInfo sourceFile="packages/core/src/config/shipping-method/shipping-eligibility-checker.ts" sourceLine="173" packageName="@vendure/core" />
 
 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.

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 {
     /**

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({

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

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({

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;
 }