@northguild/gmt 1.18.0 → 1.19.0

package/dist/intermodal/validate/isValidX12DateTimeRange.js

@@ -0,0 +1,33 @@
+import { parseX12DateTimeRange } from "../parse/parseX12DateTimeRange.js";
+/**
+ * Return true when `value` is an X12 Date Time Period value (data element 1251) that states a
+ * range between two real local date-times, in a date-time range format qualifier (data element
+ * 1250).
+ *
+ * ### Format codes
+ * | Code | Mask | The dictionary's definition |
+ * |---|---|---|
+ * | `RDT` | `CCYYMMDDHHMM-CCYYMMDDHHMM` | "Range of Date and Time, Expressed in Format CCYYMMDDHHMM-CCYYMMDDHHMM" |
+ * | `DTS` | `CCYYMMDDHHMMSS-CCYYMMDDHHMMSS` | "Range of Date and Time Expressed in Format CCYYMMDDHHMMSS-CCYYMMDDHHMMSS" |
+ *
+ * - True exactly when `parseX12DateTimeRange` returns a range for the same arguments: the
+ *   validator calls the parser, so the two cannot disagree.
+ * - A range is valid with exactly one hyphen, and only against its code.
+ * - A range whose end precedes its start is false; an end equal to its start is true.
+ * - Checks the calendar as well as the shape: hour 24, second 60 and 29 February 2023 are
+ *   false.
+ * - False for any other code, a code of another kind included; check a code alone with
+ *   `isValidX12DateTimePeriodFormat`. False for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "202406151430-202406201600")
+ * @param format X12 data element 1250 format qualifier
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12DateTimeRange("202406151430-202406201600", "RDT") // true
+ * @example isValidX12DateTimeRange("20240615143045-20240620160030", "DTS") // true
+ * @example isValidX12DateTimeRange("202406151430202406201600", "RDT") // false (a range is transmitted with its hyphen)
+ * @example isValidX12DateTimeRange("202406151431-202406151430", "RDT") // false (the end precedes the start)
+ */
+export function isValidX12DateTimeRange(value, format) {
+    return parseX12DateTimeRange(value, format) !== null;
+}

package/dist/intermodal/validate/isValidX12Time.d.ts

@@ -0,0 +1,38 @@
+import type { X12TimeFormat } from "../../types/edi.js";
+/**
+ * Return true when `value` is an X12 time that states a real time of day: a data element 337
+ * value with no qualifier, or a time that fits the data element 1250 format qualifier it
+ * arrived with.
+ *
+ * ### Forms
+ * | `format` | Digits | Mask | The dictionary's definition |
+ * |---|---|---|---|
+ * | omitted | 4, 6, 7 or 8 | `HHMM`, `HHMMSS`, `HHMMSSD`, `HHMMSSDD` | Element 337: "H = hours (00-23), M = minutes (00-59), S = integer seconds (00-59) … D = tenths (0-9) and DD = hundredths (00-99)" |
+ * | `TM` | 4 | `HHMM` | "Time Expressed in Format HHMM" |
+ * | `TS` | 6 | `HHMMSS` | "Time Expressed in Format HHMMSS" |
+ *
+ * - True exactly when `parseX12Time` returns a time for the same arguments: the validator calls
+ *   the parser, so the two cannot disagree.
+ * - Omit `format` for the time element of a freight segment (`AT7-06`, `G62-04`, `DTM-03`),
+ *   which has no qualifier. Pass it for a time that arrives with one (`DTP-02` and `DTP-03`,
+ *   `DTM-05` and `DTM-06`).
+ * - A qualifier is strict: `"143045"` is false under `TM`, and a 7- or 8-digit value is false
+ *   under either qualifier, although all three are true with none.
+ * - A `format` that is present and is not `TM` or `TS` is false.
+ * - Hour 24, minute 60, second 60 and a value of 5 or 9 digits are false.
+ * - False for a non-string value.
+ *
+ * @param value The time as transmitted (e.g. "1430")
+ * @param format X12 data element 1250 format qualifier the time arrived with; omit it for a data element 337 value
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12Time("1430") // true
+ * @example isValidX12Time("1430", "TM") // true
+ * @example isValidX12Time("143045", "TS") // true
+ * @example isValidX12Time("14300012") // true (hundredths of a second)
+ * @example isValidX12Time("14300012", "TS") // false (no 1250 code holds decimal seconds)
+ * @example isValidX12Time("143045", "TM") // false (six digits is a TS value)
+ * @example isValidX12Time("2430") // false (hour 24)
+ * @example isValidX12Time("14304") // false (five digits is not an element 337 form)
+ */
+export declare function isValidX12Time(value: string, format?: X12TimeFormat): boolean;

package/dist/intermodal/validate/isValidX12Time.js

@@ -0,0 +1,40 @@
+import { parseX12Time } from "../parse/parseX12Time.js";
+/**
+ * Return true when `value` is an X12 time that states a real time of day: a data element 337
+ * value with no qualifier, or a time that fits the data element 1250 format qualifier it
+ * arrived with.
+ *
+ * ### Forms
+ * | `format` | Digits | Mask | The dictionary's definition |
+ * |---|---|---|---|
+ * | omitted | 4, 6, 7 or 8 | `HHMM`, `HHMMSS`, `HHMMSSD`, `HHMMSSDD` | Element 337: "H = hours (00-23), M = minutes (00-59), S = integer seconds (00-59) … D = tenths (0-9) and DD = hundredths (00-99)" |
+ * | `TM` | 4 | `HHMM` | "Time Expressed in Format HHMM" |
+ * | `TS` | 6 | `HHMMSS` | "Time Expressed in Format HHMMSS" |
+ *
+ * - True exactly when `parseX12Time` returns a time for the same arguments: the validator calls
+ *   the parser, so the two cannot disagree.
+ * - Omit `format` for the time element of a freight segment (`AT7-06`, `G62-04`, `DTM-03`),
+ *   which has no qualifier. Pass it for a time that arrives with one (`DTP-02` and `DTP-03`,
+ *   `DTM-05` and `DTM-06`).
+ * - A qualifier is strict: `"143045"` is false under `TM`, and a 7- or 8-digit value is false
+ *   under either qualifier, although all three are true with none.
+ * - A `format` that is present and is not `TM` or `TS` is false.
+ * - Hour 24, minute 60, second 60 and a value of 5 or 9 digits are false.
+ * - False for a non-string value.
+ *
+ * @param value The time as transmitted (e.g. "1430")
+ * @param format X12 data element 1250 format qualifier the time arrived with; omit it for a data element 337 value
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12Time("1430") // true
+ * @example isValidX12Time("1430", "TM") // true
+ * @example isValidX12Time("143045", "TS") // true
+ * @example isValidX12Time("14300012") // true (hundredths of a second)
+ * @example isValidX12Time("14300012", "TS") // false (no 1250 code holds decimal seconds)
+ * @example isValidX12Time("143045", "TM") // false (six digits is a TS value)
+ * @example isValidX12Time("2430") // false (hour 24)
+ * @example isValidX12Time("14304") // false (five digits is not an element 337 form)
+ */
+export function isValidX12Time(value, format) {
+    return parseX12Time(value, format) !== "";
+}

package/dist/intermodal/validate/isValidX12TimeCode.d.ts

@@ -0,0 +1,38 @@
+import type { X12TimeCode } from "../../types/edi.js";
+/**
+ * Return true when `timeCode` is one of the 56 X12 data element 623 time codes, the codes
+ * `x12TimeCodeOffset` and `x12TimeCodeZone` read between them.
+ *
+ * - The codes are `01`–`29`, `GM`, `UT`, `LT` and the named zone codes (`AD`, `AS`, `AT`, `CD`,
+ *   `CS`, `CT`, `ED`, `ES`, `ET`, `HD`, `HS`, `HT`, `MD`, `MS`, `MT`, `ND`, `NS`, `NT`, `PD`,
+ *   `PS`, `PT`, `TD`, `TS`, `TT`), release 008010, read from
+ *   [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-008010/element/623); the X12
+ *   text itself was not reached.
+ * - **The function takes no release, so it accepts the superset.**
+ *   [Release 005010](https://www.stedi.com/edi/x12-005010/element/623) has 51 of the codes:
+ *   `25`–`29` were added in release 006010 and are not valid in an 004010 or 005010 interchange,
+ *   although this returns true for them.
+ * - `TS`, `TT`, `CD` and `MD` are codes of data element 1250 too, with unrelated meanings there.
+ *   True here says the value is a time code; check a format qualifier with
+ *   `isValidX12DateTimePeriodFormat`.
+ * - Membership is by the list, never by shape: `00` and `30` are two digits and are not codes.
+ * - Matching is exact: two characters, upper case, no padding.
+ * - Accepts any input type and returns false for non-string values.
+ * - True exactly when one of `x12TimeCodeOffset` and `x12TimeCodeZone` returns a value: the 31
+ *   codes that state an offset and the 25 that name a zone are the 56. A valid code says the
+ *   value is in the list, not that it carries an offset: `ES` is valid and names a zone.
+ *   `classifyX12TimeCode` says which of the two a code is, and narrows it for that reader.
+ *
+ * @param timeCode candidate value of any type
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12TimeCode("ES") // true
+ * @example isValidX12TimeCode("13") // true
+ * @example isValidX12TimeCode("LT") // true
+ * @example isValidX12TimeCode("27") // true (in release 006010 and later)
+ * @example isValidX12TimeCode("et") // false (case is exact)
+ * @example isValidX12TimeCode("30") // false (not a 623 code)
+ * @example isValidX12TimeCode("EST") // false (an abbreviation, not a 623 code)
+ * @example isValidX12TimeCode(null) // false
+ */
+export declare function isValidX12TimeCode(timeCode: unknown): timeCode is X12TimeCode;

package/dist/intermodal/validate/isValidX12TimeCode.js

@@ -0,0 +1,41 @@
+import { X12_TIME_CODES } from "../../internal/index.js";
+/**
+ * Return true when `timeCode` is one of the 56 X12 data element 623 time codes, the codes
+ * `x12TimeCodeOffset` and `x12TimeCodeZone` read between them.
+ *
+ * - The codes are `01`–`29`, `GM`, `UT`, `LT` and the named zone codes (`AD`, `AS`, `AT`, `CD`,
+ *   `CS`, `CT`, `ED`, `ES`, `ET`, `HD`, `HS`, `HT`, `MD`, `MS`, `MT`, `ND`, `NS`, `NT`, `PD`,
+ *   `PS`, `PT`, `TD`, `TS`, `TT`), release 008010, read from
+ *   [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-008010/element/623); the X12
+ *   text itself was not reached.
+ * - **The function takes no release, so it accepts the superset.**
+ *   [Release 005010](https://www.stedi.com/edi/x12-005010/element/623) has 51 of the codes:
+ *   `25`–`29` were added in release 006010 and are not valid in an 004010 or 005010 interchange,
+ *   although this returns true for them.
+ * - `TS`, `TT`, `CD` and `MD` are codes of data element 1250 too, with unrelated meanings there.
+ *   True here says the value is a time code; check a format qualifier with
+ *   `isValidX12DateTimePeriodFormat`.
+ * - Membership is by the list, never by shape: `00` and `30` are two digits and are not codes.
+ * - Matching is exact: two characters, upper case, no padding.
+ * - Accepts any input type and returns false for non-string values.
+ * - True exactly when one of `x12TimeCodeOffset` and `x12TimeCodeZone` returns a value: the 31
+ *   codes that state an offset and the 25 that name a zone are the 56. A valid code says the
+ *   value is in the list, not that it carries an offset: `ES` is valid and names a zone.
+ *   `classifyX12TimeCode` says which of the two a code is, and narrows it for that reader.
+ *
+ * @param timeCode candidate value of any type
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12TimeCode("ES") // true
+ * @example isValidX12TimeCode("13") // true
+ * @example isValidX12TimeCode("LT") // true
+ * @example isValidX12TimeCode("27") // true (in release 006010 and later)
+ * @example isValidX12TimeCode("et") // false (case is exact)
+ * @example isValidX12TimeCode("30") // false (not a 623 code)
+ * @example isValidX12TimeCode("EST") // false (an abbreviation, not a 623 code)
+ * @example isValidX12TimeCode(null) // false
+ */
+export function isValidX12TimeCode(timeCode) {
+    return (typeof timeCode === "string" &&
+        X12_TIME_CODES.includes(timeCode));
+}

package/dist/internal/businessCalendar.js

@@ -1,6 +1,8 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDate } from "../plain/validate/isValidDate.js";
 import { isValidTimeZone } from "../zoned/validate/isValidTimeZone.js";
+import { isObject } from "./isObject.js";
+import { isoYearString } from "./isoYearString.js";
 const ISO_WEEKDAYS = 7;
 /**
  * The weekend GMT assumed before calendars existed: Saturday and Sunday, no holidays. It is
@@ -59,9 +61,7 @@ export function parseHolidays(holidays) {
  * absent calendar as the default Saturday–Sunday week.
  */
 export function parseBusinessCalendar(calendar) {
-    if (typeof calendar !== "object" ||
-        calendar === null ||
-        Array.isArray(calendar)) {
+    if (!isObject(calendar) || Array.isArray(calendar)) {
         return null;
     }
     const { weekend, holidays, timeZone } = calendar;
@@ -106,8 +106,6 @@ const EPOCH_WEEKDAY_OFFSET = 3;
 const DAYS_PER_400_YEARS = 146_097;
 /** Days from 0000-03-01, the start of a March-based year, to 1970-01-01. */
 const DAYS_FROM_MARCH_0000_TO_EPOCH = 719_468;
-/** TC39 `PadISOYear`: years 0–9999 print with four digits, any other with a sign and six. */
-const MAX_FOUR_DIGIT_YEAR = 9999;
 /**
  * Days from 1970-01-01 to an ISO date, in the proleptic Gregorian calendar of ECMA-262 §21.4.1
  * that Temporal's ISO calendar extends. Years run from March so the leap day ends each one.
@@ -147,10 +145,7 @@ function isoFieldsOf(epochDay) {
 /** `Temporal.PlainDate#toString` for an ISO date, which is how `holidays` stores its dates. */
 function isoDateString(epochDay) {
     const [year, month, day] = isoFieldsOf(epochDay);
-    const yearText = year < 0 || year > MAX_FOUR_DIGIT_YEAR
-        ? `${year < 0 ? "-" : "+"}${String(Math.abs(year)).padStart(6, "0")}`
-        : String(year).padStart(4, "0");
-    return `${yearText}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+    return `${isoYearString(year)}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
 }
 /**
  * Days from 1970-01-01 to `date`, an ISO-calendar date. Any other calendar throws a

package/dist/internal/dutyEngine.d.ts

@@ -0,0 +1,125 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { Disambiguation, DutyViolation, RuleOutcome } from "../types/index.js";
+import { type DutyLogEntry, type DutyRun } from "./dutyLog.js";
+import { type ResolvedWallClock, type UnitScale, type UnitSpan } from "./dutyPeriods.js";
+import { type ResolvedPair, type ResolvedPeriod, type ResolvedRule, type StatusSet } from "./dutyRules.js";
+import { type ZoneFrame } from "./zoneFrame.js";
+/** Everything one call evaluates its rules against. */
+export type DutyContext = {
+    entries: readonly DutyLogEntry[];
+    frame: ZoneFrame;
+    dayStartTime: Temporal.PlainTime | null;
+    /** How a day start or local window edge the zone repeats or skips is resolved. */
+    disambiguation: Disambiguation;
+    scales: Map<string, UnitScale>;
+    /** Local window edges already resolved, by local date-time: Temporal resolves each once. */
+    wallClocks: Map<string, ResolvedWallClock | null>;
+    /**
+     * Local window instances already resolved, by window: separate stretches of local dates, each
+     * with the span it covers.
+     */
+    windowInstances: Map<string, WindowInstances[]>;
+    /** The runs of the whole log in a set of statuses, found once per call. */
+    runs: Map<StatusSet, DutyRun[]>;
+};
+/** A window a call cannot place in Temporal's range. Caught by the public function. */
+export declare class Unrepresentable extends RangeError {
+}
+/**
+ * Read the log, rules and options `evaluateDutyLog` and `dutyViolations` take, all-or-nothing.
+ *
+ * - `options` must be an object with a valid `timeZone`; `dayStartTime` is optional, but a rule
+ *   that counts operator days needs it; `disambiguation` is `"compatible"` when absent. Each
+ *   member is read once.
+ *
+ * @param log candidate duty log
+ * @param rules candidate rules
+ * @param options candidate `{ timeZone, dayStartTime?, disambiguation? }`
+ * @returns the context and resolved rules, or null on invalid input
+ */
+export declare function prepareDutyCall(log: unknown, rules: unknown, options: unknown): {
+    context: DutyContext;
+    rules: ResolvedRule[];
+} | null;
+type StatusTest = StatusSet | ((status: string) => boolean);
+/**
+ * Read a status list a helper takes: an array of strings, `[]` allowed. Each element is read once.
+ *
+ * @param value candidate status list
+ * @returns the statuses, or null when `value` is not an array of strings
+ */
+export declare function readStatusList(value: unknown): StatusSet | null;
+/**
+ * Maximal runs of touching entries whose status passes `test`, merged as `mergeIntervals` merges
+ * them (CORE-6): touching entries join, and a gap or another status ends a run.
+ */
+export declare function runsOf(log: readonly DutyLogEntry[], test: StatusTest): DutyRun[];
+/** The parts of runs inside `[from, to)`, empty parts dropped. */
+export declare function clipRuns(runs: readonly DutyRun[], from: bigint, to: bigint): DutyRun[];
+/** Time in `statuses` inside `[from, to)`. */
+export declare function timeIn(log: readonly DutyLogEntry[], statuses: StatusTest, from: bigint, to: bigint): bigint;
+/**
+ * The paired rests among runs of rest: two runs in a row, each shorter than `fullRest` and at
+ * least `pair.each`, the longer at least `pair.one` and both together at least `pair.combined`.
+ *
+ * - A run of `fullRest` or more is a rest on its own: it pairs with nothing, and no pair spans it.
+ * - A run shorter than `pair.each` is neither half of a pair nor a break between two runs.
+ * - Pairs may chain: of runs a, b and c, both (a, b) and (b, c) are returned when both qualify.
+ *
+ * @param runs runs of rest, in order
+ * @param fullRest the length at which a run is a full rest
+ * @param pair the three floors
+ * @returns the qualifying pairs, in order
+ */
+export declare function restPairs(runs: readonly DutyRun[], fullRest: bigint, pair: ResolvedPair): {
+    first: DutyRun;
+    second: DutyRun;
+}[];
+/** One local window on one local date, resolved; `rejected` as `resolveWallClock` reports it. */
+type WindowInstance = {
+    start: bigint;
+    end: bigint;
+    rejected: boolean;
+};
+/** The instances of one local window on the local dates `first` to `last`, covering `[from, to)`. */
+type WindowInstances = {
+    from: bigint;
+    to: bigint;
+    first: Temporal.PlainDate;
+    last: Temporal.PlainDate;
+    instances: WindowInstance[];
+};
+/**
+ * Evaluate every rule at one instant.
+ *
+ * @param context the call's context
+ * @param rules the resolved rules
+ * @param at the instant, epoch nanoseconds
+ * @returns one outcome per rule, in order
+ */
+export declare function evaluateDutyRules(context: DutyContext, rules: readonly ResolvedRule[], at: bigint): RuleOutcome[];
+/**
+ * Call `visit` with the end of every period of `scale` that ends inside `(from, until]`, starting
+ * with the one `from` falls in.
+ *
+ * - Throws `Unrepresentable` when more than `MAX_PERIOD_COUNT` periods end there, or for a period
+ *   Temporal cannot hold.
+ * - A span of `MAX_PERIOD_COUNT + 1` times `LONGER_THAN_ANY` or more certainly holds more ends
+ *   than that, so it is refused without a lookup. A shorter span is walked, and the walk decides.
+ */
+export declare function walkBoundaries(scale: UnitScale, unit: Extract<ResolvedPeriod, {
+    kind: "units";
+}>["unit"], from: bigint, until: bigint, visit: (boundary: bigint) => void): void;
+/**
+ * Every violation of the rules whose severity is `"violation"` inside a range. A moving window's
+ * failures are one violation while no check passes between them; a count since a reset, or one
+ * fixed period, is one violation however often it is checked. Each is reported by its worst
+ * window and listed in the range it began in.
+ *
+ * @param context the call's context
+ * @param rules the resolved rules
+ * @param range the range, epoch nanoseconds
+ * @returns the violations, ordered by window start and then by rule
+ */
+export declare function scanDutyViolations(context: DutyContext, rules: readonly ResolvedRule[], range: UnitSpan): DutyViolation[];
+export {};