Skip to main content

Checkpoint

A checkpoint is a framework-provided function that records progress through multi-step operations. Checkpoints serve different purposes depending on the execution context:

  • In tests: Checkpoints drive assertions and test reporting, capturing intermediate states for verification.
  • In debug/staging: Checkpoints emit structured log entries that feed distributed tracing and observability systems.
  • In production: Checkpoints are disabled via optional chaining (?.), resulting in zero runtime overhead.

One call, three behaviours — the context decides which:

Motivation​

Long-running handlers and test chains share a common need: visibility into what happened at each stage of a multi-step operation. Without checkpoints, debugging a failed handler requires sifting through logs, and debugging a failed test requires adding temporary assertions.

Checkpoints provide a single mechanism that serves both needs — tracing for production and assertions for tests — without duplicating logic.

Usage​

In Handlers​

Handlers access checkpoint through the $meta parameter. Since checkpoint may be undefined in production, always use optional chaining:

import {handler, type IMeta} from '@feasibleone/blong';

export default handler(
({handler: {accountGet, transferCreate}}) =>
async function paymentTransferExecute(
{accountId, amount}: {accountId: string; amount: number},
$meta: IMeta,
) {
const account = await accountGet({id: accountId}, $meta);
$meta.checkpoint?.('account-loaded', {accountId: account.id, balance: account.balance});

if (account.balance < amount) throw new Error('Insufficient funds');
$meta.checkpoint?.('balance-verified', {available: account.balance, requested: amount});

const transfer = await transferCreate({amount, from: account.id}, $meta);
$meta.checkpoint?.('transfer-created', {transferId: transfer.id});

return {transferId: transfer.id, state: transfer.state};
},
);

In Tests​

Tests can assert on checkpoints captured during handler execution:

import {handler, type IAssert, type IMeta, type IProgressPoint} from '@feasibleone/blong';

export default handler(({handler: {paymentTransferExecute}}) => ({
// No 'name' parameter — context name is injected into $meta by the framework proxy
testPaymentCheckpoints: (params: Record<string, unknown>, $meta: IMeta) => [
async function executeAndVerify(assert: IAssert, {$meta}: {$meta: IMeta}) {
const result = await paymentTransferExecute({accountId: 'acc-1', amount: 100}, $meta);
assert.ok(result.transferId, 'Transfer created');

// Verify the checkpoints recorded during execution — the list also holds any branch
// the handler took, which is why the entries are filtered by kind
const points = ($meta.progress ?? []).filter(
(entry): entry is IProgressPoint => entry.kind === 'point',
);
assert.equal(points.length, 3);
assert.equal(points[0].name, 'account-loaded');
assert.equal(points[1].name, 'balance-verified');
assert.equal(points[2].name, 'transfer-created');
},
],
}));

What a point records​

A point says which of the two shapes it is, so one list can hold it and a branch together:

  • kind: 'point' — This entry is a checkpoint. A branch is kind: 'region'.
  • name — A descriptive string identifying the checkpoint (e.g., 'account-loaded', 'transfer-created').
  • data — An optional object with relevant state at that point.
  • timestamp — Automatically added by the framework.
  • regions — The branches this point was announced inside, outermost first. A report groups by it, and it travels with the point: an entry that arrived from another process over a call still says which branches it sat in, even though that process is the one that numbered them.

Modes​

The mode is checkpointMode in the registry config — no handler code changes.

Environment$meta.checkpoint$meta.decideWhat is recorded
Productionundefinedalwaysthe branch rationale only — worth tracing even in production
Debugrecording functionalwayspoints and branches, kept in $meta and emitted with the log
Testrecording functionalwaysthe same; the registry also attaches assert, so a test can assert on the sequence

checkpoint is absent in production rather than a no-op function, which is what makes the ?. call free; lib.checkpoint follows the same rule for code that has no $meta. A branch is the one thing that cannot be optional: it selects, so a missing helper would skip the work rather than cost a note.

One thing the table's "plus assert" is often misread as: a checkpoint does not take an assertion. The optional assertion is a separate handle the registry attaches under the same mode (assert: recording ? nodeAssert : undefined), so a handler written assert?.ok(...) does nothing in production — that is what makes one handler usable as both production code and a test.

Points and Branches​

A checkpoint is one shape of a progress point; a decide branch is the other. Both are moments in the logic that explain the shape a run took, both are recorded in one place, and both are drawn on the sequence diagram the log builds — a point as a note beside the participant that reported it, a branch as an alt block around the calls made inside it (lukaot). The test report draws the same two shapes from the same list, each as what it is: a branch becomes a group — a sub-test in tap, a step in Allure — holding the points taken inside it, and a point is printed beside the step that announced it. In tap that is a comment, because a moment a step passed through is not a test of its own:

# total-calculated: total=200, itemCount=2
# Subtest: discount-tier = standard
# discount-applied: discount=0.1, discountedTotal=180

The data is printed only while it stays small enough to read: the five shortest properties, values longer than a line left out, and the count of what was left out said, so the line never reads as the whole story. Allure keeps every point as a step, so nothing is lost where a report has the room.

What separates them is what each may cost: a point may be dropped, because nothing else depends on it; a branch may not, because it is the control flow.

The block names every candidate the code declared: a candidate the decision never reached — evaluation stops at the branch it takes — is drawn and labelled, so a reader sees both the alternative that was weighed and refused and the one that was never tried. The record's own rationale keeps the same list, in evaluation order, so it can be replayed without reading source (R11). A block is also ordered so that it renders: mermaid refuses a section with nothing in it when it is the last before end, and the whole block stops drawing. So the arms with nothing to draw come first and the one carrying the calls last — the arm that ran, drawn under the alternatives it weighed. Only the order changes, and the labels are what name the candidates; a block whose arms are all empty says "nothing observed yet" on its last one. Both belong to the handler that announces them, which the diagram has to show, and a handler's work crosses process boundaries as naturally as its call does. A call's records are written by the framework around the handler — before it starts and after it returns — so nothing is recorded at the moment a handler speaks: what it announced is collected once it is done and written on its answer. The participant a note is drawn over is therefore the participant that answered, and the collection is installed before the handler is run, so that what it announces after its first wait is collected too (lukaot has the whole of that rule).

$meta.checkpoint?.('total-calculated', {total, itemCount});
const fee = $meta.decide('fee-tier', {total}, [
{name: 'waived', when: values => (values.total as number) > 100, run: () => 0},
{name: 'standard', when: () => true, run: () => total * 0.01},
]); // the chosen branch's result, or `undefined` when none matched

Relationship to Handlers and Tests​

Checkpoints are a key element of the unified handler-test concept. They blur the line between handlers and tests:

  • A handler with checkpoints is already instrumented for testing — tests can call it and verify the checkpoint sequence.
  • A test with checkpoints is already instrumented for production — when the test graduates to a handler, the checkpoints become observability points.

See the handler-test POC suite for working examples.