nextDeparture

Signature

nextDeparture(after: string, timetable: Headway | readonly string[], options?: NextDepartureOptions): string

Find the next departure a connection can make: the first scheduled departure at or after after plus the minimum connection time.

• This is timetable lookup, not routing: it answers “which departure does this arrival make”, the explicit departure a scheduleDelivery leg takes. Choosing among routes is the consumer’s.
• The threshold is after plus minimumConnection, in exact time. A departure exactly at the threshold is made: a zero-slack connection is feasible, as in scheduleDelivery. The connection follows transitTime’s duration rule (a day is 24 hours; years, months and weeks return "") and may not be negative.
• List form (string[]): the earliest entry at or after the threshold, in any order. Two entries at the same instant go to the first in the list. The entry is returned exactly as written, so it can be passed straight to scheduleDelivery as a leg’s departure. An empty list, or no entry late enough, returns "".
• Headway form ({ headway, from, to }): departures every headway from from, in the half-open window [from, to) — to itself is never a departure, as a GTFS frequencies.txt end_time is not. Departures are from + k × headway in exact time, so across a DST transition they keep their spacing and the wall clock shifts. The result is written the way from was written: in its zone, at its offset exactly as written, or as a Z instant. A headway that is not greater than zero, or to at or before from, returns "", as does a threshold past the last departure. This models GTFS exact_times=1 (schedule-based) service; for frequency-based service (exact_times=0) the result is a nominal slot, not a timetabled departure.
• Every moment must carry its offset — after, each entry, from and to: an instant (Z/offset), or a zoned string with its offset, whose bracketed zone must be real and agree with that offset, as transitTime reads a departure. A zoned wall time without an offset is refused, since in a repeated fall-back hour it names two departures, and a zoneless wall time names none; both return "". One invalid entry invalidates the whole list, never a partial answer.
• Returns "" on invalid input or when no departure qualifies.

Parameters

Parameter	Type	Description
after	string	ISO 8601 instant or zoned datetime string of the arrival that must connect
timetable	Headway | readonly string[]	the departures as exact moments, or a headway service { headway, from, to }

Options

options

The connection time needed before a departure can be made

Options for nextDeparture.

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

Option	Type	Default	Description
minimumConnection?	string	"PT0S"	The ISO 8601 duration the connection needs after after before a departure can be made: exact time (a day is 24 hours), not negative.

Returns

the departure (a list entry as written, or a headway departure in from’s notation; "" when none qualifies), or "" on invalid input

Types

Headway

A headway service: a departure every headway from from, up to (not including) to — the shape of a GTFS frequencies.txt row (headway_secs, start_time, end_time; GTFS Schedule Reference, https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#frequenciestxt).

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

Member	Type	Description
headway	string	The ISO 8601 duration between departures: exact time (a day is 24 hours), greater than zero.
from	string	The first departure, an exact moment: an instant (Z/offset) or a zoned string.
to	string	The end of the service window, excluded: an exact moment after from.

Examples

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

nextDeparture("2024-06-15T09:00:00Z", ["2024-06-15T08:00:00Z", "2024-06-15T09:30:00Z", "2024-06-15T11:00:00Z"]) // "2024-06-15T09:30:00Z"

aftertimetable

output

 

Source

transport/calculate/nextDeparture.ts