UNPKG

@burglekitt/gmt

Version:

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

github.com/burglekitt/gmt

burglekitt/gmt

26 lines (25 loc) • 1.71 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
import { Temporal } from "@js-temporal/polyfill"; import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js"; /** * Return the difference between two PlainDateTime values in the requested unit. * * - Returns `null` for invalid inputs (negative diffs are valid). * - Uses Temporal.PlainDateTime.until and extracts the requested unit. * * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the result, * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "hour", roundingMode: "halfExpand" }` * rounds the difference to the nearest hour before extracting the requested unit. * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the * array (e.g. `["day", "hour"]` with `smallestUnit: "week"`) — this combination is rejected by * Temporal and returns null, same as other invalid input. * * @param dateTime1 ISO PlainDateTime string for the start * @param dateTime2 ISO PlainDateTime string for the end * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls) * @returns numeric difference in the requested unit, or null on invalid input * * @example diffDateTime("2024-03-10T12:00:00", "2024-03-15T12:00:00", "day") // 5 * @example diffDateTime("invalid", "2024-03-15T12:00:00", "day") // null */ export declare function diffDateTime(dateTime1: string, dateTime2: string, units: DateTimeDurationUnit | DateTimeDurationUnit[], options?: RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;