iamcal 2.0.0 → 2.1.0

package/src/component.ts

@@ -1,28 +1,44 @@
+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 interface Property {
-    name: string
-    params: string[]
-    value: string
-}
-
 export class Component {
     name: string
     properties: Property[]
     components: Component[]
 
-    constructor(name: string, properties?: Property[], components?: Component[]) {
+    constructor(
+        name: string,
+        properties?: Property[],
+        components?: Component[]
+    ) {
         this.name = name
         if (properties) {
             this.properties = properties
         } else {
-            this.properties = new Array()
+            this.properties = []
         }
         if (components) {
             this.components = components
         } else {
-            this.components = new Array()
+            this.components = []
         }
     }
 
@@ -30,7 +46,7 @@ export class Component {
         // Create lines
         const lines = [`BEGIN:${this.name}`]
 
-        for (let property of this.properties) {
+        for (const property of this.properties) {
             let line =
                 property['name'] + //
                 property.params.map(p => ';' + p).join('') +
@@ -45,7 +61,7 @@ export class Component {
             lines.push(line)
         }
 
-        for (let component of this.components) {
+        for (const component of this.components) {
             lines.push(component.serialize())
         }
 
@@ -66,24 +82,46 @@ export class Component {
         return null
     }
 
-    setProperty(name: string, value: string): this {
+    setProperty(name: string, value: string | CalendarDateOrTime): this {
         for (const property of this.properties) {
             if (property.name === name) {
-                property.value = value
+                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({
-            name: name,
-            params: [],
-            value: value,
-        })
+        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 this
+        if (index === -1) return
         // Remove property at index
         this.properties.splice(index, 1)
     }
@@ -111,9 +149,15 @@ export class Component {
         return this
     }
 
+    addComponents(components: Component[]): this {
+        this.components.push(...components)
+        return this
+    }
+
     /**
-     * Remove a component from this component
-     * @returns `true` if the component was removed. `false` if the component was not present
+     * 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)
@@ -125,10 +169,10 @@ export class Component {
         return true
     }
 
-    getComponents(name: string): Component[] {
+    getComponentsWithName(name: string): Component[] {
         const components: Component[] = []
 
-        for (let component of this.components) {
+        for (const component of this.components) {
             if (component.name === name) {
                 components.push(component)
             }
@@ -136,4 +180,69 @@ export class 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

@@ -1,33 +1,37 @@
-import { Component } from '../component'
+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';
+    name = 'VCALENDAR'
 
     /**
      * @param prodid A unique identifier of the program creating the calendar.
-     *
-     * Example: `-//Google Inc//Google Calendar 70.9054//EN`
+     * @example
+     * new Calendar('-//Google Inc//Google Calendar 70.9054//EN')
      */
     constructor(prodid: string)
+
     /**
      * @param prodid A unique identifier of the program creating the calendar.
-     *
-     * Example: `-//Google Inc//Google Calendar 70.9054//EN`
      * @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) {
-        var component: Component
+        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'
@@ -38,8 +42,19 @@ export class Calendar extends Component {
         super(component.name, component.properties, component.components)
     }
 
-    events(): CalendarEvent[] {
-        return this.getComponents('VEVENT').map(c => new CalendarEvent(c))
+    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
@@ -50,23 +65,23 @@ export class Calendar extends Component {
             return this.removeComponent(event)
         } else {
             const uid = a as string
-            for (const event of this.events()) {
-                if (event.uid() !== uid) continue
+            for (const event of this.getEvents()) {
+                if (event.getUid() !== uid) continue
                 return this.removeComponent(event)
             }
         }
         return false
     }
 
-    prodId(): string {
+    getProductId(): string {
         return this.getProperty('PRODID')!.value
     }
 
-    setProdId(value: string): this {
+    setProductId(value: string): this {
         return this.setProperty('PRODID', value)
     }
 
-    version(): string {
+    getVersion(): string {
         return this.getProperty('VERSION')!.value
     }
 
@@ -74,19 +89,19 @@ export class Calendar extends Component {
         return this.setProperty('VERSION', value)
     }
 
-    calScale(): string | undefined {
+    getCalendarScale(): string | undefined {
         return this.getProperty('CALSCALE')?.value
     }
 
-    setCalScale(value: string): this {
+    setCalendarScale(value: string): this {
         return this.setProperty('CALSCALE', value)
     }
 
-    removeCalScale() {
+    removeCalendarScale() {
         this.removePropertiesWithName('CALSCALE')
     }
 
-    method(): string | undefined {
+    getMethod(): string | undefined {
         return this.getProperty('METHOD')?.value
     }
 
@@ -98,7 +113,7 @@ export class Calendar extends Component {
         this.removePropertiesWithName('METHOD')
     }
 
-    calendarName(): string | undefined {
+    getCalendarName(): string | undefined {
         return this.getProperty('X-WR-CALNAME')?.value
     }
 
@@ -110,7 +125,7 @@ export class Calendar extends Component {
         this.removePropertiesWithName('X-WR-CALNAME')
     }
 
-    calendarDescription(): string | undefined {
+    getCalendarDescription(): string | undefined {
         return this.getProperty('X-WR-CALDESC')?.value
     }
 
@@ -121,4 +136,27 @@ export class Calendar extends Component {
     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
 }