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 data | Use |
|---|---|
| From one stage to the next stage of the same run | The input of next(stage, input) |
| From one run to a later run | A checkpoint |
Pass data between stages
Section titled “Pass data between stages”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.
Read and save a checkpoint
Section titled “Read and save a checkpoint”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); }, }), },});How checkpoints work
Section titled “How checkpoints work”ctx.checkpointisnulluntil a stage saves a checkpoint. After that, it is{ value, version }. Read the saved data fromctx.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(), orblocked(). 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.
When you do not need a checkpoint
Section titled “When you do not need a checkpoint”Type already does some work for you:
- Type does not run the same event two times for the same subscription.
- Matchers and
resourcesfilters remove events before your code runs. - Recurring sources give each run its own
scheduledAttime.
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.
Other state
Section titled “Other state”- Saved data:
ctx.read.data.read()andctx.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.