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

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

@@ -1,38 +1,21 @@
-import { DateTime } from './DateTime.js';
+import { BASE_DATE_OBJECT, DateTime } from './DateTime.js';
 /**
  * CalendarDate represents a date without time or timezone information.
  */
 export default class CalendarDate {
     dateTime;
     /**
-     * Creates a CalendarDate from a DateTime, year/month/day, or defaults to today in UTC.
-     * @param source - DateTime instance, year number, or null/undefined for today
-     * @param month - Month (1-12) when source is a year number
-     * @param day - Day of month when source is a year number
-     * @example
-     * ```ts
-     * new CalendarDate()                          // today
-     * new CalendarDate(DateTime.now())            // from DateTime
-     * new CalendarDate(2026, 2, 7)               // February 7, 2026
-     * ```
+     * @internal
      */
-    constructor(source, month = 1, day = 1) {
-        if (source instanceof DateTime && source.isValid) {
-            const isoDate = source.toISODate();
-            this.dateTime = DateTime.fromISO(isoDate, { zone: 'UTC' });
+    constructor(source) {
+        if (source instanceof DateTime) {
+            this.dateTime = DateTime.fromISO(source.toISODate(), { zone: 'UTC' });
         }
-        else if (typeof source === 'number') {
-            try {
-                this.dateTime = DateTime.utc(source, month, day);
-            }
-            catch (error) {
-                if (error instanceof Error)
-                    throw new InvalidCalendarDate(error);
-                throw error;
-            }
+        else if (source && typeof source === 'object') {
+            this.dateTime = wrapLuxonError(() => DateTime.utc(source.year ?? BASE_DATE_OBJECT.year, source.month ?? BASE_DATE_OBJECT.month, source.day ?? BASE_DATE_OBJECT.day));
         }
         else {
-            this.dateTime = CalendarDate.today().toDateTime();
+            this.dateTime = DateTime.now();
         }
     }
     /**
@@ -58,8 +41,8 @@ export default class CalendarDate {
      * CalendarDate.fromJSDate(new Date(), { zone: 'America/New_York' })
      * ```
      */
-    static fromJSDate(javascriptDate, { zone } = {}) {
-        return new CalendarDate(DateTime.fromJSDate(javascriptDate, zone ? { zone } : {}));
+    static fromJSDate(javascriptDate, opts = {}) {
+        return new CalendarDate(DateTime.fromJSDate(javascriptDate, opts));
     }
     /**
      * Create a CalendarDate from an ISO 8601 date string.
@@ -70,19 +53,10 @@ export default class CalendarDate {
      * @example
      * ```ts
      * CalendarDate.fromISO('2026-02-07')
-     * CalendarDate.fromISO('2026-02-07T09:00:00Z')  // time portion ignored
      * ```
      */
-    static fromISO(str, { zone } = {}) {
-        let dateTime;
-        try {
-            dateTime = DateTime.fromISO(str, zone ? { zone } : { setZone: true });
-        }
-        catch (error) {
-            if (error instanceof Error)
-                throw new InvalidCalendarDate(error);
-            throw error;
-        }
+    static fromISO(str, opts = {}) {
+        const dateTime = wrapLuxonError(() => DateTime.fromISO(str, opts));
         return new CalendarDate(dateTime);
     }
     /**
@@ -96,15 +70,7 @@ export default class CalendarDate {
      * ```
      */
     static fromSQL(str) {
-        let dateTime;
-        try {
-            dateTime = DateTime.fromSQL(str, { zone: 'UTC' });
-        }
-        catch (error) {
-            if (error instanceof Error)
-                throw new InvalidCalendarDate(error);
-            throw error;
-        }
+        const dateTime = wrapLuxonError(() => DateTime.fromSQL(str, { zone: 'UTC' }));
         return new CalendarDate(dateTime);
     }
     /**
@@ -122,21 +88,8 @@ export default class CalendarDate {
      * 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;
-        }
+    static fromFormat(text, format, opts) {
+        const dateTime = wrapLuxonError(() => DateTime.fromFormat(text, format, opts));
         return new CalendarDate(dateTime);
     }
     /**
@@ -151,15 +104,7 @@ export default class CalendarDate {
      * ```
      */
     static fromObject(obj, opts) {
-        let dateTime;
-        try {
-            dateTime = DateTime.fromObject(obj, opts);
-        }
-        catch (error) {
-            if (error instanceof Error)
-                throw new InvalidCalendarDate(error);
-            throw error;
-        }
+        const dateTime = wrapLuxonError(() => DateTime.fromObject(obj, opts));
         return new CalendarDate(dateTime);
     }
     /**
@@ -172,8 +117,8 @@ export default class CalendarDate {
      * CalendarDate.today({ zone: 'America/New_York' })
      * ```
      */
-    static today({ zone = 'UTC' } = {}) {
-        return new CalendarDate(DateTime.now().setZone(zone));
+    static today(opts) {
+        return new CalendarDate(DateTime.now(opts));
     }
     /**
      * Returns a CalendarDate for tomorrow's date.
@@ -212,6 +157,19 @@ export default class CalendarDate {
     toISO() {
         return this.dateTime.toISODate();
     }
+    /**
+     * Returns the date as an ISO date string.
+     * Alias for `toISO()`.
+     *
+     * @returns ISO date string (e.g., '2026-02-07')
+     * @example
+     * ```ts
+     * CalendarDate.fromObject({ year: 2026, month: 2, day: 7 }).toISODate()  // '2026-02-07'
+     * ```
+     */
+    toISODate() {
+        return this.toISO();
+    }
     /**
      * Returns the date as an SQL date string.
      * @returns SQL date string (e.g., '2026-02-07')
@@ -220,8 +178,12 @@ export default class CalendarDate {
      * CalendarDate.fromObject({ year: 2026, month: 2, day: 7 }).toSQL()  // '2026-02-07'
      * ```
      */
+    _toSQL;
     toSQL() {
-        return this.dateTime.toSQLDate();
+        if (this._toSQL)
+            return this._toSQL;
+        this._toSQL = this.dateTime.toSQLDate();
+        return this._toSQL;
     }
     /**
      * Returns the date as an ISO string for JSON serialization.
@@ -235,26 +197,19 @@ export default class CalendarDate {
         return this.toISO();
     }
     /**
-     * Returns the epoch milliseconds for the date at midnight UTC.
-     * @returns Unix timestamp in milliseconds
+     * Returns the date as an ISO date string (for valueOf() operations).
+     * @returns ISO date string (e.g., '2026-02-07')
      * @example
      * ```ts
      * CalendarDate.fromISO('2026-02-07').valueOf()
      * ```
      */
+    _valueOf;
     valueOf() {
-        return this.dateTime.valueOf();
-    }
-    /**
-     * Returns the date as an ISO date string (same as toISO).
-     * @returns ISO date string (e.g., '2026-02-07')
-     * @example
-     * ```ts
-     * CalendarDate.fromObject({ year: 2026, month: 2, day: 7 }).toISODate()  // '2026-02-07'
-     * ```
-     */
-    toISODate() {
-        return this.toISO();
+        if (this._valueOf)
+            return this._valueOf;
+        this._valueOf = this.toISO();
+        return this._valueOf;
     }
     /**
      * Returns a localized string representation of the date.
@@ -401,17 +356,17 @@ export default class CalendarDate {
         return new CalendarDate(this.dateTime.minus(duration));
     }
     /**
-     * Returns the latest CalendarDate from the given arguments.
-     * @param calendarDates - CalendarDates to compare
-     * @returns The latest CalendarDate
+     * Returns a new CalendarDate with the given date units set.
+     * @param values - Object with date units to set (year, month, day)
+     * @returns A new CalendarDate
+     * @throws {InvalidCalendarDate} When the underlying DateTime operation fails
      * @example
      * ```ts
-     * CalendarDate.max(date1, date2, date3)
+     * CalendarDate.fromISO('2026-02-07').set({ year: 2025, day: 15 })  // 2025-02-15
      * ```
      */
-    static max(...calendarDates) {
-        const dateTimes = calendarDates.map(calendarDate => calendarDate.toDateTime());
-        return new CalendarDate(DateTime.max(...dateTimes));
+    set(values) {
+        return new CalendarDate(wrapLuxonError(() => this.dateTime.set(values)));
     }
     /**
      * Returns the earliest CalendarDate from the given arguments.
@@ -423,8 +378,23 @@ export default class CalendarDate {
      * ```
      */
     static min(...calendarDates) {
-        const dateTimes = calendarDates.map(calendarDate => calendarDate.toDateTime());
-        return new CalendarDate(DateTime.min(...dateTimes));
+        if (calendarDates.length === 0)
+            return null;
+        return calendarDates.reduce((min, calendarDate) => (calendarDate.valueOf() < min.valueOf() ? calendarDate : min), calendarDates[0]);
+    }
+    /**
+     * Returns the latest CalendarDate from the given arguments.
+     * @param calendarDates - CalendarDates to compare
+     * @returns The latest CalendarDate
+     * @example
+     * ```ts
+     * CalendarDate.max(date1, date2, date3)
+     * ```
+     */
+    static max(...calendarDates) {
+        if (calendarDates.length === 0)
+            return null;
+        return calendarDates.reduce((max, calendarDate) => (calendarDate.valueOf() > max.valueOf() ? calendarDate : max), calendarDates[0]);
     }
     /**
      * Returns true if this and other are in the same unit of time.
@@ -455,37 +425,48 @@ export default class CalendarDate {
      * const d1 = CalendarDate.fromISO('2026-02-07')
      * const d2 = CalendarDate.fromISO('2026-02-15')
      * d2.diff(d1, 'days')    // 8
-     * d2.diff(d1, 'months')  // 0
      * ```
      */
-    diff(otherCalendarDate, duration) {
-        const otherDateTime = otherCalendarDate.toDateTime();
-        // For quarters and months, use Luxon's diff directly since DateTime.diff doesn't support them
-        if (duration === 'quarters' || duration === 'months') {
-            const luxonDiff = this.dateTime.toLuxon().diff(otherDateTime.toLuxon(), duration);
-            return luxonDiff[duration] ?? 0;
+    /**
+     * Returns the difference between this CalendarDate and another in the specified unit(s).
+     *
+     * @param other - CalendarDate to compare against
+     * @param unit - Unit or units to return (years, quarters, months, weeks, days)
+     * @returns Object with only the specified units (or all units if not specified)
+     * @example
+     * ```ts
+     * const d1 = CalendarDate.fromISO('2026-02-15')
+     * const d2 = CalendarDate.fromISO('2026-02-07')
+     * d1.diff(d2, 'days')  // { days: 8 }
+     * d1.diff(d2, ['months', 'days'])  // { months: 0, days: 8 }
+     * d1.diff(d2)  // { years: 0, months: 0, days: 8 }
+     * ```
+     */
+    diff(other, unit) {
+        const otherDateTime = other.toDateTime();
+        const unitArray = unit === undefined ? undefined : Array.isArray(unit) ? unit : [unit];
+        const result = this.dateTime.diff(otherDateTime, unitArray);
+        const filtered = {};
+        const requestedUnits = unit === undefined ? ['years', 'months', 'days'] : Array.isArray(unit) ? unit : [unit];
+        for (const requestedUnit of requestedUnits) {
+            filtered[requestedUnit] = result[requestedUnit] ?? 0;
         }
-        const result = this.dateTime.diff(otherDateTime, duration);
-        return result[duration] ?? 0;
+        return filtered;
     }
     /**
-     * Returns the difference between this CalendarDate and today in the specified unit.
-     * @param duration - Unit for the difference ('years', 'quarters', 'months', 'weeks', or 'days')
-     * @returns Numeric difference in the specified unit (rounded up)
+     * Returns the difference between this CalendarDate and today in the specified unit(s).
+     *
+     * @param unit - Unit or units to return (years, quarters, months, weeks, days)
+     * @returns Object with only the specified units (or all units if not specified)
      * @example
      * ```ts
      * const future = CalendarDate.today().plus({ days: 5 })
-     * future.diffNow('days')  // approximately 5
+     * future.diffNow('days')  // { days: 5 }
+     * future.diffNow(['months', 'days'])  // { months: 0, days: 5 }
      * ```
      */
-    diffNow(duration) {
-        // For quarters and months, use Luxon's diff directly since DateTime.diffNow doesn't support them
-        if (duration === 'quarters' || duration === 'months') {
-            const luxonDiff = this.dateTime.toLuxon().diffNow(duration);
-            return Math.ceil(luxonDiff[duration] ?? 0);
-        }
-        const result = this.dateTime.diffNow(duration);
-        return Math.ceil(result[duration] ?? 0);
+    diffNow(unit) {
+        return this.diff(CalendarDate.today(), unit);
     }
     /**
      * Returns true if this CalendarDate equals another CalendarDate.
@@ -499,7 +480,7 @@ export default class CalendarDate {
      * ```
      */
     equals(otherCalendarDate) {
-        return this.dateTime.equals(otherCalendarDate.toDateTime());
+        return this.valueOf() === otherCalendarDate.valueOf();
     }
 }
 /**
@@ -519,3 +500,13 @@ export class InvalidCalendarDate extends Error {
         super((error.message ?? '').replace('DateTime', 'CalendarDate'));
     }
 }
+function wrapLuxonError(fn) {
+    try {
+        return fn();
+    }
+    catch (error) {
+        if (error instanceof Error)
+            throw new InvalidCalendarDate(error);
+        throw error;
+    }
+}

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

@@ -0,0 +1,173 @@
+import BaseClockTime from './BaseClockTime.js';
+import { BASE_DATE_OBJECT, DateTime } from './DateTime.js';
+/**
+ * ClockTime represents a time of day without timezone information.
+ *
+ * Useful for representing TIME WITHOUT TIME ZONE fields from a Postgres database.
+ * All output methods strip timezone offset information.
+ */
+export default class ClockTime extends BaseClockTime {
+    /**
+     * Create a ClockTime from a JavaScript Date.
+     * @param javascriptDate - A JavaScript Date instance
+     * @returns A ClockTime for the time portion
+     * @example
+     * ```ts
+     * ClockTime.fromJSDate(new Date())
+     * ```
+     */
+    static fromJSDate(javascriptDate) {
+        const dateTime = this.wrapLuxonError(() => DateTime.fromJSDate(javascriptDate));
+        return new ClockTime(dateTime);
+    }
+    /**
+     * Create a ClockTime from an ISO 8601 time string.
+     * Preserves the time values as-is, regardless of any timezone info in the string.
+     * @param str - ISO time string (e.g., '14:30:45.123456')
+     * @returns A ClockTime for the given time
+     * @throws {InvalidClockTime} When the ISO string is invalid
+     * @example
+     * ```ts
+     * ClockTime.fromISO('14:30:45.123456')      // stores 14:30:45.123456
+     * ClockTime.fromISO('14:30:45.123456-05:00') // stores 14:30:45.123456 (timezone ignored)
+     * ```
+     */
+    static fromISO(str) {
+        const dateTime = this.wrapLuxonError(() => DateTime.fromISO(str));
+        return new ClockTime(dateTime);
+    }
+    /**
+     * Create a ClockTime from an SQL time string.
+     * Preserves the time values as-is, regardless of any timezone info in the string.
+     * @param str - SQL time string (e.g., '14:30:45.123456')
+     * @returns A ClockTime for the given time
+     * @throws {InvalidClockTime} When the SQL string is invalid
+     * @example
+     * ```ts
+     * ClockTime.fromSQL('14:30:45.123456')       // stores 14:30:45.123456
+     * ClockTime.fromSQL('14:30:45.123456+05:30') // stores 14:30:45.123456 (timezone ignored)
+     * ```
+     */
+    static fromSQL(str) {
+        const dateTime = this.wrapLuxonError(() => DateTime.fromSQL(str));
+        return new ClockTime(dateTime);
+    }
+    /**
+     * Create a ClockTime from a custom format string.
+     * Uses Luxon format tokens (e.g., 'HH:mm:ss', 'hh:mm a').
+     * @param text - The string to parse
+     * @param format - Format string using Luxon tokens
+     * @param opts - Optional configuration
+     * @param opts.locale - Locale for parsing (e.g., 'en-US', 'fr-FR')
+     * @param opts.numberingSystem - Numbering system (e.g., 'arab', 'beng')
+     * @param opts.outputCalendar - Output calendar system (e.g., 'islamic', 'hebrew')
+     * @returns A ClockTime for the parsed time
+     * @throws {InvalidClockTime} When the string doesn't match the format or is invalid
+     * @example
+     * ```ts
+     * ClockTime.fromFormat('14:30:45', 'HH:mm:ss')
+     * ClockTime.fromFormat('2:30 PM', 'h:mm a')
+     * ```
+     */
+    static fromFormat(text, format, opts) {
+        const dateTime = this.wrapLuxonError(() => DateTime.fromFormat(text, format, opts));
+        return new ClockTime(dateTime);
+    }
+    /**
+     * Create a ClockTime from an object with time units.
+     * @param obj - Object with hour, minute, second, millisecond, microsecond properties
+     * @param opts - Optional configuration
+     * @param opts.locale - Locale (e.g., 'en-US', 'fr-FR')
+     * @param opts.numberingSystem - Numbering system (e.g., 'arab', 'beng')
+     * @param opts.outputCalendar - Output calendar system (e.g., 'islamic', 'hebrew')
+     * @returns A ClockTime for the given components
+     * @throws {InvalidClockTime} When time values are invalid
+     * @example
+     * ```ts
+     * ClockTime.fromObject({ hour: 14, minute: 30, second: 45 })
+     * ClockTime.fromObject({ hour: 14, minute: 30 })
+     * ```
+     */
+    static fromObject(obj, opts) {
+        const dateTime = this.wrapLuxonError(() => DateTime.fromObject({
+            ...BASE_DATE_OBJECT,
+            ...obj,
+        }, opts));
+        return new ClockTime(dateTime);
+    }
+    /**
+     * Returns a ClockTime for the current time.
+     * @returns A ClockTime for now
+     * @example
+     * ```ts
+     * ClockTime.now()
+     * ```
+     */
+    static now() {
+        return new ClockTime(DateTime.now());
+    }
+    /**
+     * Returns the time as an ISO 8601 time string without timezone offset.
+     * Alias for `toISOTime()`.
+     *
+     * @param opts - Optional format options
+     * @param opts.suppressMilliseconds - If true, omits milliseconds/microseconds when they are zero
+     * @param opts.suppressSeconds - If true, omits seconds when they are zero
+     * @param opts.format - Format variant: 'basic' (compact) or 'extended' (default, with colons)
+     * @returns ISO time string without timezone offset (e.g., '14:30:45.123456')
+     * @example
+     * ```ts
+     * ClockTime.fromObject({ hour: 14, minute: 30, second: 45 }).toISO()  // '14:30:45.000000'
+     * ClockTime.fromISO('14:30:45-05:00').toISO()  // '14:30:45.000000' (timezone stripped)
+     * ```
+     */
+    toISO(opts) {
+        return this.dateTime.toISOTime({ ...opts, includeOffset: false });
+    }
+    /**
+     * Returns the SQL time string without timezone offset.
+     * Result is memoized for performance.
+     *
+     * @returns SQL time string without timezone offset (e.g., '14:30:45.123456')
+     * @example
+     * ```ts
+     * ClockTime.fromISO('14:30:45').toSQL()  // '14:30:45.000000'
+     * ```
+     */
+    toSQL() {
+        if (this._toSQL)
+            return this._toSQL;
+        this._toSQL = this.dateTime.toSQLTime({ includeOffset: false });
+        return this._toSQL;
+    }
+    static wrapLuxonError(fn) {
+        try {
+            return fn();
+        }
+        catch (error) {
+            if (error instanceof Error)
+                throw new InvalidClockTime(error);
+            throw error;
+        }
+    }
+    wrapLuxonError(fn) {
+        return this.constructor.wrapLuxonError(fn);
+    }
+}
+/**
+ * Thrown when a ClockTime is invalid (e.g., invalid input or time values).
+ * @param error - The original error (available as cause)
+ * @example
+ * ```ts
+ * try {
+ *   ClockTime.fromISO('25:00:00')
+ * } catch (e) {
+ *   if (e instanceof InvalidClockTime) console.error(e.message)
+ * }
+ * ```
+ */
+export class InvalidClockTime extends Error {
+    constructor(error) {
+        super((error.message ?? '').replace('DateTime', 'ClockTime'));
+    }
+}