@rvoh/dream 2.3.0-alpha.4 → 2.3.0-alpha.6

package/dist/cjs/src/utils/datetime/CalendarDate.js

@@ -107,6 +107,38 @@ export default class CalendarDate {
         }
         return new CalendarDate(dateTime);
     }
+    /**
+     * Create a CalendarDate from a custom format string.
+     * Uses Luxon format tokens (e.g., 'MM/dd/yyyy', 'MMMM dd, yyyy').
+     * @param text - The string to parse
+     * @param format - Format string using Luxon tokens
+     * @param options - Optional zone and locale options
+     * @returns A CalendarDate for the parsed date
+     * @throws {InvalidCalendarDate} When the string doesn't match the format or is invalid
+     * @example
+     * ```ts
+     * CalendarDate.fromFormat('12/15/2017', 'MM/dd/yyyy')
+     * CalendarDate.fromFormat('May 25, 1982', 'MMMM dd, yyyy')
+     * CalendarDate.fromFormat('mai 25, 1982', 'MMMM dd, yyyy', { locale: 'fr' })
+     * ```
+     */
+    static fromFormat(text, format, { zone, locale } = {}) {
+        let dateTime;
+        try {
+            const opts = {};
+            if (zone)
+                opts.zone = zone;
+            if (locale)
+                opts.locale = locale;
+            dateTime = DateTime.fromFormat(text, format, opts);
+        }
+        catch (error) {
+            if (error instanceof Error)
+                throw new InvalidCalendarDate(error);
+            throw error;
+        }
+        return new CalendarDate(dateTime);
+    }
     /**
      * Create a CalendarDate from an object with date units.
      * @param obj - Object with year, month, day properties

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

@@ -381,17 +381,20 @@ export class DateTime {
     }
     /**
      * Create a DateTime from epoch milliseconds.
-     * @param milliseconds - Unix timestamp in milliseconds
+     * @param millisecondInput - Unix timestamp in milliseconds (fractional part becomes microseconds)
      * @param options - Optional zone/locale options
      * @returns A DateTime for the given instant
      * @example
      * ```ts
      * DateTime.fromMillis(1707234567890)
+     * DateTime.fromMillis(1707234567890.123) // .123 ms = 123 microseconds
      * ```
      */
-    static fromMillis(milliseconds, options) {
-        const luxonDatetime = LuxonDateTime.fromMillis(milliseconds, options);
-        return new DateTime(luxonDatetime, 0);
+    static fromMillis(millisecondInput, options) {
+        const { milliseconds, microseconds } = microsecondParts(millisecondInput * 1000, {
+            errorIfNegative: false,
+        });
+        return new DateTime(LuxonDateTime.fromMillis(milliseconds, options), microseconds);
     }
     /**
      * Create a DateTime from epoch microseconds.
@@ -410,17 +413,22 @@ export class DateTime {
     }
     /**
      * Create a DateTime from epoch seconds.
-     * @param seconds - Unix timestamp in seconds
+     * Fractional seconds are converted to milliseconds and microseconds.
+     * @param seconds - Unix timestamp in seconds (fractional part becomes ms + µs)
      * @param options - Optional zone/locale options
      * @returns A DateTime for the given instant
      * @example
      * ```ts
      * DateTime.fromSeconds(1707234567)
+     * DateTime.fromSeconds(1707234567.123456) // .123456 seconds = 123ms + 456µs
      * ```
      */
     static fromSeconds(seconds, options) {
-        const luxonDatetime = LuxonDateTime.fromSeconds(seconds, options);
-        return new DateTime(luxonDatetime, 0);
+        // 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, options);
+        return new DateTime(luxonDatetime, microseconds);
     }
     /**
      * Create a DateTime from an object with date/time units.
@@ -481,6 +489,46 @@ export class DateTime {
         const luxonDatetime = wrapLuxonError(() => LuxonDateTime.fromSQL(textForLuxon, opts));
         return new DateTime(luxonDatetime, microsecond);
     }
+    /**
+     * Create a DateTime from a custom format string.
+     * Supports standard Luxon format tokens plus 'u' or 'SSSSSS' for microseconds (6 decimal places).
+     * @param text - The string to parse
+     * @param format - Format string using Luxon tokens (e.g., 'MM/dd/yyyy HH:mm:ss.u')
+     * @param opts - Optional parsing options (zone, locale, etc.)
+     * @returns A DateTime for the parsed instant
+     * @throws {InvalidDateTime} When the string doesn't match the format or is invalid
+     * @example
+     * ```ts
+     * DateTime.fromFormat('12/15/2017', 'MM/dd/yyyy')
+     * DateTime.fromFormat('12/15/2017 10:30:45', 'MM/dd/yyyy HH:mm:ss')
+     * DateTime.fromFormat('12/15/2017 10:30:45.123456', 'MM/dd/yyyy HH:mm:ss.u')
+     * DateTime.fromFormat('12/15/2017 10:30:45.123456', 'MM/dd/yyyy HH:mm:ss.SSSSSS')
+     * DateTime.fromFormat('mai 25, 1982', 'MMMM dd, yyyy', { locale: 'fr' })
+     * ```
+     */
+    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);
+        }
+    }
     /**
      * Returns an ISO 8601 string with 6 fractional second digits (milliseconds + microseconds).
      * @param opts - Optional format options (includeOffset, suppressMilliseconds, etc.)
@@ -813,20 +861,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
@@ -985,58 +1051,43 @@ export class DateTime {
      * ```
      */
     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
+        const unitArray = unit === undefined ? undefined : typeof unit === 'string' ? [unit] : unit;
+        const needsMicroseconds = !unitArray || unitArray.includes('microseconds');
+        const needsMilliseconds = !unitArray || unitArray.includes('milliseconds');
+        // Strip 'microseconds' before passing to Luxon (it doesn't support it)
+        const luxonUnits = unitArray?.filter(u => u !== 'microseconds');
+        const luxonDuration = this.luxonDatetime.diff(other.toLuxon(), luxonUnits && luxonUnits.length > 0 ? luxonUnits : undefined);
+        const result = luxonDuration.toObject();
+        if (needsMicroseconds) {
             if (unit === 'microseconds') {
-                const thisTotalMicroseconds = this.toMicroseconds();
-                const otherTotalMicroseconds = other.toMicroseconds();
-                fullObject.microseconds = thisTotalMicroseconds - otherTotalMicroseconds;
+                // Only microseconds requested: return total difference
+                result.microseconds = this.toMicroseconds() - other.toMicroseconds();
             }
-            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;
+            else if (needsMilliseconds && result.milliseconds !== undefined) {
+                // Both ms + µs requested: combine Luxon's ms with µs field diff, then re-split.
+                // Example: Luxon says -1ms, µs fields are 999-0=+999 → total=-1µs → 0ms, -1µs
+                const totalMicroDiff = Math.round(result.milliseconds * 1000) + (this.microsecond - other.microsecond);
+                result.milliseconds = Math.trunc(totalMicroDiff / 1000) || 0; // || 0 normalizes -0
+                result.microseconds = totalMicroDiff - result.milliseconds * 1000;
             }
-            // 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);
+            else {
+                // µs without ms: just the field difference
+                result.microseconds = this.microsecond - other.microsecond;
             }
         }
-        // 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;
+        else if (needsMilliseconds && result.milliseconds !== undefined) {
+            // ms without µs: truncate fractional part
+            result.milliseconds = Math.trunc(result.milliseconds);
         }
-        return result;
+        // Return only the requested units
+        if (unit === undefined)
+            return result;
+        if (typeof unit === 'string')
+            return { [unit]: result[unit] ?? 0 };
+        const filtered = {};
+        for (const u of unit)
+            filtered[u] = result[u] ?? 0;
+        return filtered;
     }
     /**
      * Returns the difference between this DateTime and now.

package/dist/cjs/src/utils/datetime/helpers/isoTimeDecimalString.js

@@ -1,8 +1,12 @@
-export default function isoTimeDecimalString(datetime, { nullIfZero }) {
+export default function isoTimeDecimalString(datetime, { nullIfZero, truncateMicroseconds }) {
     const milliseconds = datetime.millisecond;
-    const microseconds = datetime.microsecond;
-    const totalMicroseconds = milliseconds * 1000 + microseconds;
-    if (totalMicroseconds === 0 && nullIfZero)
+    if (truncateMicroseconds) {
+        if (nullIfZero && milliseconds === 0)
+            return null;
+        return milliseconds.toString().padStart(3, '0');
+    }
+    const totalMicroseconds = milliseconds * 1000 + datetime.microsecond;
+    if (nullIfZero && totalMicroseconds === 0)
         return null;
     return totalMicroseconds.toString().padStart(6, '0');
 }

package/dist/cjs/src/utils/datetime/helpers/replaceISOMicroseconds.js

@@ -1,6 +1,9 @@
 import isoTimeDecimalString from './isoTimeDecimalString.js';
 export default function replaceISOMicroseconds(timeObj, isoString, opts) {
-    const decimalString = isoTimeDecimalString(timeObj, { nullIfZero: opts?.suppressMilliseconds });
+    const decimalString = isoTimeDecimalString(timeObj, {
+        nullIfZero: opts?.suppressMilliseconds,
+        truncateMicroseconds: opts?.truncateMicroseconds,
+    });
     if (decimalString === null)
         return isoString;
     // Match time in both ISO format (with T) and SQL format (with space)

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

@@ -107,6 +107,38 @@ export default class CalendarDate {
         }
         return new CalendarDate(dateTime);
     }
+    /**
+     * Create a CalendarDate from a custom format string.
+     * Uses Luxon format tokens (e.g., 'MM/dd/yyyy', 'MMMM dd, yyyy').
+     * @param text - The string to parse
+     * @param format - Format string using Luxon tokens
+     * @param options - Optional zone and locale options
+     * @returns A CalendarDate for the parsed date
+     * @throws {InvalidCalendarDate} When the string doesn't match the format or is invalid
+     * @example
+     * ```ts
+     * CalendarDate.fromFormat('12/15/2017', 'MM/dd/yyyy')
+     * CalendarDate.fromFormat('May 25, 1982', 'MMMM dd, yyyy')
+     * CalendarDate.fromFormat('mai 25, 1982', 'MMMM dd, yyyy', { locale: 'fr' })
+     * ```
+     */
+    static fromFormat(text, format, { zone, locale } = {}) {
+        let dateTime;
+        try {
+            const opts = {};
+            if (zone)
+                opts.zone = zone;
+            if (locale)
+                opts.locale = locale;
+            dateTime = DateTime.fromFormat(text, format, opts);
+        }
+        catch (error) {
+            if (error instanceof Error)
+                throw new InvalidCalendarDate(error);
+            throw error;
+        }
+        return new CalendarDate(dateTime);
+    }
     /**
      * Create a CalendarDate from an object with date units.
      * @param obj - Object with year, month, day properties

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

@@ -381,17 +381,20 @@ export class DateTime {
     }
     /**
      * Create a DateTime from epoch milliseconds.
-     * @param milliseconds - Unix timestamp in milliseconds
+     * @param millisecondInput - Unix timestamp in milliseconds (fractional part becomes microseconds)
      * @param options - Optional zone/locale options
      * @returns A DateTime for the given instant
      * @example
      * ```ts
      * DateTime.fromMillis(1707234567890)
+     * DateTime.fromMillis(1707234567890.123) // .123 ms = 123 microseconds
      * ```
      */
-    static fromMillis(milliseconds, options) {
-        const luxonDatetime = LuxonDateTime.fromMillis(milliseconds, options);
-        return new DateTime(luxonDatetime, 0);
+    static fromMillis(millisecondInput, options) {
+        const { milliseconds, microseconds } = microsecondParts(millisecondInput * 1000, {
+            errorIfNegative: false,
+        });
+        return new DateTime(LuxonDateTime.fromMillis(milliseconds, options), microseconds);
     }
     /**
      * Create a DateTime from epoch microseconds.
@@ -410,17 +413,22 @@ export class DateTime {
     }
     /**
      * Create a DateTime from epoch seconds.
-     * @param seconds - Unix timestamp in seconds
+     * Fractional seconds are converted to milliseconds and microseconds.
+     * @param seconds - Unix timestamp in seconds (fractional part becomes ms + µs)
      * @param options - Optional zone/locale options
      * @returns A DateTime for the given instant
      * @example
      * ```ts
      * DateTime.fromSeconds(1707234567)
+     * DateTime.fromSeconds(1707234567.123456) // .123456 seconds = 123ms + 456µs
      * ```
      */
     static fromSeconds(seconds, options) {
-        const luxonDatetime = LuxonDateTime.fromSeconds(seconds, options);
-        return new DateTime(luxonDatetime, 0);
+        // 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, options);
+        return new DateTime(luxonDatetime, microseconds);
     }
     /**
      * Create a DateTime from an object with date/time units.
@@ -481,6 +489,46 @@ export class DateTime {
         const luxonDatetime = wrapLuxonError(() => LuxonDateTime.fromSQL(textForLuxon, opts));
         return new DateTime(luxonDatetime, microsecond);
     }
+    /**
+     * Create a DateTime from a custom format string.
+     * Supports standard Luxon format tokens plus 'u' or 'SSSSSS' for microseconds (6 decimal places).
+     * @param text - The string to parse
+     * @param format - Format string using Luxon tokens (e.g., 'MM/dd/yyyy HH:mm:ss.u')
+     * @param opts - Optional parsing options (zone, locale, etc.)
+     * @returns A DateTime for the parsed instant
+     * @throws {InvalidDateTime} When the string doesn't match the format or is invalid
+     * @example
+     * ```ts
+     * DateTime.fromFormat('12/15/2017', 'MM/dd/yyyy')
+     * DateTime.fromFormat('12/15/2017 10:30:45', 'MM/dd/yyyy HH:mm:ss')
+     * DateTime.fromFormat('12/15/2017 10:30:45.123456', 'MM/dd/yyyy HH:mm:ss.u')
+     * DateTime.fromFormat('12/15/2017 10:30:45.123456', 'MM/dd/yyyy HH:mm:ss.SSSSSS')
+     * DateTime.fromFormat('mai 25, 1982', 'MMMM dd, yyyy', { locale: 'fr' })
+     * ```
+     */
+    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);
+        }
+    }
     /**
      * Returns an ISO 8601 string with 6 fractional second digits (milliseconds + microseconds).
      * @param opts - Optional format options (includeOffset, suppressMilliseconds, etc.)
@@ -813,20 +861,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
@@ -985,58 +1051,43 @@ export class DateTime {
      * ```
      */
     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
+        const unitArray = unit === undefined ? undefined : typeof unit === 'string' ? [unit] : unit;
+        const needsMicroseconds = !unitArray || unitArray.includes('microseconds');
+        const needsMilliseconds = !unitArray || unitArray.includes('milliseconds');
+        // Strip 'microseconds' before passing to Luxon (it doesn't support it)
+        const luxonUnits = unitArray?.filter(u => u !== 'microseconds');
+        const luxonDuration = this.luxonDatetime.diff(other.toLuxon(), luxonUnits && luxonUnits.length > 0 ? luxonUnits : undefined);
+        const result = luxonDuration.toObject();
+        if (needsMicroseconds) {
             if (unit === 'microseconds') {
-                const thisTotalMicroseconds = this.toMicroseconds();
-                const otherTotalMicroseconds = other.toMicroseconds();
-                fullObject.microseconds = thisTotalMicroseconds - otherTotalMicroseconds;
+                // Only microseconds requested: return total difference
+                result.microseconds = this.toMicroseconds() - other.toMicroseconds();
             }
-            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;
+            else if (needsMilliseconds && result.milliseconds !== undefined) {
+                // Both ms + µs requested: combine Luxon's ms with µs field diff, then re-split.
+                // Example: Luxon says -1ms, µs fields are 999-0=+999 → total=-1µs → 0ms, -1µs
+                const totalMicroDiff = Math.round(result.milliseconds * 1000) + (this.microsecond - other.microsecond);
+                result.milliseconds = Math.trunc(totalMicroDiff / 1000) || 0; // || 0 normalizes -0
+                result.microseconds = totalMicroDiff - result.milliseconds * 1000;
             }
-            // 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);
+            else {
+                // µs without ms: just the field difference
+                result.microseconds = this.microsecond - other.microsecond;
             }
         }
-        // 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;
+        else if (needsMilliseconds && result.milliseconds !== undefined) {
+            // ms without µs: truncate fractional part
+            result.milliseconds = Math.trunc(result.milliseconds);
         }
-        return result;
+        // Return only the requested units
+        if (unit === undefined)
+            return result;
+        if (typeof unit === 'string')
+            return { [unit]: result[unit] ?? 0 };
+        const filtered = {};
+        for (const u of unit)
+            filtered[u] = result[u] ?? 0;
+        return filtered;
     }
     /**
      * Returns the difference between this DateTime and now.

package/dist/esm/src/utils/datetime/helpers/isoTimeDecimalString.js

@@ -1,8 +1,12 @@
-export default function isoTimeDecimalString(datetime, { nullIfZero }) {
+export default function isoTimeDecimalString(datetime, { nullIfZero, truncateMicroseconds }) {
     const milliseconds = datetime.millisecond;
-    const microseconds = datetime.microsecond;
-    const totalMicroseconds = milliseconds * 1000 + microseconds;
-    if (totalMicroseconds === 0 && nullIfZero)
+    if (truncateMicroseconds) {
+        if (nullIfZero && milliseconds === 0)
+            return null;
+        return milliseconds.toString().padStart(3, '0');
+    }
+    const totalMicroseconds = milliseconds * 1000 + datetime.microsecond;
+    if (nullIfZero && totalMicroseconds === 0)
         return null;
     return totalMicroseconds.toString().padStart(6, '0');
 }

package/dist/esm/src/utils/datetime/helpers/replaceISOMicroseconds.js

@@ -1,6 +1,9 @@
 import isoTimeDecimalString from './isoTimeDecimalString.js';
 export default function replaceISOMicroseconds(timeObj, isoString, opts) {
-    const decimalString = isoTimeDecimalString(timeObj, { nullIfZero: opts?.suppressMilliseconds });
+    const decimalString = isoTimeDecimalString(timeObj, {
+        nullIfZero: opts?.suppressMilliseconds,
+        truncateMicroseconds: opts?.truncateMicroseconds,
+    });
     if (decimalString === null)
         return isoString;
     // Match time in both ISO format (with T) and SQL format (with space)

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

@@ -34,11 +34,13 @@ export interface ToISOTimeOptions {
     includeOffset?: boolean;
     includePrefix?: boolean;
     format?: 'basic' | 'extended';
+    truncateMicroseconds?: boolean;
 }
 export interface ToSQLOptions {
     includeZone?: boolean;
     includeOffset?: boolean;
     includeOffsetSpace?: boolean;
+    truncateMicroseconds?: boolean;
 }
 export type DateTimeUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond';
 /**

package/dist/types/src/types/datetime.ts

@@ -40,12 +40,14 @@ export interface ToISOTimeOptions {
   includeOffset?: boolean
   includePrefix?: boolean
   format?: 'basic' | 'extended'
+  truncateMicroseconds?: boolean
 }
 
 export interface ToSQLOptions {
   includeZone?: boolean
   includeOffset?: boolean
   includeOffsetSpace?: boolean
+  truncateMicroseconds?: boolean
 }
 
 export type DateTimeUnit =