iamcal 2.0.0 → 2.1.0

package/src/components/CalendarEvent.ts

@@ -1,43 +1,81 @@
-import { Component } from "../component"
-import { parseDate, toDateString, toDateTimeString } from "../parse"
+import { KnownPropertyName, PropertyValidationError } from '../property'
+import { ComponentValidationError, Component } from '../component'
+import {
+    CalendarDateTime,
+    convertDate,
+    CalendarDateOrTime,
+    parseDateProperty,
+    toDateTimeString,
+} from '../date'
 
 /**
  * Represents a VEVENT component, representing an event in a calendar.
  */
 export class CalendarEvent extends Component {
-    name = 'VEVENT';
+    name = 'VEVENT'
 
-    constructor(uid: string, dtstamp: Date)
+    constructor(
+        uid: string,
+        dtstamp: CalendarDateTime | Date,
+        dtstart: CalendarDateOrTime | Date
+    )
     constructor(component: Component)
-    constructor(a: string | Component, b?: Date) {
-        var component: Component
-        if (b) {
+    constructor(
+        a: string | Component,
+        b?: CalendarDateTime | Date,
+        c?: CalendarDateOrTime | Date
+    ) {
+        let component: Component
+        if (a instanceof Component) {
+            component = a as Component
+            CalendarEvent.prototype.validate.call(component)
+        } else {
             const uid = a as string
-            const dtstamp = b as Date
+            const dtstamp = convertDate(b!, false)
+            const dtstart = convertDate(c!)
             component = new Component('VEVENT')
             component.setProperty('UID', uid)
-            component.setProperty('DTSTAMP', toDateTimeString(dtstamp))
-        } else {
-            component = a as Component
+            component.setProperty('DTSTAMP', dtstamp)
+            component.setProperty('DTSTART', dtstart)
         }
         super(component.name, component.properties, component.components)
     }
 
-    stamp(): Date {
-        return parseDate(this.getProperty('DTSTAMP')!)
+    serialize(): string {
+        if (!this.getEnd() && !this.duration()) {
+            throw new Error(
+                'Failed to serialize calendar event, end or duration must be set'
+            )
+        }
+        return super.serialize()
     }
 
-    setStamp(value: Date, fullDay: boolean = false): this {
-        if (fullDay) {
-            this.setProperty('DTSTAMP', toDateString(value))
-            this.setPropertyParams('DTSTAMP', ['VALUE=DATE'])
-        } else {
-            this.setProperty('DTSTAMP', toDateTimeString(value))
+    validate() {
+        if (this.name !== 'VEVENT')
+            throw new ComponentValidationError('Component name must be VEVENT')
+        const requiredProperties: KnownPropertyName[] = [
+            'UID',
+            'DTSTAMP',
+            'DTSTART',
+        ]
+        this.validateAllProperties(requiredProperties)
+    }
+
+    getStamp(): CalendarDateTime {
+        return parseDateProperty(
+            this.getProperty('DTSTAMP')!
+        ) as CalendarDateTime
+    }
+
+    setStamp(value: CalendarDateTime | Date): this {
+        const converted = convertDate(value, false)
+        if (converted.isFullDay()) {
+            throw new PropertyValidationError('DTSTAMP cannot be of type DATE')
         }
-        return this
+        return this.setProperty('DTSTAMP', converted)
     }
 
-    uid(): string {
+    getUid(): string {
         return this.getProperty('UID')!.value
     }
 
@@ -45,8 +83,8 @@ export class CalendarEvent extends Component {
         return this.setProperty('UID', value)
     }
 
-    summary(): string {
-        return this.getProperty('SUMMARY')!.value
+    getSummary(): string | undefined {
+        return this.getProperty('SUMMARY')?.value
     }
 
     setSummary(value: string): this {
@@ -57,8 +95,8 @@ export class CalendarEvent extends Component {
         this.removePropertiesWithName('SUMMARY')
     }
 
-    description(): string {
-        return this.getProperty('DESCRIPTION')!.value
+    getDescription(): string | undefined {
+        return this.getProperty('DESCRIPTION')?.value
     }
 
     setDescription(value: string): this {
@@ -69,7 +107,7 @@ export class CalendarEvent extends Component {
         this.removePropertiesWithName('DESCRIPTION')
     }
 
-    location(): string | undefined {
+    getLocation(): string | undefined {
         return this.getProperty('LOCATION')?.value
     }
 
@@ -82,57 +120,98 @@ export class CalendarEvent extends Component {
     }
 
     /**
-     * Get the start of the event.
-     * If set as a full day the time will be at the start of the day.
+     * Get the start date or time of the event.
+     * @returns The start date or time of the event as a {@link CalendarDateOrTime}.
      */
-    start(): Date {
-        return parseDate(this.getProperty('DTSTART')!)
-    }
-
-    /** Set the start of the event. */
-    setStart(value: Date, fullDay: boolean = false): this {
-        if (fullDay) {
-            this.setProperty('DTSTART', toDateString(value))
-            this.setPropertyParams('DTSTART', ['VALUE=DATE'])
-        } else {
-            this.setProperty('DTSTART', toDateTimeString(value))
-        }
-        return this
+    getStart(): CalendarDateOrTime {
+        return parseDateProperty(this.getProperty('DTSTART')!)
     }
 
-    removeStart() {
-        this.removePropertiesWithName('DTSTART')
+    /**
+     * Set the start date or time of the event.
+     * @param value The start date of the event as a {@link CalendarDateOrTime} or `Date`.
+     * @returns The CalendarEvent instance for chaining.
+     */
+    setStart(value: CalendarDateOrTime | Date): this {
+        return this.setProperty('DTSTART', convertDate(value))
     }
 
     /**
      * Get the non-inclusive end of the event.
-     * If set as a full day the time will be at the start of the day.
+     * @returns The end date of the event as a {@link CalendarDateOrTime} or `undefined` if not set.
      */
-    end(): Date {
-        return parseDate(this.getProperty('DTEND')!)
+    getEnd(): CalendarDateOrTime | undefined {
+        const property = this.getProperty('DTEND')
+        if (!property) return
+        return parseDateProperty(property)
     }
 
     /**
-     * Set the non-inclusive end of the event.
+     * Set the exclusive end of the event.
+     *
+     * Will remove 'duration' if present.
+     * @param value The end date of the event as a {@link CalendarDateOrTime} or `Date`.
+     * @returns The CalendarEvent instance for chaining.
+     * @throws If the end date is a full day date and the start date is a date-time, or vice versa.
      */
-    setEnd(value: Date, fullDay: boolean = false): this {
-        if (fullDay) {
-            this.setProperty('DTEND', toDateString(value))
-            this.setPropertyParams('DTEND', ['VALUE=DATE'])
-        } else {
-            this.setProperty('DTEND', toDateTimeString(value))
+    setEnd(value: CalendarDateOrTime | Date): this {
+        const date = convertDate(value)
+        const start = this.getStart()
+        if (date.isFullDay() !== start.isFullDay()) {
+            throw new Error(
+                `End must be same date type as start. Start is ${start.isFullDay() ? 'date' : 'datetime'} but new end value is ${date.isFullDay() ? 'date' : 'datetime'}`
+            )
         }
-        return this
+
+        this.removeDuration()
+        return this.setProperty('DTEND', date)
     }
 
+    /**
+     * Remove the end of the event.
+     *
+     * NOTE: An event must have either an end or a duration set.
+     */
     removeEnd() {
         this.removePropertiesWithName('DTEND')
     }
 
-    created(): Date | undefined {
+    /**
+     * Get the duration of the event as a string formatted according to the iCalendar specification.
+     * @returns The duration of the event, or `undefined` if not set.
+     */
+    getDuration(): string | undefined {
+        return this.getProperty('DURATION')?.value
+    }
+
+    /**
+     * Set the duration of the event.
+     *
+     * Will remove 'end' if present.
+     * @param value The duration of the event as a string in the format defined by RFC5545.
+     * @returns The CalendarEvent instance for chaining.
+     * @example
+     * // Set duration to 1 hour and 30 minutes.
+     * event.setDuration(`PT1H30M`)
+     */
+    setDuration(value: string): this {
+        this.removeEnd()
+        return this.setProperty('DURATION', value)
+    }
+
+    /**
+     * Remove the duration of the event.
+     *
+     * NOTE: An event must have either an end or a duration set.
+     */
+    removeDuration() {
+        this.removePropertiesWithName('DURATION')
+    }
+
+    getCreated(): CalendarDateOrTime | undefined {
         const property = this.getProperty('CREATED')
         if (!property) return
-        return parseDate(property)
+        return parseDateProperty(property)
     }
 
     setCreated(value: Date): this {
@@ -143,24 +222,49 @@ export class CalendarEvent extends Component {
         this.removePropertiesWithName('CREATED')
     }
 
-    geo(): [number, number] | undefined {
+    getGeographicPosition(): [number, number] | undefined {
         const text = this.getProperty('GEO')?.value
         if (!text) return
-        const pattern = /^[+-]?\d+(\.\d+)?,[+-]?\d+(\.\d+)?$/
-        if (!pattern.test(text)) throw new Error(`Failed to parse GEO property: ${text}`)
+        const validGeoPattern = /^[+-]?\d+(\.\d+)?;[+-]?\d+(\.\d+)?$/
+        if (!validGeoPattern.test(text))
+            throw new Error(`Failed to parse GEO property: ${text}`)
         const [longitude, latitude] = text.split(',')
         return [parseFloat(longitude), parseFloat(latitude)]
     }
 
-    setGeo(latitude: number, longitude: number): this {
-        const text = `${latitude},${longitude}`
-        return this
+    setGeographicPosition(latitude: number, longitude: number): this {
+        const text = `${latitude};${longitude}`
+        return this.setProperty('GEO', text)
     }
 
-    removeGeo() {
+    removeGeographicLocation() {
         this.removePropertiesWithName('GEO')
     }
-}
 
-const event = new CalendarEvent('abc', new Date())
-event.getPropertyParams('DTEND')?.includes('VALUE=DATE')
+    /* eslint-disable */
+
+    /** @deprecated use {@link getStamp} instead */
+    stamp = this.getStamp
+    /** @deprecated use {@link getUid} instead */
+    uid = this.getUid
+    /** @deprecated use {@link getSummary} instead */
+    summary = this.getSummary
+    /** @deprecated use {@link getDescription} instead */
+    description = this.getDescription
+    /** @deprecated use {@link getLocation} instead */
+    location = this.getLocation
+    /** @deprecated use {@link getStart} instead */
+    start = this.getStart
+    /** @deprecated use {@link getEnd} instead */
+    end = this.getEnd
+    /** @deprecated use {@link getDuration} instead */
+    duration = this.getDuration
+    /** @deprecated use {@link getCreated} instead */
+    created = this.getCreated
+    /** @deprecated use {@link getGeographicPosition} instead */
+    geo = this.getGeographicPosition
+    /** @deprecated use {@link setGeographicPosition} instead */
+    setGeo = this.setGeographicPosition
+    /** @deprecated use {@link removeGeographicLocation} instead */
+    removeGeo = this.removeGeographicLocation
+}

package/src/components/TimeZone.ts

@@ -1,16 +1,21 @@
-import { Component } from '../component'
-import { parseDate, toDateString, toDateTimeString } from '../parse'
+import { Component, ComponentValidationError } from '../component'
+import { CalendarDateOrTime, parseDateProperty } from '../date'
+import { KnownPropertyName } from '../property'
+import { TimeZoneOffset } from './TimeZoneOffset'
 
 /**
  * Represents a VTIMEZONE component, containing time zone definitions.
  */
 export class TimeZone extends Component {
+    name = 'VTIMEZONE'
+
     constructor(id: string)
     constructor(component: Component)
     constructor(a: string | Component) {
-        var component: Component
+        let component: Component
         if (a instanceof Component) {
             component = a as Component
+            TimeZone.prototype.validate.call(component)
         } else {
             const tzid = a as string
             component = new Component('VTIMEZONE')
@@ -19,7 +24,14 @@ export class TimeZone extends Component {
         super(component.name, component.properties, component.components)
     }
 
-    id(): string {
+    validate() {
+        if (this.name !== 'VTIMEZONE')
+            throw new ComponentValidationError('Component name must be VEVENT')
+        const requiredProperties: KnownPropertyName[] = ['TZID']
+        this.validateAllProperties(requiredProperties)
+    }
+
+    getId(): string {
         return this.getProperty('TZID')!.value
     }
 
@@ -27,21 +39,21 @@ export class TimeZone extends Component {
         return this.setProperty('TZID', value)
     }
 
-    lastMod(): Date | undefined {
-        const text = this.getProperty('LAST-MOD')
+    getLastModified(): CalendarDateOrTime | undefined {
+        const text = this.getProperty('LAST-MODIFIED')
         if (!text) return
-        return parseDate(text)
+        return parseDateProperty(text)
     }
 
-    setLastMod(value: Date): this {
-        return this.setProperty('LAST-MOD', value.toISOString())
+    setLastModified(value: Date): this {
+        return this.setProperty('LAST-MODIFIED', value.toISOString())
     }
 
-    removeLastMod() {
+    removeLastModified() {
         this.removePropertiesWithName('LAST-MOD')
     }
 
-    url(): string | undefined {
+    getUrl(): string | undefined {
         return this.getProperty('TZURL')?.value
     }
 
@@ -53,110 +65,88 @@ export class TimeZone extends Component {
         this.removePropertiesWithName('TZURL')
     }
 
-    /** Get all time offsets. */
-    offsets(): TimeZoneOffset[] {
+    /**
+     * Get all time offsets.
+     * @returns An array of time zone offsets defined in this time zone.
+     */
+    getOffsets(): TimeZoneOffset[] {
         const offsets: TimeZoneOffset[] = []
         this.components.forEach(component => {
-            if (component.name === 'STANDARD' || component.name === 'DAYLIGHT') {
+            if (
+                component.name === 'STANDARD' ||
+                component.name === 'DAYLIGHT'
+            ) {
                 offsets.push(new TimeZoneOffset(component))
             }
         })
         return offsets
     }
 
-    /** Get standard/winter time offsets. */
-    standardOffsets(): TimeZoneOffset[] {
-        return this.getComponents('STANDARD').map(c => new TimeZoneOffset(c))
-    }
-
-    /** Get daylight savings time offsets. */
-    daylightOffsets(): TimeZoneOffset[] {
-        return this.getComponents('DAYLIGHT').map(c => new TimeZoneOffset(c))
-    }
-}
-
-export type OffsetType = 'DAYLIGHT' | 'STANDARD'
-type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
-export type Offset = `${'-' | '+'}${Digit}${Digit}${Digit}${Digit}`
-/** Represents a STANDARD or DAYLIGHT component, defining a time zone offset. */
-class TimeZoneOffset extends Component {
     /**
-     *
-     * @param type If this is a STANDARD or DAYLIGHT component.
-     * @param start From when this offset is active.
-     * @param offsetFrom The offset that is in use prior to this time zone observance.
-     * @param offsetTo The offset that is in use during this time zone observance.
+     * Get standard/winter time offsets.
+     * @returns An array of time zone offsets defined in this time zone that are of type STANDARD.
      */
-    constructor(type: OffsetType, start: Date, offsetFrom: Offset, offsetTo: Offset)
-    constructor(component: Component)
-    constructor(a: OffsetType | Component, b?: Date, c?: Offset, d?: Offset) {
-        var component: Component
-        if (a instanceof Component) {
-            component = a as Component
-        } else {
-            const name = a as OffsetType
-            const start = b as Date
-            const offsetFrom = c as Offset
-            const offsetTo = d as Offset
-            component = new Component(name)
-            component.setProperty('DTSTART', toDateTimeString(start))
-            component.setProperty('TZOFFSETFROM', offsetFrom)
-            component.setProperty('TZOFFSETTO', offsetTo)
-        }
-        super(component.name, component.properties, component.components)
-    }
-
-    start(): Date {
-        return parseDate(this.getProperty('DTSTART')!)
-    }
-
-    setStart(value: Date, fullDay: boolean = false): this {
-        if (fullDay) {
-            this.setProperty('DTSTART', toDateString(value))
-            this.setPropertyParams('DTSTART', ['VALUE=DATE'])
-        } else {
-            this.setProperty('DTSTART', toDateTimeString(value))
-        }
-        return this
+    getStandardOffsets(): TimeZoneOffset[] {
+        return this.getComponentsWithName('STANDARD').map(
+            c => new TimeZoneOffset(c)
+        )
     }
 
-    offsetFrom(): Offset {
-        return this.getProperty('TZOFFSETFROM')!.value as Offset
+    /**
+     * Get daylight savings time offsets.
+     * @returns An array of time zone offsets defined in this time zone that are of type DAYLIGHT.
+     */
+    getDaylightOffsets(): TimeZoneOffset[] {
+        return this.getComponentsWithName('DAYLIGHT').map(
+            c => new TimeZoneOffset(c)
+        )
     }
 
-    setOffsetFrom(value: Offset): this {
-        return this.setProperty('TZOFFSETFROM', value)
-    }
+    /* eslint-disable */
 
-    offsetTo(): Offset {
-        return this.getProperty('TZOFFSETTO')!.value as Offset
-    }
+    /**
+     * @deprecated Use {@link getId} instead.
+     */
+    id = this.getId
 
-    setOffsetTo(value: Offset): this {
-        return this.setProperty('TZOFFSETTO', value)
-    }
+    /**
+     * @deprecated Use {@link getLastModified} instead.
+     */
+    lastMod = this.getLastModified
 
-    comment(): string | undefined {
-        return this.getProperty('COMMENT')?.value
-    }
+    /**
+     * @deprecated Use {@link setLastModified} instead.
+     */
+    setLastMod = this.setLastModified
 
-    setComment(value: string): this {
-        return this.setProperty('COMMENT', value)
-    }
+    /**
+     * @deprecated Use {@link removeLastModified} instead.
+     */
+    removeLastMod = this.removeLastModified
 
-    removeComment() {
-        this.removePropertiesWithName('COMMENT')
-    }
+    /**
+     * @deprecated Use {@link getUrl} instead.
+     */
+    url = this.getUrl
 
-    timeZoneName(): string | undefined {
-        return this.getProperty('TZNAME')?.value
-    }
+    /**
+     * Get all time offsets.
+     * @returns An array of time zone offsets defined in this time zone.
+     * @deprecated Use {@link getOffsets} instead.
+     */
+    offsets = this.getOffsets
 
-    setTimeZoneName(value: string): this {
-        return this.setProperty('TZNAME', value)
-    }
+    /**
+     * Get standard/winter time offsets.
+     * @returns An array of time zone offsets defined in this time zone that are of type STANDARD.
+     * @deprecated Use {@link getStandardOffsets} instead.
+     */
+    standardOffsets = this.getStandardOffsets
 
-    removeTimeZoneName() {
-        this.removePropertiesWithName('TZNAME')
-    }
-}
+    /**
+     * Get daylight savings time offsets.
+     * @returns An array of time zone offsets defined in this time zone that are of type DAYLIGHT.
+     * @deprecated Use {@link getDaylightOffsets} instead.
+     */
+    daylightOffsets = this.getDaylightOffsets
+}