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
valarms	string	Alarm array for the tasks. See relevant secion.	VALARM

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:

const 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:

const 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).

Valarms

This field holds alarm(s) for the VTODO. It must be an array object, with the following fields:

Name	Type	Required	Description
action	string	Yes	Can be either "display", "email," or "audio."
trigger	string	yes	This field contains the trigger for the alarm. See relevant section for more information.
description	string	Maybe	This field contains desription of the alarm and it is required if the action type is either "diplay" or "email." It is used as the email body in case the action is "email."
attendes	Object Array	Maybe	Required if the action type is "email." See relevant section for more information.
summary	string	Maybe	Required if the action type is "email." It is used as the subject line for the email sent to the attendees.

Attendees

This field if used to include the people that must be notified by email, in case the action "email" is used in the VALARM.

It must be an array of objects with the following fields:

Name	Type	Required	Description
commonName	string	Yes	Name of the attendee.
email	string	Yes	Email of the attendee.

Trigger

Trigger field denotes when the Alarm will be displayed. It can either be a specific date & time, or it can be relative to the task's start/end. The Trigger object must have the following fields:

Name	Type	Required	Description
isRelated	boolean	Yes	Specifies whether you are trying to set the alarm relative to start/end of the task or using a particular date for the alarm. Set to true if you want to have an alarm relative to start or the end of the task.
value	string or number	Yes	In case the alarm is relative (i.e. isrelated is set to true) the value field must contain the exact date and time when the alarm is triggered. In case the alarm is relative to start/end, it must contain the time period (in seconds) relative to the start/end when it must trigger. See the examples for more information.
relatedTo	string	Maybe	If the isRelated flag is set to true, this field must be set. Could be either "start" or "end"

Here are some examples:

You can set the alarm to trigger on 22/04/2025 at 23:00 as follows:

trigger:{
    isRelated: false,
    value:"20250422T230000",
}

The 'value' field is parsed by moment library, so you can set the date and time in any format that is supported by it.

If you want to set the alarm to trigger 30 minutes (1800 seconds) before the start of the task, the trigger must look like:

trigger:{
    isRelated: true,
    value:-1800,
    relatedTo:"start"
}

Here's how you can set the alarm to trigger 5 mins after the end:

trigger:{
    isRelated: true,
    value:300,
    relatedTo:"end"
}

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.