Skip to main content

Comparison Methods

Relative Comparison Methods

compare()​

Note

This method is provided by relativeTimePlugin. You must register it using Chronos.use(relativeTimePlugin) before calling .compare(). Once registered, all Chronos instances will have access to the .compare() method.

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 getRelative* methods

Example​

import { Chronos } from 'nhb-toolbox';
import { relativeTimePlugin } from 'nhb-toolbox/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()​

Note

This method is provided by relativeTimePlugin. You must register it using Chronos.use(relativeTimePlugin) before calling .getRelativeYear(). Once registered, all Chronos instances will have access to the .getRelativeYear() method.

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 'nhb-toolbox';
import { relativeTimePlugin } from 'nhb-toolbox/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()​

Note

This method is provided by relativeTimePlugin. You must register it using Chronos.use(relativeTimePlugin) before calling .getRelativeMonth(). Once registered, all Chronos instances will have access to the .getRelativeMonth() method.

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 'nhb-toolbox';
import { relativeTimePlugin } from 'nhb-toolbox/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()​

Note

This method is provided by relativeTimePlugin. You must register it using Chronos.use(relativeTimePlugin) before calling .getRelativeWeek(). Once registered, all Chronos instances will have access to the .getRelativeWeek() method.

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 'nhb-toolbox';
import { relativeTimePlugin } from 'nhb-toolbox/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

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

getRelativeDay()​

Note

This method is provided by relativeTimePlugin. You must register it using Chronos.use(relativeTimePlugin) before calling .getRelativeDay(). Once registered, all Chronos instances will have access to the .getRelativeDay() method.

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 'nhb-toolbox';
import { relativeTimePlugin } from 'nhb-toolbox/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()​

Note

This method is provided by relativeTimePlugin. You must register it using Chronos.use(relativeTimePlugin) before calling .getRelativeHour(). Once registered, all Chronos instances will have access to the .getRelativeHour() method.

Signature​

getRelativeHour(time?: ChronosInput): number

Parameters​

  • time: Optional comparison time (default: now)

Return Type​

number - Hour difference

Example​

import { Chronos } from 'nhb-toolbox';
import { relativeTimePlugin } from 'nhb-toolbox/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

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

getRelativeMinute()​

Note

This method is provided by relativeTimePlugin. You must register it using Chronos.use(relativeTimePlugin) before calling .getRelativeMinute(). Once registered, all Chronos instances will have access to the .getRelativeMinute() method.

Signature​

getRelativeMinute(time?: ChronosInput): number

Parameters​

  • time: Optional comparison time (default: now)

Return Type​

number - Minute difference

Example​

import { Chronos } from 'nhb-toolbox';
import { relativeTimePlugin } from 'nhb-toolbox/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

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

getRelativeSecond()​

Note

This method is provided by relativeTimePlugin. You must register it using Chronos.use(relativeTimePlugin) before calling .getRelativeSecond(). Once registered, all Chronos instances will have access to the .getRelativeSecond() method.

Signature​

getRelativeSecond(time?: ChronosInput): number

Parameters​

  • time: Optional comparison time (default: now)

Return Type​

number - Second difference

Example​

import { Chronos } from 'nhb-toolbox';
import { relativeTimePlugin } from 'nhb-toolbox/plugins/relativeTimePlugin';

Chronos.use(relativeTimePlugin);

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

getRelativeMilliSecond()​

Note

This method is provided by relativeTimePlugin. You must register it using Chronos.use(relativeTimePlugin) before calling .getRelativeMilliSecond(). Once registered, all Chronos instances will have access to the .getRelativeMilliSecond() method.

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 'nhb-toolbox';
import { relativeTimePlugin } from 'nhb-toolbox/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