or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

component-parser.mdcomponents.mddesign-system.mdduration.mdevents.mdhelpers.mdindex.mdparsing.mdperiod-binary.mdproperties.mdrecurrence.mdtime.mdtimezone.mdvcard-time.md
tile.json

index.mddocs/

ICAL.js

ICAL.js is a comprehensive JavaScript parser for iCalendar (RFC 5545) and vCard (RFC 6350) data formats. Originally designed as a replacement for libical in the Mozilla Calendar Project, this web-focused library enables parsing, manipulation, and generation of calendar data with zero dependencies. It provides complete JavaScript-based solutions for calendar applications supporting all major calendar features including events, todos, recurring patterns, timezones, and VTIMEZONE definitions.

Package Information

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

Core Imports

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

For browser usage:

<script src="ical.js"></script>
<!-- ICAL namespace is now available globally -->

Basic Usage

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

// Parse an iCalendar string
const icalString = `BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp//Example Client//EN
BEGIN:VEVENT
UID:example@example.com
DTSTART:20230615T100000Z
DTEND:20230615T110000Z
SUMMARY:Team Meeting
DESCRIPTION:Weekly team sync
END:VEVENT
END:VCALENDAR`;

// Parse to jCal format
const jcalData = ICAL.parse(icalString);

// Create component wrapper
const vcalendar = new ICAL.Component(jcalData);

// Get the first event
const vevent = vcalendar.getFirstSubcomponent('vevent');

// Create high-level Event object
const event = new ICAL.Event(vevent);

console.log(event.summary);     // "Team Meeting"
console.log(event.startDate);   // ICAL.Time object
console.log(event.endDate);     // ICAL.Time object

// Serialize back to iCalendar string
const serialized = vcalendar.toString();

Architecture

ICAL.js is organized into multiple layers providing different levels of abstraction:

  • Raw Data Layer: jCal/jCard JSON representation of calendar data
  • Component/Property Layer: 
    ICAL.Component
    and 
    ICAL.Property
    classes for structured manipulation
  • High-Level API: 
    ICAL.Event
    , 
    ICAL.Time
    , 
    ICAL.Duration
    classes for semantic operations
  • Parsing/Serialization: 
    ICAL.parse
    and 
    ICAL.stringify
    for format conversion
  • Recurrence Engine: 
    ICAL.Recur
    , 
    ICAL.RecurIterator
    for handling recurring events
  • Timezone Support: 
    ICAL.Timezone
    , 
    ICAL.TimezoneService
    for timezone-aware operations

Capabilities

Parsing and Serialization

Core parsing functionality for converting between iCalendar/vCard strings and JavaScript objects, with support for both jCal/jCard JSON formats and native string formats.

// Parse iCalendar/vCard string to jCal/jCard array
function parse(input: string): Array;

// Convert jCal/jCard array back to iCalendar/vCard string
function stringify(jCal: Array): string;

Parsing and Serialization

Component Manipulation

Structured access to iCalendar and vCard components with methods for adding, removing, and querying properties and subcomponents.

class Component {
  constructor(jCal: Array | string, parent?: Component);
  
  // Static methods
  static fromString(str: string): Component;
  
  // Properties
  readonly name: string;
  jCal: Array;
  
  // Component methods
  getAllSubcomponents(name?: string): Component[];
  getFirstSubcomponent(name: string): Component;
  addSubcomponent(component: Component): Component;
  removeSubcomponent(component: Component): boolean;
  
  // Property methods
  getAllProperties(name?: string): Property[];
  getFirstProperty(name: string): Property;
  getFirstPropertyValue(name: string): any;
  addProperty(property: Property): Property;
  removeProperty(property: Property): boolean;
  hasProperty(name: string): boolean;
  updatePropertyWithValue(name: string, value: any): Property;
  
  toString(): string;
}

Component Manipulation

Property Management

Detailed property manipulation including parameters, multi-values, and type-specific value handling.

class Property {
  constructor(jCal: Array | string, parent?: Component);
  
  // Static methods
  static fromString(str: string, designSet?: Object): Property;
  
  // Properties
  readonly name: string;
  type: string;
  jCal: Array;
  
  // Parameter methods
  getParameter(name: string): string;
  setParameter(name: string, value: string): void;
  removeParameter(name: string): void;
  getParameterIterator(): Object;
  
  // Value methods
  getFirstValue(): any;
  getValues(): Array;
  setValue(value: any): void;
  setValues(values: Array): void;
  getDefaultType(): string;
  
  toICALString(): string;
}

Property Management

Time and Date Handling

Comprehensive time representation with timezone support, date arithmetic, and calendar calculations.

class Time {
  constructor(data?: Object, zone?: Timezone);
  
  // Static methods
  static now(): Time;
  static fromString(str: string): Time;
  static fromJSDate(date: Date, useUTC?: boolean): Time;
  static fromData(data: Object): Time;
  static weekOneStarts(year: number, wkst: number): number;
  static getDominicalLetter(year: number): string;
  static isLeapYear(year: number): boolean;
  
  // Static constants
  static readonly SUNDAY: number;
  static readonly MONDAY: number;
  static readonly TUESDAY: number;
  static readonly WEDNESDAY: number;
  static readonly THURSDAY: number;
  static readonly FRIDAY: number;
  static readonly SATURDAY: number;
  
  // Properties
  year: number;
  month: number;
  day: number;
  hour: number;
  minute: number;
  second: number;
  isDate: boolean;
  zone: Timezone;
  readonly icaltype: string;
  
  // Methods
  clone(): Time;
  reset(): void;
  fromData(data: Object, zone?: Timezone): void;
  dayOfWeek(): number;
  dayOfYear(): number;
  weekNumber(weekStart: number): number;
  addDuration(duration: Duration): void;
  subtractDate(other: Time): Duration;
  compare(other: Time): number;
  normalize(): void;
  toJSDate(): Date;
  toUnixTime(): number;
  toString(): string;
}

Time and Date Handling

Event Management

High-level event representation with recurrence pattern support, exception handling, and occurrence calculation.

class Event {
  constructor(component?: Component, options?: Object);
  
  // Properties
  component: Component;
  summary: string;
  startDate: Time;
  endDate: Time;
  duration: Duration;
  location: string;
  attendees: Array;
  organizer: Property;
  uid: string;
  exceptions: Object;
  strictExceptions: boolean;
  
  // Methods
  isRecurring(): boolean;
  isRecurrenceException(): boolean;
  relateException(obj: Component | Event): void;
  modifiesFuture(): boolean;
  findRangeException(time: Time): Event;
  getOccurrenceDetails(occurrence: Time): Object;
  getRecurrenceTypes(): Object;
  isOnDay(day: Time): boolean;
  toString(): string;
}

Event Management

Recurrence Patterns

Complete recurrence rule processing with support for complex patterns, iterators, and expansion with exceptions.

class Recur {
  constructor(data?: Object);
  
  // Static methods
  static fromString(str: string): Recur;
  static fromData(data: Object): Recur;
  
  // Properties
  freq: string;
  interval: number;
  wkst: number;
  until: Time;
  count: number;
  bysecond: Array;
  byminute: Array;
  byhour: Array;
  byday: Array;
  bymonthday: Array;
  byyearday: Array;
  byweekno: Array;
  bymonth: Array;
  bysetpos: Array;
  
  // Methods
  clone(): Recur;
  isFinite(): boolean;
  isByCount(): boolean;
  addComponent(part: string, value: any): void;
  setComponent(part: string, value: any): void;
  getComponent(part: string): any;
  getNextOccurrence(startTime: Time, endTime: Time): Time;
  toString(): string;
}

class RecurIterator {
  constructor(options: Object);
  
  // Properties
  last: Time;
  completed: boolean;
  
  // Methods
  next(): Time;
}

class RecurExpansion {
  constructor(options: Object);
  
  // Properties
  complete: boolean;
  
  // Methods
  next(): Time;
}

Recurrence Patterns

Duration Calculations

Duration representation for time spans with support for weeks, days, hours, minutes, and seconds.

class Duration {
  constructor(data?: Object);
  
  // Static methods
  static fromString(str: string): Duration;
  static fromSeconds(seconds: number): Duration;
  
  // Properties
  weeks: number;
  days: number;
  hours: number;
  minutes: number;
  seconds: number;
  isNegative: boolean;
  readonly icaltype: string;
  
  // Methods
  clone(): Duration;
  toSeconds(): number;
  toString(): string;
  normalize(): void;
}

Duration Calculations

Timezone Support

Comprehensive timezone handling with VTIMEZONE component support, UTC offset calculations, and timezone service management.

class Timezone {
  constructor(data: Object | Component);
  
  // Static methods
  static fromData(data: Object): Timezone;
  
  // Static properties
  static utcTimezone: Timezone;
  static localTimezone: Timezone;
  
  // Properties
  tzid: string;
  location: string;
  component: Component;
  
  // Methods
  utcOffset(dt: Time): number;
  toString(): string;
}

class UtcOffset {
  constructor(data?: Object);
  
  // Static methods
  static fromString(str: string): UtcOffset;
  
  // Properties
  hours: number;
  minutes: number;
  factor: number;
  readonly icaltype: string;
  
  // Methods
  clone(): UtcOffset;
  toSeconds(): number;
  toString(): string;
}

Timezone Support

Period and Binary Data

Support for time periods and binary data encoding/decoding with base64 operations.

class Period {
  constructor(data: Object);
  
  // Static methods
  static fromString(str: string): Period;
  static fromData(data: Object): Period;
  
  // Properties
  start: Time;
  end: Time;
  duration: Duration;
  readonly icaltype: string;
  
  // Methods
  getDuration(): Duration;
  getEnd(): Time;
  toString(): string;
  toICALString(): string;
}

class Binary {
  constructor(value: string);
  
  // Properties
  value: string;
  readonly icaltype: string;
  
  // Methods
  decodeValue(): string;
  setEncodedValue(value: string): void;
  toString(): string;
}

Period and Binary Data

Component Stream Processing

SAX-style parser for processing large iCalendar files with event-driven callbacks, ideal for memory-efficient processing of large calendar datasets.

class ComponentParser {
  constructor(options?: Object);
  
  // Event handlers
  oncomplete(): void;
  onerror(err: Error): void;
  ontimezone(timezone: Timezone): void;
  onevent(event: Event): void;
  
  // Core processing
  process(ical: string | Object | Component): void;
}

Component Stream Processing

vCard Time Handling

Specialized time representation for vCard date/time values with support for reduced precision formats and UTC offset timezones.

class VCardTime extends Time {
  constructor(data?: Object, zone?: Timezone | UtcOffset, icaltype?: string);
  
  // Static methods
  static fromDateAndOrTimeString(value: string, icalType: string): VCardTime;
  
  // Properties
  icalclass: string; // "vcardtime"
  icaltype: string; // "date-and-or-time", "date", "time", "date-time"
}

vCard Time Handling

Helper Utilities

Essential utility functions for string manipulation, object operations, type validation, and debugging support used throughout ICAL.js.

namespace helpers {
  // Timezone utilities
  function updateTimezones(vcal: Component): Component;
  
  // Type validation
  function isStrictlyNaN(number: number): boolean;
  function strictParseInt(string: string): number;
  
  // String utilities
  function foldline(line: string): string;
  function pad2(data: string | number): string;
  
  // Object utilities
  function clone(src: any, deep?: boolean): any;
  function extend(source: Object, target: Object): Object;
}

Helper Utilities

Design System

Design sets defining parsing and serialization rules for different iCalendar and vCard formats, with support for component structures and value type definitions.

namespace design {
  // Design sets
  readonly defaultSet: Object;
  readonly icalendar: Object;
  readonly vcard: Object;
  readonly components: Object;
  readonly strict: boolean;
  
  // Methods
  function getDesignSet(componentName: string): Object;
}

Design System

Global Configuration

// Global configuration constants
ICAL.foldLength: number;      // Line folding character limit (default: 75)
ICAL.newLineChar: string;     // Newline characters (default: "\r\n")

Type Definitions

// Core interfaces used throughout the API
interface ComponentData {
  [key: string]: any;
}

interface PropertyData {
  [key: string]: any;
}

interface TimeData {
  year?: number;
  month?: number;
  day?: number;
  hour?: number;
  minute?: number;
  second?: number;
  isDate?: boolean;
}

interface DurationData {
  weeks?: number;
  days?: number;
  hours?: number;
  minutes?: number;
  seconds?: number;
  isNegative?: boolean;
}

interface RecurData {
  freq?: string;
  interval?: number;
  wkst?: number;
  until?: Time;
  count?: number;
  bysecond?: Array;
  byminute?: Array;
  byhour?: Array;
  byday?: Array;
  bymonthday?: Array;
  byyearday?: Array;
  byweekno?: Array;
  bymonth?: Array;
  bysetpos?: Array;
}