# Rail mistakes

Industry: Rail

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

### Taking the hour modulo 24

Severity: high.

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:
```js
const [hours, minutes, seconds] = "25:35:00".split(":");

[String(Number(hours) % 24).padStart(2, "0"), minutes, seconds].join(":");
// "01:35:00" — the day is gone
```

Right:
```js
import { parseGtfsTime } from "@northguild/gmt/rail/parse";

parseGtfsTime("25:35:00");
// { seconds: 5700, dayOverflow: 1 }
```

## A clock-time check

### Checking a stop time as a clock time

Severity: high.

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:
```js
import { isValidTime } from "@northguild/gmt/plain/validate";

isValidTime("25:35:00");
// false — a valid stop time is refused
```

Right:
```js
import { isValidGtfsTime } from "@northguild/gmt/rail/validate";

isValidGtfsTime("25:35:00");
// true
isValidGtfsTime("25:60:00");
// false (minute 60)
```

## Writing it back

### Writing the seconds alone

Severity: medium.

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:
```js
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 gone
```

Right:
```js
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

### Trimming inside the time reader

Severity: medium.

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:
```js
const cell = " 25:35:00";

cell.trim();
// "25:35:00" — read, and the dirty feed goes on unnoticed
```

Right:
```js
import { parseGtfsTime } from "@northguild/gmt/rail/parse";

parseGtfsTime(" 25:35:00");
// null
parseGtfsTime("25:35:00");
// { seconds: 5700, dayOverflow: 1 }
```

## Seconds since midnight

### Adding the seconds to local midnight

Severity: medium.

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:
```js
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 Berlin
```

Right:
```js
import { gtfsToInstant } from "@northguild/gmt/rail/convert";

gtfsToInstant("20260329", "25:35:00", "Europe/Berlin");
// "2026-03-29T23:35:00Z"
```

## The stop's own zone

### Reading a stop's time in its own zone

Severity: medium.

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:
```js
import { gtfsToInstant } from "@northguild/gmt/rail/convert";

// stop.stop_timezone is "Europe/London"; the agency is in Berlin
gtfsToInstant("20260329", "08:00:00", "Europe/London");
// "2026-03-29T07:00:00Z" — an hour from the time the feed means
```

Right:
```js
import { gtfsToInstant } from "@northguild/gmt/rail/convert";

// the zone is agency.agency_timezone, for every stop
gtfsToInstant("20260329", "08:00:00", "Europe/Berlin");
// "2026-03-29T06:00:00Z"
```

The [GTFS Trip Board](/gmt/tools/gtfs-trip-board/?w=gtfstrip&wa=%7B%22preset%22%3A%22border%22%7D) reads a whole trip both ways: the instant `gtfsToInstant` gives for each stop, and the one the stop's own zone would give.
