Advanced Scheduling with the Defer public API v2

Today we're reaching GA for our public API v2, granting you direct access to Defer's Epoque Scheduler to build more advanced scheduling use cases.

Defer enabled hundreds of Node.js developers to quickly set up CRON and background tasks, without any infrastructure work. Still, many of our users reached out for more flexibility with Defer's scheduling capabilities, such as rescheduling or listing executions programmatically.

A direct access to the Scheduler

The v2 Defer public API comes with 7 new endpoints, including 5 available from the @defer/client for faster iterations:

rescheduleExecution()

Rescheduling an execution no longer requires to cancel and re-enqueue an execution.

Also, by omitting the second argument, rescheduleExecution() can be used to trigger the immediate run of the scheduled execution.

listExecutions()

Many of you leverage Defer to orchestrate workflows. Before being able to list executions, keeping track of pending or running executions required to store maps of IDs and workflow ID within your application.

listExecutions() is now a powerful way to gather executions given a set of criteria:

• listing all executions linked to a workflowID by using the metadata filter
• list all child executions with the executedBy filter

Example: listing documents processing progress within your application

The following code snippet is a Next.js Server Action used on by a Client Component to list the status of a given user's documents processing:

1// src/actions/listUserDocumentsProcessing.ts2"use server"3
4import { listExecutions } from "@defer/client"5
6export async function listUserDocumentsProcessing(7  userId: string,8  cursor?: string9) {10  const { data, pageInfo } = await listExecutions(11    {12      first: 50,13      ...(cursor ? { after: cursor } : {}),14    },15    {16      metadata: [17        {18          key: "type",19          values: ["video-transcript", "document-summarization"],20        },21        { key: "user_id", values: [userId] },22      ],23    }24  )25
26  const processings = data.map(({ createdAt, functionName, state }) => ({27    status: state,28    type:29      functionName === "videoTranscript" ? "transcript" : "summarization",30    createdAt,31  }))32
33  return {34    processings,35    hasNextPage: pageInfo.hasNextPage,36    cursor: pageInfo.endCursor,37  }38}39

getExecutionResult()

For faster performance, starting @defer/client@2.0.0, getExecution() no longer returns the execution's result. You can now use getExecutionResult() to get the full result, along with the GET /executions/{execution-id}/arguments and /executions/{execution-id}/logs for more details on an execution's run.

listExecutionAttempts()

A faster way to access an execution's retries to perform follow-up actions (ex: custom retry automation) or integrate with your application (ex: document processing user interface).

reRunExecution()

This new method, combined with listExecutionAttempts() or getExecution() enable you to implement more complex retry system by automating manual reruns.

Example: Enabling end-users to retry document processing

The above 2 methods can be leveraged to empower our documents processing end-user to re-run some transcripts and summarization work.

The UI created using listUserDocumentsProcessing() Next.js Server Action could allow user to inspect individual processing and provide the list of retries and error return by leveraging listExecutionAttempts() and getExecutionResult(). Then, again, with a Next.js Server Action, a end-user could choose to re-run a processing with the help of reRunExecution():

1// src/actions/rerunUserDocumentProcessing.ts2"use server"3
4import { reRunExecution } from "@defer/client"5
6export async function rerunUserDocumentProcessing(executionID: string) {7  await reRunExecution(executionID)8  return9}10

1// src/app/documentProcessing/[id].tsx2import { rerunUserDocumentProcessing } from "@/actions/rerunUserDocumentProcessing"3
4export default function DocumentProcessing() {5  const router = useRouter()6  const rerun = rerunUserDocumentProcessing.bind(null, router.query.id)7  // ...8  return (9    <main>10      <div>11        {/* ... */}12        <form action={rerun}>13          <button type="submit">Re-run processing</button>14        </form>15      </div>16    </main>17  )18}19

Going further

Get the full description of the 7 newly available methods and endpoints in our References documentation.