cutoffSchedule

Legs, dwell, cut-offs and punctuality, shared by road, rail, sea and air.

Signature

cutoffSchedule(anchor: string, cutoffs: Cutoff[], options: CutoffScheduleOptions): CutoffTime[]

Compute a whole stack of cut-offs against one anchor event, earliest first.

An ocean booking carries several deadlines counted back from the same departure — documentation, VGM, gate-in, customs — and when the vessel is rescheduled all of them move. cutoffSchedule computes each entry with cutoffAt against the one anchor, so a new departure is one call and every deadline follows it.
Each entry is cutoffAt(anchor, entry.offset, { ...options, atLocalTime: entry.atLocalTime }): the same local-time resolution, the same rolling, the same sentinel. atLocalTime belongs to the entry; one in options is not read.
Sorted earliest first by instant, not by the text of the local time: on a fall-back day 01:30 on the first pass is before 01:15 on the second. Entries on the same instant keep the order they were given in.
name is an opaque string echoed back; duplicates are kept.
Every entry must succeed: one invalid entry, or one cut-off in a skipped local hour, returns [] rather than a stack with a deadline silently missing. An empty cutoffs array returns [].
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.

Parameters

Parameter	Type	Description
`anchor`	`string`	ISO 8601 instant or zoned datetime string of the event the deadlines count back from
`cutoffs`	`Cutoff[]`	the named deadlines, each with an offset and an optional local time of day

Options

options

The zone every cut-off is read in, and how one rolls off a non-business day, as cutoffAt takes them

Options for cutoffSchedule: cutoffAt’s, with atLocalTime read from each entry instead.

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

Option	Type	Default	Description
`timeZone`	`string`	Required	The time zone every cut-off is read in: an IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts).
`calendar?`	`BusinessCalendar` (`CutoffOptions`)	None. No cut-off’s date is rolled; a `roll` without it returns `[]`.	The working week and holidays every cut-off’s local date is rolled against. Requires `roll`.
`roll?`	`RollConvention` (`CutoffOptions`)	None. No cut-off’s date is rolled; a `calendar` without it returns `[]`.	How a cut-off on a non-business day moves, as `rollDate` moves it. Requires `calendar`.

Returns

the named cut-offs, earliest first, or [] on invalid input

Types

Cutoff

One named deadline in a cut-off stack: how long before the anchor, and at what local time.

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

Member	Type	Description
`name`	`string`	The caller’s label, echoed back (`"document"`, `"VGM"`); GMT does not interpret it.
`offset`	`string`	The ISO 8601 duration before the anchor, as `cutoffAt` takes it.
`atLocalTime?`	`string`	The local time of day the cut-off is pinned to, as `cutoffAt` takes it.

CutoffTime

One computed deadline in a cut-off schedule.

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

Member	Type	Description
`name`	`string`	The entry’s `name`, echoed back.
`at`	`string`	The cut-off as a zoned string in the options’ `timeZone`.

Examples

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

cutoffSchedule("2024-06-14T16:00:00Z", [{ name: "gate-in", offset: "P1D" }, { name: "document", offset: "P2D", atLocalTime: "17:00" }, { name: "VGM", offset: "P1D", atLocalTime: "10:00" }], { timeZone: "Europe/Amsterdam" }) // [{ name: "document", at: "2024-06-12T17:00:00+02:00[Europe/Amsterdam]" }, { name: "VGM", at: "2024-06-13T10:00:00+02:00[Europe/Amsterdam]" }, { name: "gate-in", at: "2024-06-13T18:00:00+02:00[Europe/Amsterdam]" }]

Source

transport/calculate/cutoffSchedule.ts