Miss any of our Open RFC calls?Watch the recordings here! »

immutable-ics

0.4.0 • Public • Published

immutable-ics

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

Status

npm version Build Status js-standard-style

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.

Install

npm i immutable-ics

DownloadsWeekly Downloads

876

Version

0.4.0

License

ISC

Last publish

Collaborators

  • avatar