Immutable-ics NPM

immutable-ics

Immutable iCalendar document creation using typed-immutable and Immutable.js.

Status

Installation

npm install --save immutable-ics

Quick Guide

Import

Import the modules:

import { Component, Property } from 'immutable-ics'

The following modules are available:

Component: Typed Immutable Record to build an iCalendar Component
Property: Typed Immutable Record to build an iCalendar Property

Create a component

Create a new component and add properties:

let calendar
let event

const versionProperty = new Property({ name: 'VERSION', value: 2 })

const dtstartProperty = new Property({
  name: 'DTSTART',
  parameters: { VALUE: 'DATE' },
  value: new Date('1991-07-11 7:00:00')
})

calendar = new Component({ name: 'VCALENDAR' })
calendar = calendar.pushProperty(versionProperty)

event = new Component({ name: 'VEVENT' })
event = event.pushProperty(dtstartProperty)

calendar = calendar.pushComponent(event)

Or instantiate everything at once:

const calendar = new Component({
  name: 'VCALENDAR',
  properties: [
    new Property({ name: 'VERSION', value: 2 })
  ],
  components: [
    new Component({
      name: 'VEVENT',
      properties: [
        new Property({
          name: 'DTSTART',
          parameters: { VALUE: 'DATE' },
          value: new Date('1991-07-11 7:00:00')
        })
      ]
    })
  ]
})

Generate iCalendar data

Call #toString on the Component or Property to get a string representation of the component according to the iCalendar specifications.

calendar.toString()

Generated data:

BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VEVENT
DTSTART;VALUE=DATE:19910711
END:VEVENT
END:VCALENDAR

This string can then be saved to a file, sent to the user, etc.

API

`Component`

An Immutable Record with the following properties:

name: String: Name of the component (e.g. "VCALENDAR", "VEVENT")
components: List<Component>: List of Component instances
properties: List<Property>: List of Property instances

All methods return a new instance of the component due to its backing on Immutable's Record.

Extended Methods

Component.constructor({ name: String, components: (List<Component> | Array<Component>), properties: (List<Property> | Array<Property>) }): Component
Instantiate a new Component with initial values. components and properties will be coerced to a List.
Component.prototype.pushComponent(component: Component): Component
Push a Component to the list of components.
Component.prototype.pushProperty(property: Property): Component
Push a Property to the list of properties.
Component.prototype.clear(): Component
Clear all components and properties from the component.
Component.prototype.clearComponents(): Component
Clear all components from the component.
Component.prototype.clearProperties(): Component
Clear all properties from the component.
Component.prototype.toString(): String
Get a string representation of the component according to the iCalendar specifications.

`Property`

An Immutable Record with the following properties:

name: String: Name of the property (e.g. "DTSTART", "SUMMARY")
parameters: Map<String, Any>: Property parameters (e.g. "VALUE")
transform: Boolean = true: Explicit determiner if the value is transformed
value: Any: Value of the property

All methods return a new instance of the property due to its backing on Immutable's Record.

Extended Methods

Property.constructor({ name: String, parameters: (Object | Map<String, Any>), transform: Boolean = true, value: Any }): Property
Instantiate a new Property with initial values. parameters will be coerced into a Map.
Property.prototype.getTransformedValue(): String
Get the transformed value of the property's value. Transformations are conveniences to generate valid iCalendar data from JavaScript objects.
For example, providing a Date object to a DTSTAMP property value will transform as such:
```
const dtstampProperty = new Property({
  name: 'DTSTAMP'
  parameters: { VALUE: 'DATE' },
  value: new Date('1991-07-11 7:00:00')
})

dtstampProperty.toString() // => DTSTAMP;VALUE=DATE:19910711
```
Property.prototype.toString(): String
Get a string representation of the property according to the iCalendar specifications.