CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-ical-js

Javascript parser for ics (rfc5545) and vcard (rfc6350) data

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

ical.js

ical.js is a comprehensive JavaScript library for parsing and working with iCalendar (RFC 5545), jCal (RFC 7265), vCard (RFC 6350), and jCard (RFC 7095) data formats. It serves as a replacement for libical in web-based calendar applications, enabling developers to parse, manipulate, and generate calendar and contact data directly in JavaScript environments including browsers and Node.js.

Package Information

  • Package Name: ical.js
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install ical.js

Core Imports

import ICAL from "ical.js";

For CommonJS:

const ICAL = require("ical.js");

Individual imports:

import { parse, stringify, Component, Event, Time } from "ical.js";

Basic Usage

import ICAL from "ical.js";

// Parse iCalendar data
const icalData = `BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example//Example//EN
BEGIN:VEVENT
UID:12345@example.com
DTSTART:20231201T120000Z
DTEND:20231201T130000Z
SUMMARY:Team Meeting
DESCRIPTION:Weekly team standup
END:VEVENT
END:VCALENDAR`;

const jcalData = ICAL.parse(icalData);
const vcalendar = new ICAL.Component(jcalData);
const vevent = vcalendar.getFirstSubcomponent("vevent");
const event = new ICAL.Event(vevent);

console.log(event.summary); // "Team Meeting"
console.log(event.startDate.toString()); // Start date
console.log(event.endDate.toString()); // End date

// Generate iCalendar data
const newEvent = new ICAL.Component("vevent");
newEvent.addPropertyWithValue("uid", "new-event@example.com");
newEvent.addPropertyWithValue("summary", "New Meeting");
newEvent.addPropertyWithValue("dtstart", ICAL.Time.now());

const newCalendar = new ICAL.Component("vcalendar");
newCalendar.addPropertyWithValue("version", "2.0");
newCalendar.addPropertyWithValue("prodid", "-//Example//Example//EN");
newCalendar.addSubcomponent(newEvent);

const icalString = ICAL.stringify(newCalendar.jCal);
console.log(icalString);

Architecture

ical.js is built around several key architectural components:

  • Parsing Engine: Core parse() and stringify() functions that convert between iCalendar/vCard strings and jCal/jCard objects
  • Component System: Object-oriented wrappers (Component, Property, Event) that provide convenience methods for manipulating calendar data
  • Time Representation: Timezone-aware time handling (Time, VCardTime, Duration, Period) with full RFC compliance
  • Recurrence Engine: Comprehensive recurrence rule processing (Recur, RecurExpansion, RecurIterator) for repeating events
  • Timezone Management: Complete timezone support (Timezone, TimezoneService, UtcOffset) with VTIMEZONE component handling
  • Design System: Pluggable design sets for different data formats (iCalendar, vCard 3.0, vCard 4.0)

Capabilities

Core Parsing and Serialization

High-level parsing and serialization functions for converting between iCalendar/vCard strings and structured jCal/jCard objects.

function parse(input: string): object | object[];
function stringify(jCal: array): string;

Core Parsing

Time and Date Handling

Comprehensive time representation classes for handling dates, times, durations, and periods with full timezone support and RFC compliance.

class Time {
  constructor(data?: object, zone?: Timezone);
  static fromString(aValue: string, aProperty?: Property): Time;
  static fromJSDate(aDate: Date, useUTC?: boolean): Time;
  static now(): Time;
}

class Duration {
  constructor(data?: object);
  static fromString(aStr: string): Duration;
  static fromSeconds(aSeconds: number): Duration;
}

Time and Date Handling

Calendar Components and Properties

Object-oriented wrappers for working with calendar components and properties, providing convenient methods for manipulation and access.

class Component {
  constructor(jCal: array, parent?: Component);
  static fromString(str: string): Component;
  getFirstSubcomponent(name: string): Component | null;
  getFirstProperty(name: string): Property | null;
  addSubcomponent(component: Component): void;
  addPropertyWithValue(name: string, value: any): Property;
}

class Event {
  constructor(component: Component, options?: object);
  get summary(): string;
  get startDate(): Time;
  get endDate(): Time;
  iterator(startTime?: Time): RecurExpansion;
}

Calendar Components

Recurrence Rule Processing

Complete implementation of RFC 5545 recurrence rules with expansion engines for generating recurring event instances.

class Recur {
  constructor(data?: object);
  static fromString(string: string): Recur;
  iterator(aStart: Time): RecurIterator;
  getNextOccurrence(aStartTime: Time, aRecurrenceId?: Time): Time;
}

class RecurExpansion {
  constructor(options: object);
  next(): Time | null;
}

Recurrence Processing

Timezone Management

Comprehensive timezone handling with support for VTIMEZONE components, UTC offset calculations, and timezone conversions.

class Timezone {
  constructor(data?: object);
  static fromData(aData: object): Timezone;
  static get utcTimezone(): Timezone;
  static get localTimezone(): Timezone;
  utcOffset(tt: Time): number;
}

const TimezoneService: {
  get(tzid: string): Timezone | null;
  register(timezone: Timezone, name?: string): void;
  reset(): void;
};

Timezone Management

Utility Functions and Helpers

Various utility classes and helper functions for specialized data handling, binary data processing, and internal operations.

class Binary {
  constructor(aValue?: string);
  static fromString(aString: string): Binary;
  decodeValue(): string;
  toString(): string;
}

const helpers: {
  updateTimezones(vcal: Component): void;
  clone(aSrc: any, aDeep?: boolean): any;
  foldline(aLine: string): string;
};

const design: {
  strict: boolean;
  defaultSet: object;
  icalendar: object;
  vcard: object;
  vcard3: object;
};

Utilities and Helpers

Configuration

ical.js provides several global configuration options:

ICAL.foldLength = 75;     // Characters before line folding
ICAL.debug = false;       // Debug mode flag  
ICAL.newLineChar = '\r\n'; // Line ending characters

Error Handling

The library may throw various errors during parsing and processing:

  • ParserError: Thrown during invalid iCalendar/vCard parsing
  • ComponentError: Thrown for invalid component operations
  • ValueError: Thrown for invalid property values or parameters

Always wrap parsing operations in try-catch blocks when working with untrusted input data.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ical.js@2.2.x
Publish Source
CLI
Badge
tessl/npm-ical-js badge