@venizia/ignis-helpers 0.2.2-1 → 0.2.2-3

package/dist/esm/modules/temporal/helper.js

@@ -1,14 +1,10 @@
 import { HTTP } from '../../common/constants/http.js';
-import { BaseHelper } from '../base.js';
-import { getError, isApplicationError } from '../error/index.js';
-import { isTemporalNamespace } from './adapters/guards.js';
-import { IntlTemporalAdapter } from './adapters/intl.js';
-import { NativeTemporalAdapter } from './adapters/native.js';
-import { epochAtOffset, EXACT_UNIT_MILLISECONDS, isRealDateTime, isSupportedYear, MAX_TEMPORAL_YEAR, MIN_TEMPORAL_YEAR, shiftWallClock, truncateTo, wallClockAt, wallClockOf, } from './calendar.js';
-import { DEFAULT_TEMPORAL_LOCALE, DEFAULT_TEMPORAL_PATTERN, DEFAULT_TEMPORAL_TIME_ZONE, TemporalUnits, } from './common/constants.js';
-import { TemporalDuration } from './duration.js';
-import { TemporalLocale } from './locale.js';
-import { TemporalPattern } from './pattern.js';
+import { getError } from '../error/index.js';
+import { AbstractTemporalHelper } from './abstract.js';
+import { TemporalCalendar } from './calendar/index.js';
+import { DEFAULT_TEMPORAL_PATTERN, TemporalInclusivities, TemporalUnits } from './common/constants.js';
+import { TemporalDuration } from './duration/index.js';
+import { TemporalPattern } from './pattern/index.js';
 /** `2026-09-19`, `2026-09-19T12:00`, `2026-09-19 12:00:00.021+07:00`, `...Z` - an offset only after a time. */
 const ISO_8601 = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|[+-]\d{2}(?::?\d{2}(?::?\d{2})?)?)?)?$/i;
 /** The offset of an ISO 8601 value: `+07`, `+07:00`, `+0700`, `+07:06:40`. */
@@ -17,7 +13,22 @@ const DAY_MILLISECONDS = 86_400_000;
 /** 0001-01-01T00:00:00.000Z and 9999-12-31T23:59:59.999Z. */
 const MIN_INSTANT = -62_135_596_800_000;
 const MAX_INSTANT = 253_402_300_799_999;
-const MAX_KNOWN_TIME_ZONES = 256;
+/** Months in each calendar unit `diff` counts by months. */
+const MONTHS_IN = {
+    [TemporalUnits.MONTH]: 1,
+    [TemporalUnits.QUARTER]: 3,
+    [TemporalUnits.YEAR]: 12,
+};
+/** What each wall-clock field `set` takes. The day is clamped to the month separately. */
+const FIELD_RANGES = {
+    year: [TemporalCalendar.MIN_YEAR, TemporalCalendar.MAX_YEAR],
+    month: [1, 12],
+    day: [1, 31],
+    hour: [0, 23],
+    minute: [0, 59],
+    second: [0, 59],
+    millisecond: [0, 999],
+};
 /** `formatIntl` builds one formatter per locale, options and zone; capped so caller-fed options cannot grow it. */
 const MAX_INTL_FORMATTERS = 128;
 /** `relative` without a unit says it in the largest whole one, down to seconds. */
@@ -30,7 +41,6 @@ const RELATIVE_UNITS = [
     TemporalUnits.MINUTE,
     TemporalUnits.SECOND,
 ];
-const OUT_OF_RANGE = `outside the years ${MIN_TEMPORAL_YEAR}-${MAX_TEMPORAL_YEAR}`;
 /**
  * Dates in one time zone, through whichever library you choose: pass an adapter - the runtime's
  * `Temporal` (the default where the runtime has it, `Intl` everywhere else), your own dayjs, your own Luxon. The adapter only reports a zone's UTC
@@ -41,179 +51,40 @@ const OUT_OF_RANGE = `outside the years ${MIN_TEMPORAL_YEAR}-${MAX_TEMPORAL_YEAR
  * swapping the adapter never touches a call site. The zone is yours to set: without one this helper
  * computes in UTC, never in the host's zone. Years run from 1 to 9999.
  */
-export class TemporalHelper extends BaseHelper {
-    /** Validated once per process: `Intl` answers the same for a zone name every time. */
-    static { this.knownTimeZones = new Set(); }
+export class TemporalHelper extends AbstractTemporalHelper {
     static { this.intlFormatters = new Map(); }
     /**
-     * `locale` (default `en-US`) spells month and weekday names, AM/PM, relative time and durations,
-     * unless a call passes its own.
+     * A date picker hands back a `Date` meaning "this wall clock in the host's zone". This returns the
+     * instant that shows the same year, month, day and time in the helper's zone. `sourceTz` defaults
+     * to the host's. A skipped wall time resolves forward, a repeated one to the earlier instant.
      */
-    constructor(opts) {
-        super({ scope: opts?.scope ?? TemporalHelper.name });
-        this.timeZone = TemporalHelper.ensureTimeZone({
-            timeZone: opts?.timeZone ?? DEFAULT_TEMPORAL_TIME_ZONE,
-            statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+    fromWallClock(opts) {
+        return this.moveWallClock({
+            value: opts.value,
+            from: opts.sourceTz ?? TemporalHelper.getHostTz(),
+            to: this.resolveTz({ tz: opts.tz }),
         });
-        this.locale = TemporalHelper.ensureLocale({ locale: opts?.locale ?? DEFAULT_TEMPORAL_LOCALE });
-        this.adapter = opts?.adapter ?? TemporalHelper.defaultAdapter();
-    }
-    /** The runtime's `Temporal` where it has one; `Intl`, which every runtime has, everywhere else. */
-    static defaultAdapter() {
-        return isTemporalNamespace(Reflect.get(globalThis, 'Temporal'))
-            ? new NativeTemporalAdapter()
-            : new IntlTemporalAdapter();
-    }
-    static ensureLocale(opts) {
-        TemporalLocale.of({ locale: opts.locale });
-        return opts.locale;
-    }
-    /** A parse or input error the caller may treat as "not a date"; anything else is a bug and still throws. */
-    static isRefusal(error) {
-        return isApplicationError(error) && error.statusCode === HTTP.ResultCodes.RS_4.BadRequest;
-    }
-    static ensureTimeZone(opts) {
-        const { timeZone, statusCode } = opts;
-        if (TemporalHelper.knownTimeZones.has(timeZone)) {
-            return timeZone;
-        }
-        try {
-            new Intl.DateTimeFormat('en-US', { timeZone });
-        }
-        catch (error) {
-            throw getError({
-                statusCode,
-                message: `[TemporalHelper] unknown time zone '${timeZone}' | ${error instanceof Error ? error.message : String(error)}`,
-            });
-        }
-        if (TemporalHelper.knownTimeZones.size < MAX_KNOWN_TIME_ZONES) {
-            TemporalHelper.knownTimeZones.add(timeZone);
-        }
-        return timeZone;
-    }
-    static ensureUnit(opts) {
-        const { unit, amount } = opts;
-        if (!TemporalUnits.isValid(unit)) {
-            throw getError({
-                statusCode: HTTP.ResultCodes.RS_4.BadRequest,
-                message: `[TemporalHelper] unknown unit '${unit}' | Supported: ${[...TemporalUnits.SCHEME_SET].join(', ')}`,
-            });
-        }
-        if (amount !== undefined && !Number.isInteger(amount)) {
-            throw getError({
-                statusCode: HTTP.ResultCodes.RS_4.BadRequest,
-                message: `[TemporalHelper] amount must be an integer - received ${amount}`,
-            });
-        }
-    }
-    /** Every result passes here: an overflowing `add` is refused, never an Invalid Date. */
-    static ensureInstant(opts) {
-        const { epoch } = opts;
-        if (!(epoch >= MIN_INSTANT && epoch <= MAX_INSTANT)) {
-            throw getError({
-                statusCode: HTTP.ResultCodes.RS_4.BadRequest,
-                message: `[TemporalHelper] ${Number.isNaN(epoch) ? 'invalid date' : OUT_OF_RANGE} - received ${epoch}`,
-            });
-        }
-        return new Date(epoch);
-    }
-    static ensureYear(opts) {
-        if (!isSupportedYear(opts.parts.year)) {
-            throw getError({
-                statusCode: HTTP.ResultCodes.RS_4.BadRequest,
-                message: `[TemporalHelper] year ${opts.parts.year} is ${OUT_OF_RANGE}`,
-            });
-        }
-    }
-    resolveTimeZone(opts) {
-        return opts.timeZone === undefined
-            ? this.timeZone
-            : TemporalHelper.ensureTimeZone({
-                timeZone: opts.timeZone,
-                statusCode: HTTP.ResultCodes.RS_4.BadRequest,
-            });
-    }
-    /** The adapter's one answer, rounded: an offset is whole milliseconds, a library's float may not be. */
-    offsetAt(opts) {
-        return Math.round(this.adapter.getOffsetMilliseconds({ value: new Date(opts.epoch), timeZone: opts.timeZone }));
-    }
-    zonedParts(opts) {
-        const parts = wallClockAt({ epoch: opts.epoch, offsetMilliseconds: this.offsetAt(opts) });
-        TemporalHelper.ensureYear({ parts });
-        return parts;
     }
     /**
-     * Every instant whose wall clock reads `parts` in the zone, earliest first: one as a rule, two
-     * when the clock goes back, none when it jumps forward. `forward` is where a skipped time lands -
-     * read with the offset from before the jump, so it moves past the gap.
+     * The reverse of `fromWallClock`, to feed a picker: a `Date` whose wall clock in `targetTz` (default:
+     * the host's) reads what the helper's zone reads for `value`.
      */
-    instantsOf(opts) {
-        const { parts, timeZone } = opts;
-        const local = epochAtOffset({ parts, offsetMilliseconds: 0 });
-        const before = this.offsetAt({ epoch: local - DAY_MILLISECONDS, timeZone });
-        const after = this.offsetAt({ epoch: local + DAY_MILLISECONDS, timeZone });
-        const offsets = before === after ? [before] : [before, after];
-        const instants = [];
-        for (const offset of offsets) {
-            const candidate = local - offset;
-            if (this.offsetAt({ epoch: candidate, timeZone }) === offset) {
-                instants.push(candidate);
-            }
-        }
-        instants.sort((left, right) => left - right);
-        return { instants, forward: local - before };
-    }
-    /** The instant wall-clock `parts` name: a skipped time moves forward, a repeated one takes the earlier. */
-    earliestOf(opts) {
-        const { instants, forward } = this.instantsOf(opts);
-        return instants[0] ?? forward;
-    }
-    /**
-     * `[start, end)` of the unit holding `epoch`. A day or longer starts at its first instant. An hour
-     * or less repeats when the clock goes back, so it starts at the latest start not after `epoch`,
-     * and ends where the wall clock next shows either the following unit or this one's start again.
-     */
-    unitBounds(opts) {
-        const { epoch, unit, timeZone } = opts;
-        const startParts = truncateTo({ parts: this.zonedParts({ epoch, timeZone }), unit });
-        const nextParts = shiftWallClock({ parts: startParts, amount: 1, unit });
-        TemporalHelper.ensureYear({ parts: nextParts });
-        const starts = this.instantsOf({ parts: startParts, timeZone });
-        if (EXACT_UNIT_MILLISECONDS[unit] === undefined) {
-            const start = starts.instants[0] ?? starts.forward;
-            return { start, end: this.earliestOf({ parts: nextParts, timeZone }) };
-        }
-        const started = starts.instants.filter(instant => instant <= epoch);
-        const start = started.at(-1) ?? starts.instants[0] ?? starts.forward;
-        const nexts = this.instantsOf({ parts: nextParts, timeZone });
-        const following = nexts.instants.find(instant => instant > start) ?? nexts.forward;
-        const repeated = starts.instants.find(instant => instant > start);
-        return { start, end: repeated === undefined ? following : Math.min(repeated, following) };
-    }
-    getTimeZone() {
-        return this.timeZone;
-    }
-    getLocale() {
-        return this.locale;
-    }
-    now() {
-        return new Date();
-    }
-    /** The instant a value names. An ISO string without an offset is read as wall clock in the zone. */
-    toDate(opts) {
-        const { value } = opts;
-        if (typeof value === 'string') {
-            return this.parse({ value, timeZone: opts.timeZone });
-        }
-        return TemporalHelper.ensureInstant({
-            epoch: value instanceof Date ? value.getTime() : value,
+    toWallClock(opts) {
+        return this.moveWallClock({
+            value: opts.value,
+            from: this.resolveTz({ tz: opts.tz }),
+            to: opts.targetTz ?? TemporalHelper.getHostTz(),
         });
     }
-    /** The wall clock the value shows in the zone, with its ISO weekday and UTC offset. */
-    parts(opts) {
-        const timeZone = this.resolveTimeZone({ timeZone: opts.timeZone });
-        const date = this.toDate({ value: opts.value, timeZone });
-        return this.zonedParts({ epoch: date.getTime(), timeZone });
+    /** A helper like this one, with another locale or zone: same adapter, same `names`. */
+    clone(opts) {
+        return new TemporalHelper({
+            adapter: this.adapter,
+            tz: opts.tz ?? this.tz,
+            locale: opts.locale ?? this.locale,
+            names: this.names,
+            scope: this.scope,
+        });
     }
     /**
      * Reads a string. With a `pattern` (`YYYY YY MM M DD D HH H mm m ss s SSS Z ZZ`, text in
@@ -222,7 +93,7 @@ export class TemporalHelper extends BaseHelper {
      */
     parse(opts) {
         const { value, pattern } = opts;
-        const timeZone = this.resolveTimeZone({ timeZone: opts.timeZone });
+        const tz = this.resolveTz({ tz: opts.tz });
         const read = pattern ? TemporalPattern.parse({ pattern, value }) : this.readIso({ value });
         if (!read) {
             throw getError({
@@ -232,15 +103,18 @@ export class TemporalHelper extends BaseHelper {
                     : `[TemporalHelper] '${value}' is not ISO 8601 | Pass a pattern for any other shape`,
             });
         }
-        if (!isRealDateTime({ parts: read.parts })) {
+        if (!TemporalCalendar.isRealDateTime({ parts: read.parts })) {
             throw getError({
                 statusCode: HTTP.ResultCodes.RS_4.BadRequest,
                 message: `[TemporalHelper] '${value}' is not a real date and time`,
             });
         }
         const epoch = read.offsetMilliseconds === undefined
-            ? this.earliestOf({ parts: read.parts, timeZone })
-            : epochAtOffset({ parts: read.parts, offsetMilliseconds: read.offsetMilliseconds });
+            ? this.earliestOf({ parts: read.parts, tz })
+            : TemporalCalendar.epochAtOffset({
+                parts: read.parts,
+                offsetMilliseconds: read.offsetMilliseconds,
+            });
         return TemporalHelper.ensureInstant({ epoch });
     }
     readIso(opts) {
@@ -277,9 +151,9 @@ export class TemporalHelper extends BaseHelper {
     /** `parse`, answering `null` where `parse` refuses the value. A pattern that does not compile still throws. */
     tryParse(opts) {
         // Outside the try: a bad zone is the caller's bug, as a broken pattern is.
-        const timeZone = this.resolveTimeZone({ timeZone: opts.timeZone });
+        const tz = this.resolveTz({ tz: opts.tz });
         try {
-            return this.parse({ ...opts, timeZone });
+            return this.parse({ ...opts, tz });
         }
         catch (error) {
             if (TemporalHelper.isRefusal(error)) {
@@ -290,35 +164,56 @@ export class TemporalHelper extends BaseHelper {
     }
     /** Whether the value names an instant in years 1-9999 - a string read as `parse` reads it. */
     isValid(opts) {
-        const { value, pattern, timeZone } = opts;
+        const { value, pattern, tz } = opts;
         if (typeof value === 'string') {
-            return this.tryParse({ value, pattern, timeZone }) !== null;
+            return this.tryParse({ value, pattern, tz }) !== null;
+        }
+        if (!(value instanceof Date) && typeof value !== 'number') {
+            return false;
         }
         const epoch = value instanceof Date ? value.getTime() : value;
         return epoch >= MIN_INSTANT && epoch <= MAX_INSTANT;
     }
     /**
-     * Writes the value in the zone. Without a `pattern`: ISO 8601 with the zone's offset. The locale
-     * tokens `MMMM MMM dddd ddd A a hh h LL L` are spelled in `locale`.
+     * Writes the value in the zone. Without a `pattern`: ISO 8601 with the zone's offset. The tokens
+     * `MMMM MMM dddd ddd dd A a hh h LL L` are spelled in `locale`. With a `fallback`, a value that is
+     * not a date - null included - writes the fallback; without one, it is a 400.
      */
     format(opts) {
+        const { value, fallback } = opts;
+        const tz = this.resolveTz({ tz: opts.tz });
+        const locale = opts.locale ?? this.locale;
+        let date;
+        if (fallback !== undefined) {
+            date = this.tryToDate({ value, tz });
+        }
+        else if (value === null || value === undefined) {
+            throw TemporalHelper.notADate({ value });
+        }
+        else {
+            date = this.toDate({ value, tz });
+        }
+        if (date === null) {
+            return fallback ?? '';
+        }
         return TemporalPattern.format({
             pattern: opts.pattern ?? DEFAULT_TEMPORAL_PATTERN,
-            parts: this.parts({ value: opts.value, timeZone: opts.timeZone }),
-            locale: opts.locale ?? this.locale,
+            parts: this.zonedParts({ epoch: date.getTime(), tz }),
+            locale,
+            names: this.namesOf({ locale }),
         });
     }
     /** Writes the value with `Intl.DateTimeFormat` options, in the zone - for what the pattern tokens cannot say. */
     formatIntl(opts) {
-        const timeZone = this.resolveTimeZone({ timeZone: opts.timeZone });
+        const tz = this.resolveTz({ tz: opts.tz });
         const locale = opts.locale === undefined
             ? this.locale
             : TemporalHelper.ensureLocale({ locale: opts.locale });
-        const date = this.toDate({ value: opts.value, timeZone });
-        const key = `${locale}|${timeZone}|${JSON.stringify(opts.options ?? {})}`;
+        const date = this.toDate({ value: opts.value, tz });
+        const key = `${locale}|${tz}|${JSON.stringify(opts.options ?? {})}`;
         let formatter = TemporalHelper.intlFormatters.get(key);
         if (!formatter) {
-            formatter = new Intl.DateTimeFormat(locale, { ...opts.options, timeZone });
+            formatter = new Intl.DateTimeFormat(locale, { ...opts.options, timeZone: tz });
             if (TemporalHelper.intlFormatters.size < MAX_INTL_FORMATTERS) {
                 TemporalHelper.intlFormatters.set(key, formatter);
             }
@@ -333,19 +228,21 @@ export class TemporalHelper extends BaseHelper {
     add(opts) {
         const { amount, unit } = opts;
         TemporalHelper.ensureUnit({ unit, amount });
-        const timeZone = this.resolveTimeZone({ timeZone: opts.timeZone });
-        const date = this.toDate({ value: opts.value, timeZone });
+        const tz = this.resolveTz({ tz: opts.tz });
+        const date = this.toDate({ value: opts.value, tz });
         if (amount === 0) {
             return date;
         }
-        const exact = EXACT_UNIT_MILLISECONDS[unit];
+        const exact = TemporalCalendar.EXACT_UNIT_MILLISECONDS[unit];
         if (exact !== undefined) {
             return TemporalHelper.ensureInstant({ epoch: date.getTime() + amount * exact });
         }
-        const parts = wallClockOf({ parts: this.zonedParts({ epoch: date.getTime(), timeZone }) });
-        const shifted = shiftWallClock({ parts, amount, unit });
+        const parts = TemporalCalendar.wallClockOf({
+            parts: this.zonedParts({ epoch: date.getTime(), tz }),
+        });
+        const shifted = TemporalCalendar.shift({ parts, amount, unit });
         TemporalHelper.ensureYear({ parts: shifted });
-        return TemporalHelper.ensureInstant({ epoch: this.earliestOf({ parts: shifted, timeZone }) });
+        return TemporalHelper.ensureInstant({ epoch: this.earliestOf({ parts: shifted, tz }) });
     }
     subtract(opts) {
         return this.add({ ...opts, amount: -opts.amount });
@@ -354,24 +251,24 @@ export class TemporalHelper extends BaseHelper {
     startOf(opts) {
         const { unit } = opts;
         TemporalHelper.ensureUnit({ unit });
-        const timeZone = this.resolveTimeZone({ timeZone: opts.timeZone });
-        const date = this.toDate({ value: opts.value, timeZone });
+        const tz = this.resolveTz({ tz: opts.tz });
+        const date = this.toDate({ value: opts.value, tz });
         if (unit === TemporalUnits.MILLISECOND) {
             return date;
         }
-        const { start } = this.unitBounds({ epoch: date.getTime(), unit, timeZone });
+        const { start } = this.unitBounds({ epoch: date.getTime(), unit, tz });
         return TemporalHelper.ensureInstant({ epoch: start });
     }
     /** The last millisecond of the unit containing the value, in the zone. */
     endOf(opts) {
         const { unit } = opts;
         TemporalHelper.ensureUnit({ unit });
-        const timeZone = this.resolveTimeZone({ timeZone: opts.timeZone });
-        const date = this.toDate({ value: opts.value, timeZone });
+        const tz = this.resolveTz({ tz: opts.tz });
+        const date = this.toDate({ value: opts.value, tz });
         if (unit === TemporalUnits.MILLISECOND) {
             return date;
         }
-        const { end } = this.unitBounds({ epoch: date.getTime(), unit, timeZone });
+        const { end } = this.unitBounds({ epoch: date.getTime(), unit, tz });
         return TemporalHelper.ensureInstant({ epoch: end - 1 });
     }
     /** Monday to Friday, read on the wall clock of the zone. */
@@ -389,70 +286,118 @@ export class TemporalHelper extends BaseHelper {
             value: opts.value,
             amount: opts.step,
             unit: TemporalUnits.DAY,
-            timeZone: opts.timeZone,
+            tz: opts.tz,
         });
-        while (!this.isWeekday({ value: candidate, timeZone: opts.timeZone })) {
+        while (!this.isWeekday({ value: candidate, tz: opts.tz })) {
             candidate = this.add({
                 value: candidate,
                 amount: opts.step,
                 unit: TemporalUnits.DAY,
-                timeZone: opts.timeZone,
+                tz: opts.tz,
             });
         }
         return candidate;
     }
+    /**
+     * The value with wall-clock fields replaced in the zone - `{ hour: 9, minute: 0 }` is 09:00 that day.
+     * `month` is 1-12. The day is clamped to the month's last day, so setting February on the 31st
+     * lands on the 28th or 29th. A wall time a daylight-saving jump skips resolves forward, as `parse` does.
+     */
+    set(opts) {
+        const tz = this.resolveTz({ tz: opts.tz });
+        const date = this.toDate({ value: opts.value, tz });
+        const wall = TemporalCalendar.wallClockOf({
+            parts: this.zonedParts({ epoch: date.getTime(), tz }),
+        });
+        const next = { ...wall };
+        for (const [field, [min, max]] of Object.entries(FIELD_RANGES)) {
+            const given = Reflect.get(opts, field);
+            if (given === undefined) {
+                continue;
+            }
+            if (typeof given !== 'number' || !Number.isInteger(given) || given < min || given > max) {
+                throw getError({
+                    statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+                    message: `[TemporalHelper] ${field} must be an integer from ${min} to ${max} - received ${String(given)}`,
+                });
+            }
+            Reflect.set(next, field, given);
+        }
+        next.day = Math.min(next.day, TemporalCalendar.daysInMonth({ year: next.year, month: next.month }));
+        return TemporalHelper.ensureInstant({ epoch: this.earliestOf({ parts: next, tz }) });
+    }
+    /** `value` is before `other` - at the unit's granularity in the zone when `unit` is given. */
+    isBefore(opts) {
+        return this.compare(opts) < 0;
+    }
+    isAfter(opts) {
+        return this.compare(opts) > 0;
+    }
+    /** In the same unit - `unit: 'day'` is the same calendar day in the zone. */
+    isSame(opts) {
+        return this.compare(opts) === 0;
+    }
+    isSameOrBefore(opts) {
+        return this.compare(opts) <= 0;
+    }
+    isSameOrAfter(opts) {
+        return this.compare(opts) >= 0;
+    }
+    /**
+     * Whether `value` lies between `from` and `to`, in either order. `inclusivity` says which ends count:
+     * `()` (the default) neither, `[]` both, `[)` the start, `(]` the end.
+     */
+    isBetween(opts) {
+        const { value, from, to, unit, inclusivity = TemporalInclusivities.EXCLUSIVE, tz } = opts;
+        if (!TemporalInclusivities.isValid(inclusivity)) {
+            throw getError({
+                statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+                message: `[TemporalHelper] unknown inclusivity '${inclusivity}' | Supported: ${[...TemporalInclusivities.SCHEME_SET].join(', ')}`,
+            });
+        }
+        const isStartIncluded = inclusivity.startsWith('[');
+        const isEndIncluded = inclusivity.endsWith(']');
+        const fromOrder = this.compare({ value, other: from, unit, tz });
+        const toOrder = this.compare({ value, other: to, unit, tz });
+        const isAfterStart = isStartIncluded ? fromOrder >= 0 : fromOrder > 0;
+        const isBeforeEnd = isEndIncluded ? toOrder <= 0 : toOrder < 0;
+        // The range given backwards: `to` is the earlier end.
+        const isAfterEnd = isEndIncluded ? toOrder >= 0 : toOrder > 0;
+        const isBeforeStart = isStartIncluded ? fromOrder <= 0 : fromOrder < 0;
+        return (isAfterStart && isBeforeEnd) || (isAfterEnd && isBeforeStart);
+    }
     /**
      * How many whole units `value` is past `other` - negative when it is before - truncated toward
-     * zero. Hours and smaller count elapsed time. Days and larger count the calendar in the zone, as
-     * `add` moves it: the answer is the largest `n` that `add` can move `other` by without passing
-     * `value`, so `diff(add(x, n), x)` is `n` wherever the zone skips no whole day.
+     * zero, counted as dayjs counts. Hours and smaller are elapsed time. Days and weeks are calendar
+     * days in the zone: the wall clocks' difference, so a 23-hour daylight-saving day is one day.
+     * Months, quarters and years are anchored on the date with the later day of the month, then
+     * truncated, so `diff(a, b)` is always `-diff(b, a)`.
      */
     diff(opts) {
         const { unit } = opts;
         TemporalHelper.ensureUnit({ unit });
-        const timeZone = this.resolveTimeZone({ timeZone: opts.timeZone });
-        const value = this.toDate({ value: opts.value, timeZone }).getTime();
-        const other = this.toDate({ value: opts.other, timeZone }).getTime();
-        const exact = EXACT_UNIT_MILLISECONDS[unit];
+        const tz = this.resolveTz({ tz: opts.tz });
+        const value = this.toDate({ value: opts.value, tz }).getTime();
+        const other = this.toDate({ value: opts.other, tz }).getTime();
+        // `+ 0` turns a truncated `-0` into `0`.
+        const exact = TemporalCalendar.EXACT_UNIT_MILLISECONDS[unit];
         if (exact !== undefined) {
-            // `+ 0` turns a truncated `-0` into `0`.
             return Math.trunc((value - other) / exact) + 0;
         }
-        if (value === other) {
-            return 0;
-        }
-        const later = this.zonedParts({ epoch: value, timeZone });
-        const earlier = this.zonedParts({ epoch: other, timeZone });
-        // A first guess from the wall clocks, settled by `add` itself: back while it passes `value`, then
-        // on while the next step does not - a zone that repeats or skips a whole day can put it either side.
-        let guess;
-        if (unit === TemporalUnits.MONTH || unit === TemporalUnits.YEAR) {
-            const months = (later.year - earlier.year) * 12 + (later.month - earlier.month);
-            guess = unit === TemporalUnits.YEAR ? Math.trunc(months / 12) : months;
-        }
-        else {
-            const days = Math.round((epochAtOffset({ parts: wallClockOf({ parts: later }), offsetMilliseconds: 0 }) -
-                epochAtOffset({ parts: wallClockOf({ parts: earlier }), offsetMilliseconds: 0 })) /
-                DAY_MILLISECONDS);
-            guess = unit === TemporalUnits.WEEK ? Math.trunc(days / 7) : Math.trunc(days);
-        }
-        const direction = Math.sign(value - other);
-        const start = wallClockOf({ parts: earlier });
-        const passes = (amount) => {
-            // A move past years 1-9999 passes every value inside them, and `add` would refuse it.
-            if (!isSupportedYear(shiftWallClock({ parts: start, amount, unit }).year)) {
-                return true;
-            }
-            const moved = this.add({ value: other, amount, unit, timeZone }).getTime();
-            return direction > 0 ? moved > value : moved < value;
-        };
-        while (guess !== 0 && passes(guess)) {
-            guess -= direction;
-        }
-        while (!passes(guess + direction)) {
-            guess += direction;
-        }
-        return guess + 0;
+        const months = MONTHS_IN[unit];
+        if (months !== undefined) {
+            return Math.trunc(this.monthGap({ value, other, tz }) / months) + 0;
+        }
+        const wallClocks = TemporalCalendar.epochAtOffset({
+            parts: TemporalCalendar.wallClockOf({ parts: this.zonedParts({ epoch: value, tz }) }),
+            offsetMilliseconds: 0,
+        }) -
+            TemporalCalendar.epochAtOffset({
+                parts: TemporalCalendar.wallClockOf({ parts: this.zonedParts({ epoch: other, tz }) }),
+                offsetMilliseconds: 0,
+            });
+        const days = wallClocks / DAY_MILLISECONDS;
+        return Math.trunc(unit === TemporalUnits.WEEK ? days / 7 : days) + 0;
     }
     /**
      * `-1`, `0` or `1` as `value` is before, in, or after the unit that holds `other`, in the zone.
@@ -460,13 +405,13 @@ export class TemporalHelper extends BaseHelper {
      */
     compare(opts) {
         const { unit } = opts;
-        const timeZone = this.resolveTimeZone({ timeZone: opts.timeZone });
+        const tz = this.resolveTz({ tz: opts.tz });
         const value = unit === undefined
-            ? this.toDate({ value: opts.value, timeZone })
-            : this.startOf({ value: opts.value, unit, timeZone });
+            ? this.toDate({ value: opts.value, tz })
+            : this.startOf({ value: opts.value, unit, tz });
         const other = unit === undefined
-            ? this.toDate({ value: opts.other, timeZone })
-            : this.startOf({ value: opts.other, unit, timeZone });
+            ? this.toDate({ value: opts.other, tz })
+            : this.startOf({ value: opts.other, unit, tz });
         const delta = value.getTime() - other.getTime();
         return delta < 0 ? -1 : delta > 0 ? 1 : 0;
     }
@@ -478,12 +423,12 @@ export class TemporalHelper extends BaseHelper {
      */
     relative(opts) {
         const { unit, numeric = 'always', style = 'long' } = opts;
-        const timeZone = this.resolveTimeZone({ timeZone: opts.timeZone });
+        const tz = this.resolveTz({ tz: opts.tz });
         const locale = opts.locale === undefined
             ? this.locale
             : TemporalHelper.ensureLocale({ locale: opts.locale });
-        const value = this.toDate({ value: opts.value, timeZone });
-        const base = opts.base === undefined ? this.now() : this.toDate({ value: opts.base, timeZone });
+        const value = this.toDate({ value: opts.value, tz });
+        const base = opts.base === undefined ? this.now() : this.toDate({ value: opts.base, tz });
         let amount = 0;
         let said = TemporalUnits.SECOND;
         if (unit !== undefined) {
@@ -495,16 +440,16 @@ export class TemporalHelper extends BaseHelper {
                 });
             }
             amount = this.diff({
-                value: this.startOf({ value, unit, timeZone }),
-                other: this.startOf({ value: base, unit, timeZone }),
+                value: this.startOf({ value, unit, tz }),
+                other: this.startOf({ value: base, unit, tz }),
                 unit,
-                timeZone,
+                tz,
             });
             said = unit;
         }
         else {
             for (const candidate of RELATIVE_UNITS) {
-                const counted = this.diff({ value, other: base, unit: candidate, timeZone });
+                const counted = this.diff({ value, other: base, unit: candidate, tz });
                 if (counted !== 0 || candidate === TemporalUnits.SECOND) {
                     amount = counted;
                     said = candidate;
@@ -526,7 +471,13 @@ export class TemporalHelper extends BaseHelper {
         const locale = opts.locale === undefined
             ? this.locale
             : TemporalHelper.ensureLocale({ locale: opts.locale });
-        return TemporalDuration.format({ milliseconds: opts.milliseconds, style: opts.style, locale });
+        return TemporalDuration.format({
+            milliseconds: opts.milliseconds,
+            style: opts.style,
+            pattern: opts.pattern,
+            maxUnits: opts.maxUnits,
+            locale,
+        });
     }
 }
 //# sourceMappingURL=helper.js.map