@rvoh/dream 2.2.2 → 2.3.0-alpha.1

package/dist/types/src/utils/datetime/DateTime.d.ts

@@ -0,0 +1,597 @@
+import * as luxon from 'luxon';
+import { DateTime as LuxonDateTime } from 'luxon';
+import { DateTimeFormatOptions, DateTimeJSOptions, DateTimeObject, DateTimeOptions, DateTimeUnit, DiffResult, DurationLikeObject, DurationUnit, LocaleOptions, ToISOTimeOptions, ToSQLOptions, WeekdayName, Zone } from '../../types/datetime.js';
+export declare const Settings: typeof luxon.Settings;
+/**
+ * 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 declare class DateTime {
+    protected readonly luxonDatetime: LuxonDateTime;
+    protected readonly _microseconds: number;
+    /**
+     * 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(): number;
+    get year(): number;
+    get month(): number;
+    get day(): number;
+    get hour(): number;
+    get minute(): number;
+    get second(): number;
+    get millisecond(): number;
+    get weekday(): number;
+    /**
+     * 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(): WeekdayName;
+    get weekNumber(): number;
+    get weekYear(): number;
+    get ordinal(): number;
+    get quarter(): number;
+    get zoneName(): string;
+    get offset(): number;
+    get isValid(): boolean;
+    get invalidReason(): string | null;
+    get invalidExplanation(): string | null;
+    get locale(): string;
+    get zone(): Zone;
+    protected constructor(luxonDatetime: LuxonDateTime, microseconds?: number);
+    /**
+     * 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(): 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(): DateTime;
+    /**
+     * Create a local DateTime. Accepts the same overloads as Luxon plus an optional microsecond (8th numeric arg).
+     * The last argument may be an options object instead of a time component.
+     * @param yearOrOpts - Year, or options object when called with no args or opts only
+     * @param month - Month (1–12)
+     * @param day - Day of month
+     * @param hour - Hour (0–23)
+     * @param minute - Minute (0–59)
+     * @param second - Second (0–59)
+     * @param millisecond - Millisecond (0–999)
+     * @param microsecondOrOpts - Microsecond (0–999) or options object
+     * @param opts - Options (zone, locale, etc.)
+     * @returns A DateTime in the local zone
+     * @example
+     * ```ts
+     * DateTime.local()                                    // now
+     * DateTime.local(2017, 3, 12)                         // 2017-03-12T00:00:00
+     * DateTime.local(2017, 3, 12, 5, 45, 10, 765, 123)    // with microsecond
+     * DateTime.local(2017, 3, 12, { zone: 'utc' })        // with options
+     * ```
+     */
+    static local(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number, microsecond: number, opts?: DateTimeJSOptions): DateTime;
+    static local(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number, opts?: DateTimeJSOptions): DateTime;
+    static local(year: number, month: number, day: number, hour: number, minute: number, second: number, opts?: DateTimeJSOptions): DateTime;
+    static local(year: number, month: number, day: number, hour: number, minute: number, opts?: DateTimeJSOptions): DateTime;
+    static local(year: number, month: number, day: number, hour: number, opts?: DateTimeJSOptions): DateTime;
+    static local(year: number, month: number, day: number, opts?: DateTimeJSOptions): DateTime;
+    static local(year: number, month: number, opts?: DateTimeJSOptions): DateTime;
+    static local(year: number, opts?: DateTimeJSOptions): DateTime;
+    static local(opts?: DateTimeJSOptions): DateTime;
+    /**
+     * Create a UTC DateTime. Accepts the same overloads as Luxon plus an optional microsecond (8th numeric arg).
+     * The last argument may be an options object instead of a time component.
+     * @param yearOrOpts - Year, or options object when called with no args or opts only
+     * @param month - Month (1–12)
+     * @param day - Day of month
+     * @param hour - Hour (0–23)
+     * @param minute - Minute (0–59)
+     * @param second - Second (0–59)
+     * @param millisecond - Millisecond (0–999)
+     * @param microsecondOrOpts - Microsecond (0–999) or options object
+     * @param options - Options (locale, etc.)
+     * @returns A DateTime in UTC
+     * @example
+     * ```ts
+     * DateTime.utc()                                      // now in UTC
+     * DateTime.utc(2017, 3, 12, 5, 45, 10, 765, 123)     // with microsecond
+     * DateTime.utc(2017, 3, 12, { locale: 'fr' })        // with options
+     * ```
+     */
+    static utc(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number, microsecond: number, options?: LocaleOptions): DateTime;
+    static utc(year: number, month: number, day: number, hour: number, minute: number, second: number, options?: LocaleOptions): DateTime;
+    static utc(year: number, month: number, day: number, hour: number, minute: number, options?: LocaleOptions): DateTime;
+    static utc(year: number, month: number, day: number, hour: number, options?: LocaleOptions): DateTime;
+    static utc(year: number, month: number, day: number, options?: LocaleOptions): DateTime;
+    static utc(year: number, month: number, options?: LocaleOptions): DateTime;
+    static utc(year: number, options?: LocaleOptions): DateTime;
+    static utc(options?: LocaleOptions): DateTime;
+    /**
+     * 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: Date, options?: DateTimeJSOptions): DateTime;
+    /**
+     * 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: number, options?: DateTimeJSOptions): DateTime;
+    /**
+     * 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: number, options?: DateTimeJSOptions): DateTime;
+    /**
+     * 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: number, options?: DateTimeJSOptions): DateTime;
+    /**
+     * 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: DateTimeObject, opts?: DateTimeJSOptions): DateTime;
+    /**
+     * 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: string, opts?: DateTimeOptions): DateTime;
+    /**
+     * 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: string, opts?: DateTimeOptions): DateTime;
+    /**
+     * 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?: ToISOTimeOptions): string;
+    /**
+     * 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(): string;
+    /**
+     * 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?: ToISOTimeOptions): string;
+    /**
+     * 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?: ToSQLOptions): string;
+    /**
+     * 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(): string;
+    /**
+     * 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?: ToSQLOptions): string;
+    /**
+     * Returns a JavaScript Date object.
+     * @returns JavaScript Date
+     * @example
+     * ```ts
+     * DateTime.local(2017, 3, 12).toJSDate()
+     * ```
+     */
+    toJSDate(): Date;
+    /**
+     * 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(): number;
+    /**
+     * 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(): string;
+    /**
+     * 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(): string;
+    /**
+     * 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?: DateTimeFormatOptions, opts?: LocaleOptions): string;
+    /**
+     * 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: string, opts?: LocaleOptions): string;
+    /**
+     * 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: DurationLikeObject | number): DateTime;
+    /**
+     * 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: DurationLikeObject | number): DateTime;
+    /**
+     * 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: DateTimeObject): 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?: {
+        includeConfig?: boolean;
+    }): DateTimeObject;
+    /**
+     * 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: DateTime): boolean;
+    /**
+     * Returns the epoch time in milliseconds (toMillis * 1000 + millisecond).
+     * @returns Unix timestamp in milliseconds
+     * @example
+     * ```ts
+     * DateTime.fromMicroseconds(1770455024077750).toMillis()  // 1770455024077.75
+     * ```
+     */
+    toMillis(): number;
+    /**
+     * Returns the epoch time in microseconds (toMillis * 1000 + microsecond).
+     * @returns Unix timestamp in microseconds
+     * @example
+     * ```ts
+     * DateTime.fromMicroseconds(1707234567890123).toMicroseconds()  // 1707234567890123
+     * ```
+     */
+    toMicroseconds(): number;
+    /**
+     * 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(): number;
+    /**
+     * 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(): number;
+    /**
+     * 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: DateTime[]): DateTime | null;
+    /**
+     * 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: DateTime[]): DateTime | null;
+    /**
+     * 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?: string | Zone, opts?: {
+        keepLocalTime?: boolean;
+    }): DateTime;
+    /**
+     * 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?: number, opts?: {
+        keepLocalTime?: boolean;
+    }): DateTime;
+    /**
+     * 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(): DateTime;
+    /**
+     * 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: DateTimeUnit, opts?: {
+        useLocaleWeeks?: boolean;
+    }): DateTime;
+    /**
+     * 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: DateTimeUnit, opts?: {
+        useLocaleWeeks?: boolean;
+    }): DateTime;
+    /**
+     * 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: LocaleOptions): DateTime;
+    /**
+     * 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: string): DateTime;
+    /**
+     * 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: DateTime, unit: DateTimeUnit): boolean;
+    /**
+     * 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<U extends DurationUnit | readonly DurationUnit[] | undefined = undefined>(other: DateTime, unit?: U): DiffResult<U>;
+    /**
+     * 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<U extends DurationUnit | readonly DurationUnit[] | undefined = undefined>(unit?: U): DiffResult<U>;
+}
+/**
+ * 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 declare class InvalidDateTime extends Error {
+    constructor(error: Error);
+}

package/dist/types/src/utils/datetime/helpers/isoTimeDecimalString.d.ts

@@ -0,0 +1,4 @@
+import { DateTime } from '../DateTime.js';
+export default function isoTimeDecimalString(datetime: DateTime, { nullIfZero }: {
+    nullIfZero: boolean | undefined;
+}): string | null;

package/dist/types/src/utils/datetime/helpers/microsecondParts.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Normalizes a microsecond value: values > 999 become whole milliseconds + remainder (0–999).
+ * Throws for negative.
+ */
+export declare function microsecondParts(microsecondInput: number, { errorIfNegative }?: {
+    errorIfNegative?: boolean;
+}): {
+    milliseconds: number;
+    microseconds: number;
+};

package/dist/types/src/utils/datetime/helpers/replaceISOMicroseconds.d.ts

@@ -0,0 +1,3 @@
+import type { ToISOTimeOptions } from '../../../types/datetime.js';
+import type { DateTime } from '../DateTime.js';
+export default function replaceISOMicroseconds(timeObj: DateTime, isoString: string, opts: ToISOTimeOptions | undefined): string;

package/docs/assets/highlight.css

@@ -23,6 +23,8 @@
     --dark-hl-10: #F44747;
     --light-hl-11: #000000FF;
     --dark-hl-11: #D4D4D4;
+    --light-hl-12: #EE0000;
+    --dark-hl-12: #D7BA7D;
     --light-code-background: #FFFFFF;
     --dark-code-background: #1E1E1E;
 }
@@ -40,6 +42,7 @@
     --hl-9: var(--light-hl-9);
     --hl-10: var(--light-hl-10);
     --hl-11: var(--light-hl-11);
+    --hl-12: var(--light-hl-12);
     --code-background: var(--light-code-background);
 } }
 
@@ -56,6 +59,7 @@
     --hl-9: var(--dark-hl-9);
     --hl-10: var(--dark-hl-10);
     --hl-11: var(--dark-hl-11);
+    --hl-12: var(--dark-hl-12);
     --code-background: var(--dark-code-background);
 } }
 
@@ -72,6 +76,7 @@
     --hl-9: var(--light-hl-9);
     --hl-10: var(--light-hl-10);
     --hl-11: var(--light-hl-11);
+    --hl-12: var(--light-hl-12);
     --code-background: var(--light-code-background);
 }
 
@@ -88,6 +93,7 @@
     --hl-9: var(--dark-hl-9);
     --hl-10: var(--dark-hl-10);
     --hl-11: var(--dark-hl-11);
+    --hl-12: var(--dark-hl-12);
     --code-background: var(--dark-code-background);
 }
 
@@ -103,4 +109,5 @@
 .hl-9 { color: var(--hl-9); }
 .hl-10 { color: var(--hl-10); }
 .hl-11 { color: var(--hl-11); }
+.hl-12 { color: var(--hl-12); }
 pre, code { background: var(--code-background); }

package/docs/assets/navigation.js

@@ -1 +1 @@
-window.navigationData = "data:application/octet-stream;base64,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"
+window.navigationData = "data:application/octet-stream;base64,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"