@northguild/gmt 1.18.0 → 1.20.0

package/dist/utc/validate/isValidHttpDate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Return true when `value` is a real HTTP header date: the RFC 9110 §5.6.7 HTTP-date that
+ * headers like `Last-Modified`, `Date` and `Expires` carry, such as
+ * `Fri, 15 Mar 2024 14:30:00 GMT`.
+ *
+ * - True exactly when `parseHttpDate` returns a UTC string for the same value: the validator
+ *   calls the parser, so the two cannot disagree.
+ * - **All three HTTP-date formats**, which RFC 9110 §5.6.7 says a recipient "MUST accept":
+ *   IMF-fixdate, and the obsolete rfc850-date (`Sunday, 06-Nov-94 08:49:37 GMT`) and asctime-date
+ *   (`Sun Nov  6 08:49:37 1994`). The `httpDate` pattern matches IMF-fixdate alone.
+ * - Checks the calendar as well as the shape. The pattern matches a day that does not exist:
+ *   `31 Feb`, `29 Feb 2023` and `31 Jun` are false here.
+ * - **The day name must match the date, in all three formats.** The pattern does not check it.
+ * - False for an hour above 23 and a minute above 59, which the pattern matches. False for a
+ *   second of 60: GMT rejects leap seconds.
+ * - HTTP-date is case-sensitive and fixed-width, and its zone is the literal `GMT`: a numeric
+ *   offset is false.
+ * - **An rfc850-date reads the clock.** Its two-digit year is read against the current instant
+ *   (`Temporal.Now.instant()`), as `parseHttpDate` describes, so the same string can change its
+ *   answer decades apart; if the clock cannot be read the answer is false. The other two formats
+ *   never read the clock.
+ * - False for a non-string. Read the value with `parseHttpDate`; write one with `formatHttpDate`.
+ *
+ * @param value candidate RFC 9110 HTTP-date string
+ * @returns boolean indicating validity
+ *
+ * @example isValidHttpDate("Fri, 15 Mar 2024 14:30:00 GMT") // true
+ * @example isValidHttpDate("Sun Nov  6 08:49:37 1994") // true (asctime-date; the httpDate pattern does not match it)
+ * @example isValidHttpDate("Sat, 15 Mar 2024 14:30:00 GMT") // false (15 Mar 2024 was a Friday; the httpDate pattern matches it)
+ * @example isValidHttpDate("Wed, 29 Feb 2023 14:30:00 GMT") // false (2023 has no 29 February; the httpDate pattern matches it)
+ * @example isValidHttpDate("Fri, 15 Mar 2024 24:00:00 GMT") // false (hour 24; the httpDate pattern matches it)
+ * @example isValidHttpDate("Fri, 15 Mar 2024 14:30:00 -0400") // false (not an HTTP-date)
+ * @example isValidHttpDate("not a date") // false
+ */
+export declare function isValidHttpDate(value: string): boolean;

package/dist/utc/validate/isValidHttpDate.js

@@ -0,0 +1,38 @@
+import { parseHttpDate } from "../parse/parseHttpDate.js";
+/**
+ * Return true when `value` is a real HTTP header date: the RFC 9110 §5.6.7 HTTP-date that
+ * headers like `Last-Modified`, `Date` and `Expires` carry, such as
+ * `Fri, 15 Mar 2024 14:30:00 GMT`.
+ *
+ * - True exactly when `parseHttpDate` returns a UTC string for the same value: the validator
+ *   calls the parser, so the two cannot disagree.
+ * - **All three HTTP-date formats**, which RFC 9110 §5.6.7 says a recipient "MUST accept":
+ *   IMF-fixdate, and the obsolete rfc850-date (`Sunday, 06-Nov-94 08:49:37 GMT`) and asctime-date
+ *   (`Sun Nov  6 08:49:37 1994`). The `httpDate` pattern matches IMF-fixdate alone.
+ * - Checks the calendar as well as the shape. The pattern matches a day that does not exist:
+ *   `31 Feb`, `29 Feb 2023` and `31 Jun` are false here.
+ * - **The day name must match the date, in all three formats.** The pattern does not check it.
+ * - False for an hour above 23 and a minute above 59, which the pattern matches. False for a
+ *   second of 60: GMT rejects leap seconds.
+ * - HTTP-date is case-sensitive and fixed-width, and its zone is the literal `GMT`: a numeric
+ *   offset is false.
+ * - **An rfc850-date reads the clock.** Its two-digit year is read against the current instant
+ *   (`Temporal.Now.instant()`), as `parseHttpDate` describes, so the same string can change its
+ *   answer decades apart; if the clock cannot be read the answer is false. The other two formats
+ *   never read the clock.
+ * - False for a non-string. Read the value with `parseHttpDate`; write one with `formatHttpDate`.
+ *
+ * @param value candidate RFC 9110 HTTP-date string
+ * @returns boolean indicating validity
+ *
+ * @example isValidHttpDate("Fri, 15 Mar 2024 14:30:00 GMT") // true
+ * @example isValidHttpDate("Sun Nov  6 08:49:37 1994") // true (asctime-date; the httpDate pattern does not match it)
+ * @example isValidHttpDate("Sat, 15 Mar 2024 14:30:00 GMT") // false (15 Mar 2024 was a Friday; the httpDate pattern matches it)
+ * @example isValidHttpDate("Wed, 29 Feb 2023 14:30:00 GMT") // false (2023 has no 29 February; the httpDate pattern matches it)
+ * @example isValidHttpDate("Fri, 15 Mar 2024 24:00:00 GMT") // false (hour 24; the httpDate pattern matches it)
+ * @example isValidHttpDate("Fri, 15 Mar 2024 14:30:00 -0400") // false (not an HTTP-date)
+ * @example isValidHttpDate("not a date") // false
+ */
+export function isValidHttpDate(value) {
+    return parseHttpDate(value) !== "";
+}

package/dist/utc/validate/isValidUtc.d.ts

@@ -6,6 +6,10 @@
  * - Reads RFC 9557 annotations as `Temporal.Instant.from` does: elective ones (`[foo=bar]`), a
  *   time zone annotation and a calendar annotation are ignored (an instant has neither), and an
  *   unknown critical one (`[!foo=bar]`) is rejected.
+ * - Accepts four forms beyond the timestamp shape `YYYY-MM-DDTHH:MM:SS[.f]Z`: a time without
+ *   seconds, a comma before the fraction, an expanded `±YYYYYY` year and RFC 9557 annotations.
+ *   For the plain RFC 3339 spelling that readers other than Temporal expect, use
+ *   `isValidUtcTimestamp`, which is false for all four.
  * - Rejects leap seconds (e.g., "2024-12-31T23:59:60Z").
  * - Uses Temporal.Instant.from for validation.
  * - Requires a time component — date-only strings ("2024-01-01Z") are rejected.

package/dist/utc/validate/isValidUtc.js

@@ -1,6 +1,6 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isoStringBody } from "../../internal/isoStringBody.js";
-import { isLeapSecond } from "../../plain/validate/index.js";
+import { hasSecond60 } from "../../plain/validate/index.js";
 import { utcDateTime } from "../../regex/utc-date-time.js";
 /**
  * Return true when the provided string is a valid ISO 8601 UTC datetime.
@@ -10,6 +10,10 @@ import { utcDateTime } from "../../regex/utc-date-time.js";
  * - Reads RFC 9557 annotations as `Temporal.Instant.from` does: elective ones (`[foo=bar]`), a
  *   time zone annotation and a calendar annotation are ignored (an instant has neither), and an
  *   unknown critical one (`[!foo=bar]`) is rejected.
+ * - Accepts four forms beyond the timestamp shape `YYYY-MM-DDTHH:MM:SS[.f]Z`: a time without
+ *   seconds, a comma before the fraction, an expanded `±YYYYYY` year and RFC 9557 annotations.
+ *   For the plain RFC 3339 spelling that readers other than Temporal expect, use
+ *   `isValidUtcTimestamp`, which is false for all four.
  * - Rejects leap seconds (e.g., "2024-12-31T23:59:60Z").
  * - Uses Temporal.Instant.from for validation.
  * - Requires a time component — date-only strings ("2024-01-01Z") are rejected.
@@ -27,7 +31,7 @@ import { utcDateTime } from "../../regex/utc-date-time.js";
  */
 export function isValidUtc(value) {
     const body = isoStringBody(value);
-    if (isLeapSecond(body)) {
+    if (hasSecond60(body)) {
         return false;
     }
     if (!utcDateTime.test(body)) {

package/dist/utc/validate/isValidUtcRange.js

@@ -1,5 +1,5 @@
 // fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidUtc } from "./isValidUtc.js";
 import { isObject, isOptionsArgument } from "../../internal/isObject.js";
 /**

package/dist/utc/validate/isValidUtcTimestamp.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Return true when `value` is a real UTC instant written as `YYYY-MM-DDTHH:MM:SS[.f]Z` and
+ * nothing else: a narrower check than `isValidUtc`.
+ *
+ * - The shape is one spelling of the RFC 3339 §5.6 `date-time`: a four-digit year, `0000` to
+ *   `9999` (`date-fullyear = 4DIGIT`), an upper-case `T`, a time with seconds, an optional
+ *   fraction of one to nine digits after a dot (`time-secfrac = "." 1*DIGIT`; GMT stops at nine
+ *   because Temporal keeps nanoseconds), and an upper-case `Z` with nothing after it.
+ * - Use it for a string headed for storage, or for a reader that is not Temporal: the shape is
+ *   plain RFC 3339, and the one `Temporal.Instant.prototype.toString()`, called with no options,
+ *   writes for years `0000` to `9999`.
+ * - Use `isValidUtc` when Temporal is the only reader. It also accepts a time without seconds, a
+ *   comma before the fraction, an expanded `±YYYYYY` year and RFC 9557 annotations; all four are
+ *   false here.
+ * - A subset of `isValidUtc`: every string that is true here is true there. The instant is
+ *   checked as well as the shape, so a day that does not exist is false.
+ * - False for the other spellings §5.6 allows: a lower-case `t` or `z`, a space for `T` (its
+ *   NOTE), and a numeric offset, `+00:00` included. `isValidRfc3339DateTime` checks the whole
+ *   grammar, with the same two GMT limits.
+ * - False for a leap second (`:60`), although §5.6 `time-second` admits it: GMT rejects leap
+ *   seconds because Temporal would read one as `:59`.
+ * - Not one canonical spelling: `12:00:00Z` and `12:00:00.000Z` are one instant and both are
+ *   true. A reader may still refuse or round a string that is true here: PostgreSQL has no year
+ *   `0000` and keeps microseconds. See `toPgMicroseconds` and `precision/`.
+ * - False for a non-string.
+ *
+ * @param value candidate UTC timestamp string
+ * @returns true when `value` is a real UTC instant in this shape, or false on invalid input
+ *
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00Z") // true
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00.123456789Z") // true (nine fraction digits)
+ * @example isValidUtcTimestamp("0000-01-01T00:00:00Z") // true (year 0000)
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00Z[Europe/Paris]") // false (RFC 9557 annotation; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00,5Z") // false (comma before the fraction; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("-005000-01-01T00:00:00Z") // false (expanded year; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("2026-10-06T12:00Z") // false (no seconds; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("2026-10-06t12:00:00z") // false (lower-case t and z)
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00+00:00") // false (a numeric offset, not Z)
+ * @example isValidUtcTimestamp("2026-02-30T00:00:00Z") // false (February has no 30th; the rfc3339DateTime pattern matches it)
+ * @example isValidUtcTimestamp("2016-12-31T23:59:60Z") // false (leap second)
+ * @example isValidUtcTimestamp("not a date") // false
+ */
+export declare function isValidUtcTimestamp(value: string): boolean;

package/dist/utc/validate/isValidUtcTimestamp.js

@@ -0,0 +1,48 @@
+import { rfc3339DateTime } from "../../regex/rfc-3339.js";
+import { isValidUtc } from "./isValidUtc.js";
+/**
+ * Return true when `value` is a real UTC instant written as `YYYY-MM-DDTHH:MM:SS[.f]Z` and
+ * nothing else: a narrower check than `isValidUtc`.
+ *
+ * - The shape is one spelling of the RFC 3339 §5.6 `date-time`: a four-digit year, `0000` to
+ *   `9999` (`date-fullyear = 4DIGIT`), an upper-case `T`, a time with seconds, an optional
+ *   fraction of one to nine digits after a dot (`time-secfrac = "." 1*DIGIT`; GMT stops at nine
+ *   because Temporal keeps nanoseconds), and an upper-case `Z` with nothing after it.
+ * - Use it for a string headed for storage, or for a reader that is not Temporal: the shape is
+ *   plain RFC 3339, and the one `Temporal.Instant.prototype.toString()`, called with no options,
+ *   writes for years `0000` to `9999`.
+ * - Use `isValidUtc` when Temporal is the only reader. It also accepts a time without seconds, a
+ *   comma before the fraction, an expanded `±YYYYYY` year and RFC 9557 annotations; all four are
+ *   false here.
+ * - A subset of `isValidUtc`: every string that is true here is true there. The instant is
+ *   checked as well as the shape, so a day that does not exist is false.
+ * - False for the other spellings §5.6 allows: a lower-case `t` or `z`, a space for `T` (its
+ *   NOTE), and a numeric offset, `+00:00` included. `isValidRfc3339DateTime` checks the whole
+ *   grammar, with the same two GMT limits.
+ * - False for a leap second (`:60`), although §5.6 `time-second` admits it: GMT rejects leap
+ *   seconds because Temporal would read one as `:59`.
+ * - Not one canonical spelling: `12:00:00Z` and `12:00:00.000Z` are one instant and both are
+ *   true. A reader may still refuse or round a string that is true here: PostgreSQL has no year
+ *   `0000` and keeps microseconds. See `toPgMicroseconds` and `precision/`.
+ * - False for a non-string.
+ *
+ * @param value candidate UTC timestamp string
+ * @returns true when `value` is a real UTC instant in this shape, or false on invalid input
+ *
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00Z") // true
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00.123456789Z") // true (nine fraction digits)
+ * @example isValidUtcTimestamp("0000-01-01T00:00:00Z") // true (year 0000)
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00Z[Europe/Paris]") // false (RFC 9557 annotation; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00,5Z") // false (comma before the fraction; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("-005000-01-01T00:00:00Z") // false (expanded year; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("2026-10-06T12:00Z") // false (no seconds; isValidUtc accepts it)
+ * @example isValidUtcTimestamp("2026-10-06t12:00:00z") // false (lower-case t and z)
+ * @example isValidUtcTimestamp("2026-10-06T12:00:00+00:00") // false (a numeric offset, not Z)
+ * @example isValidUtcTimestamp("2026-02-30T00:00:00Z") // false (February has no 30th; the rfc3339DateTime pattern matches it)
+ * @example isValidUtcTimestamp("2016-12-31T23:59:60Z") // false (leap second)
+ * @example isValidUtcTimestamp("not a date") // false
+ */
+export function isValidUtcTimestamp(value) {
+    // `isValidUtc` goes first: it stops a non-string before the pattern would read it as text.
+    return isValidUtc(value) && rfc3339DateTime.test(value);
+}

package/dist/workforce/calculate/dutyDayFor.d.ts

@@ -0,0 +1,38 @@
+import type { DutyDay, Interval } from "../../types/index.js";
+/**
+ * Return the operator-designated day an instant falls in: from the most recent `dayStartTime`
+ * in `timeZone` at or before the instant, up to (not including) the next one.
+ *
+ * The day an hours-of-work rule counts is the operator's, not the local midnight where the
+ * person happens to be, so the reference zone and the start time are both the caller's and
+ * neither has a default.
+ *
+ * - A `dayStartTime` that a clock change skips or repeats is resolved under `day.disambiguation`,
+ *   the CORE-4 policy in `resolveLocal`. The default, `"compatible"`, reads a skipped time after
+ *   the gap (02:30 on New York's spring-forward day is 03:30) and a repeated one at its first
+ *   pass. The day that holds the change is then shorter or longer by the change: 23 or 25 hours
+ *   across a one-hour change, 24.5 across Lord Howe's 30-minute fall-back, 21 across Casey's
+ *   three-hour jump. `"reject"` returns `null` for
+ *   a day that starts or ends at such a time.
+ * - The instant is read in `timeZone` whatever offset or zone it is written with, so a log whose
+ *   entries cross zones still falls into the reference zone's days.
+ * - A date whose start resolves onto the next date's start opens no day: the date
+ *   `Pacific/Apia` deleted in 2011 is part of no operator day.
+ * - Returns `null` when `instant` is not an ISO 8601 instant string, when `day` is not an object
+ *   with a valid `timeZone` and a `dayStartTime` that `isValidTime` accepts, and when the day or
+ *   the next one starts outside Temporal's instant range.
+ *
+ * @param instant ISO 8601 instant string to place
+ * @param day the reference zone and the local time each day starts at
+ * @returns `{ start, end }` of the day as UTC instants ending in "Z", or null on invalid input
+ *
+ * @example dutyDayFor("2024-01-01T08:59:00Z", { timeZone: "America/New_York", dayStartTime: "04:00" }) // { start: "2023-12-31T09:00:00Z", end: "2024-01-01T09:00:00Z" } — 03:59 local is the previous day
+ * @example dutyDayFor("2024-01-01T09:00:00Z", { timeZone: "America/New_York", dayStartTime: "04:00" }) // { start: "2024-01-01T09:00:00Z", end: "2024-01-02T09:00:00Z" }
+ * @example dutyDayFor("2024-03-10T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "02:30" }) // { start: "2024-03-10T07:30:00Z", end: "2024-03-11T06:30:00Z" } — 02:30 is skipped, read as 03:30; 23 hours
+ * @example dutyDayFor("2024-11-03T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "01:30" }) // { start: "2024-11-03T05:30:00Z", end: "2024-11-04T06:30:00Z" } — 01:30 is repeated, the first pass starts it; 25 hours
+ * @example dutyDayFor("2024-11-03T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "01:30", disambiguation: "later" }) // { start: "2024-11-03T06:30:00Z", end: "2024-11-04T06:30:00Z" } — the second pass; 24 hours
+ * @example dutyDayFor("2024-11-03T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "01:30", disambiguation: "reject" }) // null — the day starts at a repeated time
+ * @example dutyDayFor("2024-01-01T12:00:00Z", { timeZone: "UTC" }) // null — no dayStartTime
+ * @example dutyDayFor("2024-01-01T12:00:00Z", { timeZone: "Invalid/Zone", dayStartTime: "04:00" }) // null
+ */
+export declare function dutyDayFor(instant: string, day: DutyDay): Interval | null;

package/dist/workforce/calculate/dutyDayFor.js

@@ -0,0 +1,71 @@
+import { Temporal } from "../../internal/temporal.js";
+import { isObject, parseInstantNanoseconds, zoneFrame } from "../../internal/index.js";
+import { operatorDayScale, parseDayStartTime, } from "../../internal/dutyPeriods.js";
+import { parseScheduleDisambiguation } from "../../internal/operatingSchedule.js";
+/**
+ * Return the operator-designated day an instant falls in: from the most recent `dayStartTime`
+ * in `timeZone` at or before the instant, up to (not including) the next one.
+ *
+ * The day an hours-of-work rule counts is the operator's, not the local midnight where the
+ * person happens to be, so the reference zone and the start time are both the caller's and
+ * neither has a default.
+ *
+ * - A `dayStartTime` that a clock change skips or repeats is resolved under `day.disambiguation`,
+ *   the CORE-4 policy in `resolveLocal`. The default, `"compatible"`, reads a skipped time after
+ *   the gap (02:30 on New York's spring-forward day is 03:30) and a repeated one at its first
+ *   pass. The day that holds the change is then shorter or longer by the change: 23 or 25 hours
+ *   across a one-hour change, 24.5 across Lord Howe's 30-minute fall-back, 21 across Casey's
+ *   three-hour jump. `"reject"` returns `null` for
+ *   a day that starts or ends at such a time.
+ * - The instant is read in `timeZone` whatever offset or zone it is written with, so a log whose
+ *   entries cross zones still falls into the reference zone's days.
+ * - A date whose start resolves onto the next date's start opens no day: the date
+ *   `Pacific/Apia` deleted in 2011 is part of no operator day.
+ * - Returns `null` when `instant` is not an ISO 8601 instant string, when `day` is not an object
+ *   with a valid `timeZone` and a `dayStartTime` that `isValidTime` accepts, and when the day or
+ *   the next one starts outside Temporal's instant range.
+ *
+ * @param instant ISO 8601 instant string to place
+ * @param day the reference zone and the local time each day starts at
+ * @returns `{ start, end }` of the day as UTC instants ending in "Z", or null on invalid input
+ *
+ * @example dutyDayFor("2024-01-01T08:59:00Z", { timeZone: "America/New_York", dayStartTime: "04:00" }) // { start: "2023-12-31T09:00:00Z", end: "2024-01-01T09:00:00Z" } — 03:59 local is the previous day
+ * @example dutyDayFor("2024-01-01T09:00:00Z", { timeZone: "America/New_York", dayStartTime: "04:00" }) // { start: "2024-01-01T09:00:00Z", end: "2024-01-02T09:00:00Z" }
+ * @example dutyDayFor("2024-03-10T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "02:30" }) // { start: "2024-03-10T07:30:00Z", end: "2024-03-11T06:30:00Z" } — 02:30 is skipped, read as 03:30; 23 hours
+ * @example dutyDayFor("2024-11-03T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "01:30" }) // { start: "2024-11-03T05:30:00Z", end: "2024-11-04T06:30:00Z" } — 01:30 is repeated, the first pass starts it; 25 hours
+ * @example dutyDayFor("2024-11-03T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "01:30", disambiguation: "later" }) // { start: "2024-11-03T06:30:00Z", end: "2024-11-04T06:30:00Z" } — the second pass; 24 hours
+ * @example dutyDayFor("2024-11-03T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "01:30", disambiguation: "reject" }) // null — the day starts at a repeated time
+ * @example dutyDayFor("2024-01-01T12:00:00Z", { timeZone: "UTC" }) // null — no dayStartTime
+ * @example dutyDayFor("2024-01-01T12:00:00Z", { timeZone: "Invalid/Zone", dayStartTime: "04:00" }) // null
+ */
+export function dutyDayFor(instant, day) {
+    try {
+        if (typeof instant !== "string" || !isObject(day)) {
+            return null;
+        }
+        const { timeZone, dayStartTime } = day;
+        const disambiguation = parseScheduleDisambiguation(day);
+        const at = parseInstantNanoseconds(instant);
+        const frame = zoneFrame(timeZone);
+        const time = parseDayStartTime(dayStartTime);
+        if (at === null ||
+            frame === null ||
+            time === null ||
+            disambiguation === null) {
+            return null;
+        }
+        const span = operatorDayScale(frame, time, disambiguation).containing(at);
+        if (span === null) {
+            return null;
+        }
+        return {
+            start: Temporal.Instant.fromEpochNanoseconds(span.start).toString(),
+            end: Temporal.Instant.fromEpochNanoseconds(span.end).toString(),
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/workforce/calculate/dutyTotals.d.ts

@@ -0,0 +1,24 @@
+import type { DutyEntry, Interval } from "../../types/index.js";
+/**
+ * Return the time a duty log spends in any of `statuses` inside a window, as an exact ISO 8601
+ * duration.
+ *
+ * - The interval algebra of CORE-6: the entries in `statuses` are merged, each run is cut to
+ *   `window` (half-open), and what is left is summed. An entry that crosses the window's edge
+ *   counts only its part inside.
+ * - Hours are the largest unit, as `sumIntervals` writes it: `"PT49H30M"`, never days.
+ * - `[]` as `statuses`, an empty log or an empty window gives `"PT0S"`.
+ * - Returns `""` when the log fails `isValidDutyLog`, when `window` is not a valid `Interval`, and
+ *   when `statuses` is not an array of strings.
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param window `{ start, end }` record of ISO 8601 instant strings to total inside
+ * @param statuses the statuses whose time is totalled
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example dutyTotals([{ status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T15:00:00Z" }, { status: "onDuty", start: "2024-01-01T15:00:00Z", end: "2024-01-01T17:00:00Z" }, { status: "driving", start: "2024-01-01T17:00:00Z", end: "2024-01-01T20:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // "PT8H"
+ * @example dutyTotals([{ status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T15:00:00Z" }], { start: "2024-01-01T12:00:00Z", end: "2024-01-01T18:00:00Z" }, ["driving"]) // "PT3H" — cut at the window
+ * @example dutyTotals([], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // "PT0S"
+ * @example dutyTotals([{ status: "driving", start: "2024-01-01T15:00:00Z", end: "2024-01-01T10:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // "" — inverted entry
+ */
+export declare function dutyTotals(log: DutyEntry[], window: Interval, statuses: string[]): string;

package/dist/workforce/calculate/dutyTotals.js

@@ -0,0 +1,41 @@
+import { formatHourDuration, parseIntervalNanoseconds } from "../../internal/index.js";
+import { parseDutyLog } from "../../internal/dutyLog.js";
+import { readStatusList, timeIn } from "../../internal/dutyEngine.js";
+/**
+ * Return the time a duty log spends in any of `statuses` inside a window, as an exact ISO 8601
+ * duration.
+ *
+ * - The interval algebra of CORE-6: the entries in `statuses` are merged, each run is cut to
+ *   `window` (half-open), and what is left is summed. An entry that crosses the window's edge
+ *   counts only its part inside.
+ * - Hours are the largest unit, as `sumIntervals` writes it: `"PT49H30M"`, never days.
+ * - `[]` as `statuses`, an empty log or an empty window gives `"PT0S"`.
+ * - Returns `""` when the log fails `isValidDutyLog`, when `window` is not a valid `Interval`, and
+ *   when `statuses` is not an array of strings.
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param window `{ start, end }` record of ISO 8601 instant strings to total inside
+ * @param statuses the statuses whose time is totalled
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example dutyTotals([{ status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T15:00:00Z" }, { status: "onDuty", start: "2024-01-01T15:00:00Z", end: "2024-01-01T17:00:00Z" }, { status: "driving", start: "2024-01-01T17:00:00Z", end: "2024-01-01T20:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // "PT8H"
+ * @example dutyTotals([{ status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T15:00:00Z" }], { start: "2024-01-01T12:00:00Z", end: "2024-01-01T18:00:00Z" }, ["driving"]) // "PT3H" — cut at the window
+ * @example dutyTotals([], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // "PT0S"
+ * @example dutyTotals([{ status: "driving", start: "2024-01-01T15:00:00Z", end: "2024-01-01T10:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // "" — inverted entry
+ */
+export function dutyTotals(log, window, statuses) {
+    try {
+        const entries = parseDutyLog(log);
+        const bounds = parseIntervalNanoseconds(window);
+        const counted = readStatusList(statuses);
+        if (entries === null || bounds === null || counted === null) {
+            return "";
+        }
+        return formatHourDuration(timeIn(entries, counted, bounds.start, bounds.end));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/workforce/calculate/dutyViolations.d.ts

@@ -0,0 +1,74 @@
+import type { Disambiguation, DutyEntry, DutyRule, DutyViolation, Interval } from "../../types/index.js";
+/**
+ * Return every violation of a set of hours-of-work rules inside a range, each with the window
+ * that failed it: the record over a month, not the check before dispatch.
+ *
+ * - Each rule is checked as `evaluateDutyLog` checks it, at every instant where its answer can
+ *   change: entry bounds, those bounds shifted by a sliding window's length, where a run reaches
+ *   or falls below a floor the rule compares it with, the boundaries of its local periods, and
+ *   the instants either side of each. So the record does not depend on how a status is split
+ *   into entries.
+ * - One entry per violation. A moving window (an elapsed duration, or more than one local period)
+ *   is one violation for as long as it keeps failing, with no passing check between, reported by
+ *   the window that failed worst, the earliest on a tie. A count since a reset, or one short rest
+ *   before a duty, is one violation however often it is checked, reported by its worst check. One
+ *   fixed period is one violation, reported by its last check, which judges the period complete.
+ * - A violation is listed in the range it began in. One already failing at `range.start` belongs
+ *   to the range before; one still failing at `range.end` is followed to its worst window, which
+ *   may end after the range, but never past the log's last entry. So two adjacent ranges list
+ *   every violation once.
+ * - Each check reads the log as it stood then, so a failure stays listed when later entries would
+ *   have excused it, such as a rest that completes a pair after the window it would have moved
+ *   had closed. The record lists what a check at that moment would have said, so it only grows as
+ *   the log does.
+ * - Only logged time is judged. Nothing after the log's last entry is checked, so a range running
+ *   past the log reads as one ending with it, and a period still open there is judged as not yet
+ *   over. Nothing before the log's first entry (and, for `usageLookback`, its first use) is
+ *   checked either, so a range of any length is read as the part of it the log covers.
+ * - Time before the log is read two ways. `evaluateDutyLog` reads it strictly, for a check before
+ *   dispatch: it is neither work nor rest, so a rest rule whose window reaches back before the log
+ *   fails for want of logged rest. The record does not invent a violation there: a rest rule
+ *   (`restRequirement`, `freePeriod`, `pattern`, `restBeforeDuty`) is not judged on a window that
+ *   starts before the log's first entry. A cap is, since time no entry covers never counts towards
+ *   one. Both read the log's first entry as the start of a stretch without rest for `maxGap`.
+ * - Rules with `severity: "advisory"` are not listed: an advisory is not a violation.
+ * - Entries are ordered by window start, then by the order of `rules`.
+ * - Returns `null` for anything `evaluateDutyLog` refuses, for a `range` that is not a valid
+ *   `Interval`, when more than 10,000 of a rule's local periods end in the part of `range` the log
+ *   covers, and when one rule would need more than 1,000,000 instants checked there.
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param range `{ start, end }` record of ISO 8601 instant strings to report on
+ * @param rules the rules, every number the caller's
+ * @param options the reference zone and the operator day
+ * @returns the violations, or null on invalid input
+ *
+ * @example dutyViolations([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T10:00:00Z" }, { status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T22:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, [{ label: "11 driving", kind: "cumulativeCap", statuses: ["driving"], cap: "PT11H", since: { statuses: ["off"], consecutive: "PT10H" } }], { timeZone: "UTC" }) // [{ label: "11 driving", window: { start: "2024-01-01T10:00:00Z", end: "2024-01-01T22:00:00Z" }, used: "PT12H", limit: "PT11H" }]
+ * @example dutyViolations([], { start: "2024-01-01T00:00:00Z", end: "2024-02-01T00:00:00Z" }, [], { timeZone: "UTC" }) // []
+ * @example dutyViolations([], { start: "2024-02-01T00:00:00Z", end: "2024-01-01T00:00:00Z" }, [], { timeZone: "UTC" }) // null — inverted range
+ */
+export declare function dutyViolations(log: DutyEntry[], range: Interval, rules: DutyRule[], options: {
+    /**
+     * The reference time zone every local period is read in, an IANA name or UTC offset: a time
+     * zone identifier (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns).
+     */
+    timeZone: string;
+    /**
+     * The local wall time each operator day starts at, as an ISO PlainTime string (`"04:00"`).
+     * A rule that counts `operatorDays` needs it.
+     *
+     * @defaultValue None. A rule that counts operator days makes the call invalid.
+     */
+    dayStartTime?: string;
+    /**
+     * How a day start, or a `freePeriod` window edge, that the clock repeats or skips becomes an
+     * instant, as `resolveLocal` resolves it. `"compatible"` reads a skipped time after the gap
+     * and a repeated one at its first pass, `"earlier"` and `"later"` take that side in both
+     * cases, and `"reject"` returns the sentinel when an operator day a rule counts starts or ends
+     * at such a time, or a local window with such an edge reaches a logged free period.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
+    disambiguation?: Disambiguation;
+}): DutyViolation[] | null;

package/dist/workforce/calculate/dutyViolations.js

@@ -0,0 +1,65 @@
+import { parseIntervalNanoseconds } from "../../internal/index.js";
+import { prepareDutyCall, scanDutyViolations } from "../../internal/dutyEngine.js";
+/**
+ * Return every violation of a set of hours-of-work rules inside a range, each with the window
+ * that failed it: the record over a month, not the check before dispatch.
+ *
+ * - Each rule is checked as `evaluateDutyLog` checks it, at every instant where its answer can
+ *   change: entry bounds, those bounds shifted by a sliding window's length, where a run reaches
+ *   or falls below a floor the rule compares it with, the boundaries of its local periods, and
+ *   the instants either side of each. So the record does not depend on how a status is split
+ *   into entries.
+ * - One entry per violation. A moving window (an elapsed duration, or more than one local period)
+ *   is one violation for as long as it keeps failing, with no passing check between, reported by
+ *   the window that failed worst, the earliest on a tie. A count since a reset, or one short rest
+ *   before a duty, is one violation however often it is checked, reported by its worst check. One
+ *   fixed period is one violation, reported by its last check, which judges the period complete.
+ * - A violation is listed in the range it began in. One already failing at `range.start` belongs
+ *   to the range before; one still failing at `range.end` is followed to its worst window, which
+ *   may end after the range, but never past the log's last entry. So two adjacent ranges list
+ *   every violation once.
+ * - Each check reads the log as it stood then, so a failure stays listed when later entries would
+ *   have excused it, such as a rest that completes a pair after the window it would have moved
+ *   had closed. The record lists what a check at that moment would have said, so it only grows as
+ *   the log does.
+ * - Only logged time is judged. Nothing after the log's last entry is checked, so a range running
+ *   past the log reads as one ending with it, and a period still open there is judged as not yet
+ *   over. Nothing before the log's first entry (and, for `usageLookback`, its first use) is
+ *   checked either, so a range of any length is read as the part of it the log covers.
+ * - Time before the log is read two ways. `evaluateDutyLog` reads it strictly, for a check before
+ *   dispatch: it is neither work nor rest, so a rest rule whose window reaches back before the log
+ *   fails for want of logged rest. The record does not invent a violation there: a rest rule
+ *   (`restRequirement`, `freePeriod`, `pattern`, `restBeforeDuty`) is not judged on a window that
+ *   starts before the log's first entry. A cap is, since time no entry covers never counts towards
+ *   one. Both read the log's first entry as the start of a stretch without rest for `maxGap`.
+ * - Rules with `severity: "advisory"` are not listed: an advisory is not a violation.
+ * - Entries are ordered by window start, then by the order of `rules`.
+ * - Returns `null` for anything `evaluateDutyLog` refuses, for a `range` that is not a valid
+ *   `Interval`, when more than 10,000 of a rule's local periods end in the part of `range` the log
+ *   covers, and when one rule would need more than 1,000,000 instants checked there.
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param range `{ start, end }` record of ISO 8601 instant strings to report on
+ * @param rules the rules, every number the caller's
+ * @param options the reference zone and the operator day
+ * @returns the violations, or null on invalid input
+ *
+ * @example dutyViolations([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T10:00:00Z" }, { status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T22:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, [{ label: "11 driving", kind: "cumulativeCap", statuses: ["driving"], cap: "PT11H", since: { statuses: ["off"], consecutive: "PT10H" } }], { timeZone: "UTC" }) // [{ label: "11 driving", window: { start: "2024-01-01T10:00:00Z", end: "2024-01-01T22:00:00Z" }, used: "PT12H", limit: "PT11H" }]
+ * @example dutyViolations([], { start: "2024-01-01T00:00:00Z", end: "2024-02-01T00:00:00Z" }, [], { timeZone: "UTC" }) // []
+ * @example dutyViolations([], { start: "2024-02-01T00:00:00Z", end: "2024-01-01T00:00:00Z" }, [], { timeZone: "UTC" }) // null — inverted range
+ */
+export function dutyViolations(log, range, rules, options) {
+    try {
+        const bounds = parseIntervalNanoseconds(range);
+        const call = prepareDutyCall(log, rules, options);
+        if (bounds === null || call === null) {
+            return null;
+        }
+        return scanDutyViolations(call.context, call.rules, bounds);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/workforce/calculate/evaluateDutyLog.d.ts

@@ -0,0 +1,77 @@
+import type { Disambiguation, DutyEntry, DutyReport, DutyRule } from "../../types/index.js";
+/**
+ * Evaluate every hours-of-work rule over a duty log at one instant, and report each one whether
+ * or not it binds.
+ *
+ * GMT implements no regulation: each rule is a shape, and every number in it is the caller's. A
+ * regime is the array of rules the caller assembles and labels. GMT reports totals, what is left
+ * and what failed; it does not decide dispatch, fitness or eligibility.
+ *
+ * - The log is read as it stands at `at`: later entries are ignored and one straddling `at` is cut
+ *   there. Time no entry covers is in no status, so it is neither work nor rest. That includes the
+ *   time before the log's first entry: give a log that reaches back as far as the longest rule
+ *   looks, or a rest rule fails for want of logged rest. A planned roster is the same call with
+ *   the plan appended and `at` set to its end.
+ * - This is the strict reading, for a check before dispatch. `dutyViolations` reads a record the
+ *   other way: it does not judge a rest rule on a window that starts before the log's first
+ *   entry, since the log cannot say what happened then. Both read the log's first entry as the
+ *   start of a stretch without rest for `maxGap`, as the end of a rest would be.
+ * - Every outcome carries `used`, `limit`, `remaining`, `window`, `dueBy` and `resetAt`, so the
+ *   second-tightest limit is visible before it binds. Failed rules are listed again under
+ *   `violations` or, with `severity: "advisory"`, under `advisories` only.
+ * - A duration in a `Period` is a sliding window ending at `at`; `operatorDays` are the days of
+ *   `dutyDayFor`; calendar days, ISO weeks, months and years are local periods in `timeZone`,
+ *   23 or 25 hours long across a one-hour clock change. Each outcome names its `periodBasis`.
+ * - The local periods are the ones holding the last instant before `at`, so at a boundary the
+ *   period just ended is judged: a roster ending at midnight is checked through its last day.
+ * - A window that runs past `at` (the rest of today, this week) has not failed a minimum while
+ *   the minimum could still be met with rest from `at` to its end; a cap fails as soon as it is
+ *   passed.
+ * - Endpoints are UTC instants ending in "Z"; durations are ISO 8601 with hours as the largest
+ *   unit (`"PT49H30M"`).
+ * - Returns `null` when the log fails `isValidDutyLog`, when `at` is not an ISO 8601 instant
+ *   string, when a rule is malformed (an unknown kind, a status list that is empty or holds a
+ *   non-string, a duration that is not positive exact time, a malformed period, a duplicate
+ *   label, a count of periods past 10,000 alone or times `adjacent`, `lookback` or `periods`, a
+ *   `containing.count` past 10,000), when `options.timeZone` is invalid, when a rule counts
+ *   `operatorDays` without `options.dayStartTime`, when a window, or a requirement `orFactor`
+ *   scales, falls outside Temporal's range, when a count of free periods passes
+ *   `Number.MAX_SAFE_INTEGER`, and when one run of rest in a `freePeriod` window holds more than
+ *   20,000 of its `containing` windows (about 54 years of a daily window).
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param at ISO 8601 instant string to evaluate at
+ * @param rules the rules, every number the caller's
+ * @param options the reference zone and the operator day
+ * @returns the report, or null on invalid input
+ *
+ * @example evaluateDutyLog([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T10:00:00Z" }, { status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T21:00:00Z" }], "2024-01-01T21:00:00Z", [{ label: "11 driving", kind: "cumulativeCap", statuses: ["driving"], cap: "PT11H", since: { statuses: ["off"], consecutive: "PT10H" } }], { timeZone: "UTC" }) // { at: "2024-01-01T21:00:00Z", outcomes: [{ label: "11 driving", kind: "cumulativeCap", severity: "violation", satisfied: true, used: "PT11H", limit: "PT11H", remaining: "PT0S", window: { start: "2024-01-01T10:00:00Z", end: "2024-01-01T21:00:00Z" }, periodBasis: null, dueBy: null, resetAt: "2024-01-01T10:00:00Z" }], violations: [], advisories: [] }
+ * @example evaluateDutyLog([{ status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T21:00:00Z" }], "2024-01-01T21:00:00Z", [{ label: "60 in 7", kind: "rollingCap", statuses: ["driving"], cap: "PT60H", window: { operatorDays: 7 } }], { timeZone: "UTC" }) // null — operator days without dayStartTime
+ * @example evaluateDutyLog([], "2024-01-01T00:00:00Z", [], { timeZone: "UTC" }) // { at: "2024-01-01T00:00:00Z", outcomes: [], violations: [], advisories: [] }
+ * @example evaluateDutyLog([{ status: "on", start: "2024-01-01T02:00:00Z", end: "2024-01-01T01:00:00Z" }], "2024-01-01T03:00:00Z", [], { timeZone: "UTC" }) // null — inverted entry
+ */
+export declare function evaluateDutyLog(log: DutyEntry[], at: string, rules: DutyRule[], options: {
+    /**
+     * The reference time zone every local period is read in, an IANA name or UTC offset: a time
+     * zone identifier (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns). A log kept in another clock is converted to instants first.
+     */
+    timeZone: string;
+    /**
+     * The local wall time each operator day starts at, as an ISO PlainTime string (`"04:00"`).
+     * A rule that counts `operatorDays` needs it.
+     *
+     * @defaultValue None. A rule that counts operator days makes the call invalid.
+     */
+    dayStartTime?: string;
+    /**
+     * How a day start, or a `freePeriod` window edge, that the clock repeats or skips becomes an
+     * instant, as `resolveLocal` resolves it. `"compatible"` reads a skipped time after the gap
+     * and a repeated one at its first pass, `"earlier"` and `"later"` take that side in both
+     * cases, and `"reject"` returns the sentinel when an operator day a rule counts starts or ends
+     * at such a time, or a local window with such an edge reaches a logged free period.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
+    disambiguation?: Disambiguation;
+}): DutyReport | null;