@northguild/gmt 1.15.0 → 1.17.0

package/dist/internal/zonedWallClockDifference.d.ts

@@ -0,0 +1,92 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { DurationRelativeTo } from "../types/index.js";
+/** Options accepted by `ZonedDateTime#until`. */
+export type ZonedDifferenceOptions = Temporal.DifferenceOptions<Temporal.DateTimeUnit>;
+/** Options accepted by `Duration#round`, with GMT's `relativeTo` forms. */
+export interface DurationRoundOptions {
+    largestUnit?: Temporal.LargestUnit<Temporal.DateTimeUnit>;
+    smallestUnit?: Temporal.SmallestUnit<Temporal.DateTimeUnit>;
+    roundingIncrement?: number;
+    roundingMode?: Temporal.RoundingMode;
+    relativeTo?: DurationRelativeTo;
+}
+/**
+ * `PlainDate#until(other, options)` with rounding options for two dates in one calendar, as TC39
+ * `DifferenceTemporalPlainDate` computes it: `CalendarDateUntil` through the Temporal compat layer,
+ * then — unless the granularity is one day — `RoundRelativeDuration` in a plain context.
+ *
+ * @param one the start, in the calendar to measure in
+ * @param two the end, in the same calendar
+ * @param options Temporal `largestUnit` / `smallestUnit` / `roundingIncrement` / `roundingMode`
+ * @returns the rounded date duration; throws where TC39 Temporal throws
+ */
+export declare function plainDateUntilWithRounding(one: Temporal.PlainDate, two: Temporal.PlainDate, options: Temporal.DifferenceOptions<Temporal.DateUnit>): Temporal.Duration;
+/**
+ * Whether Temporal's DifferenceTemporalZonedDateTime would reject `largestUnit` for this pair: a
+ * calendar unit (day or larger) between two different time zones (TimeZoneEquals is false), because
+ * "day lengths can vary between time zones due to DST". `ZonedDateTime#equals` applies TC39
+ * TimeZoneEquals, so `UTC` equals `Etc/UTC` and `Asia/Calcutta` equals `Asia/Kolkata`.
+ *
+ * @param one the start
+ * @param two the end
+ * @param largestUnit the requested `largestUnit`
+ * @returns true when the pair cannot be differenced in `largestUnit`
+ */
+export declare function isCalendarDifferenceAcrossZones(one: Temporal.ZonedDateTime, two: Temporal.ZonedDateTime, largestUnit: string): boolean;
+/**
+ * `ZonedDateTime#until`, correct at the range limits (see the note at the top of this file).
+ *
+ * @param one the start
+ * @param two the end
+ * @param options Temporal `largestUnit` / `smallestUnit` / `roundingIncrement` / `roundingMode`
+ * @returns the difference; throws where TC39 Temporal throws
+ */
+export declare function zonedUntil(one: Temporal.ZonedDateTime, two: Temporal.ZonedDateTime, options?: ZonedDifferenceOptions): Temporal.Duration;
+/**
+ * `PlainDateTime#until` / `#since`, correct when the polyfill would round over a nudge window that
+ * does not contain the target (defect 4).
+ *
+ * The plain difference functions round through the polyfill directly, because neither the range
+ * limits nor the non-ISO calendars reach them the way they reach the zoned ones. A calendar
+ * `smallestUnit` measured from a day that a month add would constrain is the one case that does, so
+ * it takes the spec path and everything else stays the polyfill's own call.
+ *
+ * @param one the earlier plain datetime
+ * @param two the later plain datetime
+ * @param options Temporal difference options, passed through unchanged when the defect cannot apply
+ * @returns the difference; throws where TC39 Temporal throws
+ */
+export declare function plainUntilWithRounding(one: Temporal.PlainDateTime, two: Temporal.PlainDateTime, options?: {
+    largestUnit?: unknown;
+    smallestUnit?: unknown;
+    roundingIncrement?: number;
+    roundingMode?: Temporal.RoundingMode;
+}): Temporal.Duration;
+/**
+ * `Duration#total({ unit, relativeTo })`, correct at the range limits and in calendars the
+ * polyfill gets wrong.
+ *
+ * @param duration the duration to total
+ * @param unit the Temporal unit to total in
+ * @param relativeTo Temporal `relativeTo`; a zoned one reaches the range-limit fallbacks, and a
+ *   zoned or plain one in a calendar that needs the compat layer takes the spec path
+ * @returns the total; throws where TC39 Temporal throws
+ */
+export declare function durationTotal(duration: Temporal.Duration, unit: Temporal.TotalUnit<Temporal.DateTimeUnit>, relativeTo?: DurationRelativeTo): number;
+/**
+ * `Duration#round(roundTo)`, correct at the range limits.
+ *
+ * @param duration the duration to round
+ * @param roundTo Temporal round options; only a zoned `relativeTo` reaches the fallbacks
+ * @returns the rounded duration; throws where TC39 Temporal throws
+ */
+export declare function durationRound(duration: Temporal.Duration, roundTo: DurationRoundOptions): Temporal.Duration;
+/**
+ * `Temporal.Duration.compare(one, two, { relativeTo })`, correct at the range limits.
+ *
+ * @param one the first duration
+ * @param two the second duration
+ * @param relativeTo Temporal `relativeTo`; only a zoned one reaches the fallbacks
+ * @returns -1, 0 or 1; throws where TC39 Temporal throws
+ */
+export declare function durationCompare(one: Temporal.Duration | string, two: Temporal.Duration | string, relativeTo?: DurationRelativeTo): number;