@burglekitt/gmt/dist/plain/interval/intervalCountDate.d.ts

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

/**
 * Count how many `unit` boundaries a date interval crosses.
 *
 * - Counts calendar boundaries touched by the half-open interval `[start, end)` — distinct
 *   from `diffDate`, which measures exact elapsed duration.
 * - `"2024-01-01"` to `"2024-01-03"` counted in days is 2: the end boundary is excluded.
 * - A zero-length interval counts 1 when it sits mid-unit and 0 when it sits exactly on a
 *   unit boundary (e.g. `"2024-01-15"` counts 1 month but 0 days).
 * - Weeks start on Monday (ISO 8601).
 * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
 * - Returns `null` on invalid input (unparseable start/end, `start > end`, unsupported unit,
 *   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, boundaries are counted in that calendar (a Hebrew leap year
 *   crosses 13 month boundaries, not 12 — see the roadmap's E5 decisions of record, D5). When
 *   they carry different tags (or either is bare ISO), counting falls back to Gregorian.
 *
 * @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 unit string — `"year" | "month" | "week" | "day"` (time units return null)
 * @returns number of unit boundaries touched, or null on invalid input
 *
 * @example intervalCountDate("2024-01-01", "2024-01-03", "day") // 2
 * @example intervalCountDate("2024-01-15", "2024-03-10", "month") // 3
 * @example intervalCountDate("2024-01-15", "2024-01-15", "month") // 1 (zero-length, mid-month)
 * @example intervalCountDate("2024-01-01", "2024-01-01", "month") // 0 (zero-length, on the boundary)
 * @example intervalCountDate("2024-01-01", "2024-01-10", "hour") // null
 * @example intervalCountDate("invalid", "2024-01-10", "day") // null
 * @example intervalCountDate("5784-01-01[u-ca=hebrew]", "5785-01-01[u-ca=hebrew]", "month") // 13 (Hebrew leap year, measured in Hebrew)
 */
export declare function intervalCountDate(start: string, end: string, unit: string): number | null;