0
# ical.js
1

2
ical.js is a comprehensive JavaScript library for parsing and working with iCalendar (RFC 5545), jCal (RFC 7265), vCard (RFC 6350), and jCard (RFC 7095) data formats. It serves as a replacement for libical in web-based calendar applications, enabling developers to parse, manipulate, and generate calendar and contact data directly in JavaScript environments including browsers and Node.js.
3

4
## Package Information
5

6
- **Package Name**: ical.js
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install ical.js`
10

11
## Core Imports
12

13
```javascript
14
import ICAL from "ical.js";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const ICAL = require("ical.js");
21
```
22

23
Individual imports:
24

25
```javascript
26
import { parse, stringify, Component, Event, Time } from "ical.js";
27
```
28

29
## Basic Usage
30

31
```javascript
32
import ICAL from "ical.js";
33

34
// Parse iCalendar data
35
const icalData = `BEGIN:VCALENDAR
36
VERSION:2.0
37
PRODID:-//Example//Example//EN
38
BEGIN:VEVENT
39
UID:12345@example.com
40
DTSTART:20231201T120000Z
41
DTEND:20231201T130000Z
42
SUMMARY:Team Meeting
43
DESCRIPTION:Weekly team standup
44
END:VEVENT
45
END:VCALENDAR`;
46

47
const jcalData = ICAL.parse(icalData);
48
const vcalendar = new ICAL.Component(jcalData);
49
const vevent = vcalendar.getFirstSubcomponent("vevent");
50
const event = new ICAL.Event(vevent);
51

52
console.log(event.summary); // "Team Meeting"
53
console.log(event.startDate.toString()); // Start date
54
console.log(event.endDate.toString()); // End date
55

56
// Generate iCalendar data
57
const newEvent = new ICAL.Component("vevent");
58
newEvent.addPropertyWithValue("uid", "new-event@example.com");
59
newEvent.addPropertyWithValue("summary", "New Meeting");
60
newEvent.addPropertyWithValue("dtstart", ICAL.Time.now());
61

62
const newCalendar = new ICAL.Component("vcalendar");
63
newCalendar.addPropertyWithValue("version", "2.0");
64
newCalendar.addPropertyWithValue("prodid", "-//Example//Example//EN");
65
newCalendar.addSubcomponent(newEvent);
66

67
const icalString = ICAL.stringify(newCalendar.jCal);
68
console.log(icalString);
69
```
70

71
## Architecture
72

73
ical.js is built around several key architectural components:
74

75
- **Parsing Engine**: Core `parse()` and `stringify()` functions that convert between iCalendar/vCard strings and jCal/jCard objects
76
- **Component System**: Object-oriented wrappers (`Component`, `Property`, `Event`) that provide convenience methods for manipulating calendar data
77
- **Time Representation**: Timezone-aware time handling (`Time`, `VCardTime`, `Duration`, `Period`) with full RFC compliance
78
- **Recurrence Engine**: Comprehensive recurrence rule processing (`Recur`, `RecurExpansion`, `RecurIterator`) for repeating events
79
- **Timezone Management**: Complete timezone support (`Timezone`, `TimezoneService`, `UtcOffset`) with VTIMEZONE component handling
80
- **Design System**: Pluggable design sets for different data formats (iCalendar, vCard 3.0, vCard 4.0)
81

82
## Capabilities
83

84
### Core Parsing and Serialization
85

86
High-level parsing and serialization functions for converting between iCalendar/vCard strings and structured jCal/jCard objects.
87

88
```javascript { .api }
89
function parse(input: string): object | object[];
90
function stringify(jCal: array): string;
91
```
92

93
[Core Parsing](./parsing.md)
94

95
### Time and Date Handling
96

97
Comprehensive time representation classes for handling dates, times, durations, and periods with full timezone support and RFC compliance.
98

99
```javascript { .api }
100
class Time {
101
  constructor(data?: object, zone?: Timezone);
102
  static fromString(aValue: string, aProperty?: Property): Time;
103
  static fromJSDate(aDate: Date, useUTC?: boolean): Time;
104
  static now(): Time;
105
}
106

107
class Duration {
108
  constructor(data?: object);
109
  static fromString(aStr: string): Duration;
110
  static fromSeconds(aSeconds: number): Duration;
111
}
112
```
113

114
[Time and Date Handling](./time-date.md)
115

116
### Calendar Components and Properties
117

118
Object-oriented wrappers for working with calendar components and properties, providing convenient methods for manipulation and access.
119

120
```javascript { .api }
121
class Component {
122
  constructor(jCal: array, parent?: Component);
123
  static fromString(str: string): Component;
124
  getFirstSubcomponent(name: string): Component | null;
125
  getFirstProperty(name: string): Property | null;
126
  addSubcomponent(component: Component): void;
127
  addPropertyWithValue(name: string, value: any): Property;
128
}
129

130
class Event {
131
  constructor(component: Component, options?: object);
132
  get summary(): string;
133
  get startDate(): Time;
134
  get endDate(): Time;
135
  iterator(startTime?: Time): RecurExpansion;
136
}
137
```
138

139
[Calendar Components](./components.md)
140

141
### Recurrence Rule Processing
142

143
Complete implementation of RFC 5545 recurrence rules with expansion engines for generating recurring event instances.
144

145
```javascript { .api }
146
class Recur {
147
  constructor(data?: object);
148
  static fromString(string: string): Recur;
149
  iterator(aStart: Time): RecurIterator;
150
  getNextOccurrence(aStartTime: Time, aRecurrenceId?: Time): Time;
151
}
152

153
class RecurExpansion {
154
  constructor(options: object);
155
  next(): Time | null;
156
}
157
```
158

159
[Recurrence Processing](./recurrence.md)
160

161
### Timezone Management
162

163
Comprehensive timezone handling with support for VTIMEZONE components, UTC offset calculations, and timezone conversions.
164

165
```javascript { .api }
166
class Timezone {
167
  constructor(data?: object);
168
  static fromData(aData: object): Timezone;
169
  static get utcTimezone(): Timezone;
170
  static get localTimezone(): Timezone;
171
  utcOffset(tt: Time): number;
172
}
173

174
const TimezoneService: {
175
  get(tzid: string): Timezone | null;
176
  register(timezone: Timezone, name?: string): void;
177
  reset(): void;
178
};
179
```
180

181
[Timezone Management](./timezone.md)
182

183
### Utility Functions and Helpers
184

185
Various utility classes and helper functions for specialized data handling, binary data processing, and internal operations.
186

187
```javascript { .api }
188
class Binary {
189
  constructor(aValue?: string);
190
  static fromString(aString: string): Binary;
191
  decodeValue(): string;
192
  toString(): string;
193
}
194

195
const helpers: {
196
  updateTimezones(vcal: Component): void;
197
  clone(aSrc: any, aDeep?: boolean): any;
198
  foldline(aLine: string): string;
199
};
200

201
const design: {
202
  strict: boolean;
203
  defaultSet: object;
204
  icalendar: object;
205
  vcard: object;
206
  vcard3: object;
207
};
208
```
209

210
[Utilities and Helpers](./utilities.md)
211

212
## Configuration
213

214
ical.js provides several global configuration options:
215

216
```javascript { .api }
217
ICAL.foldLength = 75;     // Characters before line folding
218
ICAL.debug = false;       // Debug mode flag  
219
ICAL.newLineChar = '\r\n'; // Line ending characters
220
```
221

222
## Error Handling
223

224
The library may throw various errors during parsing and processing:
225

226
- **ParserError**: Thrown during invalid iCalendar/vCard parsing
227
- **ComponentError**: Thrown for invalid component operations
228
- **ValueError**: Thrown for invalid property values or parameters
229

230
Always wrap parsing operations in try-catch blocks when working with untrusted input data.