bestAvailable

Legs, dwell, cut-offs and punctuality, shared by road, rail, sea and air.

Signature

bestAvailable(events: TimestampEvent[]): ClassifiedTimestamp | null

Pick the best available timestamp for an event from its planned, estimated, requested and actual records, and say which class it is.

One field often carries four meanings — DCSA’s eventClassifierCode vocabulary: PLN (planned), EST (estimated), REQ (requested) and ACT (actual). A dashboard that shows the latest-recorded value puts an estimate in the actual column the moment a late feed arrives. This returns the class with the value, so the consumer can label it.
An ACT wins whenever there is one, whatever was recorded after it: an estimate recorded after the arrival is still only an estimate.
Otherwise PLN, then REQ, then EST. This ACT > PLN > REQ > EST selection is GMT’s own convention. DCSA’s Port Call standard negotiates some port call services — a berth, pilotage, towage — through an estimated, then requested, then planned timestamp, followed by an actual; this order reads that pattern from its most settled end. DCSA defines the classes and the pattern, not a rule for choosing among them. A plan is agreed; a request is asked for; an estimate is only predicted. So an EST or REQ never replaces a PLN, however much later it was recorded, and there is never an EST when a REQ exists. The order is fixed, not configurable.
Within the chosen class, the newest-recorded event wins (latest recordedAt), so a revised plan or a corrected actual replaces the earlier one. Two records at the same instant go to the later one in the array.
at is echoed exactly as written. at and recordedAt are instants (Z/offset) or zoned strings, compared as instants and 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 for an empty list, or when any event is invalid — a classifier other than exactly PLN, EST, REQ or ACT included.

Parameters

Parameter	Type	Description
`events`	`TimestampEvent[]`	the event’s timestamp records, in any order

Returns

the chosen at and its class (null for an empty list), or null on invalid input

Types

ClassifiedTimestamp

What bestAvailable returns: the chosen timestamp and the class it carries.

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

Member	Type	Description
`at`	`string`	The chosen event’s `at`, exactly as it was written.
`classifier`	`"PLN"` \| `"EST"` \| `"REQ"` \| `"ACT"` (`TimestampClass`)	The class of the chosen event, so the value is never shown as something it is not.

Examples

import { bestAvailable } from "@northguild/gmt/transport/calculate";

bestAvailable([{ classifier: "ACT", at: "2024-06-15T12:52:00Z", recordedAt: "2024-06-15T12:53:00Z" }, { classifier: "EST", at: "2024-06-15T13:05:00Z", recordedAt: "2024-06-15T14:00:00Z" }]) // { at: "2024-06-15T12:52:00Z", classifier: "ACT" } (an estimate recorded after the actual never replaces it)

Source

transport/calculate/bestAvailable.ts