# ical-expander

> ICS / iCal / iCalendar parser / expander

Latest version **3.2.0** (published 2025-10-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install ical-expander
pnpm add ical-expander
yarn add ical-expander
bun add ical-expander
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.2.0 |
| Published | 2025-10-02 |
| First published | 2017-03-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=4 |
| Dependencies | 1 |
| Unpacked size | 131.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 72 |
| Author | Mikael Finstad |
| Maintainers | mifi |

## Links

- npm: https://www.npmjs.com/package/ical-expander
- Repository: https://github.com/mifi/ical-expander
- Homepage: https://github.com/mifi/ical-expander#readme
- Issues: https://github.com/mifi/ical-expander/issues
- npm.io page: https://npm.io/package/ical-expander

## Dependencies (1)

- [ical.js](https://npm.io/package/ical.js.md) ^1.2.2

## Recent versions

- 3.2.0 (latest) — 2025-10-02
- 3.1.0 — 2020-12-08
- 3.0.0 — 2020-04-24
- 2.1.0 — 2019-12-03
- 2.0.0 — 2018-05-19
- 1.1.2 — 2017-10-21
- 1.1.1 — 2017-10-21
- 1.1.0 — 2017-05-29
- 1.0.1 — 2017-03-29
- 1.0.0 — 2017-03-29

## README

# ical-expander 📅 [![npm version](https://badge.fury.io/js/ical-expander.svg)](https://badge.fury.io/js/ical-expander) ![Test local branches](https://github.com/mifi/ical-expander/workflows/Test%20local%20branches/badge.svg) [![](https://mifi.github.io/ical-expander-coverage/coverage-badge.svg)](https://mifi.github.io/ical-expander-coverage) [![Known Vulnerabilities](https://snyk.io/test/github/mifi/ical-expander/badge.svg)](https://snyk.io/test/github/mifi/ical-expander)
ICS / iCal / iCalendar parser / expander.

Wrapper around [ical.js](https://github.com/mozilla-comm/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](https://www.iana.org/time-zones), so that it parses correctly when a timezone definition is not available in the ICS file itself. `zones.json` can be found [here](https://hg.mozilla.org/comm-central/file/tip/calendar/timezones/zones.json) 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.

## Install

```
npm install ical-expander
```

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

## Example

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 = events.events.map(e => ({ startDate: e.startDate, summary: e.summary }));
const mappedOccurrences = events.occurrences.map(o => ({ startDate: o.startDate, summary: o.item.summary }));
const allEvents = [].concat(mappedEvents, mappedOccurrences);

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

## Usage
### Constructor
```
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!__)

### between()
```
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
```


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

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

### all()
`icalExpander.all()` is an alias for `icalExpander.between()`  
__Do not run this with `maxIterations: 0`__

### Return value
All methods return:
```
{
  events: [],
  occurrences: [],
}
```
- `events` is a list of [ICAL.Event](http://mozilla-comm.github.io/ical.js/api/ICAL.Event.html) objects.
- `occurrences` is a list of [ICAL.Event.occurrenceDetails](http://mozilla-comm.github.io/ical.js/api/ICAL.Event.html#.occurrenceDetails) objects.

### icalExpander.component
Root [ICAL.Component](http://mozilla-comm.github.io/ical.js/api/ICAL.Component.html) from parsed data.

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

## See also:
- https://github.com/mozilla-comm/ical.js/issues/294
- https://nylas.com/blog/rrules/
- https://github.com/jakubroztocil/rrule

---
_Source: https://npm.io/package/ical-expander · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
