From da00c51a564abc3a6771760c7bf98822f7a40fc3 Mon Sep 17 00:00:00 2001 From: James Ritchie Date: Tue, 15 Oct 2024 13:58:47 +0100 Subject: [PATCH 1/3] Added a new context page with task context properties --- docs/context.mdx | 193 +++++++++++++++++++++++++ docs/mint.json | 3 +- packages/core/src/v3/schemas/common.ts | 20 +++ 3 files changed, 215 insertions(+), 1 deletion(-) create mode 100644 docs/context.mdx diff --git a/docs/context.mdx b/docs/context.mdx new file mode 100644 index 0000000000..cb9c57a953 --- /dev/null +++ b/docs/context.mdx @@ -0,0 +1,193 @@ +--- +title: "Context" +description: "Get the context of a task run." +--- + +Context (`ctx`) is a way to get information about a task. Here's an example: + +```typescript +import { task } from "@trigger.dev/sdk/v3"; + +export const parentTask = task({ + id: "parent-task", + run: async (payload: { message: string }, { ctx }) => { + + if (ctx.environment.type === "DEVELOPMENT") { + return; + } + }, +}); +``` + +## Context properties + + + Information about the task being executed. + + + The export name of the task. + + + The ID of the task. + + + The file path of the task. + + + + + + Information about the current execution attempt. + + + The ID of the execution attempt. + + + The attempt number. + + + The start time of the attempt. + + + The ID of the background worker. + + + The ID of the background worker task. + + + The current status of the attempt. + + + + + + Information about the task run. + + + The ID of the task run. + + + The context of the task run. + + + An array of tags associated with the task run. + + + Whether this is a test run. + + + The creation time of the task run. + + + The start time of the task run. + + + An optional idempotency key for the task run. + + + The maximum number of attempts allowed for this task run. + + + The duration of the task run in milliseconds. + + + The cost of the task run in cents. + + + The base cost of the task run in cents. + + + The version of the task run. + + + The maximum allowed duration for the task run. + + + + + + Information about the queue the task is running in. + + + The ID of the queue. + + + The name of the queue. + + + + + + Information about the execution environment. + + + The ID of the environment. + + + The slug of the environment. + + + The type of the environment (PRODUCTION, STAGING, DEVELOPMENT, or PREVIEW). + + + + + + Information about the organization. + + + The ID of the organization. + + + The slug of the organization. + + + The name of the organization. + + + + + + Information about the project. + + + The ID of the project. + + + The reference of the project. + + + The slug of the project. + + + The name of the project. + + + + + + Optional information about the batch, if applicable. + + + The ID of the batch. + + + + + + Optional information about the machine preset used for execution. + + + The name of the machine preset. + + + The CPU allocation for the machine. + + + The memory allocation for the machine. + + + The cost in cents per millisecond for this machine preset. + + + diff --git a/docs/mint.json b/docs/mint.json index 41f936223c..c934c6f9d1 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -163,7 +163,8 @@ "runs/max-duration", "tags", "runs/metadata", - "run-usage" + "run-usage", + "context" ] }, { diff --git a/packages/core/src/v3/schemas/common.ts b/packages/core/src/v3/schemas/common.ts index c7e2bd8f77..22c9148f75 100644 --- a/packages/core/src/v3/schemas/common.ts +++ b/packages/core/src/v3/schemas/common.ts @@ -231,20 +231,40 @@ export const TaskRunExecution = z.object({ export type TaskRunExecution = z.infer; export const TaskRunContext = z.object({ + /** Information about the task being executed. */ task: TaskRunExecutionTask, + + /** Information about the current execution attempt. */ attempt: TaskRunExecutionAttempt.omit({ backgroundWorkerId: true, backgroundWorkerTaskId: true, }), + + /** Information about the task run. */ run: TaskRun.omit({ payload: true, payloadType: true, metadata: true }), + + /** Information about the queue the task is running in. */ queue: TaskRunExecutionQueue, + + /** Information about the execution environment. */ environment: TaskRunExecutionEnvironment, + + /** Information about the organization. */ organization: TaskRunExecutionOrganization, + + /** Information about the project. */ project: TaskRunExecutionProject, + + /** Optional information about the batch, if applicable. */ batch: TaskRunExecutionBatch.optional(), + + /** Optional information about the machine preset used for execution. */ machine: MachinePreset.optional(), }); +/** + * Represents the context of a task run execution. + */ export type TaskRunContext = z.infer; export const TaskRunExecutionRetry = z.object({ From 268962a60fe99c53dc7d9608c48211f5c4801865 Mon Sep 17 00:00:00 2001 From: James Ritchie Date: Thu, 17 Oct 2024 10:54:43 +0100 Subject: [PATCH 2/3] Removed code comments --- packages/core/src/v3/schemas/common.ts | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/packages/core/src/v3/schemas/common.ts b/packages/core/src/v3/schemas/common.ts index 22c9148f75..c7e2bd8f77 100644 --- a/packages/core/src/v3/schemas/common.ts +++ b/packages/core/src/v3/schemas/common.ts @@ -231,40 +231,20 @@ export const TaskRunExecution = z.object({ export type TaskRunExecution = z.infer; export const TaskRunContext = z.object({ - /** Information about the task being executed. */ task: TaskRunExecutionTask, - - /** Information about the current execution attempt. */ attempt: TaskRunExecutionAttempt.omit({ backgroundWorkerId: true, backgroundWorkerTaskId: true, }), - - /** Information about the task run. */ run: TaskRun.omit({ payload: true, payloadType: true, metadata: true }), - - /** Information about the queue the task is running in. */ queue: TaskRunExecutionQueue, - - /** Information about the execution environment. */ environment: TaskRunExecutionEnvironment, - - /** Information about the organization. */ organization: TaskRunExecutionOrganization, - - /** Information about the project. */ project: TaskRunExecutionProject, - - /** Optional information about the batch, if applicable. */ batch: TaskRunExecutionBatch.optional(), - - /** Optional information about the machine preset used for execution. */ machine: MachinePreset.optional(), }); -/** - * Represents the context of a task run execution. - */ export type TaskRunContext = z.infer; export const TaskRunExecutionRetry = z.object({ From 2269d0b4747746b89c2ab303f4de11a36b0a9f98 Mon Sep 17 00:00:00 2001 From: James Ritchie Date: Thu, 17 Oct 2024 11:14:21 +0100 Subject: [PATCH 3/3] Added more crosslinks --- docs/context.mdx | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/docs/context.mdx b/docs/context.mdx index cb9c57a953..618e80a74d 100644 --- a/docs/context.mdx +++ b/docs/context.mdx @@ -3,7 +3,13 @@ title: "Context" description: "Get the context of a task run." --- -Context (`ctx`) is a way to get information about a task. Here's an example: +Context (`ctx`) is a way to get information about a run. + + +The context object does not change whilst your code is executing. This means values like `ctx.run.durationMs` will be fixed at the moment the `run()` function is called. + + +Here's an example: ```typescript import { task } from "@trigger.dev/sdk/v3"; @@ -22,10 +28,9 @@ export const parentTask = task({ ## Context properties - Information about the task being executed. - + - The export name of the task. + The exported function name of the task e.g. `myTask` if you defined it like this: `export const myTask = task(...)`. The ID of the task. @@ -37,7 +42,6 @@ export const parentTask = task({ - Information about the current execution attempt. The ID of the execution attempt. @@ -61,7 +65,6 @@ export const parentTask = task({ - Information about the task run. The ID of the task run. @@ -70,10 +73,10 @@ export const parentTask = task({ The context of the task run. - An array of tags associated with the task run. + An array of [tags](/tags) associated with the task run. - Whether this is a test run. + Whether this is a [test run](/run-tests). The creation time of the task run. @@ -82,31 +85,30 @@ export const parentTask = task({ The start time of the task run. - An optional idempotency key for the task run. + An optional [idempotency key](/idempotency) for the task run. - The maximum number of attempts allowed for this task run. + The [maximum number of attempts](/triggering#maxattempts) allowed for this task run. - The duration of the task run in milliseconds. + The duration of the task run in milliseconds when the `run()` function is called. For live values use the [usage SDK functions](/run-usage). - The cost of the task run in cents. + The cost of the task run in cents when the `run()` function is called. For live values use the [usage SDK functions](/run-usage). - The base cost of the task run in cents. + The base cost of the task run in cents when the `run()` function is called. For live values use the [usage SDK functions](/run-usage). - The version of the task run. + The [version](/versioning) of the task run. - The maximum allowed duration for the task run. + The [maximum allowed duration](/runs/max-duration) for the task run. - Information about the queue the task is running in. The ID of the queue. @@ -118,7 +120,6 @@ export const parentTask = task({ - Information about the execution environment. The ID of the environment. @@ -133,7 +134,6 @@ export const parentTask = task({ - Information about the organization. The ID of the organization. @@ -148,7 +148,6 @@ export const parentTask = task({ - Information about the project. The ID of the project.