splitIntervalByUnitDate

Signature

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

Split a date 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.
• Each boundary is computed from start (start + k × amount), not by stepping from the previous boundary, 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.
• A step that resolves to the same date 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, or a unit that has no effect on PlainDate, e.g. "hours").
• Accepts RFC 9557 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. When they name different calendars (a bare ISO string names iso8601) the result is [], as Temporal’s until throws when CalendarEquals is false (before 1.16.0 it stepped in ISO). 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.
• Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, [u-ca=<id>], canonical calendar ids); see isValidCalendarDate.

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

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 the interval begins on, as an ISO 8601 date (YYYY-MM-DD). It keeps a calendar annotation such as [u-ca=hebrew] when the inputs carry one.
end	string	The first date 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 { splitIntervalByUnitDate } from "@northguild/gmt/plain/interval";

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

startendunitamount

output

 

Source

plain/interval/splitIntervalByUnitDate.ts