UNPKG

@burglekitt/gmt

Version:

Temporal-based date and time utilities with timezone support and polyfill integration

github.com/burglekitt/gmt

burglekitt/gmt

33 lines (32 loc) • 2.59 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
/** * 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. * * @param start ISO PlainDate string for the interval start, optionally calendar-annotated * @param end ISO PlainDate string for the interval end, optionally calendar-annotated * @param unit duration unit string — `"years" | "months" | "weeks" | "days"` (time units are ignored by PlainDate and return []) * @param amount positive number of units per step * @returns array of `{ start, end }` records, or [] on invalid input * * @example 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" }] * @example 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" }] * @example splitIntervalByUnitDate("2024-01-01", "2024-01-01", "day", 2) // [{ start: "2024-01-01", end: "2024-01-01" }] * @example splitIntervalByUnitDate("2024-01-01", "2024-01-10", "day", 0) // [] * @example splitIntervalByUnitDate("invalid", "2024-01-10", "day", 2) // [] * @example 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) */ export declare function splitIntervalByUnitDate(start: string, end: string, unit: string, amount: number): Array<{ start: string; end: string; }>;