@rvoh/dream 2.2.3 → 2.3.0-alpha.1

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

@@ -0,0 +1,919 @@
+import * as luxon from 'luxon';
+import { DateTime as LuxonDateTime } from 'luxon';
+import round from '../../helpers/round.js';
+import { microsecondParts } from './helpers/microsecondParts.js';
+import replaceISOMicroseconds from './helpers/replaceISOMicroseconds.js';
+export const Settings = luxon.Settings;
+Settings.throwOnInvalid = true;
+/**
+ * DateTime wraps Luxon DateTime with microsecond precision (0-999).
+ * The decimal part in ISO/SQL is 6 digits: first 3 = milliseconds, next 3 = microseconds.
+ */
+export class DateTime {
+    luxonDatetime;
+    _microseconds;
+    /**
+     * Microsecond part of the DateTime (NOT microseconds since Unix epoch)
+     *
+     * This value will not exceed 999 because above that will carry over to the
+     * millisecond part of the DateTime
+     *
+     * @returns The microsecond of the second (0–999)
+     */
+    get microsecond() {
+        return this._microseconds;
+    }
+    // Proxied Luxon getters
+    get year() {
+        return this.luxonDatetime.year;
+    }
+    get month() {
+        return this.luxonDatetime.month;
+    }
+    get day() {
+        return this.luxonDatetime.day;
+    }
+    get hour() {
+        return this.luxonDatetime.hour;
+    }
+    get minute() {
+        return this.luxonDatetime.minute;
+    }
+    get second() {
+        return this.luxonDatetime.second;
+    }
+    get millisecond() {
+        return this.luxonDatetime.millisecond;
+    }
+    get weekday() {
+        return this.luxonDatetime.weekday;
+    }
+    /**
+     * Returns the lowercase name of the weekday.
+     * @returns Weekday name: 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', or 'sunday'
+     * @example
+     * ```ts
+     * DateTime.fromISO('2026-02-09T09:00:00Z').weekdayName  // 'monday' (Feb 9, 2026 is a Monday)
+     * DateTime.fromISO('2026-02-07T09:00:00Z').weekdayName  // 'saturday'
+     * ```
+     */
+    get weekdayName() {
+        const weekdayNumber = this.luxonDatetime.weekday; // 1 (Monday) to 7 (Sunday)
+        const weekdayNames = [
+            'monday',
+            'tuesday',
+            'wednesday',
+            'thursday',
+            'friday',
+            'saturday',
+            'sunday',
+        ];
+        return weekdayNames[weekdayNumber - 1];
+    }
+    get weekNumber() {
+        return this.luxonDatetime.weekNumber;
+    }
+    get weekYear() {
+        return this.luxonDatetime.weekYear;
+    }
+    get ordinal() {
+        return this.luxonDatetime.ordinal;
+    }
+    get quarter() {
+        return this.luxonDatetime.quarter;
+    }
+    get zoneName() {
+        return this.luxonDatetime.zoneName;
+    }
+    get offset() {
+        return this.luxonDatetime.offset;
+    }
+    get isValid() {
+        return this.luxonDatetime.isValid;
+    }
+    get invalidReason() {
+        return this.luxonDatetime.invalidReason;
+    }
+    get invalidExplanation() {
+        return this.luxonDatetime.invalidExplanation;
+    }
+    get locale() {
+        return this.luxonDatetime.locale;
+    }
+    get zone() {
+        return this.luxonDatetime.zone;
+    }
+    constructor(luxonDatetime, microseconds = 0) {
+        this.luxonDatetime = luxonDatetime;
+        this._microseconds = microseconds;
+    }
+    /**
+     * Returns the underlying Luxon DateTime instance.
+     * Since Luxon is immutable, it is safe to return the actual object.
+     * @returns The Luxon DateTime instance
+     * @example
+     * ```ts
+     * const dt = DateTime.now()
+     * const luxon = dt.toLuxon()
+     * ```
+     */
+    toLuxon() {
+        return this.luxonDatetime;
+    }
+    /**
+     * Returns the current time in the system's local zone.
+     * @returns A DateTime for the current instant
+     * @example
+     * ```ts
+     * const now = DateTime.now()
+     * ```
+     */
+    static now() {
+        return new DateTime(LuxonDateTime.now(), 0);
+    }
+    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));
+        return new DateTime(luxonDatetime, microseconds);
+    }
+    static utc(yearOrOpts, month, day, hour, minute, second, millisecond, microsecondOrOpts, options) {
+        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));
+        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
+     * @returns A DateTime representing the same instant
+     * @example
+     * ```ts
+     * DateTime.fromJSDate(new Date())
+     * DateTime.fromJSDate(new Date(), { zone: 'America/New_York' })
+     * ```
+     */
+    static fromJSDate(date, options) {
+        const luxonDatetime = options
+            ? // @ts-expect-error - exactOptionalPropertyTypes incompatibility with Luxon types
+                LuxonDateTime.fromJSDate(date, options)
+            : 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
+     * @returns A DateTime for the given instant
+     * @example
+     * ```ts
+     * DateTime.fromMillis(1707234567890)
+     * ```
+     */
+    static fromMillis(milliseconds, options) {
+        const luxonDatetime = LuxonDateTime.fromMillis(milliseconds, options);
+        return new DateTime(luxonDatetime, 0);
+    }
+    /**
+     * Create a DateTime from epoch microseconds.
+     * @param microseconds - Unix timestamp in microseconds (milliseconds from quotient, microsecond from remainder)
+     * @param options - Optional zone/locale options
+     * @returns A DateTime for the given instant
+     * @example
+     * ```ts
+     * DateTime.fromMicroseconds(1707234567890123)
+     * ```
+     */
+    static fromMicroseconds(microsecondsInput, options) {
+        const { milliseconds, microseconds } = microsecondParts(microsecondsInput);
+        const luxonDatetime = LuxonDateTime.fromMillis(milliseconds, options);
+        return new DateTime(luxonDatetime, microseconds);
+    }
+    /**
+     * Create a DateTime from epoch seconds.
+     * @param seconds - Unix timestamp in seconds
+     * @param options - Optional zone/locale options
+     * @returns A DateTime for the given instant
+     * @example
+     * ```ts
+     * DateTime.fromSeconds(1707234567)
+     * ```
+     */
+    static fromSeconds(seconds, options) {
+        const luxonDatetime = LuxonDateTime.fromSeconds(seconds, options);
+        return new DateTime(luxonDatetime, 0);
+    }
+    /**
+     * 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
+     * @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
+     * ```
+     */
+    static fromObject(obj, opts) {
+        const { microsecond, millisecond, ...rest } = obj;
+        let microsecondsTotal = microsecond ?? 0;
+        // Handle fractional milliseconds by converting to microseconds
+        let adjustedMillisecond = millisecond;
+        if (millisecond !== undefined) {
+            const wholeMilli = Math.floor(millisecond);
+            const fractionalMilli = millisecond - wholeMilli;
+            microsecondsTotal += Math.round(fractionalMilli * 1000);
+            adjustedMillisecond = wholeMilli;
+        }
+        const { milliseconds, microseconds } = microsecondParts(microsecondsTotal);
+        const luxonDatetime = wrapLuxonError(() => LuxonDateTime.fromObject({ ...rest, millisecond: adjustedMillisecond }, 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
+     * @returns A DateTime for the parsed instant
+     * @example
+     * ```ts
+     * DateTime.fromISO('2024-03-15T10:30:45.123456-05:00')
+     * ```
+     */
+    static fromISO(text, opts) {
+        const { microsecond } = parseFractionalPart(text);
+        const textForLuxon = toThreeDecimalFraction(text);
+        const luxonDatetime = wrapLuxonError(() => LuxonDateTime.fromISO(textForLuxon, opts));
+        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
+     * @returns A DateTime for the parsed instant
+     * @example
+     * ```ts
+     * DateTime.fromSQL('2024-03-15 10:30:45.123456')
+     * ```
+     */
+    static fromSQL(text, opts) {
+        const { microsecond } = parseFractionalPart(text);
+        const textForLuxon = toThreeDecimalFraction(text);
+        const luxonDatetime = wrapLuxonError(() => LuxonDateTime.fromSQL(textForLuxon, 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")
+     * @example
+     * ```ts
+     * DateTime.fromISO('2024-03-15T10:30:45.123456').toISO()
+     * ```
+     */
+    toISO(opts) {
+        return replaceISOMicroseconds(this, this.luxonDatetime.toISO(opts), opts);
+    }
+    /**
+     * Returns an ISO date string (date only, no time).
+     * @returns ISO date string (e.g. "2024-03-15")
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12).toISODate()
+     * ```
+     */
+    toISODate() {
+        return this.luxonDatetime.toISODate();
+    }
+    /**
+     * Returns the time portion in ISO format with 6 fractional second digits.
+     * @param opts - Optional format options
+     * @returns Time string (e.g. "10:30:45.123456-05:00")
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12, 10, 30, 45, 123, 456).toISOTime()
+     * ```
+     */
+    toISOTime(opts) {
+        return replaceISOMicroseconds(this, this.luxonDatetime.toISOTime(opts), opts);
+    }
+    /**
+     * Returns an SQL datetime string with 6 fractional second digits.
+     * @param opts - Optional format options
+     * @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()
+     * ```
+     */
+    toSQL(opts) {
+        return replaceISOMicroseconds(this, this.luxonDatetime.toSQL(opts), opts);
+    }
+    /**
+     * Returns an SQL date string (date only, no time).
+     * @returns SQL date string (e.g. "2024-03-15")
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12).toSQLDate()
+     * ```
+     */
+    toSQLDate() {
+        return this.luxonDatetime.toSQLDate();
+    }
+    /**
+     * Returns an SQL time string with 6 fractional second digits.
+     * @param opts - Optional format options
+     * @returns SQL time string (e.g. "10:30:45.123456")
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12, 10, 30, 45, 123, 456).toSQLTime()
+     * ```
+     */
+    toSQLTime(opts) {
+        return replaceISOMicroseconds(this, this.luxonDatetime.toSQLTime(opts), opts);
+    }
+    /**
+     * Returns a JavaScript Date object.
+     * @returns JavaScript Date
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12).toJSDate()
+     * ```
+     */
+    toJSDate() {
+        return this.luxonDatetime.toJSDate();
+    }
+    /**
+     * Returns the epoch time in microseconds (for valueOf() operations).
+     * Includes full microsecond precision.
+     * @returns Unix timestamp in microseconds
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12).valueOf()
+     * DateTime.fromISO('2026-02-07T09:03:44.123456Z').valueOf()  // includes microseconds
+     * ```
+     */
+    valueOf() {
+        return this.toMicroseconds();
+    }
+    /**
+     * Returns an ISO 8601 formatted string for JSON serialization.
+     * This ensures DateTime objects are properly serialized to ISO format.
+     * @returns ISO datetime string with microsecond precision
+     * @example
+     * ```ts
+     * DateTime.fromISO('2026-02-07T09:03:44.123456Z').toJSON()  // '2026-02-07T09:03:44.123456Z'
+     * JSON.stringify({ time: DateTime.now() })  // Uses toJSON() automatically
+     * ```
+     */
+    toJSON() {
+        return this.toISO();
+    }
+    /**
+     * Returns an ISO 8601 formatted string representation.
+     * Alias for toISO().
+     * @returns ISO datetime string with microsecond precision
+     * @example
+     * ```ts
+     * DateTime.fromISO('2026-02-07T09:03:44.123456Z').toString()  // '2026-02-07T09:03:44.123456Z'
+     * const dt = DateTime.local(2017, 3, 12, 10, 30, 45, 123, 456)
+     * `The time is ${dt}`  // Uses toString() implicitly
+     * ```
+     */
+    toString() {
+        return this.toISO();
+    }
+    /**
+     * Returns a localized string representation.
+     * @param formatOpts - Optional format options
+     * @param opts - Optional locale options
+     * @returns Localized string
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12).toLocaleString()
+     * ```
+     */
+    toLocaleString(formatOpts, opts) {
+        return this.luxonDatetime.toLocaleString(formatOpts, opts);
+    }
+    /**
+     * Returns a string representation using a format string.
+     * Supports all Luxon format tokens. Fractional second tokens (S, SSS, SSSSSS) are enhanced
+     * to include microseconds beyond Luxon's millisecond precision.
+     *
+     * @param fmt - Format string (e.g., 'yyyy-MM-dd HH:mm:ss', 'yyyy-MM-dd HH:mm:ss.SSSSSS')
+     * @param opts - Optional locale options
+     * @returns Formatted string
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12).toFormat('yyyy-MM-dd')  // '2017-03-12'
+     * DateTime.local(2017, 3, 12, 10, 30, 45, 123, 456).toFormat('yyyy-MM-dd HH:mm:ss.SSSSSS')  // '2017-03-12 10:30:45.123456'
+     * ```
+     */
+    toFormat(fmt, opts) {
+        // 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;
+        // Build the full fractional string (milliseconds + microseconds)
+        const fullFractional = String(this.millisecond).padStart(3, '0') + String(this.microsecond).padStart(3, '0');
+        // Pad or truncate to match the requested length
+        const fractionalOutput = fullFractional.padEnd(tokenLength, '0').slice(0, tokenLength);
+        // Replace S tokens with the literal fractional digits (escaped for Luxon)
+        // We need to escape the fractional output so Luxon treats it as literal text
+        const modifiedFmt = fmt.replace(/S+/, `'${fractionalOutput}'`);
+        return this.luxonDatetime.toFormat(modifiedFmt, opts);
+    }
+    /**
+     * Adds a duration to this DateTime. Supports microsecond via DurationLikeObject.
+     * Fractional milliseconds are converted to microseconds (e.g., 1.5 ms = 1 ms + 500 µs).
+     * @param duration - Duration to add (DurationLikeObject with microsecond, or milliseconds number)
+     * @returns A new DateTime
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12).plus({ hours: 2 })
+     * DateTime.local(2017, 3, 12, 0, 0, 0, 0, 500).plus({ microseconds: 600 })
+     * DateTime.local(2017, 3, 12).plus({ milliseconds: 1.5 }) // adds 1ms + 500µs
+     * ```
+     */
+    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 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);
+    }
+    /**
+     * Subtracts a duration from this DateTime. Supports microsecond via DurationLikeObject.
+     * Fractional milliseconds are converted to microseconds (e.g., 1.5 ms = 1 ms + 500 µs).
+     * @param duration - Duration to subtract
+     * @returns A new DateTime
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12, 14).minus({ hours: 2 })
+     * DateTime.local(2017, 3, 12).minus({ milliseconds: 1.5 }) // subtracts 1ms + 500µs
+     * ```
+     */
+    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 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);
+    }
+    /**
+     * Returns a new DateTime with the given units set.
+     * @param values - Object with units to set (year, month, day, hour, minute, second, millisecond, microsecond)
+     * @returns A new DateTime
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12).set({ hour: 14, microsecond: 500 })
+     * ```
+     */
+    set(values) {
+        const { microsecond, ...rest } = values;
+        const luxonDatetime = this.luxonDatetime.set(rest);
+        const { milliseconds, microseconds } = microsecondParts(microsecond ?? this.microsecond);
+        return new DateTime(milliseconds > 0 ? luxonDatetime.plus({ milliseconds }) : luxonDatetime, microseconds);
+    }
+    /**
+     * 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 };
+    }
+    /**
+     * Returns true if this and other represent the same instant and microsecond.
+     * @param other - DateTime to compare
+     * @returns true if equal
+     * @example
+     * ```ts
+     * dt1.equals(dt2)
+     * ```
+     */
+    equals(other) {
+        if (!this.luxonDatetime.equals(other.luxonDatetime))
+            return false;
+        return this.microsecond === other.microsecond;
+    }
+    /**
+     * Returns the epoch time in milliseconds (toMillis * 1000 + millisecond).
+     * @returns Unix timestamp in milliseconds
+     * @example
+     * ```ts
+     * DateTime.fromMicroseconds(1770455024077750).toMillis()  // 1770455024077.75
+     * ```
+     */
+    toMillis() {
+        return round(this.luxonDatetime.toMillis() + this.microsecond / 1000, 3);
+    }
+    /**
+     * Returns the epoch time in microseconds (toMillis * 1000 + microsecond).
+     * @returns Unix timestamp in microseconds
+     * @example
+     * ```ts
+     * DateTime.fromMicroseconds(1707234567890123).toMicroseconds()  // 1707234567890123
+     * ```
+     */
+    toMicroseconds() {
+        return this.luxonDatetime.toMillis() * 1000 + this.microsecond;
+    }
+    /**
+     * Returns the epoch time in seconds, including fractional milliseconds.
+     * Includes microsecond precision in the fractional part.
+     * @returns Unix timestamp in seconds (with fractional milliseconds)
+     * @example
+     * ```ts
+     * DateTime.fromSeconds(1707234567).toSeconds()  // 1707234567
+     * DateTime.fromISO('2026-02-07T09:03:44.123456Z').toSeconds()  // includes .123456 in fractional part
+     * ```
+     */
+    toSeconds() {
+        // Get seconds from Luxon (which includes milliseconds in fractional part)
+        const luxonSeconds = this.luxonDatetime.toSeconds();
+        // Add microseconds to the fractional part
+        // luxonSeconds already has milliseconds, so we add the additional microseconds
+        const additionalMicroseconds = this.microsecond / 1_000_000;
+        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)
+     * @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)
+     * ```
+     */
+    toUnixInteger() {
+        return Math.floor(this.toSeconds());
+    }
+    /**
+     * Returns the earliest DateTime from the given arguments.
+     * @param dateTimes - DateTimes to compare
+     * @returns The earliest DateTime, or null if empty
+     * @example
+     * ```ts
+     * DateTime.min(dt1, dt2, dt3)
+     * ```
+     */
+    static min(...dateTimes) {
+        if (dateTimes.length === 0)
+            return null;
+        return dateTimes.reduce((best, dt) => (dt.toMicroseconds() < best.toMicroseconds() ? dt : best), dateTimes[0]);
+    }
+    /**
+     * Returns the latest DateTime from the given arguments.
+     * @param dateTimes - DateTimes to compare
+     * @returns The latest DateTime, or null if empty
+     * @example
+     * ```ts
+     * DateTime.max(dt1, dt2, dt3)
+     * ```
+     */
+    static max(...dateTimes) {
+        if (dateTimes.length === 0)
+            return null;
+        return dateTimes.reduce((best, dt) => (dt.toMicroseconds() > best.toMicroseconds() ? dt : best), dateTimes[0]);
+    }
+    /**
+     * Returns a new DateTime in the given zone. Microsecond is preserved.
+     * @param zone - Zone name or Zone instance
+     * @param opts - Optional zone options (keepLocalTime, etc.)
+     * @returns A new DateTime
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12).setZone('utc')
+     * ```
+     */
+    setZone(zone, opts) {
+        const luxonDatetime = this.luxonDatetime.setZone(zone, opts);
+        return new DateTime(luxonDatetime, this.microsecond);
+    }
+    /**
+     * Returns a new DateTime in UTC. Microsecond is preserved.
+     * @param offset - Optional offset in minutes
+     * @param opts - Optional zone options
+     * @returns A new DateTime in UTC
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12).toUTC()
+     * ```
+     */
+    toUTC(offset, opts) {
+        const luxonDatetime = this.luxonDatetime.toUTC(offset, opts);
+        return new DateTime(luxonDatetime, this.microsecond);
+    }
+    /**
+     * Returns a new DateTime in the system's local zone. Microsecond is preserved.
+     * @returns A new DateTime in local zone
+     * @example
+     * ```ts
+     * dtUTC.toLocal()
+     * ```
+     */
+    toLocal() {
+        const luxonDatetime = this.luxonDatetime.toLocal();
+        return new DateTime(luxonDatetime, this.microsecond);
+    }
+    /**
+     * Returns a new DateTime at the start of the given unit.
+     * Microsecond is 0 except when unit is 'millisecond' (then preserved).
+     * @param unit - Unit to truncate to (year, month, day, hour, minute, second, millisecond)
+     * @param opts - Optional options
+     * @returns A new DateTime
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12, 14, 30).startOf('day')   // 2017-03-12T00:00:00
+     * DateTime.local(2017, 3, 12, 14, 30).startOf('hour')  // 2017-03-12T14:00:00
+     * ```
+     */
+    startOf(unit, opts) {
+        const luxonDatetime = this.luxonDatetime.startOf(unit, opts);
+        const microseconds = unit === 'millisecond' ? this.microsecond : 0;
+        return new DateTime(luxonDatetime, microseconds);
+    }
+    /**
+     * Returns a new DateTime at the end of the given unit.
+     * Microsecond is 999 when unit is 'millisecond', else 0.
+     * @param unit - Unit to extend to end of
+     * @param opts - Optional options
+     * @returns A new DateTime
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12).endOf('month')   // 2017-03-31T23:59:59.999999
+     * DateTime.local(2017, 3, 12).endOf('day')    // 2017-03-12T23:59:59.999999
+     * ```
+     */
+    endOf(unit, opts) {
+        const luxonDatetime = this.luxonDatetime.endOf(unit, opts);
+        const microseconds = unit === 'millisecond' ? this.microsecond : 999;
+        return new DateTime(luxonDatetime, microseconds);
+    }
+    /**
+     * Returns a new DateTime with the given locale/zone options. Microsecond is preserved.
+     * @param properties - Locale and/or zone options
+     * @returns A new DateTime
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12).reconfigure({ locale: 'fr' })
+     * ```
+     */
+    reconfigure(properties) {
+        const luxonDatetime = this.luxonDatetime.reconfigure(properties);
+        return new DateTime(luxonDatetime, this.microsecond);
+    }
+    /**
+     * Returns a new DateTime with the given locale. Microsecond is preserved.
+     * @param locale - Locale string (e.g. 'en-US', 'fr')
+     * @returns A new DateTime
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12).setLocale('fr')
+     * ```
+     */
+    setLocale(locale) {
+        const luxonDatetime = this.luxonDatetime.setLocale(locale);
+        return new DateTime(luxonDatetime, this.microsecond);
+    }
+    /**
+     * Returns true if this DateTime is in the same unit as another.
+     * @param other - DateTime to compare
+     * @param unit - Unit to compare
+     * @returns true if same
+     * @example
+     * ```ts
+     * dt1.hasSame(dt2, 'day')
+     * ```
+     */
+    hasSame(other, unit) {
+        return this.luxonDatetime.hasSame(other.luxonDatetime, unit);
+    }
+    /**
+     * Returns the difference between this and another DateTime.
+     *
+     * Supports microsecond precision when 'microseconds' is included in the unit parameter.
+     *
+     * @param other - DateTime to diff against
+     * @param unit - Unit or units to return (e.g., 'days', 'hours', ['days', 'hours', 'microseconds'])
+     * @returns Object with only the specified units (or all units if not specified)
+     * @example
+     * ```ts
+     * 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 }
+     * ```
+     */
+    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;
+        }
+        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;
+            }
+            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);
+            }
+        }
+        // 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 };
+        }
+        // If unit is an array, return only those units
+        const result = {};
+        for (const u of unit) {
+            result[u] = fullObject[u] ?? 0;
+        }
+        return result;
+    }
+    /**
+     * Returns the difference between this DateTime and now.
+     *
+     * Supports microsecond precision when 'microseconds' is included in the unit parameter.
+     *
+     * @param unit - Unit or units to return
+     * @returns Object with only the specified units (or all units if not specified)
+     * @example
+     * ```ts
+     * dt.diffNow('days') // { days: 5 }
+     * dt.diffNow(['days', 'hours', 'microseconds']) // { days: 5, hours: 3, microseconds: 123 }
+     * ```
+     */
+    diffNow(unit) {
+        return this.diff(DateTime.now(), unit);
+    }
+}
+function wrapLuxonError(fn) {
+    try {
+        return fn();
+    }
+    catch (error) {
+        if (error instanceof Error)
+            throw new InvalidDateTime(error);
+        throw error;
+    }
+}
+/**
+ * Shared logic for local() and utc(): parses overloaded args, resolves options,
+ * normalizes microsecond, and calls the appropriate Luxon factory.
+ * Returns the Luxon instance and microsecond for the caller to wrap.
+ * @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 { 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);
+    return { luxonDatetime, microseconds };
+}
+/** Parse fractional part from ISO/SQL string: first 3 digits = ms, next 3 = µs */
+function parseFractionalPart(str) {
+    const match = str.match(/\.(\d+)/);
+    if (!match)
+        return { millisecond: 0, microsecond: 0 };
+    const frac = (match[1] ?? '').padEnd(6, '0').slice(0, 6);
+    return {
+        millisecond: parseInt(frac.slice(0, 3), 10),
+        microsecond: parseInt(frac.slice(3, 6), 10),
+    };
+}
+/** Reduce ISO/SQL string to 3 decimal places for Luxon (ms only) */
+function toThreeDecimalFraction(str) {
+    const match = str.match(/\.(\d+)/);
+    if (!match)
+        return str;
+    const frac = (match[1] ?? '').padEnd(3, '0').slice(0, 3);
+    return str.replace(/\.\d+/, '.' + frac);
+}
+/**
+ * Thrown when a DateTime is invalid (e.g. invalid input or Luxon error).
+ * @param error - The original error (available as cause)
+ * @example
+ * ```ts
+ * try {
+ *   DateTime.fromISO('invalid')
+ * } catch (e) {
+ *   if (e instanceof InvalidDateTime) console.error(e.cause)
+ * }
+ * ```
+ */
+export class InvalidDateTime extends Error {
+    constructor(error) {
+        super(error.message ?? '');
+        this.name = 'InvalidDateTime';
+        this.cause = error;
+    }
+}