Newly Paranoid Maintainers

    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

    2,303

    Version

    0.4.0

    License

    ISC

    Last publish

    Collaborators

    • angeloashmore