splitIntervalByUnitUtc

Signature

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

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

• Returns an array of { start, end } records that tile the interval, each record’s end equal to the next record’s start.
• Every piece is half-open [start, end): a boundary belongs only to the piece that starts there, so the pieces share no value and together cover the interval exactly once (the rule CORE-6’s splitIntervalAt uses).
• The final sub-interval is trimmed so its end never exceeds the original end.
• Calendar-unit boundaries (years, months, weeks, days) are computed from start (start + k × amount), so month-end starts don’t drift: a monthly split from January 31 lands on February 29, March 31, April 30. Temporal’s add constrains a day the month lacks to the month’s last day, and stepping from that boundary would keep the shortened day (February 29, then March 29).
• Comparison: Luxon’s Interval.splitBy computes each boundary from the start the same way.
• Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never clamp, and stepping keeps nanosecond precision where k × amount would pass Number.MAX_SAFE_INTEGER.
• A step that resolves to the same instant as the previous boundary is skipped, so no empty slice is produced. A step that goes backwards returns [].
• 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

Options

options

A limit on the size of the result

Option	Type	Default	Description
maxPieces?	number	1_000_000	The most records the result may hold. A result that would hold more, or more than the longest possible array (2^32 - 1 elements), returns [] and none is built. A value that is not a positive safe integer also returns [].

Returns

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

Members of each item

Member	Type	Description
start	string	The instant the interval begins at, as an ISO 8601 UTC string ending in Z.
end	string	The first instant after the interval, in the same format as start. It is exclusive: the interval holds everything from start up to but not including this value. It can equal start, which makes the interval empty.

Examples

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

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" }]

startendunitamount

output

 

Source

utc/interval/splitIntervalByUnitUtc.ts