Awesome Open Source
Awesome Open Source

ical-expander 📅 npm version Test local branches Known Vulnerabilities

ICS / iCal / iCalendar parser / expander.

Wrapper around ical.js that automatically handles EXDATE (excluded recursive occurrences), RRULE and recurring events overridden by RECURRENCE-ID.

Also handles timezones, and includes timezones from the IANA Time Zone Database, so that it parses correctly when a timezone definition is not available in the ICS file itself. zones.json can be found here and compiled by running compile-zones.js.

Be careful as the processing done in this library is synchronous and will block the JS event loop while processing. Especially when processing large ICS files and with high maxIterations values.


npm install ical-expander

⚠️ Warning: This package uses ES6 features, and might require transpiling if used in browsers


Download .ics from google calendar for example.

const IcalExpander = require('ical-expander');
const fs = require('fs');

const ics = fs.readFileSync('./basic.ics', 'utf-8');

const icalExpander = new IcalExpander({ ics, maxIterations: 100 });
const events = icalExpander.between(new Date('2017-01-24T00:00:00.000Z'), new Date('2017-03-30T00:00:00.000Z'));

const mappedEvents = => ({ startDate: e.startDate, summary: e.summary }));
const mappedOccurrences = => ({ startDate: o.startDate, summary: o.item.summary }));
const allEvents = [].concat(mappedEvents, mappedOccurrences);

console.log( => `${e.startDate.toJSDate().toISOString()} - ${e.summary}`).join('\n'));



const icalExpander = new IcalExpander({ ics, maxIterations })
  • ics: String containing ICS data to parse
  • maxIterations: Max iterations on each RRULE. Defaults to 1000 (undefined or null). 0 means never stop (be careful!)


icalExpander.between(after, before)

Include all events occuring between after and before. i.e. with a start time before before JS Date and an end time after JS Date.

  • after JS Date: Start of range. Default: No start limit.
  • before JS Date. End of range. Default: No end limit. Do not run with no end limit and maxIterations: 0

Example of events included between a date range:

range:    ---------- after |-----------------------| before -------------
event 1:                   |          start <------|------------> end
event 2:         start <---|---------------> end   |
event 3:      start <------|-----------------------|--------------> end
event 4:                   |    start <---> end    |                                                   

Example of events not included between a date range:

range:    -------------------- after |--------| before ------------------
event 5:  start <------> end         |        |
event 6:                             |        |          start <---> end


icalExpander.before(before) is an alias for icalExpander.between(undefined, before)


icalExpander.after() is an alias for icalExpander.between(after)


icalExpander.all() is an alias for icalExpander.between()
Do not run this with maxIterations: 0

Return value

All methods return:

  events: [],
  occurrences: [],


Root ICAL.Component from parsed data.


  • RECURRENCE-ID: check that within same day?
  • Get data from moment-timezone instead?

See also:

Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Javascript (1,155,559
Calendar (9,974
Aliases (6,852
Timezone (2,360
Ics (1,095
Ical (747
Icalendar (561
Rrule (29
Recurring (28