TS-ICS

This library can parse and create Ics files and provides TypeScript types for easy handling and aims to be fully RFC 5545 compliant.

Motivation

Many of the Ics libraries provide good functionality, but none of them are type safe. This library can parse Ics strings with any validator, thanks to Standard-Schema.

Installation

npm i ts-ics

generate

generateIcsCalendar

1import { generateIcsCalendar, type IcsCalendar } from "ts-ics";
2
3const calendar: IcsCalendar = {...}
4
5const icsCalendarString = generateIcsCalendar(calendar);

generateIcsEvent

1import { generateIcsEvent, type IcsEvent } from "ts-ics";
2
3const event: IcsEvent = {...}
4
5const icsEventString = generateIcsEvent(event);

generate non standard values

Non-standard values must be prefixed with X-. Unhandled non-standard values are automatically prefixed and converted to upper case, and the value is converted to a string.

1type NonStandard = { isCustomer: string }
2
3const calendar: IcsCalendar<NonStandard> = {
4  nonStandard: { isCustomer: "yeah" },
5  ...
6};
7
8const calendarString = generateIcsCalendar<NonStandard>(calendar, {
9  nonStandard: {
10    isCustomer: { name: "X-IS-CUSTOMER", generate: (v) => ({ value: v }) },
11  },
12});

parse

IcsCalendar

without parsing

1import { convertIcsCalendar, type IcsCalendar } from "ts-ics";
2
3const calendar: IcsCalendar = convertIcsCalendar(undefined, icsCalendarString);

parse with zod

1import { type IcsCalendar } from "ts-ics";
2import { parseIcsCalendar } from "@ts-ics/schema-zod";
3
4const calendarParsed: IcsCalendar = parseIcsCalendar(icsCalendarString);

provide your own validator

This library uses Standard-Schema under the hood, so every schema library that implements the spec can be used.

1import { convertIcsCalendar, type IcsCalendar } from "ts-ics";
2import { zIcsCalendar } from "@ts-ics/schema-zod";
3
4const calendar: IcsCalendar = convertIcsCalendar(
5  zIcsCalendar,
6  icsCalendarString
7);

IcsEvent

without parsing

1import { convertIcsEvent, type IcsEvent } from "ts-ics";
2
3const event: IcsEvent = convertIcsEvent(undefined, icsEventString);

parse with zod

1import { type IcsEvent } from "ts-ics";
2import { parseIcsEvent } from "@ts-ics/schema-zod";
3
4const eventParsed: IcsEvent = parseIcsEvent(icsEventString);

provide your own validator

This library uses Standard-Schema under the hood, so every schema library that implements the spec can be used.

1import { convertIcsEvent, type IcsEvent } from "ts-ics";
2import { zIcsEvent } from "@ts-ics/schema-zod";
3
4const calendar: IcsEvent = convertIcsEvent(zIcsEvent, icsEventString);

parse non standard values

Non-standard values must be prefixed with X-. Unhandled non-standard values are automatically un-prefixed and converted to camel case, and the value is converted to a string.

1const calendarString = `...
2  X-IS-CUSTOMER:yeah
3  ...`;
4
5const calendar = convertIcsCalendar(undefined, calendarString, {
6  nonStandard: {
7    isCustomer: {
8      name: "X-IS-CUSTOMER",
9      convert: (line) => line.value,
10      schema: z.string(), // optionally provide any validator
11    },
12  },
13});

utils

extendByRecurrenceRule

1import { extendByRecurrenceRule } from "ts-ics";
2
3const start = new Date(Date.UTC(2023, 9, 5));
4const ruleString = "FREQ=DAILY;BYMINUTE=15,16,17,18,19;BYSECOND=0,20,40";
5
6const rule = parseIcsRecurrenceRule(ruleString);
7
8const dates = extendByRecurrenceRule(rule, {
9  start,
10  end: addDays(start, 1),
11});

License

MIT - License

Thanks

Thanks to iCalendar.org for the ics documentation and the many examples which are used for testing purposes.