UNPKG

@burglekitt/gmt

Version:

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

github.com/burglekitt/gmt

burglekitt/gmt

37 lines (36 loc) • 2.77 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
34
35
36
37
/** * Return the overlapping span of two zoned intervals, or null when they do not overlap. * * - Uses `Temporal.ZonedDateTime.compare` for comparison (same instant semantics). * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap. * - Returns `null` if either interval is invalid (`start > end`). * - Returns `null` on invalid input (wrong type, malformed strings, leap seconds). * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as * well as bare ISO ones — E7 (issue #152) — but **rejects a mismatched pair**: every endpoint * must name the same calendar system (E7's D4-zoned). Unlike the ordering functions, this one * returns a *value* the caller reads back as a datetime, and there is no principled way to pick * one endpoint's calendar as the answer's. Rejection also keeps a uniform policy across all * eight value-returning zoned set operations, four of which return arrays — a per-element * "winner's tag" would produce a result set whose members disagree about which calendar they * are in. (`intervalUnionZoned`'s existing "winning endpoint's *time zone* wins" is not * precedent: the zone is a property of the surviving point, the calendar is a property of the * answer.) A mismatch returns the sentinel. * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never * copied from an input string (E7's D7-zoned). * - Still rejects Temporal's own `[timeZone][u-ca=...]` RFC 9557 ordering — see * `regex/calendar-zoned-date-time.ts`. * * @param aStart ISO 8601 zoned datetime string for the first interval start * @param aEnd ISO 8601 zoned datetime string for the first interval end * @param bStart ISO 8601 zoned datetime string for the second interval start * @param bEnd ISO 8601 zoned datetime string for the second interval end * @returns `{ start, end }` with the overlapping span, or null on invalid input / no overlap * * @example intervalIntersectionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // { start: "2024-04-01T00:00:00+00:00[UTC]", end: "2024-06-30T23:59:59+00:00[UTC]" } * @example intervalIntersectionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-07-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null * @example intervalIntersectionZoned("invalid", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null */ export declare function intervalIntersectionZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): { start: string; end: string; } | null;