@pipobscure/ical 0.0.1

package/src/todo.ts

@@ -0,0 +1,253 @@
+/**
+ * VTODO component (RFC 5545 §3.6.2)
+ *
+ * UID and DTSTAMP are required.
+ * DTSTART and DUE/DURATION are optional.
+ * DTEND MUST NOT be present when DURATION is present.
+ */
+
+import { Component } from './component.js';
+import { Property, parseProperty } from './property.js';
+import { Alarm } from './alarm.js';
+import type { ICalDate, ICalDateTime, ICalDuration, ICalRecur, ICalGeo, ICalValue } from './types.js';
+
+export class Todo extends Component {
+  constructor() {
+    super('VTODO');
+  }
+
+  // ── Required ─────────────────────────────────────────────────────────
+
+  get uid(): string | null {
+    return this.getProperty('UID')?.text ?? null;
+  }
+  set uid(v: string) {
+    this.setProperty('UID', v);
+  }
+
+  get dtstamp(): ICalDateTime | null {
+    const v = this.getValue('DTSTAMP');
+    return v && typeof v === 'object' && v.type === 'date-time' ? (v as ICalDateTime) : null;
+  }
+  set dtstamp(v: ICalDateTime | Date) {
+    this.setProperty('DTSTAMP', v instanceof Date
+      ? { type: 'date-time', year: v.getUTCFullYear(), month: v.getUTCMonth() + 1, day: v.getUTCDate(), hour: v.getUTCHours(), minute: v.getUTCMinutes(), second: v.getUTCSeconds(), utc: true } satisfies ICalDateTime
+      : v);
+  }
+
+  // ── Date/time ─────────────────────────────────────────────────────────
+
+  get dtstart(): ICalDateTime | ICalDate | null {
+    const v = this.getValue('DTSTART');
+    if (!v || typeof v !== 'object') return null;
+    return v.type === 'date-time' || v.type === 'date' ? (v as ICalDateTime | ICalDate) : null;
+  }
+  set dtstart(v: ICalDateTime | ICalDate | Date) {
+    if (v instanceof Date) {
+      this.setProperty('DTSTART', { type: 'date-time', year: v.getUTCFullYear(), month: v.getUTCMonth() + 1, day: v.getUTCDate(), hour: v.getUTCHours(), minute: v.getUTCMinutes(), second: v.getUTCSeconds(), utc: true } satisfies ICalDateTime);
+    } else if (v.type === 'date') {
+      this.setProperty('DTSTART', v, { VALUE: 'DATE' });
+    } else {
+      this.setProperty('DTSTART', v);
+    }
+  }
+
+  get due(): ICalDateTime | ICalDate | null {
+    const v = this.getValue('DUE');
+    if (!v || typeof v !== 'object') return null;
+    return v.type === 'date-time' || v.type === 'date' ? (v as ICalDateTime | ICalDate) : null;
+  }
+  set due(v: ICalDateTime | ICalDate | Date) {
+    if (v instanceof Date) {
+      this.setProperty('DUE', { type: 'date-time', year: v.getUTCFullYear(), month: v.getUTCMonth() + 1, day: v.getUTCDate(), hour: v.getUTCHours(), minute: v.getUTCMinutes(), second: v.getUTCSeconds(), utc: true } satisfies ICalDateTime);
+    } else if (v.type === 'date') {
+      this.setProperty('DUE', v, { VALUE: 'DATE' });
+    } else {
+      this.setProperty('DUE', v);
+    }
+  }
+
+  get completed(): ICalDateTime | null {
+    const v = this.getValue('COMPLETED');
+    return v && typeof v === 'object' && v.type === 'date-time' ? (v as ICalDateTime) : null;
+  }
+  set completed(v: ICalDateTime | Date) {
+    this.setProperty('COMPLETED', v instanceof Date
+      ? { type: 'date-time', year: v.getUTCFullYear(), month: v.getUTCMonth() + 1, day: v.getUTCDate(), hour: v.getUTCHours(), minute: v.getUTCMinutes(), second: v.getUTCSeconds(), utc: true } satisfies ICalDateTime
+      : v);
+  }
+
+  get duration(): ICalDuration | null {
+    const v = this.getValue('DURATION');
+    return v && typeof v === 'object' && v.type === 'duration' ? (v as ICalDuration) : null;
+  }
+  set duration(v: ICalDuration) {
+    this.setProperty('DURATION', v);
+  }
+
+  // ── Descriptive ──────────────────────────────────────────────────────
+
+  get summary(): string | null {
+    return this.getProperty('SUMMARY')?.text ?? null;
+  }
+  set summary(v: string) {
+    this.setProperty('SUMMARY', v);
+  }
+
+  get description(): string | null {
+    return this.getProperty('DESCRIPTION')?.text ?? null;
+  }
+  set description(v: string) {
+    this.setProperty('DESCRIPTION', v);
+  }
+
+  get location(): string | null {
+    return this.getProperty('LOCATION')?.text ?? null;
+  }
+  set location(v: string) {
+    this.setProperty('LOCATION', v);
+  }
+
+  get status(): 'NEEDS-ACTION' | 'COMPLETED' | 'IN-PROCESS' | 'CANCELLED' | string | null {
+    return this.getProperty('STATUS')?.text ?? null;
+  }
+  set status(v: string) {
+    this.setProperty('STATUS', v);
+  }
+
+  get priority(): number | null {
+    return this.getProperty('PRIORITY')?.number ?? null;
+  }
+  set priority(v: number) {
+    this.setProperty('PRIORITY', Math.max(0, Math.min(9, Math.trunc(v))));
+  }
+
+  get percentComplete(): number | null {
+    return this.getProperty('PERCENT-COMPLETE')?.number ?? null;
+  }
+  set percentComplete(v: number) {
+    this.setProperty('PERCENT-COMPLETE', Math.max(0, Math.min(100, Math.trunc(v))));
+  }
+
+  get sequence(): number | null {
+    return this.getProperty('SEQUENCE')?.number ?? null;
+  }
+  set sequence(v: number) {
+    this.setProperty('SEQUENCE', Math.max(0, Math.trunc(v)));
+  }
+
+  get klass(): string | null {
+    return this.getProperty('CLASS')?.text ?? null;
+  }
+  set klass(v: string) {
+    this.setProperty('CLASS', v);
+  }
+
+  get url(): string | null {
+    return this.getProperty('URL')?.text ?? null;
+  }
+  set url(v: string) {
+    this.setProperty('URL', v);
+  }
+
+  get geo(): ICalGeo | null {
+    const v = this.getValue('GEO');
+    return v && typeof v === 'object' && v.type === 'geo' ? (v as ICalGeo) : null;
+  }
+  set geo(v: ICalGeo) {
+    this.setProperty('GEO', v);
+  }
+
+  get organizer(): string | null {
+    return this.getProperty('ORGANIZER')?.text ?? null;
+  }
+  set organizer(v: string) {
+    this.setProperty('ORGANIZER', v);
+  }
+
+  get created(): ICalDateTime | null {
+    const v = this.getValue('CREATED');
+    return v && typeof v === 'object' && v.type === 'date-time' ? (v as ICalDateTime) : null;
+  }
+  set created(v: ICalDateTime | Date) {
+    this.setProperty('CREATED', v instanceof Date
+      ? { type: 'date-time', year: v.getUTCFullYear(), month: v.getUTCMonth() + 1, day: v.getUTCDate(), hour: v.getUTCHours(), minute: v.getUTCMinutes(), second: v.getUTCSeconds(), utc: true } satisfies ICalDateTime
+      : v);
+  }
+
+  get lastModified(): ICalDateTime | null {
+    const v = this.getValue('LAST-MODIFIED');
+    return v && typeof v === 'object' && v.type === 'date-time' ? (v as ICalDateTime) : null;
+  }
+  set lastModified(v: ICalDateTime | Date) {
+    this.setProperty('LAST-MODIFIED', v instanceof Date
+      ? { type: 'date-time', year: v.getUTCFullYear(), month: v.getUTCMonth() + 1, day: v.getUTCDate(), hour: v.getUTCHours(), minute: v.getUTCMinutes(), second: v.getUTCSeconds(), utc: true } satisfies ICalDateTime
+      : v);
+  }
+
+  // ── Multi-occurrence ──────────────────────────────────────────────────
+
+  get attendees(): Property[] {
+    return this.getProperties('ATTENDEE');
+  }
+
+  addAttendee(calAddress: string, params: Record<string, string> = {}): this {
+    this.appendProperty('ATTENDEE', calAddress, params);
+    return this;
+  }
+
+  get categories(): ICalValue[] {
+    return this.getValues('CATEGORIES');
+  }
+
+  set categories(v: string[]) {
+    this.setProperty('CATEGORIES', v);
+  }
+
+  get rrules(): ICalRecur[] {
+    return this.getProperties('RRULE')
+      .map((p) => p.scalar)
+      .filter((v): v is ICalRecur => typeof v === 'object' && v !== null && v.type === 'recur');
+  }
+
+  addRrule(v: ICalRecur): this {
+    this.appendProperty('RRULE', v);
+    return this;
+  }
+
+  get alarms(): Alarm[] {
+    return this.getComponents('VALARM') as Alarm[];
+  }
+
+  addAlarm(alarm: Alarm): this {
+    this.addComponent(alarm);
+    return this;
+  }
+
+  // ── Validation ────────────────────────────────────────────────────────
+
+  override toString(): string {
+    if (!this.uid) throw new Error('VTODO: UID is required');
+    if (!this.getProperty('DTSTAMP')) throw new Error('VTODO: DTSTAMP is required');
+    if (this.getProperty('DUE') && this.getProperty('DURATION')) {
+      throw new Error('VTODO: DUE and DURATION MUST NOT both be present');
+    }
+    return super.toString();
+  }
+
+  // ── Factory ──────────────────────────────────────────────────────────
+
+  static fromRaw(
+    props: ReadonlyArray<{ name: string; params: Record<string, string>; value: string }>,
+    subcomponents: Component[] = [],
+  ): Todo {
+    const todo = new Todo();
+    for (const { name, params, value } of props) {
+      todo.addProperty(parseProperty(name, value, params));
+    }
+    for (const sub of subcomponents) {
+      todo.addComponent(sub);
+    }
+    return todo;
+  }
+}

package/src/tokenize.ts

@@ -0,0 +1,99 @@
+/**
+ * Low-level iCalendar tokenizer.
+ *
+ * Handles:
+ * - CRLF, LF, and bare CR line endings (tolerant)
+ * - Line unfolding (RFC 5545 §3.1: lines starting with SPACE or HTAB are continuations)
+ * - Content line parsing: name, parameters, value
+ * - Quoted parameter values
+ * - Multi-value parameters (comma-separated)
+ */
+
+import type { ContentLine } from './types.js';
+
+/** Normalize line endings and unfold continuation lines. */
+function unfold(str: string): string {
+  return str
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+    .replace(/\n[ \t]/g, ''); // RFC 5545 §3.1 unfolding
+}
+
+/**
+ * Parse a single content line into its name, parameters, and value.
+ * Returns null for empty or unparseable lines (tolerant).
+ */
+export function parseContentLine(line: string): ContentLine | null {
+  const len = line.length;
+  if (len === 0) return null;
+
+  let i = 0;
+
+  // ── name ──────────────────────────────────────────────────────────────────
+  // RFC 5545: name = iana-token / x-name
+  // iana-token = 1*(ALPHA / DIGIT / "-")
+  const nameStart = i;
+  while (i < len && line[i] !== ':' && line[i] !== ';') i++;
+  const name = line.slice(nameStart, i).trim().toUpperCase();
+  if (!name) return null;
+
+  // ── parameters ────────────────────────────────────────────────────────────
+  const params: Record<string, string | string[]> = {};
+
+  while (i < len && line[i] === ';') {
+    i++; // consume ';'
+
+    // param-name
+    const pnStart = i;
+    while (i < len && line[i] !== '=' && line[i] !== ';' && line[i] !== ':') i++;
+    const paramName = line.slice(pnStart, i).trim().toUpperCase();
+
+    const values: string[] = [];
+
+    if (i < len && line[i] === '=') {
+      i++; // consume '='
+
+      // One or more comma-separated param-values
+      do {
+        if (i < len && line[i] === '"') {
+          // Quoted string (DQUOTE *QSAFE-CHAR DQUOTE)
+          i++; // consume opening '"'
+          const vStart = i;
+          while (i < len && line[i] !== '"') i++;
+          values.push(line.slice(vStart, i));
+          if (i < len) i++; // consume closing '"'
+        } else {
+          // Unquoted param-value: everything up to ',' ';' ':'
+          const vStart = i;
+          while (i < len && line[i] !== ',' && line[i] !== ';' && line[i] !== ':') i++;
+          values.push(line.slice(vStart, i).trim());
+        }
+      } while (i < len && line[i] === ',' && ++i); // consume ',' between values
+    }
+
+    if (paramName) {
+      params[paramName] = values.length === 1 ? (values[0] ?? '') : values;
+    }
+  }
+
+  // ── value ─────────────────────────────────────────────────────────────────
+  if (i < len && line[i] === ':') i++; // consume ':'
+  const value = line.slice(i);
+
+  return { name, params, value };
+}
+
+/**
+ * Tokenize an iCalendar string into an array of content lines.
+ * Tolerant: skips blank lines and unparseable content.
+ */
+export function tokenize(src: string): ContentLine[] {
+  const lines = unfold(src).split('\n');
+  const result: ContentLine[] = [];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const parsed = parseContentLine(line);
+    if (parsed) result.push(parsed);
+  }
+  return result;
+}

package/src/types.ts

@@ -0,0 +1,135 @@
+/** All structured value types produced by the parser and consumed by the serializer. */
+
+export interface ICalDate {
+  readonly type: 'date';
+  readonly year: number;
+  readonly month: number;
+  readonly day: number;
+}
+
+export interface ICalDateTime {
+  readonly type: 'date-time';
+  readonly year: number;
+  readonly month: number;
+  readonly day: number;
+  readonly hour: number;
+  readonly minute: number;
+  readonly second: number;
+  /** true when value ends with 'Z' (UTC) */
+  readonly utc: boolean;
+  /** TZID parameter value when present */
+  readonly tzid?: string;
+}
+
+export interface ICalTime {
+  readonly type: 'time';
+  readonly hour: number;
+  readonly minute: number;
+  readonly second: number;
+  readonly utc: boolean;
+}
+
+export interface ICalDuration {
+  readonly type: 'duration';
+  readonly negative: boolean;
+  readonly weeks?: number;
+  readonly days?: number;
+  readonly hours?: number;
+  readonly minutes?: number;
+  readonly seconds?: number;
+}
+
+export interface ICalPeriod {
+  readonly type: 'period';
+  readonly start: ICalDateTime;
+  readonly end: ICalDateTime | ICalDuration;
+}
+
+export type RecurFreq =
+  | 'SECONDLY'
+  | 'MINUTELY'
+  | 'HOURLY'
+  | 'DAILY'
+  | 'WEEKLY'
+  | 'MONTHLY'
+  | 'YEARLY';
+
+export type Weekday = 'SU' | 'MO' | 'TU' | 'WE' | 'TH' | 'FR' | 'SA';
+
+export interface ByDayRule {
+  readonly day: Weekday;
+  /** ordinal week number, e.g. +1 = first, -1 = last */
+  readonly ordwk?: number;
+}
+
+export interface ICalRecur {
+  readonly type: 'recur';
+  readonly freq: RecurFreq;
+  readonly until?: ICalDate | ICalDateTime;
+  readonly count?: number;
+  readonly interval?: number;
+  readonly bysecond?: readonly number[];
+  readonly byminute?: readonly number[];
+  readonly byhour?: readonly number[];
+  readonly byday?: readonly ByDayRule[];
+  readonly bymonthday?: readonly number[];
+  readonly byyearday?: readonly number[];
+  readonly byweekno?: readonly number[];
+  readonly bymonth?: readonly number[];
+  readonly bysetpos?: readonly number[];
+  readonly wkst?: Weekday;
+}
+
+export interface ICalUtcOffset {
+  readonly type: 'utc-offset';
+  readonly sign: '+' | '-';
+  readonly hours: number;
+  readonly minutes: number;
+  readonly seconds?: number;
+}
+
+export interface ICalGeo {
+  readonly type: 'geo';
+  readonly latitude: number;
+  readonly longitude: number;
+}
+
+/** BINARY value — base64-encoded data wrapped in a tagged type for discriminated union safety */
+export interface ICalBinary {
+  readonly type: 'binary';
+  readonly data: Uint8Array;
+}
+
+/** Union of all structured iCal values — every member has a `type` discriminant */
+export type ICalStructured =
+  | ICalDate
+  | ICalDateTime
+  | ICalTime
+  | ICalDuration
+  | ICalPeriod
+  | ICalRecur
+  | ICalUtcOffset
+  | ICalGeo
+  | ICalBinary;
+
+/** Full iCal value union (scalars + structured) */
+export type ICalValue =
+  | string
+  | number
+  | boolean
+  | ICalStructured;
+
+/** A parsed content line before value interpretation */
+export interface ContentLine {
+  readonly name: string;
+  readonly params: Readonly<Record<string, string | readonly string[]>>;
+  readonly value: string;
+}
+
+/** A fully parsed property with typed value */
+export interface ParsedProperty {
+  readonly name: string;
+  readonly params: Readonly<Record<string, string | readonly string[]>>;
+  readonly value: ICalValue | readonly ICalValue[];
+  readonly rawValue: string;
+}