Relative Time Plugin

Relative Time Plugin — Chronos Plugin Documentation.

About Relative Time Plugin

Relative time plugin is a plugin that adds relative time manipulation and calculation methods to Chronos.

Import & Usage

Import

To use the Relative Time Plugin, import it first:

import { Chronos, chronos } from "chronos-date";
import { relativeTimePlugin } from 'chronos-date/plugins/relativeTimePlugin';

Register

Now you can use the plugin's methods:

// Register the plugin globally
Chronos.use(relativeTimePlugin);
// or
chronos.use(relativeTimePlugin);
// or
Chronos.register(relativeTimePlugin);
// or
chronos.register(relativeTimePlugin);

Usage

Example usage of the relativeTimePlugin:

const c = new Chronos();

console.log({ 
    isToday: c.isToday(),
    isYesterday: c.isYesterday(),
    isTomorrow: c.isTomorrow(),
    compare: c.add(3, 'day').compare('day')
});

Example Usage

playground.ts

Overview

The relativeTimePlugin adds comprehensive relative time functionalities to Chronos, enabling:

Time differences calculation
Is today, yesterday, tomorrow checks

Methods Added by the Plugin

Note

All these methods are provided by relativeTimePlugin. You must register it using Chronos.use(relativeTimePlugin) before calling them. Once registered, all Chronos instances will have access to these methods.

Method	Description	Returns
`compare`	Returns the difference between two dates in the specified units.	`number`
`getRelativeYear`	Returns the difference between two dates in years.	`number`
`getRelativeMonth`	Returns the difference between two dates in months.	`number`
`getRelativeWeek`	Returns the difference between two dates in weeks.	`number`
`getRelativeDay`	Returns the difference between two dates in days.	`number`
`getRelativeHour`	Returns the difference between two dates in hours.	`number`
`getRelativeMinute`	Returns the difference between two dates in minutes.	`number`
`getRelativeSecond`	Returns the difference between two dates in seconds.	`number`
`getRelativeMillisecond`	Returns the difference between two dates in milliseconds.	`number`
`isToday`	Checks if the current date is today.	`boolean`
`isYesterday`	Checks if the current date is yesterday.	`boolean`
`isTomorrow`	Checks if the current date is tomorrow.	`boolean`

API Reference

compare()

Signature

compare(unit: TimeUnit = 'minute', time?: ChronosInput): number

Parameters

unit: Time unit for comparison (default: 'minute')
time: Optional comparison time (default: now)

Return Type

number - Difference in specified units

Notes

Negative value indicates past time relative to comparison time
Positive value indicates future time
Wrapper around the various getRelativeUnit methods

Note

To calculate accurate difference use diff() method.

Example

import { Chronos } from 'chronos-date';
import { relativeTimePlugin } from 'chronos-date/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

const pastDate = new Chronos().subtract(2, 'days');
pastDate.compare('day'); // -2

const futureDate = new Chronos().add(3, 'hours'); 
futureDate.compare('hour'); // 3

getRelativeYear()

Signature

getRelativeYear(time?: ChronosInput): number

Parameters

time: Optional comparison time (default: now)

Return Type

number - Full year difference

Notes

Counts complete years between dates
Accounts for month/day position

Example

import { Chronos } from 'chronos-date';
import { relativeTimePlugin } from 'chronos-date/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

const date = new Chronos('2020-06-15');
date.getRelativeYear('2023-05-01'); // -2 (not quite 3 years)
date.getRelativeYear('2023-07-01'); // -3

getRelativeMonth()

Signature

getRelativeMonth(time?: ChronosInput): number

Parameters

time: Optional comparison time (default: now)

Return Type

number - Full month difference

Notes

Counts complete months between dates
Accounts for day position

Example

import { Chronos } from 'chronos-date';
import { relativeTimePlugin } from 'chronos-date/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

const date = new Chronos('2023-01-15');
date.getRelativeMonth('2023-03-10'); // -1 (not quite 2 months)
date.getRelativeMonth('2023-03-20'); // -2

getRelativeWeek()

Signature

getRelativeWeek(time?: ChronosInput): number

Parameters

time: Optional comparison time (default: now)

Return Type

number - Week difference

Notes

Based on 7-day periods
Uses same calculation as getRelativeDay() divided by 7

Example

import { Chronos } from 'chronos-date';
import { relativeTimePlugin } from 'chronos-date/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

new Chronos().getRelativeWeek('2023-01-01'); // Weeks between dates

getRelativeDay()

Signature

getRelativeDay(time?: ChronosInput): number

Parameters

time: Optional comparison time (default: now)

Return Type

number - Day difference

Special Values

-1: Yesterday
0: Today
1: Tomorrow

Example

import { Chronos } from 'chronos-date';
import { relativeTimePlugin } from 'chronos-date/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

const today = new Chronos();
today.getRelativeDay(); // 0

const yesterday = new Chronos().subtract(1, 'day');
yesterday.getRelativeDay(); // -1

const tomorrow = new Chronos().add(1, 'day');
tomorrow.getRelativeDay(); // 1

getRelativeHour()

Signature

getRelativeHour(time?: ChronosInput): number

Parameters

time: Optional comparison time (default: now)

Return Type

number - Hour difference

Example

import { Chronos } from 'chronos-date';
import { relativeTimePlugin } from 'chronos-date/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

const date = new Chronos().add(90, 'minutes');
date.getRelativeHour(); // 1 (full hours)

getRelativeMinute()

Signature

getRelativeMinute(time?: ChronosInput): number

Parameters

time: Optional comparison time (default: now)

Return Type

number - Minute difference

Example

import { Chronos } from 'chronos-date';
import { relativeTimePlugin } from 'chronos-date/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

const date = new Chronos().add(150, 'seconds');
date.getRelativeMinute(); // 2 (full minutes)

getRelativeSecond()

Signature

getRelativeSecond(time?: ChronosInput): number

Parameters

time: Optional comparison time (default: now)

Return Type

number - Second difference

Example

import { Chronos } from 'chronos-date';
import { relativeTimePlugin } from 'chronos-date/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

const date = new Chronos().add(1500, 'milliseconds');
date.getRelativeSecond(); // 1 (full seconds)

getRelativeMilliSecond()

Signature

getRelativeMilliSecond(time?: ChronosInput): number

Parameters

time: Optional comparison time (default: now)

Return Type

number - Millisecond difference

Notes

Most precise relative comparison
Returns raw millisecond delta

Example

import { Chronos } from 'chronos-date';
import { relativeTimePlugin } from 'chronos-date/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

const date = new Chronos().add(500, 'milliseconds');
date.getRelativeMilliSecond(); // 500

These relative comparison methods provide:

Multiple granularities (years to milliseconds)
Signed values indicating past/future
Flexible comparison points
Consistent immutable return types

The relative methods are particularly useful for:

Age calculations
Countdowns/timers
Expiration checks
Time-sensitive conditional logic

isToday()

Signature

isToday(): boolean

Return Type

boolean - Whether date is today

Example

import { Chronos } from 'chronos-date';
import { relativeTimePlugin } from 'chronos-date/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

new Chronos().isToday(); // true

isTomorrow()

Signature

isTomorrow(): boolean

Return Type

boolean - Whether date is tomorrow

Example

import { Chronos } from 'chronos-date';
import { relativeTimePlugin } from 'chronos-date/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

new Chronos().add(1, 'day').isTomorrow(); // true

isYesterday()

Signature

isYesterday(): boolean

Return Type

boolean - Whether date is yesterday

Example

import { Chronos } from 'chronos-date';
import { relativeTimePlugin } from 'chronos-date/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

new Chronos().subtract(1, 'day').isYesterday(); // true

Last updated: Wed, Jun 24, 2026 09:04:13AM (UTC)

Business Plugin

Business Plugin — Chronos Plugin Documentation.

Date Range Plugin

Date Range Plugin — Chronos Plugin Documentation.