Utilities and Helpers

/**
 * Binary data handling for base64-encoded properties
 * @param aValue - Binary value string
 */
class Binary {
  constructor(aValue?: string);
  
  // Properties
  value: string;  // Raw binary data
  
  // Static methods
  static fromString(aString: string): Binary;
  
  // Instance methods
  decodeValue(): string;
  setEncodedValue(aValue: string): void;
  toString(): string;
}

import ICAL from "ical.js";

// Create binary data from string
const binaryData = ICAL.Binary.fromString("SGVsbG8gV29ybGQ="); // "Hello World" in base64

// Create binary instance
const binary = new ICAL.Binary("SGVsbG8gV29ybGQ=");

// Decode binary data
const decoded = binary.decodeValue();
console.log(decoded); // "Hello World"

// Set new encoded value
binary.setEncodedValue("VGhpcyBpcyBhIHRlc3Q="); // "This is a test" in base64

// Get string representation
console.log(binary.toString()); // Base64 encoded string

// Working with calendar properties
const attachment = new ICAL.Property([
  "attach",
  { encoding: "base64", value: "binary" },
  "binary",
  "SGVsbG8gV29ybGQ="
]);

const attachmentBinary = attachment.getFirstValue();
if (attachmentBinary instanceof ICAL.Binary) {
  console.log(attachmentBinary.decodeValue()); // "Hello World"
}

/**
 * Utility functions used throughout the library
 */
const helpers: {
  /**
   * Compiles and manages VTIMEZONE components
   * @param vcal - Calendar component containing timezones
   */
  updateTimezones(vcal: Component): void;
  
  /**
   * Checks for strict NaN values
   * @param number - Number to check
   * @returns True if strictly NaN
   */
  isStrictlyNaN(number: any): boolean;
  
  /**
   * Strict integer parsing with error handling
   * @param string - String to parse
   * @returns Parsed integer
   */
  strictParseInt(string: string): number;
  
  /**
   * Creates or returns class instances with proper type formatting
   * @param data - Data to format
   * @param type - Target type/class
   * @returns Formatted instance
   */
  formatClassType(data: any, type: Function): any;
  
  /**
   * Find unescaped string positions in buffer
   * @param buffer - Buffer to search
   * @param search - String to find
   * @param pos - Starting position
   * @returns Position of unescaped string
   */
  unescapedIndexOf(buffer: string, search: string, pos?: number): number;
  
  /**
   * Binary search insertion maintaining sort order
   * @param list - Sorted array
   * @param seekVal - Value to insert
   * @param cmpfunc - Comparison function
   * @returns Insertion index
   */
  binsearchInsert(list: any[], seekVal: any, cmpfunc?: (a: any, b: any) => number): number;
  
  /**
   * Object/primitive cloning (shallow/deep)
   * @param aSrc - Source object/value
   * @param aDeep - Deep clone flag
   * @returns Cloned object/value
   */
  clone(aSrc: any, aDeep?: boolean): any;
  
  /**
   * iCalendar line folding according to RFC 5545
   * @param aLine - Line to fold
   * @returns Folded line
   */
  foldline(aLine: string): string;
  
  /**
   * Zero-padding to minimum 2 characters
   * @param data - Data to pad
   * @returns Padded string
   */
  pad2(data: number | string): string;
  
  /**
   * Number truncation handling negatives properly
   * @param number - Number to truncate
   * @returns Truncated number
   */
  trunc(number: number): number;
  
  /**
   * Object property extension (merge)
   * @param source - Source object
   * @param target - Target object
   * @returns Extended object
   */
  extend(source: object, target: object): object;
};

import ICAL from "ical.js";

// Update timezones in a calendar
const calendar = ICAL.Component.fromString(calendarData);
ICAL.helpers.updateTimezones(calendar);

// Strict number validation
console.log(ICAL.helpers.isStrictlyNaN(NaN));     // true
console.log(ICAL.helpers.isStrictlyNaN("NaN"));   // false
console.log(ICAL.helpers.isStrictlyNaN(123));     // false

// Strict integer parsing
try {
  const num = ICAL.helpers.strictParseInt("123");
  console.log(num); // 123
  
  // This will throw an error for invalid input
  const invalid = ICAL.helpers.strictParseInt("abc");
} catch (error) {
  console.error("Invalid integer:", error.message);
}

// Format class types
const timeData = { year: 2023, month: 12, day: 25 };
const formattedTime = ICAL.helpers.formatClassType(timeData, "time");

// String searching with escape handling
const text = "Hello\\,World,Test";
const commaPos = ICAL.helpers.unescapedIndexOf(text, ",", 0);
console.log(commaPos); // Position of unescaped comma

// Binary search insertion
const sortedNumbers = [1, 3, 5, 7, 9];
const insertPos = ICAL.helpers.binsearchInsert(sortedNumbers, 6);
console.log(insertPos); // 3 (position to insert 6)

sortedNumbers.splice(insertPos, 0, 6);
console.log(sortedNumbers); // [1, 3, 5, 6, 7, 9]

// Object cloning
const original = { a: 1, b: { c: 2 } };
const shallow = ICAL.helpers.clone(original, false);
const deep = ICAL.helpers.clone(original, true);

shallow.b.c = 3;
console.log(original.b.c); // 3 (shallow copy shares references)

deep.b.c = 4;
console.log(original.b.c); // Still 3 (deep copy is independent)

// Line folding for iCalendar format
const longLine = "SUMMARY:" + "Very long event summary that exceeds the typical line length limit".repeat(3);
const foldedLine = ICAL.helpers.foldline(longLine);
console.log(foldedLine); // Properly folded with CRLF + space

// Number padding
console.log(ICAL.helpers.pad2(5));   // "05"
console.log(ICAL.helpers.pad2(15));  // "15"
console.log(ICAL.helpers.pad2("7")); // "07"

// Number truncation
console.log(ICAL.helpers.trunc(3.7));   // 3
console.log(ICAL.helpers.trunc(-3.7));  // -3 (proper negative handling)

// Object extension
const base = { a: 1, b: 2 };
const extension = { b: 3, c: 4 };
const extended = ICAL.helpers.extend(base, extension);
console.log(extended); // { a: 1, b: 3, c: 4 }

/**
 * Design sets for different formats
 */
const design: {
  /** Parser strictness flag */
  strict: boolean;
  /** Default design set for new components */
  defaultSet: object;
  /** Default type for unknown properties */
  defaultType: string;
  /** iCalendar (RFC5545/RFC7265) design set */
  icalendar: object;
  /** vCard 4.0 (RFC6350/RFC7095) design set */
  vcard: object;
  /** vCard 3.0 (RFC2425/RFC2426) design set */
  vcard3: object;
  /** Component-specific design sets */
  components: object;
  
  /**
   * Gets design set for component
   * @param componentName - Name of component
   * @returns Design set object
   */
  getDesignSet(componentName: string): object;
};

import ICAL from "ical.js";

// Configure strict parsing
ICAL.design.strict = true;

// Get design set for specific component
const veventDesign = ICAL.design.getDesignSet("vevent");
console.log(veventDesign); // Design rules for VEVENT components

// Access format-specific design sets
console.log(Object.keys(ICAL.design.icalendar.property)); // iCalendar properties
console.log(Object.keys(ICAL.design.vcard.property));     // vCard 4.0 properties
console.log(Object.keys(ICAL.design.vcard3.property));    // vCard 3.0 properties

// Check default settings
console.log(ICAL.design.defaultType); // Default property type
console.log(ICAL.design.defaultSet);  // Default design set

// Component design access
console.log(ICAL.design.components.vevent);     // VEVENT design
console.log(ICAL.design.components.vtimezone);  // VTIMEZONE design

// Custom property handling with design sets
function parseCustomProperty(propertyString, designSet) {
  // Use specific design set for parsing
  return ICAL.Property.fromString(propertyString, designSet);
}

// Parse with vCard design
const vcardProperty = parseCustomProperty("FN:John Doe", ICAL.design.vcard);
console.log(vcardProperty.name); // "fn"

// Parse with iCalendar design  
const icalProperty = parseCustomProperty("SUMMARY:Meeting", ICAL.design.icalendar);
console.log(icalProperty.name); // "summary"

/**
 * 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 default options
const parser = new ICAL.ComponentParser();

// Parse iCalendar string into components
const icalData = `BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example//Calendar//EN
BEGIN:VEVENT
UID:event1@example.com
DTSTART:20231201T120000Z
DTEND:20231201T130000Z
SUMMARY:First Event
END:VEVENT
BEGIN:VEVENT
UID:event2@example.com
DTSTART:20231202T140000Z
DTEND:20231202T150000Z
SUMMARY:Second Event
END:VEVENT
END:VCALENDAR`;

const components = parser.process(icalData);
console.log(`Parsed ${components.length} components`);

components.forEach(component => {
  console.log(`Component: ${component.name}`);
  if (component.name === "vevent") {
    const summary = component.getFirstPropertyValue("summary");
    console.log(`  Summary: ${summary}`);
  }
});

// Create parser with custom options
const customParser = new ICAL.ComponentParser({
  // Custom parsing options can be specified here
  strictMode: true,
  ignoreErrors: false
});

try {
  const strictComponents = customParser.process(icalData);
  console.log("Strict parsing successful");
} catch (error) {
  console.error("Strict parsing failed:", error.message);
}

// Process multiple calendar formats
const vcardData = `BEGIN:VCARD
VERSION:4.0
FN:John Doe
N:Doe;John;;;
EMAIL:john@example.com
END:VCARD`;

const vcardComponents = parser.process(vcardData);
console.log(`Parsed vCard with ${vcardComponents.length} components`);

import ICAL from "ical.js";

// Global configuration options
ICAL.foldLength = 75;        // Line folding length
ICAL.debug = false;          // Debug mode
ICAL.newLineChar = '\r\n';   // Line ending characters

// Design system configuration
ICAL.design.strict = true;   // Enable strict parsing
ICAL.design.defaultType = "text"; // Default property type

// Example: Custom configuration for specific use case
function configureForWebApp() {
  ICAL.foldLength = 120;     // Longer lines for web display
  ICAL.design.strict = false; // More lenient parsing
  ICAL.debug = true;         // Enable debugging
}

function configureForStrictCompliance() {
  ICAL.foldLength = 75;      // RFC-compliant folding
  ICAL.design.strict = true; // Strict validation
  ICAL.debug = false;        // No debug output
}

// Reset to defaults
function resetConfiguration() {
  ICAL.foldLength = 75;
  ICAL.debug = false;
  ICAL.newLineChar = '\r\n';
  ICAL.design.strict = false;
}