iamcal 1.1.1 → 2.1.0

package/src/component.ts

@@ -0,0 +1,248 @@
+import { CalendarDateOrTime } from './date'
+import {
+    AllowedPropertyName,
+    KnownPropertyName,
+    MissingPropertyError,
+    Property,
+    PropertyValidationError,
+    validateProperty,
+} from './property'
+
+/** Represents an error which occurs while validating a calendar component. */
+export class ComponentValidationError extends Error {
+    constructor(message: string) {
+        super(message)
+        this.name = 'ComponentValidationError'
+    }
+}
+
+// Max line length as defined by RFC 5545 3.1.
+const MAX_LINE_LENGTH = 75
+
+export class Component {
+    name: string
+    properties: Property[]
+    components: Component[]
+
+    constructor(
+        name: string,
+        properties?: Property[],
+        components?: Component[]
+    ) {
+        this.name = name
+        if (properties) {
+            this.properties = properties
+        } else {
+            this.properties = []
+        }
+        if (components) {
+            this.components = components
+        } else {
+            this.components = []
+        }
+    }
+
+    serialize(): string {
+        // Create lines
+        const lines = [`BEGIN:${this.name}`]
+
+        for (const property of this.properties) {
+            let line =
+                property['name'] + //
+                property.params.map(p => ';' + p).join('') +
+                ':' +
+                property['value']
+
+            // Wrap lines
+            while (line.length > MAX_LINE_LENGTH) {
+                lines.push(line.substring(0, MAX_LINE_LENGTH))
+                line = ' ' + line.substring(MAX_LINE_LENGTH)
+            }
+            lines.push(line)
+        }
+
+        for (const component of this.components) {
+            lines.push(component.serialize())
+        }
+
+        lines.push(`END:${this.name}`)
+
+        // Join lines
+        const serialized = lines.join('\n')
+
+        return serialized
+    }
+
+    getProperty(name: string): Property | null {
+        for (const property of this.properties) {
+            if (property.name === name) {
+                return property
+            }
+        }
+        return null
+    }
+
+    setProperty(name: string, value: string | CalendarDateOrTime): this {
+        for (const property of this.properties) {
+            if (property.name === name) {
+                if (typeof value === 'string') {
+                    property.value = value
+                } else {
+                    const prop = value.toProperty(name)
+                    property.params = prop.params
+                    property.value = prop.value
+                }
+                return this
+            }
+        }
+        this.properties.push(
+            typeof value === 'string'
+                ? {
+                      name: name,
+                      params: [],
+                      value: value,
+                  }
+                : value.toProperty(name)
+        )
+        return this
+    }
+
+    hasProperty(name: string, value?: string): boolean {
+        for (const property of this.properties) {
+            if (
+                property.name === name &&
+                (value === undefined || property.value === value)
+            ) {
+                return true
+            }
+        }
+        return false
+    }
+
+    removePropertiesWithName(name: string) {
+        const index = this.properties.findIndex(p => p.name === name)
+        if (index === -1) return
+        // Remove property at index
+        this.properties.splice(index, 1)
+    }
+
+    getPropertyParams(name: string): string[] | null {
+        for (const property of this.properties) {
+            if (property.name === name) {
+                return property.params
+            }
+        }
+        return null
+    }
+
+    setPropertyParams(name: string, params: string[]): this {
+        for (const property of this.properties) {
+            if (property.name === name) {
+                property.params = params
+            }
+        }
+        return this
+    }
+
+    addComponent(component: Component): this {
+        this.components.push(component)
+        return this
+    }
+
+    addComponents(components: Component[]): this {
+        this.components.push(...components)
+        return this
+    }
+
+    /**
+     * Remove a component from this component.
+     * @param component The component to remove.
+     * @returns `true` if the component was removed. `false` if the component was not present.
+     */
+    removeComponent(component: Component): boolean {
+        const index = this.components.indexOf(component)
+        if (index === -1) return false
+
+        // Remove element at index from list
+        this.components.splice(index, 1)
+
+        return true
+    }
+
+    getComponentsWithName(name: string): Component[] {
+        const components: Component[] = []
+
+        for (const component of this.components) {
+            if (component.name === name) {
+                components.push(component)
+            }
+        }
+
+        return components
+    }
+
+    /**
+     * Validate the component according to the rules of the iCalendar
+     * specification.
+     *
+     * This method should be overridden by subclasses to
+     * implement specific validation logic. The methods
+     * {@link validateRequiredProperty} and {@link validateOptionalProperty} may
+     * help with this.
+     * @throws {ComponentValidationError} If the component is invalid.
+     */
+    validate(): void {}
+
+    /**
+     * Validate that a property exists and is valid using {@link validateProperty}.
+     * @param propertyName The name of the property to validate.
+     * @throws {MissingPropertyError} If the property doesn't exist on this component.
+     * @throws {PropertyValidationError} If the property exists but is invalid.
+     */
+    validateRequiredProperty(propertyName: AllowedPropertyName) {
+        const property = this.getProperty(propertyName)
+        if (property == null)
+            throw new MissingPropertyError(
+                `Missing required property ${propertyName}`
+            )
+        validateProperty(property)
+    }
+
+    /**
+     * Validate that a property is valid using {@link validateProperty} if it exists.
+     * @param propertyName The name of the property to validate.
+     * @throws {PropertyValidationError} If the property exists and is invalid.
+     */
+    validateOptionalProperty(propertyName: AllowedPropertyName) {
+        const property = this.getProperty(propertyName)
+        if (property != null) validateProperty(property)
+    }
+
+    /**
+     * Validate all properties on this component.
+     *
+     * If a property is in `requiredProperties` it is
+     * validated with {@link validateRequiredProperty}, otherwise it is
+     * validated with {@link validateOptionalProperty}.
+     * @param requiredProperties A list of property names which are required on this component.
+     */
+    validateAllProperties(requiredProperties?: AllowedPropertyName[]) {
+        requiredProperties?.forEach(propertyName => {
+            if (!this.hasProperty(propertyName)) {
+                throw new MissingPropertyError(
+                    `Missing required property ${propertyName}`
+                )
+            }
+        })
+
+        this.properties.forEach(property => {
+            if (
+                requiredProperties?.includes(property.name as KnownPropertyName)
+            ) {
+                this.validateRequiredProperty(property.name)
+            } else {
+                this.validateOptionalProperty(property.name)
+            }
+        })
+    }
+}

package/src/components/Calendar.ts

@@ -0,0 +1,162 @@
+import { KnownPropertyName } from '../property'
+import { Component, ComponentValidationError } from '../component'
+import { CalendarEvent } from './CalendarEvent'
+
+/**
+ * Represents a VCALENDAR component, the root component of an iCalendar file.
+ */
+export class Calendar extends Component {
+    name = 'VCALENDAR'
+
+    /**
+     * @param prodid A unique identifier of the program creating the calendar.
+     * @example
+     * new Calendar('-//Google Inc//Google Calendar 70.9054//EN')
+     */
+    constructor(prodid: string)
+
+    /**
+     * @param prodid A unique identifier of the program creating the calendar.
+     * @param version The version of the iCalendar specification that this calendar uses.
+     * @example
+     * new Calendar('-//Google Inc//Google Calendar 70.9054//EN')
+     */
+    constructor(prodid: string, version: string)
+
+    /**
+     * @param component A VCALENDAR component.
+     */
+    constructor(component: Component)
+    constructor(a?: string | Component, b?: string) {
+        let component: Component
+        if (a instanceof Component) {
+            component = a as Component
+            Calendar.prototype.validate.call(component)
+        } else {
+            const prodid = a as string
+            const version = (b as string) ?? '2.0'
+            component = new Component('VCALENDAR')
+            component.setProperty('PRODID', prodid)
+            component.setProperty('VERSION', version)
+        }
+        super(component.name, component.properties, component.components)
+    }
+
+    validate() {
+        if (this.name !== 'VCALENDAR')
+            throw new ComponentValidationError(
+                'Component name must be VCALENDAR'
+            )
+        const requiredProperties: KnownPropertyName[] = ['PRODID', 'VERSION']
+        this.validateAllProperties(requiredProperties)
+    }
+
+    getEvents(): CalendarEvent[] {
+        return this.getComponentsWithName('VEVENT').map(
+            c => new CalendarEvent(c)
+        )
+    }
+
+    removeEvent(event: CalendarEvent): boolean
+    removeEvent(uid: string): boolean
+    removeEvent(a: CalendarEvent | string): boolean {
+        if (a instanceof CalendarEvent) {
+            const event = a as CalendarEvent
+            return this.removeComponent(event)
+        } else {
+            const uid = a as string
+            for (const event of this.getEvents()) {
+                if (event.getUid() !== uid) continue
+                return this.removeComponent(event)
+            }
+        }
+        return false
+    }
+
+    getProductId(): string {
+        return this.getProperty('PRODID')!.value
+    }
+
+    setProductId(value: string): this {
+        return this.setProperty('PRODID', value)
+    }
+
+    getVersion(): string {
+        return this.getProperty('VERSION')!.value
+    }
+
+    setVersion(value: string): this {
+        return this.setProperty('VERSION', value)
+    }
+
+    getCalendarScale(): string | undefined {
+        return this.getProperty('CALSCALE')?.value
+    }
+
+    setCalendarScale(value: string): this {
+        return this.setProperty('CALSCALE', value)
+    }
+
+    removeCalendarScale() {
+        this.removePropertiesWithName('CALSCALE')
+    }
+
+    getMethod(): string | undefined {
+        return this.getProperty('METHOD')?.value
+    }
+
+    setMethod(value: string): this {
+        return this.setProperty('METHOD', value)
+    }
+
+    removeMethod() {
+        this.removePropertiesWithName('METHOD')
+    }
+
+    getCalendarName(): string | undefined {
+        return this.getProperty('X-WR-CALNAME')?.value
+    }
+
+    setCalendarName(value: string): this {
+        return this.setProperty('X-WR-CALNAME', value)
+    }
+
+    removeCalendarName() {
+        this.removePropertiesWithName('X-WR-CALNAME')
+    }
+
+    getCalendarDescription(): string | undefined {
+        return this.getProperty('X-WR-CALDESC')?.value
+    }
+
+    setCalendarDescription(value: string): this {
+        return this.setProperty('X-WR-CALDESC', value)
+    }
+
+    removeCalendarDescription() {
+        this.removePropertiesWithName('X-WR-CALDESC')
+    }
+
+    /* eslint-disable */
+
+    /** @deprecated use {@link getEvents} instead */
+    events = this.getEvents
+    /** @deprecated use {@link getProductId} instead */
+    prodId = this.getProductId
+    /** @deprecated use {@link setProductId} instead */
+    setProdId = this.setProductId
+    /** @deprecated use {@link getVersion} instead */
+    version = this.getVersion
+    /** @deprecated use {@link getCalendarScale} instead */
+    calScale = this.getCalendarScale
+    /** @deprecated use {@link setCalendarScale} instead */
+    setCalScale = this.setCalendarScale
+    /** @deprecated use {@link removeCalendarScale} instead */
+    removeCalScale = this.removeCalendarScale
+    /** @deprecated use {@link getMethod} instead */
+    method = this.getMethod
+    /** @deprecated use {@link getCalendarName} instead */
+    calendarName = this.getCalendarName
+    /** @deprecated use {@link getCalendarDescription} instead */
+    calendarDescription = this.getCalendarDescription
+}

package/src/components/CalendarEvent.ts

@@ -0,0 +1,270 @@
+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'
+
+    constructor(
+        uid: string,
+        dtstamp: CalendarDateTime | Date,
+        dtstart: CalendarDateOrTime | Date
+    )
+    constructor(component: Component)
+    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 = convertDate(b!, false)
+            const dtstart = convertDate(c!)
+            component = new Component('VEVENT')
+            component.setProperty('UID', uid)
+            component.setProperty('DTSTAMP', dtstamp)
+            component.setProperty('DTSTART', dtstart)
+        }
+        super(component.name, component.properties, component.components)
+    }
+
+    serialize(): string {
+        if (!this.getEnd() && !this.duration()) {
+            throw new Error(
+                'Failed to serialize calendar event, end or duration must be set'
+            )
+        }
+        return super.serialize()
+    }
+
+    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.setProperty('DTSTAMP', converted)
+    }
+
+    getUid(): string {
+        return this.getProperty('UID')!.value
+    }
+
+    setUid(value: string): this {
+        return this.setProperty('UID', value)
+    }
+
+    getSummary(): string | undefined {
+        return this.getProperty('SUMMARY')?.value
+    }
+
+    setSummary(value: string): this {
+        return this.setProperty('SUMMARY', value)
+    }
+
+    removeSummary() {
+        this.removePropertiesWithName('SUMMARY')
+    }
+
+    getDescription(): string | undefined {
+        return this.getProperty('DESCRIPTION')?.value
+    }
+
+    setDescription(value: string): this {
+        return this.setProperty('DESCRIPTION', value)
+    }
+
+    removeDescription() {
+        this.removePropertiesWithName('DESCRIPTION')
+    }
+
+    getLocation(): string | undefined {
+        return this.getProperty('LOCATION')?.value
+    }
+
+    setLocation(value: string): this {
+        return this.setProperty('LOCATION', value)
+    }
+
+    removeLocation() {
+        this.removePropertiesWithName('LOCATION')
+    }
+
+    /**
+     * Get the start date or time of the event.
+     * @returns The start date or time of the event as a {@link CalendarDateOrTime}.
+     */
+    getStart(): CalendarDateOrTime {
+        return parseDateProperty(this.getProperty('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.
+     * @returns The end date of the event as a {@link CalendarDateOrTime} or `undefined` if not set.
+     */
+    getEnd(): CalendarDateOrTime | undefined {
+        const property = this.getProperty('DTEND')
+        if (!property) return
+        return parseDateProperty(property)
+    }
+
+    /**
+     * 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: 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'}`
+            )
+        }
+
+        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')
+    }
+
+    /**
+     * 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 parseDateProperty(property)
+    }
+
+    setCreated(value: Date): this {
+        return this.setProperty('CREATED', toDateTimeString(value))
+    }
+
+    removeCreated() {
+        this.removePropertiesWithName('CREATED')
+    }
+
+    getGeographicPosition(): [number, number] | undefined {
+        const text = this.getProperty('GEO')?.value
+        if (!text) return
+        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)]
+    }
+
+    setGeographicPosition(latitude: number, longitude: number): this {
+        const text = `${latitude};${longitude}`
+        return this.setProperty('GEO', text)
+    }
+
+    removeGeographicLocation() {
+        this.removePropertiesWithName('GEO')
+    }
+
+    /* 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
+}