@northguild/gmt 1.18.0 → 1.20.0

package/dist/internal/cutoffAtResolved.js

@@ -0,0 +1,162 @@
+import { Temporal } from "./temporal.js";
+import { parseBusinessCalendar, } from "./businessCalendar.js";
+import { rollBusinessDate } from "./rollBusinessDate.js";
+import { earlierOccurrence } from "./earlierOccurrence.js";
+import { isRollConventionName, isTimeString, isZoneId } from "./inputChecks.js";
+import { zoneFrame } from "./zoneFrame.js";
+/**
+ * Validate the options a whole stack shares, parsing the calendar once.
+ *
+ * @param timeZone the zone the cut-offs are read in
+ * @param calendar the working week and holidays, or `undefined`
+ * @param roll the roll convention, or `undefined`
+ * @returns the shared options, or `null` when any is invalid, or only one of `calendar` and
+ * `roll` is given (no standard supplies either one by default)
+ *
+ * @example resolveSharedCutoffOptions("Europe/Amsterdam", undefined, undefined) // { timeZone: "Europe/Amsterdam", rolling: null }
+ * @example resolveSharedCutoffOptions("Europe/Amsterdam", undefined, "preceding") // null (a roll needs a calendar)
+ * @example resolveSharedCutoffOptions("Not/AZone", undefined, undefined) // null
+ */
+export function resolveSharedCutoffOptions(timeZone, calendar, roll) {
+    if (typeof timeZone !== "string" || !isZoneId(timeZone)) {
+        return null;
+    }
+    const frame = zoneFrame(timeZone);
+    if (frame === null) {
+        return null;
+    }
+    const parsed = calendar === undefined ? null : parseBusinessCalendar(calendar);
+    if (calendar !== undefined && parsed === null) {
+        return null;
+    }
+    if (roll !== undefined && !isRollConventionName(roll)) {
+        return null;
+    }
+    // Rolling needs both a calendar and a direction, and no standard supplies either one by
+    // default: a calendar without a roll, or a roll without a calendar, is a missing term.
+    if ((calendar === undefined) !== (roll === undefined)) {
+        return null;
+    }
+    return {
+        timeZone,
+        frame,
+        rolling: parsed === null || roll === undefined
+            ? null
+            : { calendar: parsed, roll: roll },
+    };
+}
+/**
+ * Validate an entry's local time of day.
+ *
+ * @param atLocalTime the local time of day, or `undefined` for none
+ * @returns `{ time }` (`time` is `null` for none), or `null` when it is not a valid time
+ *
+ * @example resolveCutoffTime("17:00") // { time: PlainTime 17:00 }
+ * @example resolveCutoffTime(undefined) // { time: null }
+ * @example resolveCutoffTime("25:00") // null
+ */
+export function resolveCutoffTime(atLocalTime) {
+    if (atLocalTime === undefined) {
+        return { time: null };
+    }
+    if (typeof atLocalTime !== "string" || !isTimeString(atLocalTime)) {
+        return null;
+    }
+    return { time: Temporal.PlainTime.from(atLocalTime) };
+}
+/** The calendar part of a duration — years, months, weeks and days. */
+function datePart(offset) {
+    return Temporal.Duration.from({
+        years: offset.years,
+        months: offset.months,
+        weeks: offset.weeks,
+        days: offset.days,
+    });
+}
+/** The exact part of a duration — hours and smaller. */
+function timePart(offset) {
+    return Temporal.Duration.from({
+        hours: offset.hours,
+        minutes: offset.minutes,
+        seconds: offset.seconds,
+        milliseconds: offset.milliseconds,
+        microseconds: offset.microseconds,
+        nanoseconds: offset.nanoseconds,
+    });
+}
+/**
+ * The offset taken off the anchor with no pinning: the calendar part moves the local wall
+ * clock, then the exact part comes off in exact time — Temporal's `ZonedDateTime#subtract`,
+ * except that a wall clock landing in a skipped hour is `null` rather than moved forward.
+ */
+function subtractOffset(anchor, offset, frame) {
+    const calendarPart = datePart(offset);
+    if (calendarPart.blank) {
+        return anchor.subtract(timePart(offset));
+    }
+    const wall = earlierOccurrence(anchor.toPlainDateTime().subtract(calendarPart), frame);
+    return wall === null ? null : wall.subtract(timePart(offset));
+}
+/**
+ * The local date the cut-off falls on after rolling, or `null` when the roll fails. With no
+ * calendar the date is left as it is.
+ */
+function rolledDate(date, shared) {
+    if (shared.rolling === null) {
+        return date;
+    }
+    const { calendar, roll } = shared.rolling;
+    try {
+        return rollBusinessDate(date, roll, calendar);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One cut-off over options already validated: the deadline `duration` before `anchor`, as
+ * `cutoffAt` defines it.
+ *
+ * @param anchor the event the deadline counts back from
+ * @param duration the offset before the anchor
+ * @param atLocalTime the local time of day to pin to, or `null` for none
+ * @param shared the zone and roll the whole stack shares
+ * @returns the cut-off as a zoned string and its epoch nanoseconds, or `null` when it falls in
+ * a skipped local hour or the roll runs out
+ *
+ * @example cutoffAtResolved(Temporal.Instant.from("2024-06-14T16:00:00Z"), Temporal.Duration.from("P2D"), Temporal.PlainTime.from("17:00"), { timeZone: "Europe/Amsterdam", rolling: null })?.text // "2024-06-12T17:00:00+02:00[Europe/Amsterdam]"
+ */
+export function cutoffAtResolved(anchor, duration, atLocalTime, shared) {
+    try {
+        const found = cutoffZoned(anchor.toZonedDateTimeISO(shared.timeZone), duration, atLocalTime, shared);
+        return found === null
+            ? null
+            : { text: found.toString(), ns: found.epochNanoseconds };
+    }
+    catch {
+        return null;
+    }
+}
+function cutoffZoned(start, duration, atLocalTime, shared) {
+    if (atLocalTime !== null) {
+        const day = rolledDate(start
+            .subtract(timePart(duration))
+            .toPlainDate()
+            .subtract(datePart(duration)), shared);
+        return day === null
+            ? null
+            : earlierOccurrence(day.toPlainDateTime(atLocalTime), shared.frame);
+    }
+    const cutoff = subtractOffset(start, duration, shared.frame);
+    if (cutoff === null) {
+        return null;
+    }
+    const day = rolledDate(cutoff.toPlainDate(), shared);
+    if (day === null) {
+        return null;
+    }
+    if (day.equals(cutoff.toPlainDate())) {
+        return cutoff;
+    }
+    return earlierOccurrence(day.toPlainDateTime(cutoff.toPlainTime()), shared.frame);
+}

package/dist/internal/cycleFieldValue.d.ts

@@ -12,8 +12,6 @@
  *   rule, not a standard's: a cycle always moves the way `amount` points, and the nearest
  *   multiple can lie the other way — e.g. minute `22` cycled by `+15` with `round: true` lands on
  *   `30` (the next multiple of 15 above 22), not `15` (the nearest multiple).
- * - Comparison: `@internationalized/date`'s `CycleOptions.round` rounds a bounded field the same
- *   way.
  *
  * @param current the field's current numeric value
  * @param amount signed amount to cycle by

package/dist/internal/cycleFieldValue.js

@@ -12,8 +12,6 @@
  *   rule, not a standard's: a cycle always moves the way `amount` points, and the nearest
  *   multiple can lie the other way — e.g. minute `22` cycled by `+15` with `round: true` lands on
  *   `30` (the next multiple of 15 above 22), not `15` (the nearest multiple).
- * - Comparison: `@internationalized/date`'s `CycleOptions.round` rounds a bounded field the same
- *   way.
  *
  * @param current the field's current numeric value
  * @param amount signed amount to cycle by

package/dist/internal/dateTimeUnitHelpers.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 /**
  * Return the start of the specified date-time `unit` for a `Temporal.PlainDateTime`.
  *

package/dist/internal/dateUnitHelpers.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 /**
  * Return the start of the specified date `unit` for a `Temporal.PlainDate`.
  *

package/dist/internal/daylightTime.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 /**
  * Whether an instant is in daylight saving time, read from the zone's offset changes alone.
  *

package/dist/internal/differenceRecord.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 /** Temporal's duration fields, largest first (Temporal Table 21, the unit ladder). */
 declare const DURATION_FIELDS: readonly ["years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds", "microseconds", "nanoseconds"];
 /** A plural Temporal duration field name. */

package/dist/internal/durationUntilString.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import type { DurationStringOptions, RoundingOptions } from "../types/index.js";
 /**
  * Compute the ISO 8601 duration string between two Temporal objects via `.until()` + `.toString()`.

package/dist/internal/durationUntilString.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { plainDateUntil } from "./plainDateUntil.js";
 import { zonedUntil } from "./zonedWallClockDifference.js";
 export function durationUntilString(start, end, largestUnit, options) {

package/dist/internal/dutyEngine.d.ts

@@ -0,0 +1,125 @@
+import { Temporal } from "./temporal.js";
+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 RunStore } from "./dutyRunIndex.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 whole log and the run index of each status test, built once per call. */
+    store: RunStore;
+};
+/** 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;
+/**
+ * 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: StatusSet): 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: StatusSet, 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 {};