Docs / Language & functions

a9script authoring pack — state functions

The state functions, with their arguments and a line of real script each. Called by bare name; nothing is imported. A call marked pauses does real work outside the script: the run is saved, and continues on the next line with the result.

getState(key) — pauses

Reads a small durable value this environment stored earlier — a delta token, a watermark, a cursor. What setState put there is what comes back, across runs.

• key (string) — The key setState stored under.

Answers: The stored value, or undefined for a key that was never set. A stored null comes back as null — the two stay distinguishable, so a cleared marker and a missing one read differently.

const watermark = getState("orders-watermark");
if (watermark === undefined) { log("first sync — start from the beginning"); }

setState(key, value) — pauses

Stores one small durable value under a key — the place for delta tokens, watermarks and cursors between runs. A later set replaces the value.

• key (string) — The key to store under.
• value (any) — Any JSON value. State is for SMALL things: a value over 64 KiB as JSON is refused, naming the limit — pages of records belong in a dataset.

Answers: Nothing.

setState("orders-watermark", { since: "2026-07-01T00:00:00Z" });
log("watermark moved");