Calendar Components and Properties

/**
 * Wraps jCal components with convenience methods
 * @param jCal - jCal component array
 * @param parent - Parent component
 */
class Component {
  constructor(jCal: array, parent?: Component);
  
  // Properties
  readonly name: string;        // Component name
  readonly jCal: array;         // Raw jCal data
  parent: Component | null;     // Parent component
  
  // Static methods
  static fromString(str: string): Component;
  
  // Subcomponent methods
  getFirstSubcomponent(name: string): Component | null;
  getAllSubcomponents(name?: string): Component[];
  addSubcomponent(component: Component): void;
  removeSubcomponent(nameOrComp: string | Component): boolean;
  removeAllSubcomponents(name: string): void;
  
  // Property methods
  hasProperty(name: string): boolean;
  getFirstProperty(name: string): Property | null;
  getFirstPropertyValue(name: string): any;
  getAllProperties(name?: string): Property[];
  addProperty(property: Property): Property;
  addPropertyWithValue(name: string, value: any): Property;
  updatePropertyWithValue(name: string, value: any): Property;
  removeProperty(nameOrProp: string | Property): boolean;
  removeAllProperties(name: string): void;
  
  // Utility methods
  getTimeZoneByID(tzid: string): Timezone | null;
  toJSON(): object;
  toString(): string;
}

import ICAL from "ical.js";

// Create new calendar component
const vcalendar = new ICAL.Component("vcalendar");
vcalendar.addPropertyWithValue("version", "2.0");
vcalendar.addPropertyWithValue("prodid", "-//Example Corp//Calendar//EN");

// Create event component
const vevent = new ICAL.Component("vevent");
vevent.addPropertyWithValue("uid", "event-123@example.com");
vevent.addPropertyWithValue("summary", "Team Meeting");
vevent.addPropertyWithValue("dtstart", ICAL.Time.fromString("20231201T120000Z"));
vevent.addPropertyWithValue("dtend", ICAL.Time.fromString("20231201T130000Z"));
vevent.addPropertyWithValue("description", "Weekly team standup meeting");

// Add event to calendar
vcalendar.addSubcomponent(vevent);

// Parse existing calendar
const icalString = `BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example//Calendar//EN
BEGIN:VEVENT
UID:existing-event@example.com
DTSTART:20231202T140000Z
DTEND:20231202T150000Z
SUMMARY:Existing Event
DESCRIPTION:This event already exists
END:VEVENT
END:VCALENDAR`;

const parsedComponent = ICAL.Component.fromString(icalString);

// Access subcomponents
const events = parsedComponent.getAllSubcomponents("vevent");
console.log(`Found ${events.length} events`);

const firstEvent = parsedComponent.getFirstSubcomponent("vevent");
if (firstEvent) {
  console.log(firstEvent.getFirstPropertyValue("summary")); // "Existing Event"
}

// Modify properties
if (firstEvent.hasProperty("description")) {
  firstEvent.updatePropertyWithValue("description", "Modified description");
}

// Add new properties
firstEvent.addPropertyWithValue("location", "Conference Room A");

// Remove properties
firstEvent.removeProperty("description");

// Work with timezones
const timezoneProp = firstEvent.getFirstProperty("dtstart");
if (timezoneProp) {
  const timezone = parsedComponent.getTimeZoneByID("America/New_York");
}

// Convert back to string
console.log(parsedComponent.toString());

/**
 * Property wrapper with convenience methods
 * @param jCal - jCal property array
 * @param parent - Parent component
 */
class Property {
  constructor(jCal: array, parent?: Component);
  
  // Properties
  readonly type: string;        // Property type
  readonly name: string;        // Property name
  readonly jCal: array;         // Raw jCal data
  parent: Component | null;     // Parent component
  
  // Static methods
  static fromString(str: string, designSet?: object): Property;
  
  // Parameter methods
  getParameter(name: string): string | string[];
  getFirstParameter(name: string): string;
  setParameter(name: string, value: string | string[]): void;
  removeParameter(name: string): void;
  
  // Type methods
  getDefaultType(): string;
  resetType(type: string): void;
  
  // Value methods
  getFirstValue(): any;
  getValues(): any[];
  removeAllValues(): void;
  setValues(values: any[]): void;
  setValue(value: any): void;
  
  // Serialization methods
  toJSON(): object;
  toICALString(): string;
}

import ICAL from "ical.js";

// Create property from string
const dtstart = ICAL.Property.fromString("DTSTART:20231201T120000Z");
console.log(dtstart.name);  // "dtstart"
console.log(dtstart.type);  // "date-time"
console.log(dtstart.getFirstValue()); // Time object

// Create property with parameters
const dtStartWithTz = ICAL.Property.fromString("DTSTART;TZID=America/New_York:20231201T120000");
console.log(dtStartWithTz.getParameter("tzid")); // "America/New_York"

// Create property programmatically
const summary = new ICAL.Property(["summary", {}, "text", "Team Meeting"]);
console.log(summary.getFirstValue()); // "Team Meeting"

// Modify property values
summary.setValue("Updated Meeting Title");
console.log(summary.getFirstValue()); // "Updated Meeting Title"

// Work with multi-value properties
const categories = new ICAL.Property(["categories", {}, "text", "work", "meeting"]);
console.log(categories.getValues()); // ["work", "meeting"]
categories.setValues(["work", "meeting", "important"]);

// Manage parameters
const attendee = new ICAL.Property([
  "attendee", 
  { cn: "John Doe", role: "req-participant" }, 
  "cal-address", 
  "mailto:john@example.com"
]);

console.log(attendee.getParameter("cn"));   // "John Doe"
console.log(attendee.getParameter("role")); // "req-participant"

attendee.setParameter("partstat", "accepted");
attendee.removeParameter("role");

// Property type handling
console.log(attendee.getDefaultType()); // Default type for attendee
attendee.resetType("uri"); // Change property type

// Convert to string format
console.log(summary.toICALString()); // "SUMMARY:Updated Meeting Title"

/**
 * High-level event representation with convenience methods
 * @param component - VEVENT component
 * @param options - Event options
 */
class Event {
  constructor(component: Component, options?: object);
  
  // Properties (getters/setters)
  uid: string;
  startDate: Time;
  endDate: Time;
  duration: Duration;
  location: string;
  readonly attendees: Property[];  // Read-only attendees list
  summary: string;
  description: string;
  color: string;
  organizer: Property;
  sequence: number;
  recurrenceId: Time;
  
  // Component access
  readonly component: Component;
  
  // Static properties
  static THISANDFUTURE: string; // Range constant for recurring events
  
  // Instance methods
  relateException(obj: Event): void;
  modifiesFuture(): boolean;
  findRangeException(time: Time): Event | null;
  getOccurrenceDetails(occurrence: Time): object;
  iterator(startTime?: Time): RecurExpansion;
  isRecurring(): boolean;
  isRecurrenceException(): boolean;
  getRecurrenceTypes(): string[];
  toString(): string;
}

import ICAL from "ical.js";

// Create event from component
const vevent = new ICAL.Component("vevent");
vevent.addPropertyWithValue("uid", "meeting-123@example.com");
vevent.addPropertyWithValue("summary", "Weekly Team Meeting");
vevent.addPropertyWithValue("dtstart", ICAL.Time.fromString("20231201T120000Z"));
vevent.addPropertyWithValue("dtend", ICAL.Time.fromString("20231201T130000Z"));

const event = new ICAL.Event(vevent);

// Access event properties
console.log(event.summary);    // "Weekly Team Meeting"
console.log(event.uid);        // "meeting-123@example.com"
console.log(event.startDate.toString()); // Start date
console.log(event.endDate.toString());   // End date

// Modify event properties
event.summary = "Updated Meeting Title";
event.location = "Conference Room A";
event.description = "Updated meeting description";

// Work with dates and durations
event.startDate = ICAL.Time.fromString("20231201T140000Z");
event.duration = ICAL.Duration.fromString("PT2H"); // 2 hours

// Access organizer and attendees
if (event.organizer) {
  console.log(event.organizer.getFirstValue()); // Organizer email
  console.log(event.organizer.getParameter("cn")); // Organizer name
}

event.attendees.forEach(attendee => {
  console.log(attendee.getFirstValue());        // Attendee email
  console.log(attendee.getParameter("cn"));     // Attendee name
  console.log(attendee.getParameter("partstat")); // Participation status
});

// Parse existing event
const eventString = `BEGIN:VEVENT
UID:recurring-meeting@example.com
DTSTART:20231201T120000Z
DTEND:20231201T130000Z
SUMMARY:Recurring Meeting
RRULE:FREQ=WEEKLY;BYDAY=FR
END:VEVENT`;

const component = ICAL.Component.fromString(eventString);
const recurringEvent = new ICAL.Event(component);

// Check recurrence
console.log(recurringEvent.isRecurring()); // true
console.log(recurringEvent.getRecurrenceTypes()); // ["WEEKLY"]

// Get recurrence iterator
const iterator = recurringEvent.iterator(ICAL.Time.fromString("20231201T000000Z"));
let next = iterator.next();
while (next) {
  console.log(next.toString()); // Each occurrence
  next = iterator.next();
  if (iterator.complete) break;
}

// Work with recurrence exceptions
const exceptionEvent = new ICAL.Event(/* exception component */);
recurringEvent.relateException(exceptionEvent);

// Check if event modifies future occurrences
console.log(recurringEvent.modifiesFuture()); // true/false

// Find range exceptions
const occurrenceTime = ICAL.Time.fromString("20231208T120000Z");
const rangeException = recurringEvent.findRangeException(occurrenceTime);

/**
 * Component parsing utilities
 * @param options - Parser options
 */
class ComponentParser {
  constructor(options?: object);
  
  // Instance methods
  process(ical: string): Component[];
}

import ICAL from "ical.js";

// Create parser with custom options
const parser = new ICAL.ComponentParser({
  // Custom parser options
});

// Process iCalendar data
const icalData = `BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VEVENT
UID:test@example.com
DTSTART:20231201T120000Z
SUMMARY:Test Event  
END:VEVENT
END:VCALENDAR`;

const components = parser.process(icalData);
components.forEach(component => {
  console.log(component.name); // Component type
  console.log(component.toString()); // Component string
});