classifyPunctuality

Signature

classifyPunctuality(planned: string, actual: string, tolerance: PunctualityTolerance): Punctuality | null

Classify an arrival as early, on time or late against the caller’s tolerance.

• “On time” without a stated tolerance is not a measurement, and the tolerance differs by mode: a 15-minute tolerance ({ late: "PT15M" }), a 60/120-minute pair compared side by side, or a day-based one ({ late: "P1D", early: "P1D" }). GMT holds no default; the caller states it.
• The deviation is scheduleDeviation’s: actual minus planned in exact elapsed time, so a delay across a DST transition is measured in real minutes, never wall-clock ones.
• Late when the deviation is late or more: exactly 15 minutes against PT15M is late.
• Early when early is given and the deviation is -early or less: exactly 10 minutes early against PT10M is early.
• On time only strictly inside the tolerance: after -early (when given) and before late. Both boundaries belong to the outside. This convention is GMT’s own, stated here, not a reading of any rule.
• Without early, every early arrival is on time. early: undefined is the same as leaving it out; early: null is invalid.
• late: "PT0S" leaves no on-time window after the plan: an arrival exactly on the plan is late. early: "PT0S" leaves none before it: an arrival exactly on the plan is early (with a non-zero late), because both boundaries are outside the on-time window. With both at "PT0S", nothing is on time; late is checked first, so the plan itself is late.
• Tolerances are exact durations: a day is 24 hours; years, months and weeks return null, as does a negative tolerance (-PT0S is zero).
• Both times are an instant (Z/offset) or a zoned string, read as scheduleDeviation reads them: the offset fixes the instant, and an offset written to the minute that is the bracketed zone’s sub-minute offset rounded (-00:45[Africa/Monrovia], for −00:44:30) names the instant the zone gives. Otherwise the bracket is not checked.
• Returns null on invalid input.

Parameters

Parameter	Type	Description
planned	string	ISO 8601 instant or zoned datetime string of the planned time
actual	string	ISO 8601 instant or zoned datetime string of the actual time
tolerance	PunctualityTolerance	late (required) and early (optional) tolerances as ISO 8601 durations of exact time

Returns

“early”, “onTime” or “late”, or null on invalid input

Types

Punctuality

An arrival’s punctuality against a PunctualityTolerance.

import type { Punctuality } from "@northguild/gmt";

"early" | "onTime" | "late"

Related types

• PunctualityTolerance

Examples

import { classifyPunctuality } from "@northguild/gmt/transport/compare";

classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:14:59Z", { late: "PT15M" }) // "onTime"

plannedactualtolerance

output

 

Source

transport/compare/classifyPunctuality.ts