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

package/README.md

@@ -7,6 +7,8 @@
 
 `rrule-rust` is a library for handling recurrence rules, powered by Rust's high-performance [rrule](https://crates.io/crates/rrule) crate.
 
+> 🚀 It provides significant performance improvements over pure JavaScript implementation, especially when working with non-UTC timezones.
+
 1. [Quick Start](#quick-start)
 2. [Performance](#performance)
 
@@ -42,19 +44,35 @@ const asString = set.toString(); // DTSTART;TZID=US/Eastern:19970902T090000\nFRE
 
 ## Performance
 
-```
-  Host: MacBook Pro, 14-inch, 2023
-  OS: macOS 14.4.1 (23E224)
-  Processor: Apple M3 Pro
-  Memory: 36 GB LPDDR5
-```
+**Test Environment:**
+
+- **Host:** MacBook Pro, 14-inch, 2023
+- **OS:** macOS 14.4.1 (23E224)
+- **Processor:** Apple M3 Pro
+- **Memory:** 36 GB LPDDR5
+- **Node.js:** v24.11.1
+
+**Test Case:** Generating 30 daily occurrences using `rruleSet.all()`
 
-|          | rrule        | rrule-rust    |              |
-| -------- | ------------ | ------------- | ------------ |
-| UTC TZ   | 15 904 ops/s | 108 538 ops/s | ~6x faster   |
-| Other TZ | 260 ops/s    | 106 034 ops/s | ~400x faster |
+#### UTC Timezone
 
-You can run benchmarks using `npm run benchmark`.
+| Implementation   | Without Cache  | With Cache        |
+| ---------------- | -------------- | ----------------- |
+| **rrule-rust**   | ~240,000 ops/s | ~14,000,000 ops/s |
+| **rrule (node)** | ~20,000 ops/s  | ~1,300,000 ops/s  |
+
+#### Other Timezone (Pacific/Kiritimati)
+
+| Implementation   | Without Cache  | With Cache        |
+| ---------------- | -------------- | ----------------- |
+| **rrule-rust**   | ~235,000 ops/s | ~14,000,000 ops/s |
+| **rrule (node)** | ~420 ops/s     | ~1,300,000 ops/s  |
+
+**Run benchmarks yourself:**
+
+```bash
+npm run benchmark
+```
 
 ## License
 

package/dist/browser/cache.d.ts

@@ -0,0 +1,15 @@
+export interface OperationOptions {
+    disabled: boolean;
+}
+export declare class OperationCache {
+    private _disabled;
+    private readonly store;
+    constructor({ disabled }: OperationOptions);
+    get disabled(): boolean;
+    getOrSet<T>(key: string, defaultValue: T): T;
+    getOrCompute<T>(key: string, compute: () => T): T;
+    disable(): void;
+    enable(): void;
+    clear(): void;
+    clone(): OperationCache;
+}

package/dist/browser/cache.js

@@ -0,0 +1,44 @@
+export class OperationCache {
+    constructor({ disabled }) {
+        this._disabled = disabled;
+        this.store = new Map();
+    }
+    get disabled() {
+        return this._disabled;
+    }
+    getOrSet(key, defaultValue) {
+        if (this.disabled) {
+            return defaultValue;
+        }
+        if (this.store.has(key)) {
+            return this.store.get(key);
+        }
+        this.store.set(key, defaultValue);
+        return defaultValue;
+    }
+    getOrCompute(key, compute) {
+        if (this.disabled) {
+            return compute();
+        }
+        if (this.store.has(key)) {
+            return this.store.get(key);
+        }
+        const value = compute();
+        this.store.set(key, value);
+        return value;
+    }
+    disable() {
+        this._disabled = true;
+    }
+    enable() {
+        this._disabled = false;
+    }
+    clear() {
+        this.store.clear();
+    }
+    clone() {
+        return new OperationCache({
+            disabled: this.disabled,
+        });
+    }
+}

package/dist/browser/datetime.d.ts

@@ -1,77 +1,317 @@
+/**
+ * Represents a date without time information.
+ */
 export interface DateLike {
+    /** Year component (e.g., 2024) */
     readonly year: number;
+    /** Month component (1-12) */
     readonly month: number;
+    /** Day component (1-31) */
     readonly day: number;
 }
+export type StripUtc<T extends DateTimeLike> = Omit<T, 'utc'>;
+export type OptionalUtc<T extends DateTimeLike> = Omit<T, 'utc'> & {
+    utc?: boolean;
+};
+/**
+ * Represents a date with time information.
+ */
 export interface DateTimeLike {
+    /** Year component (e.g., 2024) */
     readonly year: number;
+    /** Month component (1-12) */
     readonly month: number;
+    /** Day component (1-31) */
     readonly day: number;
+    /** Hour component (0-23) */
     readonly hour: number;
+    /** Minute component (0-59) */
     readonly minute: number;
+    /** Second component (0-59) */
     readonly second: number;
+    /** Whether the time is in UTC */
     readonly utc: boolean;
 }
+/**
+ * Represents time information.
+ */
 export interface Time {
+    /** Hour component (0-23) */
     readonly hour: number;
+    /** Minute component (0-59) */
     readonly minute: number;
+    /** Second component (0-59) */
     readonly second: number;
+    /** Whether the time is in UTC */
     readonly utc: boolean;
 }
+/**
+ * Options for converting DateTime to plain object.
+ */
 export interface ToPlainDateTimeOptions {
+    /** Whether to exclude the `utc` field from the result */
     stripUtc?: boolean;
 }
 /**
- * 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 declare class DateTime<T extends Time | undefined> {
-    private readonly state;
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    readonly time: T;
+    private offset?;
     private constructor();
-    get year(): number;
-    get month(): number;
-    get day(): number;
-    get time(): T;
     /**
      * Creates a new DateTime object from the given date and time components.
+     *
+     * This method can create either a date-only or date-time instance depending on the parameters.
+     *
+     * @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), optional
+     * @param minute - Minute component (0-59), optional
+     * @param second - Second component (0-59), optional
+     * @param utc - Whether the time is in UTC, optional
+     * @returns A DateTime instance with or without time information
+     *
+     * @example
+     * ```typescript
+     * // Create a date-only DateTime
+     * const date = DateTime.create(2024, 1, 15);
+     *
+     * // Create a local DateTime
+     * const local = DateTime.create(2024, 1, 15, 14, 30, 0, false);
+     *
+     * // Create a UTC DateTime
+     * const utc = DateTime.create(2024, 1, 15, 14, 30, 0, true);
+     * ```
      */
     static create(year: number, month: number, day: number): DateTime<undefined>;
     static create(year: number, month: number, day: number, hour: number, minute: number, second: number, utc: boolean): DateTime<Time>;
     /**
-     * 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: number, month: number, day: number): DateTime<undefined>;
     /**
+     * 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: number, month: number, day: number, hour: number, minute: number, second: number): DateTime<Time>;
     /**
+     * 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: number, month: number, day: number, hour: number, minute: number, second: number): DateTime<Time>;
     /**
-     * Creates a new DateTime object from the given plain object.
+     * Creates a new DateTime object from a plain object representation.
+     *
+     * @param plain - A plain object with date or date-time components
+     * @returns A DateTime instance
+     *
+     * @example
+     * ```typescript
+     * // From DateLike
+     * const date = DateTime.fromPlain({ year: 2024, month: 1, day: 15 });
+     *
+     * // From DateTimeLike
+     * const datetime = DateTime.fromPlain({
+     *   year: 2024, month: 1, day: 15,
+     *   hour: 14, minute: 30, second: 0, utc: false
+     * });
+     * ```
      */
-    static fromPlain(plain: DateTimeLike): DateTime<Time>;
+    static fromPlain(plain: OptionalUtc<DateTimeLike>): DateTime<Time>;
+    static fromPlain(plain: StripUtc<DateTimeLike>): DateTime<Time>;
     static fromPlain(plain: DateLike): DateTime<undefined>;
     /**
-     * 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");
+     * ```
      */
     static fromString(str: string): DateTime<Time> | DateTime<undefined>;
     /**
-     * Converts DateTime into a plain object.
+     * Converts the DateTime into a plain object representation.
+     *
+     * @param options - Conversion options
+     * @param options.stripUtc - If true, excludes the `utc` field from the result
+     * @returns A plain object with date or date-time components
+     *
+     * @example
+     * ```typescript
+     * const utc = DateTime.utc(2024, 1, 15, 14, 30, 0);
+     *
+     * // With utc field
+     * const plain1 = utc.toPlain();
+     * // { year: 2024, month: 1, day: 15, hour: 14, minute: 30, second: 0, utc: true }
+     *
+     * // Without utc field
+     * const plain2 = utc.toPlain({ stripUtc: true });
+     * // { year: 2024, month: 1, day: 15, hour: 14, minute: 30, second: 0 }
+     *
+     * // Date-only DateTime
+     * const date = DateTime.date(2024, 1, 15);
+     * const plain3 = date.toPlain();
+     * // { year: 2024, month: 1, day: 15 }
+     * ```
      */
-    toPlain<DTL extends DateTimeLike>(options?: ToPlainDateTimeOptions & {
+    toPlain(options: ToPlainDateTimeOptions & {
         stripUtc: false;
-    }): DTL;
-    toPlain<DTL extends Omit<DateTimeLike, 'utc'>>(options?: ToPlainDateTimeOptions & {
+    }): T extends Time ? DateTimeLike : DateLike;
+    toPlain(options: ToPlainDateTimeOptions & {
         stripUtc: true;
-    }): DTL;
-    toPlain<DTL extends DateLike>(): DTL;
+    }): T extends Time ? StripUtc<DateTimeLike> : DateLike;
+    toPlain(): T extends Time ? DateTimeLike : DateLike;
     /**
-     * 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(): string;
+    /**
+     * 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(): number;
+    /**
+     * 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(): Date;
+    private toMilliseconds;
 }