Added a new Context page for the docs (#1416)

* Added a new context page with task context properties * Removed code comments * Added more crosslinks
triggerdotdev · Oct 17, 2024 · d3f1094 · d3f1094
1 parent 6dc556b
commit d3f1094
Show file tree

Hide file tree

Showing 2 changed files with 194 additions and 1 deletion.
diff --git a/docs/context.mdx b/docs/context.mdx
@@ -0,0 +1,192 @@
+---
+title: "Context"
+description: "Get the context of a task run."
+---
+
+Context (`ctx`) is a way to get information about a run. 
+
+<Note>
+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.
+</Note>
+
+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
+
+<ResponseField name="task" type="object">
+  <Expandable title="properties" defaultOpen={true}>
+    <ResponseField name="exportName" type="string">
+      The exported function name of the task e.g. `myTask` if you defined it like this: `export const myTask = task(...)`.
+    </ResponseField>
+    <ResponseField name="id" type="string">
+      The ID of the task.
+    </ResponseField>
+    <ResponseField name="filePath" type="string">
+      The file path of the task.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="attempt" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">
+      The ID of the execution attempt.
+    </ResponseField>
+    <ResponseField name="number" type="number">
+      The attempt number.
+    </ResponseField>
+    <ResponseField name="startedAt" type="date">
+      The start time of the attempt.
+    </ResponseField>
+    <ResponseField name="backgroundWorkerId" type="string">
+      The ID of the background worker.
+    </ResponseField>
+    <ResponseField name="backgroundWorkerTaskId" type="string">
+      The ID of the background worker task.
+    </ResponseField>
+    <ResponseField name="status" type="string">
+      The current status of the attempt.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="run" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">
+      The ID of the task run.
+    </ResponseField>
+    <ResponseField name="context" type="any" optional>
+      The context of the task run.
+    </ResponseField>
+    <ResponseField name="tags" type="array">
+      An array of [tags](/tags) associated with the task run.
+    </ResponseField>
+    <ResponseField name="isTest" type="boolean">
+      Whether this is a [test run](/run-tests).
+    </ResponseField>
+    <ResponseField name="createdAt" type="date">
+      The creation time of the task run.
+    </ResponseField>
+    <ResponseField name="startedAt" type="date">
+      The start time of the task run.
+    </ResponseField>
+    <ResponseField name="idempotencyKey" type="string" optional>
+      An optional [idempotency key](/idempotency) for the task run.
+    </ResponseField>
+    <ResponseField name="maxAttempts" type="number" optional>
+      The [maximum number of attempts](/triggering#maxattempts) allowed for this task run.
+    </ResponseField>
+    <ResponseField name="durationMs" type="number">
+      The duration of the task run in milliseconds when the `run()` function is called. For live values use the [usage SDK functions](/run-usage).
+    </ResponseField>
+    <ResponseField name="costInCents" type="number">
+      The cost of the task run in cents when the `run()` function is called. For live values use the [usage SDK functions](/run-usage).
+    </ResponseField>
+    <ResponseField name="baseCostInCents" type="number">
+      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).
+    </ResponseField>
+    <ResponseField name="version" type="string" optional>
+      The [version](/versioning) of the task run.
+    </ResponseField>
+    <ResponseField name="maxDuration" type="number" optional>
+      The [maximum allowed duration](/runs/max-duration) for the task run.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="queue" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">
+      The ID of the queue.
+    </ResponseField>
+    <ResponseField name="name" type="string">
+      The name of the queue.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="environment" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">
+      The ID of the environment.
+    </ResponseField>
+    <ResponseField name="slug" type="string">
+      The slug of the environment.
+    </ResponseField>
+    <ResponseField name="type" type="string">
+      The type of the environment (PRODUCTION, STAGING, DEVELOPMENT, or PREVIEW).
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="organization" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">
+      The ID of the organization.
+    </ResponseField>
+    <ResponseField name="slug" type="string">
+      The slug of the organization.
+    </ResponseField>
+    <ResponseField name="name" type="string">
+      The name of the organization.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="project" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">
+      The ID of the project.
+    </ResponseField>
+    <ResponseField name="ref" type="string">
+      The reference of the project.
+    </ResponseField>
+    <ResponseField name="slug" type="string">
+      The slug of the project.
+    </ResponseField>
+    <ResponseField name="name" type="string">
+      The name of the project.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="batch" type="object" optional>
+  Optional information about the batch, if applicable.
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">
+      The ID of the batch.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="machine" type="object" optional>
+  Optional information about the machine preset used for execution.
+  <Expandable title="properties">
+    <ResponseField name="name" type="string">
+      The name of the machine preset.
+    </ResponseField>
+    <ResponseField name="cpu" type="number">
+      The CPU allocation for the machine.
+    </ResponseField>
+    <ResponseField name="memory" type="number">
+      The memory allocation for the machine.
+    </ResponseField>
+    <ResponseField name="centsPerMs" type="number">
+      The cost in cents per millisecond for this machine preset.
+    </ResponseField>
+  </Expandable>
+</ResponseField>
diff --git a/docs/mint.json b/docs/mint.json
@@ -163,7 +163,8 @@
         "runs/max-duration",
         "tags",
         "runs/metadata",
-        "run-usage"
+        "run-usage",
+        "context"
       ]
     },
     {