Registry / serialization / ical-expander

ical-expander

JSON →
library3.2.0jsnpmunverified

ical-expander is a JavaScript/TypeScript library designed for parsing and expanding iCalendar (ICS) data. It acts as a wrapper around the `ical.js` library, simplifying the complexities of recurring events by automatically handling `EXDATE` (excluded occurrences), `RRULE` (recurrence rules), and `RECURRENCE-ID` (overridden instances). The package also incorporates timezone definitions from the IANA Time Zone Database, ensuring correct parsing even when timezone information is absent from the ICS file itself. The current stable version is 3.2.0, with a release cadence that indicates active maintenance and incremental improvements, such as recent updates to timezone data and fixes related to `ical.js` versions. A key consideration is its synchronous processing model, which can block the JavaScript event loop when dealing with large ICS files or high `maxIterations` values, requiring careful usage, particularly in performance-sensitive applications. Its primary differentiator is abstracting away the intricacies of `ical.js` for common expansion tasks.

serialization
npm install ical-expander
github ↗package ↗
INSTALL
IMPORT
SIG · ICAL-EXPANDER
I
ical-expander
serializationjavascriptv3.2.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

IcalExpander
✓ import { IcalExpander } from 'ical-expander';
✗ import IcalExpander from 'ical-expander';
The primary class `IcalExpander` is a named export, not a default export.
IcalExpander (CommonJS)
✓ const IcalExpander = require('ical-expander');
✗ const { IcalExpander } = require('ical-expander');
In CommonJS environments, the module export is directly the IcalExpander class, not an object containing it.
IcalExpander (TypeScript Type)
✓ import type { IcalExpander } from 'ical-expander';
Explicit type import for TypeScript for better tree-shaking and clarity, though `import { IcalExpander } from 'ical-expander';` works for both value and type.

This example demonstrates how to load an ICS file, parse it using IcalExpander, and then retrieve all events and occurrences within a specified date range, logging their start dates and summaries.

const IcalExpander = require('ical-expander'); const fs = require('fs'); // Assuming 'basic.ics' exists in the same directory 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.toJSDate().toISOString(), // Convert to JS Date and then ISO string summary: e.summary })); const mappedOccurrences = events.occurrences.map(o => ({ startDate: o.startDate.toJSDate().toISOString(), // Convert to JS Date and then ISO string summary: o.item.summary })); const allEvents = [].concat(mappedEvents, mappedOccurrences); console.log(allEvents.map(e => `${e.startDate} - ${e.summary}`).join('\n'));
Debug
Known issues
gotchaThe library performs synchronous processing, which can block the JavaScript event loop. This is particularly problematic when parsing very large ICS files or setting a high `maxIterations` value.
fix
For large ICS files, consider processing in a worker thread (e.g., Worker Threads in Node.js, Web Workers in browsers) to offload the synchronous work from the main thread. Keep `maxIterations` to a reasonable, bounded value.
affects: >=1.0.0
gotchaUsing `maxIterations: 0` in the constructor disables the iteration limit, which can lead to infinite loops or extremely long processing times for complex or malformed recurrence rules.
fix
Always provide a finite, reasonable `maxIterations` value (default is 1000). Only set to `0` if you are absolutely certain of the ICS file's structure and performance implications, and can implement external timeouts.
affects: >=1.0.0
gotchaThis package uses ES6 features. If targeting environments that do not fully support ES6 (e.g., older browsers), you might need to transpile `ical-expander` along with your application code.
fix
Configure your build tools (e.g., Babel, Webpack) to transpile `node_modules/ical-expander` if necessary for your target environments.
affects: >=1.0.0
breakingVersion 3.0.0 introduced an update to `ical.js` to correctly handle modified recurrences. This change, while fixing previous bugs, might alter the output for specific edge cases involving `RECURRENCE-ID` if your application relied on the prior (potentially incorrect) behavior.
fix
Thoroughly test your application's event parsing logic after upgrading to `3.0.0` or later, especially for calendars containing events with modified recurring instances (`RECURRENCE-ID`).
affects: >=3.0.0
gotchaVersion 3.1.0 included an update to the IANA timezone data (`zones` and `zones-compiled`). While typically an improvement, this could subtly change the interpretation of timezones for certain events, especially those at daylight saving time boundaries or in historically complex timezones.
fix
If your application is sensitive to precise timezone interpretations, verify event parsing for critical dates and timezones after upgrading to `3.1.0` or later.
affects: >=3.1.0
Errors
Common errors & fixes
TypeError: IcalExpander is not a constructor
Incorrect import statement; `IcalExpander` is a named export, not a default export in ESM, and directly exported in CJS.
fix
For ESM/TypeScript: `import { IcalExpander } from 'ical-expander';`. For CommonJS: `const IcalExpander = require('ical-expander');`.
TypeError: Cannot read properties of undefined (reading 'map')
This usually happens when `events.events` or `events.occurrences` are undefined, which can occur if the `between()` method returns an unexpected structure, possibly due to a malformed ICS or an empty result set that wasn't properly handled.
fix
Ensure the ICS content is valid. Add checks for `events.events` and `events.occurrences` being defined before attempting to map them, e.g., `(events.events || []).map(...)`.
Application becomes unresponsive or hangs when parsing ICS files.
The synchronous nature of `ical-expander` blocks the main thread, especially with large ICS files or when `maxIterations` is set very high (or to `0`).
fix
Reduce `maxIterations` to a reasonable value. For very large files, process the ICS data in a Web Worker (browser) or Worker Thread (Node.js) to avoid blocking the main event loop.
Upgrade
Version history
3.2.0latest on npm
Audit
Dependencies
ical.jsrequiredCore parsing logic; ical-expander is a wrapper around this library for enhanced recurrence handling and timezone support.
Agent activity
8 hits · last 30 days
node
8
Resources
githubhttps://github.com/mifi/ical-expander ↗
packagehttps://www.npmjs.com/package/ical-expander ↗
ical-expander — npm install ical-expander · libregistry