@pipobscure/ical 0.0.1

package/src/parse.ts

@@ -0,0 +1,166 @@
+/**
+ * Tolerant iCalendar parser.
+ *
+ * Principles:
+ *  - Accepts CRLF, LF, or bare CR line endings.
+ *  - Handles folded lines.
+ *  - Unknown components are stored as generic Component instances.
+ *  - Unknown properties are stored with TEXT value.
+ *  - Missing required wrappers are recovered from where possible.
+ *  - Malformed property lines are skipped with a warning (no crash).
+ */
+
+import { tokenize } from './tokenize.js';
+import { parseProperty } from './property.js';
+import { Component } from './component.js';
+import { Calendar } from './calendar.js';
+import { Event } from './event.js';
+import { Todo } from './todo.js';
+import { Journal } from './journal.js';
+import { FreeBusy } from './freebusy.js';
+import { Timezone, buildTimezoneRule } from './timezone.js';
+import { Alarm } from './alarm.js';
+
+// ── Raw tree built during tokenization ───────────────────────────────────
+
+interface RawNode {
+  type: string;
+  props: Array<{ name: string; params: Record<string, string>; value: string }>;
+  children: RawNode[];
+}
+
+/** Build a raw component tree from the flat token stream. */
+function buildTree(src: string): RawNode[] {
+  const tokens = tokenize(src);
+  const root: RawNode = { type: 'ROOT', props: [], children: [] };
+  const stack: RawNode[] = [root];
+
+  for (const token of tokens) {
+    const current = stack[stack.length - 1]!;
+
+    if (token.name === 'BEGIN') {
+      const node: RawNode = {
+        type: token.value.toUpperCase().trim(),
+        props: [],
+        children: [],
+      };
+      current.children.push(node);
+      stack.push(node);
+    } else if (token.name === 'END') {
+      if (stack.length > 1) stack.pop();
+      // Tolerant: if stack is empty we ignore the END
+    } else {
+      // Normalize params: ensure all values are strings (flatten single-element arrays)
+      const params: Record<string, string> = {};
+      for (const [k, v] of Object.entries(token.params)) {
+        params[k] = Array.isArray(v) ? (v as string[]).join(',') : String(v);
+      }
+      current.props.push({ name: token.name, params, value: token.value });
+    }
+  }
+
+  return root.children;
+}
+
+// ── Component builders ────────────────────────────────────────────────────
+
+function buildComponent(node: RawNode): Component {
+  switch (node.type) {
+    case 'VCALENDAR':  return buildCalendar(node);
+    case 'VEVENT':     return buildEvent(node);
+    case 'VTODO':      return buildTodo(node);
+    case 'VJOURNAL':   return buildJournal(node);
+    case 'VFREEBUSY':  return buildFreebusy(node);
+    case 'VTIMEZONE':  return buildTimezone(node);
+    case 'VALARM':     return buildAlarm(node);
+    case 'STANDARD':
+    case 'DAYLIGHT':   return buildTimezoneRule(node.type, node.props);
+    default:           return buildGeneric(node);
+  }
+}
+
+function buildCalendar(node: RawNode): Calendar {
+  const children = node.children.map(buildComponent);
+  return Calendar.fromRaw(node.props, children);
+}
+
+function buildEvent(node: RawNode): Event {
+  const children = node.children.map(buildComponent);
+  return Event.fromRaw(node.props, children);
+}
+
+function buildTodo(node: RawNode): Todo {
+  const children = node.children.map(buildComponent);
+  return Todo.fromRaw(node.props, children);
+}
+
+function buildJournal(node: RawNode): Journal {
+  return Journal.fromRaw(node.props);
+}
+
+function buildFreebusy(node: RawNode): FreeBusy {
+  return FreeBusy.fromRaw(node.props);
+}
+
+function buildTimezone(node: RawNode): Timezone {
+  const children = node.children.map(buildComponent);
+  return Timezone.fromRaw(node.props, children);
+}
+
+function buildAlarm(node: RawNode): Alarm {
+  return Alarm.fromRaw(node.props);
+}
+
+function buildGeneric(node: RawNode): Component {
+  const comp = new Component(node.type);
+  for (const { name, params, value } of node.props) {
+    comp.addProperty(parseProperty(name, value, params));
+  }
+  for (const child of node.children) {
+    comp.addComponent(buildComponent(child));
+  }
+  return comp;
+}
+
+// ── Public API ────────────────────────────────────────────────────────────
+
+/**
+ * Parse an iCalendar string and return a Calendar object.
+ *
+ * Tolerant: if the input has no VCALENDAR wrapper (e.g. just a bare VEVENT)
+ * the content is wrapped in a synthetic Calendar.
+ *
+ * @throws Only on completely unparseable input that yields zero tokens.
+ */
+export function parse(src: string): Calendar {
+  const roots = buildTree(src);
+
+  // Find the first VCALENDAR
+  const calNode = roots.find((n) => n.type === 'VCALENDAR');
+  if (calNode) {
+    return buildCalendar(calNode);
+  }
+
+  // Tolerant: no VCALENDAR wrapper — synthesize one
+  const cal = new Calendar();
+  for (const node of roots) {
+    cal.addComponent(buildComponent(node));
+  }
+  return cal;
+}
+
+/**
+ * Parse an iCalendar string and return all top-level Calendar objects.
+ * Some feeds embed multiple VCALENDAR blocks in a single file.
+ */
+export function parseAll(src: string): Calendar[] {
+  const roots = buildTree(src);
+  const calendars = roots.filter((n) => n.type === 'VCALENDAR');
+
+  if (calendars.length > 0) {
+    return calendars.map(buildCalendar);
+  }
+
+  // No VCALENDAR blocks — wrap everything in one
+  return [parse(src)];
+}

package/src/property-registry.ts

@@ -0,0 +1,124 @@
+/**
+ * RFC 5545 property registry.
+ *
+ * Maps property names to their default value type, allowed alternative types,
+ * whether they accept a list of values, and which components they belong to.
+ */
+
+export type ValueTypeName =
+  | 'TEXT'
+  | 'INTEGER'
+  | 'FLOAT'
+  | 'BOOLEAN'
+  | 'URI'
+  | 'CAL-ADDRESS'
+  | 'BINARY'
+  | 'UTC-OFFSET'
+  | 'DATE'
+  | 'DATE-TIME'
+  | 'TIME'
+  | 'DURATION'
+  | 'PERIOD'
+  | 'RECUR'
+  | 'GEO';
+
+export interface PropertyDef {
+  /** Default value type when no VALUE= parameter is present */
+  readonly defaultType: ValueTypeName;
+  /** Additional allowed value types selectable via VALUE= parameter */
+  readonly allowedTypes?: readonly ValueTypeName[];
+  /**
+   * true  → value is a comma-separated list of the same type
+   * false → single value
+   */
+  readonly multi?: boolean;
+}
+
+/**
+ * RFC 5545 §3.8 — Component Properties
+ * Includes deprecated but commonly encountered properties (EXRULE).
+ */
+export const PROPERTY_REGISTRY: Readonly<Record<string, PropertyDef>> = {
+  // ── Calendar Properties (§3.7) ─────────────────────────────────────────
+  CALSCALE:         { defaultType: 'TEXT' },
+  METHOD:           { defaultType: 'TEXT' },
+  PRODID:           { defaultType: 'TEXT' },
+  VERSION:          { defaultType: 'TEXT' },
+
+  // ── Descriptive Component Properties (§3.8.1) ──────────────────────────
+  ATTACH:           { defaultType: 'URI', allowedTypes: ['BINARY'] },
+  CATEGORIES:       { defaultType: 'TEXT', multi: true },
+  CLASS:            { defaultType: 'TEXT' },
+  COMMENT:          { defaultType: 'TEXT' },
+  DESCRIPTION:      { defaultType: 'TEXT' },
+  GEO:              { defaultType: 'GEO' },
+  LOCATION:         { defaultType: 'TEXT' },
+  'PERCENT-COMPLETE': { defaultType: 'INTEGER' },
+  PRIORITY:         { defaultType: 'INTEGER' },
+  RESOURCES:        { defaultType: 'TEXT', multi: true },
+  STATUS:           { defaultType: 'TEXT' },
+  SUMMARY:          { defaultType: 'TEXT' },
+
+  // ── Date and Time Component Properties (§3.8.2) ───────────────────────
+  COMPLETED:        { defaultType: 'DATE-TIME' },
+  DTEND:            { defaultType: 'DATE-TIME', allowedTypes: ['DATE'] },
+  DUE:              { defaultType: 'DATE-TIME', allowedTypes: ['DATE'] },
+  DTSTART:          { defaultType: 'DATE-TIME', allowedTypes: ['DATE'] },
+  DURATION:         { defaultType: 'DURATION' },
+  FREEBUSY:         { defaultType: 'PERIOD', multi: true },
+  TRANSP:           { defaultType: 'TEXT' },
+
+  // ── Time Zone Component Properties (§3.8.3) ───────────────────────────
+  TZID:             { defaultType: 'TEXT' },
+  TZNAME:           { defaultType: 'TEXT' },
+  TZOFFSETFROM:     { defaultType: 'UTC-OFFSET' },
+  TZOFFSETTO:       { defaultType: 'UTC-OFFSET' },
+  TZURL:            { defaultType: 'URI' },
+
+  // ── Relationship Component Properties (§3.8.4) ────────────────────────
+  ATTENDEE:         { defaultType: 'CAL-ADDRESS' },
+  CONTACT:          { defaultType: 'TEXT' },
+  ORGANIZER:        { defaultType: 'CAL-ADDRESS' },
+  'RECURRENCE-ID':  { defaultType: 'DATE-TIME', allowedTypes: ['DATE'] },
+  'RELATED-TO':     { defaultType: 'TEXT' },
+  URL:              { defaultType: 'URI' },
+  UID:              { defaultType: 'TEXT' },
+
+  // ── Recurrence Component Properties (§3.8.5) ──────────────────────────
+  EXDATE:           { defaultType: 'DATE-TIME', allowedTypes: ['DATE'], multi: true },
+  RDATE:            { defaultType: 'DATE-TIME', allowedTypes: ['DATE', 'PERIOD'], multi: true },
+  RRULE:            { defaultType: 'RECUR' },
+  EXRULE:           { defaultType: 'RECUR' }, // deprecated, still common
+
+  // ── Alarm Component Properties (§3.8.6) ───────────────────────────────
+  ACTION:           { defaultType: 'TEXT' },
+  REPEAT:           { defaultType: 'INTEGER' },
+  TRIGGER:          { defaultType: 'DURATION', allowedTypes: ['DATE-TIME'] },
+
+  // ── Change Management Component Properties (§3.8.7) ──────────────────
+  CREATED:          { defaultType: 'DATE-TIME' },
+  DTSTAMP:          { defaultType: 'DATE-TIME' },
+  'LAST-MODIFIED':  { defaultType: 'DATE-TIME' },
+  SEQUENCE:         { defaultType: 'INTEGER' },
+
+  // ── Miscellaneous Component Properties (§3.8.8) ───────────────────────
+  'REQUEST-STATUS': { defaultType: 'TEXT' },
+};
+
+/** Look up a property definition; returns undefined for X- and unknown properties. */
+export function getPropertyDef(name: string): PropertyDef | undefined {
+  return PROPERTY_REGISTRY[name];
+}
+
+/**
+ * Determine the effective value type for a content line.
+ * Respects VALUE= parameter override.
+ */
+export function resolveValueType(
+  name: string,
+  params: Readonly<Record<string, string | readonly string[]>>,
+): ValueTypeName {
+  const override = typeof params['VALUE'] === 'string' ? params['VALUE'].toUpperCase() : undefined;
+  if (override) return override as ValueTypeName;
+  return PROPERTY_REGISTRY[name]?.defaultType ?? 'TEXT';
+}

package/src/property.ts

@@ -0,0 +1,163 @@
+/**
+ * Property — a named, parametered, typed iCalendar property.
+ *
+ * Strict on construction (required for serialization).
+ * Tolerant when created from raw parsed data.
+ */
+
+import type { ICalValue, ParsedProperty } from './types.js';
+import { CODECS, GEO } from './value-types.js';
+import { getPropertyDef, resolveValueType } from './property-registry.js';
+import type { ValueTypeName } from './property-registry.js';
+
+export class Property implements ParsedProperty {
+  readonly name: string;
+  readonly params: Readonly<Record<string, string | readonly string[]>>;
+  readonly value: ICalValue | readonly ICalValue[];
+  readonly rawValue: string;
+
+  constructor(
+    name: string,
+    value: ICalValue | readonly ICalValue[],
+    params: Readonly<Record<string, string | readonly string[]>> = {},
+    rawValue = '',
+  ) {
+    this.name = name.toUpperCase();
+    this.value = value;
+    this.params = params;
+    this.rawValue = rawValue;
+  }
+
+  /** Get the first (or only) value as a plain value (null when the list is empty). */
+  get scalar(): ICalValue | null {
+    const v = this.value;
+    if (Array.isArray(v)) return (v as ICalValue[])[0] ?? null;
+    return v as ICalValue;
+  }
+
+  /** Get the value as an array (always). */
+  get list(): ICalValue[] {
+    const v = this.value;
+    if (Array.isArray(v)) return [...(v as ICalValue[])];
+    return [v as ICalValue];
+  }
+
+  /** Convenience: get value as string (or null). */
+  get text(): string | null {
+    const v = this.scalar;
+    return typeof v === 'string' ? v : null;
+  }
+
+  /** Convenience: get value as number (or null). */
+  get number(): number | null {
+    const v = this.scalar;
+    return typeof v === 'number' ? v : null;
+  }
+
+  /** Convenience: get value as boolean. */
+  get boolean(): boolean | null {
+    const v = this.scalar;
+    return typeof v === 'boolean' ? v : null;
+  }
+
+  /**
+   * Serialize this property to a single (unfolded) content line string.
+   * Throws if the value type cannot be serialized.
+   */
+  toContentLine(): string {
+    const paramStr = serializeParams(this.params);
+    const valueStr = this.serializeValue();
+    return `${this.name}${paramStr}:${valueStr}`;
+  }
+
+  private serializeValue(): string {
+    const def = getPropertyDef(this.name);
+    const typeName = resolveValueType(this.name, this.params);
+
+    if (typeName === 'GEO') {
+      const v = this.scalar as { type: 'geo'; latitude: number; longitude: number };
+      return GEO.serialize(v);
+    }
+
+    const codec = CODECS[typeName];
+
+    const serialize = (v: ICalValue): string => {
+      if (codec) return codec.serialize(v);
+      // Unknown / X- property: convert to string
+      return String(v ?? '');
+    };
+
+    if (def?.multi && Array.isArray(this.value)) {
+      return this.value.map(serialize).join(',');
+    }
+    return serialize(Array.isArray(this.value) ? (this.value[0] ?? '') : this.value);
+  }
+}
+
+function serializeParams(
+  params: Readonly<Record<string, string | readonly string[]>>,
+): string {
+  let result = '';
+  for (const [key, val] of Object.entries(params)) {
+    const valStr = Array.isArray(val) ? val.join(',') : val;
+    // Quote if contains special characters
+    const needsQuote = /[;:,]/.test(valStr as string);
+    result += `;${key}=${needsQuote ? `"${valStr}"` : valStr}`;
+  }
+  return result;
+}
+
+// ── Factory ───────────────────────────────────────────────────────────────
+
+/**
+ * Parse a raw content-line value string into a typed Property.
+ * Tolerant: unknown value types fall back to TEXT.
+ */
+export function parseProperty(
+  name: string,
+  rawValue: string,
+  params: Readonly<Record<string, string | readonly string[]>>,
+): Property {
+  const typeName = resolveValueType(name, params) as ValueTypeName;
+  const def = getPropertyDef(name);
+
+  try {
+    if (typeName === 'GEO') {
+      return new Property(name, GEO.parse(rawValue), params, rawValue);
+    }
+
+    const codec = CODECS[typeName] ?? CODECS['TEXT']!;
+
+    if (def?.multi) {
+      // Split on unescaped commas
+      const parts = splitMultiValue(rawValue);
+      const values = parts.map((p) => codec.parse(p, params) as ICalValue);
+      return new Property(name, values, params, rawValue);
+    }
+
+    const value = codec.parse(rawValue, params) as ICalValue;
+    return new Property(name, value, params, rawValue);
+  } catch {
+    // Tolerant fallback: store as raw string
+    return new Property(name, rawValue, params, rawValue);
+  }
+}
+
+/** Split a comma-separated multi-value string, respecting backslash escapes. */
+function splitMultiValue(raw: string): string[] {
+  const parts: string[] = [];
+  let current = '';
+  for (let i = 0; i < raw.length; i++) {
+    if (raw[i] === '\\' && i + 1 < raw.length) {
+      current += raw[i]! + raw[i + 1]!;
+      i++;
+    } else if (raw[i] === ',') {
+      parts.push(current);
+      current = '';
+    } else {
+      current += raw[i]!;
+    }
+  }
+  parts.push(current);
+  return parts;
+}

package/src/timezone.ts

@@ -0,0 +1,169 @@
+/**
+ * VTIMEZONE, DAYLIGHT, and STANDARD components (RFC 5545 §3.6.5)
+ *
+ * VTIMEZONE contains one or more DAYLIGHT or STANDARD sub-components that
+ * define the UTC offset rules.
+ */
+
+import { Component } from './component.js';
+import { parseProperty } from './property.js';
+import type { ICalDateTime, ICalUtcOffset, ICalRecur } from './types.js';
+
+// ── STANDARD / DAYLIGHT ──────────────────────────────────────────────────
+
+export class TimezoneRule extends Component {
+  constructor(type: 'STANDARD' | 'DAYLIGHT') {
+    super(type);
+  }
+
+  get dtstart(): ICalDateTime | null {
+    const v = this.getValue('DTSTART');
+    return typeof v === 'object' && v !== null && v.type === 'date-time'
+      ? (v as ICalDateTime)
+      : null;
+  }
+  set dtstart(v: ICalDateTime) {
+    this.setProperty('DTSTART', v);
+  }
+
+  get tzoffsetfrom(): ICalUtcOffset | null {
+    const v = this.getValue('TZOFFSETFROM');
+    return typeof v === 'object' && v !== null && v.type === 'utc-offset'
+      ? (v as ICalUtcOffset)
+      : null;
+  }
+  set tzoffsetfrom(v: ICalUtcOffset) {
+    this.setProperty('TZOFFSETFROM', v);
+  }
+
+  get tzoffsetto(): ICalUtcOffset | null {
+    const v = this.getValue('TZOFFSETTO');
+    return typeof v === 'object' && v !== null && v.type === 'utc-offset'
+      ? (v as ICalUtcOffset)
+      : null;
+  }
+  set tzoffsetto(v: ICalUtcOffset) {
+    this.setProperty('TZOFFSETTO', v);
+  }
+
+  get tzname(): string | null {
+    return this.getProperty('TZNAME')?.text ?? null;
+  }
+  set tzname(v: string) {
+    this.setProperty('TZNAME', v);
+  }
+
+  get rrule(): ICalRecur | null {
+    const v = this.getValue('RRULE');
+    return typeof v === 'object' && v !== null && v.type === 'recur' ? (v as ICalRecur) : null;
+  }
+  set rrule(v: ICalRecur) {
+    this.setProperty('RRULE', v);
+  }
+
+  // ── Strict validation ────────────────────────────────────────────────
+
+  override toString(): string {
+    if (!this.dtstart) throw new Error(`${this.type}: DTSTART is required`);
+    if (!this.tzoffsetfrom) throw new Error(`${this.type}: TZOFFSETFROM is required`);
+    if (!this.tzoffsetto) throw new Error(`${this.type}: TZOFFSETTO is required`);
+    return super.toString();
+  }
+}
+
+export class Standard extends TimezoneRule {
+  constructor() { super('STANDARD'); }
+}
+
+export class Daylight extends TimezoneRule {
+  constructor() { super('DAYLIGHT'); }
+}
+
+// ── VTIMEZONE ─────────────────────────────────────────────────────────────
+
+export class Timezone extends Component {
+  constructor() {
+    super('VTIMEZONE');
+  }
+
+  /** TZID is required (RFC 5545 §3.6.5). */
+  get tzid(): string | null {
+    return this.getProperty('TZID')?.text ?? null;
+  }
+  set tzid(v: string) {
+    this.setProperty('TZID', v);
+  }
+
+  get tzurl(): string | null {
+    return this.getProperty('TZURL')?.text ?? null;
+  }
+  set tzurl(v: string) {
+    this.setProperty('TZURL', v);
+  }
+
+  get lastModified(): ICalDateTime | null {
+    const v = this.getValue('LAST-MODIFIED');
+    return typeof v === 'object' && v !== null && v.type === 'date-time'
+      ? (v as ICalDateTime)
+      : null;
+  }
+  set lastModified(v: ICalDateTime) {
+    this.setProperty('LAST-MODIFIED', v);
+  }
+
+  get standardRules(): TimezoneRule[] {
+    return this.getComponents('STANDARD') as TimezoneRule[];
+  }
+
+  get daylightRules(): TimezoneRule[] {
+    return this.getComponents('DAYLIGHT') as TimezoneRule[];
+  }
+
+  addStandard(rule: Standard): this {
+    this.addComponent(rule);
+    return this;
+  }
+
+  addDaylight(rule: Daylight): this {
+    this.addComponent(rule);
+    return this;
+  }
+
+  // ── Strict validation ────────────────────────────────────────────────
+
+  override toString(): string {
+    if (!this.tzid) throw new Error('VTIMEZONE: TZID is required');
+    if (this.components.length === 0) {
+      throw new Error('VTIMEZONE: at least one STANDARD or DAYLIGHT sub-component is required');
+    }
+    return super.toString();
+  }
+
+  // ── Factory ──────────────────────────────────────────────────────────
+
+  static fromRaw(
+    props: ReadonlyArray<{ name: string; params: Record<string, string>; value: string }>,
+    subcomponents: Component[],
+  ): Timezone {
+    const tz = new Timezone();
+    for (const { name, params, value } of props) {
+      tz.addProperty(parseProperty(name, value, params));
+    }
+    for (const sub of subcomponents) {
+      tz.addComponent(sub);
+    }
+    return tz;
+  }
+}
+
+/** Build a TimezoneRule (STANDARD or DAYLIGHT) from raw parsed data. */
+export function buildTimezoneRule(
+  type: string,
+  props: ReadonlyArray<{ name: string; params: Record<string, string>; value: string }>,
+): TimezoneRule {
+  const rule = type.toUpperCase() === 'DAYLIGHT' ? new Daylight() : new Standard();
+  for (const { name, params, value } of props) {
+    rule.addProperty(parseProperty(name, value, params));
+  }
+  return rule;
+}