ical-generator 5.0.2-develop.2 → 6.0.0-develop.1

package/package.json

@@ -1,8 +1,5 @@
 {
   "author": "Sebastian Pekarek <mail@sebbo.net>",
-  "browser": {
-    "fs": false
-  },
   "bugs": {
     "url": "http://github.com/sebbo2002/ical-generator/issues"
   },
@@ -15,17 +12,16 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/exec": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/npm": "^10.0.5",
+    "@semantic-release/npm": "^11.0.0",
     "@touch4it/ical-timezones": "^1.9.0",
     "@types/luxon": "^3.3.2",
-    "@types/mocha": "^10.0.1",
-    "@types/node": "^20.5.8",
+    "@types/mocha": "^10.0.2",
     "@typescript-eslint/eslint-plugin": "^6.7.0",
     "@typescript-eslint/parser": "^6.7.0",
     "c8": "^8.0.1",
-    "dayjs": "^1.11.9",
-    "eslint": "^8.48.0",
-    "eslint-plugin-jsonc": "^2.9.0",
+    "dayjs": "^1.11.10",
+    "eslint": "^8.51.0",
+    "eslint-plugin-jsonc": "^2.10.0",
     "esm": "^3.2.25",
     "license-checker": "^25.0.1",
     "luxon": "^3.4.3",
@@ -34,14 +30,13 @@
     "moment": "^2.29.4",
     "moment-timezone": "^0.5.43",
     "nyc": "^15.1.0",
-    "portfinder": "^1.0.32",
     "rrule": "^2.7.2",
-    "semantic-release": "^21.1.1",
+    "semantic-release": "^22.0.5",
     "semantic-release-license": "^1.0.2",
     "source-map-support": "^0.5.21",
     "ts-node": "^10.9.1",
     "tsup": "^7.2.0",
-    "typedoc": "^0.25.0",
+    "typedoc": "^0.25.2",
     "typescript": "^5.2.2"
   },
   "engines": {
@@ -77,7 +72,6 @@
     "@touch4it/ical-timezones": ">=1.6.0",
     "@types/luxon": ">= 1.26.0",
     "@types/mocha": ">= 8.2.1",
-    "@types/node": ">= 15.0.0",
     "dayjs": ">= 1.10.0",
     "luxon": ">= 1.26.0",
     "moment": ">= 2.29.0",
@@ -131,5 +125,5 @@
     "test": "mocha"
   },
   "type": "module",
-  "version": "5.0.2-develop.2"
+  "version": "6.0.0-develop.1"
 }

package/src/alarm.ts

@@ -32,24 +32,34 @@ export interface ICalAttachment {
     mime: string | null;
 }
 
-export interface ICalAlarmData {
-    type?: ICalAlarmType | null;
-    trigger?: number | ICalDateTimeValue | null;
+export type ICalAlarmData = ICalAlarmBaseData |
+    ICalAlarmTriggerData |
+    ICalAlarmTriggerAfterData |
+    ICalAlarmTriggerBeforeData;
+
+type ICalAlarmTriggerData = ICalAlarmBaseData & { trigger: number | ICalDateTimeValue };
+type ICalAlarmTriggerAfterData = ICalAlarmBaseData & { triggerAfter: number | ICalDateTimeValue };
+type ICalAlarmTriggerBeforeData = ICalAlarmBaseData & { triggerBefore: number | ICalDateTimeValue };
+
+interface ICalAlarmBaseData {
+    type?: ICalAlarmType;
     relatesTo?: ICalAlarmRelatesTo | null;
-    triggerBefore?: number | ICalDateTimeValue | null;
-    triggerAfter?: number | ICalDateTimeValue | null;
-    repeat?: number | null;
-    interval?: number | null;
+    repeat?: ICalAlarmRepeatData | null;
     attach?: string | ICalAttachment | null;
     description?: string | null;
     x?: {key: string, value: string}[] | [string, string][] | Record<string, string>;
 }
 
+export interface ICalAlarmRepeatData {
+    times: number;
+    interval: number;
+}
+
 interface ICalInternalAlarmData {
-    type: ICalAlarmType | null;
-    trigger: ICalDateTimeValue | number | null;
+    type: ICalAlarmType;
+    trigger: ICalDateTimeValue | number;
     relatesTo: ICalAlarmRelatesTo | null;
-    repeat: number | null;
+    repeat: ICalAlarmRepeatData | null;
     interval: number | null;
     attach: ICalAttachment | null;
     description: string | null;
@@ -57,10 +67,10 @@ interface ICalInternalAlarmData {
 }
 
 export interface ICalAlarmJSONData {
-    type: ICalAlarmType | null;
-    trigger: string | number | null;
+    type: ICalAlarmType;
+    trigger: string | number;
     relatesTo: ICalAlarmRelatesTo | null;
-    repeat: number | null;
+    repeat: ICalAlarmRepeatData | null;
     interval: number | null;
     attach: ICalAttachment | null;
     description: string | null;
@@ -99,8 +109,8 @@ export default class ICalAlarm {
      */
     constructor (data: ICalAlarmData, event: ICalEvent) {
         this.data = {
-            type: null,
-            trigger: null,
+            type: ICalAlarmType.display,
+            trigger: -600,
             relatesTo: null,
             repeat: null,
             interval: null,
@@ -115,11 +125,10 @@ export default class ICalAlarm {
         }
 
         data.type !== undefined && this.type(data.type);
-        data.trigger !== undefined && this.trigger(data.trigger);
-        data.triggerBefore !== undefined && this.triggerBefore(data.triggerBefore);
-        data.triggerAfter !== undefined && this.triggerAfter(data.triggerAfter);
-        data.repeat !== undefined && this.repeat(data.repeat);
-        data.interval !== undefined && this.interval(data.interval);
+        'trigger' in data && data.trigger !== undefined && this.trigger(data.trigger);
+        'triggerBefore' in data && data.triggerBefore !== undefined && this.triggerBefore(data.triggerBefore);
+        'triggerAfter' in data && data.triggerAfter !== undefined && this.triggerAfter(data.triggerAfter);
+        data.repeat && this.repeat(data.repeat);
         data.attach !== undefined && this.attach(data.attach);
         data.description !== undefined && this.description(data.description);
         data.x !== undefined && this.x(data.x);
@@ -130,24 +139,19 @@ export default class ICalAlarm {
      * Get the alarm type
      * @since 0.2.1
      */
-    type (type: ICalAlarmType | null): this;
+    type (type: ICalAlarmType): this;
 
     /**
      * Set the alarm type. See [[`ICalAlarmType`]]
      * for available status options.
      * @since 0.2.1
      */
-    type (): ICalAlarmType | null;
-    type (type?: ICalAlarmType | null): this | ICalAlarmType | null {
+    type (): ICalAlarmType;
+    type (type?: ICalAlarmType): this | ICalAlarmType {
         if (type === undefined) {
             return this.data.type;
         }
-        if (!type) {
-            this.data.type = null;
-            return this;
-        }
-
-        if (!Object.keys(ICalAlarmType).includes(type)) {
+        if (!type || !Object.keys(ICalAlarmType).includes(type)) {
             throw new Error('`type` is not correct, must be either `display` or `audio`!');
         }
 
@@ -165,7 +169,7 @@ export default class ICalAlarm {
      *
      * @since 0.2.1
      */
-    trigger (): number | ICalDateTimeValue | null;
+    trigger (): number | ICalDateTimeValue;
 
     /**
      * Use this method to set the alarm time.
@@ -185,28 +189,22 @@ export default class ICalAlarm {
      *
      * @since 0.2.1
      */
-    trigger (trigger: number | ICalDateTimeValue | Date | null): this;
-    trigger (trigger?: number | ICalDateTimeValue | Date | null): this | number | ICalDateTimeValue | null {
+    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;
         }
-        if (trigger === undefined && this.data.trigger) {
-            return this.data.trigger;
-        }
         if (trigger === undefined) {
-            return null;
+            return this.data.trigger;
         }
 
         // Setter
-        if (!trigger) {
-            this.data.trigger = null;
-        }
-        else if (typeof trigger === 'number' && isFinite(trigger)) {
+        if (typeof trigger === 'number' && isFinite(trigger)) {
             this.data.trigger = -1 * trigger;
         }
-        else if(typeof trigger === 'number') {
+        else if(!trigger || typeof trigger === 'number') {
             throw new Error('`trigger` is not correct, must be a finite number or a supported date!');
         }
         else {
@@ -275,7 +273,7 @@ export default class ICalAlarm {
      *
      * @since 0.2.1
      */
-    triggerAfter (): number | ICalDateTimeValue | null;
+    triggerAfter (): number | ICalDateTimeValue;
 
     /**
      * Use this method to set the alarm time. Unlike `trigger`, this time
@@ -295,8 +293,8 @@ export default class ICalAlarm {
      *
      * @since 0.2.1
      */
-    triggerAfter (trigger: number | ICalDateTimeValue | null): this;
-    triggerAfter (trigger?: number | ICalDateTimeValue | null): this | number | ICalDateTimeValue | null {
+    triggerAfter (trigger: number | ICalDateTimeValue): this;
+    triggerAfter (trigger?: number | ICalDateTimeValue): this | number | ICalDateTimeValue {
         if (trigger === undefined) {
             return this.data.trigger;
         }
@@ -315,7 +313,7 @@ export default class ICalAlarm {
      * @since 0.2.1
      * @alias trigger
      */
-    triggerBefore (trigger: number | ICalDateTimeValue | null): this;
+    triggerBefore (trigger: number | ICalDateTimeValue): this;
 
     /**
      * Use this method to set the alarm time.
@@ -336,8 +334,8 @@ export default class ICalAlarm {
      * @since 0.2.1
      * @alias trigger
      */
-    triggerBefore (): number | ICalDateTimeValue | null;
-    triggerBefore (trigger?: number | ICalDateTimeValue | null): this | number | ICalDateTimeValue | null {
+    triggerBefore (): number | ICalDateTimeValue;
+    triggerBefore (trigger?: number | ICalDateTimeValue): this | number | ICalDateTimeValue {
         if(trigger === undefined) {
             return this.trigger();
         }
@@ -350,7 +348,7 @@ export default class ICalAlarm {
      * Get Alarm Repetitions
      * @since 0.2.1
      */
-    repeat(): number | null;
+    repeat(): ICalAlarmRepeatData | null;
 
     /**
      * Set Alarm Repetitions. Use this to repeat the alarm.
@@ -361,15 +359,17 @@ export default class ICalAlarm {
      *
      * // repeat the alarm 4 times every 5 minutes…
      * cal.createAlarm({
-     *     repeat: 4,
-     *     interval: 300
+     *     repeat: {
+     *         times: 4,
+     *         interval: 300
+     *     }
      * });
      * ```
      *
      * @since 0.2.1
      */
-    repeat(repeat: number | null): this;
-    repeat (repeat?: number | null): this | number | null {
+    repeat(repeat: ICalAlarmRepeatData | null): this;
+    repeat (repeat?: ICalAlarmRepeatData | null): this | ICalAlarmRepeatData | null {
         if (repeat === undefined) {
             return this.data.repeat;
         }
@@ -378,52 +378,17 @@ export default class ICalAlarm {
             return this;
         }
 
-        if (typeof repeat !== 'number' || !isFinite(repeat)) {
-            throw new Error('`repeat` is not correct, must be numeric!');
+        if (typeof repeat !== 'object') {
+            throw new Error('`repeat` is not correct, must be an object!');
         }
-
-        this.data.repeat = repeat;
-        return this;
-    }
-
-
-    /**
-     * Get Repeat Interval
-     * @since 0.2.1
-     */
-    interval (interval: number | null): this;
-
-    /**
-     * Set Repeat Interval
-     *
-     * ```javascript
-     * const cal = ical();
-     * const event = cal.createEvent();
-     *
-     * // repeat the alarm 4 times every 5 minutes…
-     * cal.createAlarm({
-     *     repeat: 4,
-     *     interval: 300
-     * });
-     * ```
-     *
-     * @since 0.2.1
-     */
-    interval(): number | null;
-    interval (interval?: number | null): this | number | null {
-        if (interval === undefined) {
-            return this.data.interval || null;
+        if (typeof repeat.times !== 'number' || !isFinite(repeat.times)) {
+            throw new Error('`repeat.times` is not correct, must be numeric!');
         }
-        if (!interval) {
-            this.data.interval = null;
-            return this;
+        if (typeof repeat.interval !== 'number' || !isFinite(repeat.interval)) {
+            throw new Error('`repeat.interval` is not correct, must be numeric!');
         }
 
-        if (typeof interval !== 'number' || !isFinite(interval)) {
-            throw new Error('`interval` is not correct, must be numeric!');
-        }
-
-        this.data.interval = interval;
+        this.data.repeat = repeat;
         return this;
     }
 
@@ -619,13 +584,6 @@ export default class ICalAlarm {
     toString (): string {
         let g = 'BEGIN:VALARM\r\n';
 
-        if (!this.data.type) {
-            throw new Error('No value for `type` in ICalAlarm given!');
-        }
-        if (!this.data.trigger) {
-            throw new Error('No value for `trigger` in ICalAlarm given!');
-        }
-
         // ACTION
         g += 'ACTION:' + this.data.type.toUpperCase() + '\r\n';
 
@@ -638,26 +596,23 @@ export default class ICalAlarm {
             }
         } 
         else if (typeof this.data.trigger === 'number') {
-            g += 'TRIGGER;RELATED=' + this.data.relatesTo.toUpperCase() + ':' + toDurationString(this.data.trigger) + '\r\n';
+            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 && !this.data.interval) {
-            throw new Error('No value for `interval` in ICalAlarm given, but required for `repeat`!');
-        }
         if (this.data.repeat) {
-            g += 'REPEAT:' + this.data.repeat + '\r\n';
-        }
+            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`!');
+            }
 
-        // INTERVAL
-        if (this.data.interval && !this.data.repeat) {
-            throw new Error('No value for `repeat` in ICalAlarm given, but required for `interval`!');
-        }
-        if (this.data.interval) {
-            g += 'DURATION:' + toDurationString(this.data.interval) + '\r\n';
+            g += 'REPEAT:' + this.data.repeat.times + '\r\n';
+            g += 'DURATION:' + toDurationString(this.data.repeat.interval) + '\r\n';
         }
 
         // ATTACH

package/src/attendee.ts

@@ -7,7 +7,7 @@ import ICalEvent from './event.js';
 
 interface ICalInternalAttendeeData {
     name: string | null;
-    email: string | null;
+    email: string;
     mailto: string | null;
     sentBy: string | null;
     status: ICalAttendeeStatus | null;
@@ -21,7 +21,7 @@ interface ICalInternalAttendeeData {
 
 export interface ICalAttendeeData {
     name?: string | null;
-    email?: string | null;
+    email: string;
     mailto?: string | null;
     sentBy?: string | null;
     status?: ICalAttendeeStatus | null;
@@ -37,7 +37,7 @@ export interface ICalAttendeeData {
 
 export interface ICalAttendeeJSONData {
     name: string | null;
-    email: string | null;
+    email: string;
     mailto: string | null;
     sentBy: string | null;
     status: ICalAttendeeStatus | null;
@@ -81,14 +81,14 @@ export enum ICalAttendeeType {
  * import ical from 'ical-generator';
  * const calendar = ical();
  * const event = calendar.createEvent();
- * const attendee = event.createAttendee();
+ * const attendee = event.createAttendee({ email: 'mail@example.com' });
  * ```
  *
  * You can also use the [[`ICalAttendee`]] object directly:
  *
  * ```javascript
  * import ical, {ICalAttendee} from 'ical-generator';
- * const attendee = new ICalAttendee();
+ * const attendee = new ICalAttendee({ email: 'mail@example.com' });
  * event.attendees([attendee]);
  * ```
  */
@@ -106,7 +106,7 @@ export default class ICalAttendee {
     constructor(data: ICalAttendeeData, event: ICalEvent) {
         this.data = {
             name: null,
-            email: null,
+            email: '',
             mailto: null,
             sentBy: null,
             status: null,
@@ -121,6 +121,9 @@ export default class ICalAttendee {
         if (!this.event) {
             throw new Error('`event` option required!');
         }
+        if (!data.email) {
+            throw new Error('No value for `email` in ICalAttendee given!');
+        }
 
         data.name !== undefined && this.name(data.name);
         data.email !== undefined && this.email(data.email);
@@ -163,14 +166,14 @@ export default class ICalAttendee {
      * Get the attendee's email address
      * @since 0.2.0
      */
-    email(): string | null;
+    email(): string;
 
     /**
      * Set the attendee's email address
      * @since 0.2.0
      */
-    email(email: string | null): this;
-    email(email?: string | null): this | string | null {
+    email(email: string): this;
+    email(email?: string): this | string {
         if (!email) {
             return this.data.email;
         }
@@ -363,7 +366,7 @@ export default class ICalAttendee {
 
         if(typeof delegatedTo === 'string') {
             this.data.delegatedTo = new ICalAttendee(
-                checkNameAndMail('delegatedTo', delegatedTo),
+                { email: delegatedTo, ...checkNameAndMail('delegatedTo', delegatedTo) },
                 this.event,
             );
         }
@@ -405,7 +408,7 @@ export default class ICalAttendee {
         }
         else if(typeof delegatedFrom === 'string') {
             this.data.delegatedFrom = new ICalAttendee(
-                checkNameAndMail('delegatedFrom', delegatedFrom),
+                { email: delegatedFrom, ...checkNameAndMail('delegatedFrom', delegatedFrom) },
                 this.event,
             );
         }

package/src/calendar.ts

@@ -9,8 +9,6 @@ import {
     toDurationString
 } from './tools.js';
 import ICalEvent, {ICalEventData, ICalEventJSONData} from './event.js';
-import {writeFile, writeFileSync, promises as fsPromises} from 'node:fs';
-import {ServerResponse} from 'node:http';
 import { ICalMomentDurationStub, ICalTimezone } from './types.js';
 
 
@@ -583,92 +581,6 @@ export default class ICalCalendar {
     }
 
 
-    /**
-     * Save ical file using [`fs/promises`](https://nodejs.org/api/fs.html#fs_fspromises_writefile_file_data_options).
-     * Only works in node.js environments.
-     *
-     * ```javascript
-     * await calendar.save('./calendar.ical');
-     * ```
-     */
-    save(path: string): Promise<void>;
-
-    /**
-     * Save ical file with [`fs.writeFile`](http://nodejs.org/api/fs.html#fs_fs_writefile_filename_data_options_callback).
-     * Only works in node.js environments.
-     *
-     * ```javascript
-     * calendar.save('./calendar.ical', err => {
-     *     console.log(err);
-     * });
-     * ```
-     */
-    save(path: string, cb?: (err: NodeJS.ErrnoException | null) => void): this;
-    save(path: string, cb?: (err: NodeJS.ErrnoException | null) => void): this | Promise<void> {
-        if (cb) {
-            writeFile(path, this.toString(), cb);
-            return this;
-        }
-
-        return fsPromises.writeFile(path, this.toString());
-    }
-
-
-    /**
-     * Save Calendar to disk synchronously using
-     * [fs.writeFileSync](http://nodejs.org/api/fs.html#fs_fs_writefilesync_filename_data_options).
-     * Only works in node.js environments.
-     *
-     * ```javascript
-     * calendar.saveSync('./calendar.ical');
-     * ```
-     */
-    saveSync(path: string): this {
-        writeFileSync(path, this.toString());
-        return this;
-    }
-
-
-    /**
-     * Send calendar to the user when using HTTP using the passed `ServerResponse` object.
-     * Use second parameter `filename` to change the filename, which defaults to `'calendar.ics'`.
-     *
-     * @param response HTTP Response object which is used to send the calendar
-     * @param [filename = 'calendar.ics'] Filename of the calendar file
-     */
-    serve(response: ServerResponse, filename = 'calendar.ics'): this {
-        response.writeHead(200, {
-            'Content-Type': 'text/calendar; charset=utf-8',
-            'Content-Disposition': `attachment; filename="${filename}"`
-        });
-
-        response.end(this.toString());
-        return this;
-    }
-
-
-    /**
-     * Generates a blob to use for downloads or to generate a download URL.
-     * Only supported in browsers supporting the Blob API.
-     *
-     * @since 1.9.0
-     */
-    toBlob(): Blob {
-        return new Blob([this.toString()], {type: 'text/calendar'});
-    }
-
-
-    /**
-     * Returns a URL to download the ical file. Uses the Blob object internally,
-     * so it's only supported in browsers supporting the Blob API.
-     *
-     * @since 1.9.0
-     */
-    toURL(): string {
-        return URL.createObjectURL(this.toBlob());
-    }
-
-
     /**
      * Set X-* attributes. Woun't filter double attributes,
      * which are also added by another method (e.g. busystatus),

package/src/category.ts

@@ -5,13 +5,15 @@ import {escape} from './tools.js';
 
 
 export interface ICalCategoryData {
-    name?: string | null
+    name: string;
 }
 
 export interface ICalCategoryInternalData {
-    name: string | null
+    name: string;
 }
 
+export type ICalCategoryJSONData = ICalCategoryInternalData;
+
 
 /**
  * Usually you get an `ICalCategory` object like this:
@@ -40,10 +42,14 @@ export default class ICalCategory {
      */
     constructor(data: ICalCategoryData) {
         this.data = {
-            name: null
+            name: ''
         };
 
-        data.name !== undefined && this.name(data.name);
+        if(!data.name) {
+            throw new Error('No value for `name` in ICalCategory given!');
+        }
+
+        this.name(data.name);
     }
 
 
@@ -51,19 +57,19 @@ export default class ICalCategory {
      * Get the category name
      * @since 0.3.0
      */
-    name(): string | null;
+    name(): string;
 
     /**
      * Set the category name
      * @since 0.3.0
      */
-    name(name: string | null): this;
-    name(name?: string | null): this | string | null {
+    name(name: string): this;
+    name(name?: string): this | string {
         if (name === undefined) {
             return this.data.name;
         }
 
-        this.data.name = name || null;
+        this.data.name = name;
         return this;
     }
 
@@ -89,10 +95,6 @@ export default class ICalCategory {
     toString(): string {
 
         // CN / Name
-        if (!this.data.name) {
-            throw new Error('No value for `name` in ICalCategory given!');
-        }
-
         return escape(this.data.name, false);
     }
 }