@vendure/docs 0.0.0-202601161541

package/docs/reference/typescript-api/cache/index.md

@@ -0,0 +1,79 @@
+---
+title: "Cache"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## Cache
+
+<GenerationInfo sourceFile="packages/core/src/cache/cache.ts" sourceLine="72" packageName="@vendure/core" since="3.1.0" />
+
+A convenience wrapper around the <a href='/reference/typescript-api/cache/cache-service#cacheservice'>CacheService</a> methods which provides a simple
+API for caching and retrieving data.
+
+The advantage of using the `Cache` class rather than directly calling the `CacheService`
+methods is that it allows you to define a consistent way of generating cache keys and
+to set default cache options, and takes care of setting the value in cache if it does not
+already exist.
+
+In most cases, using the `Cache` class will result in simpler and more readable code.
+
+This class is normally created via the <a href='/reference/typescript-api/cache/cache-service#cacheservice'>CacheService</a>.`createCache()` method.
+
+*Example*
+
+```ts
+const cache = cacheService.createCache({
+  getKey: id => `ProductVariantIds:${id}`,
+  options: {
+    ttl: 1000 * 60 * 60,
+    tags: ['products'],
+  },
+});
+
+// This will fetch the value from the cache if it exists, or
+// fetch it from the ProductService if not, and then cache
+// using the key 'ProductVariantIds.${id}'.
+const variantIds = await cache.get(id, async () => {
+  const variants await ProductService.getVariantsByProductId(ctx, id) ;
+  // The cached value must be serializable, so we just return the ids
+  return variants.map(v => v.id);
+});
+```
+
+```ts title="Signature"
+class Cache {
+    constructor(config: CacheConfig, cacheService: CacheService)
+    get(id: string | number, getValueFn: () => T | Promise<T>) => Promise<T>;
+    delete(id: string | number | Array<string | number>) => Promise<void>;
+    invalidateTags(tags: string[]) => Promise<void>;
+}
+```
+
+<div className="members-wrapper">
+
+### constructor
+
+<MemberInfo kind="method" type={`(config: <a href='/reference/typescript-api/cache/cache-config#cacheconfig'>CacheConfig</a>, cacheService: <a href='/reference/typescript-api/cache/cache-service#cacheservice'>CacheService</a>) => Cache`}   />
+
+
+### get
+
+<MemberInfo kind="method" type={`(id: string | number, getValueFn: () =&#62; T | Promise&#60;T&#62;) => Promise&#60;T&#62;`}   />
+
+Retrieves the value from the cache if it exists, otherwise calls the `getValueFn` function
+to get the value, sets it in the cache and returns it.
+### delete
+
+<MemberInfo kind="method" type={`(id: string | number | Array&#60;string | number&#62;) => Promise&#60;void&#62;`}   />
+
+Deletes one or more items from the cache.
+### invalidateTags
+
+<MemberInfo kind="method" type={`(tags: string[]) => Promise&#60;void&#62;`}   />
+
+Invalidates one or more tags in the cache.
+
+
+</div>

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

@@ -0,0 +1,85 @@
+---
+title: "RedisCachePlugin"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## RedisCachePlugin
+
+<GenerationInfo sourceFile="packages/core/src/plugin/redis-cache-plugin/redis-cache-plugin.ts" sourceLine="25" 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
+replacement for the <a href='/reference/typescript-api/cache/default-cache-plugin#defaultcacheplugin'>DefaultCachePlugin</a>.
+
+Note: To use this plugin, you need to manually install the `ioredis` package:
+
+```shell
+npm install ioredis@^5.3.2
+```
+
+```ts title="Signature"
+class RedisCachePlugin {
+    static options: RedisCachePluginInitOptions = {
+        maxItemSizeInBytes: 128_000,
+        redisOptions: {},
+        namespace: 'vendure-cache',
+    };
+    init(options: RedisCachePluginInitOptions) => ;
+}
+```
+
+<div className="members-wrapper">
+
+### options
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/cache/redis-cache-plugin#rediscacheplugininitoptions'>RedisCachePluginInitOptions</a>`}   />
+
+
+### init
+
+<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>

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

@@ -0,0 +1,75 @@
+---
+title: "RedisCacheStrategy"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## RedisCacheStrategy
+
+<GenerationInfo sourceFile="packages/core/src/plugin/redis-cache-plugin/redis-cache-strategy.ts" sourceLine="23" packageName="@vendure/core" since="3.1.0" />
+
+A <a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a> which stores cached items in a Redis instance.
+This is a high-performance cache strategy which is suitable for production use.
+
+Note: To use this strategy, you need to manually install the `ioredis` package:
+
+```shell
+npm install ioredis@^5.3.2
+```
+
+```ts title="Signature"
+class RedisCacheStrategy implements CacheStrategy {
+    constructor(options: RedisCachePluginInitOptions)
+    init() => ;
+    destroy() => ;
+    get(key: string) => Promise<T | undefined>;
+    set(key: string, value: T, options?: SetCacheKeyOptions) => Promise<void>;
+    delete(key: string) => Promise<void>;
+    invalidateTags(tags: string[]) => Promise<void>;
+}
+```
+* Implements: <code><a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a></code>
+
+
+
+<div className="members-wrapper">
+
+### constructor
+
+<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/cache/redis-cache-plugin#rediscacheplugininitoptions'>RedisCachePluginInitOptions</a>) => RedisCacheStrategy`}   />
+
+
+### init
+
+<MemberInfo kind="method" type={`() => `}   />
+
+
+### destroy
+
+<MemberInfo kind="method" type={`() => `}   />
+
+
+### get
+
+<MemberInfo kind="method" type={`(key: string) => Promise&#60;T | undefined&#62;`}   />
+
+
+### set
+
+<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
+
+<MemberInfo kind="method" type={`(key: string) => Promise&#60;void&#62;`}   />
+
+
+### invalidateTags
+
+<MemberInfo kind="method" type={`(tags: string[]) => Promise&#60;void&#62;`}   />
+
+
+
+
+</div>

package/docs/reference/typescript-api/cache/request-context-cache-service.md

@@ -0,0 +1,54 @@
+---
+title: "RequestContextCacheService"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## RequestContextCacheService
+
+<GenerationInfo sourceFile="packages/core/src/cache/request-context-cache.service.ts" sourceLine="15" packageName="@vendure/core" />
+
+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<T> | undefined;
+}
+```
+
+<div className="members-wrapper">
+
+### set
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, key: any, val: T) => void`}   />
+
+Set a value in the RequestContext cache.
+### get
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, 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
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, key: any, getDefault?: () =&#62; T) => T`}   />
+
+
+### get
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, key: any, getDefault?: () =&#62; T) => T | Promise&#60;T&#62; | undefined`}   />
+
+
+
+
+</div>

package/docs/reference/typescript-api/cache/self-refreshing-cache.md

@@ -0,0 +1,152 @@
+---
+title: "SelfRefreshingCache"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## SelfRefreshingCache
+
+<GenerationInfo sourceFile="packages/core/src/common/self-refreshing-cache.ts" sourceLine="10" packageName="@vendure/core" />
+
+A cache which automatically refreshes itself if the value is found to be stale.
+
+```ts title="Signature"
+interface SelfRefreshingCache<V, RefreshArgs extends any[] = []> {
+    value(...refreshArgs: RefreshArgs | [undefined] | []): Promise<V>;
+    memoize<Args extends any[], R>(
+        args: Args,
+        refreshArgs: RefreshArgs,
+        fn: (value: V, ...args: Args) => R,
+    ): Promise<R>;
+    refresh(...args: RefreshArgs): Promise<V>;
+}
+```
+
+<div className="members-wrapper">
+
+### value
+
+<MemberInfo kind="method" type={`(refreshArgs: RefreshArgs | [undefined] | []) => Promise&#60;V&#62;`}   />
+
+The current value of the cache. If the value is stale, the data will be refreshed and then
+the fresh value will be returned.
+### memoize
+
+<MemberInfo kind="method" type={`(args: Args, refreshArgs: RefreshArgs, fn: (value: V, ...args: Args) =&#62; R) => Promise&#60;R&#62;`}   />
+
+Allows a memoized function to be defined. For the given arguments, the `fn` function will
+be invoked only once and its output cached and returned.
+The results cache is cleared along with the rest of the cache according to the configured
+`ttl` value.
+### refresh
+
+<MemberInfo kind="method" type={`(args: RefreshArgs) => Promise&#60;V&#62;`}   />
+
+Force a refresh of the value, e.g. when it is known that the value has changed such as after
+an update operation to the source data in the database.
+
+
+</div>
+
+
+## SelfRefreshingCacheConfig
+
+<GenerationInfo sourceFile="packages/core/src/common/self-refreshing-cache.ts" sourceLine="46" packageName="@vendure/core" />
+
+Configuration options for creating a <a href='/reference/typescript-api/cache/self-refreshing-cache#selfrefreshingcache'>SelfRefreshingCache</a>.
+
+```ts title="Signature"
+interface SelfRefreshingCacheConfig<V, RefreshArgs extends any[]> {
+    name: string;
+    ttl: number;
+    refresh: {
+        fn: (...args: RefreshArgs) => Promise<V>;
+        /**
+         * Default arguments, passed to refresh function
+         */
+        defaultArgs: RefreshArgs;
+    };
+    getTimeFn?: () => number;
+}
+```
+
+<div className="members-wrapper">
+
+### name
+
+<MemberInfo kind="property" type={`string`}   />
+
+The name of the cache, used for logging purposes.
+e.g. `'MyService.cachedValue'`.
+### ttl
+
+<MemberInfo kind="property" type={`number`}   />
+
+The time-to-live (ttl) in milliseconds for the cache. After this time, the value will be considered stale
+and will be refreshed the next time it is accessed.
+### refresh
+
+<MemberInfo kind="property" type={`{         fn: (...args: RefreshArgs) =&#62; Promise&#60;V&#62;;         /**          * Default arguments, passed to refresh function          */         defaultArgs: RefreshArgs;     }`}   />
+
+The function which is used to refresh the value of the cache.
+This function should return a Promise which resolves to the new value.
+### getTimeFn
+
+<MemberInfo kind="property" type={`() =&#62; number`}   />
+
+Intended for unit testing the SelfRefreshingCache only.
+By default uses `() => new Date().getTime()`
+
+
+</div>
+
+
+## createSelfRefreshingCache
+
+<GenerationInfo sourceFile="packages/core/src/common/self-refreshing-cache.ts" sourceLine="114" packageName="@vendure/core" />
+
+Creates a <a href='/reference/typescript-api/cache/self-refreshing-cache#selfrefreshingcache'>SelfRefreshingCache</a> object, which is used to cache a single frequently-accessed value. In this type
+of cache, the function used to populate the value (`refreshFn`) is defined during the creation of the cache, and
+it is immediately used to populate the initial value.
+
+From there, when the `.value` property is accessed, it will return a value from the cache, and if the
+value has expired, it will automatically run the `refreshFn` to update the value and then return the
+fresh value.
+
+*Example*
+
+```ts title="Example of creating a SelfRefreshingCache"
+import { createSelfRefreshingCache } from '@vendure/core';
+
+@Injectable()
+export class PublicChannelService {
+  private publicChannel: SelfRefreshingCache<Channel, [RequestContext]>;
+
+  async init() {
+    this.publicChannel = await createSelfRefreshingCache<Channel, [RequestContext]>({
+     name: 'PublicChannelService.publicChannel',
+     ttl: 1000 * 60 * 60, // 1 hour
+     refresh: {
+       fn: async (ctx: RequestContext) => {
+        return this.channelService.getPublicChannel(ctx);
+      },
+     defaultArgs: [RequestContext.empty()],
+    },
+  });
+}
+```
+
+```ts title="Signature"
+function createSelfRefreshingCache<V, RefreshArgs extends any[]>(config: SelfRefreshingCacheConfig<V, RefreshArgs>, refreshArgs?: RefreshArgs): Promise<SelfRefreshingCache<V, RefreshArgs>>
+```
+Parameters
+
+### config
+
+<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/cache/self-refreshing-cache#selfrefreshingcacheconfig'>SelfRefreshingCacheConfig</a>&#60;V, RefreshArgs&#62;`} />
+
+### refreshArgs
+
+<MemberInfo kind="parameter" type={`RefreshArgs`} />
+

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

@@ -0,0 +1,87 @@
+---
+title: "SqlCacheStrategy"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## SqlCacheStrategy
+
+<GenerationInfo sourceFile="packages/core/src/plugin/default-cache-plugin/sql-cache-strategy.ts" sourceLine="21" 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 {
+    protected cacheSize = 10_000;
+    protected ttlProvider: CacheTtlProvider;
+    constructor(config?: { cacheSize?: number; cacheTtlProvider?: CacheTtlProvider })
+    protected connection: TransactionalConnection;
+    protected configService: ConfigService;
+    init(injector: Injector) => ;
+    get(key: string) => Promise<T | undefined>;
+    set(key: string, value: T, options?: SetCacheKeyOptions) => ;
+    delete(key: string) => ;
+    invalidateTags(tags: string[]) => ;
+}
+```
+* Implements: <code><a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a></code>
+
+
+
+<div className="members-wrapper">
+
+### cacheSize
+
+<MemberInfo kind="property" type={``}   />
+
+
+### ttlProvider
+
+<MemberInfo kind="property" type={`CacheTtlProvider`}   />
+
+
+### constructor
+
+<MemberInfo kind="method" type={`(config?: { cacheSize?: number; cacheTtlProvider?: CacheTtlProvider }) => SqlCacheStrategy`}   />
+
+
+### connection
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>`}   />
+
+
+### configService
+
+<MemberInfo kind="property" type={`ConfigService`}   />
+
+
+### init
+
+<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />
+
+
+### get
+
+<MemberInfo kind="method" type={`(key: string) => Promise&#60;T | undefined&#62;`}   />
+
+
+### set
+
+<MemberInfo kind="method" type={`(key: string, value: T, options?: <a href='/reference/typescript-api/cache/cache-strategy#setcachekeyoptions'>SetCacheKeyOptions</a>) => `}   />
+
+
+### delete
+
+<MemberInfo kind="method" type={`(key: string) => `}   />
+
+
+### invalidateTags
+
+<MemberInfo kind="method" type={`(tags: string[]) => `}   />
+
+
+
+
+</div>

package/docs/reference/typescript-api/common/admin-ui/admin-ui-app-config.md

@@ -0,0 +1,43 @@
+---
+title: "AdminUiAppConfig"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## AdminUiAppConfig
+
+<GenerationInfo sourceFile="packages/common/src/shared-types.ts" sourceLine="355" packageName="@vendure/common" />
+
+Configures the path to a custom-build of the Admin UI app.
+
+```ts title="Signature"
+interface AdminUiAppConfig {
+    path: string;
+    route?: string;
+    compile?: () => Promise<void>;
+}
+```
+
+<div className="members-wrapper">
+
+### path
+
+<MemberInfo kind="property" type={`string`}   />
+
+The path to the compiled admin UI app files. If not specified, an internal
+default build is used. This path should contain the `vendure-ui-config.json` file,
+index.html, the compiled js bundles etc.
+### route
+
+<MemberInfo kind="property" type={`string`} default={`'admin'`}   />
+
+Specifies the url route to the Admin UI app.
+### compile
+
+<MemberInfo kind="property" type={`() =&#62; Promise&#60;void&#62;`}   />
+
+The function which will be invoked to start the app compilation process.
+
+
+</div>

package/docs/reference/typescript-api/common/admin-ui/admin-ui-app-dev-mode-config.md

@@ -0,0 +1,47 @@
+---
+title: "AdminUiAppDevModeConfig"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## AdminUiAppDevModeConfig
+
+<GenerationInfo sourceFile="packages/common/src/shared-types.ts" sourceLine="383" packageName="@vendure/common" />
+
+Information about the Admin UI app dev server.
+
+```ts title="Signature"
+interface AdminUiAppDevModeConfig {
+    sourcePath: string;
+    port: number;
+    route?: string;
+    compile: () => Promise<void>;
+}
+```
+
+<div className="members-wrapper">
+
+### sourcePath
+
+<MemberInfo kind="property" type={`string`}   />
+
+The path to the uncompiled UI app source files. This path should contain the `vendure-ui-config.json` file.
+### port
+
+<MemberInfo kind="property" type={`number`}   />
+
+The port on which the dev server is listening. Overrides the value set by `AdminUiOptions.port`.
+### route
+
+<MemberInfo kind="property" type={`string`} default={`'admin'`}   />
+
+Specifies the url route to the Admin UI app.
+### compile
+
+<MemberInfo kind="property" type={`() =&#62; Promise&#60;void&#62;`}   />
+
+The function which will be invoked to start the app compilation process.
+
+
+</div>