iamcal 3.0.3 → 4.0.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,9 +78,30 @@ 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 {
@@ -74,10 +109,10 @@ export class CalendarDateTime 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 {
@@ -100,9 +135,57 @@ export class CalendarDateTime implements CalendarDateOrTime {
         return new Date(this.date)
     }
 
-    isFullDay(): boolean {
+    isFullDay(): this is CalendarDate {
         return false
     }
+
+    /**
+     * 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 +453,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/io.ts

@@ -1,13 +1,19 @@
 import fs from 'fs'
 import readline from 'readline'
 import { Calendar } from './components/Calendar'
-import { DeserializationError, deserializeComponent } from './parse'
+import {
+    DeserializationError,
+    deserializeComponent,
+    deserializeComponentString,
+} from './parse'
+import { ComponentValidationError } from './component'
 
 /**
  * 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.
+ * @deprecated Use `loadCalendarSync` instead.
  */
 export async function load(path: fs.PathLike): Promise<Calendar> {
     const stream = fs.createReadStream(path)
@@ -25,12 +31,30 @@ export async function load(path: fs.PathLike): Promise<Calendar> {
     return new Calendar(component)
 }
 
+/**
+ * Read a calendar from a iCalendar file.
+ * @param path Path to the file.
+ * @param encoding The file encoding, defaults to UTF-8.
+ * @returns The calendar deserialized from the file.
+ * @throws {DeserializationError} If the file content is not a valid component.
+ * @throws {ComponentValidationError} If the deserialized component is not a VCALENDAR.
+ */
+export function loadCalendarSync(
+    path: fs.PathLike,
+    encoding: BufferEncoding = 'utf8'
+): Calendar {
+    const text = fs.readFileSync(path, { encoding: encoding })
+    const component = deserializeComponentString(text)
+    return new Calendar(component)
+}
+
 /**
  * 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')
+ * @deprecated Use `dumpCalendarSync` instead.
  */
 export function dump(calendar: Calendar, path: string): Promise<void> {
     return new Promise(resolve => {
@@ -39,3 +63,20 @@ export function dump(calendar: Calendar, path: string): Promise<void> {
         })
     })
 }
+
+/**
+ * Write a calendar to a file.
+ * @param calendar The calendar to write to file.
+ * @param path Path to the file to write.
+ * @param encoding The file encoding, defaults to UTF-8.
+ * @example
+ * dump(myCalendar, 'calendar.ics')
+ */
+export function dumpCalendarSync(
+    calendar: Calendar,
+    path: string,
+    encoding: BufferEncoding = 'utf8'
+): void {
+    const text = calendar.serialize()
+    fs.writeFileSync(path, text, { encoding: encoding })
+}