@northguild/gmt 1.16.0 → 1.18.0

package/dist/types/index.js

@@ -11,12 +11,13 @@ export * from "./datetime-format-options.js";
 export * from "./disambiguation.js";
 export * from "./duration-relative-to.js";
 export * from "./duration-string-options.js";
-export * from "./duration-unit.js";
 export * from "./fiscal-calendar.js";
 export * from "./fractional-digit.js";
+export * from "./free-time-options.js";
 export * from "./interval.js";
 export * from "./now-unit.js";
 export * from "./offset.js";
+export * from "./operating-schedule.js";
 export * from "./overflow.js";
 export * from "./relative-date-time-unit.js";
 export * from "./relative-date-unit.js";
@@ -29,6 +30,7 @@ export * from "./rounding-options.js";
 export * from "./time-cycle-field.js";
 export * from "./time-duration-unit.js";
 export * from "./time-unit.js";
+export * from "./transport-timestamps.js";
 export * from "./unix-now-unit.js";
 export * from "./utc-now-unit.js";
 export * from "./zone-bucket-unit.js";

package/dist/types/interval.d.ts

@@ -5,7 +5,9 @@
  *   RFC 5545 `DTEND` is non-inclusive). Intervals that touch share no instant.
  * - Both endpoints are instants: an offset (`Z`, `±HH:MM`) is required, a bracketed IANA zone is
  *   optional, and the two may name different zones. Leap seconds are rejected; a `[u-ca=...]`
- *   annotation is ignored, as `Temporal.Instant.from` ignores it.
+ *   annotation is ignored, as `Temporal.Instant.from` ignores it. The offset fixes the instant;
+ *   an offset written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives.
  * - `start === end` (as instants) is a valid, empty interval: it has a position but contains no
  *   instant. `start` after `end` is invalid.
  *
@@ -13,6 +15,11 @@
  * `plain|utc|zoned|unix/interval` functions take positional strings and a different model.
  */
 export type Interval = {
+    /** The first instant inside the interval, as an ISO 8601 instant string with an offset. */
     start: string;
+    /**
+     * The first instant after the interval, as an ISO 8601 instant string with an offset; it is
+     * not itself inside. It may equal `start`, which makes the interval empty, but not precede it.
+     */
     end: string;
 };

package/dist/types/offset.d.ts

@@ -1,2 +1,11 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * What to do when the UTC offset written in a zoned value disagrees with its time zone, as
+ * Temporal's `offset` option (`Temporal.ZonedDateTime.prototype.with(item, { offset })`). It is
+ * used alongside `Disambiguation`.
+ *
+ * `"use"` keeps the instant the offset names, `"ignore"` keeps the wall time and takes the offset
+ * from the zone, `"prefer"` keeps the offset when it is valid for the zone and otherwise takes
+ * the zone's, and `"reject"` refuses the mismatch.
+ */
 export type Offset = Temporal.ZonedDateTimeAssignmentOptions["offset"];

package/dist/types/operating-schedule.d.ts

@@ -0,0 +1,71 @@
+import type { BusinessCalendar } from "./business-calendar.js";
+/**
+ * An ISO weekday number: 1 (Monday) through 7 (Sunday), as `Temporal.PlainDate#dayOfWeek`
+ * reads it.
+ */
+export type IsoWeekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+/**
+ * A daily window of local wall time, half-open: open from `from` up to (not including) `to`.
+ *
+ * - `from` and `to` are wall-clock readings in the schedule's zone, not instants.
+ * - A window belongs to the date it starts on. A Friday night window listed under weekday 5
+ *   runs into Saturday morning; a holiday or override on Friday removes or replaces it, and one
+ *   on Saturday does not.
+ */
+export type LocalWindow = {
+    /**
+     * The wall time the window opens, as an ISO PlainTime string (`"09:00"`, `"17:30:00"`) that
+     * `isValidTime` accepts.
+     */
+    from: string;
+    /**
+     * The wall time the window closes, as an ISO PlainTime string; the window does not include it.
+     * A value after `from` keeps the window inside one local date. A value at or before `from`
+     * wraps past midnight into the next local date: `{ from: "23:00", to: "06:00" }` is a night,
+     * and `{ from: "00:00", to: "00:00" }` is a whole day.
+     */
+    to: string;
+};
+/** One local date whose windows differ from the weekly pattern. */
+export type OperatingOverride = {
+    /** The local date the override applies to, as an ISO PlainDate string in the schedule's zone. */
+    date: string;
+    /**
+     * The windows that date has instead of its weekly ones, holiday or not. `[]` closes the date
+     * for the whole day.
+     */
+    windows: LocalWindow[];
+};
+/**
+ * Weekly opening hours in one zone, with dated exceptions.
+ *
+ * This is deliberately a weekly pattern with dated exceptions, not an RFC 5545 recurrence rule:
+ * there is no monthly or yearly recurrence.
+ */
+export type OperatingSchedule = {
+    /**
+     * The time zone the windows are read in: an IANA name or a UTC offset. A UTC offset such as
+     * `"+02:00"` observes no DST.
+     */
+    timeZone: string;
+    /**
+     * The windows of each ISO weekday. A missing weekday, or `[]`, is closed all day. Windows of
+     * one weekday may overlap or touch; they are merged.
+     */
+    weekly: Partial<Record<IsoWeekday, LocalWindow[]>>;
+    /**
+     * The local dates that are closed, as ISO PlainDate strings. A `BusinessCalendar` can be passed
+     * directly: its `holidays` are read, and its `weekend` and `timeZone` are not, because `weekly`
+     * already says which weekdays open and `timeZone` above is the zone.
+     *
+     * @defaultValue None. No date is closed as a holiday.
+     */
+    holidays?: string[] | BusinessCalendar;
+    /**
+     * The single dates whose windows replace the weekly ones. An override wins over a holiday on the
+     * same date, and two overrides for one date make the schedule invalid.
+     *
+     * @defaultValue None. Every date follows the weekly pattern and the holidays.
+     */
+    overrides?: OperatingOverride[];
+};

package/dist/types/overflow.d.ts

@@ -1,2 +1,8 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * What to do when a date or time field is out of range, as Temporal's `overflow` option
+ * (`Temporal.PlainDate.prototype.add(item, { overflow })`). `"constrain"` clamps the field to the
+ * nearest valid value, so January 31 plus one month is the last day of February; `"reject"`
+ * refuses the value.
+ */
 export type Overflow = Temporal.ArithmeticOptions["overflow"];

package/dist/types/relative-rounding-method.d.ts

@@ -1 +1,7 @@
+/**
+ * How the `formatRelative*` functions round a fractional distance to a whole number of the unit
+ * displayed. It is applied to the signed value, where a past distance is negative: `"floor"`
+ * rounds toward negative infinity, `"ceil"` toward positive infinity, and `"round"` to the nearest
+ * whole number, a half going toward positive infinity.
+ */
 export type RelativeRoundingMethod = "floor" | "ceil" | "round";

package/dist/types/relative-time-options.d.ts

@@ -5,14 +5,42 @@ import type { RelativeRoundingMethod } from "./relative-rounding-method.js";
  * restrict `largestUnit` or add domain-specific fields.
  */
 export interface RelativeTimeFormatOptions {
-    /** Name style: "long" (default), "short", or "narrow". */
+    /**
+     * The length of the unit name, as the `style` of `Intl.RelativeTimeFormat`: `"long"` ("in 3
+     * months"), `"short"` ("in 3 mo.") or `"narrow"` (the locale's most compact form).
+     *
+     * @defaultValue `"long"`
+     */
     style?: "long" | "short" | "narrow";
-    /** Whether to use relative time words ("in 2 days") or numeric ("2 days"). */
+    /**
+     * Whether a distance may be written as a word instead of a number, as the `numeric` option of
+     * `Intl.RelativeTimeFormat`. `"auto"` uses the locale's word where it has one ("yesterday",
+     * "next year"); `"always"` writes the number every time ("1 day ago").
+     *
+     * @defaultValue `"auto"`
+     */
     numeric?: "always" | "auto";
-    /** The largest unit to display. Each domain restricts the allowed values. */
+    /**
+     * The one unit the distance is written in, whatever its size, so `"hour"` renders a day and a
+     * half as "in 36 hours". Each domain restricts the allowed values to the units its values have,
+     * singular or plural; any other value returns `""`.
+     *
+     * @defaultValue None. The unit is picked from the distance.
+     */
     largestUnit?: string;
-    /** How the computed distance rounds to the display unit. */
+    /**
+     * The way a fractional distance becomes the whole number displayed: `"round"` goes to the nearest
+     * whole number, `"floor"` down and `"ceil"` up. It applies to the signed value, where a past
+     * distance is negative, so `"floor"` turns −1.5 hours into "2 hours ago".
+     *
+     * @defaultValue `"round"`
+     */
     roundingMethod?: RelativeRoundingMethod;
-    /** Anchor point for the relative diff. */
+    /**
+     * The moment the distance is measured from, as an ISO string in the same form as the value
+     * being formatted.
+     *
+     * @defaultValue The current date and time.
+     */
     reference?: string;
 }

package/dist/types/rounding-options.d.ts

@@ -1,6 +1,33 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * How a difference is rounded, as the rounding options of Temporal's `until()` and `since()`
+ * (`Temporal.PlainDate.prototype.until(other, options)`). `Unit` is the set of units the values
+ * being compared have: date units for dates, time units for times.
+ */
 export type RoundingOptions<Unit extends Temporal.DateTimeUnit> = {
+    /**
+     * The smallest unit kept in the difference; anything smaller is rounded into it. It may not be
+     * larger than the largest unit asked for.
+     *
+     * @defaultValue None. The difference is not rounded: Temporal uses the smallest unit the
+     * values have, `"day"` for dates and `"nanosecond"` otherwise.
+     */
     smallestUnit?: Temporal.SmallestUnit<Unit>;
+    /**
+     * The step the smallest unit is rounded to, so `15` with `"minute"` rounds to a quarter of an
+     * hour. For a time unit it must divide the next larger unit evenly and be smaller than it (`15`
+     * or `30` minutes, not `7` or `60`); a date unit takes any whole number from 1 up. A non-integer
+     * is truncated first, as Temporal does, and any other value is invalid input.
+     *
+     * @defaultValue `1`, Temporal's default.
+     */
     roundingIncrement?: number;
+    /**
+     * Which way a value between two steps goes. `"trunc"` rounds toward zero and `"halfExpand"` to
+     * the nearest step, a half going away from zero; the other modes are those of Temporal's
+     * `roundingMode` option.
+     *
+     * @defaultValue `"trunc"`, Temporal's default for a difference.
+     */
     roundingMode?: Temporal.RoundingMode;
 };

package/dist/types/time-cycle-field.d.ts

@@ -1 +1,5 @@
+/**
+ * A time field `cycleTime`, `cycleDateTime` and `cycleZoned` can step and wrap, from `"hour"`
+ * down to `"nanosecond"`: the fields of Temporal's `PlainTime`.
+ */
 export type TimeCycleField = "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond";

package/dist/types/time-duration-unit.d.ts

@@ -1,2 +1,6 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * A time field of an ISO 8601 duration, in the plural, from `"hours"` down to `"nanoseconds"`.
+ * It names the unit an amount of time is given in or a time difference is measured in.
+ */
 export type TimeDurationUnit = keyof Pick<Temporal.DurationLike, "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds">;

package/dist/types/time-unit.d.ts

@@ -1,2 +1,6 @@
 import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * A time unit in the singular, from `"hour"` down to `"nanosecond"`, as Temporal's rounding and
+ * difference options name units.
+ */
 export type TimeUnit = Temporal.TimeUnit;

package/dist/types/transport-timestamps.d.ts

@@ -0,0 +1,54 @@
+/**
+ * What a transport timestamp claims to be, in DCSA's `eventClassifierCode` vocabulary:
+ *
+ * - `PLN`: planned, the schedule.
+ * - `EST`: estimated, a prediction that may be revised.
+ * - `REQ`: requested, the time one party asked another for.
+ * - `ACT`: actual, an observation of what happened.
+ *
+ * One field can hold all four. A value is only comparable with another once its class is known:
+ * an estimate compared with an actual as though both were observations is the standard
+ * visibility-dashboard error.
+ */
+export type TimestampClass = "PLN" | "EST" | "REQ" | "ACT";
+/**
+ * One recorded timestamp of an event: what it claims, when it claims it, and when that claim was
+ * recorded.
+ */
+export type TimestampEvent = {
+    /** What the timestamp claims to be: planned, estimated, requested or actual. */
+    classifier: TimestampClass;
+    /**
+     * The moment the timestamp names, as an ISO 8601 instant (`Z` or an offset) or zoned string.
+     * Functions that return it echo it exactly as written.
+     */
+    at: string;
+    /**
+     * When the timestamp was recorded or received, as an ISO 8601 instant or zoned string. It
+     * orders revisions of the same class: the latest recorded is the current one.
+     */
+    recordedAt: string;
+};
+/**
+ * The caller's punctuality tolerance, as ISO 8601 durations of exact time (a day is 24 hours;
+ * years, months and weeks are refused; neither may be negative).
+ *
+ * GMT holds no default: "on time" without a stated tolerance is not a measurement. A 15-minute
+ * tolerance is `{ late: "PT15M" }`; a day-based one is `{ late: "P1D", early: "P1D" }`.
+ */
+export type PunctualityTolerance = {
+    /**
+     * How far after the plan an arrival may be before it is late: a deviation of this much or more
+     * is late. `"PT0S"` makes every arrival at or after the plan late.
+     */
+    late: string;
+    /**
+     * How far before the plan an arrival may be before it is early: a deviation of this much or
+     * more ahead of the plan is early.
+     *
+     * @defaultValue None. An early arrival is on time.
+     */
+    early?: string;
+};
+/** An arrival's punctuality against a `PunctualityTolerance`. */
+export type Punctuality = "early" | "onTime" | "late";

package/dist/unix/calculate/addUnix.d.ts

@@ -6,15 +6,11 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - Converts to ZonedDateTime, adds the duration, then converts back to epoch.
  * - Validates duration units and values.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone.
  * - Returns null for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in null).
- *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone returns null), overflow ("constrain" | "reject")
+ * @param options optional: how `value` is read and how an out-of-range result day is handled
  * @returns Unix epoch number after addition, or null on invalid input
  *
  * @example addUnix(1706659200000, { days: 1 }) // 1706745600000
@@ -25,7 +21,25 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example addUnix(1706659200000, { days: 1 }, { timeZone: "Mars/Olympus" }) // null (unknown zone)
  */
 export declare function addUnix(value: number | string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `null`. The result is in the same unit.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the calendar arithmetic runs in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
+    /**
+     * How a result day that does not exist in its month is handled, such as January 31 plus one
+     * month. `"constrain"` clamps to the last valid day, and `"reject"` returns `null`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): number | null;

package/dist/unix/calculate/addUnix.js

@@ -9,15 +9,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Converts to ZonedDateTime, adds the duration, then converts back to epoch.
  * - Validates duration units and values.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone.
  * - Returns null for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
- * to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in null).
- *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone returns null), overflow ("constrain" | "reject")
+ * @param options optional: how `value` is read and how an out-of-range result day is handled
  * @returns Unix epoch number after addition, or null on invalid input
  *
  * @example addUnix(1706659200000, { days: 1 }) // 1706745600000

package/dist/unix/calculate/diffUnix.d.ts

@@ -33,15 +33,13 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *   gives the same number back. For an exact count use the `bigint` APIs: `spanNs` in `span/`,
  *   or `toNanoseconds` in `precision/`.
  * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone is
- *   invalid.
  * - Unit names may be singular or plural (`"day"` or `"days"`), as in Temporal; a record result
  *   keeps the plural keys.
  *
  * @param value1 first Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param value2 second Unix epoch, in the same form and unit
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the epochs are read and how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffUnix(1706745600000, 1706659200000, "days", { timeZone: "UTC" }) // -1 (measured from the first value to the second)
@@ -52,6 +50,18 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example diffUnix(1704067200000, 1740787200000, ["years", "days"], { timeZone: "UTC" }) // { years: 1, days: 59 } (P1Y2M; the 2 months are carried into days)
  */
 export declare function diffUnix(value1: number | string, value2: number | string, units: DateTimeDurationUnit | Temporal.DateTimeUnit | Array<DateTimeDurationUnit | Temporal.DateTimeUnit>, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `null`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone calendar units are measured in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 } & RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;

package/dist/unix/calculate/diffUnix.js

@@ -37,15 +37,13 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   gives the same number back. For an exact count use the `bigint` APIs: `spanNs` in `span/`,
  *   or `toNanoseconds` in `precision/`.
  * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone is
- *   invalid.
  * - Unit names may be singular or plural (`"day"` or `"days"`), as in Temporal; a record result
  *   keeps the plural keys.
  *
  * @param value1 first Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param value2 second Unix epoch, in the same form and unit
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the epochs are read and how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffUnix(1706745600000, 1706659200000, "days", { timeZone: "UTC" }) // -1 (measured from the first value to the second)

package/dist/unix/calculate/diffUnixAsDuration.d.ts

@@ -23,14 +23,12 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
  * different Temporal types.
  * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone is
- *   invalid.
  * - Unit names may be singular or plural (`"day"` or `"days"`), as in Temporal.
  *
  * @param value1 first Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param value2 second Unix epoch, in the same form and unit
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the epochs are read, how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffUnixAsDuration(1706659200000, 1706745600000, "days") // "P1D"
@@ -40,6 +38,18 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example diffUnixAsDuration(NaN, 1706745600000, "days") // ""
  */
 export declare function diffUnixAsDuration(value1: number | string, value2: number | string, unit: DateTimeDurationUnit | Temporal.DateTimeUnit, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone calendar units are measured in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 } & RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;

package/dist/unix/calculate/diffUnixAsDuration.js

@@ -25,14 +25,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
  * different Temporal types.
  * - Each value is a safe integer or a digit string (`"1706659200000"`); anything else is invalid.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone is
- *   invalid.
  * - Unit names may be singular or plural (`"day"` or `"days"`), as in Temporal.
  *
  * @param value1 first Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param value2 second Unix epoch, in the same form and unit
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the epochs are read, how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffUnixAsDuration(1706659200000, 1706745600000, "days") // "P1D"

package/dist/unix/calculate/endOfQuarterForUnix.d.ts

@@ -9,11 +9,9 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *   takes neither. Those ignored options were removed in 1.16.0.
  * - Returns null for invalid input.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone returns
- *   null.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
+ * @param options optional: how `value` is read and the zone the quarter is found in
  * @returns Unix epoch number representing the end of the quarter, or null on invalid input
  *
  * @example endOfQuarterForUnix(1706659200000, { timeZone: "UTC" }) // 1711929599999
@@ -22,6 +20,18 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example endOfQuarterForUnix(NaN) // null
  */
 export declare function endOfQuarterForUnix(value: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `null`. The result is in the same unit.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the unit boundaries are found in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): number | null;

package/dist/unix/calculate/endOfQuarterForUnix.js

@@ -10,11 +10,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   takes neither. Those ignored options were removed in 1.16.0.
  * - Returns null for invalid input.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone returns
- *   null.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
+ * @param options optional: how `value` is read and the zone the quarter is found in
  * @returns Unix epoch number representing the end of the quarter, or null on invalid input
  *
  * @example endOfQuarterForUnix(1706659200000, { timeZone: "UTC" }) // 1711929599999

package/dist/unix/calculate/endOfUnix.d.ts

@@ -8,15 +8,12 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - Returns the last millisecond of the real local `unit` containing `value` in `timeZone` — just before the next bucket `floorToZone` would return — so the result is never before `value`: the second pass of a repeated fall-back hour ends at its own 1:59:59.999.
  * - Takes no `disambiguation` or `offset`: a boundary is always a real instant, as TC39's `startOfDay()`
  *   takes neither. Those ignored options were removed in 1.16.0.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null, for every unit.
  * - Returns null for invalid input.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone returns
- *   null.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param unit Temporal.DateUnit | Temporal.TimeUnit to specify the end
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), weekStartsOn ("monday" | "sunday")
+ * @param options optional: how `value` is read, the zone the unit is found in and the first day of the week
  * @returns Unix epoch number representing the end of the unit, or null on invalid input
  *
  * @example endOfUnix(1706659200000, "year", { timeZone: "UTC" }) // 1735689599999
@@ -29,7 +26,26 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example endOfUnix(NaN, "day") // null
  */
 export declare function endOfUnix(value: number | string, unit: Temporal.DateTimeUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `null`. The result is in the same unit.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The time zone the unit boundaries are found in: an IANA name, a UTC offset, or `"local"` for
+     * the system time zone. An unknown zone returns `null`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * null, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): number | null;

package/dist/unix/calculate/endOfUnix.js

@@ -10,15 +10,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Returns the last millisecond of the real local `unit` containing `value` in `timeZone` — just before the next bucket `floorToZone` would return — so the result is never before `value`: the second pass of a repeated fall-back hour ends at its own 1:59:59.999.
  * - Takes no `disambiguation` or `offset`: a boundary is always a real instant, as TC39's `startOfDay()`
  *   takes neither. Those ignored options were removed in 1.16.0.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null, for every unit.
  * - Returns null for invalid input.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
- * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone. An unknown zone returns
- *   null.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param unit Temporal.DateUnit | Temporal.TimeUnit to specify the end
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), weekStartsOn ("monday" | "sunday")
+ * @param options optional: how `value` is read, the zone the unit is found in and the first day of the week
  * @returns Unix epoch number representing the end of the unit, or null on invalid input
  *
  * @example endOfUnix(1706659200000, "year", { timeZone: "UTC" }) // 1735689599999