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
```