transport

Transport is the part of moving goods or people that road, rail, sea and air share: a leg with a departure and an arrival, time spent waiting at a stop, a cut-off before a departure, a schedule, and how late counts as late. This layer works the same for every mode, and every time it handles is an exact instant shown in the zone where it is read.

What these functions solve

• A leg’s running time is elapsed time, not a difference between two wall clocks. A leg that crosses a clock change lands at a different local time than the hours suggest. transitTime adds the duration to the departure, and etaAtZone shows the arrival in the reader’s zone. See guide, scenario, mistakes.
• Elapsed hours divided by the length of a day is not the days something sat. Days are counted midnight to midnight where it sat. dwellTime returns the elapsed time and the local calendar days together. See guide, Dwell Ledger, scenario.
• A move with several legs needs each hand-off in the zone where it happens. scheduleDelivery chains the legs into one ETA. crossingTime times a crossing on the clock of the place that administers it, and nextDeparture finds the first departure a connection can still make. See guide, Delivery Scheduler, Departure Board.
• A cut-off is enforced on the clock of the place that enforces it. It is stated as a time before an event. cutoffAt finds one, cutoffSchedule finds the whole stack for a sailing, and isPastCutoff and timeToCutoff test a time against it. See guide, Cut-off Stack, Cut-off Ruler.
• On time means nothing until you state how much slack counts. An estimate shown as if it were an actual hides a slip. classifyPunctuality, scheduleDeviation and punctualityRate take the tolerance from you, and bestAvailable says which class of timestamp it picked. See guide, Punctuality Board, scenario.

Start with the guide: Transport: Legs and Dwell.

calculate

• bestAvailable: Pick the best available timestamp for an event from its planned, estimated, requested and actual records, and say which class it is.
• crossingTime: Measure a crossing — a canal transit, a strait passage, a border queue — and render both ends in the zone the crossing is administered in.
• cutoffAt: Find a deadline stated as an offset before an anchor event, in the local time of the place that enforces it.
• cutoffSchedule: Compute a whole stack of cut-offs against one anchor event, earliest first.
• dwellTime: Measure how long something sat somewhere, and how many local calendar days it sat there.
• estimateDrift: Measure how far an estimate moved between its first and last revision.
• nextDeparture: Find the next departure a connection can make: the first scheduled departure at or after after plus the minimum connection time.
• punctualityRate: The share of planned/actual pairs that were on time under one tolerance.
• scheduleDelivery: Chain the legs of a multi-modal move into an end-to-end ETA with zone-local times at every handoff.
• transitTime: Add a transit duration to a departure and return the arrival, in the departure’s own zone.

compare

• classifyPunctuality: Classify an arrival as early, on time or late against the caller’s tolerance.
• isPastCutoff: Report whether a cut-off has passed.
• scheduleDeviation: Measure how far an actual time is from its plan: positive when late, negative when early.
• timeToCutoff: Measure the time left until a cut-off, negative once it has passed.

convert

• etaAtZone: Render an arrival instant as local time in the zone where it will be read.