splitIntervalByUnitUtc

Signature

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

import { splitIntervalByUnitUtc } from "@northguild/gmt/utc/interval";

Split a UTC 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).
• Returns [] on invalid input (unparseable start/end, unsupported unit, non-positive amount, leap-second strings).

Parameters

Parameter	Type	Description
start	string	ISO UTC datetime string for the interval start
end	string	ISO UTC 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

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

Source

utc/interval/splitIntervalByUnitUtc.ts