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.