ics

ics

The iCalendar generator

Install

npm install -S ics

Example Usage

In node / CommonJS

1. Create an iCalendar event:

…

1. Write an iCalendar file:

…

1. Create multiple iCalendar events:

…

3b) Create multiple events asynchronously (large batches):

createEventsAsync returns a Promise that resolves to { error, value } (there is no callback form). While building the calendar it yields to the event loop periodically, which helps keep huge event lists from blocking Node or the browser for too long.

const { createEventsAsync } = require('ics')

async function run () {
  const { error, value } = await createEventsAsync([
    {
      title: 'Lunch',
      start: [2018, 1, 15, 12, 15],
      duration: { minutes: 45 }
    },
    {
      title: 'Dinner',
      start: [2018, 1, 15, 12, 15],
      duration: { hours: 1, minutes: 30 }
    }
  ])

  if (error) {
    console.log(error)
    return
  }

  console.log(value)
}

run()

An empty event list and optional calendar header work the same as with createEvents:

createEventsAsync([], { calName: 'My calendar' }).then(({ error, value }) => {
  if (error) console.log(error)
  else console.log(value)
})

1. Create iCalendar events with Audio (Mac):

…

Using ESModules & in the browser

…

API

createEvent(attributes[, callback])

Generates an iCal-compliant VCALENDAR string with one VEVENT. If a callback is not provided, returns an object having the form { error, value }, where value contains an iCal-compliant string if there are no errors. If a callback is provided, returns a Node-style callback.

attributes

Object literal containing event information. Only the start property is required.

Note all date/time fields can be the array form, or a number representing the unix timestamp in milliseconds (e.g. getTime() on a Date).

The following properties are accepted:

To create an all-day event, pass only three values (year, month, and date) to the start and end properties. The date of the end property should be the day after your all-day event. For example, in order to create an all-day event occuring on October 15, 2018:

const eventAttributes = {
  start: [2018, 10, 15],
  end: [2018, 10, 16],
  /* rest of attributes */
}

callback

Optional. Node-style callback.

function (err, value) {
  if (err) {
    // if iCal generation fails, err is an object containing the reason
    // if iCal generation succeeds, err is null
  }

  console.log(value) // iCal-compliant text string
}

createEvents(events[, headerParams, callback])

Generates an iCal-compliant VCALENDAR string with multiple VEVENTS.

headerParams may be omitted, and in this case they will be read from the first event.

If a callback is not provided, returns an object having the form { error, value }, where value is an iCal-compliant text string if error is null.

If a callback is provided, returns a Node-style callback.

events

Array of attributes objects (as described in createEvent).

callback

Optional. Node-style callback.

function (err, value) {
  if (err) {
    // if iCal generation fails, err is an object containing the reason
    // if iCal generation succeeds, err is null
  }

  console.log(value) // iCal-compliant text string
}

createEventsAsync(events[, headerAttributes])

Async variant of createEvents. Resolves to an object { error, value } where value is an iCal-compliant string when error is null. There is no callback overload.

events is an array of the same attributes objects as in createEvent. The optional headerAttributes object is merged with the first event when events is non-empty, or used alone to build the calendar header when events is empty (same behavior as createEvents).

While iterating events, the implementation yields to the event loop at intervals so very large batches are less likely to freeze the process. It also builds the output in parts and joins once at the end to reduce string concatenation overhead.

Develop

Run mocha tests and watch for changes:

npm start

Run tests once and exit:

npm test

Build the project, compiling all ES6 files within the src directory into vanilla JavaScript in the dist directory.

npm run build

References

• RFC 5545: Internet Calendaring and Scheduling Core Object Specification (iCalendar)
• iCalendar Validator