or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

components.mdindex.mdparsing.mdrecurrence.mdtime-date.mdtimezone.mdutilities.md
tile.json

parsing.mddocs/

Core Parsing and Serialization

Core functions for parsing iCalendar/vCard strings into structured jCal/jCard objects and converting them back to string format. These are the fundamental entry points for working with calendar and contact data.

Capabilities

Parse Function

Parses iCalendar or vCard data into raw jCal/jCard objects for further processing.

/**
 * Parses iCalendar or vCard data into raw jCal objects
 * @param input - iCalendar/vCard string to parse
 * @returns Single jCal object or array thereof
 */
function parse(input: string): object | object[];

Usage Examples:

import ICAL from "ical.js";

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

const jcalData = ICAL.parse(icalString);
console.log(jcalData);
// Output: ["vcalendar", [...properties...], [...components...]]

// Parse vCard data
const vcardString = `BEGIN:VCARD
VERSION:4.0
FN:John Doe
N:Doe;John;;;
EMAIL:john.doe@example.com
TEL:+1-555-123-4567
END:VCARD`;

const jcardData = ICAL.parse(vcardString);
console.log(jcardData);
// Output: ["vcard", [...properties...]]

// Parse multiple components
const multipleEvents = `BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example//Example//EN
BEGIN:VEVENT
UID:event1@example.com
DTSTART:20231201T120000Z
SUMMARY:Event 1
END:VEVENT
BEGIN:VEVENT
UID:event2@example.com
DTSTART:20231202T140000Z
SUMMARY:Event 2
END:VEVENT
END:VCALENDAR`;

const parsedCalendar = ICAL.parse(multipleEvents);
// Access individual components through the jCal structure

Stringify Function

Converts jCal/jCard arrays back into standard iCalendar/vCard string format.

/**
 * Converts jCal/jCard arrays into iCalendar/vCard strings
 * @param jCal - jCal/jCard document to stringify
 * @returns Stringified iCalendar/vCard document
 */
function stringify(jCal: array): string;

Usage Examples:

import ICAL from "ical.js";

// Create a jCal structure programmatically
const jcalData = [
  "vcalendar",
  [
    ["version", {}, "text", "2.0"],
    ["prodid", {}, "text", "-//Example//Example//EN"]
  ],
  [
    ["vevent", [
      ["uid", {}, "text", "new-event@example.com"],
      ["dtstart", {}, "date-time", "2023-12-01T15:00:00Z"],
      ["dtend", {}, "date-time", "2023-12-01T16:00:00Z"],
      ["summary", {}, "text", "Generated Event"],
      ["description", {}, "text", "This event was created programmatically"]
    ], []]
  ]
];

const icalString = ICAL.stringify(jcalData);
console.log(icalString);

// Working with Component objects
const component = new ICAL.Component("vcalendar");
component.addPropertyWithValue("version", "2.0");
component.addPropertyWithValue("prodid", "-//Example//Example//EN");

const event = new ICAL.Component("vevent");
event.addPropertyWithValue("uid", "component-event@example.com");
event.addPropertyWithValue("summary", "Component-based Event");
event.addPropertyWithValue("dtstart", ICAL.Time.now());

component.addSubcomponent(event);

// Stringify the component's jCal representation
const componentString = ICAL.stringify(component.jCal);
console.log(componentString);

Design Sets

The parsing system uses design sets to handle different data formats and validation rules.

const design: {
  /** Parser strictness flag */
  strict: boolean;
  /** Default design set for new components */
  defaultSet: object;
  /** Default type for unknown properties */
  defaultType: string;
  /** iCalendar (RFC5545/RFC7265) design set */
  icalendar: object;
  /** vCard 4.0 (RFC6350/RFC7095) design set */
  vcard: object;
  /** vCard 3.0 (RFC2425/RFC2426) design set */
  vcard3: object;
  /** Component-specific design sets */
  components: object;
  /** Gets design set for component */
  getDesignSet(componentName: string): object;
};

Usage Examples:

import ICAL from "ical.js";

// Enable strict parsing mode
ICAL.design.strict = true;

// Get design set for specific component
const veventDesign = ICAL.design.getDesignSet("vevent");
console.log(veventDesign);

// Access format-specific design sets
console.log(ICAL.design.icalendar); // iCalendar format rules
console.log(ICAL.design.vcard);     // vCard 4.0 format rules
console.log(ICAL.design.vcard3);    // vCard 3.0 format rules

Error Handling

Parsing operations may throw errors for malformed input data:

import ICAL from "ical.js";

try {
  const invalidIcal = "BEGIN:VCALENDAR\nINVALID CONTENT\nEND:VCALENDAR";
  const result = ICAL.parse(invalidIcal);
} catch (error) {
  console.error("Parsing failed:", error.message);
  // Handle parsing errors appropriately
}

// Enable strict mode for more rigorous validation
ICAL.design.strict = true;
try {
  const result = ICAL.parse(potentiallyInvalidData);
} catch (error) {
  console.error("Strict parsing failed:", error.message);
}

Integration with Higher-Level Components

The parse and stringify functions work seamlessly with ical.js's higher-level component system:

import ICAL from "ical.js";

// Parse -> Component -> Manipulate -> Stringify workflow
const icalData = `BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VEVENT
UID:example@test.com
DTSTART:20231201T120000Z
SUMMARY:Original Event
END:VEVENT
END:VCALENDAR`;

// Parse to jCal
const jcal = ICAL.parse(icalData);

// Wrap in Component for easy manipulation
const vcalendar = new ICAL.Component(jcal);
const vevent = vcalendar.getFirstSubcomponent("vevent");

// Modify the event
vevent.updatePropertyWithValue("summary", "Modified Event");
vevent.addPropertyWithValue("description", "This event was modified");

// Convert back to string
const modifiedIcal = ICAL.stringify(vcalendar.jCal);
console.log(modifiedIcal);