splitIntervalByUnitDate

Signature

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

import { splitIntervalByUnitDate } from "@northguild/gmt/plain/interval";

Split a date 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, or a unit that has no effect on PlainDate, e.g. "hours").
• Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). When start and end carry the same calendar tag, stepping (and each slice’s boundaries) happens in that calendar — a Hebrew leap year splits into 13 month-slices, not 12 (E5 decision of record D5); otherwise (or if either is bare ISO) it falls back to Gregorian. Each boundary’s tag is re-derived from the actual stepped date, never copied — a month-by-month step can cross a leap-month or era boundary mid-split.

Parameters

Parameter	Type	Description
start	string	ISO PlainDate string for the interval start, optionally calendar-annotated
end	string	ISO PlainDate string for the interval end, optionally calendar-annotated
unit	string	duration unit string — "years" | "months" | "weeks" | "days" (time units are ignored by PlainDate and return [])
amount	number	positive number of units per step

Returns

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

Examples

splitIntervalByUnitDate("2024-01-01", "2024-01-10", "day", 2) // [{ start: "2024-01-01", end: "2024-01-03" }, { start: "2024-01-03", end: "2024-01-05" }, { start: "2024-01-05", end: "2024-01-07" }, { start: "2024-01-07", end: "2024-01-09" }, { start: "2024-01-09", end: "2024-01-10" }]
splitIntervalByUnitDate("2024-01-01", "2024-01-09", "day", 2) // [{ start: "2024-01-01", end: "2024-01-03" }, { start: "2024-01-03", end: "2024-01-05" }, { start: "2024-01-05", end: "2024-01-07" }, { start: "2024-01-07", end: "2024-01-09" }]
splitIntervalByUnitDate("2024-01-01", "2024-01-01", "day", 2) // [{ start: "2024-01-01", end: "2024-01-01" }]
splitIntervalByUnitDate("2024-01-01", "2024-01-10", "day", 0) // []
splitIntervalByUnitDate("invalid", "2024-01-10", "day", 2) // []
splitIntervalByUnitDate("5784-01-01[u-ca=hebrew]", "5785-01-01[u-ca=hebrew]", "month", 1) // 13 slices, tiling the Hebrew leap year (including Adar I)

Source

plain/interval/splitIntervalByUnitDate.ts