iamcal 2.0.0 → 2.1.1

package/src/components/TimeZoneOffset.ts

@@ -0,0 +1,187 @@
+import { Component, ComponentValidationError } from '../component'
+import { CalendarDateOrTime, convertDate, parseDateProperty } from '../date'
+import { AllowedPropertyName } from '../property'
+
+export const knownOffsetTypes = ['DAYLIGHT', 'STANDARD']
+export type OffsetType = (typeof knownOffsetTypes)[number]
+type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
+export type Offset = `${'-' | '+'}${Digit}${Digit}${Digit}${Digit}`
+
+/**
+ * Represents a STANDARD or DAYLIGHT subcomponent, defining a time zone offset.
+ */
+export 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.
+     */
+    constructor(
+        type: OffsetType,
+        start: CalendarDateOrTime | Date,
+        offsetFrom: Offset,
+        offsetTo: Offset
+    )
+    constructor(component: Component)
+    constructor(
+        a: OffsetType | Component,
+        b?: CalendarDateOrTime | Date,
+        c?: Offset,
+        d?: Offset
+    ) {
+        let component: Component
+        if (a instanceof Component) {
+            component = a as Component
+            TimeZoneOffset.prototype.validate.call(component)
+        } else {
+            const name = a as OffsetType
+            const start = convertDate(b!)
+            const offsetFrom = c as Offset
+            const offsetTo = d as Offset
+            component = new Component(name)
+            component.setProperty('DTSTART', start)
+            component.setProperty('TZOFFSETFROM', offsetFrom)
+            component.setProperty('TZOFFSETTO', offsetTo)
+        }
+        super(component.name, component.properties, component.components)
+    }
+
+    validate(): void {
+        if (!knownOffsetTypes.includes(this.name)) {
+            throw new ComponentValidationError(
+                'Component name must be STANDARD or DAYLIGHT'
+            )
+        }
+        const requiredProperties: AllowedPropertyName[] = [
+            'DTSTART',
+            'TZOFFSETFROM',
+            'TZOFFSETTO',
+        ]
+        this.validateAllProperties(requiredProperties)
+    }
+
+    /**
+     * Get the date or time when this time zone offset starts.
+     * @returns The start date or time of this time zone offset.
+     */
+    getStart(): CalendarDateOrTime {
+        return parseDateProperty(this.getProperty('DTSTART')!)
+    }
+
+    /**
+     * Set the date or time when this time zone offset starts.
+     * @param value The start date or time.
+     * @returns The TimeZoneOffset instance for chaining.
+     */
+    setStart(value: CalendarDateOrTime | Date): this {
+        return this.setProperty('DTSTART', convertDate(value))
+    }
+
+    /**
+     * Get the offset which is offset from during this time zone offset.
+     * @returns The offset in a format such as "+0100" or "-0230".
+     */
+    getOffsetFrom(): Offset {
+        return this.getProperty('TZOFFSETFROM')!.value as Offset
+    }
+
+    /**
+     * Set the offset to offset from during this time zone offset.
+     * @param value An offset such as "+0100" or "-0230".
+     * @returns The TimeZoneOffset instance for chaining.
+     */
+    setOffsetFrom(value: Offset): this {
+        return this.setProperty('TZOFFSETFROM', value)
+    }
+
+    /**
+     * Get the offset which is offset to during this time zone offset.
+     * @returns The offset in a format such as "+0100" or "-0230".
+     */
+    getOffsetTo(): Offset {
+        return this.getProperty('TZOFFSETTO')!.value as Offset
+    }
+
+    /**
+     * Set the offset to offset to during this time zone offset.
+     * @param value An offset such as "+0100" or "-0230".
+     * @returns The TimeZoneOffset instance for chaining.
+     */
+    setOffsetTo(value: Offset): this {
+        return this.setProperty('TZOFFSETTO', value)
+    }
+
+    getComment(): string | undefined {
+        return this.getProperty('COMMENT')?.value
+    }
+
+    setComment(value: string): this {
+        return this.setProperty('COMMENT', value)
+    }
+
+    removeComment() {
+        this.removePropertiesWithName('COMMENT')
+    }
+
+    /**
+     * Get the name of this time zone offset.
+     * @returns The time zone offset name if it exists.
+     */
+    getTimeZoneName(): string | undefined {
+        return this.getProperty('TZNAME')?.value
+    }
+
+    /**
+     * Set the name of this time zone offset.
+     * @param value The new name.
+     * @returns The TimeZoneOffset instance for chaining.
+     * @example
+     * timeZoneOffset.setTimeZoneName('EST')
+     */
+    setTimeZoneName(value: string): this {
+        return this.setProperty('TZNAME', value)
+    }
+
+    /**
+     * Remove the name of this time zone offset.
+     */
+    removeTimeZoneName() {
+        this.removePropertiesWithName('TZNAME')
+    }
+
+    /* eslint-disable */
+
+    /**
+     * Get the date or time when this time zone offset starts.
+     * @returns The start date or time of this time zone offset.
+     * @deprecated Use {@link getStart} instead.
+     */
+    start = this.getStart
+
+    /**
+     * Get the offset which is offset from during this time zone offset.
+     * @returns The offset in a format such as "+0100" or "-0230".
+     * @deprecated Use {@link getOffsetFrom} instead.
+     */
+    offsetFrom = this.getOffsetFrom
+
+    /**
+     * Get the offset which is offset to during this time zone offset.
+     * @returns The offset in a format such as "+0100" or "-0230".
+     * @deprecated Use {@link getOffsetTo} instead.
+     */
+    offsetTo = this.getOffsetTo
+
+    /**
+     * @deprecated Use {@link getComment} instead.
+     */
+    comment = this.getComment
+
+    /**
+     * Get the name of this time zone offset.
+     * @returns The time zone offset name if it exists.
+     * @deprecated Use {@link getTimeZoneName} instead.
+     */
+    timeZoneName = this.getTimeZoneName
+}

package/src/components/index.ts

@@ -1,3 +1,4 @@
 export * from './Calendar'
 export * from './CalendarEvent'
-export * from './TimeZone'
+export * from './TimeZone'
+export * from './TimeZoneOffset'

package/src/date.ts

@@ -0,0 +1,395 @@
+import * as patterns from './patterns'
+import { getPropertyValueType, type Property } from './property'
+
+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 interface CalendarDateOrTime {
+    /**
+     * Create a property from this date.
+     * @param name The name of the property.
+     */
+    toProperty(name: string): Property
+
+    /**
+     * Get the string value of this date.
+     * @returns An iCalendar date or date-time string.
+     */
+    getValue(): string
+
+    /**
+     * Get the date value of this date. For {@link CalendarDate} this is the
+     * time at the start of the day.
+     * @returns The date value of this date.
+     */
+    getDate(): Date
+
+    /**
+     * 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
+}
+
+/**
+ * Represents a DATE value as defined by RFC5545.
+ * This is a date without a time, representing a whole day.
+ */
+export class CalendarDate implements CalendarDateOrTime {
+    private date: Date
+
+    constructor(date: Date | string | CalendarDateOrTime) {
+        if (typeof date === 'object') {
+            if (Object.prototype.toString.call(date) === '[object Date]') {
+                this.date = date as Date
+            } else {
+                this.date = (date as CalendarDateOrTime).getDate()
+            }
+        } else {
+            try {
+                this.date = parseDateString(date)
+            } catch {
+                this.date = new Date(date)
+            }
+        }
+
+        if (!this.date || isNaN(this.date.getTime())) {
+            throw new Error('Invalid date provided')
+        }
+
+        this.date.setHours(0, 0, 0, 0)
+    }
+
+    toProperty(name: string): Property {
+        return {
+            name,
+            params: ['VALUE=DATE'],
+            value: this.getValue(),
+        }
+    }
+
+    getValue(): string {
+        return toDateString(this.date)
+    }
+
+    getDate(): Date {
+        return new Date(this.date)
+    }
+
+    isFullDay(): boolean {
+        return true
+    }
+}
+
+export class CalendarDateTime implements CalendarDateOrTime {
+    private date: Date
+
+    constructor(date: Date | string | CalendarDateOrTime) {
+        if (typeof date === 'object') {
+            if (Object.prototype.toString.call(date) === '[object Date]') {
+                this.date = date as Date
+            } else {
+                this.date = (date as CalendarDateOrTime).getDate()
+            }
+        } else {
+            try {
+                this.date = parseDateTimeString(date)
+            } catch {
+                this.date = new Date(date)
+            }
+        }
+
+        if (!this.date || isNaN(this.date.getTime())) {
+            throw new Error('Invalid date provided')
+        }
+    }
+
+    toProperty(name: string): Property {
+        return {
+            name,
+            params: [],
+            value: this.getValue(),
+        }
+    }
+
+    getValue(): string {
+        return toDateTimeString(this.date)
+    }
+
+    getDate(): Date {
+        return new Date(this.date)
+    }
+
+    isFullDay(): boolean {
+        return false
+    }
+}
+
+/**
+ * Pad a number with leading zeros.
+ * @param num The number to pad with zeros.
+ * @param length How many digits the resulting string should have.
+ * @returns The padded string.
+ * @throws If the digits of `num` is greater than `length`.
+ * @throws If `num` is NaN, a decimal or negative.
+ * @throws If `length` is not NaN, a decimal or less than 1.
+ */
+export function padZeros(num: number, length: number): string {
+    if (isNaN(num)) throw new Error('Number must not be NaN')
+    if (isNaN(length)) throw new Error('Length must not be NaN')
+    if (num < 0) throw new Error('Number must not be negative')
+    if (length <= 0) throw new Error('Length must not be less than 1')
+    if (num % 1 !== 0) throw new Error('Number must be an integer')
+    if (length % 1 !== 0) throw new Error('Length must be an integer')
+
+    const digits = Math.floor(Math.log10(num)) + 1
+    if (num !== 0 && digits > length)
+        throw new Error('Number must not have more digits than length')
+
+    return String(num).padStart(length, '0')
+}
+
+/**
+ * Pad zeros for the year component of a date string.
+ * @param year The year, should be positive.
+ * @returns The 4-digit padded year.
+ */
+export function padYear(year: number): string {
+    return padZeros(year, 4)
+}
+
+/**
+ * Pad zeros for the month component of a date string.
+ * @param month The month, should be between 1 and 12.
+ * @returns The 2-digit padded month.
+ */
+export function padMonth(month: number): string {
+    return padZeros(month, 2)
+}
+
+/**
+ * Pad zeros for the day component of a date string.
+ * @param day The day, should be between 1 and 31.
+ * @returns The 2-digit padded day.
+ */
+export function padDay(day: number): string {
+    return padZeros(day, 2)
+}
+
+/**
+ * Pad zeros for the hours component of a time string.
+ * @param hours The hours, should be between 0 and 23.
+ * @returns The 2-digit padded hours.
+ */
+export function padHours(hours: number): string {
+    return padZeros(hours, 2)
+}
+
+/**
+ * Pad zeros for the minutes component of a time string.
+ * @param minutes The minutes, should be between 0 and 59.
+ * @returns The 2-digit padded minutes.
+ */
+export function padMinutes(minutes: number): string {
+    return padZeros(minutes, 2)
+}
+
+/**
+ * Pad zeros for the seconds component of a time string.
+ * @param seconds The seconds, should be between 0 and 59.
+ * @returns The 2-digit padded seconds.
+ */
+export function padSeconds(seconds: number): string {
+    return padZeros(seconds, 2)
+}
+
+/**
+ * Parse a date property into a {@link CalendarDateOrTime}.
+ * @param dateProperty The property to parse.
+ * @param defaultType The default value type to be used if the property does not have an explicit value type.
+ * @returns The parsed date as a {@link CalendarDateOrTime}.
+ * @throws If the value is invalid for the value type.
+ * @throws If the value type is not `DATE-TIME` or `DATE`.
+ */
+export function parseDateProperty(
+    dateProperty: Property,
+    defaultType: 'DATE-TIME' | 'DATE' = 'DATE-TIME'
+): CalendarDateOrTime {
+    const value = dateProperty.value
+    const valueType = getPropertyValueType(dateProperty, defaultType)
+
+    if (valueType === 'DATE-TIME') {
+        return new CalendarDateTime(value)
+    } else if (valueType === 'DATE') {
+        return new CalendarDate(value)
+    } else {
+        throw new Error(`Illegal value type for date '${valueType}'`)
+    }
+}
+
+/**
+ * Format a date as an iCalendar compatible time string. The day of the date is
+ * ignored.
+ * @param date The date to convert to a time string.
+ * @returns The time of the date formatted according to the iCalendar specification.
+ * @throws If the date is invalid.
+ */
+export function toTimeString(date: Date): string {
+    if (isNaN(date.getTime())) throw new Error('Date is invalid')
+    return `${padHours(date.getHours())}${padMinutes(date.getMinutes())}${padSeconds(date.getSeconds())}`
+}
+
+/**
+ * Format a date as an iCalendar compatible date string.
+ * @param date The date to convert to a date string.
+ * @returns A date string formatted according to the iCalendar specification.
+ * @throws If the date is invalid.
+ */
+export function toDateString(date: Date): string {
+    if (isNaN(date.getTime())) throw new Error('Date is invalid')
+    return `${padYear(date.getFullYear())}${padMonth(date.getMonth() + 1)}${padDay(date.getDate())}`
+}
+
+/**
+ * Format a date as an iCalendar compatible date-time string.
+ * @param date The date to convert to a date-time string.
+ * @returns A date-time string formatted according to the iCalendar specification.
+ * @throws If the date is invalid.
+ */
+export function toDateTimeString(date: Date): string {
+    if (isNaN(date.getTime())) throw new Error('Date is invalid')
+    return `${toDateString(date)}T${toTimeString(date)}`
+}
+
+/**
+ * Format a date as an iCalendar compatible date-time string. Offsets the date
+ * to UTC using `timeZoneOffset`.
+ * @param date The date in local time to convert to UTC and a date-time string.
+ * @param timeZoneOffset The timezone offset in minutes.
+ * @returns A UTC date-time string formatted according to the iCalendar specification.
+ * @throws If the date is invalid.
+ * @throws If the offset is invalid.
+ * @example
+ * // The timezone offset for CET (Central European Time)
+ * const timeZoneOffsetCET = -60 // +01:00
+ * const date = new Date('2025-08-07T12:00:00') // The time in CET
+ * // Returns "20250807T110000Z"
+ * const utcDate = toDateTimeStringUTC(date, timeZoneOffsetCET)
+ */
+export function toDateTimeStringUTC(
+    date: Date,
+    timeZoneOffset: number
+): string {
+    if (isNaN(date.getTime())) throw new Error('Date is invalid')
+    if (isNaN(timeZoneOffset)) throw new Error('Time zone offset cannot be NaN')
+    const utcDate = new Date(date.getTime() + timeZoneOffset * ONE_MINUTE_MS)
+    return `${toDateString(utcDate)}T${toTimeString(utcDate)}Z`
+}
+
+/**
+ * Parse a date-time string to a `Date`.
+ * @param dateTime A date-time string formatted according to the iCalendar specification.
+ * @returns The parsed date-time.
+ * @throws If the date is invalid.
+ */
+export function parseDateTimeString(dateTime: string): Date {
+    if (!patterns.valueTypeDateTime.test(dateTime)) {
+        throw new Error('Date-time has invalid format')
+    }
+
+    const year = parseInt(dateTime.substring(0, 4))
+    const monthIndex = parseInt(dateTime.substring(4, 6)) - 1
+    const day = parseInt(dateTime.substring(6, 8))
+
+    if (monthIndex < 0 || monthIndex > 11) {
+        throw new Error('Date-time is invalid')
+    }
+    const daysInMonth = new Date(year, monthIndex + 1, 0).getDate()
+    if (day < 1 || day > daysInMonth) {
+        throw new Error('Date-time is invalid')
+    }
+
+    const hours = parseInt(dateTime.substring(9, 11))
+    if (hours < 0 || hours > 23) {
+        throw new Error('Date-time is invalid')
+    }
+    const minutes = parseInt(dateTime.substring(11, 13))
+    if (minutes < 0 || minutes > 59) {
+        throw new Error('Date-time is invalid')
+    }
+    const seconds = parseInt(dateTime.substring(13, 15))
+    if (seconds < 0 || seconds > 59) {
+        throw new Error('Date-time is invalid')
+    }
+
+    if (dateTime.endsWith('Z')) {
+        const time = Date.UTC(year, monthIndex, day, hours, minutes, seconds)
+        return new Date(time)
+    } else {
+        const parsedDate = new Date(
+            year,
+            monthIndex,
+            day,
+            hours,
+            minutes,
+            seconds
+        )
+        return parsedDate
+    }
+}
+
+/**
+ * Parse a date string to a `Date`.
+ * @param date A date-time string formatted according to the iCalendar specification.
+ * @returns The parsed date.
+ * @throws If the date is invalid.
+ */
+export function parseDateString(date: string): Date {
+    if (!patterns.matchesWholeString(patterns.valueTypeDate, date)) {
+        throw new Error('Date has invalid format')
+    }
+
+    const year = parseInt(date.substring(0, 4))
+    const monthIndex = parseInt(date.substring(4, 6)) - 1
+    const day = parseInt(date.substring(6, 8))
+
+    if (monthIndex < 0 || monthIndex > 11) {
+        throw new Error('Date is invalid')
+    }
+    const daysInMonth = new Date(year, monthIndex + 1, 0).getDate()
+    if (day < 1 || day > daysInMonth) {
+        throw new Error('Date is invalid')
+    }
+
+    const parsedDate = new Date(year, monthIndex, day)
+    return parsedDate
+}
+
+/**
+ * Convert `Date` objects to a {@link CalendarDateOrTime} object or return as
+ * is if `date` is already a {@link CalendarDateOrTime}.
+ * @param date The date object to convert.
+ * @param fullDay If `true`, a `Date` object is converted to {@link CalendarDate}, otherwise `Date` is converted to {@link CalendarDateTime}.
+ * @returns A {@link CalendarDateOrTime} as described above.
+ */
+export function convertDate<T extends CalendarDateOrTime>(
+    date: Date | T,
+    fullDay?: false
+): T | CalendarDateTime
+export function convertDate<T extends CalendarDateOrTime>(
+    date: Date | T,
+    fullDay: true
+): T | CalendarDate
+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)
+    } else {
+        return date as CalendarDateOrTime
+    }
+}

package/src/index.ts

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

package/src/io.ts

@@ -1,31 +1,36 @@
 import fs from 'fs'
 import readline from 'readline'
 import { Calendar } from './components/Calendar'
-import { deserialize } from './parse'
+import { DeserializationError, deserializeComponent } from './parse'
 
 /**
- * Read a calendar from a .ical file
- * @param path Path to the file to read
- * @throws DeserializationError Component must be of valid format
- * @throws TypeError Component must be a `VCALENDAR`
+ * Read a calendar from a iCalendar file.
+ * @param path Path to the file.
+ * @returns The calendar deserialized from the file.
+ * @throws {DeserializationError} If the file content is not a valid calendar.
  */
 export async function load(path: fs.PathLike): Promise<Calendar> {
     const stream = fs.createReadStream(path)
-    const lines = readline.createInterface({ input: stream, crlfDelay: Infinity })
+    const lines = readline.createInterface({
+        input: stream,
+        crlfDelay: Infinity,
+    })
 
-    const component = await deserialize(lines)
+    const component = await deserializeComponent(lines)
 
     if (component.name != 'VCALENDAR') {
-        throw TypeError('Component is not a calendar')
+        throw new DeserializationError('Component must be a VCALENDAR')
     }
 
     return new Calendar(component)
 }
 
 /**
- * Write a calendar to a .ical file
- * @param calendar The calendar
- * @param path Path to the file to write
+ * Write a calendar to a file.
+ * @param calendar The calendar to write to file.
+ * @param path Path to the file to write.
+ * @example
+ * dump(myCalendar, 'calendar.ics')
  */
 export function dump(calendar: Calendar, path: string): Promise<void> {
     return new Promise(resolve => {