intervalDivideEquallyZoned

Signature

intervalDivideEquallyZoned(start: string, end: string, n: number): { start: string; end: string; }[]

import { intervalDivideEquallyZoned } from "@northguild/gmt/zoned/interval";

Split a zoned interval into n equal-length sub-intervals.

• Returns an array of n { start, end } records that tile the original interval, each record’s end equal to the next record’s start.
• Boundaries are computed from the total elapsed real time (nanoseconds, via Duration.prototype.total with relativeTo set to start), so a spring-forward day split in half lands exactly on the DST transition’s real midpoint rather than the local-clock midpoint.
• n === 1 returns the original interval unchanged, as a single-element array.
• A zero-length interval (start === end) returns n identical zero-length sub-intervals.
• Returns [] when n is not a positive integer, or on invalid input (unparseable start/end, start > end, leap-second strings).
• Accepts GMT calendar-annotated zoned strings (as produced by convertZonedToCalendar) as well as bare ISO ones — E7 (issue #152) — but rejects a mismatched pair: start and end must name the same calendar system (E7’s D4-zoned), since the synthesized boundaries are values the caller reads back as datetimes and an array of differently-tagged records would be unreadable as a set. A mismatch returns [].
• Output boundaries are re-derived in the resolved calendar via formatZonedInCalendar, never copied from an input string (E7’s D7-zoned).

Parameters

Parameter	Type	Description
start	string	ISO 8601 zoned datetime string for the interval start
end	string	ISO 8601 zoned datetime string for the interval end
n	number	number of equal sub-intervals to produce (positive integer)

Returns

array of n { start, end } records, or [] on invalid input

Examples

intervalDivideEquallyZoned("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", 2) // [{ start: "2024-03-09T12:00:00-05:00[America/New_York]", end: "2024-03-10T12:30:00-04:00[America/New_York]" }, { start: "2024-03-10T12:30:00-04:00[America/New_York]", end: "2024-03-11T12:00:00-04:00[America/New_York]" }] (47 real hours split in half)
intervalDivideEquallyZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-04T00:00:00+00:00[UTC]", 1) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-04T00:00:00+00:00[UTC]" }]
intervalDivideEquallyZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-04T00:00:00+00:00[UTC]", 0) // []
intervalDivideEquallyZoned("invalid", "2024-01-04T00:00:00+00:00[UTC]", 3) // []

Source

zoned/interval/intervalDivideEquallyZoned.ts