relativedelta

relativedelta-npm

relativedelta is an NPM package which brings the functionality of the relativedelta function from the dateutil Python library over to Javascript and Typescript.
Starting from version 1.0.0, all features from Python's relativedelta function are implemented.

The new RelativeDelta function makes calculating time deltas, applying different time units to dates and converting time units into other time units easier and more readable, all while respecting varying month lengths and leap years.

Installation and usage

1. Install the relativedelta package

npm install relativedelta

2. Import the RelativeDelta class into your code

import { RelativeDelta } from 'relativedelta'

// Lets convert 15 days to seconds as an example
const fifteenDaysInSeconds = new RelativeDelta({days: 15}).toSeconds() // Returns 1296000
console.log("Number of seconds in 15 days: ", fifteenDaysInSeconds) // Logs "Number of seconds in 15 days: 1296000"

Similarities and differences with Python's relativedelta

A lot of effort has been put into ensuring that this RelativeDelta function behaves and feels the same as Python's relativedelta function. While most features could be directly implemented, others had to be implemented in a different way to work with Javascript and Typescript (Like using .applyToDate() instead of being able to apply the RelativeDelta object to a Date object directly. For comparison, in Python you can add a datetime object to a relativedelta object using the + operator).

Differences

Adding dates

datetime.now() + relativedelta() -> new RelativeDelta({}).applyToDate(new Date())

Python

datetime.now() + relativedelta(days=1)

Javascript & Typescript

new RelativeDelta({ days: 1 }).applyToDate(new Date())

Converting relative delta to time unit

Not Supported -> new RelativeDelta({}).toMilliseconds(), new RelativeDelta({}).toSeconds(), ... ,new RelativeDelta({}).toYears()

Python

# No direct solution exists, so you would have to do it manually
fifteen_days_to_milliseconds = relativedelta(days=15) * 24 * 60 * 60 * 1000

Javascript & Typescript

new RelativeDelta({ days: 15 }).toMilliseconds()

millisecond and milliseconds parameters

microsecond, microseconds -> millisecond, milliseconds

new Date() only supports milliseconds as its smallest unit. Therefore, there was no reason to implement the logic to handle microseconds and thus this parameter was renamed to handle milliseconds.

date1 and date2 parameters

dt1, dt2 -> date1, date2

Python

relativedelta(dt1=current_date, dt2=previous_date)

Javascript & Typescript

new RelativeDelta({ date1: currentDate, date2: previousDate })

nlyearday parameter

nlyearday -> nonLeapYearDay

Python

relativedelta(nlyearday=150)

Javascript & Typescript

new RelativeDelta({ nonLeapYearDay: 150 })

Writing weekdays as a string

Not supported -> "MO", "TU", "WE", "TH", "FR", "SA", "SU"

In Python, you need to enter the weekday using an integer or an imported function. Using a string is more intuitive in my opinion than using an integer or imported function, so that's why strings are supported as well.

Python

from dateutil.relativedelta import MO, relativedelta
## Monday as an integer
relativedelta(weekday=0)

## Monday as an imported function
relativedelta(weekday=MO())

Javascript & Typescript

import { MO, RelativeDelta } from 'relativedelta'

// Monday as a string
new RelativeDelta({ weekDay: "MO" })

// Monday as an integer
new RelativeDelta({ weekDay: 0 })

// Monday as an imported function
new RelativeDelta({ weekDay: MO() })