Skip to content

Commit 153af67

Browse files
ericallamericallam
committed
Add JSDocs
1 parent 69f3dca commit 153af67

File tree

2 files changed

+301
-0
lines changed

2 files changed

+301
-0
lines changed

‎packages/trigger-sdk/src/v3/batch.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,23 @@ export const batch = {
2222
retrieve: retrieveBatch,
2323
};
2424

25+
/**
26+
* Retrieves details about a specific batch by its ID.
27+
*
28+
* @param {string} batchId - The unique identifier of the batch to retrieve
29+
* @param {ApiRequestOptions} [requestOptions] - Optional API request configuration options
30+
* @returns {ApiPromise<RetrieveBatchResponse>} A promise that resolves with the batch details
31+
*
32+
* @example
33+
* // First trigger a batch
34+
* const response = await batch.trigger([
35+
* { id: "simple-task", payload: { message: "Hello, World!" } }
36+
* ]);
37+
*
38+
* // Then retrieve the batch details
39+
* const batchDetails = await batch.retrieve(response.batchId);
40+
* console.log("batch", batchDetails);
41+
*/
2542
function retrieveBatch(
2643
batchId: string,
2744
requestOptions?: ApiRequestOptions

‎packages/trigger-sdk/src/v3/shared.ts‎

Lines changed: 284 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -520,6 +520,59 @@ export async function batchTrigger<TTask extends AnyTask>(
520520
);
521521
}
522522

523+
/**
524+
* Triggers multiple runs of different tasks with specified payloads and options.
525+
*
526+
* @template TTask - The type of task(s) to be triggered, extends AnyTask
527+
*
528+
* @param {Array<BatchByIdItem<InferRunTypes<TTask>>>} items - Array of task items to trigger
529+
* @param {BatchTriggerOptions} [options] - Optional batch-level trigger options
530+
* @param {TriggerApiRequestOptions} [requestOptions] - Optional API request configuration
531+
*
532+
* @returns {Promise<BatchRunHandleFromTypes<InferRunTypes<TTask>>>} A promise that resolves with the batch run handle
533+
* containing batch ID, cached status, idempotency info, runs, and public access token
534+
*
535+
* @example
536+
* ```ts
537+
* import { batch } from "@trigger.dev/sdk/v3";
538+
* import type { myTask1, myTask2 } from "~/trigger/myTasks";
539+
*
540+
* // Trigger multiple tasks with different payloads
541+
* const result = await batch.trigger<typeof myTask1 | typeof myTask2>([
542+
* {
543+
* id: "my-task-1",
544+
* payload: { some: "data" },
545+
* options: {
546+
* queue: "default",
547+
* concurrencyKey: "key",
548+
* idempotencyKey: "unique-key",
549+
* delay: "5m",
550+
* tags: ["tag1", "tag2"]
551+
* }
552+
* },
553+
* {
554+
* id: "my-task-2",
555+
* payload: { other: "data" }
556+
* }
557+
* ]);
558+
* ```
559+
*
560+
* @description
561+
* Each task item in the array can include:
562+
* - `id`: The unique identifier of the task
563+
* - `payload`: The data to pass to the task
564+
* - `options`: Optional task-specific settings including:
565+
* - `queue`: Specify a queue for the task
566+
* - `concurrencyKey`: Control concurrent execution
567+
* - `idempotencyKey`: Prevent duplicate runs
568+
* - `idempotencyKeyTTL`: Time-to-live for idempotency key
569+
* - `delay`: Delay before task execution
570+
* - `ttl`: Time-to-live for the task
571+
* - `tags`: Array of tags for the task
572+
* - `maxAttempts`: Maximum retry attempts
573+
* - `metadata`: Additional metadata
574+
* - `maxDuration`: Maximum execution duration
575+
*/
523576
export async function batchTriggerById<TTask extends AnyTask>(
524577
items: Array<BatchByIdItem<InferRunTypes<TTask>>>,
525578
options?: BatchTriggerOptions,
@@ -608,6 +661,83 @@ export async function batchTriggerById<TTask extends AnyTask>(
608661
return handle as BatchRunHandleFromTypes<InferRunTypes<TTask>>;
609662
}
610663

664+
/**
665+
* Triggers multiple tasks and waits for all of them to complete before returning their results.
666+
* This function must be called from within a task.run() context.
667+
*
668+
* @template TTask - Union type of tasks to be triggered, extends AnyTask
669+
*
670+
* @param {Array<BatchByIdAndWaitItem<InferRunTypes<TTask>>>} items - Array of task items to trigger
671+
* @param {TriggerApiRequestOptions} [requestOptions] - Optional API request configuration
672+
*
673+
* @returns {Promise<BatchByIdResult<TTask>>} A promise that resolves with the batch results, including
674+
* success/failure status and strongly-typed outputs for each task
675+
*
676+
* @throws {Error} If called outside of a task.run() context
677+
* @throws {Error} If no API client is configured
678+
*
679+
* @example
680+
* ```ts
681+
* import { batch, task } from "@trigger.dev/sdk/v3";
682+
*
683+
* export const parentTask = task({
684+
* id: "parent-task",
685+
* run: async (payload: string) => {
686+
* const results = await batch.triggerAndWait<typeof childTask1 | typeof childTask2>([
687+
* {
688+
* id: "child-task-1",
689+
* payload: { foo: "World" },
690+
* options: {
691+
* queue: "default",
692+
* delay: "5m",
693+
* tags: ["batch", "child1"]
694+
* }
695+
* },
696+
* {
697+
* id: "child-task-2",
698+
* payload: { bar: 42 }
699+
* }
700+
* ]);
701+
*
702+
* // Type-safe result handling
703+
* for (const result of results) {
704+
* if (result.ok) {
705+
* switch (result.taskIdentifier) {
706+
* case "child-task-1":
707+
* console.log("Child task 1 output:", result.output); // string type
708+
* break;
709+
* case "child-task-2":
710+
* console.log("Child task 2 output:", result.output); // number type
711+
* break;
712+
* }
713+
* } else {
714+
* console.error("Task failed:", result.error);
715+
* }
716+
* }
717+
* }
718+
* });
719+
* ```
720+
*
721+
* @description
722+
* Each task item in the array can include:
723+
* - `id`: The task identifier (must match one of the tasks in the union type)
724+
* - `payload`: Strongly-typed payload matching the task's input type
725+
* - `options`: Optional task-specific settings including:
726+
* - `queue`: Specify a queue for the task
727+
* - `concurrencyKey`: Control concurrent execution
728+
* - `delay`: Delay before task execution
729+
* - `ttl`: Time-to-live for the task
730+
* - `tags`: Array of tags for the task
731+
* - `maxAttempts`: Maximum retry attempts
732+
* - `metadata`: Additional metadata
733+
* - `maxDuration`: Maximum execution duration
734+
*
735+
* The function provides full type safety for:
736+
* - Task IDs
737+
* - Payload types
738+
* - Return value types
739+
* - Error handling
740+
*/
611741
export async function batchTriggerByIdAndWait<TTask extends AnyTask>(
612742
items: Array<BatchByIdAndWaitItem<InferRunTypes<TTask>>>,
613743
requestOptions?: TriggerApiRequestOptions
@@ -691,6 +821,83 @@ export async function batchTriggerByIdAndWait<TTask extends AnyTask>(
691821
);
692822
}
693823

824+
/**
825+
* Triggers multiple tasks and waits for all of them to complete before returning their results.
826+
* This function must be called from within a task.run() context.
827+
*
828+
* @template TTask - Union type of tasks to be triggered, extends AnyTask
829+
*
830+
* @param {Array<BatchByIdAndWaitItem<InferRunTypes<TTask>>>} items - Array of task items to trigger
831+
* @param {TriggerApiRequestOptions} [requestOptions] - Optional API request configuration
832+
*
833+
* @returns {Promise<BatchByIdResult<TTask>>} A promise that resolves with the batch results, including
834+
* success/failure status and strongly-typed outputs for each task
835+
*
836+
* @throws {Error} If called outside of a task.run() context
837+
* @throws {Error} If no API client is configured
838+
*
839+
* @example
840+
* ```ts
841+
* import { batch, task } from "@trigger.dev/sdk/v3";
842+
*
843+
* export const parentTask = task({
844+
* id: "parent-task",
845+
* run: async (payload: string) => {
846+
* const results = await batch.triggerAndWait<typeof childTask1 | typeof childTask2>([
847+
* {
848+
* id: "child-task-1",
849+
* payload: { foo: "World" },
850+
* options: {
851+
* queue: "default",
852+
* delay: "5m",
853+
* tags: ["batch", "child1"]
854+
* }
855+
* },
856+
* {
857+
* id: "child-task-2",
858+
* payload: { bar: 42 }
859+
* }
860+
* ]);
861+
*
862+
* // Type-safe result handling
863+
* for (const result of results) {
864+
* if (result.ok) {
865+
* switch (result.taskIdentifier) {
866+
* case "child-task-1":
867+
* console.log("Child task 1 output:", result.output); // string type
868+
* break;
869+
* case "child-task-2":
870+
* console.log("Child task 2 output:", result.output); // number type
871+
* break;
872+
* }
873+
* } else {
874+
* console.error("Task failed:", result.error);
875+
* }
876+
* }
877+
* }
878+
* });
879+
* ```
880+
*
881+
* @description
882+
* Each task item in the array can include:
883+
* - `id`: The task identifier (must match one of the tasks in the union type)
884+
* - `payload`: Strongly-typed payload matching the task's input type
885+
* - `options`: Optional task-specific settings including:
886+
* - `queue`: Specify a queue for the task
887+
* - `concurrencyKey`: Control concurrent execution
888+
* - `delay`: Delay before task execution
889+
* - `ttl`: Time-to-live for the task
890+
* - `tags`: Array of tags for the task
891+
* - `maxAttempts`: Maximum retry attempts
892+
* - `metadata`: Additional metadata
893+
* - `maxDuration`: Maximum execution duration
894+
*
895+
* The function provides full type safety for:
896+
* - Task IDs
897+
* - Payload types
898+
* - Return value types
899+
* - Error handling
900+
*/
694901
export async function batchTriggerTasks<TTasks extends readonly AnyTask[]>(
695902
items: {
696903
[K in keyof TTasks]: BatchByTaskItem<TTasks[K]>;
@@ -781,6 +988,83 @@ export async function batchTriggerTasks<TTasks extends readonly AnyTask[]>(
781988
return handle as unknown as BatchTasksRunHandleFromTypes<TTasks>;
782989
}
783990

991+
/**
992+
* Triggers multiple tasks and waits for all of them to complete before returning their results.
993+
* This function must be called from within a task.run() context.
994+
*
995+
* @template TTask - Union type of tasks to be triggered, extends AnyTask
996+
*
997+
* @param {Array<BatchByIdAndWaitItem<InferRunTypes<TTask>>>} items - Array of task items to trigger
998+
* @param {TriggerApiRequestOptions} [requestOptions] - Optional API request configuration
999+
*
1000+
* @returns {Promise<BatchByIdResult<TTask>>} A promise that resolves with the batch results, including
1001+
* success/failure status and strongly-typed outputs for each task
1002+
*
1003+
* @throws {Error} If called outside of a task.run() context
1004+
* @throws {Error} If no API client is configured
1005+
*
1006+
* @example
1007+
* ```ts
1008+
* import { batch, task } from "@trigger.dev/sdk/v3";
1009+
*
1010+
* export const parentTask = task({
1011+
* id: "parent-task",
1012+
* run: async (payload: string) => {
1013+
* const results = await batch.triggerAndWait<typeof childTask1 | typeof childTask2>([
1014+
* {
1015+
* id: "child-task-1",
1016+
* payload: { foo: "World" },
1017+
* options: {
1018+
* queue: "default",
1019+
* delay: "5m",
1020+
* tags: ["batch", "child1"]
1021+
* }
1022+
* },
1023+
* {
1024+
* id: "child-task-2",
1025+
* payload: { bar: 42 }
1026+
* }
1027+
* ]);
1028+
*
1029+
* // Type-safe result handling
1030+
* for (const result of results) {
1031+
* if (result.ok) {
1032+
* switch (result.taskIdentifier) {
1033+
* case "child-task-1":
1034+
* console.log("Child task 1 output:", result.output); // string type
1035+
* break;
1036+
* case "child-task-2":
1037+
* console.log("Child task 2 output:", result.output); // number type
1038+
* break;
1039+
* }
1040+
* } else {
1041+
* console.error("Task failed:", result.error);
1042+
* }
1043+
* }
1044+
* }
1045+
* });
1046+
* ```
1047+
*
1048+
* @description
1049+
* Each task item in the array can include:
1050+
* - `id`: The task identifier (must match one of the tasks in the union type)
1051+
* - `payload`: Strongly-typed payload matching the task's input type
1052+
* - `options`: Optional task-specific settings including:
1053+
* - `queue`: Specify a queue for the task
1054+
* - `concurrencyKey`: Control concurrent execution
1055+
* - `delay`: Delay before task execution
1056+
* - `ttl`: Time-to-live for the task
1057+
* - `tags`: Array of tags for the task
1058+
* - `maxAttempts`: Maximum retry attempts
1059+
* - `metadata`: Additional metadata
1060+
* - `maxDuration`: Maximum execution duration
1061+
*
1062+
* The function provides full type safety for:
1063+
* - Task IDs
1064+
* - Payload types
1065+
* - Return value types
1066+
* - Error handling
1067+
*/
7841068
export async function batchTriggerAndWaitTasks<TTasks extends readonly AnyTask[]>(
7851069
items: {
7861070
[K in keyof TTasks]: BatchByTaskAndWaitItem<TTasks[K]>;

0 commit comments

Comments
 (0)