A timestamp can be syntactically readable and still be the wrong input for a dashboard decision. A number labelled “five minutes old” hides several assumptions: which clock produced it, which timezone the string carries, and what the interface means by old.
I built Clock Contract Lab as a small, dependency-free JavaScript example. It uses a fixed synthetic reference clock and ten visible boundary fixtures. You can change the timestamp and review window without connecting a live feed or submitting data.
The live demo’s automatically generated CodePen preview. The reference clock and fixtures are synthetic.
Three clocks that should not collapse into one
A useful ingestion record can distinguish:
- Event time: when the source says the observation occurred.
- Receipt time: when your system received it.
- Review time: when the interface evaluates its age.
This demo evaluates event time against one fixed review clock. It does not measure delivery latency because it has no receipt event. That boundary matters: a timestamp-age badge should not claim to diagnose network delay.
A trading session is a fourth, different question. An observation from a closed exchange may be the latest available observation while being outside a short elapsed-time window. Conversely, a recent timestamp cannot prove a feed is real-time or that the underlying market is liquid.
Define the accepted format before calling a parser
The lab deliberately accepts a narrow format: a complete date and time, seconds, optional one-to-three fractional digits, and either Z or an explicit numeric UTC offset.
It rejects a local-looking value such as:
2026-10-11T11:55:00
The interface does not silently assign the reader’s timezone. MDN’s Date.parse reference documents the local-time interpretation of a date-and-time string without a timezone, as well as implementation-dependent behavior for other formats. This is why accepting a string and defining a contract are separate tasks.
The chosen format is a demo contract, not a complete implementation of every ISO 8601 or RFC 3339 variation. Leap-second values are outside its accepted range.
Validate calendar components separately
A matching regular expression does not establish that February has thirty days. The example checks the month’s actual day limit and applies the Gregorian leap-year rule before using Date.parse.
This separates two failures:
- The value does not follow the accepted text format.
- The components follow the format but do not describe an accepted calendar or clock value.
Both become INVALID, with a reason. An empty input becomes UNKNOWN. It is not replaced with the current time, because that would turn missing evidence into apparently recent evidence.
Normalize the instant, then apply policy
These two fixtures describe the same instant:
2026-10-11T11:55:00Z
2026-10-11T14:55:00+03:00
Both normalize to 11:55 UTC. Against the demo’s 12:00 UTC reference clock, both are five minutes old.
The review window is a separate input. A fifteen-minute window is an example chosen for the interface, not an exchange-specific recommendation or a default from a commercial script.
const ageMinutes = (reviewTimeMs - eventTimeMs) / 60000;
The result has five possible states:
| State | What this example establishes |
|---|---|
| UNKNOWN | No timestamp was provided |
| INVALID | Timestamp or policy fails the demo contract |
| CHECK CLOCK | Event appears later than the review clock |
| WITHIN WINDOW | Non-negative age is at or below the chosen window |
| OUTSIDE WINDOW | Age exceeds the chosen window |
A future timestamp is not clamped to zero and painted as recent. The demo exposes the inconsistency. A production application would need a documented clock-skew policy and suitable telemetry; this example does not supply them.
Boundary checks belong near the interface
The visible “Run boundary checks” button evaluates UTC input, offset equivalence, an older observation, the inclusive threshold, empty input, an impossible date, a missing timezone, a future event, a non-leap February date and an invalid policy.
All ten fixtures passed in the browser during publication checks. That is evidence for this small example, not proof of production ingestion reliability or performance under load. The HTML, CSS and JavaScript are available in the public Pen for inspection.
The page uses textContent for results and aria-live for status updates. It implements no analytics, storage, form submission or external data fetch. CodePen’s own hosting behavior is separate from the demo code.
What a green-looking state must not imply
WITHIN WINDOW does not mean the exchange is open, the feed has no entitlement delay, a symbol is qualified, or a trade is suitable. Displaying the reason beside the state makes that narrower meaning visible.
For market-research context, I maintain a global-stock screening guide about currencies and sessions and a guide to high scores that remain blocked by quality checks.
I also build Crypto Setup Planner at AGProLabs. Those are my own project links. This lab is a standalone teaching example; it is not the script’s source code, webhook receiver or alert integration. It provides no trading entries, execution or financial advice.
Written and coded with AI assistance, with the described fixtures checked through the visible browser interface.
Top comments (0)