@rvoh/dream 2.3.0-alpha.5 → 2.3.0-alpha.7

package/dist/esm/src/utils/datetime/DateTime.js

@@ -4,9 +4,17 @@ import { microsecondParts } from './helpers/microsecondParts.js';
 import replaceISOMicroseconds from './helpers/replaceISOMicroseconds.js';
 export const Settings = LuxonSettings;
 Settings.throwOnInvalid = true;
+export const BASE_DATE_OBJECT = {
+    year: 2000,
+    month: 1,
+    day: 1,
+};
 /**
  * DateTime wraps Luxon DateTime with microsecond precision (0-999).
  * The decimal part in ISO/SQL is 6 digits: first 3 = milliseconds, next 3 = microseconds.
+ *
+ * Full datetime output (toISO, toSQL) is normalized to UTC.
+ * Time-only output (toISOTime, toSQLTime) omits timezone offset by default.
  */
 export class DateTime {
     luxonDatetime;
@@ -87,9 +95,6 @@ export class DateTime {
     get offset() {
         return this.luxonDatetime.offset;
     }
-    get isValid() {
-        return this.luxonDatetime.isValid;
-    }
     get invalidReason() {
         return this.luxonDatetime.invalidReason;
     }
@@ -102,6 +107,9 @@ export class DateTime {
     get zone() {
         return this.luxonDatetime.zone;
     }
+    /**
+     * @internal
+     */
     constructor(luxonDatetime, microseconds = 0) {
         this.luxonDatetime = luxonDatetime;
         this._microseconds = microseconds;
@@ -127,8 +135,8 @@ export class DateTime {
      * const now = DateTime.now()
      * ```
      */
-    static now() {
-        return new DateTime(LuxonDateTime.now(), 0);
+    static now({ zone = 'UTC' } = {}) {
+        return new DateTime(LuxonDateTime.now().setZone(zone), 0);
     }
     // Format presets for toLocaleString()
     /**
@@ -353,18 +361,22 @@ export class DateTime {
     }
     static local(yearOrOpts, month, day, hour, minute, second, millisecond, microsecondOrOpts, opts) {
         const isOpts = (v) => typeof v === 'object' && v !== null;
-        const { luxonDatetime, microseconds } = buildLocalOrUtcDateTime(yearOrOpts, month, day, hour, minute, second, millisecond, microsecondOrOpts, opts, isOpts, (y, m, d, h, mi, s, ms, options) => LuxonDateTime.local(y, m, d, h, mi, s, ms, options));
+        const { luxonDatetime, microseconds } = buildLocalOrUtcDateTime(yearOrOpts, month, day, hour, minute, second, millisecond, microsecondOrOpts, opts, isOpts, (y, m, d, h, mi, s, ms, opts) => LuxonDateTime.local(y, m, d, h, mi, s, ms, opts));
         return new DateTime(luxonDatetime, microseconds);
     }
-    static utc(yearOrOpts, month, day, hour, minute, second, millisecond, microsecondOrOpts, options) {
+    static utc(yearOrOpts, month, day, hour, minute, second, millisecond, microsecondOrOpts, opts) {
         const isOpts = (v) => typeof v === 'object' && v !== null;
-        const { luxonDatetime, microseconds } = buildLocalOrUtcDateTime(yearOrOpts, month, day, hour, minute, second, millisecond, microsecondOrOpts, options, isOpts, (y, m, d, h, mi, s, ms, opts) => LuxonDateTime.utc(y, m, d, h, mi, s, ms, opts));
+        const { luxonDatetime, microseconds } = buildLocalOrUtcDateTime(yearOrOpts, month, day, hour, minute, second, millisecond, microsecondOrOpts, opts, isOpts, (y, m, d, h, mi, s, ms, opts) => LuxonDateTime.utc(y, m, d, h, mi, s, ms, opts));
         return new DateTime(luxonDatetime, microseconds);
     }
     /**
      * Create a DateTime from a JavaScript Date.
      * @param date - A JavaScript Date instance
-     * @param options - Optional zone for the result
+     * @param opts - Optional configuration
+     * @param opts.zone - Timezone for the result (IANA timezone name or Zone object)
+     * @param opts.locale - Locale string (e.g., 'en-US', 'fr-FR')
+     * @param opts.numberingSystem - Numbering system (e.g., 'arab', 'beng')
+     * @param opts.outputCalendar - Calendar system (e.g., 'islamic', 'hebrew')
      * @returns A DateTime representing the same instant
      * @example
      * ```ts
@@ -372,66 +384,94 @@ export class DateTime {
      * DateTime.fromJSDate(new Date(), { zone: 'America/New_York' })
      * ```
      */
-    static fromJSDate(date, options) {
-        const luxonDatetime = options
+    static fromJSDate(date, opts) {
+        const luxonDatetime = opts
             ? // @ts-expect-error - exactOptionalPropertyTypes incompatibility with Luxon types
-                LuxonDateTime.fromJSDate(date, options)
+                LuxonDateTime.fromJSDate(date, opts)
             : LuxonDateTime.fromJSDate(date);
         return new DateTime(luxonDatetime, 0);
     }
     /**
      * Create a DateTime from epoch milliseconds.
-     * @param milliseconds - Unix timestamp in milliseconds
-     * @param options - Optional zone/locale options
+     * @param millisecondInput - Unix timestamp in milliseconds (fractional part becomes microseconds)
+     * @param opts - Optional configuration
+     * @param opts.zone - Timezone for the result (IANA timezone name or Zone object)
+     * @param opts.locale - Locale string (e.g., 'en-US', 'fr-FR')
+     * @param opts.numberingSystem - Numbering system (e.g., 'arab', 'beng')
+     * @param opts.outputCalendar - Calendar system (e.g., 'islamic', 'hebrew')
      * @returns A DateTime for the given instant
      * @example
      * ```ts
      * DateTime.fromMillis(1707234567890)
+     * DateTime.fromMillis(1707234567890.123) // .123 ms = 123 microseconds
+     * DateTime.fromMillis(1707234567890, { zone: 'America/New_York' })
      * ```
      */
-    static fromMillis(milliseconds, options) {
-        const luxonDatetime = LuxonDateTime.fromMillis(milliseconds, options);
-        return new DateTime(luxonDatetime, 0);
+    static fromMillis(millisecondInput, opts) {
+        const { milliseconds, microseconds } = microsecondParts(millisecondInput * 1000, {
+            errorIfNegative: false,
+        });
+        return new DateTime(LuxonDateTime.fromMillis(milliseconds, opts), microseconds);
     }
     /**
      * Create a DateTime from epoch microseconds.
      * @param microseconds - Unix timestamp in microseconds (milliseconds from quotient, microsecond from remainder)
-     * @param options - Optional zone/locale options
+     * @param opts - Optional configuration
+     * @param opts.zone - Timezone for the result (IANA timezone name or Zone object)
+     * @param opts.locale - Locale string (e.g., 'en-US', 'fr-FR')
+     * @param opts.numberingSystem - Numbering system (e.g., 'arab', 'beng')
+     * @param opts.outputCalendar - Calendar system (e.g., 'islamic', 'hebrew')
      * @returns A DateTime for the given instant
      * @example
      * ```ts
      * DateTime.fromMicroseconds(1707234567890123)
+     * DateTime.fromMicroseconds(1707234567890123, { zone: 'America/New_York' })
      * ```
      */
-    static fromMicroseconds(microsecondsInput, options) {
+    static fromMicroseconds(microsecondsInput, opts) {
         const { milliseconds, microseconds } = microsecondParts(microsecondsInput);
-        const luxonDatetime = LuxonDateTime.fromMillis(milliseconds, options);
+        const luxonDatetime = LuxonDateTime.fromMillis(milliseconds, opts);
         return new DateTime(luxonDatetime, microseconds);
     }
     /**
      * Create a DateTime from epoch seconds.
-     * @param seconds - Unix timestamp in seconds
-     * @param options - Optional zone/locale options
+     * Fractional seconds are converted to milliseconds and microseconds.
+     * @param seconds - Unix timestamp in seconds (fractional part becomes ms + µs)
+     * @param opts - Optional configuration
+     * @param opts.zone - Timezone for the result (IANA timezone name or Zone object)
+     * @param opts.locale - Locale string (e.g., 'en-US', 'fr-FR')
+     * @param opts.numberingSystem - Numbering system (e.g., 'arab', 'beng')
+     * @param opts.outputCalendar - Calendar system (e.g., 'islamic', 'hebrew')
      * @returns A DateTime for the given instant
      * @example
      * ```ts
      * DateTime.fromSeconds(1707234567)
+     * DateTime.fromSeconds(1707234567.123456) // .123456 seconds = 123ms + 456µs
+     * DateTime.fromSeconds(1707234567, { zone: 'America/New_York' })
      * ```
      */
-    static fromSeconds(seconds, options) {
-        const luxonDatetime = LuxonDateTime.fromSeconds(seconds, options);
-        return new DateTime(luxonDatetime, 0);
+    static fromSeconds(seconds, opts) {
+        // Convert seconds to microseconds to preserve full precision
+        const totalMicroseconds = seconds * 1_000_000;
+        const { milliseconds, microseconds } = microsecondParts(totalMicroseconds, { errorIfNegative: false });
+        const luxonDatetime = LuxonDateTime.fromMillis(milliseconds, opts);
+        return new DateTime(luxonDatetime, microseconds);
     }
     /**
      * Create a DateTime from an object with date/time units.
      * Fractional milliseconds are converted to microseconds (e.g., 1.5 ms = 1 ms + 500 µs).
-     * @param obj - Object with year, month, day, etc.; supports optional microsecond
-     * @param opts - Optional zone/locale options
+     * @param obj - Object with year, month, day, hour, minute, second, millisecond, microsecond
+     * @param opts - Optional configuration
+     * @param opts.zone - Timezone for the datetime (IANA timezone name or Zone object)
+     * @param opts.locale - Locale string (e.g., 'en-US', 'fr-FR')
+     * @param opts.numberingSystem - Numbering system (e.g., 'arab', 'beng')
+     * @param opts.outputCalendar - Calendar system (e.g., 'islamic', 'hebrew')
      * @returns A DateTime for the given components
      * @example
      * ```ts
      * DateTime.fromObject({ year: 2017, month: 3, day: 12, hour: 5, minute: 45, microsecond: 123 })
      * DateTime.fromObject({ year: 2017, month: 3, day: 12, millisecond: 1.5 }) // 1ms + 500µs
+     * DateTime.fromObject({ year: 2017, month: 3, day: 12 }, { zone: 'America/New_York' })
      * ```
      */
     static fromObject(obj, opts) {
@@ -446,39 +486,56 @@ export class DateTime {
             adjustedMillisecond = wholeMilli;
         }
         const { milliseconds, microseconds } = microsecondParts(microsecondsTotal);
-        const luxonDatetime = wrapLuxonError(() => LuxonDateTime.fromObject({ ...rest, millisecond: adjustedMillisecond }, opts));
+        const luxonDatetime = wrapLuxonError(() => LuxonDateTime.fromObject({ ...rest, millisecond: adjustedMillisecond }, (opts?.zone ? opts : { zone: 'UTC', ...opts })));
         return new DateTime(milliseconds > 0 ? luxonDatetime.plus({ milliseconds }) : luxonDatetime, microseconds);
     }
     /**
      * Create a DateTime from an ISO 8601 string.
      * @param text - ISO string (e.g. "2024-03-15T10:30:45.123456-05:00"); parses up to 6 fractional second digits
-     * @param opts - Optional parsing options
+     * @param opts - Optional configuration
+     * @param opts.zone - Timezone to interpret/convert the datetime in (defaults to UTC)
+     * @param opts.locale - Locale string (e.g., 'en-US', 'fr-FR')
+     * @param opts.numberingSystem - Numbering system (e.g., 'arab', 'beng')
+     * @param opts.outputCalendar - Calendar system (e.g., 'islamic', 'hebrew')
      * @returns A DateTime for the parsed instant
      * @example
      * ```ts
      * DateTime.fromISO('2024-03-15T10:30:45.123456-05:00')
+     * DateTime.fromISO('2024-03-15T10:30:45Z', { zone: 'America/New_York' })
      * ```
      */
     static fromISO(text, opts) {
         const { microsecond } = parseFractionalPart(text);
         const textForLuxon = toThreeDecimalFraction(text);
-        const luxonDatetime = wrapLuxonError(() => LuxonDateTime.fromISO(textForLuxon, opts));
+        const hasTimezoneInString = hasIsoTimezoneInformation(textForLuxon);
+        const luxonOpts = opts?.zone
+            ? opts
+            : hasTimezoneInString
+                ? { setZone: true, ...opts }
+                : { zone: 'UTC', ...opts };
+        const luxonDatetime = wrapLuxonError(() => LuxonDateTime.fromISO(textForLuxon, luxonOpts));
         return new DateTime(luxonDatetime, microsecond);
     }
     /**
      * Create a DateTime from an SQL datetime string.
      * @param text - SQL string (e.g. "2024-03-15 10:30:45.123456"); parses up to 6 fractional second digits
-     * @param opts - Optional parsing options
+     * @param opts - Optional configuration
+     * @param opts.zone - Timezone to interpret the datetime in (overrides timezone in string)
+     * @param opts.locale - Locale string (e.g., 'en-US', 'fr-FR')
+     * @param opts.numberingSystem - Numbering system (e.g., 'arab', 'beng')
+     * @param opts.outputCalendar - Calendar system (e.g., 'islamic', 'hebrew')
      * @returns A DateTime for the parsed instant
      * @example
      * ```ts
      * DateTime.fromSQL('2024-03-15 10:30:45.123456')
+     * DateTime.fromSQL('2024-03-15 10:30:45', { zone: 'America/New_York' })
      * ```
      */
     static fromSQL(text, opts) {
         const { microsecond } = parseFractionalPart(text);
         const textForLuxon = toThreeDecimalFraction(text);
-        const luxonDatetime = wrapLuxonError(() => LuxonDateTime.fromSQL(textForLuxon, opts));
+        const luxonOpts = opts?.zone ? opts : { zone: 'UTC', ...opts };
+        const luxonDatetime = wrapLuxonError(() => LuxonDateTime.fromSQL(textForLuxon, luxonOpts));
         return new DateTime(luxonDatetime, microsecond);
     }
     /**
@@ -499,39 +556,34 @@ export class DateTime {
      * ```
      */
     static fromFormat(text, format, opts) {
-        // Check if format includes microsecond token ('u' or 'SSSSSS')
         const hasMicrosecondToken = format.includes('.u') || format.includes('.SSSSSS');
-        let microsecond = 0;
-        if (hasMicrosecondToken) {
-            // Extract microseconds from the text
-            const { microsecond: extractedMicrosecond } = parseFractionalPart(text);
-            microsecond = extractedMicrosecond;
-            // Replace microsecond token with millisecond token for Luxon
-            // 'u' -> 'SSS' (Luxon only supports milliseconds)
-            // 'SSSSSS' -> 'SSS'
-            const formatForLuxon = format.replace(/\.u\b/, '.SSS').replace(/\.SSSSSS\b/, '.SSS');
-            // Truncate fractional part to 3 digits for Luxon
-            const textForLuxon = toThreeDecimalFraction(text);
-            const luxonDatetime = wrapLuxonError(() => LuxonDateTime.fromFormat(textForLuxon, formatForLuxon, opts));
-            return new DateTime(luxonDatetime, microsecond);
-        }
-        else {
-            // No microsecond token, use Luxon directly
-            const luxonDatetime = wrapLuxonError(() => LuxonDateTime.fromFormat(text, format, opts));
-            return new DateTime(luxonDatetime, 0);
-        }
+        const microsecond = hasMicrosecondToken ? parseFractionalPart(text).microsecond : 0;
+        const textForLuxon = hasMicrosecondToken ? toThreeDecimalFraction(text) : text;
+        const formatForLuxon = hasMicrosecondToken
+            ? format.replace(/\.u\b/, '.SSS').replace(/\.SSSSSS\b/, '.SSS')
+            : format;
+        const luxonDatetime = wrapLuxonError(() => LuxonDateTime.fromFormat(textForLuxon, formatForLuxon, opts));
+        return new DateTime(luxonDatetime, microsecond);
     }
     /**
      * Returns an ISO 8601 string with 6 fractional second digits (milliseconds + microseconds).
-     * @param opts - Optional format options (includeOffset, suppressMilliseconds, etc.)
-     * @returns ISO string (e.g. "2024-03-15T10:30:45.123456-05:00")
+     *
+     * Always converts to UTC before formatting (e.g., '2024-03-15T15:30:45.123456Z').
+     *
+     * @param opts - Optional format options
+     * @param opts.suppressMilliseconds - If true, omits fractional seconds when they are zero
+     * @param opts.suppressSeconds - If true, omits seconds when they are zero
+     * @param opts.includeOffset - If true, includes timezone offset
+     * @param opts.format - Format variant: 'basic' (compact) or 'extended' (default, with separators)
+     * @returns ISO string (e.g. "2024-03-15T10:30:45.123456-05:00" or "2024-03-15T10:30:45.123456Z")
      * @example
      * ```ts
-     * DateTime.fromISO('2024-03-15T10:30:45.123456').toISO()
+     * DateTime.fromISO('2024-03-15T10:30:45.123456').toISO() // Converts to UTC
      * ```
      */
     toISO(opts) {
-        return replaceISOMicroseconds(this, this.luxonDatetime.toISO(opts), opts);
+        const dt = this.toUTC();
+        return replaceISOMicroseconds(dt, dt.luxonDatetime.toISO(opts), opts);
     }
     /**
      * Returns an ISO date string (date only, no time).
@@ -546,27 +598,44 @@ export class DateTime {
     }
     /**
      * Returns the time portion in ISO format with 6 fractional second digits.
+     *
+     * Omits timezone offset by default (e.g., '10:30:45.123456').
+     *
      * @param opts - Optional format options
-     * @returns Time string (e.g. "10:30:45.123456-05:00")
+     * @param opts.suppressMilliseconds - If true, omits fractional seconds when they are zero
+     * @param opts.suppressSeconds - If true, omits seconds when they are zero
+     * @param opts.includeOffset - If true, includes timezone offset
+     * @param opts.format - Format variant: 'basic' (compact) or 'extended' (default, with colons)
+     * @returns Time string (e.g. "10:30:45.123456" or "10:30:45.123456-05:00")
      * @example
      * ```ts
-     * DateTime.local(2017, 3, 12, 10, 30, 45, 123, 456).toISOTime()
+     * DateTime.local(2017, 3, 12, 10, 30, 45, 123, 456).toISOTime() // '10:30:45.123456'
      * ```
      */
     toISOTime(opts) {
-        return replaceISOMicroseconds(this, this.luxonDatetime.toISOTime(opts), opts);
+        return replaceISOMicroseconds(this, this.luxonDatetime.toISOTime({
+            includeOffset: false,
+            ...opts,
+        }), opts);
     }
     /**
      * Returns an SQL datetime string with 6 fractional second digits.
-     * @param opts - Optional format options
+     *
+     * Always converts to UTC before formatting (e.g., '2024-03-15 15:30:45.123456').
+     *
      * @returns SQL string (e.g. "2024-03-15 10:30:45.123456")
      * @example
      * ```ts
-     * DateTime.local(2017, 3, 12, 10, 30, 45, 123, 456).toSQL()
+     * DateTime.local(2017, 3, 12, 10, 30, 45, 123, 456).toSQL() // Converts to UTC
      * ```
      */
-    toSQL(opts) {
-        return replaceISOMicroseconds(this, this.luxonDatetime.toSQL(opts), opts);
+    _toSQL;
+    toSQL() {
+        if (this._toSQL)
+            return this._toSQL;
+        const dt = this.toUTC();
+        this._toSQL = replaceISOMicroseconds(dt, dt.luxonDatetime.toSQL(), {});
+        return this._toSQL;
     }
     /**
      * Returns an SQL date string (date only, no time).
@@ -581,15 +650,22 @@ export class DateTime {
     }
     /**
      * Returns an SQL time string with 6 fractional second digits.
-     * @param opts - Optional format options
+     *
+     * Omits timezone offset by default.
+     *
+     * @param opts - Optional SQL time format options
+     * @param opts.includeOffset - If true, includes timezone offset
      * @returns SQL time string (e.g. "10:30:45.123456")
      * @example
      * ```ts
-     * DateTime.local(2017, 3, 12, 10, 30, 45, 123, 456).toSQLTime()
+     * DateTime.local(2017, 3, 12, 10, 30, 45, 123, 456).toSQLTime() // '10:30:45.123456'
+     * DateTime.local(2017, 3, 12, 10, 30, 45, 123, 456).toSQLTime({ includeOffset: true }) // '10:30:45.123456 -04:00'
      * ```
      */
-    toSQLTime(opts) {
-        return replaceISOMicroseconds(this, this.luxonDatetime.toSQLTime(opts), opts);
+    toSQLTime(opts = {}) {
+        return replaceISOMicroseconds(this, this.luxonDatetime.toSQLTime({
+            includeOffset: opts.includeOffset ?? false,
+        }), {});
     }
     /**
      * Returns a JavaScript Date object.
@@ -603,21 +679,30 @@ export class DateTime {
         return this.luxonDatetime.toJSDate();
     }
     /**
-     * Returns the epoch time in microseconds (for valueOf() operations).
-     * Includes full microsecond precision.
-     * @returns Unix timestamp in microseconds
+     * Returns an ISO 8601 string representation (for valueOf() operations).
+     *
+     * Converts to UTC before formatting.
+     *
+     * @returns ISO datetime string with microsecond precision
      * @example
      * ```ts
-     * DateTime.local(2017, 3, 12).valueOf()
-     * DateTime.fromISO('2026-02-07T09:03:44.123456Z').valueOf()  // includes microseconds
+     * DateTime.local(2017, 3, 12).valueOf() // Converts to UTC
+     * DateTime.fromISO('2026-02-07T09:03:44.123456Z').valueOf()              // '2026-02-07T09:03:44.123456Z'
      * ```
      */
+    _valueOf;
     valueOf() {
-        return this.toMicroseconds();
+        if (this._valueOf)
+            return this._valueOf;
+        this._valueOf = this.toISO();
+        return this._valueOf;
     }
     /**
      * Returns an ISO 8601 formatted string for JSON serialization.
      * This ensures DateTime objects are properly serialized to ISO format.
+     *
+     * Converts to UTC before formatting.
+     *
      * @returns ISO datetime string with microsecond precision
      * @example
      * ```ts
@@ -631,6 +716,9 @@ export class DateTime {
     /**
      * Returns an ISO 8601 formatted string representation.
      * Alias for toISO().
+     *
+     * Converts to UTC before formatting.
+     *
      * @returns ISO datetime string with microsecond precision
      * @example
      * ```ts
@@ -644,12 +732,17 @@ export class DateTime {
     }
     /**
      * Returns a localized string representation.
-     * @param formatOpts - Optional format options
-     * @param opts - Optional locale options
+     * @param formatOpts - Intl.DateTimeFormat options for formatting
+     * @param opts - Optional locale configuration
+     * @param opts.locale - Locale string (e.g., 'en-US', 'fr-FR')
+     * @param opts.numberingSystem - Numbering system (e.g., 'arab', 'beng')
+     * @param opts.outputCalendar - Calendar system (e.g., 'islamic', 'hebrew')
      * @returns Localized string
      * @example
      * ```ts
      * DateTime.local(2017, 3, 12).toLocaleString()
+     * DateTime.local(2017, 3, 12).toLocaleString(DateTime.DATE_FULL)
+     * DateTime.local(2017, 3, 12).toLocaleString({ weekday: 'long' }, { locale: 'fr-FR' })
      * ```
      */
     toLocaleString(formatOpts, opts) {
@@ -673,7 +766,6 @@ export class DateTime {
         // Check if format contains fractional second tokens (S)
         const fractionalMatch = fmt.match(/S+/);
         if (!fractionalMatch) {
-            // No fractional seconds, just use Luxon's toFormat
             return this.luxonDatetime.toFormat(fmt, opts);
         }
         const tokenLength = fractionalMatch[0].length;
@@ -699,35 +791,10 @@ export class DateTime {
      * ```
      */
     plus(duration) {
-        const durationObj = typeof duration === 'number' ? { milliseconds: duration } : duration;
-        const { microseconds: microsecondsToAdd = 0, millisecond, milliseconds, ...rest } = durationObj;
-        // Handle both millisecond and milliseconds (prefer milliseconds if both are present)
-        const millisecondsToAdd = milliseconds ?? millisecond;
-        let microsecondsAdjusted = microsecondsToAdd;
-        // Build the object to pass to Luxon
-        const luxonDuration = { ...rest };
-        // Always handle fractional milliseconds by converting to microseconds
-        if (millisecondsToAdd !== undefined) {
-            const wholeMilli = Math.floor(millisecondsToAdd);
-            const fractionalMilli = millisecondsToAdd - wholeMilli;
-            microsecondsAdjusted += Math.round(fractionalMilli * 1000);
-            if (milliseconds !== undefined) {
-                luxonDuration.milliseconds = wholeMilli;
-            }
-            else {
-                luxonDuration.millisecond = wholeMilli;
-            }
-        }
+        const { luxonDuration, microsecondDelta } = splitDurationAndMicroseconds(duration);
         const luxonDatetime = this.luxonDatetime.plus(luxonDuration);
-        // Calculate total microseconds as: (current microseconds) + (microseconds to add)
-        // This works with both positive and negative values
-        const totalMicroseconds = this.microsecond + microsecondsAdjusted;
-        // Normalize the microseconds
-        const millisecondAdjustment = Math.floor(totalMicroseconds / 1000);
-        const finalMicroseconds = ((totalMicroseconds % 1000) + 1000) % 1000; // Ensure 0-999 range
-        return new DateTime(millisecondAdjustment !== 0
-            ? luxonDatetime.plus({ milliseconds: millisecondAdjustment })
-            : luxonDatetime, finalMicroseconds);
+        const normalized = normalizeMicrosecondTotal(this.microsecond + microsecondDelta);
+        return new DateTime(applyMillisecondAdjustment(luxonDatetime, normalized.millisecondAdjustment), normalized.microseconds);
     }
     /**
      * Subtracts a duration from this DateTime. Supports microsecond via DurationLikeObject.
@@ -741,34 +808,10 @@ export class DateTime {
      * ```
      */
     minus(duration) {
-        const durationObj = typeof duration === 'number' ? { milliseconds: duration } : duration;
-        const { microseconds: microsecondsToSubtract = 0, millisecond, milliseconds, ...rest } = durationObj;
-        // Handle both millisecond and milliseconds (prefer milliseconds if both are present)
-        const millisecondsToSubtract = milliseconds ?? millisecond;
-        let microsecondsAdjusted = microsecondsToSubtract;
-        // Build the object to pass to Luxon
-        const luxonDuration = { ...rest };
-        // Always handle fractional milliseconds by converting to microseconds
-        if (millisecondsToSubtract !== undefined) {
-            const wholeMilli = Math.floor(millisecondsToSubtract);
-            const fractionalMilli = millisecondsToSubtract - wholeMilli;
-            microsecondsAdjusted += Math.round(fractionalMilli * 1000);
-            if (milliseconds !== undefined) {
-                luxonDuration.milliseconds = wholeMilli;
-            }
-            else {
-                luxonDuration.millisecond = wholeMilli;
-            }
-        }
+        const { luxonDuration, microsecondDelta } = splitDurationAndMicroseconds(duration);
         const luxonDatetime = this.luxonDatetime.minus(luxonDuration);
-        // Calculate total microseconds as: (current microseconds) - (microseconds to subtract)
-        const totalMicroseconds = this.microsecond - microsecondsAdjusted;
-        // Normalize the microseconds
-        const millisecondAdjustment = Math.floor(totalMicroseconds / 1000);
-        const finalMicroseconds = ((totalMicroseconds % 1000) + 1000) % 1000; // Ensure 0-999 range
-        return new DateTime(millisecondAdjustment !== 0
-            ? luxonDatetime.plus({ milliseconds: millisecondAdjustment })
-            : luxonDatetime, finalMicroseconds);
+        const normalized = normalizeMicrosecondTotal(this.microsecond - microsecondDelta);
+        return new DateTime(applyMillisecondAdjustment(luxonDatetime, normalized.millisecondAdjustment), normalized.microseconds);
     }
     /**
      * Returns a new DateTime with the given units set.
@@ -787,16 +830,24 @@ export class DateTime {
     }
     /**
      * Returns an object with date/time components including microsecond.
-     * @param opts - Optional options (includeConfig for Luxon config)
      * @returns Object with year, month, day, hour, minute, second, millisecond, microsecond
      * @example
      * ```ts
      * DateTime.local(2017, 3, 12, 5, 45, 10, 123, 456).toObject()
      * ```
      */
-    toObject(opts) {
-        const obj = this.luxonDatetime.toObject(opts);
-        return { ...obj, microsecond: this.microsecond };
+    toObject() {
+        const obj = this.luxonDatetime.toObject();
+        return {
+            year: obj.year,
+            month: obj.month,
+            day: obj.day,
+            hour: obj.hour,
+            minute: obj.minute,
+            second: obj.second,
+            millisecond: obj.millisecond,
+            microsecond: this.microsecond,
+        };
     }
     /**
      * Returns true if this and other represent the same instant and microsecond.
@@ -808,9 +859,7 @@ export class DateTime {
      * ```
      */
     equals(other) {
-        if (!this.luxonDatetime.equals(other.luxonDatetime))
-            return false;
-        return this.microsecond === other.microsecond;
+        return this.valueOf() === other.valueOf();
     }
     /**
      * Returns the epoch time in milliseconds (toMillis * 1000 + millisecond).
@@ -853,20 +902,38 @@ export class DateTime {
         return luxonSeconds + additionalMicroseconds;
     }
     /**
-     * Returns the epoch time in seconds as an integer (floor of toSeconds).
-     * Truncates any fractional seconds, returning only the whole seconds portion.
-     * Equivalent to Math.floor(toSeconds()).
-     * @returns Unix timestamp in seconds (integer only, no fractional part)
+     * Returns the epoch time in seconds as an integer, truncating any fractional part.
      * @example
      * ```ts
-     * DateTime.fromSeconds(1707234567).toUnixInteger()  // 1707234567
-     * DateTime.fromISO('2026-02-07T09:03:44.123456Z').toUnixInteger()  // 1770455024 (fractional part truncated)
-     * DateTime.fromISO('2026-02-07T09:03:44.999999Z').toUnixInteger()  // 1770455024 (not rounded up)
+     * DateTime.fromISO('2026-02-07T09:03:44.123456Z').unixIntegerSeconds  // 1770455024
+     * DateTime.fromISO('2026-02-07T09:03:44.999999Z').unixIntegerSeconds  // 1770455024 (not rounded up)
      * ```
      */
-    toUnixInteger() {
+    get unixIntegerSeconds() {
         return Math.floor(this.toSeconds());
     }
+    /**
+     * Returns the epoch time in milliseconds as an integer, truncating any fractional part.
+     * @example
+     * ```ts
+     * DateTime.fromISO('2026-02-07T09:03:44.123456Z').unixIntegerMilliseconds  // 1770455024123
+     * DateTime.fromISO('2026-02-07T09:03:44.123999Z').unixIntegerMilliseconds  // 1770455024123 (not rounded up)
+     * ```
+     */
+    get unixIntegerMilliseconds() {
+        return Math.floor(this.toMillis());
+    }
+    /**
+     * Returns the epoch time in microseconds as an integer.
+     * Equivalent to `toMicroseconds()` since microseconds are always whole numbers.
+     * @example
+     * ```ts
+     * DateTime.fromISO('2026-02-07T09:03:44.123456Z').unixIntegerMicroseconds  // 1770455024123456
+     * ```
+     */
+    get unixIntegerMicroseconds() {
+        return this.toMicroseconds();
+    }
     /**
      * Returns the earliest DateTime from the given arguments.
      * @param dateTimes - DateTimes to compare
@@ -879,7 +946,7 @@ export class DateTime {
     static min(...dateTimes) {
         if (dateTimes.length === 0)
             return null;
-        return dateTimes.reduce((best, dt) => (dt.toMicroseconds() < best.toMicroseconds() ? dt : best), dateTimes[0]);
+        return dateTimes.reduce((min, datetime) => (datetime.valueOf() < min.valueOf() ? datetime : min), dateTimes[0]);
     }
     /**
      * Returns the latest DateTime from the given arguments.
@@ -893,7 +960,7 @@ export class DateTime {
     static max(...dateTimes) {
         if (dateTimes.length === 0)
             return null;
-        return dateTimes.reduce((best, dt) => (dt.toMicroseconds() > best.toMicroseconds() ? dt : best), dateTimes[0]);
+        return dateTimes.reduce((max, datetime) => (datetime.valueOf() > max.valueOf() ? datetime : max), dateTimes[0]);
     }
     /**
      * Returns a new DateTime in the given zone. Microsecond is preserved.
@@ -932,8 +999,7 @@ export class DateTime {
      * ```
      */
     toLocal() {
-        const luxonDatetime = this.luxonDatetime.toLocal();
-        return new DateTime(luxonDatetime, this.microsecond);
+        return new DateTime(this.luxonDatetime.toLocal(), this.microsecond);
     }
     /**
      * Returns a new DateTime at the start of the given unit.
@@ -1021,62 +1087,47 @@ export class DateTime {
      * dt1.diff(dt2, 'days') // { days: 5 }
      * dt1.diff(dt2, ['days', 'hours']) // { days: 5, hours: 3 }
      * dt1.diff(dt2, ['milliseconds', 'microseconds']) // { milliseconds: 123, microseconds: 456 }
-     * dt1.diff(dt2) // { years: 0, months: 0, ..., milliseconds: 123 }
+     * dt1.diff(dt2) // { years: 0, months: 0, days: 0, hours: 0, minutes: 0, seconds: 1, milliseconds: 500, microseconds: 0 }
      * ```
      */
     diff(other, unit) {
-        // Check if we need to calculate microseconds
-        const needsMicroseconds = unit === 'microseconds' ||
-            (Array.isArray(unit) && unit.includes('microseconds'));
-        // Check if we also need milliseconds
-        const needsMilliseconds = unit === 'milliseconds' ||
-            (Array.isArray(unit) && unit.includes('milliseconds'));
-        // Filter out 'microseconds' from the unit array since Luxon doesn't support it
-        let luxonUnits = unit;
-        if (Array.isArray(unit)) {
-            const filtered = unit.filter(u => u !== 'microseconds');
-            luxonUnits = filtered.length > 0 ? filtered : undefined;
+        const unitArray = normalizeDiffUnitArray(unit);
+        let result = {};
+        const onlyMicroseconds = unitArray.length === 1 && unitArray[0] === 'microseconds';
+        if (!onlyMicroseconds) {
+            const luxonUnitArray = normalizeDiffUnitArray(unitArray.filter(u => u !== 'microseconds'));
+            const luxonDuration = this.luxonDatetime.diff(other.toLuxon(), luxonUnitArray);
+            result = luxonDuration.toObject();
         }
-        else if (unit === 'microseconds') {
-            luxonUnits = undefined;
-        }
-        // Get Luxon's diff (which handles all units except microseconds)
-        const luxonDuration = this.luxonDatetime.diff(other.toLuxon(), luxonUnits);
-        const fullObject = luxonDuration.toObject();
-        // Calculate microsecond difference if needed
-        if (needsMicroseconds || unit === undefined) {
-            // When microseconds is the ONLY unit requested, return total microseconds
-            if (unit === 'microseconds') {
-                const thisTotalMicroseconds = this.toMicroseconds();
-                const otherTotalMicroseconds = other.toMicroseconds();
-                fullObject.microseconds = thisTotalMicroseconds - otherTotalMicroseconds;
+        const microsecondFieldDiff = this.microsecond - other.microsecond;
+        if (unitArray.includes('microseconds')) {
+            if (onlyMicroseconds) {
+                const millisecondDiff = this.luxonDatetime.diff(other.toLuxon(), 'milliseconds').milliseconds ?? 0;
+                result.microseconds = Math.round(millisecondDiff * 1000) + microsecondFieldDiff;
             }
             else {
-                // When microseconds is requested with other units, return only the fractional part (0-999)
-                const thisMicrosecond = this.microsecond;
-                const otherMicrosecond = other.microsecond;
-                fullObject.microseconds = thisMicrosecond - otherMicrosecond;
-            }
-            // If milliseconds are also requested/present, truncate them to whole numbers
-            // since the fractional part is now represented in microseconds
-            if ((needsMilliseconds || unit === undefined) && fullObject.milliseconds !== undefined) {
-                fullObject.milliseconds = Math.trunc(fullObject.milliseconds);
+                // Find the bottom (smallest) Luxon unit in the result and convert its
+                // entire value to microseconds, add the microsecond field diff, then
+                // split back. This handles borrowing/carrying automatically.
+                const bottomUnit = bottomLuxonUnit(result);
+                if (bottomUnit !== undefined) {
+                    const microsPerUnit = MICROSECONDS_PER_UNIT[bottomUnit];
+                    const totalMicros = Math.round(result[bottomUnit] * microsPerUnit) + microsecondFieldDiff;
+                    result[bottomUnit] = Math.trunc(totalMicros / microsPerUnit) || 0;
+                    result.microseconds = totalMicros - result[bottomUnit] * microsPerUnit;
+                }
+                else {
+                    result.microseconds = microsecondFieldDiff;
+                }
             }
         }
-        // If no unit specified, return all units (including microseconds)
-        if (unit === undefined) {
-            return fullObject;
-        }
-        // If unit is a single string, return only that unit
-        if (typeof unit === 'string') {
-            return { [unit]: fullObject[unit] ?? 0 };
+        else if (unitArray.includes('milliseconds')) {
+            result.milliseconds = (result.milliseconds ?? 0) + microsecondFieldDiff / 1000;
         }
-        // If unit is an array, return only those units
-        const result = {};
-        for (const u of unit) {
-            result[u] = fullObject[u] ?? 0;
-        }
-        return result;
+        const filtered = {};
+        for (const requestedUnit of unitArray)
+            filtered[requestedUnit] = result[requestedUnit] ?? 0;
+        return filtered;
     }
     /**
      * Returns the difference between this DateTime and now.
@@ -1112,33 +1163,84 @@ function wrapLuxonError(fn) {
  * @internal
  */
 function buildLocalOrUtcDateTime(yearOrOpts, month, day, hour, minute, second, millisecond, microsecondOrOpts, opts, isOpts, factory) {
-    const options = isOpts(opts)
-        ? opts
-        : isOpts(microsecondOrOpts)
-            ? microsecondOrOpts
-            : isOpts(millisecond)
-                ? millisecond
-                : isOpts(second)
-                    ? second
-                    : isOpts(minute)
-                        ? minute
-                        : isOpts(hour)
-                            ? hour
-                            : isOpts(day)
-                                ? day
-                                : isOpts(month)
-                                    ? month
-                                    : isOpts(yearOrOpts)
-                                        ? yearOrOpts
-                                        : undefined;
+    const options = firstOptionArg(isOpts, opts, microsecondOrOpts, millisecond, second, minute, hour, day, month, yearOrOpts);
     const { milliseconds: millisecondPartOfMicroseconds, microseconds } = microsecondParts(typeof microsecondOrOpts === 'number' ? microsecondOrOpts : 0);
-    const y = typeof yearOrOpts === 'number' ? yearOrOpts : 0;
-    const m = typeof month === 'number' ? month : 1;
-    const d = typeof day === 'number' ? day : 1;
-    const ms = (typeof millisecond === 'number' ? millisecond : 0) + millisecondPartOfMicroseconds;
-    const luxonDatetime = factory(y, m, d, typeof hour === 'number' ? hour : 0, typeof minute === 'number' ? minute : 0, typeof second === 'number' ? second : 0, ms, options);
+    const y = numericOrDefault(yearOrOpts, 0);
+    const m = numericOrDefault(month, 1);
+    const d = numericOrDefault(day, 1);
+    const ms = numericOrDefault(millisecond, 0) + millisecondPartOfMicroseconds;
+    const luxonDatetime = factory(y, m, d, numericOrDefault(hour, 0), numericOrDefault(minute, 0), numericOrDefault(second, 0), ms, options);
     return { luxonDatetime, microseconds };
 }
+function splitDurationAndMicroseconds(duration) {
+    const durationObj = typeof duration === 'number' ? { milliseconds: duration } : duration;
+    const { microsecond = 0, microseconds = 0, millisecond, milliseconds, ...rest } = durationObj;
+    const luxonDuration = { ...rest };
+    const millisecondInput = milliseconds ?? millisecond;
+    let microsecondDelta = microsecond + microseconds;
+    if (millisecondInput !== undefined) {
+        const wholeMilliseconds = Math.floor(millisecondInput);
+        const fractionalMilliseconds = millisecondInput - wholeMilliseconds;
+        microsecondDelta += Math.round(fractionalMilliseconds * 1000);
+        if (milliseconds !== undefined) {
+            luxonDuration.milliseconds = wholeMilliseconds;
+        }
+        else {
+            luxonDuration.millisecond = wholeMilliseconds;
+        }
+    }
+    return { luxonDuration: luxonDuration, microsecondDelta };
+}
+function normalizeMicrosecondTotal(totalMicroseconds) {
+    const millisecondAdjustment = Math.floor(totalMicroseconds / 1000);
+    const microseconds = ((totalMicroseconds % 1000) + 1000) % 1000;
+    return { millisecondAdjustment, microseconds };
+}
+function applyMillisecondAdjustment(datetime, milliseconds) {
+    return milliseconds !== 0 ? datetime.plus({ milliseconds }) : datetime;
+}
+function normalizeDiffUnitArray(unit) {
+    if (unit === undefined)
+        return DEFAULT_DIFF_UNITS_WITH_MICROSECONDS;
+    return typeof unit === 'string' ? [unit] : unit.length === 0 ? DEFAULT_DIFF_UNITS_WITH_MICROSECONDS : unit;
+}
+const DEFAULT_DIFF_UNITS_WITH_MICROSECONDS = [
+    'years',
+    'months',
+    'days',
+    'hours',
+    'minutes',
+    'seconds',
+    'milliseconds',
+    'microseconds',
+];
+/** Microseconds per Luxon unit, ordered from smallest to largest unit. */
+const MICROSECONDS_PER_UNIT = {
+    milliseconds: 1_000,
+    seconds: 1_000_000,
+    minutes: 60_000_000,
+    hours: 3_600_000_000,
+    days: 86_400_000_000,
+    weeks: 604_800_000_000,
+};
+/** Returns the smallest Luxon unit present in the result object (excluding microseconds). */
+function bottomLuxonUnit(result) {
+    for (const unit of Object.keys(MICROSECONDS_PER_UNIT)) {
+        if (result[unit] !== undefined)
+            return unit;
+    }
+    return undefined;
+}
+function numericOrDefault(value, fallback) {
+    return typeof value === 'number' ? value : fallback;
+}
+function firstOptionArg(isOpts, ...values) {
+    for (const value of values) {
+        if (isOpts(value))
+            return value;
+    }
+    return undefined;
+}
 /** Parse fractional part from ISO/SQL string: first 3 digits = ms, next 3 = µs */
 function parseFractionalPart(str) {
     const match = str.match(/\.(\d+)/);
@@ -1158,6 +1260,10 @@ function toThreeDecimalFraction(str) {
     const frac = (match[1] ?? '').padEnd(3, '0').slice(0, 3);
     return str.replace(/\.\d+/, '.' + frac);
 }
+const ISO_TIMEZONE_SUFFIX_REGEX = /(Z|[+-]\d{2}(?::?\d{2})?)$/i;
+function hasIsoTimezoneInformation(str) {
+    return ISO_TIMEZONE_SUFFIX_REGEX.test(str);
+}
 /**
  * Thrown when a DateTime is invalid (e.g. invalid input or Luxon error).
  * @param error - The original error (available as cause)