ical.js

The core ical.js library does not include timezone definitions to keep the package size small. If your iCalendar files do not include timezone definitions and you need to perform timezone conversions, you must use ical.timezones.js (or its minified version).

Note: ical.timezones.js is not included in the standard distribution because it contains IANA timezone definitions that change regularly. You may need to build your own or find a recent build.

You can test ical.js functionality using these online tools:

• JSFiddle: A sandbox environment to try out the library code.
• ICAL Validator: A tool to verify iCalendar and jCal files using the library.
• Recurrence Tester: A tool to calculate occurrences based on an RRULE, useful for testing the recurrence iterator.

To use ical.js in a Node.js environment, install it using npm. The library has no dependencies and is written in modern JavaScript.

npm install ical.js

ICALTester is a tool used to compare different iCalendar recurrence implementations against ical.js. It works by generating random rules based on a configuration file and running them through a target binary or executable.

To run the comparison, use node compare.js with two arguments:

1. The path to a rules.json file defining the rule patterns.
2. The path to the binary/executable you wish to compare against ical.js.

$ node compare.js rules.json ./support/libical-recur

If you are working in a modern browser environment, you can import ical.js as an ES6 module directly from a CDN like unpkg. Use the type="module" attribute in your script tag.

<script type="module">
  import ICAL from "https://unpkg.com/ical.js/dist/ical.min.js";
  document.querySelector("button").addEventListener("click", () => {
    ICAL.parse(document.getElementById("txt").value);
  });
</script>

If you cannot use ES6 modules, you can use the transpiled ES5 version via a standard script tag. This version is available as a CommonJS-compatible file (.cjs).

<script src="https://unpkg.com/ical.js/dist/ical.es5.min.cjs"></script>
<textarea id="txt"></textarea>
<button onclick="ICAL.parse(document.getElementById('txt').value)"></button>

A designSet is used by the parser and stringifier to determine how values, parameters, and properties are represented. This is a core configuration object for customizing how iCalendar/jCard data is handled.

Properties:

• value (Object): Definitions for value types (keys are type names).
• param (Object): Definitions for parameters (keys are parameter names).
• property (Object): Definitions for properties (keys are property names).
• propertyGroups (Boolean): Indicates if content lines may include a group name.

The rules.json file defines the structure of the recurrence rules to be tested. The format follows the same structure required by ICAL.Recur.fromData().

To introduce randomness into the testing, you can use the % character as a value. When the tester encounters %, it will generate a random valid value for that specific property. This allows for fuzz-testing various combinations of recurrence rules.

[
  { "freq": "MONTHLY", "bymonthday": "%" }
]

When creating or initializing an ICAL.Time instance, you can provide a timeInit object. This object allows you to specify the date and time components.

Properties:

• year (Number): The year for this date.
• month (Number): The month for this date.
• day (Number): The day for this date.
• hour (Number): The hour for this date.
• minute (Number): The minute for this date.
• second (Number): The second for this date.
• isDate (Boolean): If true, the instance represents a date (as opposed to a date-time).

After installing via npm, import the ICAL object to access the parsing and utility methods.

import ICAL from "ical.js";

Any binary used with ICALTester must accept three positional arguments and output a list of occurrences in a specific format.

Arguments:

1. <rrule>: The recurrence rule string (e.g., "FREQ=MONTHLY;BYDAY=1FR,3SU").
2. <dtstart>: The start date/time string (e.g., "2014-11-11T08:00:00").
3. <occurrence count>: An integer representing how many occurrences to calculate.

Output Format: A list of timestamps, one per line, in the format YYYYMMDDTHHMMSS.

# Usage: <binary> <rrule> <dtstart> <occurrence count>
$ ./support/libical-recur "FREQ=MONTHLY;BYDAY=1FR,3SU" "2014-11-11T08:00:00" 10
20141116T080000
20141205T080000
...

When the parser encounters malformed data, it throws a ParserError. You should wrap your parsing logic in a try...catch block to handle these gracefully. Common causes for ParserError include:

• Unclosed components (e.g., BEGIN without END).
• Invalid parameters in a line.
• Missing parameter values.
• Lines that do not contain a valid token (missing : or ;).
• Unmatched double quotes in parameters.

import ICAL from 'ical.js';

try {
  const jcal = ICAL.parse('INVALID_DATA_WITHOUT_DELIMITERS');
} catch (err) {
  if (err instanceof ICAL.parse.ParserError) {
    console.error('Parsing failed:', err.message);
  } else {
    throw err;
  }
}