splitIntervalByUnitDateTime

Signature

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

Split a date-time 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 value 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).

Parameters

Parameter	Type	Description
start	string	ISO PlainDateTime string for the interval start
end	string	ISO PlainDateTime string for the interval end
unit	string	duration unit string — any DateTimeDurationUnit
amount	number	positive number of units per step

Options

options

The 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 date-time the interval begins at, as an ISO 8601 date-time string with no offset or time zone.
end	string	The first date-time 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 { splitIntervalByUnitDateTime } from "@northguild/gmt/plain/interval";

splitIntervalByUnitDateTime("2024-01-01T12:00:00", "2024-01-01T14:00:00", "hour", 1) // [{ start: "2024-01-01T12:00:00", end: "2024-01-01T13:00:00" }, { start: "2024-01-01T13:00:00", end: "2024-01-01T14:00:00" }]

startendunitamount

output

 

Source

plain/interval/splitIntervalByUnitDateTime.ts