rrule-rust
Version:
RRule implementation for browsers and Node.js written in Rust
364 lines (363 loc) • 13.2 kB
TypeScript
/**
* 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.
*
* 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> {
readonly year: number;
readonly month: number;
readonly day: number;
readonly time: T;
private offset?;
private constructor();
/**
* 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 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 UTC DateTime object from a JavaScript Date object.
*
* The resulting DateTime will have `utc` set to `true` and will represent
* the same moment in time as the input Date object.
*
* @param date - A JavaScript Date object
* @returns A DateTime instance with UTC time
*
* @example
* ```typescript
* const jsDate = new Date('2024-01-15T14:30:00.000Z');
* const datetime = DateTime.fromDate(jsDate);
* console.log(datetime.year); // 2024
* console.log(datetime.month); // 1
* console.log(datetime.day); // 15
* console.log(datetime.time.hour); // 14
* console.log(datetime.time.minute); // 30
* console.log(datetime.time.second); // 0
* console.log(datetime.time.utc); // true
* ```
*/
static fromDate(date: Date): DateTime<Time>;
/**
* Creates a new UTC DateTime object from a Unix timestamp in milliseconds.
*
* The resulting DateTime will have `utc` set to `true` and will represent
* the moment in time corresponding to the given timestamp.
*
* @param timestamp - Unix timestamp in milliseconds since January 1, 1970 00:00:00 UTC
* @returns A DateTime instance with UTC time
*
* @example
* ```typescript
* const timestamp = Date.UTC(2024, 0, 15, 14, 30, 0); // 1705329000000
* const datetime = DateTime.fromTimestamp(timestamp);
* console.log(datetime.year); // 2024
* console.log(datetime.month); // 1
* console.log(datetime.day); // 15
* console.log(datetime.time.hour); // 14
* console.log(datetime.time.minute); // 30
* console.log(datetime.time.second); // 0
* console.log(datetime.time.utc); // true
* ```
*/
static fromTimestamp(timestamp: number): DateTime<Time>;
/**
* 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: OptionalUtc<DateTimeLike>): DateTime<Time>;
static fromPlain(plain: StripUtc<DateTimeLike>): DateTime<Time>;
static fromPlain(plain: DateLike): DateTime<undefined>;
/**
* 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 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(options: ToPlainDateTimeOptions & {
stripUtc: false;
}): T extends Time ? DateTimeLike : DateLike;
toPlain(options: ToPlainDateTimeOptions & {
stripUtc: true;
}): T extends Time ? StripUtc<DateTimeLike> : DateLike;
toPlain(): T extends Time ? DateTimeLike : DateLike;
/**
* 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;
}