etaAtZone

Signature

etaAtZone(arrivalUtc: string, targetZone: string): string

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

• Schedules are computed in UTC and displayed where the cargo lands. The zone is the caller’s fact: GMT does not resolve a port, airport, terminal or station code to a timezone, and takes an IANA identifier instead (see the parked registries note in the epic’s painpoints).
• arrivalUtc is any instant isValidInstant accepts — Z, an offset, or an offset with a bracketed zone. Only the instant is read; a bracketed zone in the input is not the zone the result is rendered in, targetZone is.
• The offset fixes the instant; a bracketed zone only resolves a rounded one. 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, as Temporal.ZonedDateTime.from reads it, so rendering this function’s own result again gives the same moment, except a wall time repeated inside a sub-minute offset change, which reads as its first pass (see isValidInstant). A zone that does not exist, or that disagrees with the offset, is not checked and changes nothing.
• No disambiguation arises. The input is a moment, and a moment has exactly one wall time in any zone, so the disambiguation vocabulary of resolveLocal does not apply here. On a fall-back night two moments an hour apart print the same wall time with different offsets, and the offset in the result is what tells them apart; on a spring-forward night the skipped hour simply never appears. That is also why the result carries its offset and zone rather than a bare wall time.
• Returns a zoned ISO 8601 string, Temporal.ZonedDateTime.prototype.toString()’s form: wall time, offset, bracketed zone.
• targetZone is whatever isValidTimeZone accepts, which is what Temporal accepts: an IANA identifier, or a fixed offset such as "+09:00", which renders with the offset as its zone. A fixed offset is a legitimate rendering choice for a ship’s log (MAR-18); it is not a place.
• Returns "" when the instant or the zone is invalid.
• An offset with seconds (-00:44:30) returns "". A written zone cannot carry seconds (RFC 9557 §4.1), so the result could not name it. Pass the IANA name, or call fromOffsetInstant({ instant, offset }) for the local time with its full offset and no bracket.

Parameters

Parameter	Type	Description
arrivalUtc	string	ISO 8601 instant string of the arrival
targetZone	string	IANA name or a UTC offset to the minute (what isValidTimeZone accepts), for the place the arrival is read in

Returns

zoned ISO 8601 string of the local arrival, or "" on invalid input

Examples

import { etaAtZone } from "@northguild/gmt/transport/convert";

etaAtZone("2024-06-15T12:30:00Z", "Asia/Tokyo") // "2024-06-15T21:30:00+09:00[Asia/Tokyo]"

arrivalUtctargetZone

output

 

Source

transport/convert/etaAtZone.ts