Skip to content
Changelog

Report a bug

Keep State Between Runs

Each code stage runs in a new QuickJS VM. Variables, closures, and module state do not stay after the stage returns. There are two ways to keep data:

To keep dataUse
From one stage to the next stage of the same runThe input of next(stage, input)
From one run to a later runA checkpoint

A stage gives data to the next stage only through next(). The value must be JSON, and it must match the input schema of the destination stage. Type checks the value before the next stage runs.

An agent stage gets the input that the code stage passed to it. Its onResult code stage gets { taskInput, result, receipt }. Use agentResult(agentStage) as that stage’s input.

Do not keep data in a module variable for a later stage. The later stage runs in a new VM and does not see it.

This automation reads the last checkpoint in its entry stage, passes the time window to the next stage, and saves the new checkpoint in the last stage, after the work is done:

import {
automation,
code,
complete,
next,
recurringEventSchema,
} from "@type-dot-com/sdk/automations";
import { err } from "neverthrow";
import { z } from "zod";
const progress = z.object({ lastScheduledAt: z.string() });
const window = z.object({ from: z.string().nullable(), to: z.string() });
export default automation({
output: window,
deployment: {
subscriptions: {
hourly: {
title: "Hourly window",
description: "Report the time since the last completed run",
source: {
kind: "recurring",
schedule: { kind: "interval", everySeconds: 3600 },
},
entry: "start",
},
},
},
stages: {
start: code({
input: recurringEventSchema,
transitions: ["finish"],
run: ({ ctx, input }) => {
// An older revision can have saved a different shape.
const saved = progress.safeParse(ctx.checkpoint?.value);
return next("finish", {
from: saved.success ? saved.data.lastScheduledAt : null,
to: input.scheduledAt,
});
},
}),
finish: code({
input: window,
transitions: [],
run: ({ ctx, input }) => {
// Do the work for this window here, then record the progress.
const staged = ctx.saveCheckpoint({ lastScheduledAt: input.to });
if (staged.isErr()) return err(staged.error);
return complete(input);
},
}),
},
});
  • ctx.checkpoint is null until a stage saves a checkpoint. After that, it is { value, version }. Read the saved data from ctx.checkpoint.value.
  • ctx.saveCheckpoint(value) stages the value. If you call it more than one time in a stage, the last value wins.
  • Type saves the staged value when the stage returns next(), complete(), or blocked(). It saves it in the same step as the stage result and the transition to the next stage.
  • If a stage fails, Type discards the value that the stage staged. Checkpoints that earlier stages of the same run saved stay saved.
  • If the automation is paused, disabled, or archived while a stage runs, Type does not save that stage’s result or checkpoint.
  • Each subscription has one checkpoint. All stages of a run that a subscription started read and save that same checkpoint.
  • Each stage reads the checkpoint as it is when the stage starts. While an agent stage works, other runs of the automation can start and save a checkpoint first.
  • The checkpoint stays when you deploy new code. If you rename the subscription key, the new key has no checkpoint.
  • The value must be JSON. The checkpoint, output, visualization, and receipts of one stage must fit in 2 MiB together.

Save the checkpoint in the stage that finishes the work. If you save it in an earlier stage and a later stage fails, the next run skips the work that failed.

Checkpoints and external writes are not atomic

Section titled “Checkpoints and external writes are not atomic”

Type saves the checkpoint when the stage returns. It does not save it in the same step as a message or an API write. Plan for these cases:

  • The write succeeds, then the stage fails before it returns. The next run starts from the old checkpoint and can do the same write again.
  • The write has an unknown result because of a timeout.

To make a repeat safe, use a stable effect key, and read the destination before you write. See Write Safely.

Type already does some work for you:

  • Type does not run the same event two times for the same subscription.
  • Matchers and resources filters remove events before your code runs.
  • Recurring sources give each run its own scheduledAt time.

Do not add a checkpoint only to repeat this work. Use a checkpoint for progress that your workflow needs, for example the last item that you processed.

  • Saved data: ctx.read.data.read() and ctx.read.data.list() read data that is saved for this automation. Automation code cannot write it.
  • Sandbox files: Each run has its own sandbox. Its files are there for the later stages of the same run, and Type deletes them when the run ends.
  • Run output: complete() shows a result in run history. Later runs cannot read it.