monitor.heartbeat-check

A heartbeat's state as a check status for a status page: up, late as degraded, down as down, new as nothing yet.

1.0.0 · published 2026-10-03 by charlie · Anterra

Pinned by 8 tests, run in TypeScript, Python and Rust.

What it does

A heartbeat (a cron job that pings the monitor on a schedule, judged by `monitor.heartbeat`) as one check behind a status page component, so the job can sit on the same page as the HTTP targets and feed `monitor.component-state`, `monitor.incidents` and `monitor.uptime`.

| heartbeat state | check status | why | | --- | --- | --- | | `up` | `up` | pinged within its period | | `late` | `degraded` | past due but inside the grace time: something is slow, nothing has failed yet | | `down` | `down` | past the grace time: the job has stopped | | `new` | null | it has never pinged, so there is nothing to report |

For example

heartbeatCheck(up) → up a heartbeat pinging on time is up
heartbeatCheck(late) → degraded a late heartbeat is degraded, not down: it is still inside its grace time
heartbeatCheck(down) → down a heartbeat past its grace time is down

The function

The same function in TypeScript, Python and Rust, pinned by the same tests. Pick your language; the choice follows you around the registry.

export function heartbeatCheck(state: HeartbeatState): CheckStatus | null

state	HeartbeatState	where the heartbeat stands, from monitor.heartbeat
returns	CheckStatus?	null for a heartbeat that has never pinged: there is nothing to report yet

Your code names it in one line, in the file that uses it

import { heartbeatCheck } from "#fune/monitor.heartbeat-check@^1";

impl/typescript.ts · 17 lines · open · raw

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { type CheckStatus } from "./monitor_check_status.ts";  ← from monitor.check-status ^1.0.0 · built alongside by fune
import { type HeartbeatState } from "./monitor_heartbeat.ts";  ← from monitor.heartbeat ^1.0.0 · built alongside by fune

const STATUS: Readonly<Record<string, CheckStatus>> = { up: "up", late: "degraded", down: "down" };

/**
 * A heartbeat as one check behind a status page component. Late is
 * degraded, not down: the job may still ping within its grace time, which is
 * what the grace time is for. A new heartbeat has proved nothing either way,
 * so it is null rather than a guess.
 */
export function heartbeatCheck(state: HeartbeatState): CheckStatus | null {
  if (state === "new") return null;
  const status = Object.prototype.hasOwnProperty.call(STATUS, state) ? STATUS[state] : undefined;
  if (status === undefined) throw new RangeError(`unknown heartbeat state: ${String(state)}`);
  return status;
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add monitor.heartbeat-check

Download for TypeScript monitor.heartbeat-check-1.0.0-typescript.fune · 4,921 bytes sha256 6dde2997440b4777371067211386b79adac0e1a2767248c3c1794b8e54a8d0ac

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./monitor.heartbeat-check-1.0.0-typescript.fune, or fetch it from a terminal with fune pull monitor.heartbeat-check@1.0.0:typescript.

The whole function, every language, is one file too: monitor.heartbeat-check-1.0.0.fune, 6,589 bytes, sha256 ba92e30f23d19bb08606233144125bb805f847790f3973b11d15a465ee2381f9. It installs into a project of any language.

Customise it in your app

The seams this capability offers. Put a marker directly above a function of your own and fune build wires it into the built code; the package on the registry is not changed, the built file’s header lists it under CUSTOMISED, and fune hooks lists every hook in the project. How hooks work.

before — your function gets the arguments and returns them, changed or not, or throws to refuse the call.

// fune: before monitor.heartbeat-check

after — your function gets the result and the arguments, and returns the final result.

// fune: after monitor.heartbeat-check

replace — inside this capability’s code only, calls to a dependency go to your function, with the same signature. Other capabilities that use it are unaffected; write in * to replace it everywhere.

// fune: replace monitor.check-status in monitor.heartbeat-check
// fune: replace monitor.heartbeat in monitor.heartbeat-check

step — your function runs at a numbered point inside the function’s body, receives the in-scope values it names as parameters, and may return replacements. List the points with fune show monitor.heartbeat-check --steps.

// fune: step monitor.heartbeat-check after <n|label>

Tests

A version published now needs at least 8 tests for every function, and one that expects the error for each function that throws; the registry refuses it otherwise. fune verify --all runs each case in TypeScript, Python and Rust, and a project runs them again with fune verify. This page lists the cases; it does not run them. The exact JSON is vectors.json.

Case	Arguments		Expected
a heartbeat pinging on time is up	up	→	up
a late heartbeat is degraded, not down: it is still inside its grace time	late	→	degraded
a heartbeat past its grace time is down	down	→	down
a heartbeat that has never pinged has nothing to report	new	→	—
an unknown state is an error	missing	→	error: unknown heartbeat state: missing
states are case-sensitive	Up	→	error: unknown heartbeat state: Up
an empty state is an error		→	error: unknown heartbeat state:
a check status is not a heartbeat state: degraded is refused	degraded	→	error: unknown heartbeat state: degraded

More from the author

## Why this shape

- **Late is not down.** The grace time exists because jobs run long; calling a late job down would page for exactly the case the grace time was set to absorb. healthchecks.io, which named these states, only alerts on down. - **New is null, not up.** A heartbeat that has never pinged has proved nothing. Calling it up would show a never-deployed job as healthy on the status page; calling it down would page for a job that is not due yet. The caller leaves it out of the component's checks (and shows "awaiting first ping") until the first ping arrives.

## Errors

- `unknown heartbeat state: X`, for anything but `new`, `up`, `late` and `down` (case-sensitive; a `CheckStatus` such as `degraded` is refused).

## Sources

- healthchecks.io, "Configuring checks: period and grace time" (new, up, late, down; notifications only when a check goes down): https://healthchecks.io/docs/configuring_checks/

Files

Path	Bytes
README.md	1,600
impl/python.py	719
impl/rust.rs	845
impl/typescript.ts	820
vectors.json	877