0
# ICAL.js
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: ical.js
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install ical.js`
10
11
## Core Imports
12
13
```javascript
14
const ICAL = require('ical.js');
15
```
16
17
For browser usage:
18
19
```html
20
<script src="ical.js"></script>
21
<!-- ICAL namespace is now available globally -->
22
```
23
24
## Basic Usage
25
26
```javascript
27
const ICAL = require('ical.js');
28
29
// Parse an iCalendar string
30
const icalString = `BEGIN:VCALENDAR
31
VERSION:2.0
32
PRODID:-//Example Corp//Example Client//EN
33
BEGIN:VEVENT
34
UID:example@example.com
35
DTSTART:20230615T100000Z
36
DTEND:20230615T110000Z
37
SUMMARY:Team Meeting
38
DESCRIPTION:Weekly team sync
39
END:VEVENT
40
END:VCALENDAR`;
41
42
// Parse to jCal format
43
const jcalData = ICAL.parse(icalString);
44
45
// Create component wrapper
46
const vcalendar = new ICAL.Component(jcalData);
47
48
// Get the first event
49
const vevent = vcalendar.getFirstSubcomponent('vevent');
50
51
// Create high-level Event object
52
const event = new ICAL.Event(vevent);
53
54
console.log(event.summary); // "Team Meeting"
55
console.log(event.startDate); // ICAL.Time object
56
console.log(event.endDate); // ICAL.Time object
57
58
// Serialize back to iCalendar string
59
const serialized = vcalendar.toString();
60
```
61
62
## Architecture
63
64
ICAL.js is organized into multiple layers providing different levels of abstraction:
65
66
- **Raw Data Layer**: jCal/jCard JSON representation of calendar data
67
- **Component/Property Layer**: `ICAL.Component` and `ICAL.Property` classes for structured manipulation
68
- **High-Level API**: `ICAL.Event`, `ICAL.Time`, `ICAL.Duration` classes for semantic operations
69
- **Parsing/Serialization**: `ICAL.parse` and `ICAL.stringify` for format conversion
70
- **Recurrence Engine**: `ICAL.Recur`, `ICAL.RecurIterator` for handling recurring events
71
- **Timezone Support**: `ICAL.Timezone`, `ICAL.TimezoneService` for timezone-aware operations
72
73
## Capabilities
74
75
### Parsing and Serialization
76
77
Core parsing functionality for converting between iCalendar/vCard strings and JavaScript objects, with support for both jCal/jCard JSON formats and native string formats.
78
79
```javascript { .api }
80
// Parse iCalendar/vCard string to jCal/jCard array
81
function parse(input: string): Array;
82
83
// Convert jCal/jCard array back to iCalendar/vCard string
84
function stringify(jCal: Array): string;
85
```
86
87
[Parsing and Serialization](./parsing.md)
88
89
### Component Manipulation
90
91
Structured access to iCalendar and vCard components with methods for adding, removing, and querying properties and subcomponents.
92
93
```javascript { .api }
94
class Component {
95
constructor(jCal: Array | string, parent?: Component);
96
97
// Static methods
98
static fromString(str: string): Component;
99
100
// Properties
101
readonly name: string;
102
jCal: Array;
103
104
// Component methods
105
getAllSubcomponents(name?: string): Component[];
106
getFirstSubcomponent(name: string): Component;
107
addSubcomponent(component: Component): Component;
108
removeSubcomponent(component: Component): boolean;
109
110
// Property methods
111
getAllProperties(name?: string): Property[];
112
getFirstProperty(name: string): Property;
113
getFirstPropertyValue(name: string): any;
114
addProperty(property: Property): Property;
115
removeProperty(property: Property): boolean;
116
hasProperty(name: string): boolean;
117
updatePropertyWithValue(name: string, value: any): Property;
118
119
toString(): string;
120
}
121
```
122
123
[Component Manipulation](./components.md)
124
125
### Property Management
126
127
Detailed property manipulation including parameters, multi-values, and type-specific value handling.
128
129
```javascript { .api }
130
class Property {
131
constructor(jCal: Array | string, parent?: Component);
132
133
// Static methods
134
static fromString(str: string, designSet?: Object): Property;
135
136
// Properties
137
readonly name: string;
138
type: string;
139
jCal: Array;
140
141
// Parameter methods
142
getParameter(name: string): string;
143
setParameter(name: string, value: string): void;
144
removeParameter(name: string): void;
145
getParameterIterator(): Object;
146
147
// Value methods
148
getFirstValue(): any;
149
getValues(): Array;
150
setValue(value: any): void;
151
setValues(values: Array): void;
152
getDefaultType(): string;
153
154
toICALString(): string;
155
}
156
```
157
158
[Property Management](./properties.md)
159
160
### Time and Date Handling
161
162
Comprehensive time representation with timezone support, date arithmetic, and calendar calculations.
163
164
```javascript { .api }
165
class Time {
166
constructor(data?: Object, zone?: Timezone);
167
168
// Static methods
169
static now(): Time;
170
static fromString(str: string): Time;
171
static fromJSDate(date: Date, useUTC?: boolean): Time;
172
static fromData(data: Object): Time;
173
static weekOneStarts(year: number, wkst: number): number;
174
static getDominicalLetter(year: number): string;
175
static isLeapYear(year: number): boolean;
176
177
// Static constants
178
static readonly SUNDAY: number;
179
static readonly MONDAY: number;
180
static readonly TUESDAY: number;
181
static readonly WEDNESDAY: number;
182
static readonly THURSDAY: number;
183
static readonly FRIDAY: number;
184
static readonly SATURDAY: number;
185
186
// Properties
187
year: number;
188
month: number;
189
day: number;
190
hour: number;
191
minute: number;
192
second: number;
193
isDate: boolean;
194
zone: Timezone;
195
readonly icaltype: string;
196
197
// Methods
198
clone(): Time;
199
reset(): void;
200
fromData(data: Object, zone?: Timezone): void;
201
dayOfWeek(): number;
202
dayOfYear(): number;
203
weekNumber(weekStart: number): number;
204
addDuration(duration: Duration): void;
205
subtractDate(other: Time): Duration;
206
compare(other: Time): number;
207
normalize(): void;
208
toJSDate(): Date;
209
toUnixTime(): number;
210
toString(): string;
211
}
212
```
213
214
[Time and Date Handling](./time.md)
215
216
### Event Management
217
218
High-level event representation with recurrence pattern support, exception handling, and occurrence calculation.
219
220
```javascript { .api }
221
class Event {
222
constructor(component?: Component, options?: Object);
223
224
// Properties
225
component: Component;
226
summary: string;
227
startDate: Time;
228
endDate: Time;
229
duration: Duration;
230
location: string;
231
attendees: Array;
232
organizer: Property;
233
uid: string;
234
exceptions: Object;
235
strictExceptions: boolean;
236
237
// Methods
238
isRecurring(): boolean;
239
isRecurrenceException(): boolean;
240
relateException(obj: Component | Event): void;
241
modifiesFuture(): boolean;
242
findRangeException(time: Time): Event;
243
getOccurrenceDetails(occurrence: Time): Object;
244
getRecurrenceTypes(): Object;
245
isOnDay(day: Time): boolean;
246
toString(): string;
247
}
248
```
249
250
[Event Management](./events.md)
251
252
### Recurrence Patterns
253
254
Complete recurrence rule processing with support for complex patterns, iterators, and expansion with exceptions.
255
256
```javascript { .api }
257
class Recur {
258
constructor(data?: Object);
259
260
// Static methods
261
static fromString(str: string): Recur;
262
static fromData(data: Object): Recur;
263
264
// Properties
265
freq: string;
266
interval: number;
267
wkst: number;
268
until: Time;
269
count: number;
270
bysecond: Array;
271
byminute: Array;
272
byhour: Array;
273
byday: Array;
274
bymonthday: Array;
275
byyearday: Array;
276
byweekno: Array;
277
bymonth: Array;
278
bysetpos: Array;
279
280
// Methods
281
clone(): Recur;
282
isFinite(): boolean;
283
isByCount(): boolean;
284
addComponent(part: string, value: any): void;
285
setComponent(part: string, value: any): void;
286
getComponent(part: string): any;
287
getNextOccurrence(startTime: Time, endTime: Time): Time;
288
toString(): string;
289
}
290
291
class RecurIterator {
292
constructor(options: Object);
293
294
// Properties
295
last: Time;
296
completed: boolean;
297
298
// Methods
299
next(): Time;
300
}
301
302
class RecurExpansion {
303
constructor(options: Object);
304
305
// Properties
306
complete: boolean;
307
308
// Methods
309
next(): Time;
310
}
311
```
312
313
[Recurrence Patterns](./recurrence.md)
314
315
### Duration Calculations
316
317
Duration representation for time spans with support for weeks, days, hours, minutes, and seconds.
318
319
```javascript { .api }
320
class Duration {
321
constructor(data?: Object);
322
323
// Static methods
324
static fromString(str: string): Duration;
325
static fromSeconds(seconds: number): Duration;
326
327
// Properties
328
weeks: number;
329
days: number;
330
hours: number;
331
minutes: number;
332
seconds: number;
333
isNegative: boolean;
334
readonly icaltype: string;
335
336
// Methods
337
clone(): Duration;
338
toSeconds(): number;
339
toString(): string;
340
normalize(): void;
341
}
342
```
343
344
[Duration Calculations](./duration.md)
345
346
### Timezone Support
347
348
Comprehensive timezone handling with VTIMEZONE component support, UTC offset calculations, and timezone service management.
349
350
```javascript { .api }
351
class Timezone {
352
constructor(data: Object | Component);
353
354
// Static methods
355
static fromData(data: Object): Timezone;
356
357
// Static properties
358
static utcTimezone: Timezone;
359
static localTimezone: Timezone;
360
361
// Properties
362
tzid: string;
363
location: string;
364
component: Component;
365
366
// Methods
367
utcOffset(dt: Time): number;
368
toString(): string;
369
}
370
371
class UtcOffset {
372
constructor(data?: Object);
373
374
// Static methods
375
static fromString(str: string): UtcOffset;
376
377
// Properties
378
hours: number;
379
minutes: number;
380
factor: number;
381
readonly icaltype: string;
382
383
// Methods
384
clone(): UtcOffset;
385
toSeconds(): number;
386
toString(): string;
387
}
388
```
389
390
[Timezone Support](./timezone.md)
391
392
### Period and Binary Data
393
394
Support for time periods and binary data encoding/decoding with base64 operations.
395
396
```javascript { .api }
397
class Period {
398
constructor(data: Object);
399
400
// Static methods
401
static fromString(str: string): Period;
402
static fromData(data: Object): Period;
403
404
// Properties
405
start: Time;
406
end: Time;
407
duration: Duration;
408
readonly icaltype: string;
409
410
// Methods
411
getDuration(): Duration;
412
getEnd(): Time;
413
toString(): string;
414
toICALString(): string;
415
}
416
417
class Binary {
418
constructor(value: string);
419
420
// Properties
421
value: string;
422
readonly icaltype: string;
423
424
// Methods
425
decodeValue(): string;
426
setEncodedValue(value: string): void;
427
toString(): string;
428
}
429
```
430
431
[Period and Binary Data](./period-binary.md)
432
433
### Component Stream Processing
434
435
SAX-style parser for processing large iCalendar files with event-driven callbacks, ideal for memory-efficient processing of large calendar datasets.
436
437
```javascript { .api }
438
class ComponentParser {
439
constructor(options?: Object);
440
441
// Event handlers
442
oncomplete(): void;
443
onerror(err: Error): void;
444
ontimezone(timezone: Timezone): void;
445
onevent(event: Event): void;
446
447
// Core processing
448
process(ical: string | Object | Component): void;
449
}
450
```
451
452
[Component Stream Processing](./component-parser.md)
453
454
### vCard Time Handling
455
456
Specialized time representation for vCard date/time values with support for reduced precision formats and UTC offset timezones.
457
458
```javascript { .api }
459
class VCardTime extends Time {
460
constructor(data?: Object, zone?: Timezone | UtcOffset, icaltype?: string);
461
462
// Static methods
463
static fromDateAndOrTimeString(value: string, icalType: string): VCardTime;
464
465
// Properties
466
icalclass: string; // "vcardtime"
467
icaltype: string; // "date-and-or-time", "date", "time", "date-time"
468
}
469
```
470
471
[vCard Time Handling](./vcard-time.md)
472
473
### Helper Utilities
474
475
Essential utility functions for string manipulation, object operations, type validation, and debugging support used throughout ICAL.js.
476
477
```javascript { .api }
478
namespace helpers {
479
// Timezone utilities
480
function updateTimezones(vcal: Component): Component;
481
482
// Type validation
483
function isStrictlyNaN(number: number): boolean;
484
function strictParseInt(string: string): number;
485
486
// String utilities
487
function foldline(line: string): string;
488
function pad2(data: string | number): string;
489
490
// Object utilities
491
function clone(src: any, deep?: boolean): any;
492
function extend(source: Object, target: Object): Object;
493
}
494
```
495
496
[Helper Utilities](./helpers.md)
497
498
### Design System
499
500
Design sets defining parsing and serialization rules for different iCalendar and vCard formats, with support for component structures and value type definitions.
501
502
```javascript { .api }
503
namespace design {
504
// Design sets
505
readonly defaultSet: Object;
506
readonly icalendar: Object;
507
readonly vcard: Object;
508
readonly components: Object;
509
readonly strict: boolean;
510
511
// Methods
512
function getDesignSet(componentName: string): Object;
513
}
514
```
515
516
[Design System](./design-system.md)
517
518
## Global Configuration
519
520
```javascript { .api }
521
// Global configuration constants
522
ICAL.foldLength: number; // Line folding character limit (default: 75)
523
ICAL.newLineChar: string; // Newline characters (default: "\r\n")
524
```
525
526
## Type Definitions
527
528
```javascript { .api }
529
// Core interfaces used throughout the API
530
interface ComponentData {
531
[key: string]: any;
532
}
533
534
interface PropertyData {
535
[key: string]: any;
536
}
537
538
interface TimeData {
539
year?: number;
540
month?: number;
541
day?: number;
542
hour?: number;
543
minute?: number;
544
second?: number;
545
isDate?: boolean;
546
}
547
548
interface DurationData {
549
weeks?: number;
550
days?: number;
551
hours?: number;
552
minutes?: number;
553
seconds?: number;
554
isNegative?: boolean;
555
}
556
557
interface RecurData {
558
freq?: string;
559
interval?: number;
560
wkst?: number;
561
until?: Time;
562
count?: number;
563
bysecond?: Array;
564
byminute?: Array;
565
byhour?: Array;
566
byday?: Array;
567
bymonthday?: Array;
568
byyearday?: Array;
569
byweekno?: Array;
570
bymonth?: Array;
571
bysetpos?: Array;
572
}
573
```