rrule-rust 3.0.0-alpha.9 → 3.0.0-next.2

package/dist/browser/datetime.js

@@ -1,87 +1,140 @@
 /**
- * Represents a date and time. Either local or UTC.
+ * Represents a date and time, either local or UTC.
+ *
+ * The generic type parameter `T` determines whether this is:
+ * - `DateTime<Time>` - A date with time information
+ * - `DateTime<undefined>` - A date without time information
+ *
+ * @example
+ * ```typescript
+ * // Create a date-only DateTime
+ * const date = DateTime.date(2024, 1, 15);
+ * console.log(date.year, date.month, date.day); // 2024, 1, 15
+ *
+ * // Create a local DateTime
+ * const local = DateTime.local(2024, 1, 15, 14, 30, 0);
+ * console.log(local.time?.utc); // false
+ *
+ * // Create a UTC DateTime
+ * const utc = DateTime.utc(2024, 1, 15, 14, 30, 0);
+ * console.log(utc.time?.utc); // true
+ * ```
  */
 export class DateTime {
-    constructor(numeric) {
-        this.state = {
-            numeric,
-        };
-    }
-    get year() {
-        return (this.state.year ??= Math.floor(this.state.numeric / 100000000000));
-    }
-    get month() {
-        return (this.state.month ??= Math.floor((this.state.numeric / 1000000000) % 100));
-    }
-    get day() {
-        return (this.state.day ??= Math.floor((this.state.numeric / 10000000) % 100));
-    }
-    get time() {
-        // return cached time if available
-        if ('time' in this.state) {
-            return this.state.time;
-        }
-        const type = this.state.numeric % 10; // 0 – non utc, 1 – utc, 2 – date only
-        if (type == 2) {
-            // if it's date only, return undefined and cache it in state
-            return (this.state.time ??= undefined);
-        }
-        else {
-            // otherwise compute it from numeric representation and cache it in state
-            return (this.state.time ??= {
-                hour: Math.floor((this.state.numeric / 100000) % 100),
-                minute: Math.floor((this.state.numeric / 1000) % 100),
-                second: Math.floor((this.state.numeric / 10) % 100),
-                utc: this.state.numeric % 10 == 1,
-            });
-        }
+    constructor(year, month, day, time) {
+        this.year = year;
+        this.month = month;
+        this.day = day;
+        this.time = time;
     }
     static create(year, month, day, hour, minute, second, utc) {
-        let numeric = year * 100000000000 + month * 1000000000 + day * 10000000;
         if (hour !== undefined &&
             minute !== undefined &&
             second !== undefined &&
             utc !== undefined) {
-            numeric += hour * 100000;
-            numeric += minute * 1000;
-            numeric += second * 10;
-            numeric += utc ? 1 : 0;
-            return new DateTime(numeric);
+            const dt = new DateTime(year, month, day, {
+                hour,
+                minute,
+                second,
+                utc,
+            });
+            dt.offset = utc ? 0 : undefined;
+            return dt;
         }
         else {
-            numeric += 100000;
-            numeric += 1000;
-            numeric += 10;
-            numeric += 2;
-            return new DateTime(numeric);
+            return new DateTime(year, month, day, undefined);
         }
     }
     /**
-     * Creates a new DateTime object from the given date and time components.
+     * Creates a new date-only DateTime object (without time information).
+     *
+     * @param year - Year component (e.g., 2024)
+     * @param month - Month component (1-12)
+     * @param day - Day component (1-31)
+     * @returns A DateTime instance without time information
+     *
+     * @example
+     * ```typescript
+     * const date = DateTime.date(2024, 1, 15);
+     * console.log(date.toString()); // "20240115"
+     * ```
      */
     static date(year, month, day) {
         return this.create(year, month, day);
     }
     /**
+     * Creates a new local DateTime object (with time in local timezone).
      * This method is shorthand for `DateTime.create` with `utc` set to `false`.
+     *
+     * @param year - Year component (e.g., 2024)
+     * @param month - Month component (1-12)
+     * @param day - Day component (1-31)
+     * @param hour - Hour component (0-23)
+     * @param minute - Minute component (0-59)
+     * @param second - Second component (0-59)
+     * @returns A DateTime instance with local time
+     *
+     * @example
+     * ```typescript
+     * const value = DateTime.local(2024, 1, 15, 14, 30, 0);
+     * console.log(value.time.utc); // false
+     * console.log(value.toString()); // "20240115T143000"
+     * ```
      */
     static local(year, month, day, hour, minute, second) {
         return DateTime.create(year, month, day, hour, minute, second, false);
     }
     /**
+     * Creates a new UTC DateTime object (with time in UTC timezone).
      * This method is shorthand for `DateTime.create` with `utc` set to `true`.
+     *
+     * @param year - Year component (e.g., 2024)
+     * @param month - Month component (1-12)
+     * @param day - Day component (1-31)
+     * @param hour - Hour component (0-23)
+     * @param minute - Minute component (0-59)
+     * @param second - Second component (0-59)
+     * @returns A DateTime instance with UTC time
+     *
+     * @example
+     * ```typescript
+     * const value = DateTime.utc(2024, 1, 15, 14, 30, 0);
+     * console.log(value.time.utc); // true
+     * console.log(value.toString()); // "20240115T143000Z"
+     * ```
      */
     static utc(year, month, day, hour, minute, second) {
         return DateTime.create(year, month, day, hour, minute, second, true);
     }
     static fromPlain(plain) {
         if ('hour' in plain) {
-            return DateTime.create(plain.year, plain.month, plain.day, plain.hour, plain.minute, plain.second, plain.utc);
+            return DateTime.create(plain.year, plain.month, plain.day, plain.hour, plain.minute, plain.second, plain.utc ?? false);
         }
         return DateTime.create(plain.year, plain.month, plain.day);
     }
     /**
-     * Creates a new DateTime object from provided string representation of a date according to RFC 5545.
+     * Creates a new DateTime object from a string representation according to RFC 5545.
+     *
+     * Supported formats:
+     * - `YYYYMMDD` - Date only (e.g., "20240115")
+     * - `YYYYMMDDTHHMMSS` - Local date-time (e.g., "20240115T143000")
+     * - `YYYYMMDDTHHMMSSZ` - UTC date-time (e.g., "20240115T143000Z")
+     *
+     * @param str - The RFC 5545 formatted string
+     * @returns A DateTime instance
+     * @throws {TypeError} If the string format is invalid
+     *
+     * @example
+     * ```typescript
+     * // Parse date only
+     * const date = DateTime.fromString("20240115");
+     *
+     * // Parse local date-time
+     * const local = DateTime.fromString("20240115T143000");
+     *
+     * // Parse UTC date-time
+     * const utc = DateTime.fromString("20240115T143000Z");
+     * ```
      */
     // TODO: add template expression
     static fromString(str) {
@@ -113,8 +166,53 @@ export class DateTime {
         }
     }
     /** @internal */
-    static fromNumeric(numeric) {
-        return new DateTime(numeric);
+    static fromNumbers(year, month, day, hour, minute, second, offset) {
+        const dt = new DateTime(year, month, day, hour !== -1
+            ? {
+                hour,
+                minute,
+                second,
+                utc: offset === 0,
+            }
+            : undefined);
+        dt.offset = offset === -1 ? undefined : offset;
+        return dt;
+    }
+    /** @internal */
+    static fromInt32Array(arr) {
+        return this.fromNumbers(arr[0], arr[1], arr[2], arr[3], arr[4], arr[5], arr[6]);
+    }
+    /** @internal */
+    static fromFlatInt32Array(raw) {
+        const result = [];
+        for (let i = 0; i < raw.length; i += 7) {
+            result.push(this.fromNumbers(raw[i], raw[i + 1], raw[i + 2], raw[i + 3], raw[i + 4], raw[i + 5], raw[i + 6]));
+        }
+        return result;
+    }
+    /** @internal */
+    static toFlatInt32Array(datetimes) {
+        const arr = new Int32Array(datetimes.length * 7);
+        for (let i = 0; i < datetimes.length; i++) {
+            const dt = datetimes[i];
+            const offset = i * 7;
+            arr[offset] = dt.year;
+            arr[offset + 1] = dt.month;
+            arr[offset + 2] = dt.day;
+            if (dt.time) {
+                arr[offset + 3] = dt.time.hour;
+                arr[offset + 4] = dt.time.minute;
+                arr[offset + 5] = dt.time.second;
+                arr[offset + 6] = dt.offset ?? -1;
+            }
+            else {
+                arr[offset + 3] = -1;
+                arr[offset + 4] = -1;
+                arr[offset + 5] = -1;
+                arr[offset + 6] = -1;
+            }
+        }
+        return arr;
     }
     toPlain(options) {
         let plain;
@@ -148,10 +246,26 @@ export class DateTime {
         return plain;
     }
     /**
-     * Converts DateTime into ISO 8601 string:
-     * * `YYYYMMDD` for date only
-     * - `YYYYMMDDTHHMMSSZ` for UTC
-     * - `YYYYMMDDTHHMMSS` for local
+     * Converts the DateTime into an RFC 5545 formatted string.
+     *
+     * Format depends on the DateTime type:
+     * - `YYYYMMDD` for date only
+     * - `YYYYMMDDTHHMMSSZ` for UTC date-time
+     * - `YYYYMMDDTHHMMSS` for local date-time
+     *
+     * @returns An RFC 5545 formatted string
+     *
+     * @example
+     * ```typescript
+     * const date = DateTime.date(2024, 1, 15);
+     * console.log(date.toString()); // "20240115"
+     *
+     * const local = DateTime.local(2024, 1, 15, 14, 30, 0);
+     * console.log(local.toString()); // "20240115T143000"
+     *
+     * const utc = DateTime.utc(2024, 1, 15, 14, 30, 0);
+     * console.log(utc.toString()); // "20240115T143000Z"
+     * ```
      */
     toString() {
         let str = this.year.toString().padStart(4, '0') +
@@ -167,8 +281,79 @@ export class DateTime {
         }
         return str;
     }
+    /**
+     * Converts the DateTime to a Unix timestamp in milliseconds.
+     *
+     * This method requires timezone offset information to be available. The offset
+     * is automatically set for:
+     * - DateTime instances with `utc: true`
+     * - DateTime instances generated by RRule methods (`all`, `between`, or iteration)
+     *
+     * @returns The Unix timestamp in milliseconds since January 1, 1970 00:00:00 UTC
+     * @throws {Error} If timezone offset information is not available
+     *
+     * @example
+     * ```typescript
+     * const utc = DateTime.utc(2024, 1, 15, 14, 30, 0);
+     * const timestamp = utc.toTimestamp();
+     * console.log(timestamp); // 1705328400000
+     *
+     * // DateTime from RRule methods have offset information
+     * const rrule = new RRule({ freq: Frequency.Daily, dtstart: DateTime.local(2024, 1, 1, 10, 0, 0) });
+     * const occurrences = rrule.all();
+     * const timestamp2 = occurrences[0].toTimestamp();
+     * ```
+     */
+    toTimestamp() {
+        if (typeof this.offset === 'undefined') {
+            throw new Error('There is no information about time zone offset');
+        }
+        return this.toMilliseconds();
+    }
+    /**
+     * Converts the DateTime to a JavaScript Date object.
+     *
+     * This method requires timezone offset information to be available. The offset
+     * is automatically set for:
+     * - DateTime instances with `utc: true`
+     * - DateTime instances generated by RRule methods (`all`, `between`, or iteration)
+     *
+     * @returns A JavaScript Date object representing the same moment in time
+     * @throws {Error} If timezone offset information is not available
+     *
+     * @example
+     * ```typescript
+     * const utc = DateTime.utc(2024, 1, 15, 14, 30, 0);
+     * const date = utc.toDate();
+     * console.log(date.toISOString()); // "2024-01-15T14:30:00.000Z"
+     *
+     * // DateTime from RRule methods have offset information
+     * const rrule = new RRule({ freq: Frequency.Daily, dtstart: DateTime.utc(2024, 1, 1, 10, 0, 0) });
+     * const occurrences = rrule.all();
+     * const date2 = occurrences[0].toDate();
+     * ```
+     */
+    toDate() {
+        if (typeof this.offset !== 'number') {
+            throw new Error('There is no information about time zone offset');
+        }
+        return new Date(this.toMilliseconds());
+    }
     /** @internal */
-    toNumeric() {
-        return this.state.numeric;
+    toInt32Array() {
+        return new Int32Array([
+            this.year,
+            this.month,
+            this.day,
+            this.time ? this.time.hour : -1,
+            this.time ? this.time.minute : -1,
+            this.time ? this.time.second : -1,
+            this.offset ?? -1,
+        ]);
+    }
+    toMilliseconds() {
+        let time = Date.UTC(this.year, this.month - 1, this.day, this.time?.hour ?? 0, this.time?.minute ?? 0, this.time?.second ?? 0);
+        time -= (this.offset ?? 0) * 1000;
+        return time;
     }
 }

package/dist/browser/dtstart.d.ts

@@ -1,20 +1,110 @@
 import { DateTime, type Time, type DateTimeLike, type DateLike } from './datetime';
+/**
+ * Options for creating a DtStart instance.
+ */
 export interface DtStartOptions<DT extends DateTime<Time> | DateTime<undefined>> {
-    datetime: DT;
+    /** The start date/time value */
+    value: DT;
+    /** Optional timezone identifier (e.g., "America/New_York") */
     tzid?: string;
 }
+/**
+ * Plain object representation of DtStart.
+ */
 export interface DtStartLike<DT extends DateTimeLike | DateLike> {
-    datetime: DT;
+    /** The start date/time value */
+    value: DT;
+    /** Optional timezone identifier (e.g., "America/New_York") */
     tzid?: string;
 }
+/**
+ * Represents the start date/time for a recurrence rule (DTSTART property).
+ *
+ * DtStart defines when the recurrence pattern begins. It can optionally
+ * include a timezone identifier for proper timezone handling.
+ *
+ * @example
+ * ```typescript
+ * // Create with DateTime and timezone
+ * const dtstart = new DtStart(
+ *   DateTime.local(2024, 1, 15, 9, 0, 0),
+ *   "America/New_York"
+ * );
+ *
+ * // Create with options object
+ * const dtstart2 = new DtStart({
+ *   value: DateTime.date(2024, 1, 15),
+ *   tzid: "Europe/London"
+ * });
+ * ```
+ */
 export declare class DtStart<DT extends DateTime<Time> | DateTime<undefined> = DateTime<Time>> {
+    /** The start date/time value */
     readonly value: DT;
+    /** Optional timezone identifier (e.g., "America/New_York") */
     readonly tzid?: string;
-    constructor(datetime: DT, tzid?: string);
+    constructor(value: DT, tzid?: string);
     constructor(options: DtStartOptions<DT>);
+    /**
+     * Creates a DtStart instance from a plain object representation.
+     *
+     * @param plain - Plain object with date/time and optional timezone
+     * @returns A new DtStart instance
+     *
+     * @example
+     * ```typescript
+     * const plain = {
+     *   value: { year: 2024, month: 1, day: 15, hour: 9, minute: 0, second: 0, utc: false },
+     *   tzid: "America/New_York"
+     * };
+     * const dtstart = DtStart.fromPlain(plain);
+     * ```
+     */
     static fromPlain(plain: DtStartLike<DateTimeLike>): DtStart<DateTime<Time>>;
     static fromPlain(plain: DtStartLike<DateLike>): DtStart<DateTime<undefined>>;
+    /**
+     * Creates a new DtStart instance with a different timezone.
+     *
+     * @param tzid - Timezone identifier (e.g., "America/New_York") or undefined
+     * @returns A new DtStart instance with the specified timezone
+     *
+     * @example
+     * ```typescript
+     * const dtstart = new DtStart(DateTime.local(2024, 1, 15, 9, 0, 0));
+     * const withTz = dtstart.setTzid("America/New_York");
+     * ```
+     */
     setTzid(tzid: string | undefined): DtStart<DT>;
+    /**
+     * Creates a new DtStart instance with a different date/time value.
+     *
+     * @param datetime - The new date/time value
+     * @returns A new DtStart instance with the specified value
+     *
+     * @example
+     * ```typescript
+     * const dtstart = new DtStart(DateTime.date(2024, 1, 15));
+     * const newStart = dtstart.setValue(DateTime.local(2024, 2, 1, 10, 0, 0));
+     * ```
+     */
     setValue<NDT extends DateTime<Time> | DateTime<undefined>>(datetime: NDT): DtStart<NDT>;
-    toPlain<DTL extends DateTimeLike | DateLike = DT extends DateTime<Time> ? DateTimeLike : DateLike>(): DtStartLike<DTL>;
+    /**
+     * Converts the DtStart instance to a plain object representation.
+     *
+     * @returns A plain object with date/time and optional timezone
+     *
+     * @example
+     * ```typescript
+     * const dtstart = new DtStart(
+     *   DateTime.local(2024, 1, 15, 9, 0, 0),
+     *   "America/New_York"
+     * );
+     * const plain = dtstart.toPlain();
+     * // {
+     * //   value: { year: 2024, month: 1, day: 15, hour: 9, minute: 0, second: 0, utc: false },
+     * //   tzid: "America/New_York"
+     * // }
+     * ```
+     */
+    toPlain(): DtStartLike<DT extends DateTime<Time> ? DateTimeLike : DateLike>;
 }

package/dist/browser/dtstart.js

@@ -1,30 +1,75 @@
 import { DateTime, } from './datetime';
+/**
+ * Represents the start date/time for a recurrence rule (DTSTART property).
+ *
+ * DtStart defines when the recurrence pattern begins. It can optionally
+ * include a timezone identifier for proper timezone handling.
+ *
+ * @example
+ * ```typescript
+ * // Create with DateTime and timezone
+ * const dtstart = new DtStart(
+ *   DateTime.local(2024, 1, 15, 9, 0, 0),
+ *   "America/New_York"
+ * );
+ *
+ * // Create with options object
+ * const dtstart2 = new DtStart({
+ *   value: DateTime.date(2024, 1, 15),
+ *   tzid: "Europe/London"
+ * });
+ * ```
+ */
 export class DtStart {
-    constructor(datetimeOrOptions, tzid) {
-        if ('datetime' in datetimeOrOptions) {
-            this.value = datetimeOrOptions.datetime;
-            this.tzid = datetimeOrOptions.tzid;
+    constructor(valueOrOptions, tzid) {
+        if ('value' in valueOrOptions) {
+            this.value = valueOrOptions.value;
+            this.tzid = valueOrOptions.tzid;
         }
         else {
-            this.value = datetimeOrOptions;
+            this.value = valueOrOptions;
             this.tzid = tzid;
         }
     }
     static fromPlain(plain) {
         return new this({
-            datetime: DateTime.fromPlain(plain.datetime),
+            value: DateTime.fromPlain(plain.value),
             tzid: plain.tzid,
         });
     }
+    /**
+     * Creates a new DtStart instance with a different timezone.
+     *
+     * @param tzid - Timezone identifier (e.g., "America/New_York") or undefined
+     * @returns A new DtStart instance with the specified timezone
+     *
+     * @example
+     * ```typescript
+     * const dtstart = new DtStart(DateTime.local(2024, 1, 15, 9, 0, 0));
+     * const withTz = dtstart.setTzid("America/New_York");
+     * ```
+     */
     setTzid(tzid) {
         return new DtStart(this.value, tzid);
     }
+    /**
+     * Creates a new DtStart instance with a different date/time value.
+     *
+     * @param datetime - The new date/time value
+     * @returns A new DtStart instance with the specified value
+     *
+     * @example
+     * ```typescript
+     * const dtstart = new DtStart(DateTime.date(2024, 1, 15));
+     * const newStart = dtstart.setValue(DateTime.local(2024, 2, 1, 10, 0, 0));
+     * ```
+     */
     setValue(datetime) {
         return new DtStart(datetime, this.tzid);
     }
     toPlain() {
         return {
-            datetime: this.value.toPlain(),
+            value: this.value.toPlain(),
             tzid: this.tzid,
         };
     }

package/dist/browser/exdate.d.ts

@@ -1,20 +1,124 @@
 import { DateTime, type Time, type DateTimeLike, type DateLike } from './datetime';
+/**
+ * Options for creating an ExDate instance.
+ */
 export interface ExDateOptions<DT extends DateTime<Time> | DateTime<undefined>> {
+    /** Array of date/time values to exclude from recurrence */
     values: DT[];
+    /** Optional timezone identifier (e.g., "America/New_York") */
     tzid?: string;
 }
+/**
+ * Plain object representation of ExDate.
+ */
 export interface ExDateLike<DT extends DateTimeLike | DateLike> {
+    /** Array of date/time values to exclude from recurrence */
     values: DT[];
+    /** Optional timezone identifier (e.g., "America/New_York") */
     tzid?: string;
 }
+/**
+ * Represents exception dates (EXDATE property) for a recurrence rule.
+ *
+ * ExDate specifies date/time values that should be excluded from the
+ * recurrence set. This is useful for marking exceptions like holidays
+ * or cancelled events in a recurring series.
+ *
+ * @example
+ * ```typescript
+ * // Create with single date
+ * const exdate1 = new ExDate(DateTime.date(2024, 1, 15));
+ *
+ * // Create with multiple dates
+ * const exdate2 = new ExDate([
+ *   DateTime.date(2024, 1, 15),
+ *   DateTime.date(2024, 1, 22)
+ * ]);
+ *
+ * // Create with timezone
+ * const exdate3 = new ExDate({
+ *   values: [DateTime.local(2024, 1, 15, 9, 0, 0)],
+ *   tzid: "America/New_York"
+ * });
+ * ```
+ */
 export declare class ExDate<DT extends DateTime<Time> | DateTime<undefined> = DateTime<Time>> {
+    /** Array of date/time values to exclude from recurrence */
     readonly values: DT[];
+    /** Optional timezone identifier (e.g., "America/New_York") */
     readonly tzid?: string;
+    constructor(values: DT, tzid?: string);
     constructor(values: DT[], tzid?: string);
     constructor(options: ExDateOptions<DT>);
+    /**
+     * Creates an ExDate instance from a plain object representation.
+     *
+     * @param plain - Plain object with date/time values and optional timezone
+     * @returns A new ExDate instance
+     *
+     * @example
+     * ```typescript
+     * const plain = {
+     *   values: [
+     *     { year: 2024, month: 1, day: 15 },
+     *     { year: 2024, month: 1, day: 22 }
+     *   ],
+     *   tzid: "America/New_York"
+     * };
+     * const exdate = ExDate.fromPlain(plain);
+     * ```
+     */
     static fromPlain(plain: ExDateLike<DateTimeLike>): ExDate<DateTime<Time>>;
     static fromPlain(plain: ExDateLike<DateLike>): ExDate<DateTime<undefined>>;
+    /**
+     * Creates a new ExDate instance with a different timezone.
+     *
+     * @param tzid - Timezone identifier (e.g., "America/New_York") or undefined
+     * @returns A new ExDate instance with the specified timezone
+     *
+     * @example
+     * ```typescript
+     * const exdate = new ExDate([DateTime.date(2024, 1, 15)]);
+     * const withTz = exdate.setTzid("America/New_York");
+     * ```
+     */
     setTzid(tzid: string | undefined): ExDate<DT>;
+    /**
+     * Creates a new ExDate instance with different date/time values.
+     *
+     * @param datetimes - Array of new date/time values
+     * @returns A new ExDate instance with the specified values
+     *
+     * @example
+     * ```typescript
+     * const exdate = new ExDate([DateTime.date(2024, 1, 15)]);
+     * const updated = exdate.setValues([
+     *   DateTime.date(2024, 1, 15),
+     *   DateTime.date(2024, 1, 22)
+     * ]);
+     * ```
+     */
     setValues<NDT extends DateTime<Time> | DateTime<undefined>>(datetimes: NDT[]): ExDate<NDT>;
-    toPlain<DTL extends DateTimeLike | DateLike = DT extends DateTime<Time> ? DateTimeLike : DateLike>(): ExDateLike<DTL>;
+    /**
+     * Converts the ExDate instance to a plain object representation.
+     *
+     * @returns A plain object with date/time values and optional timezone
+     *
+     * @example
+     * ```typescript
+     * const exdate = new ExDate(
+     *   [DateTime.date(2024, 1, 15), DateTime.date(2024, 1, 22)],
+     *   "America/New_York"
+     * );
+     * const plain = exdate.toPlain();
+     * // {
+     * //   values: [
+     * //     { year: 2024, month: 1, day: 15 },
+     * //     { year: 2024, month: 1, day: 22 }
+     * //   ],
+     * //   tzid: "America/New_York"
+     * // }
+     * ```
+     */
+    toPlain(): DT extends DateTime<Time> ? ExDateLike<DateTimeLike> : ExDateLike<DateLike>;
 }