splitIntervalByUnitZoned

Signature

splitIntervalByUnitZoned(start: string, end: string, unit: string, amount: number): { start: string; end: string; }[]

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

Split a zoned interval into sub-intervals of amount × unit.

• Returns an array of { start, end } records that tile the interval.
• The final sub-interval is trimmed so its end never exceeds the original end.
• Returns [{ start, end }] when start === end (zero-length interval).
• Accepts GMT calendar-annotated zoned strings (as produced by convertZonedToCalendar) as well as bare ISO ones — E7 (issue #152). Stepping by a calendar unit (“1 month”) resolves against the endpoints’ shared calendar when both tags match, and falls back to Gregorian/ISO when they mismatch or either endpoint is bare (E7’s D5-zoned). Sub-interval boundaries are re-derived in the resolved calendar via formatZonedInCalendar, never copied from an input string (E7’s D7-zoned).
• Returns [] on invalid input (unparseable start/end, unsupported unit, non-positive amount, leap-second strings).

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
unit	string	duration unit string — any DateTimeDurationUnit
amount	number	positive number of units per step

Returns

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

Examples

splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "hour", 6) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T06:00:00+00:00[UTC]" }, { start: "2024-01-01T06:00:00+00:00[UTC]", end: "2024-01-01T12:00:00+00:00[UTC]" }, { start: "2024-01-01T12:00:00+00:00[UTC]", end: "2024-01-01T18:00:00+00:00[UTC]" }, { start: "2024-01-01T18:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }]
splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T01:30:00+00:00[UTC]", "hour", 1) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T01:00:00+00:00[UTC]" }, { start: "2024-01-01T01:00:00+00:00[UTC]", end: "2024-01-01T01:30:00+00:00[UTC]" }]
splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T00:00:00+00:00[UTC]", "hour", 1) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T00:00:00+00:00[UTC]" }]
splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "hour", 0) // []
splitIntervalByUnitZoned("invalid", "2024-01-02T00:00:00+00:00[UTC]", "hour", 1) // []

Source

zoned/interval/splitIntervalByUnitZoned.ts