@northguild/gmt 1.17.0 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@northguild/gmt",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "Temporal-based date and time utilities with timezone support and polyfill integration",
   "keywords": [
     "date",
@@ -35,10 +35,9 @@
     "dist",
     "LICENSE",
     "README.md",
-    "skills/gmt-basics",
-    "skills/gmt-arithmetic",
-    "skills/gmt-timezone",
-    "skills/gmt-integration"
+    "skills",
+    "!skills/_artifacts",
+    "!skills/contributor"
   ],
   "type": "module",
   "sideEffects": false,
@@ -55,6 +54,9 @@
       "calendar/calculate": [
         "./dist/calendar/calculate/index.d.ts"
       ],
+      "calendar/hours": [
+        "./dist/calendar/hours/index.d.ts"
+      ],
       "calendar/validate": [
         "./dist/calendar/validate/index.d.ts"
       ],
@@ -175,6 +177,9 @@
       "transport/calculate": [
         "./dist/transport/calculate/index.d.ts"
       ],
+      "transport/compare": [
+        "./dist/transport/compare/index.d.ts"
+      ],
       "transport/convert": [
         "./dist/transport/convert/index.d.ts"
       ],
@@ -290,6 +295,10 @@
       "types": "./dist/calendar/calculate/index.d.ts",
       "default": "./dist/calendar/calculate/index.js"
     },
+    "./calendar/hours": {
+      "types": "./dist/calendar/hours/index.d.ts",
+      "default": "./dist/calendar/hours/index.js"
+    },
     "./calendar/validate": {
       "types": "./dist/calendar/validate/index.d.ts",
       "default": "./dist/calendar/validate/index.js"
@@ -450,6 +459,10 @@
       "types": "./dist/transport/calculate/index.d.ts",
       "default": "./dist/transport/calculate/index.js"
     },
+    "./transport/compare": {
+      "types": "./dist/transport/compare/index.d.ts",
+      "default": "./dist/transport/compare/index.js"
+    },
     "./transport/convert": {
       "types": "./dist/transport/convert/index.d.ts",
       "default": "./dist/transport/convert/index.js"

package/skills/gmt-arithmetic/SKILL.md

@@ -32,7 +32,7 @@ sources:
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.17.0'
+  library_version: '1.18.0'
 ---
 
 # GMT Arithmetic

package/skills/gmt-basics/SKILL.md

@@ -24,7 +24,7 @@ sources:
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.17.0'
+  library_version: '1.18.0'
 ---
 
 # GMT Basics
@@ -77,6 +77,15 @@ input before you act on it.
 
 - `formatRelative*` measure from now when `reference` is omitted, so the output
   changes from day to day. Pass `reference` whenever the result must be deterministic.
+  `largestUnit` takes a singular or plural unit name (`"hour"` or `"hours"`) from the
+  units the function's values have: `formatRelativeDate` day to year, `formatRelativeTime`
+  second to hour, the others second to year. Any other unit returns `""`.
+  `roundingMethod` is `"floor"`, `"ceil"` or `"round"`: any other value returns `""`.
+- In a `parse*WithPattern` pattern, `''` is one literal quote, inside or outside
+  quoted text (UTS #35): `"MMM d, ''yy"` reads `"Mar 15, '24"`. It is not an empty
+  separator. Write adjacent fields with nothing between them, as in `"yyyyMMdd"`.
+- `getZonedNow` reads `smallestUnit` only, and writes milliseconds when it is
+  omitted or `undefined`. The string always carries the offset and the zone.
 - `parseDateWithPattern`, `parseRfc2822` and `parseHttp` return `""` on
   shape-valid-but-unreal dates such as 31 February (regex only proves shape;
   Temporal validates the real value). Parsers reject; only arithmetic clamps.

package/skills/gmt-integration/SKILL.md

@@ -17,7 +17,7 @@ sources:
 metadata:
   type: composition
   library: '@northguild/gmt'
-  library_version: '1.17.0'
+  library_version: '1.18.0'
 ---
 
 # GMT Integration
@@ -48,8 +48,11 @@ which lint package to install for Date-ban enforcement.
    `convertUtcToUnix(value, { epochUnit: "seconds" })` rather than
    dividing/multiplying by hand. An `epochUnit` option must be `"seconds"` or
    `"milliseconds"` (singular accepted): any other value returns the sentinel
-   instead of being read as milliseconds. `unix/` reads zone-dependent fields in
-   UTC unless you pass `timeZone` (`"local"` for the system zone). A
+   instead of being read as milliseconds. `unix/` and `utc/` read zone-dependent
+   fields in UTC unless you pass `timeZone` (`"local"` for the system zone); that
+   holds for the `utc/` readers and converters too, such as `parseHourFromUtc` and
+   `convertUtcToPlainDate`. `convertUtcToZoned` and `convertUnixToZoned` take a
+   required zone and do not accept `"local"`. A
    blank epoch string is invalid, not `1970`, and `sortUnix`/`minUnix`/`maxUnix`
    skip values that are not integer epochs in Temporal's range.
 4. **Nanoseconds are `bigint`, never `number`.** A `number` is exact only to
@@ -75,8 +78,10 @@ which lint package to install for Date-ban enforcement.
      unsynchronized" marker. Check for `0n` yourself before trusting it as 1900.
    - .NET ticks name an instant only when `DateTimeKind` is `Utc`. `Local` and
      `Unspecified` ticks count wall-clock time.
-   - `toNanoseconds` and `isValidInstant` read the offset and ignore a bracketed
-     zone annotation, which is not checked.
+   - `toNanoseconds` and `isValidInstant` read the offset and do not validate a
+     bracketed zone annotation. One thing is read from it: an offset written to the
+     minute that is the zone's sub-minute offset rounded (`-00:45[Africa/Monrovia]`)
+     names the instant the zone gives.
 6. **Lint packages are toolchain-specific, not mutually exclusive.** Recommend
    only the one matching the project's existing linter; do not force all three.
 7. **Read the READMEs.** This skill is a routing pointer. For full integration

package/skills/gmt-timezone/SKILL.md

@@ -1,21 +1,20 @@
 ---
 name: gmt-timezone
 description: >
-  Timezone-aware operations — get zoned now, format zoned datetimes/ranges,
-  convert between plain↔zoned↔UTC↔Unix, DST disambiguation on construction and
-  arithmetic, the instant-plus-offset pair, classifying a zoneless wall time
-  before resolving it, real zone unit boundaries
-  (startOfZoned/endOfZoned/startOfUnix/endOfUnix), hours in a local day,
-  flooring or bucketing on local boundaries (floorToZone/bucketRange),
-  calendar-annotated zoned strings, zoned values at the range limits, the
-  transport legs transitTime, etaAtZone and dwellTime (local calendar days
-  crossed), intermodal free time — freeTimeExpiry (the free window and its
-  half-open expiry), chargeableDays (the dates charged, with tier bands),
-  demurrageClock (which events a demurrage, detention, storage or combined clock
-  runs between) — and billingTimeline (invoice, dispute and resolution
-  deadlines, windows as caller parameters). Reads the installed package
-  README.md and source JSDoc for API details; this skill is a routing pointer,
-  not an API dump.
+  Timezone-aware operations — zoned now, formatting zoned values/ranges,
+  plain↔zoned↔UTC↔Unix conversion, DST disambiguation on construction and
+  arithmetic, the instant-plus-offset pair, classifyLocal/resolveLocal, real
+  unit boundaries (startOfZoned/endOfZoned/startOfUnix/endOfUnix), hours in a
+  local day, floorToZone/bucketRange, calendar-annotated zoned strings, range
+  limits, transport legs (transitTime, etaAtZone, dwellTime, crossingTime,
+  scheduleDelivery), cut-offs (cutoffAt, cutoffSchedule, isPastCutoff,
+  timeToCutoff), planned versus actual (scheduleDeviation, classifyPunctuality,
+  punctualityRate, bestAvailable and estimateDrift over PLN/EST/REQ/ACT,
+  nextDeparture), intermodal free time (freeTimeExpiry, chargeableDays,
+  demurrageClock), billingTimeline, and operating hours (OperatingSchedule,
+  recurringWindows, operatingIntervals, isOpenAt, nextOpenAt, nextCloseAt,
+  operatingTimeBetween, addOperatingTime), and daylight time
+  (isInDaylightSaving, hasDaylightSaving). Points to the README and JSDoc.
 sources:
   - 'northguild/gmt:README.md'
   - 'northguild/gmt:packages/gmt/src/zoned/get/index.ts'
@@ -34,13 +33,17 @@ sources:
   - 'northguild/gmt:packages/gmt/src/instant/convert/index.ts'
   - 'northguild/gmt:packages/gmt/src/calendar/calculate/index.ts'
   - 'northguild/gmt:packages/gmt/src/calendar/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/calendar/hours/index.ts'
+  - 'northguild/gmt:packages/gmt/src/types/operating-schedule.ts'
+  - 'northguild/gmt:packages/gmt/src/types/transport-timestamps.ts'
   - 'northguild/gmt:packages/gmt/src/transport/calculate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/transport/compare/index.ts'
   - 'northguild/gmt:packages/gmt/src/transport/convert/index.ts'
   - 'northguild/gmt:packages/gmt/src/intermodal/calculate/index.ts'
 metadata:
   type: core
   library: '@northguild/gmt'
-  library_version: '1.17.0'
+  library_version: '1.18.0'
 ---
 
 # GMT Timezone
@@ -66,6 +69,10 @@ converting between time zones, or doing arithmetic that must respect DST.
 - The user is working out when a container's free time ends, how many days of
   demurrage or detention are chargeable and for which dates, or which events a
   charge's clock runs between.
+- The user is asking whether a gate, desk, office or venue is open at an
+  instant, when it next opens or closes, how many working hours passed between
+  two instants, or when an SLA measured in open hours falls due — or is
+  expanding a recurring local window such as a night curfew.
 
 ## Core rules
 
@@ -192,7 +199,64 @@ converting between time zones, or doing arithmetic that must respect DST.
     (a skipped date is not counted, a re-entered one only once), and is the
     library's one "local days crossed" count.
     Bare instants with no `targetZone` return `null`: an offset is not a place.
-16. **Free time is counted in the terminal's local days; the start day and the
+    `crossingTime(entry, exit, targetZone)` returns `{ duration, enter, exit }`
+    with no day count (a crossing that needs one is a dwell); `targetZone` is
+    required and always the rendering zone — a bracket on the input never
+    supplies it.
+    `scheduleDelivery(legs, { startTimeZone? })` chains legs into `{ eta,
+    legTimes }`: each leg leaves at its explicit `departure` or at the previous
+    arrival plus that leg's `dwellAfter`, the minimum connect time. A scheduled
+    departure earlier than that is a missed connection and returns `null`
+    (equal passes). A departure is exact (instant or zoned string) or a
+    zoneless wall time: on the first leg it is read in `startTimeZone`, on a
+    later leg in the previous leg's `timeZone` (where that leg leaves from),
+    both with `"compatible"` resolution (ambiguous → earlier, skipped →
+    later). On a later leg, a repeated hour instead takes the earliest pass
+    at or after the previous arrival plus its dwell. A
+    negative leg `duration` is `null`; the last leg's `dwellAfter` is echoed,
+    never added. `mode`, `origin` and `destination` are opaque tags echoed on
+    each `LegTime`. An empty array returns `{ eta: "", legTimes: [] }`.
+16. **Cut-offs count back from the caller's event.**
+    `cutoffAt(anchor, offset, { timeZone, atLocalTime?, calendar?, roll? })`
+    takes an offset off the anchor (loading, departure or arrival are
+    different instants; it never guesses which). With `atLocalTime` the
+    offset's exact part comes off the anchor's instant first, its calendar
+    part off the local date, and the cut-off is that time of day: `P2D` at
+    `"17:00"` is 17:00 two days before, not 48 hours. Without it the offset
+    is `ZonedDateTime#subtract` (`P2D` keeps the wall clock, `PT96H` is 96
+    exact hours). `calendar` and `roll` go together or not at all — there is
+    no default roll, as in `rollDate`; either alone is `""`. A repeated hour
+    takes the first pass (RFC 5545 §3.3.5); a skipped hour is `""`. It does
+    not check that the cut-off is before the anchor.
+    `cutoffSchedule(anchor, [{ name, offset, atLocalTime? }], options)`
+    sorts the stack by instant and returns `[]` if any entry fails.
+    `isPastCutoff(now, cutoff)` is `true` from the cut-off instant on;
+    `timeToCutoff(now, cutoff)` is exact hours, `PT0S` at it, negative after.
+17. **Planned versus actual is exact time under the caller's tolerance.**
+    `scheduleDeviation(planned, actual)` is `actual − planned` in exact hours
+    (`"PT14M"` late, `"-PT5M"` early; a fall-back delay is `PT1H`, never
+    `PT0S`). `classifyPunctuality(planned, actual, { late, early? })` returns
+    `"early" | "onTime" | "late"`, or `null` on invalid input: both edges are
+    outside (exactly `late` is late), and without `early` every early arrival
+    is on time. There is no default tolerance; tolerances are exact durations
+    (a day is 24 hours; years, months, weeks or negative return `null`).
+    `punctualityRate(pairs, tolerance)` returns `{ onTime, total, rate }`,
+    judging every pair under a tolerance read once; an empty list or any
+    invalid pair is `null`. A `TimestampEvent` is `{ classifier: "PLN" |
+    "EST" | "REQ" | "ACT", at, recordedAt }` (DCSA vocabulary).
+    `bestAvailable(events)` returns `{ at, classifier }`: `ACT` whenever one
+    exists, else `PLN`, else `REQ`, else `EST`, newest `recordedAt` within the
+    class — never an `EST` shown as an actual. `estimateDrift(events, {
+    tolerance? })` reports first-to-last `EST` drift, `revisions` and
+    `exceedsTolerance` (strictly greater, either direction; `null` without a
+    tolerance), and is `null` with fewer than two `EST`s.
+    `nextDeparture(after, timetable, { minimumConnection? })` returns the
+    first departure at or after `after + minimumConnection`: a list entry
+    echoed as written (ready for `scheduleDelivery`'s `departure`), or for
+    `{ headway, from, to }` (a GTFS `frequencies.txt` row) `from + k × headway`
+    in the half-open `[from, to)`, written the way `from` was. Every moment
+    must carry its offset; a wall time without one is `""`.
+18. **Free time is counted in the terminal's local days; the start day and the
     basis are tariff terms, never defaults.**
     `freeTimeExpiry(clockStart, freeDays, { basis, timeZone, firstDay, calendar? })`
     returns `{ freeTimeStart, lastFreeDay, expiresAt }`: local dates in
@@ -212,7 +276,7 @@ converting between time zones, or doing arithmetic that must respect DST.
     demurrage gate-in to loaded, detention empty release to gate-in; `combined`
     runs both as one period. No standard fixes how these days are counted;
     every term is the tariff's.
-17. **Billing deadlines are dates counted from an anchor, and every window is
+19. **Billing deadlines are dates counted from an anchor, and every window is
     the caller's.** `billingTimeline({ anchorOn, invoiceIssuedOn?,
     requestReceivedOn? }, { issueDays, disputeDays, resolutionDays,
     agreedResolutionOn? })` returns `{ invoiceDeadline, issuedByDeadline,
@@ -227,7 +291,64 @@ converting between time zones, or doing arithmetic that must respect DST.
     `convertUtcToPlainDate(instant, { timeZone })`. A request before its
     invoice, or an agreed date before the request, returns `null`. GMT
     computes dates, not liability.
-18. **Read the README.** This skill is a routing pointer. For the full DST
+20. **Operating hours are local windows resolved in the schedule's zone.** An
+    `OperatingSchedule` is `{ timeZone, weekly, holidays?, overrides? }`:
+    `weekly` maps ISO weekdays `1`–`7` to half-open `LocalWindow`s
+    (`{ from: "09:00", to: "17:00" }`); a `to` at or before `from` wraps past
+    midnight and the window belongs to the date it starts on. Holidays are local
+    dates (a `BusinessCalendar` is accepted; only its `holidays` are read); an
+    override replaces one date's windows, holiday or not. Every edge goes
+    through `resolveLocal` with `disambiguation` (default `"compatible"`), so a
+    23:00–06:00 window is 8 real hours across New York's fall-back night.
+    `recurringWindows(weekly, range, zone)` and `operatingIntervals(schedule,
+    range)` return merged open intervals; `isOpenAt`, `nextOpenAt` and
+    `nextCloseAt` answer point questions; `operatingTimeBetween(start, end,
+    schedule)` is open time elapsed (hours as the largest unit), and
+    `addOperatingTime(start, "PT8H", schedule)` is the SLA deadline. Searches
+    stop at `within` (default `"P1Y"`) and return `""` past it; `P1D` is not
+    open time and returns `""`.
+21. **A zoned string names one instant in every reader.** Temporal writes a
+    zone's offset rounded to the minute, so a zone with a sub-minute offset
+    (`Africa/Monrovia` stood at −00:44:30 until 1972) is written `-00:45`.
+    Every function that reads a moment (`toNanoseconds`, `spanNs`, `Interval`
+    endpoints, `floorToZone`, `getTimeZoneOffset`, `scheduleDeviation`,
+    `timeToCutoff`, `dwellTime`) reads an offset written to the minute as the
+    bracketed zone's real offset when it is that offset rounded (TC39
+    `ToTemporalZonedDateTime`, match-minutes):
+    `1960-01-01T00:20:00-00:45[Africa/Monrovia]` is `01:04:30Z`. So a zoned
+    string GMT wrote reads back as the instant it was written for. Otherwise
+    the written offset fixes the instant. A function that reads only the
+    instant does not validate the bracket, and the bracket never supplies its
+    rendering zone. A function that keeps the zone (`isValidZonedDateTime`,
+    `transitTime`, `toOffsetInstant`, every `zoned/` function, a zoned
+    `relativeTo`) rejects a bracket that contradicts the offset, and an offset
+    written with seconds must be the zone's offset exactly:
+    `-00:45:00[Africa/Monrovia]` is invalid, `-00:44:30[Africa/Monrovia]` is
+    valid. Two limits are Temporal's own. A wall time repeated inside a
+    sub-minute offset change, written to the minute, reads as its first pass
+    (`1952-10-15T23:59:59-11:20[Pacific/Niue]`); write the offset with seconds
+    to name the second. A zoned read refuses a local date of −271821-04-19,
+    which an instant reader accepts; pass that instant in `Z` form.
+22. **Daylight time is read from the zone's clock changes.**
+    `isInDaylightSaving(zoned)` and `hasDaylightSaving(timeZone, { at })`
+    apply one rule, GMT's own definition and not the tz database's daylight
+    flag (no JavaScript API exposes it): daylight time runs from a forward
+    change of the zone's clocks to the backward change of the same size that
+    undoes it, less than 365 days later. A forward change never undone is a
+    change of standard time, so
+    `isInDaylightSaving("2016-12-01T12:00:00+03:00[Europe/Istanbul]")` is
+    `false`. The higher of two alternating offsets is the daylight one:
+    `Europe/Dublin` in summer, `Africa/Casablanca` at `+01:00`.
+    `hasDaylightSaving` is `true` when the zone is in daylight time at `at`
+    or a daylight period begins less than 365 days after it. Pass `at` (an
+    ISO 8601 instant string) for an answer that does not depend on the day
+    the code runs: `hasDaylightSaving("Europe/Istanbul", { at:
+    "2015-06-15T12:00:00Z" })` is `true`, and with `"2016-06-15T12:00:00Z"`
+    it is `false`. Without `at` the reference is the current instant. Both
+    read the runtime's time zone data, so an answer can change when that data
+    does. The JSDoc of `isInDaylightSaving` lists what the rule reads as
+    standard time.
+23. **Read the README.** This skill is a routing pointer. For the full DST
     disambiguation walkthrough, code examples, and locale ICU notes, read the
     installed package's `README.md` and the source JSDoc.
 
@@ -237,7 +358,7 @@ converting between time zones, or doing arithmetic that must respect DST.
 - **Formatting**: `formatZonedDateTime`, `formatZonedRange`,
   `formatRelativeZoned`, `formatTimeZoneName`
 - **Validation**: `isValidTimeZone`, `isValidZonedDateTime`,
-  `hasDaylightSaving`, `getDstTransitions`, `isInDaylightSaving`
+  `hasDaylightSaving` (`{ at }`), `getDstTransitions`, `isInDaylightSaving`
 - **Conversion**: `convertPlainDateTimeToZoned`, `convertZonedToPlainDateTime`,
   `convertUtcToZoned`, `convertZonedToUtc`, `convertZonedToCalendar`,
   `convertUtcToUnix`, `convertUnixToUtc`
@@ -253,10 +374,18 @@ converting between time zones, or doing arithmetic that must respect DST.
 - **Local-time resolution**: `classifyLocal`, `resolveLocal`
 - **Zone-aware buckets**: `floorToZone`, `bucketRange`,
   `isValidZoneBucketUnit`
-- **Transport legs and dwell**: `transitTime`, `etaAtZone`, `dwellTime`
+- **Transport legs and dwell**: `transitTime`, `etaAtZone`, `dwellTime`,
+  `crossingTime`, `scheduleDelivery`
+- **Cut-offs and deadlines**: `cutoffAt`, `cutoffSchedule`, `isPastCutoff`,
+  `timeToCutoff`
+- **Punctuality and timestamp classes**: `scheduleDeviation`,
+  `classifyPunctuality`, `punctualityRate`, `bestAvailable`, `estimateDrift`,
+  `nextDeparture`
 - **Free time and demurrage**: `freeTimeExpiry`, `chargeableDays`,
   `demurrageClock`
 - **Billing deadlines**: `billingTimeline`
+- **Operating hours**: `recurringWindows`, `operatingIntervals`, `isOpenAt`,
+  `nextOpenAt`, `nextCloseAt`, `operatingTimeBetween`, `addOperatingTime`
 
 ## References
 

package/dist/internal/resolveReadingTimeZone.d.ts

@@ -1,11 +0,0 @@
-/**
- * Resolve the `timeZone` option a UTC reader uses to read a value's wall-clock fields.
- *
- * - `undefined` (the option omitted) resolves to `"UTC"`.
- * - A valid IANA zone (or `"UTC"`) resolves to itself.
- * - Any other value is invalid and resolves to `null`, which callers map to their sentinel.
- *
- * @param timeZone raw option value from caller input
- * @returns the zone to read in, or `null` when the value is invalid
- */
-export declare function resolveReadingTimeZone(timeZone: unknown): string | null;

package/dist/internal/resolveReadingTimeZone.js

@@ -1,18 +0,0 @@
-import { isValidTimeZone } from "../zoned/validate/isValidTimeZone.js";
-/**
- * Resolve the `timeZone` option a UTC reader uses to read a value's wall-clock fields.
- *
- * - `undefined` (the option omitted) resolves to `"UTC"`.
- * - A valid IANA zone (or `"UTC"`) resolves to itself.
- * - Any other value is invalid and resolves to `null`, which callers map to their sentinel.
- *
- * @param timeZone raw option value from caller input
- * @returns the zone to read in, or `null` when the value is invalid
- */
-export function resolveReadingTimeZone(timeZone) {
-    if (timeZone === undefined || timeZone === "UTC")
-        return "UTC";
-    return typeof timeZone === "string" && isValidTimeZone(timeZone)
-        ? timeZone
-        : null;
-}

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

@@ -1,5 +0,0 @@
-/**
- * Plural unit keys accepted by `formatDuration` for `UNIT_TO_INTL` lookup. Maps to
- * singular `Intl.NumberFormat` unit labels (e.g. `"years"` → `"year"`).
- */
-export type DurationUnit = "years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds";