v3: Adding SDK functions for triggering tasks in a typesafe way

[ericallam]

You can now trigger tasks in a typesafe way, without importing the task file at run time:

import { tasks } from "@trigger.dev/sdk/v3";
import type { emailSequence } from "~/trigger/emails";
//     👆 **type-only** import

//app/email/route.ts
export async function POST(request: Request) {
  //get the JSON from the request
  const data = await request.json();

  // Pass the task type to `trigger()` as a generic argument, giving you full type checking
  const handle = await tasks.trigger<typeof emailSequence>("email-sequence", {
    to: data.email,
    name: data.name,
  });

  //return a success response with the handle
  return Response.json(handle);
}

You can also now use the handle returned from tasks.trigger or myTask.trigger to retrieve the output of a run in a typesafe manner:

import { tasks, runs } from "@trigger.dev/sdk/v3";
import type { emailSequence } from "~/trigger/emails";

const handle = await tasks.trigger<typeof emailSequence>("email-sequence", {
  to: data.email,
  name: data.name,
});

const run = await runs.retrieve(handle); // Pass in the handle here, not handle.id
const completedRun = await runs.poll(handle, { pollIntervalMs: 5000 )); // Poll for the run until it's completed

console.log(run.output); // run.output is typed to the return value of `emailSequence` task
console.log(completedRun.output); // completedRun.output is typed to the return value of `emailSequence` task

You can also combine tasks.trigger and run.poll into a single call, triggerAndPoll:

import { tasks, runs } from "@trigger.dev/sdk/v3";
import type { emailSequence } from "~/trigger/emails";

const completedRun = await tasks.triggerAndPoll<typeof emailSequence>("email-sequence", {
  to: data.email,
  name: data.name,
}, { pollIntervalMs: 5000 });

console.log(completedRun.output); // completedRun.output is typed to the return value of `emailSequence` task

Type helpers

This PR also exports some new handy type helpers to extract the type information embedded in a task instance:

import { TaskOutput, TaskPayload, TaskIdentifier } from "@trigger.dev/sdk/v3";
import { emailSequence } from "./trigger/emails";

type emailSequencePayload = TaskPayload<typeof emailSequence>; // retrieves the payload type of the task
type emailSequenceOutput = TaskOutput<typeof emailSequence>; // retrieves the output type of the task
type emailSequenceIdentifier = TaskIdentifier<typeof emailSequence>; // retrieves the identifier of the task
type emailSequenceHandle = TaskOutputHandle<typeof emailSequence>; // retrieves the handle of the task

[changeset-bot]

🦋 Changeset detected

Latest commit: 271eb54

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR