ical-generator 8.1.2-develop.8 → 9.0.0-develop.1

package/src/alarm.ts

@@ -1,92 +1,102 @@
 'use strict';
 
 import type ICalEvent from './event.ts';
+
+import ICalAttendee, { type ICalAttendeeData } from './attendee.ts';
 import {
     addOrGetCustomAttributes,
-    formatDate,
+    checkDate,
+    checkNameAndMail,
     escape,
+    formatDate,
     generateCustomAttributes,
-    checkDate,
     toDurationString,
     toJSON,
-    checkNameAndMail
 } from './tools.ts';
 import { type ICalDateTimeValue } from './types.ts';
-import ICalAttendee, { type ICalAttendeeData } from './attendee.ts';
-
 
 export enum ICalAlarmType {
-    display = 'display',
     audio = 'audio',
-    email = 'email'
+    display = 'display',
+    email = 'email',
 }
 
 export const ICalAlarmRelatesTo = {
     end: 'END',
-    start: 'START'
+    start: 'START',
 } as const;
 
-export type ICalAlarmRelatesTo = typeof ICalAlarmRelatesTo[keyof typeof ICalAlarmRelatesTo];
-
-export type ICalAlarmTypeValue = keyof ICalAlarmType;
-
-export interface ICalAttachment {
-    uri: string;
-    mime: string | null;
-}
-
-export type ICalAlarmData = ICalAlarmBaseData |
-    ICalAlarmTriggerData |
-    ICalAlarmTriggerAfterData |
-    ICalAlarmTriggerBeforeData;
-
-export type ICalAlarmTriggerData = ICalAlarmBaseData & { trigger: number | ICalDateTimeValue };
-export type ICalAlarmTriggerAfterData = ICalAlarmBaseData & { triggerAfter: number | ICalDateTimeValue };
-export type ICalAlarmTriggerBeforeData = ICalAlarmBaseData & { triggerBefore: number | ICalDateTimeValue };
-
 export interface ICalAlarmBaseData {
-    type?: ICalAlarmType;
+    attach?: ICalAttachment | null | string;
+    attendees?: ICalAttendee[] | ICalAttendeeData[];
+    description?: null | string;
     relatesTo?: ICalAlarmRelatesTo | null;
     repeat?: ICalAlarmRepeatData | null;
-    attach?: string | ICalAttachment | null;
-    description?: string | null;
-    summary?: string | null;
-    attendees?: ICalAttendee[] | ICalAttendeeData[];
-    x?: {key: string, value: string}[] | [string, string][] | Record<string, string>;
+    summary?: null | string;
+    type?: ICalAlarmType;
+    x?:
+        | [string, string][]
+        | Record<string, string>
+        | { key: string; value: string }[];
+}
+
+export type ICalAlarmData =
+    | ICalAlarmBaseData
+    | ICalAlarmTriggerAfterData
+    | ICalAlarmTriggerBeforeData
+    | ICalAlarmTriggerData;
+
+export interface ICalAlarmJSONData {
+    attach: ICalAttachment | null;
+    attendees: ICalAttendee[];
+    description: null | string;
+    interval: null | number;
+    relatesTo: ICalAlarmRelatesTo | null;
+    repeat: ICalAlarmRepeatData | null;
+    summary: null | string;
+    trigger: number | string;
+    type: ICalAlarmType;
+    x: { key: string; value: string }[];
 }
 
+export type ICalAlarmRelatesTo =
+    (typeof ICalAlarmRelatesTo)[keyof typeof ICalAlarmRelatesTo];
+
 export interface ICalAlarmRepeatData {
-    times: number;
     interval: number;
+    times: number;
+}
+export type ICalAlarmTriggerAfterData = ICalAlarmBaseData & {
+    triggerAfter: ICalDateTimeValue | number;
+};
+export type ICalAlarmTriggerBeforeData = ICalAlarmBaseData & {
+    triggerBefore: ICalDateTimeValue | number;
+};
+
+export type ICalAlarmTriggerData = ICalAlarmBaseData & {
+    trigger: ICalDateTimeValue | number;
+};
+
+export type ICalAlarmTypeValue = keyof ICalAlarmType;
+
+export interface ICalAttachment {
+    mime: null | string;
+    uri: string;
 }
 
 interface ICalInternalAlarmData {
-    type: ICalAlarmType;
-    trigger: ICalDateTimeValue | number;
-    relatesTo: ICalAlarmRelatesTo | null;
-    repeat: ICalAlarmRepeatData | null;
-    interval: number | null;
     attach: ICalAttachment | null;
-    description: string | null;
-    summary: string | null;
     attendees: ICalAttendee[];
-    x: [string, string][];
-}
-
-export interface ICalAlarmJSONData {
-    type: ICalAlarmType;
-    trigger: string | number;
+    description: null | string;
+    interval: null | number;
     relatesTo: ICalAlarmRelatesTo | null;
     repeat: ICalAlarmRepeatData | null;
-    interval: number | null;
-    attach: ICalAttachment | null;
-    description: string | null;
-    summary: string | null;
-    attendees: ICalAttendee[];
-    x: {key: string, value: string}[];
+    summary: null | string;
+    trigger: ICalDateTimeValue | number;
+    type: ICalAlarmType;
+    x: [string, string][];
 }
 
-
 /**
  * Usually you get an {@link ICalAlarm} object like this:
  *
@@ -116,18 +126,18 @@ export default class ICalAlarm {
      * @param data Alarm Data
      * @param event Reference to ICalEvent object
      */
-    constructor (data: ICalAlarmData, event: ICalEvent) {
+    constructor(data: ICalAlarmData, event: ICalEvent) {
         this.data = {
-            type: ICalAlarmType.display,
-            trigger: -600,
-            relatesTo: null,
-            repeat: null,
-            interval: null,
             attach: null,
+            attendees: [],
             description: null,
+            interval: null,
+            relatesTo: null,
+            repeat: null,
             summary: null,
-            attendees: [],
-            x: []
+            trigger: -600,
+            type: ICalAlarmType.display,
+            x: [],
         };
 
         this.event = event;
@@ -136,9 +146,12 @@ export default class ICalAlarm {
         }
 
         if (data.type !== undefined) this.type(data.type);
-        if ('trigger' in data && data.trigger !== undefined) this.trigger(data.trigger);
-        if ('triggerBefore' in data && data.triggerBefore !== undefined) this.triggerBefore(data.triggerBefore);
-        if ('triggerAfter' in data && data.triggerAfter !== undefined) this.triggerAfter(data.triggerAfter);
+        if ('trigger' in data && data.trigger !== undefined)
+            this.trigger(data.trigger);
+        if ('triggerBefore' in data && data.triggerBefore !== undefined)
+            this.triggerBefore(data.triggerBefore);
+        if ('triggerAfter' in data && data.triggerAfter !== undefined)
+            this.triggerAfter(data.triggerAfter);
         if (data.repeat) this.repeat(data.repeat);
         if (data.attach !== undefined) this.attach(data.attach);
         if (data.description !== undefined) this.description(data.description);
@@ -147,83 +160,149 @@ export default class ICalAlarm {
         if (data.x !== undefined) this.x(data.x);
     }
 
-
     /**
-     * Get the alarm type
+     * Get Attachment
      * @since 0.2.1
      */
-    type (type: ICalAlarmType): this;
-
+    attach(): null | { mime: null | string; uri: string };
     /**
-     * Set the alarm type. See {@link ICalAlarmType}
-     * for available status options.
+     * Set Alarm attachment. Used to set the alarm sound
+     * if alarm type is audio. Defaults to "Basso".
+     *
+     * ```javascript
+     * const cal = ical();
+     * const event = cal.createEvent();
+     *
+     * event.createAlarm({
+     *     attach: 'https://example.com/notification.aud'
+     * });
+     *
+     * // OR
+     *
+     * event.createAlarm({
+     *     attach: {
+     *         uri: 'https://example.com/notification.aud',
+     *         mime: 'audio/basic'
+     *     }
+     * });
+     * ```
+     *
      * @since 0.2.1
      */
-    type (): ICalAlarmType;
-    type (type?: ICalAlarmType): this | ICalAlarmType {
-        if (type === undefined) {
-            return this.data.type;
+    attach(
+        attachment: null | string | { mime?: null | string; uri: string },
+    ): this;
+    attach(
+        attachment?: null | string | { mime?: null | string; uri: string },
+    ): null | this | { mime: null | string; uri: string } {
+        if (attachment === undefined) {
+            return this.data.attach;
         }
-        if (!type || !Object.keys(ICalAlarmType).includes(type)) {
-            throw new Error('`type` is not correct, must be either `display` or `audio`!');
+        if (!attachment) {
+            this.data.attach = null;
+            return this;
         }
 
-        this.data.type = type;
+        let _attach = null;
+        if (typeof attachment === 'string') {
+            _attach = {
+                mime: null,
+                uri: attachment,
+            };
+        } else if (typeof attachment === 'object') {
+            _attach = {
+                mime: attachment.mime || null,
+                uri: attachment.uri,
+            };
+        } else {
+            throw new Error(
+                '`attachment` needs to be a valid formed string or an object. See https://sebbo2002.github.io/' +
+                    'ical-generator/develop/reference/classes/ICalAlarm.html#attach',
+            );
+        }
+
+        if (!_attach.uri) {
+            throw new Error('`attach.uri` is empty!');
+        }
+
+        this.data.attach = {
+            mime: _attach.mime,
+            uri: _attach.uri,
+        };
         return this;
     }
 
-
     /**
-     * Get the trigger time for the alarm. Can either
-     * be a date and time value ({@link ICalDateTimeValue}) or
-     * a number, which will represent the seconds between
-     * alarm and event start. The number is negative, if the
-     * alarm is triggered after the event started.
+     * Get all attendees
+     * @since 7.0.0
+     */
+    attendees(): ICalAttendee[];
+    /**
+     * Add multiple attendees to your event
      *
-     * @since 0.2.1
+     * @since 7.0.0
      */
-    trigger (): number | ICalDateTimeValue;
+    attendees(attendees: (ICalAttendee | ICalAttendeeData | string)[]): this;
+    attendees(
+        attendees?: (ICalAttendee | ICalAttendeeData | string)[],
+    ): ICalAttendee[] | this {
+        if (!attendees) {
+            return this.data.attendees;
+        }
+
+        attendees.forEach((attendee) => this.createAttendee(attendee));
+        return this;
+    }
 
     /**
-     * Use this method to set the alarm time.
-     *
-     * ```javascript
-     * const cal = ical();
-     * const event = cal.createEvent();
-     * const alarm = cal.createAlarm();
-     *
-     * alarm.trigger(600); // -> 10 minutes before event starts
-     * alarm.trigger(new Date()); // -> now
-     * ```
-     *
-     * You can use any supported date object, see
-     * [readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
-     * for details about supported values and timezone handling.
+     * Creates a new {@link ICalAttendee} and returns it. Use options to prefill
+     * the attendee's attributes. Calling this method without options will create
+     * an empty attendee.
      *
-     * @since 0.2.1
+     * @since 7.0.0
      */
-    trigger (trigger: number | ICalDateTimeValue | Date): this;
-    trigger (trigger?: number | ICalDateTimeValue | Date): this | number | ICalDateTimeValue {
-
-        // Getter
-        if (trigger === undefined && typeof this.data.trigger === 'number') {
-            return -1 * this.data.trigger;
+    createAttendee(
+        data: ICalAttendee | ICalAttendeeData | string,
+    ): ICalAttendee {
+        if (data instanceof ICalAttendee) {
+            this.data.attendees.push(data);
+            return data;
         }
-        if (trigger === undefined) {
-            return this.data.trigger;
+        if (typeof data === 'string') {
+            data = { email: data, ...checkNameAndMail('data', data) };
         }
 
-        // Setter
-        if (typeof trigger === 'number' && isFinite(trigger)) {
-            this.data.trigger = -1 * trigger;
-        }
-        else if(!trigger || typeof trigger === 'number') {
-            throw new Error('`trigger` is not correct, must be a finite number or a supported date!');
+        const attendee = new ICalAttendee(data, this);
+        this.data.attendees.push(attendee);
+        return attendee;
+    }
+
+    /**
+     * Get the alarm description. Used to set the alarm message
+     * if alarm type is `display`. If the alarm type is `email`, it's
+     * used to set the email body. Defaults to the event's summary.
+     *
+     * @since 0.2.1
+     */
+    description(): null | string;
+    /**
+     * Set the alarm description. Used to set the alarm message
+     * if alarm type is `display`. If the alarm type is `email`, it's
+     * used to set the email body. Defaults to the event's summary.
+     *
+     * @since 0.2.1
+     */
+    description(description: null | string): this;
+    description(description?: null | string): null | string | this {
+        if (description === undefined) {
+            return this.data.description;
         }
-        else {
-            this.data.trigger = checkDate(trigger, 'trigger');
+        if (!description) {
+            this.data.description = null;
+            return this;
         }
 
+        this.data.description = description;
         return this;
     }
 
@@ -232,34 +311,35 @@ export default class ICalAlarm {
      * Can be either `START` or `END`. If the value is
      * `START` the alarm is triggerd relative to the event start time.
      * If the value is `END` the alarm is triggerd relative to the event end time
-     * 
+     *
      * @since 4.0.1
      */
     relatesTo(): ICalAlarmRelatesTo | null;
-
     /**
      * Use this method to set to which time alarm trigger relates to.
      * Works only if trigger is a `number`
-     * 
+     *
      * ```javascript
      * const cal = ical();
      * const event = cal.createEvent();
      * const alarm = cal.createAlarm();
      *
      * alarm.trigger(600); // -> 10 minutes before event starts
-     * 
+     *
      * alarm.relatesTo('START'); // -> 10 minutes before event starts
      * alarm.relatesTo('END'); // -> 10 minutes before event ends
-     * 
+     *
      * alarm.trigger(-600); // -> 10 minutes after event starts
-     * 
+     *
      * alarm.relatesTo('START'); // -> 10 minutes after event starts
      * alarm.relatesTo('END'); // -> 10 minutes after event ends
      * ```
      * @since 4.0.1
      */
     relatesTo(relatesTo: ICalAlarmRelatesTo | null): this;
-    relatesTo(relatesTo?: ICalAlarmRelatesTo | null): this | ICalAlarmRelatesTo | null {
+    relatesTo(
+        relatesTo?: ICalAlarmRelatesTo | null,
+    ): ICalAlarmRelatesTo | null | this {
         if (relatesTo === undefined) {
             return this.data.relatesTo;
         }
@@ -269,321 +349,378 @@ export default class ICalAlarm {
         }
 
         if (!Object.values(ICalAlarmRelatesTo).includes(relatesTo)) {
-            throw new Error('`relatesTo` is not correct, must be either `START` or `END`!');
+            throw new Error(
+                '`relatesTo` is not correct, must be either `START` or `END`!',
+            );
         }
 
         this.data.relatesTo = relatesTo;
         return this;
     }
 
-
     /**
-     * Get the trigger time for the alarm. Can either
-     * be a date and time value ({@link ICalDateTimeValue}) or
-     * a number, which will represent the seconds between
-     * alarm and event start. The number is negative, if the
-     * alarm is triggered before the event started.
-     *
+     * Get Alarm Repetitions
      * @since 0.2.1
      */
-    triggerAfter (): number | ICalDateTimeValue;
-
+    repeat(): ICalAlarmRepeatData | null;
     /**
-     * Use this method to set the alarm time. Unlike `trigger`, this time
-     * the alarm takes place after the event has started.
+     * Set Alarm Repetitions. Use this to repeat the alarm.
      *
      * ```javascript
      * const cal = ical();
      * const event = cal.createEvent();
-     * const alarm = cal.createAlarm();
      *
-     * alarm.trigger(600); // -> 10 minutes after event starts
+     * // repeat the alarm 4 times every 5 minutes…
+     * cal.createAlarm({
+     *     repeat: {
+     *         times: 4,
+     *         interval: 300
+     *     }
+     * });
      * ```
      *
-     * You can use any supported date object, see
-     * [readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
-     * for details about supported values and timezone handling.
-     *
      * @since 0.2.1
      */
-    triggerAfter (trigger: number | ICalDateTimeValue): this;
-    triggerAfter (trigger?: number | ICalDateTimeValue): this | number | ICalDateTimeValue {
-        if (trigger === undefined) {
-            return this.data.trigger;
+    repeat(repeat: ICalAlarmRepeatData | null): this;
+    repeat(
+        repeat?: ICalAlarmRepeatData | null,
+    ): ICalAlarmRepeatData | null | this {
+        if (repeat === undefined) {
+            return this.data.repeat;
+        }
+        if (!repeat) {
+            this.data.repeat = null;
+            return this;
         }
 
-        return this.trigger(typeof trigger === 'number' ? -1 * trigger : trigger);
-    }
-
-
-    /**
-     * Get the trigger time for the alarm. Can either
-     * be a date and time value ({@link ICalDateTimeValue}) or
-     * a number, which will represent the seconds between
-     * alarm and event start. The number is negative, if the
-     * alarm is triggered after the event started.
-     *
-     * @since 0.2.1
-     * @see {@link trigger}
-     * @see {@link triggerAfter}
-     */
-    triggerBefore (trigger: number | ICalDateTimeValue): this;
+        if (typeof repeat !== 'object') {
+            throw new Error('`repeat` is not correct, must be an object!');
+        }
+        if (typeof repeat.times !== 'number' || !isFinite(repeat.times)) {
+            throw new Error('`repeat.times` is not correct, must be numeric!');
+        }
+        if (typeof repeat.interval !== 'number' || !isFinite(repeat.interval)) {
+            throw new Error(
+                '`repeat.interval` is not correct, must be numeric!',
+            );
+        }
+
+        this.data.repeat = repeat;
+        return this;
+    }
 
     /**
-     * Use this method to set the alarm time.
-     *
-     * ```javascript
-     * const cal = ical();
-     * const event = cal.createEvent();
-     * const alarm = cal.createAlarm();
-     *
-     * alarm.trigger(600); // -> 10 minutes before event starts
-     * alarm.trigger(new Date()); // -> now
-     * ```
+     * Get the alarm summary. Used to set the email subject
+     * if alarm type is `email`. Defaults to the event's summary.
      *
-     * You can use any supported date object, see
-     * [readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
-     * for details about supported values and timezone handling.
+     * @since 7.0.0
+     */
+    summary(): null | string;
+    /**
+     * Set the alarm summary. Used to set the email subject
+     * if alarm type is display. Defaults to the event's summary.
      *
      * @since 0.2.1
-     * @see {@link trigger}
-     * @see {@link triggerAfter}
      */
-    triggerBefore (): number | ICalDateTimeValue;
-    triggerBefore (trigger?: number | ICalDateTimeValue): this | number | ICalDateTimeValue {
-        if(trigger === undefined) {
-            return this.trigger();
+    summary(summary: null | string): this;
+    summary(summary?: null | string): null | string | this {
+        if (summary === undefined) {
+            return this.data.summary;
+        }
+        if (!summary) {
+            this.data.summary = null;
+            return this;
         }
 
-        return this.trigger(trigger);
+        this.data.summary = summary;
+        return this;
     }
 
-
     /**
-     * Get Alarm Repetitions
-     * @since 0.2.1
+     * Return a shallow copy of the alarm's options for JSON stringification.
+     * Third party objects like moment.js values are stringified as well. Can
+     * be used for persistence.
+     *
+     * @since 0.2.4
      */
-    repeat(): ICalAlarmRepeatData | null;
-
+    toJSON(): ICalAlarmJSONData {
+        const trigger = this.trigger();
+        return Object.assign({}, this.data, {
+            trigger: typeof trigger === 'number' ? trigger : toJSON(trigger),
+            x: this.x(),
+        });
+    }
     /**
-     * Set Alarm Repetitions. Use this to repeat the alarm.
+     * Return generated event as a string.
      *
      * ```javascript
-     * const cal = ical();
-     * const event = cal.createEvent();
-     *
-     * // repeat the alarm 4 times every 5 minutes…
-     * cal.createAlarm({
-     *     repeat: {
-     *         times: 4,
-     *         interval: 300
-     *     }
-     * });
+     * const alarm = event.createAlarm();
+     * console.log(alarm.toString()); // → BEGIN:VALARM…
      * ```
-     *
-     * @since 0.2.1
      */
-    repeat(repeat: ICalAlarmRepeatData | null): this;
-    repeat (repeat?: ICalAlarmRepeatData | null): this | ICalAlarmRepeatData | null {
-        if (repeat === undefined) {
-            return this.data.repeat;
+    toString(): string {
+        let g = 'BEGIN:VALARM\r\n';
+
+        // ACTION
+        g += 'ACTION:' + this.data.type.toUpperCase() + '\r\n';
+
+        if (
+            typeof this.data.trigger === 'number' &&
+            this.data.relatesTo === null
+        ) {
+            if (this.data.trigger > 0) {
+                g +=
+                    'TRIGGER;RELATED=END:' +
+                    toDurationString(this.data.trigger) +
+                    '\r\n';
+            } else {
+                g += 'TRIGGER:' + toDurationString(this.data.trigger) + '\r\n';
+            }
+        } else if (typeof this.data.trigger === 'number') {
+            g +=
+                'TRIGGER;RELATED=' +
+                this.data.relatesTo?.toUpperCase() +
+                ':' +
+                toDurationString(this.data.trigger) +
+                '\r\n';
+        } else {
+            g +=
+                'TRIGGER;VALUE=DATE-TIME:' +
+                formatDate(this.event.timezone(), this.data.trigger) +
+                '\r\n';
         }
-        if (!repeat) {
-            this.data.repeat = null;
-            return this;
+
+        // REPEAT
+        if (this.data.repeat) {
+            if (!this.data.repeat.times) {
+                throw new Error(
+                    'No value for `repeat.times` in ICalAlarm given, but required for `interval`!',
+                );
+            }
+            if (!this.data.repeat.interval) {
+                throw new Error(
+                    'No value for `repeat.interval` in ICalAlarm given, but required for `repeat`!',
+                );
+            }
+
+            g += 'REPEAT:' + this.data.repeat.times + '\r\n';
+            g +=
+                'DURATION:' +
+                toDurationString(this.data.repeat.interval) +
+                '\r\n';
         }
 
-        if (typeof repeat !== 'object') {
-            throw new Error('`repeat` is not correct, must be an object!');
+        // ATTACH
+        if (
+            this.data.type === 'audio' &&
+            this.data.attach &&
+            this.data.attach.mime
+        ) {
+            g +=
+                'ATTACH;FMTTYPE=' +
+                escape(this.data.attach.mime, false) +
+                ':' +
+                escape(this.data.attach.uri, false) +
+                '\r\n';
+        } else if (this.data.type === 'audio' && this.data.attach) {
+            g +=
+                'ATTACH;VALUE=URI:' +
+                escape(this.data.attach.uri, false) +
+                '\r\n';
+        } else if (this.data.type === 'audio') {
+            g += 'ATTACH;VALUE=URI:Basso\r\n';
         }
-        if (typeof repeat.times !== 'number' || !isFinite(repeat.times)) {
-            throw new Error('`repeat.times` is not correct, must be numeric!');
+
+        // DESCRIPTION
+        if (this.data.type !== 'audio' && this.data.description) {
+            g += 'DESCRIPTION:' + escape(this.data.description, false) + '\r\n';
+        } else if (this.data.type !== 'audio') {
+            g += 'DESCRIPTION:' + escape(this.event.summary(), false) + '\r\n';
         }
-        if (typeof repeat.interval !== 'number' || !isFinite(repeat.interval)) {
-            throw new Error('`repeat.interval` is not correct, must be numeric!');
+
+        // SUMMARY
+        if (this.data.type === 'email' && this.data.summary) {
+            g += 'SUMMARY:' + escape(this.data.summary, false) + '\r\n';
+        } else if (this.data.type === 'email') {
+            g += 'SUMMARY:' + escape(this.event.summary(), false) + '\r\n';
         }
 
-        this.data.repeat = repeat;
-        return this;
-    }
+        // ATTENDEES
+        if (this.data.type === 'email') {
+            this.data.attendees.forEach((attendee) => {
+                g += attendee.toString();
+            });
+        }
 
+        // CUSTOM X ATTRIBUTES
+        g += generateCustomAttributes(this.data);
+
+        g += 'END:VALARM\r\n';
+        return g;
+    }
 
     /**
-     * Get Attachment
+     * Get the trigger time for the alarm. Can either
+     * be a date and time value ({@link ICalDateTimeValue}) or
+     * a number, which will represent the seconds between
+     * alarm and event start. The number is negative, if the
+     * alarm is triggered after the event started.
+     *
      * @since 0.2.1
      */
-    attach (): {uri: string, mime: string | null} | null;
-
+    trigger(): ICalDateTimeValue | number;
     /**
-     * Set Alarm attachment. Used to set the alarm sound
-     * if alarm type is audio. Defaults to "Basso".
+     * Use this method to set the alarm time.
      *
      * ```javascript
      * const cal = ical();
      * const event = cal.createEvent();
+     * const alarm = cal.createAlarm();
      *
-     * event.createAlarm({
-     *     attach: 'https://example.com/notification.aud'
-     * });
-     *
-     * // OR
-     *
-     * event.createAlarm({
-     *     attach: {
-     *         uri: 'https://example.com/notification.aud',
-     *         mime: 'audio/basic'
-     *     }
-     * });
+     * alarm.trigger(600); // -> 10 minutes before event starts
+     * alarm.trigger(new Date()); // -> now
      * ```
      *
+     * You can use any supported date object, see
+     * [readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
+     * for details about supported values and timezone handling.
+     *
      * @since 0.2.1
      */
-    attach (attachment: {uri: string, mime?: string | null} | string | null): this;
-    attach (attachment?: {uri: string, mime?: string | null} | string | null): this | {uri: string, mime: string | null} | null {
-        if (attachment === undefined) {
-            return this.data.attach;
+    trigger(trigger: Date | ICalDateTimeValue | number): this;
+    trigger(
+        trigger?: Date | ICalDateTimeValue | number,
+    ): ICalDateTimeValue | number | this {
+        // Getter
+        if (trigger === undefined && typeof this.data.trigger === 'number') {
+            return -1 * this.data.trigger;
         }
-        if (!attachment) {
-            this.data.attach = null;
-            return this;
+        if (trigger === undefined) {
+            return this.data.trigger;
         }
 
-        let _attach = null;
-        if (typeof attachment === 'string') {
-            _attach = {
-                uri: attachment,
-                mime: null
-            };
-        }
-        else if (typeof attachment === 'object') {
-            _attach = {
-                uri: attachment.uri,
-                mime: attachment.mime || null
-            };
-        }
-        else {
+        // Setter
+        if (typeof trigger === 'number' && isFinite(trigger)) {
+            this.data.trigger = -1 * trigger;
+        } else if (!trigger || typeof trigger === 'number') {
             throw new Error(
-                '`attachment` needs to be a valid formed string or an object. See https://sebbo2002.github.io/' +
-                'ical-generator/develop/reference/classes/ICalAlarm.html#attach'
+                '`trigger` is not correct, must be a finite number or a supported date!',
             );
+        } else {
+            this.data.trigger = checkDate(trigger, 'trigger');
         }
 
-        if (!_attach.uri) {
-            throw new Error('`attach.uri` is empty!');
-        }
-
-        this.data.attach = {
-            uri: _attach.uri,
-            mime: _attach.mime
-        };
         return this;
     }
 
-
     /**
-     * Get the alarm description. Used to set the alarm message
-     * if alarm type is `display`. If the alarm type is `email`, it's
-     * used to set the email body. Defaults to the event's summary.
+     * Get the trigger time for the alarm. Can either
+     * be a date and time value ({@link ICalDateTimeValue}) or
+     * a number, which will represent the seconds between
+     * alarm and event start. The number is negative, if the
+     * alarm is triggered before the event started.
      *
      * @since 0.2.1
      */
-    description (): string | null;
-
+    triggerAfter(): ICalDateTimeValue | number;
     /**
-     * Set the alarm description. Used to set the alarm message
-     * if alarm type is `display`. If the alarm type is `email`, it's
-     * used to set the email body. Defaults to the event's summary.
+     * Use this method to set the alarm time. Unlike `trigger`, this time
+     * the alarm takes place after the event has started.
+     *
+     * ```javascript
+     * const cal = ical();
+     * const event = cal.createEvent();
+     * const alarm = cal.createAlarm();
+     *
+     * alarm.trigger(600); // -> 10 minutes after event starts
+     * ```
+     *
+     * You can use any supported date object, see
+     * [readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
+     * for details about supported values and timezone handling.
      *
      * @since 0.2.1
      */
-    description (description: string | null): this;
-    description (description?: string | null): this | string | null {
-        if (description === undefined) {
-            return this.data.description;
-        }
-        if (!description) {
-            this.data.description = null;
-            return this;
+    triggerAfter(trigger: ICalDateTimeValue | number): this;
+    triggerAfter(
+        trigger?: ICalDateTimeValue | number,
+    ): ICalDateTimeValue | number | this {
+        if (trigger === undefined) {
+            return this.data.trigger;
         }
 
-        this.data.description = description;
-        return this;
+        return this.trigger(
+            typeof trigger === 'number' ? -1 * trigger : trigger,
+        );
     }
 
-
     /**
-     * Get the alarm summary. Used to set the email subject
-     * if alarm type is `email`. Defaults to the event's summary.
-     *
-     * @since 7.0.0
-     */
-    summary (): string | null;
-
-    /**
-     * Set the alarm summary. Used to set the email subject
-     * if alarm type is display. Defaults to the event's summary.
+     * Get the trigger time for the alarm. Can either
+     * be a date and time value ({@link ICalDateTimeValue}) or
+     * a number, which will represent the seconds between
+     * alarm and event start. The number is negative, if the
+     * alarm is triggered after the event started.
      *
      * @since 0.2.1
+     * @see {@link trigger}
+     * @see {@link triggerAfter}
      */
-    summary (summary: string | null): this;
-    summary (summary?: string | null): this | string | null {
-        if (summary === undefined) {
-            return this.data.summary;
-        }
-        if (!summary) {
-            this.data.summary = null;
-            return this;
-        }
-
-        this.data.summary = summary;
-        return this;
-    }
-
-
+    triggerBefore(trigger: ICalDateTimeValue | number): this;
     /**
-     * Creates a new {@link ICalAttendee} and returns it. Use options to prefill
-     * the attendee's attributes. Calling this method without options will create
-     * an empty attendee.
+     * Use this method to set the alarm time.
      *
-     * @since 7.0.0
+     * ```javascript
+     * const cal = ical();
+     * const event = cal.createEvent();
+     * const alarm = cal.createAlarm();
+     *
+     * alarm.trigger(600); // -> 10 minutes before event starts
+     * alarm.trigger(new Date()); // -> now
+     * ```
+     *
+     * You can use any supported date object, see
+     * [readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
+     * for details about supported values and timezone handling.
+     *
+     * @since 0.2.1
+     * @see {@link trigger}
+     * @see {@link triggerAfter}
      */
-    createAttendee(data: ICalAttendee | ICalAttendeeData | string): ICalAttendee {
-        if (data instanceof ICalAttendee) {
-            this.data.attendees.push(data);
-            return data;
-        }
-        if (typeof data === 'string') {
-            data = { email: data, ...checkNameAndMail('data', data) };
+    triggerBefore(): ICalDateTimeValue | number;
+    triggerBefore(
+        trigger?: ICalDateTimeValue | number,
+    ): ICalDateTimeValue | number | this {
+        if (trigger === undefined) {
+            return this.trigger();
         }
 
-        const attendee = new ICalAttendee(data, this);
-        this.data.attendees.push(attendee);
-        return attendee;
+        return this.trigger(trigger);
     }
-
-
     /**
-     * Get all attendees
-     * @since 7.0.0
+     * Get the alarm type
+     * @since 0.2.1
      */
-    attendees(): ICalAttendee[];
-
+    type(type: ICalAlarmType): this;
     /**
-     * Add multiple attendees to your event
-     *
-     * @since 7.0.0
+     * Set the alarm type. See {@link ICalAlarmType}
+     * for available status options.
+     * @since 0.2.1
      */
-    attendees(attendees: (ICalAttendee | ICalAttendeeData | string)[]): this;
-    attendees(attendees?: (ICalAttendee | ICalAttendeeData | string)[]): this | ICalAttendee[] {
-        if (!attendees) {
-            return this.data.attendees;
+    type(): ICalAlarmType;
+    type(type?: ICalAlarmType): ICalAlarmType | this {
+        if (type === undefined) {
+            return this.data.type;
+        }
+        if (!type || !Object.keys(ICalAlarmType).includes(type)) {
+            throw new Error(
+                '`type` is not correct, must be either `display` or `audio`!',
+            );
         }
 
-        attendees.forEach(attendee => this.createAttendee(attendee));
+        this.data.type = type;
         return this;
     }
 
-
     /**
      * Set X-* attributes. Woun't filter double attributes,
      * which are also added by another method (e.g. type),
@@ -608,8 +745,12 @@ export default class ICalAlarm {
      *
      * @since 1.9.0
      */
-    x (keyOrArray: {key: string, value: string}[] | [string, string][] | Record<string, string>): this;
-
+    x(
+        keyOrArray:
+            | [string, string][]
+            | Record<string, string>
+            | { key: string; value: string }[],
+    ): this;
     /**
      * Set a X-* attribute. Woun't filter double attributes,
      * which are also added by another method (e.g. type),
@@ -621,128 +762,32 @@ export default class ICalAlarm {
      *
      * @since 1.9.0
      */
-    x (keyOrArray: string, value: string): this;
-
+    x(keyOrArray: string, value: string): this;
     /**
      * Get all custom X-* attributes.
      * @since 1.9.0
      */
-    x (): {key: string, value: string}[];
-    x (keyOrArray?: ({key: string, value: string})[] | [string, string][] | Record<string, string> | string, value?: string): this | void | ({key: string, value: string})[] {
-        if(keyOrArray === undefined) {
-            return addOrGetCustomAttributes (this.data);
-        }
-
-        if(typeof keyOrArray === 'string' && typeof value === 'string') {
-            addOrGetCustomAttributes (this.data, keyOrArray, value);
-        }
-        else if(typeof keyOrArray === 'object') {
-            addOrGetCustomAttributes (this.data, keyOrArray);
-        }
-        else {
+    x(): { key: string; value: string }[];
+    x(
+        keyOrArray?:
+            | [string, string][]
+            | Record<string, string>
+            | string
+            | { key: string; value: string }[],
+        value?: string,
+    ): this | void | { key: string; value: string }[] {
+        if (keyOrArray === undefined) {
+            return addOrGetCustomAttributes(this.data);
+        }
+
+        if (typeof keyOrArray === 'string' && typeof value === 'string') {
+            addOrGetCustomAttributes(this.data, keyOrArray, value);
+        } else if (typeof keyOrArray === 'object') {
+            addOrGetCustomAttributes(this.data, keyOrArray);
+        } else {
             throw new Error('Either key or value is not a string!');
         }
 
         return this;
     }
-
-
-    /**
-     * Return a shallow copy of the alarm's options for JSON stringification.
-     * Third party objects like moment.js values are stringified as well. Can
-     * be used for persistence.
-     *
-     * @since 0.2.4
-     */
-    toJSON (): ICalAlarmJSONData {
-        const trigger = this.trigger();
-        return Object.assign({}, this.data, {
-            trigger: typeof trigger === 'number' ? trigger : toJSON(trigger),
-            x: this.x()
-        });
-    }
-
-
-    /**
-     * Return generated event as a string.
-     *
-     * ```javascript
-     * const alarm = event.createAlarm();
-     * console.log(alarm.toString()); // → BEGIN:VALARM…
-     * ```
-     */
-    toString (): string {
-        let g = 'BEGIN:VALARM\r\n';
-
-        // ACTION
-        g += 'ACTION:' + this.data.type.toUpperCase() + '\r\n';
-
-        if (typeof this.data.trigger === 'number' && this.data.relatesTo === null) {
-            if (this.data.trigger > 0) {
-                g += 'TRIGGER;RELATED=END:' + toDurationString(this.data.trigger) + '\r\n';
-            }
-            else {
-                g += 'TRIGGER:' + toDurationString(this.data.trigger) + '\r\n';
-            }
-        } 
-        else if (typeof this.data.trigger === 'number') {
-            g += 'TRIGGER;RELATED=' + this.data.relatesTo?.toUpperCase() + ':' + toDurationString(this.data.trigger) + '\r\n';
-        }
-        else {
-            g += 'TRIGGER;VALUE=DATE-TIME:' + formatDate(this.event.timezone(), this.data.trigger) + '\r\n';
-        }
-
-        // REPEAT
-        if (this.data.repeat) {
-            if (!this.data.repeat.times) {
-                throw new Error('No value for `repeat.times` in ICalAlarm given, but required for `interval`!');
-            }
-            if (!this.data.repeat.interval) {
-                throw new Error('No value for `repeat.interval` in ICalAlarm given, but required for `repeat`!');
-            }
-
-            g += 'REPEAT:' + this.data.repeat.times + '\r\n';
-            g += 'DURATION:' + toDurationString(this.data.repeat.interval) + '\r\n';
-        }
-
-        // ATTACH
-        if (this.data.type === 'audio' && this.data.attach && this.data.attach.mime) {
-            g += 'ATTACH;FMTTYPE=' + escape(this.data.attach.mime, false) + ':' + escape(this.data.attach.uri, false) + '\r\n';
-        }
-        else if (this.data.type === 'audio' && this.data.attach) {
-            g += 'ATTACH;VALUE=URI:' + escape(this.data.attach.uri, false) + '\r\n';
-        }
-        else if (this.data.type === 'audio') {
-            g += 'ATTACH;VALUE=URI:Basso\r\n';
-        }
-
-        // DESCRIPTION
-        if (this.data.type !== 'audio' && this.data.description) {
-            g += 'DESCRIPTION:' + escape(this.data.description, false) + '\r\n';
-        }
-        else if (this.data.type !== 'audio') {
-            g += 'DESCRIPTION:' + escape(this.event.summary(), false) + '\r\n';
-        }
-
-        // SUMMARY
-        if (this.data.type === 'email' && this.data.summary) {
-            g += 'SUMMARY:' + escape(this.data.summary, false) + '\r\n';
-        }
-        else if (this.data.type === 'email') {
-            g += 'SUMMARY:' + escape(this.event.summary(), false) + '\r\n';
-        }
-
-        // ATTENDEES
-        if (this.data.type === 'email') {
-            this.data.attendees.forEach(attendee => {
-                g += attendee.toString();
-            });
-        }
-
-        // CUSTOM X ATTRIBUTES
-        g += generateCustomAttributes(this.data);
-
-        g += 'END:VALARM\r\n';
-        return g;
-    }
 }