Introduction

VTODOGenerator is a library to generate VTODO compatible with RFC5545.

Installation

Install via npm:

npm i vtodogenerator --save

Requirements

VTODOGenerator requires moment-timezone .

You can install it via:

npm i

Usage

Import the library.

import VTodoGenerator from "vtodogenerator";

Define task object.

var todoData = { 
    due: moment("22/04/2022 23:00", 'D/M/YYYY H:mm').toISOString(), 
    summary: "Sample Task", 
    categories: ["InProgress"],  
}

Initialise class instance, and generate todo.

var todo = new VTodoGenerator(todoData, {strict: true})
console.log(todo.generate())

//Sample Output

BEGIN:VCALENDAR
BEGIN:VTODO
UID:46asdjkasdbasdbasda4sd56asdasdn26321132
DTSTAMP:2023-04-20T22:00
SUMMARY:Sample Task
CATEGORIES:InProgress
DUE:2023-04-22T000000Z
END:VTODO
END:VCALENDAR

Guide

Supported Fields

As of now, VTODOGenerator supports the following fields:

| Name| Type| Description | RFC5545 Field Equivalent | |---|---|---|---| | dtstamp | string|Time stamp for creation of the TODO. If not supplied, current time will be used. | DTSTAMP| | summary | string|Summary of the task. Required | SUMMARY| | uid| string|UID for the task. If none is provided, a random id is autogenerated.| UID| | due | string|Due date and time of the task. | DUE| | completed| string|Date and time of completion of task | COMPLETED| | completion| string|How much the task has progressed in percentage.| PERCENT-COMPLETE| | status| string|Current status of the task. Only allowed values are: "NEEDS-ACTION", "COMPLETED", "IN-PROCESS", and "CANCELLED".| STATUS| | categories| Array of strings|Category/Labels of tasks. Can be an array of multiple value.| CATEGORIES| | relatedto| Array of Objects/string. See relevant section for more details. |Defines the relation of this task with others in the CalDAV account. | RELATED-TO| | priority| string/integer |Priority of the task, usually denoted by a number (with 1 being highest, and 9 being the lowest)| PRIORITY| | description| string |Description of the task.| DESCRIPTION| | start| string |Start date and time of the task| DTSTART| | class| string |Classification of the task, eg. PUBLIC/PRIVATE.| CLASS| | geo| string |Geographical information related to task, in the format of LATITUDE;LONGITUDE| GEO| | location| string |Location of the task.| LOCATION| | organizer| string |Organiser of the calendar event.| ORGANIZER| | sequence| string |Revision sequence number of the task. Must be a number.| SEQUENCE| | resources| Array of string |Resources/equipment required for the task.| RESOURCES| | rrule| Object. See relevant section for more details. |Recurrence rule for the task.| RRULE| | url| string |Any URL associated with the task.| URL| | tz| string |Timezone.| TZID| | recurrences| Array of Object|An array of series of task objects, in case of recurring tasks. See relevant section.| | | recurrenceid| string |Recurrence ID of the task. This is used to identify tasks in a recurrence set. See relevant section.|RECURRENCE-ID |

Fields

relatedto

relatedto defines the relation of tasks with other tasks in the CalDAV account.

This field can be either string:

relatedto: "uid-of-another-task-in-caldav-account"

or it must be an array of object of the following syntax:

{
    params:
    {
            RELTYPE: "CHILD",
    },
    val: "uid-of-another-task-1"
}

RELTYPE defines the type of relationship with other task. Value could be either CHILD, PARENT, or SIBLING.

val must contain the UID of related task.

So for this example, our new task will be have a CHILD task with UID uid-of-another-task-1.

A task can have multiple relationships. In the following example, our new task will have a child uid-of-another-task-1 and will have a parent with a UID uid-of-another-task-2:

related to:[
    {
        params:{
            RELTYPE: "CHILD",
        },
        val: "uid-of-another-task-1"
    },
    {
        params:{
            RELTYPE: "PARENT",
        },
        val: "uid-of-another-task-2"
    }
]

rrule

rrule defines the recurrence of the task, and it is valuable for generating repeating tasks.

If you specifiy rrule, start must also be specified in the task object.

rrule must be an object of the format:

rrule: {
    FREQ: string , //eg. DAILY/WEEKLY/MONTHLY
    INTERVAL: string/number,
    UNTIL: date of format recognised by moment.
}

FREQ defines the frequency of recurrence. Possible values are: "SECONDLY" / "MINUTELY" / "HOURLY" / "DAILY"/ "WEEKLY" / "MONTHLY" / "YEARLY"

INTERVAL defines the interval of the recurrence.

UNTIL defines the date and time till which the recurrence rule must be followed.

Examples

// The following will create a task that is repeated daily, starting from April 03, 2023 until Jan 03, 2024.

...
start: 03/04/2023,
rrule: {
    FREQ: DAILY
    INTERVAL: 1,
    UNTIL: 03/01/2024
}
...

// The following will create a task that is repeated weekly, starting from June 01, 2021 until forever.

...
start: 01/06/2021,
rrule: {
    FREQ: WEEKLY
    INTERVAL: 1,
}
...

Recurrences

Recurrences holds other tasks in a recurring series.

Take an example of a task that you define as:

var todoData = { 
    uid: "primary-task-uid" 
    summary: "Sample Task", 
    categories: "InProgress",  
    start: 2023-04-03,
    rrule: {
    FREQ: DAILY
    INTERVAL: 1,
    UNTIL: 2024-01-03
    }

}

This task will be repeated daily, until Jan 03, 2024, starting from April 03, 2023.

Let's say you want to edit an instance of this series (eg. the task that will occur on Dec 31, 2023), you will need to define this task as:

var todoData = { 
    uid: "primary-task-uid" 
    summary: "Sample Task", 
    categories: "InProgress",  
    start: 2023-04-03,
    rrule: {
    FREQ: DAILY
    INTERVAL: 1,
    UNTIL: 2024-01-03,
    },
    recurrences:{
         "2023-12-31": {
            description: "Don't drink too much",
            recurrenceid: "20231231T000000"
        }
    }
    }

}

On Dec 31, 2023, the task instance will show up with the description "Don't drink too much" (on most clients).

Functions

constructor(todoObject, options)

Initializes the object. Additional options can be specified using the options variable.

Parameters

| name| Type | Required| Description| |---|---|---|---| |todoObject| object| Yes | Data to generate the VTODO. Refer to guide section for all supported fields.|
|options| object| No |

Options

strict

Specifies whether the inputs must be checked strictly.

Example usage:

var todo = new VTodoGenerator(todoData, {strict: false}) 

generate(skipVCALENDAR)

Generates the VTODO.

Parameters

| name| Type | Required| Description| |---|---|---|---| |skipVCALENDAR| boolean| No | Skip the "BEGIN:VCALENDAR" part in the generated todo.|