@filecage/ical

This is a library to parse and read iCalendar files (.ics, .ical). Unlike other solutions, it is fully typed and thus provides a pleasant type hinting experience. It was built along the RFC standard definitions and validates raw input while parsing.

It implements RFC 5545, RFC 6868, RFC 7986 and RFC 9074.

Values are normalized where possible (e.g. possible list values are always accessed as array), but it does not interpret values (like timezone references) apart from the value encoding defined in RFC 5545 and RFC 6868. You'll need to handle these yourself.

Note

This is a very early development release. The interface is still experimental and many things might not yet work as expected.

Install via npm

npm i --save @filecage/ical

Warning

RFC compliance and validation strictness in development versions are not guaranteed. Anything can change at any time until release 1.x.

Why?

There are several existing parsers for iCalendar/ICS formats, but none of them met my expectations in neither the interface, the level of provided types nor RFC standard compliance.

Usage

Parsers

Two different functions exist to parse your calendar:

By File

import {parseFile} from '@filecage/ical/parse';

const calendar = await parseFile('my-calendar.ics');

By String

import {parseString} from '@filecage/ical/parse';

const calendar = await parseString(`
BEGIN:VCALENDAR
PRODID:MyCalendar
VERSION:2.0
END:VCALENDAR
`);

Getters

To navigate the raw ICS structure, the library exports the Getters package with some useful helpers:

• getDateFromDateTime to evaluate a DateTime and resolve the date/datetime from the ICS to a JS Date object
• getEventEndDateTime to evaluate the ending time of an event based on DTEND or DURATION
• iterateRecurrences to iterate over RRULE (with basic functionality, see #15 for limitations)
• getSecondsFromDuration to get the number of seconds from a DURATION ICS type
• getLocalOffsetForDateTime to find the applicable timezone offset for a DateTime object, based on UTC/floating times or TZID timezone references in the ICS