Wrap metadata with type safetey

Author: ericallam

README.md

@@ -32,6 +32,7 @@ npx trigger.dev@latest dev
 ### Relevant Files
 
 - `src/trigger/tasks.ts`: Where our `generateFunctionDocs` background task is defined.
+- `src/lib/metadataStore.ts`: Wraps the run metadata with type-safe access.
 - `src/app/page.tsx`: The main page that invokes the server action function that triggers the background task.
 - `src/app/actions.ts`: The server action function that triggers the background task and redirects to `/runs/[id]`.
 - `src/app/runs/[id]/page.tsx`: The page that displays the status of the background task and the result when it's done.

src/app/hooks/useGenerateFunctionDocs.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { ExampleMetadataSchema } from "@/lib/schemas";
+import { parseStatus } from "@/lib/metadataStore";
 import { type generateFunctionDocs } from "@/trigger/tasks";
 import { useRealtimeRun } from "@trigger.dev/react-hooks";
 
@@ -11,6 +11,15 @@ interface GenerateFunctioDocsStatus {
   output?: string;
 }
 
+/**
+ * Hook that subscribes to the generateFunctionDocs task and returns the status and output of the task.
+ *
+ * Uses the `useRealtimeRun` hook to subscribe to the task.
+ *
+ * See more about the `useRealtimeRun` hook in the [Trigger docs](https://trigger.dev/docs/frontend/react-hooks#userealtimerun).
+ *
+ * @param id the run id of the generateFunctionDocs task
+ */
 export function useGenerateFunctionDocs(id: string) {
   const { run, error } = useRealtimeRun<typeof generateFunctionDocs>(id);
 
@@ -23,9 +32,9 @@ export function useGenerateFunctionDocs(id: string) {
 
   // Parse metadata if available
   if (run?.metadata) {
-    const metadata = ExampleMetadataSchema.parse(run.metadata);
-    status.progress = metadata.status.progress;
-    status.label = metadata.status.label;
+    const { progress, label } = parseStatus(run.metadata);
+    status.progress = progress;
+    status.label = label;
   }
 
   return {

src/lib/metadataStore.ts

@@ -0,0 +1,35 @@
+import { metadata } from "@trigger.dev/sdk/v3";
+import { z } from "zod";
+
+const GenerateFunctionDocsStatus = z.object({
+  progress: z.number(),
+  label: z.string(),
+});
+
+type GenerateFunctionDocsStatus = z.infer<typeof GenerateFunctionDocsStatus>;
+
+const GenerateFunctionDocsMetadata = z.object({
+  status: GenerateFunctionDocsStatus,
+});
+
+type GenerateFunctionDocsMetadata = z.infer<
+  typeof GenerateFunctionDocsMetadata
+>;
+
+/**
+ * Update the status of the generate function docs task. Wraps the `metadata.set` method.
+ */
+export function updateStatus(status: GenerateFunctionDocsStatus) {
+  // `metadata.set` can be used to update the status of the task
+  // as long as `updateStatus` is called within the task's `run` function.
+  metadata.set("status", status);
+}
+
+/**
+ * Parse the status from the metadata.
+ *
+ * Used by the `useGenerateFunctionDocs` hook to parse the status
+ */
+export function parseStatus(data: unknown): GenerateFunctionDocsStatus {
+  return GenerateFunctionDocsMetadata.parse(data).status;
+}

src/trigger/tasks.ts

@@ -2,6 +2,7 @@ import { metadata, schemaTask } from "@trigger.dev/sdk/v3";
 import { setTimeout } from "timers/promises";
 import { OpenAI } from "openai";
 import { z } from "zod";
+import { updateStatus } from "@/lib/metadataStore";
 
 const openai = new OpenAI({
   apiKey: process.env.OPENAI_API_KEY,
@@ -15,15 +16,21 @@ export const generateFunctionDocs = schemaTask({
   }),
   maxDuration: 300, // 5 minutes
   run: async (payload, { ctx }) => {
-    metadata.set("status", { progress: 0, label: "Initializing..." });
+    updateStatus({ progress: 0, label: "Initializing..." });
 
     await setTimeout(1000);
 
-    metadata.set("status", { progress: 19, label: "Processing data..." });
+    updateStatus({
+      progress: 19,
+      label: "Processing data...",
+    });
 
     await setTimeout(1000);
 
-    metadata.set("status", { progress: 45, label: "Analyzing results..." });
+    updateStatus({
+      progress: 45,
+      label: "Analyzing results...",
+    });
 
     await setTimeout(1000);
 
@@ -34,7 +41,7 @@ export const generateFunctionDocs = schemaTask({
       model: "chatgpt-4o-latest",
     });
 
-    metadata.set("status", { progress: 85, label: "Finalizing..." });
+    updateStatus({ progress: 85, label: "Finalizing..." });
 
     await setTimeout(1000);