Rail mistakes
The Rail layer reads and writes the times in a GTFS feed. A stop time can run past 24:00:00
and stay with its service day, so the mistakes around it are the ones a clock-time habit makes:
folding the hour into a day, asking a clock-time check whether the value is valid, writing the
seconds alone, trimming a dirty value, and adding the seconds to local midnight. Every
output shown here is what the function returns.
Folding past midnight
Section titled “Folding past midnight”Taking the hour modulo 24
A stop time of 25:35:00 is 1 day past the service day, 01:35:00, and still part of the service day the trip began on. Taking the hour modulo 24 gives 01:35:00, which is a time at the start of a service day. The stop loses its day and sorts before the stops it followed. parseGtfsTime keeps the days past the service day in a number of their own.
Wrong
const [hours, minutes, seconds] = "25:35:00".split(":");
[String(Number(hours) % 24).padStart(2, "0"), minutes, seconds].join(":");// "01:35:00" — the day is goneRight
import { parseGtfsTime } from "@northguild/gmt/rail/parse";
parseGtfsTime("25:35:00");// { seconds: 5700, dayOverflow: 1 }A clock-time check
Section titled “A clock-time check”Checking a stop time as a clock time
A clock has no 25th hour, so a check made for clock times refuses 25:35:00, and an import that trusts it drops a valid stop. isValidGtfsTime asks the GTFS parser, which reads hours up to 999.
Wrong
import { isValidTime } from "@northguild/gmt/plain/validate";
isValidTime("25:35:00");// false — a valid stop time is refusedRight
import { isValidGtfsTime } from "@northguild/gmt/rail/validate";
isValidGtfsTime("25:35:00");// trueisValidGtfsTime("25:60:00");// false (minute 60)Writing it back
Section titled “Writing it back”Writing the seconds alone
Writing back only the seconds, or the hour in one digit, changes the value. The first drops the days past the service day, and the second is a form the rest of a feed does not use. formatGtfsTime writes the record in full, with at least two hour digits.
Wrong
import { parseGtfsTime } from "@northguild/gmt/rail/parse";
const { seconds } = parseGtfsTime("25:35:00");
const hour = Math.floor(seconds / 3600);const minute = Math.floor(seconds / 60) % 60;hour + ":" + String(minute).padStart(2, "0") + ":00";// "1:35:00" — one hour digit, and the day is goneRight
import { parseGtfsTime } from "@northguild/gmt/rail/parse";import { formatGtfsTime } from "@northguild/gmt/rail/format";
const late = parseGtfsTime("25:35:00");if (late !== null) formatGtfsTime(late);// "25:35:00"const early = parseGtfsTime("8:05:00");if (early !== null) formatGtfsTime(early);// "08:05:00"Spaces and the byte-order mark
Section titled “Spaces and the byte-order mark”Trimming inside the time reader
GTFS asks that extra spaces be removed from a feed, and a value with a space in it is a dirty feed. A reader that trims quietly reads it, and the next tool in the chain gets the same dirty file. parseGtfsTime refuses the value, so the CSV reader that splits the row is the place to clean it.
Wrong
const cell = " 25:35:00";
cell.trim();// "25:35:00" — read, and the dirty feed goes on unnoticedRight
import { parseGtfsTime } from "@northguild/gmt/rail/parse";
parseGtfsTime(" 25:35:00");// nullparseGtfsTime("25:35:00");// { seconds: 5700, dayOverflow: 1 }Seconds since midnight
Section titled “Seconds since midnight”Adding the seconds to local midnight
The days and seconds of a GTFS time are measured from noon minus 12 hours of the service day, which is midnight except on a day the clocks change. Adding them to local midnight is out on that day by the size of the change, an hour in most zones. The record is what to keep; an instant needs the agency's zone and the service date, and gtfsToInstant takes both.
Wrong
import { parseGtfsTime } from "@northguild/gmt/rail/parse";
const { dayOverflow, seconds } = parseGtfsTime("25:35:00");
const midnight = new Date("2026-03-29T00:00:00"); // local midnight of the service day
new Date(midnight.getTime() + (dayOverflow * 86400 + seconds) * 1000);// GTFS measures from noon minus 12 hours, so on a day the clocks change// this is out by the size of the change, an hour in BerlinRight
import { gtfsToInstant } from "@northguild/gmt/rail/convert";
gtfsToInstant("20260329", "25:35:00", "Europe/Berlin");// "2026-03-29T23:35:00Z"The stop’s own zone
Section titled “The stop’s own zone”Reading a stop's time in its own zone
The reference says the times in stop_times.txt are in the timezone specified by agency.agency_timezone, not stop_timezone. A stop in another zone still has its time written in the agency's. The same 08:00:00 on 29 March 2026 is 06:00:00Z in Berlin and 07:00:00Z in London, so the wrong zone moves the stop by an hour.
Wrong
import { gtfsToInstant } from "@northguild/gmt/rail/convert";
// stop.stop_timezone is "Europe/London"; the agency is in BerlingtfsToInstant("20260329", "08:00:00", "Europe/London");// "2026-03-29T07:00:00Z" — an hour from the time the feed meansRight
import { gtfsToInstant } from "@northguild/gmt/rail/convert";
// the zone is agency.agency_timezone, for every stopgtfsToInstant("20260329", "08:00:00", "Europe/Berlin");// "2026-03-29T06:00:00Z"The GTFS Trip Board reads a whole trip both ways: the instant gtfsToInstant gives for each stop, and the one the stop’s own zone would give.
© 2026 NorthGuild · Licences
Code examples: MIT-0. Packages: MIT. Third-party data and components: their own licences, credited where they appear. Everything else: © 2026 NorthGuild, all rights reserved.