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.