rrule-rust 3.0.0-alpha.5 → 3.0.0-alpha.7

package/README.md

@@ -25,15 +25,14 @@ If you need a browser-compatible version with WASM support:
 For more usage examples and advanced scenarios, see the [tests directory](https://github.com/lsndr/rrule-rust/tree/master/tests) in the repository.
 
 ```typescript
-import { RRule, RRuleSet, Frequency, DateTime } from 'rrule-rust';
+import { RRule, RRuleSet, Frequency, DateTime, DtStart } from 'rrule-rust';
 
 const rrule = new RRule({
   frequency: Frequency.Daily,
   count: 5,
 });
 const set = new RRuleSet({
-  dtstart: DateTime.create(1997, 9, 2, 9, 0, 0, false),
-  tzid: 'US/Eastern',
+  dtstart: new DtStart(DateTime.local(1997, 9, 2, 9, 0, 0), 'US/Eastern'),
   rrules: [rrule],
 });
 

package/dist/browser/datetime.d.ts

@@ -1,3 +1,8 @@
+export interface DateLike {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+}
 export interface DateTimeLike {
     readonly year: number;
     readonly month: number;
@@ -7,55 +12,64 @@ export interface DateTimeLike {
     readonly second: number;
     readonly utc: boolean;
 }
-export type DateTimeLikeWithoutUtc = Omit<DateTimeLike, 'utc'>;
-export interface ToPlainOptions {
+export interface Time {
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+    readonly utc: boolean;
+}
+export interface ToPlainDateTimeOptions {
     stripUtc?: boolean;
 }
 /**
  * Represents a date and time. Either local or UTC.
  */
-export declare class DateTime implements DateTimeLike {
-    private readonly numeric;
+export declare class DateTime<T extends Time | undefined> {
+    private readonly state;
     private constructor();
     get year(): number;
     get month(): number;
     get day(): number;
-    get hour(): number;
-    get minute(): number;
-    get second(): number;
-    get utc(): boolean;
+    get time(): T;
+    /**
+     * Creates a new DateTime object from the given date and time components.
+     */
+    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.
      */
-    static create(year: number, month: number, day: number, hour: number, minute: number, second: number, utc: boolean): DateTime;
+    static date(year: number, month: number, day: number): DateTime<undefined>;
     /**
      * This method is shorthand for `DateTime.create` with `utc` set to `false`.
      */
-    static local(year: number, month: number, day: number, hour: number, minute: number, second: number): DateTime;
+    static local(year: number, month: number, day: number, hour: number, minute: number, second: number): DateTime<Time>;
     /**
      * This method is shorthand for `DateTime.create` with `utc` set to `true`.
      */
-    static utc(year: number, month: number, day: number, hour: number, minute: number, second: number): DateTime;
+    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.
      */
-    static fromPlain(plain: DateTimeLike): DateTime;
+    static fromPlain(plain: 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.
      */
-    static fromString(str: string): DateTime;
+    static fromString(str: string): DateTime<Time> | DateTime<undefined>;
     /**
      * Converts DateTime into a plain object.
      */
-    toPlain(options: {
+    toPlain<DTL extends DateTimeLike>(options?: ToPlainDateTimeOptions & {
         stripUtc: false;
-    } & ToPlainOptions): DateTimeLike;
-    toPlain(options: {
+    }): DTL;
+    toPlain<DTL extends Omit<DateTimeLike, 'utc'>>(options?: ToPlainDateTimeOptions & {
         stripUtc: true;
-    } & ToPlainOptions): DateTimeLikeWithoutUtc;
-    toPlain(): DateTimeLike;
+    }): DTL;
+    toPlain<DTL extends DateLike>(): DTL;
     /**
      * Converts DateTime into ISO 8601 string:
+     * * `YYYYMMDD` for date only
      * - `YYYYMMDDTHHMMSSZ` for UTC
      * - `YYYYMMDDTHHMMSS` for local
      */

package/dist/browser/datetime.js

@@ -3,41 +3,64 @@
  */
 export class DateTime {
     constructor(numeric) {
-        this.numeric = numeric;
+        this.state = {
+            numeric,
+        };
     }
     get year() {
-        return Math.floor(this.numeric / 100000000000);
+        return (this.state.year ??= Math.floor(this.state.numeric / 100000000000));
     }
     get month() {
-        return Math.floor((this.numeric / 1000000000) % 100);
+        return (this.state.month ??= Math.floor((this.state.numeric / 1000000000) % 100));
     }
     get day() {
-        return Math.floor((this.numeric / 10000000) % 100);
-    }
-    get hour() {
-        return Math.floor((this.numeric / 100000) % 100);
-    }
-    get minute() {
-        return Math.floor((this.numeric / 1000) % 100);
+        return (this.state.day ??= Math.floor((this.state.numeric / 10000000) % 100));
     }
-    get second() {
-        return Math.floor((this.numeric / 10) % 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,
+            });
+        }
     }
-    get utc() {
-        return this.numeric % 10 == 1;
+    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);
+        }
+        else {
+            numeric += 100000;
+            numeric += 1000;
+            numeric += 10;
+            numeric += 2;
+            return new DateTime(numeric);
+        }
     }
     /**
      * Creates a new DateTime object from the given date and time components.
      */
-    static create(year, month, day, hour, minute, second, utc) {
-        const numeric = year * 100000000000 +
-            month * 1000000000 +
-            day * 10000000 +
-            hour * 100000 +
-            minute * 1000 +
-            second * 10 +
-            (utc ? 1 : 0);
-        return new DateTime(numeric);
+    static date(year, month, day) {
+        return this.create(year, month, day);
     }
     /**
      * This method is shorthand for `DateTime.create` with `utc` set to `false`.
@@ -51,68 +74,101 @@ export class DateTime {
     static utc(year, month, day, hour, minute, second) {
         return DateTime.create(year, month, day, hour, minute, second, true);
     }
-    /**
-     * Creates a new DateTime object from the given plain object.
-     */
     static fromPlain(plain) {
-        return DateTime.create(plain.year, plain.month, plain.day, plain.hour, plain.minute, plain.second, plain.utc);
+        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);
     }
     /**
      * Creates a new DateTime object from provided string representation of a date according to RFC 5545.
      */
+    // TODO: add template expression
     static fromString(str) {
-        const typeError = new TypeError('Invalid date time string');
-        if (str.length > 16 || str.length < 15) {
-            throw typeError;
+        if (!(str.length === 8 || (str.length <= 16 && str.length >= 15))) {
+            throw new TypeError('Invalid date time string');
         }
         const year = parseInt(str.slice(0, 4));
         const month = parseInt(str.slice(4, 6));
         const day = parseInt(str.slice(6, 8));
-        const hour = parseInt(str.slice(9, 11));
-        const minute = parseInt(str.slice(11, 13));
-        const second = parseInt(str.slice(13, 15));
-        const utc = str.endsWith('Z');
-        if (isNaN(year) ||
-            isNaN(month) ||
-            isNaN(day) ||
-            isNaN(hour) ||
-            isNaN(minute) ||
-            isNaN(second)) {
-            throw typeError;
+        let hour = undefined;
+        let minute = undefined;
+        let second = undefined;
+        let utc = undefined;
+        if (isNaN(year) || isNaN(month) || isNaN(day)) {
+            throw new TypeError('Invalid date');
+        }
+        if (str.length > 8) {
+            hour = parseInt(str.slice(9, 11));
+            minute = parseInt(str.slice(11, 13));
+            second = parseInt(str.slice(13, 15));
+            utc = str.endsWith('Z');
+            if (isNaN(hour) || isNaN(minute) || isNaN(second)) {
+                throw new TypeError('Invalid time');
+            }
+            return DateTime.create(year, month, day, hour, minute, second, utc);
+        }
+        else {
+            return DateTime.create(year, month, day);
         }
-        return DateTime.create(year, month, day, hour, minute, second, utc);
     }
     /** @internal */
     static fromNumeric(numeric) {
         return new DateTime(numeric);
     }
     toPlain(options) {
-        return {
-            year: this.year,
-            month: this.month,
-            day: this.day,
-            hour: this.hour,
-            minute: this.minute,
-            second: this.second,
-            utc: options?.stripUtc ? undefined : this.utc,
-        };
+        let plain;
+        if (this.time) {
+            plain = options?.stripUtc
+                ? {
+                    year: this.year,
+                    month: this.month,
+                    day: this.day,
+                    hour: this.time.hour,
+                    minute: this.time.minute,
+                    second: this.time.second,
+                }
+                : {
+                    year: this.year,
+                    month: this.month,
+                    day: this.day,
+                    hour: this.time.hour,
+                    minute: this.time.minute,
+                    second: this.time.second,
+                    utc: this.time.utc,
+                };
+        }
+        else {
+            plain = {
+                year: this.year,
+                month: this.month,
+                day: this.day,
+            };
+        }
+        return plain;
     }
     /**
      * Converts DateTime into ISO 8601 string:
+     * * `YYYYMMDD` for date only
      * - `YYYYMMDDTHHMMSSZ` for UTC
      * - `YYYYMMDDTHHMMSS` for local
      */
     toString() {
-        const year = this.year.toString().padStart(4, '0');
-        const month = this.month.toString().padStart(2, '0');
-        const day = this.day.toString().padStart(2, '0');
-        const hour = this.hour.toString().padStart(2, '0');
-        const minute = this.minute.toString().padStart(2, '0');
-        const second = this.second.toString().padStart(2, '0');
-        return `${year}${month}${day}T${hour}${minute}${second}${this.utc ? 'Z' : ''}`;
+        let str = this.year.toString().padStart(4, '0') +
+            this.month.toString().padStart(2, '0') +
+            this.day.toString().padStart(2, '0');
+        if (this.time) {
+            str +=
+                'T' +
+                    this.time.hour.toString().padStart(2, '0') +
+                    this.time.minute.toString().padStart(2, '0') +
+                    this.time.second.toString().padStart(2, '0') +
+                    (this.time.utc ? 'Z' : '');
+        }
+        return str;
     }
     /** @internal */
     toNumeric() {
-        return this.numeric;
+        return this.state.numeric;
     }
 }

package/dist/browser/dtstart.d.ts

@@ -0,0 +1,20 @@
+import { DateTime, type Time, type DateTimeLike, type DateLike } from './datetime';
+export interface DtStartOptions<DT extends DateTime<Time> | DateTime<undefined>> {
+    datetime: DT;
+    tzid?: string;
+}
+export interface DtStartLike<DT extends DateTimeLike | DateLike> {
+    datetime: DT;
+    tzid?: string;
+}
+export declare class DtStart<DT extends DateTime<Time> | DateTime<undefined> = DateTime<Time>> {
+    readonly datetime: DT;
+    readonly tzid?: string;
+    constructor(datetime: DateTime<Time> | DateTime<undefined>, tzid?: string);
+    constructor(options: DtStartOptions<DT>);
+    static fromPlain(plain: DtStartLike<DateTimeLike>): DtStart<DateTime<Time>>;
+    static fromPlain(plain: DtStartLike<DateLike>): DtStart<DateTime<undefined>>;
+    setTzid(tzid: string | undefined): DtStart<DT>;
+    setDatetime<NDT extends DateTime<Time> | DateTime<undefined>>(datetime: NDT): DtStart<NDT>;
+    toPlain<DTL extends DateTimeLike | DateLike = DT extends DateTime<Time> ? DateTimeLike : DateLike>(): DtStartLike<DTL>;
+}

package/dist/browser/dtstart.js

@@ -0,0 +1,31 @@
+import { DateTime, } from './datetime';
+export class DtStart {
+    constructor(datetimeOrOptions, tzid) {
+        if ('datetime' in datetimeOrOptions) {
+            this.datetime = datetimeOrOptions.datetime;
+            this.tzid = datetimeOrOptions.tzid;
+        }
+        else {
+            this.datetime = datetimeOrOptions;
+            this.tzid = tzid;
+        }
+    }
+    static fromPlain(plain) {
+        return new this({
+            datetime: DateTime.fromPlain(plain.datetime),
+            tzid: plain.tzid,
+        });
+    }
+    setTzid(tzid) {
+        return new DtStart(this.datetime, tzid);
+    }
+    setDatetime(datetime) {
+        return new DtStart(datetime, this.tzid);
+    }
+    toPlain() {
+        return {
+            datetime: this.datetime.toPlain(),
+            tzid: this.tzid,
+        };
+    }
+}

package/dist/browser/index.d.ts

@@ -1,3 +1,4 @@
 export * from './rrule-set';
 export * from './rrule';
 export * from './datetime';
+export * from './dtstart';

package/dist/browser/index.js

@@ -1,3 +1,4 @@
 export * from './rrule-set';
 export * from './rrule';
 export * from './datetime';
+export * from './dtstart';

package/dist/browser/rrule-set.d.ts

@@ -1,51 +1,49 @@
 import { RRule, type RRuleLike } from './rrule';
-import { DateTime, type DateTimeLike } from './datetime';
-export interface RRuleSetOptions {
-    readonly dtstart: DateTime;
-    readonly tzid?: string;
-    readonly rrules?: readonly RRule[];
-    readonly exrules?: readonly RRule[];
-    readonly exdates?: readonly DateTime[];
-    readonly rdates?: readonly DateTime[];
+import { type Time, DateTime, type DateTimeLike, type DateLike } from './datetime';
+import { DtStart, type DtStartLike } from './dtstart';
+export interface RRuleSetOptions<DT extends DateTime<Time> | DateTime<undefined> = DateTime<Time>> {
+    readonly dtstart: DtStart<DT>;
+    readonly rrules?: readonly RRule<DT>[];
+    readonly exrules?: readonly RRule<DT>[];
+    readonly exdates?: readonly DT[];
+    readonly rdates?: readonly DT[];
 }
-export interface RRuleSetLike {
-    readonly dtstart: DateTimeLike;
-    readonly tzid?: string;
-    readonly rrules: readonly RRuleLike[];
-    readonly exrules: readonly RRuleLike[];
-    readonly exdates: readonly DateTimeLike[];
-    readonly rdates: readonly DateTimeLike[];
+export interface RRuleSetLike<DT extends DateTimeLike | DateLike> {
+    readonly dtstart: DtStartLike<DT>;
+    readonly rrules: readonly RRuleLike<DT>[];
+    readonly exrules: readonly RRuleLike<DT>[];
+    readonly exdates: readonly DT[];
+    readonly rdates: readonly DT[];
 }
-export declare class RRuleSet implements Iterable<DateTime> {
-    readonly dtstart: DateTime;
-    readonly tzid: string;
-    readonly rrules: readonly RRule[];
-    readonly exrules: readonly RRule[];
-    readonly exdates: readonly DateTime[];
-    readonly rdates: readonly DateTime[];
-    constructor(dtstart: DateTime | DateTimeLike, tzid?: string);
-    constructor(options: RRuleSetOptions);
+export declare class RRuleSet<DT extends DateTime<Time> | DateTime<undefined>> implements Iterable<DateTime<Time> | DateTime<undefined>> {
+    readonly dtstart: DtStart<DT>;
+    readonly rrules: readonly RRule<DT>[];
+    readonly exrules: readonly RRule<DT>[];
+    readonly exdates: readonly DT[];
+    readonly rdates: readonly DT[];
+    constructor(dtstart: DtStart<DT>);
+    constructor(options: RRuleSetOptions<DT>);
     /**
      * Parses a string into an RRuleSet.
      */
-    static parse(str: string): RRuleSet;
-    static fromPlain(plain: RRuleSetLike): RRuleSet;
-    setDtstart(dtstart: DateTime): RRuleSet;
-    setTzid(tzid: string): RRuleSet;
-    addRrule(rrule: RRule): RRuleSet;
-    setRrules(rrules: readonly RRule[]): RRuleSet;
-    addExrule(rrule: RRule): RRuleSet;
-    setExrules(rrules: readonly RRule[]): RRuleSet;
-    addExdate(datetime: DateTime): RRuleSet;
-    setExdates(datetimes: readonly DateTime[]): RRuleSet;
-    addRdate(datetime: DateTime): RRuleSet;
-    setRdates(datetimes: readonly DateTime[]): RRuleSet;
+    static parse<DT extends DateTime<Time> | DateTime<undefined>>(str: string): RRuleSet<DT>;
+    static fromPlain(plain: RRuleSetLike<DateTimeLike>): RRuleSet<DateTime<Time>>;
+    static fromPlain(plain: RRuleSetLike<DateLike>): RRuleSet<DateTime<undefined>>;
+    setDtstart(dtstart: DtStart<DT>): RRuleSet<DT>;
+    addRrule<RRDT extends DT>(rrule: RRule<RRDT>): RRuleSet<DT>;
+    setRrules(rrules: readonly RRule<DT>[]): RRuleSet<DT>;
+    addExrule(rrule: RRule<DT>): RRuleSet<DT>;
+    setExrules(rrules: readonly RRule<DT>[]): RRuleSet<DT>;
+    addExdate(datetime: DT): RRuleSet<DT>;
+    setExdates(datetimes: readonly DT[]): RRuleSet<DT>;
+    addRdate(datetime: DT): RRuleSet<DT>;
+    setRdates(datetimes: readonly DT[]): RRuleSet<DT>;
     /**
      * Returns all the occurrences of the rrule.
      *
      * @param limit - The maximum number of occurrences to return.
      */
-    all(limit?: number): DateTime[];
+    all(limit?: number): DT[];
     /**
      * Returns all the occurrences of the rrule between after and before.
      *
@@ -53,18 +51,18 @@ export declare class RRuleSet implements Iterable<DateTime> {
      * @param before - The upper bound date.
      * @param inclusive - Whether to include after and before in the list of occurrences.
      */
-    between(after: DateTime, before: DateTime, inclusive?: boolean): DateTime[];
+    between(after: DT, before: DT, inclusive?: boolean): DT[];
     /**
      * Sets the RRuleSet from a string.
      *
      * @param str - The string to parse.
      */
-    setFromString(str: string): RRuleSet;
+    setFromString<NDT extends DateTime<Time> | DateTime<undefined> = DT>(str: string): RRuleSet<NDT>;
     toString(): string;
     /**
      * Converts the RRuleSet to a plain object.
      */
-    toPlain(): RRuleSetLike;
-    [Symbol.iterator](): Iterator<DateTime, any, any>;
+    toPlain(): RRuleSetLike<DT extends DateTime<Time> ? DateTimeLike : DateLike>;
+    [Symbol.iterator](): Iterator<DT, any, any>;
     private toOptions;
 }

package/dist/browser/rrule-set.js

@@ -1,41 +1,33 @@
 import { RRule } from './rrule';
 import { RRuleSet as Rust } from './lib';
-import { DateTime } from './datetime';
+import { DateTime, } from './datetime';
+import { DtStart } from './dtstart';
 export class RRuleSet {
-    constructor(optionsOrDtstart, tzid) {
-        if (optionsOrDtstart !== undefined &&
-            !(optionsOrDtstart instanceof DateTime) &&
-            'dtstart' in optionsOrDtstart) {
+    constructor(optionsOrDtstart) {
+        if ('dtstart' in optionsOrDtstart) {
             this.dtstart = optionsOrDtstart.dtstart;
-            this.tzid = optionsOrDtstart.tzid ?? 'UTC';
             this.rrules = optionsOrDtstart?.rrules ?? [];
             this.exrules = optionsOrDtstart?.exrules ?? [];
             this.exdates = optionsOrDtstart?.exdates ?? [];
             this.rdates = optionsOrDtstart?.rdates ?? [];
         }
-        else if (optionsOrDtstart instanceof DateTime) {
+        else {
             this.dtstart = optionsOrDtstart;
-            this.tzid = tzid ?? 'UTC';
             this.rrules = [];
             this.exrules = [];
             this.exdates = [];
             this.rdates = [];
         }
-        else {
-            throw new TypeError('Invalid arguments');
-        }
     }
     /**
      * Parses a string into an RRuleSet.
      */
     static parse(str) {
-        const rust = Rust.parse(str);
-        return this.fromRust(rust);
+        return this.fromRust(Rust.parse(str));
     }
     static fromPlain(plain) {
         return new RRuleSet({
-            dtstart: DateTime.fromPlain(plain.dtstart),
-            tzid: plain.tzid,
+            dtstart: DtStart.fromPlain(plain.dtstart),
             rrules: plain.rrules.map((rrule) => RRule.fromPlain(rrule)),
             exrules: plain.exrules.map((rrule) => RRule.fromPlain(rrule)),
             exdates: plain.exdates.map((datetime) => DateTime.fromPlain(datetime)),
@@ -47,8 +39,10 @@ export class RRuleSet {
      */
     static fromRust(rust) {
         const set = new RRuleSet({
-            dtstart: DateTime.fromNumeric(rust.dtstart),
-            tzid: rust.tzid ?? undefined,
+            dtstart: new DtStart({
+                datetime: DateTime.fromNumeric(rust.dtstart),
+                tzid: rust.tzid ?? undefined,
+            }),
             rrules: rust.rrules.map((rrule) => RRule.fromRust(rrule)),
             exrules: rust.exrules.map((rrule) => RRule.fromRust(rrule)),
             exdates: rust.exdates.map((datetime) => DateTime.fromNumeric(datetime)),
@@ -63,12 +57,6 @@ export class RRuleSet {
             dtstart: dtstart,
         });
     }
-    setTzid(tzid) {
-        return new RRuleSet({
-            ...this.toOptions(),
-            tzid: tzid,
-        });
-    }
     addRrule(rrule) {
         return new RRuleSet({
             ...this.toOptions(),
@@ -151,7 +139,7 @@ export class RRuleSet {
      * @internal
      */
     toRust() {
-        this.rust ??= new Rust(this.dtstart.toNumeric(), this.tzid, this.rrules.map((rrule) => rrule.toRust()), this.exrules.map((rrule) => rrule.toRust()), this.exdates.map((datetime) => datetime.toNumeric()), this.rdates.map((datetime) => datetime.toNumeric()));
+        this.rust ??= new Rust(this.dtstart.datetime.toNumeric(), this.dtstart.tzid, undefined, this.rrules.map((rrule) => rrule.toRust()), this.exrules.map((rrule) => rrule.toRust()), this.exdates.map((datetime) => datetime.toNumeric()), this.rdates.map((datetime) => datetime.toNumeric()));
         return this.rust;
     }
     toString() {
@@ -163,7 +151,6 @@ export class RRuleSet {
     toPlain() {
         return {
             dtstart: this.dtstart.toPlain(),
-            tzid: this.tzid,
             rrules: this.rrules.map((rrule) => rrule.toPlain()),
             exrules: this.exrules.map((rrule) => rrule.toPlain()),
             exdates: this.exdates.map((rrule) => rrule.toPlain()),
@@ -191,7 +178,6 @@ export class RRuleSet {
     toOptions() {
         return {
             dtstart: this.dtstart,
-            tzid: this.tzid,
             rrules: this.rrules,
             exrules: this.exrules,
             exdates: this.exdates,