@vendure/docs 0.0.0-202601161541

package/docs/reference/typescript-api/request/api-type.md

@@ -0,0 +1,16 @@
+---
+title: "ApiType"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## ApiType
+
+<GenerationInfo sourceFile="packages/core/src/api/common/get-api-type.ts" sourceLine="9" packageName="@vendure/core" />
+
+Which of the GraphQL APIs the current request came via.
+
+```ts title="Signature"
+type ApiType = 'admin' | 'shop' | 'custom'
+```

package/docs/reference/typescript-api/request/ctx-decorator.md

@@ -0,0 +1,23 @@
+---
+title: "Ctx Decorator"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## Ctx
+
+<GenerationInfo sourceFile="packages/core/src/api/decorators/request-context.decorator.ts" sourceLine="23" packageName="@vendure/core" />
+
+Resolver param decorator which extracts the <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> from the incoming
+request object.
+
+*Example*
+
+```ts
+ @Query()
+ getAdministrators(@Ctx() ctx: RequestContext) {
+     // ...
+ }
+```
+

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

@@ -0,0 +1,5 @@
+---
+title: "Request"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->

package/docs/reference/typescript-api/request/relations-decorator.md

@@ -0,0 +1,116 @@
+---
+title: "Relations Decorator"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## Relations
+
+<GenerationInfo sourceFile="packages/core/src/api/decorators/relations.decorator.ts" sourceLine="136" packageName="@vendure/core" since="1.6.0" />
+
+Resolver param decorator which returns an array of relation paths which can be passed through
+to the TypeORM data layer in order to join only the required relations. This works by inspecting
+the GraphQL `info` object, examining the field selection, and then comparing this with information
+about the return type's relations.
+
+In addition to analyzing the field selection, this decorator also checks for any `@Calculated()`
+properties on the entity, and additionally includes relations from the `relations` array of the calculated
+metadata, if defined.
+
+So if, for example, the query only selects the `id` field of an Order, then no other relations need
+be joined in the resulting SQL query. This can massively speed up execution time for queries which do
+not include many deep nested relations.
+
+*Example*
+
+```ts
+@Query()
+@Allow(Permission.ReadOrder)
+orders(
+    @Ctx() ctx: RequestContext,
+    @Args() args: QueryOrdersArgs,
+    @Relations(Order) relations: RelationPaths<Order>,
+): Promise<PaginatedList<Order>> {
+    return this.orderService.findAll(ctx, args.options || undefined, relations);
+}
+```
+
+In the above example, given the following query:
+
+*Example*
+
+```GraphQL
+{
+  orders(options: { take: 10 }) {
+    items {
+      id
+      customer {
+        id
+        firstName
+        lastName
+      }
+      totalQuantity
+      totalWithTax
+    }
+  }
+}
+```
+then the value of `relations` will be
+
+```
+['customer', 'lines'']
+```
+The `'customer'` comes from the fact that the query is nesting the "customer" object, and the `'lines'` is taken
+from the `Order` entity's `totalQuantity` property, which uses <a href='/reference/typescript-api/data-access/calculated#calculated'>Calculated</a> decorator and defines those relations as dependencies
+for deriving the calculated value.
+
+## Depth
+
+By default, when inspecting the GraphQL query, the Relations decorator will look 3 levels deep in any nested fields. So, e.g. if
+the above `orders` query were changed to:
+
+*Example*
+
+```GraphQL
+{
+  orders(options: { take: 10 }) {
+    items {
+      id
+      lines {
+        productVariant {
+          product {
+            featuredAsset {
+              preview
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+then the `relations` array would include `'lines'`, `'lines.productVariant'`, & `'lines.productVariant.product'` - 3 levels deep - but it would
+_not_ include `'lines.productVariant.product.featuredAsset'` since that exceeds the default depth. To specify a custom depth, you would
+use the decorator like this:
+
+*Example*
+
+```ts
+@Relations({ entity: Order, depth: 2 }) relations: RelationPaths<Order>,
+```
+
+## Omit
+
+The `omit` option is used to explicitly omit certain relations from the calculated relations array. This is useful in certain
+cases where we know for sure that we need to run the field resolver _anyway_. A good example is the `Collection.productVariants` relation.
+When a GraphQL query comes in for a Collection and also requests its `productVariants` field, there is no point using a lookahead to eagerly
+join that relation, because we will throw that data away anyway when the `productVariants` field resolver executes, since it returns a
+PaginatedList query rather than a simple array.
+
+*Example*
+
+```ts
+@Relations({ entity: Collection, omit: ['productVariant'] }) relations: RelationPaths<Collection>,
+```
+

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

@@ -0,0 +1,47 @@
+---
+title: "RequestContextService"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## RequestContextService
+
+<GenerationInfo sourceFile="packages/core/src/service/helpers/request-context/request-context.service.ts" sourceLine="25" packageName="@vendure/core" />
+
+Creates new <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> instances.
+
+```ts title="Signature"
+class RequestContextService {
+    create(config: {
+        req?: Request;
+        apiType: ApiType;
+        channelOrToken?: Channel | string;
+        languageCode?: LanguageCode;
+        currencyCode?: CurrencyCode;
+        user?: User;
+        activeOrderId?: ID;
+    }) => Promise<RequestContext>;
+    fromRequest(req: Request, info?: GraphQLResolveInfo, requiredPermissions?: Permission[], session?: CachedSession) => Promise<RequestContext>;
+}
+```
+
+<div className="members-wrapper">
+
+### create
+
+<MemberInfo kind="method" type={`(config: {         req?: Request;         apiType: <a href='/reference/typescript-api/request/api-type#apitype'>ApiType</a>;         channelOrToken?: <a href='/reference/typescript-api/entities/channel#channel'>Channel</a> | string;         languageCode?: <a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>;         currencyCode?: <a href='/reference/typescript-api/common/currency-code#currencycode'>CurrencyCode</a>;         user?: <a href='/reference/typescript-api/entities/user#user'>User</a>;         activeOrderId?: <a href='/reference/typescript-api/common/id#id'>ID</a>;     }) => Promise&#60;<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>&#62;`}  since="1.5.0"  />
+
+Creates a RequestContext based on the config provided. This can be useful when interacting
+with services outside the request-response cycle, for example in stand-alone scripts or in
+worker jobs.
+### fromRequest
+
+<MemberInfo kind="method" type={`(req: Request, info?: GraphQLResolveInfo, requiredPermissions?: <a href='/reference/typescript-api/common/permission#permission'>Permission</a>[], session?: <a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>) => Promise&#60;<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>&#62;`}   />
+
+Creates a new RequestContext based on an Express request object. This is used internally
+in the API layer by the AuthGuard, and creates the RequestContext which is then passed
+to all resolvers & controllers.
+
+
+</div>

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

@@ -0,0 +1,205 @@
+---
+title: "RequestContext"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## RequestContext
+
+<GenerationInfo sourceFile="packages/core/src/api/common/request-context.ts" sourceLine="179" packageName="@vendure/core" />
+
+The RequestContext holds information relevant to the current request, which may be
+required at various points of the stack.
+
+It is a good practice to inject the RequestContext (using the <a href='/reference/typescript-api/request/ctx-decorator#ctx'>Ctx</a> decorator) into
+_all_ resolvers & REST handler, and then pass it through to the service layer.
+
+This allows the service layer to access information about the current user, the active language,
+the active Channel, and so on. In addition, the <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a> relies on the
+presence of the RequestContext object in order to correctly handle per-request database transactions.
+
+The RequestContext also provides mechanisms for managing the database replication mode via the
+`setReplicationMode` method and the `replicationMode` getter. This allows for finer control
+over whether database queries within the context should be executed against the master or a replica
+database, which can be particularly useful in distributed database environments.
+
+*Example*
+
+```ts
+@Query()
+myQuery(@Ctx() ctx: RequestContext) {
+  return this.myService.getData(ctx);
+}
+```
+
+*Example*
+
+```ts
+@Query()
+myMutation(@Ctx() ctx: RequestContext) {
+  ctx.setReplicationMode('master');
+  return this.myService.getData(ctx);
+}
+```
+
+```ts title="Signature"
+class RequestContext {
+    empty() => RequestContext;
+    deserialize(ctxObject: SerializedRequestContext) => RequestContext;
+    userHasPermissions(permissions: Permission[]) => boolean;
+    userHasAllPermissions(permissions: Permission[]) => boolean;
+    serialize() => SerializedRequestContext;
+    copy() => RequestContext;
+    req: Request | undefined
+    apiType: ApiType
+    channel: Channel
+    channelId: ID
+    languageCode: LanguageCode
+    currencyCode: CurrencyCode
+    session: CachedSession | undefined
+    activeUserId: ID | undefined
+    isAuthorized: boolean
+    authorizedAsOwnerOnly: boolean
+    translate(key: string, variables?: { [k: string]: any }) => string;
+    setReplicationMode(mode: ReplicationMode) => void;
+    replicationMode: ReplicationMode | undefined
+}
+```
+
+<div className="members-wrapper">
+
+### empty
+
+<MemberInfo kind="method" type={`() => <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />
+
+Creates an "empty" RequestContext object. This is only intended to be used
+when a service method must be called outside the normal request-response
+cycle, e.g. when programmatically populating data. Usually a better alternative
+is to use the <a href='/reference/typescript-api/request/request-context-service#requestcontextservice'>RequestContextService</a> `create()` method, which allows more control
+over the resulting RequestContext object.
+### deserialize
+
+<MemberInfo kind="method" type={`(ctxObject: SerializedRequestContext) => <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />
+
+Creates a new RequestContext object from a serialized object created by the
+`serialize()` method.
+### userHasPermissions
+
+<MemberInfo kind="method" type={`(permissions: <a href='/reference/typescript-api/common/permission#permission'>Permission</a>[]) => boolean`}   />
+
+Returns `true` if there is an active Session & User associated with this request,
+and that User has **at least one** of the specified permissions on the active Channel.
+
+This method uses OR logic - it checks if the user has ANY of the given permissions,
+not ALL of them. For AND logic, use {@link userHasAllPermissions}.
+
+*Example*
+
+```ts
+// Returns true if user has ReadProduct OR ReadCatalog
+ctx.userHasPermissions([Permission.ReadProduct, Permission.ReadCatalog]);
+```
+### userHasAllPermissions
+
+<MemberInfo kind="method" type={`(permissions: <a href='/reference/typescript-api/common/permission#permission'>Permission</a>[]) => boolean`}  since="3.6.0"  />
+
+Returns `true` if there is an active Session & User associated with this request,
+and that User has **all** of the specified permissions on the active Channel.
+
+This method uses AND logic - it checks if the user has EVERY one of the given permissions.
+For OR logic (any permission), use {@link userHasPermissions}.
+
+*Example*
+
+```ts
+// Returns true only if user has BOTH ReadProduct AND UpdateProduct
+ctx.userHasAllPermissions([Permission.ReadProduct, Permission.UpdateProduct]);
+```
+### serialize
+
+<MemberInfo kind="method" type={`() => SerializedRequestContext`}   />
+
+Serializes the RequestContext object into a JSON-compatible simple object.
+This is useful when you need to send a RequestContext object to another
+process, e.g. to pass it to the Job Queue via the <a href='/reference/typescript-api/job-queue/job-queue-service#jobqueueservice'>JobQueueService</a>.
+### copy
+
+<MemberInfo kind="method" type={`() => <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`}   />
+
+Creates a shallow copy of the RequestContext instance. This means that
+mutations to the copy itself will not affect the original, but deep mutations
+(e.g. copy.channel.code = 'new') *will* also affect the original.
+### req
+
+<MemberInfo kind="property" type={`Request | undefined`}   />
+
+The raw Express request object.
+### apiType
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/request/api-type#apitype'>ApiType</a>`}   />
+
+Signals which API this request was received by, e.g. `admin` or `shop`.
+### channel
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/channel#channel'>Channel</a>`}   />
+
+The active <a href='/reference/typescript-api/entities/channel#channel'>Channel</a> of this request.
+### channelId
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a>`}   />
+
+
+### languageCode
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/language-code#languagecode'>LanguageCode</a>`}   />
+
+
+### currencyCode
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/currency-code#currencycode'>CurrencyCode</a>`}   />
+
+
+### session
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a> | undefined`}   />
+
+
+### activeUserId
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/common/id#id'>ID</a> | undefined`}   />
+
+
+### isAuthorized
+
+<MemberInfo kind="property" type={`boolean`}   />
+
+True if the current session is authorized to access the current resolver method.
+### authorizedAsOwnerOnly
+
+<MemberInfo kind="property" type={`boolean`}   />
+
+True if the current anonymous session is only authorized to operate on entities that
+are owned by the current session.
+### translate
+
+<MemberInfo kind="method" type={`(key: string, variables?: { [k: string]: any }) => string`}   />
+
+Translate the given i18n key
+### setReplicationMode
+
+<MemberInfo kind="method" type={`(mode: ReplicationMode) => void`}   />
+
+Sets the replication mode for the current RequestContext. This mode determines whether the operations
+within this context should interact with the master database or a replica. Use this method to explicitly
+define the replication mode for the context.
+### replicationMode
+
+<MemberInfo kind="property" type={`ReplicationMode | undefined`}   />
+
+Gets the current replication mode of the RequestContext. If no replication mode has been set,
+it returns `undefined`. This property indicates whether the context is configured to interact with
+the master database or a replica.
+
+
+</div>

package/docs/reference/typescript-api/request/transaction-decorator.md

@@ -0,0 +1,82 @@
+---
+title: "Transaction Decorator"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## Transaction
+
+<GenerationInfo sourceFile="packages/core/src/api/decorators/transaction.decorator.ts" sourceLine="81" packageName="@vendure/core" />
+
+Runs the decorated method in a TypeORM transaction. It works by creating a transactional
+QueryRunner which gets attached to the RequestContext object. When the RequestContext
+is the passed to the <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a> `getRepository()` method, this
+QueryRunner is used to execute the queries within this transaction.
+
+Essentially, the entire resolver function is wrapped in a try-catch block which commits the
+transaction on successful completion of the method, or rolls back the transaction in an unhandled
+error is thrown.
+
+*Example*
+
+```ts
+// in a GraphQL resolver file
+
+@Transaction()
+async myMutation(@Ctx() ctx: RequestContext) {
+  // as long as the `ctx` object is passed in to
+  // all database operations, the entire mutation
+  // will be run as an atomic transaction, and rolled
+  // back if an error is thrown.
+  const result = this.myService.createThing(ctx);
+  return this.myService.updateOtherThing(ctx, result.id);
+}
+```
+
+
+
+## TransactionMode
+
+<GenerationInfo sourceFile="packages/core/src/api/decorators/transaction.decorator.ts" sourceLine="32" packageName="@vendure/core" />
+
+The Transaction decorator can handle transactions automatically (which is the default) or be set to
+"manual" mode, where the <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a> `.startTransaction()` and `.commitOpenTransaction()`
+methods must them be used.
+
+*Example*
+
+```ts
+// in a GraphQL resolver file
+
+@Transaction('manual')
+async myMutation(@Ctx() ctx: RequestContext) {
+  await this.connection.startTransaction(ctx);
+  const result = this.myService.createThing(ctx);
+  const thing = this.myService.updateOtherThing(ctx, result.id);
+  await this.connection.commitOpenTransaction(ctx);
+  return thing;
+}
+```
+Note that even in manual mode, a rollback will be automatically performed in
+the case that an uncaught error is thrown within the resolver.
+
+```ts title="Signature"
+type TransactionMode = 'auto' | 'manual'
+```
+
+
+## TransactionIsolationLevel
+
+<GenerationInfo sourceFile="packages/core/src/api/decorators/transaction.decorator.ts" sourceLine="45" packageName="@vendure/core" />
+
+Transactions can be run at different isolation levels. The default is undefined, which
+falls back to the default of your database. See the documentation of your database for more
+information on available isolation levels.
+
+```ts title="Signature"
+type TransactionIsolationLevel = | 'READ UNCOMMITTED'
+    | 'READ COMMITTED'
+    | 'REPEATABLE READ'
+    | 'SERIALIZABLE'
+```

package/docs/reference/typescript-api/scheduled-tasks/clean-sessions-task.md

@@ -0,0 +1,40 @@
+---
+title: "CleanSessionsTask"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## cleanSessionsTask
+
+<GenerationInfo sourceFile="packages/core/src/scheduler/tasks/clean-sessions-task.ts" sourceLine="37" packageName="@vendure/core" since="3.3.0" />
+
+A <a href='/reference/typescript-api/scheduled-tasks/scheduled-task#scheduledtask'>ScheduledTask</a> that cleans expired & inactive sessions from the database.
+
+*Example*
+
+```ts
+import { cleanSessionsTask, VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+  // ...
+  schedulerOptions: {
+    tasks: [
+      // Use the task as is
+      cleanSessionsTask,
+      // or configure the task
+      cleanSessionsTask.configure({
+        // Run the task every day at 3:00am
+        // The default schedule is every day at 00:00am
+        schedule: cron => cron.everyDayAt(3, 0),
+        params: {
+          // How many sessions to process in each batch
+          // Default: 1000
+          batchSize: 5_000,
+        },
+      }),
+    ],
+  },
+};
+```
+

package/docs/reference/typescript-api/scheduled-tasks/default-scheduler-plugin.md

@@ -0,0 +1,86 @@
+---
+title: "DefaultSchedulerPlugin"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## DefaultSchedulerPlugin
+
+<GenerationInfo sourceFile="packages/core/src/plugin/default-scheduler-plugin/default-scheduler.plugin.ts" sourceLine="40" packageName="@vendure/core" since="3.3.0" />
+
+This plugin configures a default scheduling strategy that executes scheduled
+tasks using the database to ensure that each task is executed exactly once
+at the scheduled time, even if there are multiple instances of the worker
+running.
+
+*Example*
+
+```ts
+import { DefaultSchedulerPlugin, VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+  plugins: [
+    DefaultSchedulerPlugin.init({
+      // The default is 60s, but you can override it here
+      defaultTimeout: '10s',
+    }),
+  ],
+};
+```
+
+```ts title="Signature"
+class DefaultSchedulerPlugin {
+    static options: DefaultSchedulerPluginOptions = {
+        defaultTimeout: DEFAULT_TIMEOUT,
+        manualTriggerCheckInterval: DEFAULT_MANUAL_TRIGGER_CHECK_INTERVAL,
+    };
+    init(config?: DefaultSchedulerPluginOptions) => ;
+}
+```
+
+<div className="members-wrapper">
+
+### options
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/scheduled-tasks/default-scheduler-plugin#defaultschedulerpluginoptions'>DefaultSchedulerPluginOptions</a>`}   />
+
+
+### init
+
+<MemberInfo kind="method" type={`(config?: <a href='/reference/typescript-api/scheduled-tasks/default-scheduler-plugin#defaultschedulerpluginoptions'>DefaultSchedulerPluginOptions</a>) => `}   />
+
+
+
+
+</div>
+
+
+## DefaultSchedulerPluginOptions
+
+<GenerationInfo sourceFile="packages/core/src/plugin/default-scheduler-plugin/types.ts" sourceLine="9" packageName="@vendure/core" since="3.3.0" />
+
+The options for the <a href='/reference/typescript-api/scheduled-tasks/default-scheduler-plugin#defaultschedulerplugin'>DefaultSchedulerPlugin</a>.
+
+```ts title="Signature"
+interface DefaultSchedulerPluginOptions {
+    defaultTimeout?: string | number;
+    manualTriggerCheckInterval?: string | number;
+}
+```
+
+<div className="members-wrapper">
+
+### defaultTimeout
+
+<MemberInfo kind="property" type={`string | number`} default={`60_000ms`}   />
+
+The default timeout for scheduled tasks.
+### manualTriggerCheckInterval
+
+<MemberInfo kind="property" type={`string | number`} default={`10_000ms`}   />
+
+The interval at which the plugin will check for manually triggered tasks.
+
+
+</div>