ical-generator 6.0.2-develop.5 → 6.0.2-develop.6

package/dist/index.d.cts

@@ -982,6 +982,35 @@ declare class ICalEvent {
      * [Readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
      * for details about supported values and timezone handling.
      *
+     * ```typescript
+     * import ical from 'ical-generator';
+     *
+     * const cal = ical();
+     *
+     * const event = cal.createEvent({
+     *   start: new Date('2020-01-01')
+     * });
+     *
+     * // overwrites old start date
+     * event.start(new Date('2024-02-01'));
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:7e2aee64-b07a-4256-9b3e-e9eaa452bac8
+     * SEQUENCE:0
+     * DTSTAMP:20240212T190915Z
+     * DTSTART:20240201T000000Z
+     * SUMMARY:
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
+     *
      * @since 0.2.0
      */
     start(start: ICalDateTimeValue): this;
@@ -1083,6 +1112,36 @@ declare class ICalEvent {
      * event.allDay(true); // → appointment is for the whole day
      * ```
      *
+     * ```typescript
+     * import ical from 'ical-generator';
+     *
+     * const cal = ical();
+     *
+     * cal.createEvent({
+     *   start: new Date('2020-01-01'),
+     *   summary: 'Very Important Day',
+     *   allDay: true
+     * });
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:1964fe8d-32c5-4f2a-bd62-7d9d7de5992b
+     * SEQUENCE:0
+     * DTSTAMP:20240212T191956Z
+     * DTSTART;VALUE=DATE:20200101
+     * X-MICROSOFT-CDO-ALLDAYEVENT:TRUE
+     * X-MICROSOFT-MSNCALENDAR-ALLDAYEVENT:TRUE
+     * SUMMARY:Very Important Day
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
+     *
      * @since 0.2.0
      */
     allDay(allDay: boolean): this;
@@ -1116,12 +1175,84 @@ declare class ICalEvent {
      * });
      * ```
      *
+     * **Example:**
+     *
+     *```typescript
+     * import ical, { ICalEventRepeatingFreq } from 'ical-generator';
+     *
+     * const cal = ical();
+     *
+     * const event = cal.createEvent({
+     *   start: new Date('2020-01-01T20:00:00Z'),
+     *   summary: 'Repeating Event'
+     * });
+     * event.repeating({
+     *   freq: ICalEventRepeatingFreq.WEEKLY,
+     *   count: 4
+     * });
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:b80e6a68-c2cd-48f5-b94d-cecc7ce83871
+     * SEQUENCE:0
+     * DTSTAMP:20240212T193646Z
+     * DTSTART:20200101T200000Z
+     * RRULE:FREQ=WEEKLY;COUNT=4
+     * SUMMARY:Repeating Event
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
+     *
      * @since 0.2.0
      */
     repeating(repeating: ICalRepeatingOptions | null): this;
     /**
      * Set the event's repeating options by passing an [RRule object](https://github.com/jakubroztocil/rrule).
      * @since 2.0.0-develop.5
+     *
+     * ```typescript
+     * import ical from 'ical-generator';
+     * import { datetime, RRule } from 'rrule';
+     *
+     * const cal = ical();
+     *
+     * const event = cal.createEvent({
+     *   start: new Date('2020-01-01T20:00:00Z'),
+     *   summary: 'Repeating Event'
+     * });
+     *
+     * const rule = new RRule({
+     *   freq: RRule.WEEKLY,
+     *   interval: 5,
+     *   byweekday: [RRule.MO, RRule.FR],
+     *   dtstart: datetime(2012, 2, 1, 10, 30),
+     *   until: datetime(2012, 12, 31)
+     * })
+     * event.repeating(rule);
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:36585e40-8fa8-460d-af0c-88b6f434030b
+     * SEQUENCE:0
+     * DTSTAMP:20240212T193827Z
+     * DTSTART:20200101T200000Z
+     * RRULE:FREQ=WEEKLY;INTERVAL=5;BYDAY=MO,FR;UNTIL=20121231T000000Z
+     * SUMMARY:Repeating Event
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
      */
     repeating(repeating: ICalRRuleStub | null): this;
     /**
@@ -1167,6 +1298,15 @@ declare class ICalEvent {
      * });
      * ```
      *
+     * ```text
+     * LOCATION:Apple Store Kurfürstendamm\nKurfürstendamm 26\, 10719 Berlin\,
+     *  Deutschland
+     * X-APPLE-STRUCTURED-LOCATION;VALUE=URI;X-ADDRESS=Kurfürstendamm 26\, 10719
+     *   Berlin\, Deutschland;X-APPLE-RADIUS=141.1751386318387;X-TITLE=Apple Store
+     *   Kurfürstendamm:geo:52.50363,13.32865
+     * GEO:52.50363;13.32865
+     * ```
+     *
      * @since 0.2.0
      */
     location(location: ICalLocation | string | null): this;
@@ -1183,11 +1323,16 @@ declare class ICalEvent {
      *
      * ```javascript
      * event.description({
-     *     plain: 'Hello World!';
-     *     html: '<p>Hello World!</p>';
+     *     plain: 'Hello World!',
+     *     html: '<p>Hello World!</p>'
      * });
      * ```
      *
+     * ```text
+     * DESCRIPTION:Hello World!
+     * X-ALT-DESC;FMTTYPE=text/html:<p>Hello World!</p>
+     * ```
+     *
      * @since 0.2.0
      */
     description(description: ICalDescription | string | null): this;
@@ -1230,14 +1375,35 @@ declare class ICalEvent {
      * an empty attendee.
      *
      * ```javascript
+     * import ical from 'ical-generator';
+     *
      * const cal = ical();
-     * const event = cal.createEvent();
-     * const attendee = event.createAttendee({email: 'hui@example.com', name: 'Hui'});
+     * const event = cal.createEvent({
+     *   start: new Date()
+     * });
+     *
+     * event.createAttendee({email: 'hui@example.com', name: 'Hui'});
      *
      * // add another attendee
      * event.createAttendee('Buh <buh@example.net>');
      * ```
      *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:b4944f07-98e4-4581-ac80-2589bb20273d
+     * SEQUENCE:0
+     * DTSTAMP:20240212T194232Z
+     * DTSTART:20240212T194232Z
+     * SUMMARY:
+     * ATTENDEE;ROLE=REQ-PARTICIPANT;CN="Hui":MAILTO:hui@example.com
+     * ATTENDEE;ROLE=REQ-PARTICIPANT;CN="Buh":MAILTO:buh@example.net
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
+     *
      * As with the organizer, you can also add an explicit `mailto` address.
      *
      * ```javascript
@@ -1648,7 +1814,7 @@ declare enum ICalCalendarMethod {
 declare class ICalCalendar {
     private readonly data;
     /**
-     * You can pass options to setup your calendar or use setters to do this.
+     * You can pass options to set up your calendar or use setters to do this.
      *
      * ```javascript
      *  * import ical from 'ical-generator';
@@ -1669,6 +1835,16 @@ declare class ICalCalendar {
      * cal.name('sebbo.net');
      * ```
      *
+     * `cal.toString()` would then produce the following string:
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * NAME:sebbo.net
+     * X-WR-CALNAME:sebbo.net
+     * END:VCALENDAR
+     * ```
+     *
      * @param data Calendar data
      */
     constructor(data?: ICalCalendarData);
@@ -1691,6 +1867,11 @@ declare class ICalCalendar {
      * });
      * ```
      *
+     * `cal.toString()` would then produce the following string:
+     * ```text
+     * PRODID:-//My Company//My Product//EN
+     * ```
+     *
      * @since 0.2.0
      */
     prodId(prodId: ICalCalendarProdIdData | string): this;
@@ -1708,6 +1889,8 @@ declare class ICalCalendar {
      * #### Typescript Example
      * ```typescript
      * import {ICalCalendarMethod} from 'ical-generator';
+     *
+     * // METHOD:PUBLISH
      * calendar.method(ICalCalendarMethod.PUBLISH);
      * ```
      *
@@ -1723,6 +1906,24 @@ declare class ICalCalendar {
      * Set your feed's name. Is used to fill `NAME`
      * and `X-WR-CALNAME` in your iCal file.
      *
+     * ```typescript
+     * import ical from 'ical-generator';
+     *
+     * const cal = ical();
+     * cal.name('Next Arrivals');
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * NAME:Next Arrivals
+     * X-WR-CALNAME:Next Arrivals
+     * END:VCALENDAR
+     * ```
+     *
      * @since 0.2.0
      */
     name(name: string | null): this;
@@ -1776,7 +1977,7 @@ declare class ICalCalendar {
      * import ical from 'ical-generator';
      * import {getVtimezoneComponent} from '@touch4it/ical-timezones';
      *
-     * const cal = new ICalCalendar();
+     * const cal = ical();
      * cal.timezone({
      *     name: 'FOO',
      *     generator: getVtimezoneComponent
@@ -1804,6 +2005,10 @@ declare class ICalCalendar {
      * cal.source('http://example.com/my/original_source.ical');
      * ```
      *
+     * ```text
+     * SOURCE;VALUE=URI:http://example.com/my/original_source.ical
+     * ```
+     *
      * @since 2.2.0-develop.1
      */
     source(source: string | null): this;
@@ -1956,6 +2161,14 @@ declare class ICalCalendar {
      * });
      * ```
      *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * X-MY-CUSTOM-ATTR:1337!
+     * END:VCALENDAR
+     * ```
+     *
      * @since 1.9.0
      */
     x(keyOrArray: {
@@ -1971,6 +2184,14 @@ declare class ICalCalendar {
      * calendar.x("X-MY-CUSTOM-ATTR", "1337!");
      * ```
      *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * X-MY-CUSTOM-ATTR:1337!
+     * END:VCALENDAR
+     * ```
+     *
      * @since 1.9.0
      */
     x(keyOrArray: string, value: string): this;

package/dist/index.d.ts

@@ -982,6 +982,35 @@ declare class ICalEvent {
      * [Readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
      * for details about supported values and timezone handling.
      *
+     * ```typescript
+     * import ical from 'ical-generator';
+     *
+     * const cal = ical();
+     *
+     * const event = cal.createEvent({
+     *   start: new Date('2020-01-01')
+     * });
+     *
+     * // overwrites old start date
+     * event.start(new Date('2024-02-01'));
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:7e2aee64-b07a-4256-9b3e-e9eaa452bac8
+     * SEQUENCE:0
+     * DTSTAMP:20240212T190915Z
+     * DTSTART:20240201T000000Z
+     * SUMMARY:
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
+     *
      * @since 0.2.0
      */
     start(start: ICalDateTimeValue): this;
@@ -1083,6 +1112,36 @@ declare class ICalEvent {
      * event.allDay(true); // → appointment is for the whole day
      * ```
      *
+     * ```typescript
+     * import ical from 'ical-generator';
+     *
+     * const cal = ical();
+     *
+     * cal.createEvent({
+     *   start: new Date('2020-01-01'),
+     *   summary: 'Very Important Day',
+     *   allDay: true
+     * });
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:1964fe8d-32c5-4f2a-bd62-7d9d7de5992b
+     * SEQUENCE:0
+     * DTSTAMP:20240212T191956Z
+     * DTSTART;VALUE=DATE:20200101
+     * X-MICROSOFT-CDO-ALLDAYEVENT:TRUE
+     * X-MICROSOFT-MSNCALENDAR-ALLDAYEVENT:TRUE
+     * SUMMARY:Very Important Day
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
+     *
      * @since 0.2.0
      */
     allDay(allDay: boolean): this;
@@ -1116,12 +1175,84 @@ declare class ICalEvent {
      * });
      * ```
      *
+     * **Example:**
+     *
+     *```typescript
+     * import ical, { ICalEventRepeatingFreq } from 'ical-generator';
+     *
+     * const cal = ical();
+     *
+     * const event = cal.createEvent({
+     *   start: new Date('2020-01-01T20:00:00Z'),
+     *   summary: 'Repeating Event'
+     * });
+     * event.repeating({
+     *   freq: ICalEventRepeatingFreq.WEEKLY,
+     *   count: 4
+     * });
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:b80e6a68-c2cd-48f5-b94d-cecc7ce83871
+     * SEQUENCE:0
+     * DTSTAMP:20240212T193646Z
+     * DTSTART:20200101T200000Z
+     * RRULE:FREQ=WEEKLY;COUNT=4
+     * SUMMARY:Repeating Event
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
+     *
      * @since 0.2.0
      */
     repeating(repeating: ICalRepeatingOptions | null): this;
     /**
      * Set the event's repeating options by passing an [RRule object](https://github.com/jakubroztocil/rrule).
      * @since 2.0.0-develop.5
+     *
+     * ```typescript
+     * import ical from 'ical-generator';
+     * import { datetime, RRule } from 'rrule';
+     *
+     * const cal = ical();
+     *
+     * const event = cal.createEvent({
+     *   start: new Date('2020-01-01T20:00:00Z'),
+     *   summary: 'Repeating Event'
+     * });
+     *
+     * const rule = new RRule({
+     *   freq: RRule.WEEKLY,
+     *   interval: 5,
+     *   byweekday: [RRule.MO, RRule.FR],
+     *   dtstart: datetime(2012, 2, 1, 10, 30),
+     *   until: datetime(2012, 12, 31)
+     * })
+     * event.repeating(rule);
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:36585e40-8fa8-460d-af0c-88b6f434030b
+     * SEQUENCE:0
+     * DTSTAMP:20240212T193827Z
+     * DTSTART:20200101T200000Z
+     * RRULE:FREQ=WEEKLY;INTERVAL=5;BYDAY=MO,FR;UNTIL=20121231T000000Z
+     * SUMMARY:Repeating Event
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
      */
     repeating(repeating: ICalRRuleStub | null): this;
     /**
@@ -1167,6 +1298,15 @@ declare class ICalEvent {
      * });
      * ```
      *
+     * ```text
+     * LOCATION:Apple Store Kurfürstendamm\nKurfürstendamm 26\, 10719 Berlin\,
+     *  Deutschland
+     * X-APPLE-STRUCTURED-LOCATION;VALUE=URI;X-ADDRESS=Kurfürstendamm 26\, 10719
+     *   Berlin\, Deutschland;X-APPLE-RADIUS=141.1751386318387;X-TITLE=Apple Store
+     *   Kurfürstendamm:geo:52.50363,13.32865
+     * GEO:52.50363;13.32865
+     * ```
+     *
      * @since 0.2.0
      */
     location(location: ICalLocation | string | null): this;
@@ -1183,11 +1323,16 @@ declare class ICalEvent {
      *
      * ```javascript
      * event.description({
-     *     plain: 'Hello World!';
-     *     html: '<p>Hello World!</p>';
+     *     plain: 'Hello World!',
+     *     html: '<p>Hello World!</p>'
      * });
      * ```
      *
+     * ```text
+     * DESCRIPTION:Hello World!
+     * X-ALT-DESC;FMTTYPE=text/html:<p>Hello World!</p>
+     * ```
+     *
      * @since 0.2.0
      */
     description(description: ICalDescription | string | null): this;
@@ -1230,14 +1375,35 @@ declare class ICalEvent {
      * an empty attendee.
      *
      * ```javascript
+     * import ical from 'ical-generator';
+     *
      * const cal = ical();
-     * const event = cal.createEvent();
-     * const attendee = event.createAttendee({email: 'hui@example.com', name: 'Hui'});
+     * const event = cal.createEvent({
+     *   start: new Date()
+     * });
+     *
+     * event.createAttendee({email: 'hui@example.com', name: 'Hui'});
      *
      * // add another attendee
      * event.createAttendee('Buh <buh@example.net>');
      * ```
      *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * BEGIN:VEVENT
+     * UID:b4944f07-98e4-4581-ac80-2589bb20273d
+     * SEQUENCE:0
+     * DTSTAMP:20240212T194232Z
+     * DTSTART:20240212T194232Z
+     * SUMMARY:
+     * ATTENDEE;ROLE=REQ-PARTICIPANT;CN="Hui":MAILTO:hui@example.com
+     * ATTENDEE;ROLE=REQ-PARTICIPANT;CN="Buh":MAILTO:buh@example.net
+     * END:VEVENT
+     * END:VCALENDAR
+     * ```
+     *
      * As with the organizer, you can also add an explicit `mailto` address.
      *
      * ```javascript
@@ -1648,7 +1814,7 @@ declare enum ICalCalendarMethod {
 declare class ICalCalendar {
     private readonly data;
     /**
-     * You can pass options to setup your calendar or use setters to do this.
+     * You can pass options to set up your calendar or use setters to do this.
      *
      * ```javascript
      *  * import ical from 'ical-generator';
@@ -1669,6 +1835,16 @@ declare class ICalCalendar {
      * cal.name('sebbo.net');
      * ```
      *
+     * `cal.toString()` would then produce the following string:
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * NAME:sebbo.net
+     * X-WR-CALNAME:sebbo.net
+     * END:VCALENDAR
+     * ```
+     *
      * @param data Calendar data
      */
     constructor(data?: ICalCalendarData);
@@ -1691,6 +1867,11 @@ declare class ICalCalendar {
      * });
      * ```
      *
+     * `cal.toString()` would then produce the following string:
+     * ```text
+     * PRODID:-//My Company//My Product//EN
+     * ```
+     *
      * @since 0.2.0
      */
     prodId(prodId: ICalCalendarProdIdData | string): this;
@@ -1708,6 +1889,8 @@ declare class ICalCalendar {
      * #### Typescript Example
      * ```typescript
      * import {ICalCalendarMethod} from 'ical-generator';
+     *
+     * // METHOD:PUBLISH
      * calendar.method(ICalCalendarMethod.PUBLISH);
      * ```
      *
@@ -1723,6 +1906,24 @@ declare class ICalCalendar {
      * Set your feed's name. Is used to fill `NAME`
      * and `X-WR-CALNAME` in your iCal file.
      *
+     * ```typescript
+     * import ical from 'ical-generator';
+     *
+     * const cal = ical();
+     * cal.name('Next Arrivals');
+     *
+     * cal.toString();
+     * ```
+     *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * NAME:Next Arrivals
+     * X-WR-CALNAME:Next Arrivals
+     * END:VCALENDAR
+     * ```
+     *
      * @since 0.2.0
      */
     name(name: string | null): this;
@@ -1776,7 +1977,7 @@ declare class ICalCalendar {
      * import ical from 'ical-generator';
      * import {getVtimezoneComponent} from '@touch4it/ical-timezones';
      *
-     * const cal = new ICalCalendar();
+     * const cal = ical();
      * cal.timezone({
      *     name: 'FOO',
      *     generator: getVtimezoneComponent
@@ -1804,6 +2005,10 @@ declare class ICalCalendar {
      * cal.source('http://example.com/my/original_source.ical');
      * ```
      *
+     * ```text
+     * SOURCE;VALUE=URI:http://example.com/my/original_source.ical
+     * ```
+     *
      * @since 2.2.0-develop.1
      */
     source(source: string | null): this;
@@ -1956,6 +2161,14 @@ declare class ICalCalendar {
      * });
      * ```
      *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * X-MY-CUSTOM-ATTR:1337!
+     * END:VCALENDAR
+     * ```
+     *
      * @since 1.9.0
      */
     x(keyOrArray: {
@@ -1971,6 +2184,14 @@ declare class ICalCalendar {
      * calendar.x("X-MY-CUSTOM-ATTR", "1337!");
      * ```
      *
+     * ```text
+     * BEGIN:VCALENDAR
+     * VERSION:2.0
+     * PRODID:-//sebbo.net//ical-generator//EN
+     * X-MY-CUSTOM-ATTR:1337!
+     * END:VCALENDAR
+     * ```
+     *
      * @since 1.9.0
      */
     x(keyOrArray: string, value: string): this;