iamcal 3.1.0 → 4.1.0

package/src/date.ts

@@ -1,10 +1,17 @@
 import * as patterns from './patterns'
 import { Property } from './property/Property'
+import { CalendarDuration } from './duration'
 
 export const ONE_SECOND_MS = 1000
 export const ONE_MINUTE_MS = 60 * ONE_SECOND_MS
 export const ONE_HOUR_MS = 60 * ONE_MINUTE_MS
 export const ONE_DAY_MS = 24 * ONE_HOUR_MS
+export const ONE_WEEK_MS = 7 * ONE_DAY_MS
+
+export const ONE_MINUTE_SECONDS = 60
+export const ONE_HOUR_SECONDS = 60 * ONE_MINUTE_SECONDS
+export const ONE_DAY_SECONDS = 24 * ONE_HOUR_SECONDS
+export const ONE_WEEK_SECONDS = 7 * ONE_DAY_SECONDS
 
 export interface CalendarDateOrTime {
     /**
@@ -24,7 +31,14 @@ export interface CalendarDateOrTime {
      * Check if this date represents a full day, as opposed to a date-time.
      * @returns `true` if this object is a {@link CalendarDate}.
      */
-    isFullDay(): boolean
+    isFullDay(): this is CalendarDate
+
+    /**
+     * Get a new time offset by a duration.
+     * @param duration The duration to offset the time by.
+     * @returns A new {@link CalendarDateOrTime} of the same type.
+     */
+    offset(duration: CalendarDuration): CalendarDateOrTime
 }
 
 /**
@@ -36,10 +50,10 @@ export class CalendarDate implements CalendarDateOrTime {
 
     constructor(date: Date | string | CalendarDateOrTime) {
         if (typeof date === 'object') {
-            if (Object.prototype.toString.call(date) === '[object Date]') {
-                this.date = date as Date
+            if (isDateObject(date)) {
+                this.date = date
             } else {
-                this.date = (date as CalendarDateOrTime).getDate()
+                this.date = (date).getDate()
             }
         } else {
             try {
@@ -64,22 +78,53 @@ export class CalendarDate implements CalendarDateOrTime {
         return new Date(this.date)
     }
 
-    isFullDay(): boolean {
+    isFullDay(): this is CalendarDate {
         return true
     }
+
+    /**
+     * Get a new date offset by a duration.
+     * @param duration The duration to offset the date by.
+     * @returns A new {@link CalendarDate} offset by the duration.
+     */
+    offset(duration: CalendarDuration): CalendarDate {
+        const offsetMs = duration.floor('D').inMilliseconds()
+        const ms = this.getDate().getTime()
+        const time = new Date(ms + offsetMs)
+        return new CalendarDate(time)
+    }
+
+    [Symbol.toPrimitive](hint: string): number | string | null {
+        if (hint === 'string') {
+            return this.getValue()
+        } else if (hint === 'number') {
+            return this.date.getTime()
+        }
+        return null
+    }
 }
 
 export class CalendarDateTime implements CalendarDateOrTime {
     private date: Date
+    private absolute: boolean
 
-    constructor(date: Date | string | CalendarDateOrTime) {
+    constructor(date: Date | string | CalendarDateOrTime, absolute?: boolean) {
         if (typeof date === 'object') {
-            if (Object.prototype.toString.call(date) === '[object Date]') {
-                this.date = date as Date
+            if (isDateObject(date)) {
+                this.date = date
+                this.absolute = false
             } else {
-                this.date = (date as CalendarDateOrTime).getDate()
+                this.date = date.getDate()
+                this.absolute = date.isFullDay() ? false : (date as CalendarDateTime).isAbsolute()
             }
         } else {
+            this.absolute = absolute ?? date.endsWith('Z')
+            if (date.endsWith('Z') && !this.absolute) {
+                date = date.substring(0, date.length - 1)
+            } else if (!date.endsWith('Z') && this.absolute) {
+                date += 'Z'
+            }
+
             try {
                 this.date = parseDateTimeString(date)
             } catch {
@@ -90,19 +135,81 @@ export class CalendarDateTime implements CalendarDateOrTime {
         if (!this.date || isNaN(this.date.getTime())) {
             throw new Error('Invalid date provided')
         }
+
+        if (absolute !== undefined) {
+            this.absolute = absolute
+        }
     }
 
     getValue(): string {
-        return toDateTimeString(this.date)
+        return this.absolute
+            ? toDateTimeStringUTC(this.date, this.date.getTimezoneOffset())
+            : toDateTimeString(this.date)
     }
 
     getDate(): Date {
         return new Date(this.date)
     }
 
-    isFullDay(): boolean {
+    isFullDay(): this is CalendarDate {
         return false
     }
+
+    /**
+     * Check if this datetime is absolute, i.e. if it is represented in UTC.
+     * @returns If the datetime is absolute.
+     */
+    isAbsolute(): boolean {
+        return this.absolute
+    }
+
+    /**
+     * Get a new time offset by a duration.
+     * @param duration The duration to offset the time by.
+     * @returns A new {@link CalendarDateTime} offset by the duration.
+     */
+    offset(duration: CalendarDuration): CalendarDateTime {
+        const offsetMs = duration.inMilliseconds()
+        const ms = this.getDate().getTime()
+        const time = new Date(ms + offsetMs)
+        return new CalendarDateTime(time)
+    }
+
+    [Symbol.toPrimitive](hint: string): number | string | null {
+        if (hint === 'string') {
+            return this.getValue()
+        } else if (hint === 'number') {
+            return this.date.getTime()
+        }
+        return null
+    }
+}
+
+/**
+ * Check if an object is a JavaScript `Date`.
+ * @param maybeDate The object to check.
+ * @returns `true` if the object is a `Date`, `false` otherwise.
+ */
+export function isDateObject(maybeDate: unknown): maybeDate is Date {
+    return Object.prototype.toString.call(maybeDate) === '[object Date]'
+}
+
+/**
+ * Check if an object is a `CalendarDateOrTime`.
+ * @param maybeDate The object to check.
+ * @returns `true` if the object is a `CalendarDateOrTime`, `false` otherwise.
+ */
+export function isCalendarDateOrTime(
+    maybeDate: unknown
+): maybeDate is CalendarDateOrTime {
+    return (
+        maybeDate != null &&
+        typeof maybeDate === "object" &&
+        typeof (maybeDate as CalendarDateOrTime).getValue === "function" &&
+        typeof (maybeDate as CalendarDateOrTime).getDate === "function" &&
+        typeof (maybeDate as CalendarDateOrTime).isFullDay === "function" &&
+        typeof (maybeDate as CalendarDateOrTime).offset === "function"
+    )
 }
 
 /**
@@ -370,10 +477,10 @@ export function convertDate(
     date: Date | CalendarDateOrTime,
     fullDay: boolean = false
 ): CalendarDateOrTime {
-    if (Object.prototype.toString.call(date) === '[object Date]') {
-        if (fullDay) return new CalendarDate(date as Date)
-        else return new CalendarDateTime(date as Date)
+    if (isDateObject(date)) {
+        if (fullDay) return new CalendarDate(date)
+        else return new CalendarDateTime(date)
     } else {
-        return date as CalendarDateOrTime
+        return date
     }
 }

package/src/duration.ts

@@ -0,0 +1,329 @@
+import {
+    CalendarDateOrTime,
+    isDateObject,
+    isCalendarDateOrTime,
+    ONE_DAY_MS,
+    ONE_DAY_SECONDS,
+    ONE_HOUR_SECONDS,
+    ONE_MINUTE_SECONDS,
+    ONE_SECOND_MS,
+    ONE_WEEK_SECONDS,
+} from './date'
+import { validateDuration } from './property'
+
+export type DurationUnit = 'W' | 'D' | 'H' | 'M' | 'S'
+
+/**
+ * Represents a DURATION value as defined by RFC5545.
+ */
+export class CalendarDuration {
+    weeks?: number
+    days?: number
+    hours?: number
+    minutes?: number
+    seconds?: number
+
+    constructor(duration: string | CalendarDuration) {
+        if (typeof duration === 'string') {
+            validateDuration(duration)
+
+            const negativeMultiplier = duration.startsWith('-') ? -1 : 1
+            const findParts = /(\d+)([WDHMS])/g
+            const parts = duration.matchAll(findParts)
+            for (const part of parts) {
+                const value = parseInt(part[1], 10)
+                const name = part[2] as DurationUnit
+                switch (name) {
+                    case 'W':
+                        this.weeks = value * negativeMultiplier
+                        break
+                    case 'D':
+                        this.days = value * negativeMultiplier
+                        break
+                    case 'H':
+                        this.hours = value * negativeMultiplier
+                        break
+                    case 'M':
+                        this.minutes = value * negativeMultiplier
+                        break
+                    case 'S':
+                        this.seconds = value * negativeMultiplier
+                        break
+                }
+            }
+        } else {
+            this.weeks = duration.weeks
+            this.days = duration.days
+            this.hours = duration.hours
+            this.minutes = duration.minutes
+            this.seconds = duration.seconds
+        }
+    }
+
+    /**
+     * Get the length of this duration object in seconds.
+     * @returns The total number of seconds represented by this duration.
+     */
+    inSeconds(): number {
+        return (
+            (this.weeks ?? 0) * ONE_WEEK_SECONDS +
+            (this.days ?? 0) * ONE_DAY_SECONDS +
+            (this.hours ?? 0) * ONE_HOUR_SECONDS +
+            (this.minutes ?? 0) * ONE_MINUTE_SECONDS +
+            (this.seconds ?? 0)
+        )
+    }
+
+    /**
+     * Get the length of this duration object in milliseconds.
+     *
+     * Note that this will always return whole seconds, as durations do not
+     * support milliseconds.
+     * @returns The total number of milliseconds represented by this duration.
+     */
+    inMilliseconds(): number {
+        return this.inSeconds() * ONE_SECOND_MS
+    }
+
+    /**
+     * Get the duration string that represents this duration.
+     * @returns A duration string in the format `P[n]W` for weeks, or `P[n]DT[n]H[n]M[n]S` for days, hours, minutes and seconds. Prefixed with a `-` if negative.
+     */
+    getValue(): string {
+        return formatDurationString(
+            this.weeks,
+            this.days,
+            this.hours,
+            this.minutes,
+            this.seconds
+        )
+    }
+
+    /**
+     * Get the floor the duration to the nearest of a given unit.
+     * @param unit The unit to floor to.
+     * @returns The duration with units smaller than `unit` removed.
+     * @example
+     * const duration = new CalendarDuration("1W2D5H30M")
+     * const days = duration.floor("D") // Floor to days
+     * console.log(days.getValue()) // "1W2D"
+     */
+    floor(unit: DurationUnit): CalendarDuration {
+        const result = new CalendarDuration(this)
+        /* eslint-disable no-fallthrough */
+        switch (unit) {
+            case 'W':
+                result.days = undefined
+            case 'D':
+                result.hours = undefined
+            case 'H':
+                result.minutes = undefined
+            case 'M':
+                result.seconds = undefined
+        }
+        /* eslint-enable no-fallthrough */
+        return result
+    }
+
+    /**
+     * Create a duration from a number of seconds.
+     * @param seconds How many seconds the duration should represent.
+     * @returns A {@link CalendarDuration} representing the specified number of seconds.
+     * @throws {Error} If seconds is NaN.
+     */
+    static fromSeconds(seconds: number): CalendarDuration {
+        return new CalendarDuration(secondsToDurationString(seconds))
+    }
+
+    /**
+     * Create a duration from a number of days.
+     * @param days How many days the duration should represent.
+     * @returns A {@link CalendarDuration} representing the specified number of days.
+     * @throws {Error} If days is NaN.
+     */
+    static fromDays(days: number): CalendarDuration {
+        return new CalendarDuration(daysToDurationString(days))
+    }
+
+    /**
+     * Create a duration from a number of weeks.
+     * @param weeks How many weeks the duration should represent.
+     * @returns A {@link CalendarDuration} representing the specified number of weeks.
+     * @throws {Error} If weeks is NaN.
+     */
+    static fromWeeks(weeks: number): CalendarDuration {
+        return new CalendarDuration(weeksToDurationString(weeks))
+    }
+
+    /**
+     * Creates a duration from the difference between two dates.
+     * @param start The start date or time.
+     * @param end The end date or time.
+     * @returns A {@link CalendarDuration} representing the difference between the two dates.
+     * @throws {Error} If the start date and end date have different types.
+     */
+    static fromDifference(
+        start: Date | CalendarDateOrTime,
+        end: Date | CalendarDateOrTime
+    ): CalendarDuration {
+        if (isDateObject(start)) {
+            // Date
+            if (isDateObject(end)) {
+                const differenceSeconds =
+                    (end.getTime() - start.getTime()) / ONE_SECOND_MS
+                return CalendarDuration.fromSeconds(differenceSeconds)
+            }
+        } else if (start.isFullDay()) {
+            // CalendarDate
+            if (isCalendarDateOrTime(end) && end.isFullDay()) {
+                const startMs = start.getDate().getTime()
+                const endMs = end.getDate().getTime()
+                const differenceDays = (endMs - startMs) / ONE_DAY_MS
+                return CalendarDuration.fromDays(differenceDays)
+            }
+        } else {
+            // CalendarDateTime
+            if (isCalendarDateOrTime(end) && !end.isFullDay()) {
+                const startMs = start.getDate().getTime()
+                const endMs = end.getDate().getTime()
+                const differenceSeconds = (endMs - startMs) / ONE_SECOND_MS
+                return CalendarDuration.fromSeconds(differenceSeconds)
+            }
+        }
+
+        throw new Error('Start and end dates must be of the same type')
+    }
+}
+
+/**
+ * Convert time units to a duration string.
+ *
+ * A duration is considered negative if any unit is less than 0.
+ * @param weeks How many weeks the duration should represent.
+ * @param days The days part of the duration.
+ * @param hours The hours part of the duration.
+ * @param minutes The minutes part of the duration.
+ * @param seconds The seconds part of the duration.
+ * @returns A string representing the duration in the format `P[n]W` or `P[n]DT[n]H[n]M[n]S` where values may be omitted if 0, prefixed with `-` if negative.
+ * @throws {Error} If weeks are combined with other values.
+ * @throws {Error} If any unit is NaN.
+ */
+export function formatDurationString(
+    weeks: number | undefined,
+    days: number | undefined,
+    hours: number | undefined,
+    minutes: number | undefined,
+    seconds: number | undefined,
+): string {
+    let prefix = ''
+    let durationString = prefix + 'P'
+    let hasTime = false
+    let isEmpty = true
+
+    const appendUnit = (time: number | undefined, unit: string) => {
+        if (time === undefined) return
+        if (isNaN(time)) {
+            throw new Error(`${unit} must not be NaN`)
+        }
+        if (time < 0) prefix = '-'
+        const absTime = Math.abs(Math.floor(time))
+        durationString += absTime + unit.charAt(0)
+        isEmpty = false
+    }
+    const appendTimeUnit = (time: number | undefined, unit: string) => {
+        if (time === undefined) return
+        if (!hasTime) {
+            durationString += 'T'
+            hasTime = true
+        }
+        appendUnit(time, unit)
+    }
+
+    // Add units
+    if (weeks !== undefined) {
+        if (days !== undefined ||
+            hours !== undefined ||
+            minutes !== undefined ||
+            seconds !== undefined) {
+            throw new Error('Cannot combine weeks with other units in duration string')
+        }
+
+        appendUnit(weeks, 'Weeks')
+    }
+    appendUnit(days, 'Days')
+    appendTimeUnit(hours, 'Hours')
+    if (minutes !== undefined) {
+        appendTimeUnit(minutes, 'Minutes')
+    } else if (hours !== undefined && seconds !== undefined) {
+        appendTimeUnit(0, 'Minutes')
+    }
+    appendTimeUnit(seconds, 'Seconds')
+
+    if (isEmpty) {
+        throw new Error('Duration string must not be empty')
+    }
+
+    return prefix + durationString
+}
+
+/**
+ * Convert a number of seconds to a duration string.
+ * @param seconds How many seconds the duration should represent.
+ * @returns A string representing the duration in the format `PT[n]H[n]M[n]S` where values may be omitted if 0, prefixed with `-` if negative.
+ * @throws {Error} If seconds is NaN.
+ */
+export function secondsToDurationString(seconds: number): string {
+    if (isNaN(seconds)) throw new Error('Seconds must not be NaN')
+    seconds = Math.floor(seconds)
+
+    const absSeconds = Math.abs(seconds)
+    const minutes = Math.floor(absSeconds / 60)
+    const hours = Math.floor(minutes / 60)
+    let secondsValue: number | undefined = seconds % 60
+    let minutesValue: number | undefined = minutes % 60
+    let hoursValue: number | undefined = hours
+
+    if (hoursValue === 0) hoursValue = undefined
+    if (minutesValue === 0) minutesValue = undefined
+    if (secondsValue === 0 && !(minutesValue === undefined && hoursValue === undefined)) secondsValue = undefined
+
+    return formatDurationString(
+        undefined,
+        undefined,
+        hoursValue,
+        minutesValue,
+        secondsValue,
+    )
+}
+
+/**
+ * Convert a number of days to a duration string.
+ * @param days How many days the duration should represent.
+ * @returns A string representing the duration in the format `P[n]D`, prefixed with `-` if negative.
+ * @throws {Error} If days is NaN.
+ */
+export function daysToDurationString(days: number): string {
+    return formatDurationString(
+        undefined,
+        days,
+        undefined,
+        undefined,
+        undefined
+    )
+}
+
+/**
+ * Convert a number of weeks to a duration string.
+ * @param weeks How many weeks the duration should represent.
+ * @returns A string representing the duration in the format `P[n]W`, prefixed with `-` if negative.
+ * @throws {Error} If weeks is NaN.
+ */
+export function weeksToDurationString(weeks: number): string {
+    return formatDurationString(
+        weeks,
+        undefined,
+        undefined,
+        undefined,
+        undefined
+    )
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './component'
 export * from './components'
 export * from './date'
+export * from './duration'
 export * from './io'
 export * from './parse'
 export * from './property'

package/src/property/Property.ts

@@ -1,4 +1,5 @@
-import { CalendarDateOrTime } from 'src/date'
+import { CalendarDateOrTime, CalendarDate, CalendarDateTime, isCalendarDateOrTime } from '../date'
+import { CalendarDuration } from '../duration'
 import {
     escapePropertyParameterValue,
     escapeTextPropertyValue,
@@ -16,7 +17,7 @@ import {
     RsvpExpectation,
 } from './parameter'
 import { validateCalendarUserAddress, validateContentType } from './validate'
-import { AllowedValueType, getDefaultValueType } from './valueType'
+import { AllowedValueType, KnownValueType, getDefaultValueType } from './valueType'
 
 /**
  * Represents a property of a calendar component as described by RFC 5545 in
@@ -55,13 +56,72 @@ export class Property {
     }
 
     static fromDate(name: string, value: CalendarDateOrTime): Property {
+        const valueType = value.isFullDay() ? 'DATE' : 'DATE-TIME'
+        let properties: { [k: string]: string | string[] } | undefined = undefined
+        if (getDefaultValueType(name) !== valueType) {
+            properties = { VALUE: valueType }
+        }
+
+        return new Property(
+            name,
+            value.getValue(),
+            properties,
+        )
+    }
+
+    static fromDuration(name: string, value: CalendarDuration): Property {
         return new Property(
             name,
             value.getValue(),
-            value.isFullDay() ? { VALUE: 'DATE' } : undefined
+            { VALUE: 'CALENDARDATE' },
         )
     }
 
+    /**
+     * Get the value of this property, converted into the appropriate class if possible.
+     * @returns The value as a string or appropriate class.
+     */
+    getValue(): string | CalendarDateOrTime | CalendarDuration {
+        const valueType = this.getValueType()
+        switch (valueType) {
+            case 'DATE':
+                return new CalendarDate(this.value)
+            case 'DATE-TIME':
+                return new CalendarDateTime(this.value)
+            case 'DURATION':
+                return new CalendarDuration(this.value)
+            default:
+                return this.value
+        }
+    }
+
+    /**
+     * Set the value of this property and change the value type if a class is used.
+     * @param value The new value as a string or class.
+     */
+    setValue(value: string | CalendarDateOrTime | CalendarDuration) {
+        const valueTypeBefore = this.getExplicitValueType()
+        if (typeof value === 'string') {
+            // Set string
+            this.value = value
+        } else if (isCalendarDateOrTime(value)) {
+            // Set date
+            this.value = value.getValue()
+            this.setValueType(value.isFullDay() ? 'DATE' : 'DATE-TIME')
+        } else {
+            // Set duration
+            this.value = value.getValue()
+            this.setValueType('DURATION')
+        }
+
+        // Remove value type if set to default, unless it was already set
+        const valueType = this.getExplicitValueType()
+        const defaultValueType = this.getDefaultValueType()
+        if (valueType === defaultValueType && valueType !== valueTypeBefore) {
+            this.removeValueType()
+        }
+    }
+
     setParameter(name: string, value: string | string[]) {
         this._parameters.set(
             name.toUpperCase(),
@@ -148,8 +208,23 @@ export class Property {
      * @returns The value type of this property.
      */
     getValueType(): AllowedValueType {
-        const assignedValueType = this.getParameter('VALUE')?.[0].toUpperCase()
-        return assignedValueType ?? getDefaultValueType(this.name)
+        return this.getExplicitValueType() ?? this.getDefaultValueType()
+    }
+
+    /**
+     * Get the value type of this property.
+     * @returns The value type of this property, or `undefined` if unset.
+     */
+    getExplicitValueType(): AllowedValueType | undefined {
+        return this.getParameter('VALUE')?.[0].toUpperCase()
+    }
+
+    /**
+     * Get the default value type for this property.
+     * @returns The default value type based on the name of this property.
+     */
+    getDefaultValueType(): KnownValueType {
+        return getDefaultValueType(this.name)
     }
 
     /**

package/src/property/validate.ts

@@ -85,7 +85,7 @@ export function validateDateTime(value: string) {
         parseDateTimeString(value)
     } catch {
         throw new PropertyValidationError(
-            `${value} does not match pattern for DATETIME`
+            `${value} does not match pattern for DATE-TIME`
         )
     }
 }