Create and parse ICS format for TypeScript
npm install 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.
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.
npm i ts-ics
``ts
import { generateIcsCalendar, type IcsCalendar } from "ts-ics";
const calendar: IcsCalendar = {...}
const icsCalendarString = generateIcsCalendar(calendar);
`
`ts
import { generateIcsEvent, type IcsEvent } from "ts-ics";
const event: IcsEvent = {...}
const icsEventString = generateIcsEvent(event);
`
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.
`ts
type NonStandard = { isCustomer: string }
const calendar: IcsCalendar
nonStandard: { isCustomer: "yeah" },
...
};
const calendarString = generateIcsCalendar
nonStandard: {
isCustomer: { name: "X-IS-CUSTOMER", generate: (v) => ({ value: v }) },
},
});
`
#### without parsing
`ts
import { convertIcsCalendar, type IcsCalendar } from "ts-ics";
const calendar: IcsCalendar = convertIcsCalendar(undefined, icsCalendarString);
`
#### parse with zod
`ts
import { type IcsCalendar } from "ts-ics";
import { parseIcsCalendar } from "@ts-ics/schema-zod";
const 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.
`ts
import { convertIcsCalendar, type IcsCalendar } from "ts-ics";
import { zIcsCalendar } from "@ts-ics/schema-zod";
const calendar: IcsCalendar = convertIcsCalendar(
zIcsCalendar,
icsCalendarString
);
`
#### without parsing
`ts
import { convertIcsEvent, type IcsEvent } from "ts-ics";
const event: IcsEvent = convertIcsEvent(undefined, icsEventString);
`
#### parse with zod
`ts
import { type IcsEvent } from "ts-ics";
import { parseIcsEvent } from "@ts-ics/schema-zod";
const 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.
`ts
import { convertIcsEvent, type IcsEvent } from "ts-ics";
import { zIcsEvent } from "@ts-ics/schema-zod";
const calendar: IcsEvent = convertIcsEvent(zIcsEvent, icsEventString);
`
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.
`ts...
const calendarString =
X-IS-CUSTOMER:yeah
...;
const calendar = convertIcsCalendar(undefined, calendarString, {
nonStandard: {
isCustomer: {
name: "X-IS-CUSTOMER",
convert: (line) => line.value,
schema: z.string(), // optionally provide any validator
},
},
});
`
`ts
import { extendByRecurrenceRule } from "ts-ics";
const start = new Date(Date.UTC(2023, 9, 5));
const ruleString = "FREQ=DAILY;BYMINUTE=15,16,17,18,19;BYSECOND=0,20,40";
const rule = parseIcsRecurrenceRule(ruleString);
const dates = extendByRecurrenceRule(rule, {
start,
end: addDays(start, 1),
});
``
MIT - License
Thanks to iCalendar.org for the ics documentation and the many examples which are used for testing purposes.