@vendure/docs 0.0.0-202601161541

package/docs/reference/typescript-api/job-queue/inspectable-job-queue-strategy.md

@@ -0,0 +1,60 @@
+---
+title: "InspectableJobQueueStrategy"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## InspectableJobQueueStrategy
+
+<GenerationInfo sourceFile="packages/core/src/config/job-queue/inspectable-job-queue-strategy.ts" sourceLine="14" packageName="@vendure/core" />
+
+Defines a job queue strategy that can be inspected using the default admin ui
+
+```ts title="Signature"
+interface InspectableJobQueueStrategy extends JobQueueStrategy {
+    findOne(id: ID): Promise<Job | undefined>;
+    findMany(options?: JobListOptions): Promise<PaginatedList<Job>>;
+    findManyById(ids: ID[]): Promise<Job[]>;
+    removeSettledJobs(queueNames?: string[], olderThan?: Date): Promise<number>;
+    cancelJob(jobId: ID): Promise<Job | undefined>;
+}
+```
+* Extends: <code><a href='/reference/typescript-api/job-queue/job-queue-strategy#jobqueuestrategy'>JobQueueStrategy</a></code>
+
+
+
+<div className="members-wrapper">
+
+### findOne
+
+<MemberInfo kind="method" type={`(id: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a> | undefined&#62;`}   />
+
+Returns a job by its id.
+### findMany
+
+<MemberInfo kind="method" type={`(options?: JobListOptions) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#62;&#62;`}   />
+
+Returns a list of jobs according to the specified options.
+### findManyById
+
+<MemberInfo kind="method" type={`(ids: <a href='/reference/typescript-api/common/id#id'>ID</a>[]) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>[]&#62;`}   />
+
+Returns an array of jobs for the given ids.
+### removeSettledJobs
+
+<MemberInfo kind="method" type={`(queueNames?: string[], olderThan?: Date) => Promise&#60;number&#62;`}   />
+
+Remove all settled jobs in the specified queues older than the given date.
+If no queueName is passed, all queues will be considered. If no olderThan
+date is passed, all jobs older than the current time will be removed.
+
+Returns a promise of the number of jobs removed.
+### cancelJob
+
+<MemberInfo kind="method" type={`(jobId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a> | undefined&#62;`}   />
+
+
+
+
+</div>

package/docs/reference/typescript-api/job-queue/job-buffer-storage-strategy.md

@@ -0,0 +1,78 @@
+---
+title: "JobBufferStorageStrategy"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## JobBufferStorageStrategy
+
+<GenerationInfo sourceFile="packages/core/src/job-queue/job-buffer/job-buffer-storage-strategy.ts" sourceLine="19" packageName="@vendure/core" since="1.3.0" />
+
+This strategy defines where to store jobs that have been collected by a
+<a href='/reference/typescript-api/job-queue/job-buffer#jobbuffer'>JobBuffer</a>.
+
+:::info
+
+This is configured via the `jobQueueOptions.jobBufferStorageStrategy` property of
+your VendureConfig.
+
+:::
+
+```ts title="Signature"
+interface JobBufferStorageStrategy extends InjectableStrategy {
+    add(bufferId: string, job: Job): Promise<Job>;
+    bufferSize(bufferIds?: string[]): Promise<{ [bufferId: string]: number }>;
+    flush(bufferIds?: string[]): Promise<{ [bufferId: string]: Job[] }>;
+}
+```
+* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>
+
+
+
+<div className="members-wrapper">
+
+### add
+
+<MemberInfo kind="method" type={`(bufferId: string, job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#62;`}   />
+
+Persist a job to the storage medium. The storage format should
+take into account the `bufferId` argument, as it is necessary to be
+able to later retrieve jobs by that id.
+### bufferSize
+
+<MemberInfo kind="method" type={`(bufferIds?: string[]) => Promise&#60;{ [bufferId: string]: number }&#62;`}   />
+
+Returns an object containing the number of buffered jobs arranged by bufferId.
+
+Passing bufferIds limits the results to the specified bufferIds.
+If the array is empty, sizes will be returned for _all_ bufferIds.
+
+*Example*
+
+```ts
+const sizes = await myJobBufferStrategy.bufferSize(['buffer-1', 'buffer-2']);
+
+// sizes = { 'buffer-1': 12, 'buffer-2': 3 }
+```
+### flush
+
+<MemberInfo kind="method" type={`(bufferIds?: string[]) => Promise&#60;{ [bufferId: string]: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>[] }&#62;`}   />
+
+Clears all jobs from the storage medium which match the specified bufferIds (if the
+array is empty, clear for _all_ bufferIds), and returns those jobs in an object
+arranged by bufferId
+
+*Example*
+
+```ts
+const result = await myJobBufferStrategy.flush(['buffer-1', 'buffer-2']);
+
+// result = {
+//   'buffer-1': [Job, Job, Job, ...],
+//   'buffer-2': [Job, Job, Job, ...],
+// };
+```
+
+
+</div>

package/docs/reference/typescript-api/job-queue/job-buffer.md

@@ -0,0 +1,119 @@
+---
+title: "JobBuffer"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## JobBuffer
+
+<GenerationInfo sourceFile="packages/core/src/job-queue/job-buffer/job-buffer.ts" sourceLine="83" packageName="@vendure/core" since="1.3.0" />
+
+A JobBuffer is used to temporarily prevent jobs from being sent to the job queue for processing.
+Instead, it collects certain jobs (as specified by the `collect()` method), and stores them.
+
+How these buffered jobs are stored is determined by the configured <a href='/reference/typescript-api/job-queue/job-buffer-storage-strategy#jobbufferstoragestrategy'>JobBufferStorageStrategy</a>.
+
+The JobBuffer can be thought of as a kind of "interceptor" of jobs. That is, when a JobBuffer is active,
+it sits in between calls to `JobQueue.add()` and the actual adding of the job to the queue.
+
+At some later point, the buffer can be flushed (by calling `JobQueue.flush()`), at which point all the jobs
+that were collected into the buffer will be removed from the buffer and passed to the `JobBuffer.reduce()` method.
+This method is able to perform additional logic to e.g. aggregate many jobs into a single job in order to de-duplicate
+work.
+
+*Example*
+
+```ts
+// This is a buffer which will collect all the
+// 'apply-collection-filters' jobs and buffer them.
+export class CollectionJobBuffer implements JobBuffer<ApplyCollectionFiltersJobData> {
+  readonly id = 'apply-collection-filters-buffer';
+
+  collect(job: Job): boolean {
+    return job.queueName === 'apply-collection-filters';
+  }
+
+
+  // When the buffer gets flushed, this function will be passed all the collected jobs
+  // and will reduce them down to a single job that has aggregated all of the collectionIds.
+  reduce(collectedJobs: Array<Job<ApplyCollectionFiltersJobData>>): Array<Job<any>> {
+    // Concatenate all the collectionIds from all the events that were buffered
+    const collectionIdsToUpdate = collectedJobs.reduce((result, job) => {
+      return [...result, ...job.data.collectionIds];
+    }, [] as ID[]);
+
+    const referenceJob = collectedJobs[0];
+
+    // Create a new Job containing all the concatenated collectionIds,
+    // de-duplicated to include each collectionId only once.
+    const batchedCollectionJob = new Job<ApplyCollectionFiltersJobData>({
+      ...referenceJob,
+      id: undefined,
+      data: {
+        collectionIds: unique(collectionIdsToUpdate),
+        ctx: referenceJob.data.ctx,
+        applyToChangedVariantsOnly: referenceJob.data.applyToChangedVariantsOnly,
+      },
+    });
+
+    // Only this single job will get added to the job queue
+    return [batchedCollectionJob];
+  }
+}
+```
+
+A JobBuffer is used by adding it to the <a href='/reference/typescript-api/job-queue/job-queue-service#jobqueueservice'>JobQueueService</a>, at which point it will become active
+and start collecting jobs.
+
+At some later point, the buffer can be flushed, causing the buffered jobs to be passed through the
+`reduce()` method and sent to the job queue.
+
+*Example*
+
+```ts
+const collectionBuffer = new CollectionJobBuffer();
+
+await this.jobQueueService.addBuffer(collectionBuffer);
+
+// Here you can perform some work which would ordinarily
+// trigger the 'apply-collection-filters' job, such as updating
+// collection filters or changing ProductVariant prices.
+
+await this.jobQueueService.flush(collectionBuffer);
+
+await this.jobQueueService.removeBuffer(collectionBuffer);
+```
+
+```ts title="Signature"
+interface JobBuffer<Data extends JobData<Data> = object> {
+    readonly id: string;
+    collect(job: Job<Data>): boolean | Promise<boolean>;
+    reduce(collectedJobs: Array<Job<Data>>): Array<Job<Data>> | Promise<Array<Job<Data>>>;
+}
+```
+
+<div className="members-wrapper">
+
+### id
+
+<MemberInfo kind="property" type={`string`}   />
+
+
+### collect
+
+<MemberInfo kind="method" type={`(job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;) => boolean | Promise&#60;boolean&#62;`}   />
+
+This method is called whenever a job is added to the job queue. If it returns `true`, then
+the job will be _buffered_ and _not_ added to the job queue. If it returns `false`, the job
+will be added to the job queue as normal.
+### reduce
+
+<MemberInfo kind="method" type={`(collectedJobs: Array&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;&#62;) => Array&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;&#62; | Promise&#60;Array&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;&#62;&#62;`}   />
+
+This method is called whenever the buffer gets flushed via a call to `JobQueueService.flush()`.
+It allows logic to be run on the buffered jobs which enables optimizations such as
+aggregating and de-duplicating the work of many jobs into one job.
+
+
+</div>

package/docs/reference/typescript-api/job-queue/job-queue-options.md

@@ -0,0 +1,56 @@
+---
+title: "JobQueueOptions"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## JobQueueOptions
+
+<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="960" packageName="@vendure/core" />
+
+Options related to the built-in job queue.
+
+```ts title="Signature"
+interface JobQueueOptions {
+    jobQueueStrategy?: JobQueueStrategy;
+    jobBufferStorageStrategy?: JobBufferStorageStrategy;
+    activeQueues?: string[];
+    prefix?: string;
+}
+```
+
+<div className="members-wrapper">
+
+### jobQueueStrategy
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/job-queue/job-queue-strategy#jobqueuestrategy'>JobQueueStrategy</a>`} default={`<a href='/reference/typescript-api/job-queue/in-memory-job-queue-strategy#inmemoryjobqueuestrategy'>InMemoryJobQueueStrategy</a>`}   />
+
+Defines how the jobs in the queue are persisted and accessed.
+### jobBufferStorageStrategy
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/job-queue/job-buffer-storage-strategy#jobbufferstoragestrategy'>JobBufferStorageStrategy</a>`}   />
+
+
+### activeQueues
+
+<MemberInfo kind="property" type={`string[]`}   />
+
+Defines the queues that will run in this process.
+This can be used to configure only certain queues to run in this process.
+If its empty all queues will be run. Note: this option is primarily intended
+to apply to the Worker process. Jobs will _always_ get published to the queue
+regardless of this setting, but this setting determines whether they get
+_processed_ or not.
+### prefix
+
+<MemberInfo kind="property" type={`string`}  since="1.5.0"  />
+
+Prefixes all job queue names with the passed string. This is useful with multiple deployments
+in cloud environments using services such as Amazon SQS or Google Cloud Tasks.
+
+For example, we might have a staging and a production deployment in the same account/project and
+each one will need its own task queue. We can achieve this with a prefix.
+
+
+</div>

package/docs/reference/typescript-api/job-queue/job-queue-service.md

@@ -0,0 +1,128 @@
+---
+title: "JobQueueService"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## JobQueueService
+
+<GenerationInfo sourceFile="packages/core/src/job-queue/job-queue.service.ts" sourceLine="49" packageName="@vendure/core" />
+
+The JobQueueService is used to create new <a href='/reference/typescript-api/job-queue/#jobqueue'>JobQueue</a> instances and access
+existing jobs.
+
+*Example*
+
+```ts
+// A service which transcodes video files
+class VideoTranscoderService {
+
+  private jobQueue: JobQueue<{ videoId: string; }>;
+
+  async onModuleInit() {
+    // The JobQueue is created on initialization
+    this.jobQueue = await this.jobQueueService.createQueue({
+      name: 'transcode-video',
+      process: async job => {
+        return await this.transcodeVideo(job.data.videoId);
+      },
+    });
+  }
+
+  addToTranscodeQueue(videoId: string) {
+    this.jobQueue.add({ videoId, })
+  }
+
+  private async transcodeVideo(videoId: string) {
+    // e.g. call some external transcoding service
+  }
+
+}
+```
+
+```ts title="Signature"
+class JobQueueService implements OnModuleDestroy {
+    constructor(configService: ConfigService, jobBufferService: JobBufferService)
+    createQueue(options: CreateQueueOptions<Data>) => Promise<JobQueue<Data>>;
+    start() => Promise<void>;
+    addBuffer(buffer: JobBuffer<any>) => ;
+    removeBuffer(buffer: JobBuffer<any>) => ;
+    bufferSize(forBuffers: Array<JobBuffer<any> | string>) => Promise<{ [bufferId: string]: number }>;
+    flush(forBuffers: Array<JobBuffer<any> | string>) => Promise<Job[]>;
+    getJobQueues() => GraphQlJobQueue[];
+}
+```
+* Implements: <code>OnModuleDestroy</code>
+
+
+
+<div className="members-wrapper">
+
+### constructor
+
+<MemberInfo kind="method" type={`(configService: ConfigService, jobBufferService: JobBufferService) => JobQueueService`}   />
+
+
+### createQueue
+
+<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/job-queue/types#createqueueoptions'>CreateQueueOptions</a>&#60;Data&#62;) => Promise&#60;<a href='/reference/typescript-api/job-queue/#jobqueue'>JobQueue</a>&#60;Data&#62;&#62;`}   />
+
+Configures and creates a new <a href='/reference/typescript-api/job-queue/#jobqueue'>JobQueue</a> instance.
+### start
+
+<MemberInfo kind="method" type={`() => Promise&#60;void&#62;`}   />
+
+
+### addBuffer
+
+<MemberInfo kind="method" type={`(buffer: <a href='/reference/typescript-api/job-queue/job-buffer#jobbuffer'>JobBuffer</a>&#60;any&#62;) => `}  since="1.3.0"  />
+
+Adds a <a href='/reference/typescript-api/job-queue/job-buffer#jobbuffer'>JobBuffer</a>, which will make it active and begin collecting
+jobs to buffer.
+### removeBuffer
+
+<MemberInfo kind="method" type={`(buffer: <a href='/reference/typescript-api/job-queue/job-buffer#jobbuffer'>JobBuffer</a>&#60;any&#62;) => `}  since="1.3.0"  />
+
+Removes a <a href='/reference/typescript-api/job-queue/job-buffer#jobbuffer'>JobBuffer</a>, prevent it from collecting and buffering any
+subsequent jobs.
+### bufferSize
+
+<MemberInfo kind="method" type={`(forBuffers: Array&#60;<a href='/reference/typescript-api/job-queue/job-buffer#jobbuffer'>JobBuffer</a>&#60;any&#62; | string&#62;) => Promise&#60;{ [bufferId: string]: number }&#62;`}  since="1.3.0"  />
+
+Returns an object containing the number of buffered jobs arranged by bufferId. This
+can be used to decide whether a particular buffer has any jobs to flush.
+
+Passing in JobBuffer instances _or_ ids limits the results to the specified JobBuffers.
+If no argument is passed, sizes will be returned for _all_ JobBuffers.
+
+*Example*
+
+```ts
+const sizes = await this.jobQueueService.bufferSize('buffer-1', 'buffer-2');
+
+// sizes = { 'buffer-1': 12, 'buffer-2': 3 }
+```
+### flush
+
+<MemberInfo kind="method" type={`(forBuffers: Array&#60;<a href='/reference/typescript-api/job-queue/job-buffer#jobbuffer'>JobBuffer</a>&#60;any&#62; | string&#62;) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>[]&#62;`}  since="1.3.0"  />
+
+Flushes the specified buffers, which means that the buffer is cleared and the jobs get
+sent to the job queue for processing. Before sending the jobs to the job queue,
+they will be passed through each JobBuffer's `reduce()` method, which is can be used
+to optimize the amount of work to be done by e.g. de-duplicating identical jobs or
+aggregating data over the collected jobs.
+
+Passing in JobBuffer instances _or_ ids limits the action to the specified JobBuffers.
+If no argument is passed, _all_ JobBuffers will be flushed.
+
+Returns an array of all Jobs which were added to the job queue.
+### getJobQueues
+
+<MemberInfo kind="method" type={`() => GraphQlJobQueue[]`}   />
+
+Returns an array of `{ name: string; running: boolean; }` for each
+registered JobQueue.
+
+
+</div>

package/docs/reference/typescript-api/job-queue/job-queue-strategy.md

@@ -0,0 +1,59 @@
+---
+title: "JobQueueStrategy"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## JobQueueStrategy
+
+<GenerationInfo sourceFile="packages/core/src/config/job-queue/job-queue-strategy.ts" sourceLine="24" packageName="@vendure/core" />
+
+Defines how the jobs in the <a href='/reference/typescript-api/job-queue/job-queue-service#jobqueueservice'>JobQueueService</a> are persisted and
+accessed. Custom strategies can be defined to make use of external
+services such as Redis.
+
+:::info
+
+This is configured via the `jobQueueOptions.jobQueueStrategy` property of
+your VendureConfig.
+
+:::
+
+```ts title="Signature"
+interface JobQueueStrategy extends InjectableStrategy {
+    add<Data extends JobData<Data> = object>(job: Job<Data>, jobOptions?: JobQueueStrategyJobOptions<Data>): Promise<Job<Data>>;
+    start<Data extends JobData<Data> = object>(
+        queueName: string,
+        process: (job: Job<Data>) => Promise<any>,
+    ): Promise<void>;
+    stop<Data extends JobData<Data> = object>(
+        queueName: string,
+        process: (job: Job<Data>) => Promise<any>,
+    ): Promise<void>;
+}
+```
+* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>
+
+
+
+<div className="members-wrapper">
+
+### add
+
+<MemberInfo kind="method" type={`(job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;, jobOptions?: JobQueueStrategyJobOptions&#60;Data&#62;) => Promise&#60;<a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;&#62;`}   />
+
+Add a new job to the queue.
+### start
+
+<MemberInfo kind="method" type={`(queueName: string, process: (job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;) =&#62; Promise&#60;any&#62;) => Promise&#60;void&#62;`}   />
+
+Start the job queue
+### stop
+
+<MemberInfo kind="method" type={`(queueName: string, process: (job: <a href='/reference/typescript-api/job-queue/job#job'>Job</a>&#60;Data&#62;) =&#62; Promise&#60;any&#62;) => Promise&#60;void&#62;`}   />
+
+Stops a queue from running. Its not guaranteed to stop immediately.
+
+
+</div>