SAX-style parser for processing iCalendar components with event-driven callbacks. The ComponentParser provides an efficient way to process large iCalendar files by parsing components as they are encountered rather than loading everything into memory.
Stream-oriented parser that emits events for timezone definitions and calendar events as they are encountered.
/**
* ComponentParser constructor
* @param {Object} options - Parser configuration options (optional)
* @param {boolean} options.parseEvent - Parse VEVENT components (default: true)
* @param {boolean} options.parseTimezone - Parse VTIMEZONE components (default: true)
*/
class ICAL.ComponentParser {
constructor(options);
// Properties
parseEvent: boolean; // Whether to parse VEVENT components
parseTimezone: boolean; // Whether to parse VTIMEZONE components
}Usage Examples:
const ICAL = require('ical.js');
// Create parser with default options
const parser = new ICAL.ComponentParser();
// Create parser with custom options
const customParser = new ICAL.ComponentParser({
parseEvent: true,
parseTimezone: false
});Define callback functions to handle parsed components and errors.
/**
* Called when parsing completes successfully
*/
oncomplete(): void;
/**
* Called when a parse error occurs
* @param {Error} err - The error that occurred during parsing
*/
onerror(err: Error): void;
/**
* Called when a VTIMEZONE component is parsed
* @param {ICAL.Timezone} timezone - The parsed timezone component
*/
ontimezone(timezone: ICAL.Timezone): void;
/**
* Called when a VEVENT component is parsed
* @param {ICAL.Event} event - The parsed event component
*/
onevent(event: ICAL.Event): void;Usage Examples:
const ICAL = require('ical.js');
const parser = new ICAL.ComponentParser();
// Set up event handlers
parser.oncomplete = function() {
console.log('Parsing completed successfully');
};
parser.onerror = function(err) {
console.error('Parse error:', err.message);
};
parser.ontimezone = function(timezone) {
console.log('Found timezone:', timezone.tzid);
// Register timezone for use
ICAL.TimezoneService.register(timezone.tzid, timezone);
};
parser.onevent = function(event) {
console.log('Found event:', event.summary);
console.log('Start:', event.startDate.toString());
console.log('End:', event.endDate.toString());
};Process iCalendar data and trigger appropriate callbacks.
/**
* Process iCalendar data
* @param {string|Object|ICAL.Component} ical - iCalendar string, jCal object, or Component to process
*/
process(ical: string | Object | ICAL.Component): void;Usage Examples:
const ICAL = require('ical.js');
const parser = new ICAL.ComponentParser();
// Set up handlers
parser.onevent = function(event) {
console.log(`Event: ${event.summary} at ${event.startDate}`);
};
parser.oncomplete = function() {
console.log('Processing complete');
};
// Process from string
const icalString = `BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example//Example//EN
BEGIN:VEVENT
UID:test@example.com
DTSTART:20230615T100000Z
DTEND:20230615T110000Z
SUMMARY:Team Meeting
END:VEVENT
END:VCALENDAR`;
parser.process(icalString);
// Process from Component
const jcalData = ICAL.parse(icalString);
const component = new ICAL.Component(jcalData);
parser.process(component);
// Process from jCal object
parser.process(jcalData);ComponentParser is ideal for processing large iCalendar files that would consume too much memory if parsed entirely:
const ICAL = require('ical.js');
const fs = require('fs');
const parser = new ICAL.ComponentParser();
const events = [];
const timezones = [];
parser.onevent = function(event) {
// Process each event as it's found
events.push({
id: event.uid,
summary: event.summary,
start: event.startDate.toJSDate(),
end: event.endDate.toJSDate()
});
};
parser.ontimezone = function(timezone) {
// Collect timezone definitions
timezones.push(timezone);
ICAL.TimezoneService.register(timezone.tzid, timezone);
};
parser.oncomplete = function() {
console.log(`Processed ${events.length} events and ${timezones.length} timezones`);
};
// Process large calendar file
const largeCalendar = fs.readFileSync('large-calendar.ics', 'utf8');
parser.process(largeCalendar);Control which component types are processed to improve performance:
const ICAL = require('ical.js');
// Only process events, skip timezones
const eventsOnlyParser = new ICAL.ComponentParser({
parseEvent: true,
parseTimezone: false
});
// Only process timezones, skip events
const timezonesOnlyParser = new ICAL.ComponentParser({
parseEvent: false,
parseTimezone: true
});
eventsOnlyParser.onevent = function(event) {
// Handle events without timezone processing overhead
console.log('Event found:', event.summary);
};
timezonesOnlyParser.ontimezone = function(timezone) {
// Handle only timezone definitions
ICAL.TimezoneService.register(timezone.tzid, timezone);
};Robust error handling for malformed iCalendar data:
const ICAL = require('ical.js');
const parser = new ICAL.ComponentParser();
parser.onerror = function(err) {
console.error('Parser error:', err.message);
if (err instanceof ICAL.parse.ParserError) {
console.error('Parse error at line:', err.lineNumber);
} else {
console.error('Unexpected error:', err);
}
};
parser.onevent = function(event) {
try {
// Process event with error handling
console.log('Processing event:', event.summary);
} catch (error) {
console.error('Error processing event:', error.message);
}
};
// Process potentially malformed data
const malformedIcal = 'INVALID:CALENDAR:DATA';
parser.process(malformedIcal);