angeloashmore / ics-js Goto Github PK

View Code? Open in Web Editor NEW

21.0 3.0 10.0 463 KB

Create ICS files in ES6

License: ISC License

JavaScript 100.00%

ics-js's Introduction

ics-js

Create ICS files in ES6. Works in Node.js or in the browser.

NOTE: Please check out immutable-ics for a better JavaScript ICS solution.

Status

Installation

npm install --save ics-js

Documentation

View documentation on ESDoc.

Quick Guide

Import the module:

import * as ICS from 'ics-js';

Or import just what is needed:

import { VCALENDAR, VEVENT } from 'ics-js';

Create a component

const cal = new ICS.VCALENDAR();

The following components are implenented:

VCALENDAR
VEVENT
VALARM
VTODO

Add properties to a component

/**
 * Component#addProp(name, value, props = {}, skipTransformer = false)
 *
 * @param {string} name - Name of the property (e.g. DTSTAMP).
 * @param {*} [value] - Value of the property.
 * @param {Object} [props={}] - Object of properties for the property. Object keys and values are directly injected.
 * @param {boolean} [skipTransformer=false] - Explicitly determine if the property's value is transformed.
 */

cal.addProp('VERSION', 2) // Number(2) is converted to '2.0'
cal.addProp('PRODID', 'XYZ Corp');

Each component contains a list of property validations. Only valid properties can be added according to the RFC 5545 spec.

The following properties are implemented:

Name	Input	Output
`CATEGORIES`	`Array<String>`	Array items separated by `,`
`CREATED`	`Date`	Formatted date to spec
`DTEND`	`Date`	Formatted date to spec
`DTSTAMP`	`Date`	Formatted date to spec
`DTSTART`	`Date`	Formatted date to spec
`DUE`	`Date`	Formatted date to spec
`EXDATE`	`Array<Date>`	Array items separated by `,` formatted to spec
`GEO`	`Array<Float>`	Array items separated by `;` (should be `[x, y]`)
`LAST-MODIFIED`	`Date`	Formatted date to spec
`RDATE`	`Date`	Formatted date to spec
`TRANSP`	`Boolean`	`TRANSPARENT` if true, `OPAQUE` if false
`UID`	`String` or none	If no input is provided, generates a random GUID
`VERSION`	`Number`	Float with 1 decimal to spec

All other properties (e.g. SUMMARY, LOCATION) are stored as-is without transformations.

Nest a component

const event = new ICS.VEVENT();
event.addProp('UID');
event.addProp('DTSTAMP', new Date('2015-07-18 10:00:00'), { VALUE: 'DATE-TIME' });
event.addProp('ATTENDEE', null, {
  CN: 'Sample Company',
  RSVP: 'FALSE:mailto:[email protected]'
})

cal.addComponent(event);

Each component contains a list of valid nested components. Only valid components can be nested according to the RFC 5545 spec.

Generate ICS data

cal.toString(); // Returns a string
cal.toBlob(); // Returns a Blob (or throws IncompatiblePlatform if Blob is undefined)
cal.toBase64(); // Returns a base64 encoded string

ics-js's People

Contributors

Stargazers

Watchers

Forkers

terebentina jkdufair masaha03 baronagroup connieveer clem-esp bryanstedman jitendra1604 timebutt

ics-js's Issues

Long lines of content must be word-wrap-ed

As defined by section 3.1 of the rfc, content lines should not be longer than 75 chars. If they are, they must be split by a CR+LF+SPACE

format-date and format-text going AWOL broke dependencies

Hi - looks like format-date and format-text disappearing from node.io has caused this great package to no longer be installable.

toBlob# and toBase64# fails on node.js

toBlob# calls new Blob# which is unavailable on node.js. This causes these two functions to fail.

text values should be escaped

\n, commas and semicolons must be replaced in text values with 2 characters each: "\n", "," and ";" respectively.
However, this is just for TEXT values, not for comma or semicolon separated lists, like those of, say CATEGORIES or RRULE
(so RRULE:INTERVAL=1;FREQ=MONTHLY;BYDAY=-1SA not RRULE:INTERVAL=1\;FREQ=MONTHLY\;BYDAY=-1SA but SUMMARY:this\;is\, some \ntext)

Add support for time-less dates

DTSTART/DTEND and possibly other date props can have time-less values, like so:

BEGIN:VEVENT
DTSTART;VALUE=DATE:20140209
DTEND;VALUE=DATE:20140210
DTSTAMP:20150722T081210Z
END:VEVENT

How to add seq?

The name of the SEQ property is "SEQ" but its text output is "SEQUENCE" (as defined by the rfc).
How do you suggest to handle this? I cannot do event.addProp('SEQUENCE', 1) as it's not allowed in the list of props. Also, event.addProp('SEQ', 1) would output SEQ: 1 which is not valid.

The easiest way I can think of for your lib is to rename the SEQ prop to SEQUENCE.
Otherwise probably a getPropName() method defined in the Property class which can be overloaded?

Compatebility

I am having some issues with trying to build the script to support IE10.
Could you provide a shim version that has backward compatebility?

Assign valid value types to properties

Assign a list of valid value types to properties, e.g. TEXT, DATE, DATE-TIME. Properties have a list of allowable value types per the RFC.

By limiting the list of value types, we can expect and act upon certain value types. This will help in implementing #12.

the line separatator should be \r\n, not just \n

As per spec, the lines must end with a CRLF (\r\n), not just \n. This should be an easy fix on https://github.com/angeloashmore/ics-js/blob/master/src/Component.js#L10

Usage issue

I was following the usage:
const cal = new ICS.VCALENDAR();
And I was getting this error:

const cal = new ICS.VCALENDAR();
            ^

TypeError: ICS.VCALENDAR is not a function

But when I do
`const cal = new ICS.default.VCALENDAR();' then it seems to work. I'm not sure if that's how you intended for people to use this.

There is no way to specify a Date as UTC according to the RFC

In the RFC (https://tools.ietf.org/html/rfc5545#section-3.3.5), a UTC date can be specified in the following format without a TZID:
19980119T070000Z

However, the formatDate helper does not allow the option of emitting the 'Z' character if the date is UTC.

I propose a parameter be added to the formatDate function that informs whether the Date object should be treated as UTC (and subsequently emit the Z character on the rendered date string)

VALARM

How do I use VALARM? Can you provide me with an example?
I want to add the ACTION DISPLAY with TRIGGER -PT15M.

How I can add ATTENDEE to event?

Spec says it should look like this:

ATTENDEE;CN="Alek Barszczewski (Company)";RSVP=FALSE:mailto:[email protected]
ATTENDEE;CN="Alek Barszczewski2 (Company)";RSVP=FALSE:mailto:[email protected]
...

But when adding ATTEnDEE through addProp:

event.addProp('ATTENDEE',';CN="Alek Barszczewski (Company)";RSVP=FALSE:mailto:[email protected]')

then following entry is generated in event:

...
ATTENDEE:;CN="Alek Barszczewski (Company)";RSVP=FALSE:mailto:alek@exa
 mple.com
...

How to avoid ATTENDEE:; ?
why text row is "broken" to next line at some point?

Solution

Add skipTransformer as an argument to Component#addProp().

// set props to null or {} if not needed
Component#addProp(name, value, props, skipTransformer);

(reported by @terebentina)