@leigh-chr/ics-utils

TypeScript utilities for parsing and generating ICS (iCalendar) files according to RFC 5545.

Features

• Parse ICS files into typed JavaScript objects
• Generate valid ICS files from event data
• Full support for recurring events (RRULE)
• Alarm/reminder handling (VALARM)
• Attendee management
• Date and duration utilities
• Zero configuration required
• TypeScript-first with full type definitions

Installation

npm install @leigh-chr/ics-utils
# or
bun add @leigh-chr/ics-utils
# or
pnpm add @leigh-chr/ics-utils

Quick Start

import { parseIcsFile, generateIcsFile } from '@leigh-chr/ics-utils';

// Parse an ICS file
const { events, errors } = parseIcsFile(icsContent);
console.log(events[0].title);
console.log(events[0].startDate);

// Generate an ICS file
const ics = generateIcsFile({
  calendarName: 'My Calendar',
  events: [{
    title: 'Team Meeting',
    startDate: new Date('2024-01-15T10:00:00Z'),
    endDate: new Date('2024-01-15T11:00:00Z'),
    description: 'Weekly sync',
    location: 'Conference Room A',
  }]
});

API Reference

Parser

import { parseIcsFile } from '@leigh-chr/ics-utils';

const result = parseIcsFile(icsString);
// Returns: { events: ParsedEvent[], errors: string[] }

Generator

import { generateIcsFile } from '@leigh-chr/ics-utils';

const ics = generateIcsFile({
  calendarName: 'My Calendar',
  events: [{
    title: 'Event Title',
    startDate: new Date(),
    endDate: new Date(),
    // Optional fields:
    description: 'Event description',
    location: 'Event location',
    uid: 'unique-id',
    rrule: 'FREQ=WEEKLY;COUNT=10',
    alarms: [{ trigger: '-PT15M', action: 'DISPLAY' }],
    attendees: [{ email: '[email protected]' }],
  }]
});

Date Utilities

import {
  formatDateToICS,
  parseDateFromICS,
  formatDateOnlyToICS,
  isValidIcsDate
} from '@leigh-chr/ics-utils';

// Format JavaScript Date to ICS format
formatDateToICS(new Date());           // '20240115T100000Z'

// Parse ICS date string to JavaScript Date
parseDateFromICS('20240115T100000Z');  // Date object

// Format date-only (for all-day events)
formatDateOnlyToICS(new Date());       // '20240115'

// Validate ICS date format
isValidIcsDate('20240115T100000Z');    // true

Duration Utilities

import {
  formatDuration,
  parseDuration,
  durationToMinutes,
  isValidDuration
} from '@leigh-chr/ics-utils';

// Format to ISO 8601 duration
formatDuration(15, 'minutes');  // 'PT15M'
formatDuration(2, 'hours');     // 'PT2H'
formatDuration(1, 'days');      // 'P1D'

// Parse ISO 8601 duration
parseDuration('PT15M');         // { value: 15, unit: 'minutes' }
parseDuration('PT2H');          // { value: 2, unit: 'hours' }

// Convert to minutes
durationToMinutes('PT2H');      // 120

// Validate duration format
isValidDuration('PT15M');       // true

Alarm Utilities

import {
  parseAlarmTrigger,
  formatAlarmTrigger
} from '@leigh-chr/ics-utils';

// Parse alarm trigger
parseAlarmTrigger('-PT15M');
// { when: 'before', value: 15, unit: 'minutes' }

parseAlarmTrigger('PT30M');
// { when: 'after', value: 30, unit: 'minutes' }

// Format alarm trigger
formatAlarmTrigger('before', 15, 'minutes');  // '-PT15M'
formatAlarmTrigger('after', 1, 'hours');      // 'PT1H'

Types

import type {
  ParsedEvent,
  ParsedAlarm,
  ParsedAttendee,
  EventInput,
  GeneratorOptions,
  ParseResult,
  AlarmTrigger,
  DurationUnit,
} from '@leigh-chr/ics-utils';

ParsedEvent

interface ParsedEvent {
  uid: string;
  title: string;
  description?: string;
  location?: string;
  startDate: Date;
  endDate?: Date;
  allDay: boolean;
  rrule?: string;
  recurrenceId?: Date;
  exdates?: Date[];
  alarms: ParsedAlarm[];
  attendees: ParsedAttendee[];
  organizer?: { name?: string; email: string };
  status?: string;
  categories?: string[];
  created?: Date;
  lastModified?: Date;
}

Subpath Exports

For tree-shaking, you can import specific modules:

import { parseIcsFile } from '@leigh-chr/ics-utils/parser';
import { generateIcsFile } from '@leigh-chr/ics-utils/generator';
import { formatDateToICS } from '@leigh-chr/ics-utils/date';
import { formatDuration } from '@leigh-chr/ics-utils/duration';
import { parseAlarmTrigger } from '@leigh-chr/ics-utils/alarm';

License

AGPL-3.0 - See LICENSE for details.

Contributing

Contributions are welcome! Please see our Contributing Guide.