@ymchun/ics

UNDER ACTIVE DEVELOPMENT, MAY HAVE BREAKING CHANGES

Install

$ npm i @ymchun/ics

Basic Usage

import { Parser, ParserOptions } from '@ymchun/ics';

const icsStr = '......'; // your ics file content
const opts: ParserOptions = {
	// whether the parser should emit warning message
	quiet: true,
};

// 'calendars' is array of v-calendar components
const calendars = new Parser(opts).parse(icsStr);
// convert Vcalendar back to ics file
const ics = convertToIcs(calendar[0].getICSTokens());

Extending components and properties

More components and properties can be supported by extending Component and Property classes.

Also, your custom components and properties should implements ComponentImpl and PropertyImpl<T>.

For PropertyImpl<T>, the generic type refer to the type of your property value.

Define your custom property with parameters

class MyCustomPropertyA extends Property implements PropertyImpl<TextValue> {
	// type should match your property key when feeding into the parser options
	public type = 'MyCustomPropertyA'; // <-- property key, mandatory
	public value!: TextValue; // <-- property value, mandatory
	public parameters = {
		// property parameters
		Encoding: null as TextValue | null,
		MyCustomParam: null as MyCustomParam | null,
	};

	// set property value
	public setValue(value: string): this {
		// your property should use the 'token' property from parent class to set the value
		// since properties may have different value type, so this method is where you parse your own value
		// 'token' will become null after this method is called
		this.value = new BinaryValue().setValue(this.token.value);
		return this;
	}

	// set property parameters
	public setParameter(type: string, value: string): this {
		switch (param.name) {
			case PARAMETER.Encoding:
				this.parameters.Encoding = new TextValue().setValue(param.value);
				break;
			case PARAMETER.MyCustomParam:
				this.parameters.MyCustomParam = new MyCustomParam().setValue(param.value);
				break;
		}
		return this;
	}

	// toString convert property into ics string
	public toString(): string {
		const paramStr = propertyParameterToString(this.parameters);
		return foldLine(`${this.type}${paramStr}:${this.value.toString()}`);
	}
}

Define your custom property without parameters

class MyCustomPropertyB extends Property implements PropertyImpl<DateValue> {
	// type should match your property key when feeding into the parser options
	public type = 'MyCustomPropertyB'; // <-- property key, mandatory
	public value!: DateValue; // <-- property value, mandatory

	// this method should be implemented
	public setValue(value: string): this {
		// or if your property value is a Date object
		this.value = new DateValue().setValue(this.token.value);
		return this;
	}

	// toString convert property into ics string
	public toString(): string {
		return foldLine(`${this.type}:${this.value.toString()}`);
	}
}

Define your custom component

class MyCustomComponent extends Component implements ComponentImpl {
	// type should match your component key when feeding into the parser options
	public type = 'MyCustomComponent'; // <-- component key, mandatory

	public myCustomPropertyA: MyCustomPropertyA; // <-- use 'MyCustomPropertyA' here
	public myCustomPropertyB: MyCustomPropertyB; // <-- use 'MyCustomPropertyB' here

	public childComponentTypeA: ComponentTypeA;
	public childComponentTypeB: ComponentTypeB;

	public propertyTypeA: PropertyTypeA;
	public propertyTypeB: PropertyTypeB;
	public propertyTypeC: PropertyTypeC;

	// this method should be implemented when your component contains other components
	public setComponent(component: Component): this {
		switch (component.type) {
			case 'TypeA':
				this.daylight = component as ComponentTypeA;
				break;
			case 'TypeB':
				this.daylight = component as ComponentTypeB;
				break;
		}
		return this;
	}

	// this method should be implemented when your component has properties
	public setProperty(property: Property): this {
		switch (property.type) {
			case 'TypeA':
				this.propertyTypeA = property as PropertyTypeA;
				break;
			case 'TypeB':
				this.propertyTypeB = property as PropertyTypeB;
				break;
			case 'TypeC':
				this.propertyTypeC = property as PropertyTypeC;
				break;
			// property key --v
			case 'MyCustomPropertyA':
				this.myCustomPropertyA = property as MyCustomPropertyA;
				break;
			case 'MyCustomPropertyB':
				this.myCustomPropertyB = property as MyCustomPropertyB;
				break;
		}
		return this;
	}

	// toString convert component into ics string
	public getICSTokens(): ConvertToICS {
		// result
		const payload: ConvertToICS = {
			children: [],
			type: this.type,
		};

		// push properties
		if (this.myCustomPropertyA) {
			payload.children.push(this.myCustomPropertyA.toString());
		}
		if (this.myCustomPropertyB) {
			payload.children.push(this.myCustomPropertyB.toString());
		}
		if (this.propertyTypeA) {
			payload.children.push(this.propertyTypeA.toString());
		}
		if (this.propertyTypeB) {
			payload.children.push(this.propertyTypeB.toString());
		}
		if (this.propertyTypeC) {
			payload.children.push(this.propertyTypeC.toString());
		}

		// push components
		if (this.childComponentTypeA) {
			payload.children.push(this.childComponentTypeA.getICSTokens());
		}
		if (this.childComponentTypeB) {
			payload.children.push(this.childComponentTypeB.getICSTokens());
		}

		return payload;
	}
}

Extending existing component

class MyExtendedVCalendar extends VCalendar implements ComponentImpl {
	public myCustomProperty: MyCustomProperty; // <-- use 'MyCustomProperty' here

	// this method should be implemented when your component has properties
	public setProperty(property: Property): this {
		switch (property.type) {
			case 'MyCustomProperty':
				this.myCustomProperty = property as MyCustomProperty;
				break;
			default:
				// you should call parent class 'setProperty' method to avoid missing parent properties
				super.setProperty(property);
		}
		return this;
	}

	// toString convert component into ics string
	public getICSTokens(): ConvertToICS {
		// you should call the parent get tokens first
		const payload = super.getICSTokens();

		// then append your custom properties
		if (this.myCustomProperty) {
			payload.children.push(this.myCustomProperty.toString());
		}

		return payload;
	}
}

Register your custom components and properties via options

const icsStr = '......'; // your ics file content
const opts: ParserOptions = {
	components: {
		// the key should match the ics 'BEGIN:xxx' and 'END:xxx'
		// i.e. when parser meet 'BEGIN:MyCustomComponent', it will use this component.
		// v-- component key
		MyCustomComponent: MyCustomComponent,
		// overriding the default vCalendar component
		[COMPONENT.Calendar]: MyExtendedVCalendar,
	},
	properties: {
		// the key should match the ics 'MyCustomPropertyA:xxx' component property
		// v-- property key
		MyCustomPropertyA: MyCustomPropertyA,
		MyCustomPropertyB: MyCustomPropertyB,
	},
};

// parse icsStr into VCalendar object
const calendars = new Parser(opts).parse(icsStr);