ical.js

What is ical.js?

ical.js is a JavaScript library for parsing and manipulating iCalendar data. It allows you to create, parse, and manipulate iCalendar files, which are commonly used for calendar events and scheduling.

What are ical.js's main functionalities?

Parsing iCalendar Data

This feature allows you to parse iCalendar data from a string and extract information from it. In this example, we parse an iCalendar string and extract the summary of the first event.

const ICAL = require('ical.js');
const icalData = 'BEGIN:VCALENDAR\nVERSION:2.0\nBEGIN:VEVENT\nSUMMARY:Test Event\nDTSTART:20230301T120000Z\nDTEND:20230301T130000Z\nEND:VEVENT\nEND:VCALENDAR';
const jcalData = ICAL.parse(icalData);
const comp = new ICAL.Component(jcalData);
const vevent = comp.getFirstSubcomponent('vevent');
const summary = vevent.getFirstPropertyValue('summary');
console.log(summary); // Output: Test Event

Creating iCalendar Data

This feature allows you to create iCalendar data programmatically. In this example, we create a new event with a summary, start time, and end time, and then convert it to an iCalendar string.

const ICAL = require('ical.js');
const event = new ICAL.Component(['vcalendar', [], [
  ['vevent', [], [
    ['summary', {}, 'text', 'New Event'],
    ['dtstart', {}, 'date-time', '20230301T120000Z'],
    ['dtend', {}, 'date-time', '20230301T130000Z']
  ]]
]]);
const icalString = event.toString();
console.log(icalString);

Manipulating iCalendar Data

This feature allows you to manipulate existing iCalendar data. In this example, we parse an iCalendar string, update the summary of the first event, and then convert it back to an iCalendar string.

const ICAL = require('ical.js');
const icalData = 'BEGIN:VCALENDAR\nVERSION:2.0\nBEGIN:VEVENT\nSUMMARY:Test Event\nDTSTART:20230301T120000Z\nDTEND:20230301T130000Z\nEND:VEVENT\nEND:VCALENDAR';
const jcalData = ICAL.parse(icalData);
const comp = new ICAL.Component(jcalData);
const vevent = comp.getFirstSubcomponent('vevent');
vevent.updatePropertyWithValue('summary', 'Updated Event');
const updatedIcalString = comp.toString();
console.log(updatedIcalString);

Other packages similar to ical.js

ical

The 'ical' package is a lightweight iCalendar parser for Node.js. It focuses on parsing iCalendar data and extracting information from it. Compared to ical.js, it is simpler and more focused on parsing rather than creating or manipulating iCalendar data.

node-ical

The 'node-ical' package is a comprehensive iCalendar library for Node.js. It supports parsing, creating, and manipulating iCalendar data. It is similar to ical.js in terms of functionality but is designed specifically for Node.js environments.

ical-generator

The 'ical-generator' package is a library for generating iCalendar files in Node.js. It focuses on creating iCalendar data programmatically. Compared to ical.js, it is more specialized in generating iCalendar data rather than parsing or manipulating existing data.

README

jsical - Javascript parser for rfc5545

This is a library to parse the iCalendar format defined in rfc5545, as well as similar formats like vCard.

There are still some issues to be taken care of, but the library works for most cases. If you would like to help out and would like to discuss any API changes, please contact me or create an issue.

The initial goal was to use it as a replacement for libical in the Mozilla Calendar Project, but the library has been written with the web in mind. This library is now called ICAL.js and enables you to do all sorts of cool experiments with calendar data and the web. I am also aiming for a caldav.js when this is done. Most algorithms here were taken from libical. If you are bugfixing this library, please check if the fix can be upstreamed to libical.

Sandbox and Validator

If you want to try out ICAL.js right now, there is a jsfiddle set up and ready to use. Read on for documentation and example links.

There is also a validator that demonstrates how to use the library in a webpage in the sandbox/ subdirectory.

Try the validator online, it always uses the latest copy of ICAL.js.

Installing

You can install ICAL.js via npm, if you would like to use it in Node.js:

npm install ical.js

Alternatively, it is also available via bower for front-end development:

bower install ical.js

ICAL.js has no dependencies and uses fairly basic JavaScript. Therefore, it should work in all versions of Node.js and modern browsers. It does use getters and setters, so the minimum version of Internet Explorer is 9.

Documentation

For a few guides with code samples, please check out the wiki. If you prefer, full API documentation is available here. If you are missing anything, please don't hesitate to create an issue.

Developing

To contribute to ICAL.js you need to set up the development environment. This requires Node.js 10.x or later and grunt. Run the following steps to get started.

Preferred way (to match building and packaging with official process):

yarn global add grunt-cli  # Might need to run with sudo
yarn --frozen-lockfile

Alternative way:

npm install -g grunt-cli  # Might need to run with sudo
npm install .

You can now dive into the code, run the tests and check coverage.

Tests

Tests can either be run via Node.js or in the browser, but setting up the testing infrastructure requires node. More information on how to set up and run tests can be found on the wiki.

in Node.js

The quickest way to execute tests is using Node.js. Running the following command will run all test suites: performance, acceptance and unit tests.

grunt test-node

You can also select a single suite, or run a single test.

grunt test-node:performance
grunt test-node:acceptance
grunt test-node:unit

grunt test-node:single --test=test/parse_test.js

Appending the --debug option to any of the above commands will run the test(s) with node-inspector. It will start the debugging server and open it in Chrome or Opera, depending on what you have installed. The tests will pause before execution starts so you can set breakpoints and debug the unit tests you are working on.

If you run the performance tests comparison will be done between the current working version (latest), a previous build of ICAL.js (previous) and the unchanged copy of build/ical.js (from the master branch). See the wiki for more details.

in the browser

To run the browser tests, we are currently using karma. To run tests with karma, you can run the following targets:

grunt test-browser           # run all tests
grunt karma:unit             # run only the unit tests
grunt karma:acceptance       # run only the acceptance tests

Now you can visit http://localhost:9876 in your browser. The test output will be shown in the console you started the grunt task from. You can also run a single test:

grunt karma:single --test=test/parse_test.js

The mentioned targets all run the tests from start to finish. If you would like to debug the tests instead, you can add the --debug flag. Once you open the browser there will be a "debug" button. Clicking on the button opens am empty page, but if you open your browser's developer tools you will see the test output. You can reload this page as often as you want until all tests are running.

Last off, if you add the --remote option, karma will listen on all interfaces. This is useful if you are running the browser to test in a VM, for example when using Internet Exporer VM images.

Code Coverage

ICAL.js is set up to calculate code coverage. You can view the coverage results online, or run them locally to make sure new code is covered. Running grunt coverage will run the unit test suite measuring coverage. You can then open coverage/lcov-report/index.html to view the results in your browser.

Linters

To make sure all ICAL.js code uses a common style, please run the linters using grunt linters. Please make sure you fix any issues shown by this command before sending a pull request.

Documentation

You can generate the documentation locally, this is also helpful to ensure the jsdoc you have written is valid. To do so, run grunt jsdoc. You will find the output in the api/ subdirectory.

Packaging

When you are done with your work, you can run grunt package to create the single-file build for use in the browser, including its minified counterpart and the source map.

License

ical.js is licensed under the Mozilla Public License, version 2.0.