Skip to main content

Calculation Methods

valueOf()​

Signature​

valueOf(): number

Return Type​

number - Returns the timestamp (milliseconds since Unix epoch) of the Chronos instance

Behavior & Notes​

  • Enables arithmetic and comparison operations when used with primitive conversion
  • Automatically called when Chronos instance is used in numeric context
  • Equivalent to getTimeStamp() method
  • Returns same value as JavaScript Date's valueOf()

Examples​

// Numeric comparison
const date1 = new Chronos('2025-01-01');
const date2 = new Chronos('2025-01-02');
date2 > date1; // true (automatically calls valueOf())

// Arithmetic operations
const diff = +new Chronos('2025-01-02') - +new Chronos('2025-01-01');
// diff = 86400000 (1 day in milliseconds)

// Explicit conversion
const timestamp = new Chronos().valueOf();
// timestamp = current time in milliseconds

Use Cases​

  • Sorting arrays of Chronos instances
  • Calculating time differences
  • Interoperability with libraries expecting numeric timestamps

add()​

Signature​

add(amount: number, unit: TimeUnit): Chronos

Parameters​

  • amount: Number of units to add
  • unit: Time unit to add ('year', 'month', 'day', etc.)

Return Type​

Chronos - New instance with added time

Notes​

  • Returns new immutable instance
  • Handles month/year overflow automatically

Example​

new Chronos('2025-01-31').add(1, 'month'); // 2025-02-28

Alternatives​

  • You can also use one/all of these methods as per your need, they're self-explanatory:
    • addDays()
    • addHours()
    • addMinutes()
    • addMonths()
    • addSeconds()
    • addWeeks()
    • addYears()

subtract()​

Signature​

subtract(amount: number, unit: TimeUnit): Chronos

Parameters​

  • amount: Number of units to subtract
  • unit: Time unit to subtract

Return Type​

Chronos - New instance with subtracted time

Example​

new Chronos('2025-03-31').subtract(1, 'month'); // 2025-02-28

diff()​

Signature​

diff(other: ChronosInput, unit: TimeUnit): number

Parameters​

  • other: Date to compare with
  • unit: Unit for difference

Return Type​

number - Difference in specified units

Notes​

  • Returns signed difference (negative if other is after this date)

Example​

const date1 = new Chronos('2025-01-01');
const date2 = new Chronos('2025-01-15');
date2.diff(date1, 'days'); // 14

round()​

Note

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

Signature​

round(unit: TimeUnit, nearest?: number): Chronos

Parameters​

  • unit: The time unit to round to. Valid units: 'year', 'month', 'week', 'day', 'hour', 'minute', 'second', 'millisecond'
  • nearest: (optional): The nearest multiple to round to. Defaults to 1.

Return Type​

Chronos - Returns a new Chronos instance rounded to the nearest point based on the specified unit and granularity. If an invalid unit is passed, the original instance is returned unchanged.

Behavior & Notes​

  • Rounding is based on the proximity to the start or end of the specified time unit
  • Rounding uses sub-unit fractions (e.g., seconds within minutes, minutes within hours) to determine proximity precisely.
  • nearest defines the multiple to round to (e.g., 15-minute intervals), internally uses roundToNearest.
  • Rounding applies fractional logic based on how far into the unit the date is.
  • If an invalid unit is passed, returns the original instance unchanged.
  • Returns a new immutable Chronos instance (does not modify the original).

Unit-specific Behavior​

  • Milliseconds/Seconds/Minutes/Hours:

    • Rounds based on fractional components
    • Example: 14:35:30 rounded to nearest 15 minutes becomes 14:30:00

  • Days:

    • Rounds to nearest day based on time of day
    • Example: 2025-05-23T18:00:00 rounds to 2025-05-24T00:00:00

  • Weeks:

    • Uses ISO 8601 convention: weeks start on Monday.
    • Rounds to nearest Monday based on proximity
    • Rounding is determined by comparing the current date to:
      • The start of the current week (Monday at 00:00),
      • The start of the next week (the following Monday at 00:00).
    • If the current date is closer to the next Monday, it rounds forward. Otherwise, it rounds back to the previous (or same) Monday.
    • Rounded weeks are treated as 0-indexed relative to the year.
    • Example: Once the current date passes midweek (e.g., late Wednesday or beyond), it becomes closer to the next Monday, so rounding moves forward to that Monday’s start.

  • Months:

    • Rounds based on progress through the month (midpoint is day 15)
    • Example: 2025-01-20 rounds to 2025-02-01

  • Years:

    • Considers day-of-year progress relative to leap years
    • Example: 2025-07-01 (midyear) rounds to 2026-01-01

Examples​

import { roundPlugin } from 'nhb-toolbox/plugins/roundPlugin';

Chronos.use(roundPlugin);

// Round to nearest hour
new Chronos('2025-01-15T14:35:30').round('hour'); 
// Returns: 2025-01-15T15:00:00

// Round to nearest 15 minutes
new Chronos('2025-01-15T14:35:30').round('minute', 15);  
// Returns: 2025-01-15T14:30:00

// Round to nearest month (past midpoint)
new Chronos('2025-01-20').round('month');
// Returns: 2025-02-01T00:00:00

// Round to nearest week (closer to next Monday)
new Chronos('2025-01-16T18:00:00').round('week');
// Returns: 2025-01-20T00:00:00 (next Monday)

duration()​

Signature​

duration(toTime?: ChronosInput, absolute?: boolean): TimeDuration

Parameters​

  • toTime: End date (default: now)
  • absolute: Return absolute value, always positive if true (default: true)

Return Type​

TimeDuration - Object with breakdown

interface TimeDuration {
 /** Total number of years. */
 years: number;
 /** Number of months remaining after full years are counted. */
 months: number;
 /** Number of days remaining after full months are counted. */
 days: number;
 /** Number of hours remaining after full days are counted. */
 hours: number;
 /** Number of minutes remaining after full hours are counted. */
 minutes: number;
 /** Number of seconds remaining after full minutes are counted. */
 seconds: number;
 /** Number of milliseconds remaining after full seconds are counted. */
 milliseconds: number;
}

Example​

new Chronos('2020-01-01').duration('2025-01-01');
// {years: 3, months: 0, days: 0, ...}

See Also​

durationString()​

Signature​

durationString(options?: DurationOptions): string

Parameters​

DurationOptions configuration object:

ParameterTypeDefaultDescription
toTimeChronosInputnowThe end time to calculate duration against
absolutebooleantrueReturn absolute value, always positive if true
maxUnitsNumberRange<1, 7>7Maximum number of time units to display
separatorstring", "Separator between units in the output string
style"full" | "short""full"Display format: "full" for full words, "short" for abbreviations
showZerobooleanfalseWhether to include units with zero values

Return Type​

string - Human-readable formatted duration string

Description​

Returns a human-readable string representation of the duration between the current Chronos instance (start time) and another specified time. The method provides flexible formatting options to control the output format, including the number of units displayed, formatting style, and zero-value handling.

Examples​

// Basic usage - with default options
new Chronos('2020-01-01').durationString({ toTime: '2025-01-01' });
// "5 years"

// Short style with default options
new Chronos('2020-01-01').durationString({ 
  toTime: '2025-01-01',
  style: 'short',
});
// "5y"

// Custom separator and showing only non-zero values
new Chronos('2023-01-01 10:30:00').durationString({
  toTime: '2023-01-01 12:45:30',
  separator: ' · ',
  maxUnits: 3
});
// "2 hours · 15 minutes · 30 seconds"

// Short format for compact display
new Chronos('2023-01-01 10:30:00').durationString({
  toTime: '2023-01-01 12:45:30',
  style: 'short',
  separator: ' ',
  maxUnits: 2
});
// "2h 15m"

// Including zero values
new Chronos('2023-01-01').durationString({
  toTime: '2023-01-01',
  showZero: true,
  maxUnits: 3
});
// "0 years, 0 months, 0 days"

// Empty duration fallback
new Chronos('2023-01-01').durationString({
  toTime: '2023-01-01',
  showZero: false
});
// "0 seconds"

Notes​

  • When showZero is false (default), only units with non-zero values are included in the output.
  • The maxUnits parameter limits the number of time units displayed, starting from the largest unit (years). It respects showZero option.
  • The method automatically handles pluralization in "full" style (e.g., "1 second" vs "2 seconds").
  • If all filtered values are zero and showZero is false, returns "0 seconds" or "0s" depending on style.
  • Short style abbreviations: years (y), months (mo), days (d), hours (h), minutes (m), seconds (s), milliseconds (ms).

See Also​

  • To implement custom formatting or logic, use the duration method. It provides a full duration object that offers greater control and flexibility for advanced scenarios.

getDatesInRange()​

Generate an array of ISO date strings within a specified date range.

Signatures​

getDatesInRange(options?: RangeWithDates): string[]

Overview​

Generates dates between two points in time with:

  • Fixed date ranges (from/to) or relative ranges (span/unit)
  • Weekday filtering (skipDays/onlyDays)
  • Format control (local/utc)
  • Date boundary rounding

Parameters​

options (Optional)​

Configuration object accepting either fixed or relative range parameters:

ParameterTypeRequiredDefaultDescription
fromChronosInput❌Current dateStart date (inclusive)
toChronosInput❌4 weeks from nowEnd date (inclusive)
spannumber❌4Number of time units
unit'year'|'month'|'week'|'day'❌'week'Unit of time for relative ranges
format'local'|'utc'❌'local'Output format for ISO strings
skipDaysWeekDay[] | Enumerate<7>[]❌[]Weekdays to exclude (e.g. ['Sunday', 'Saturday'] or [0, 6])
onlyDaysWeekDay[] | Enumerate<7>[]❌[]Only include these weekdays (e.g. ['Monday'] or [1], overrides skipDays)
roundDateboolean❌falseRound dates to start of day
interface RangeWithDates {
  /** Start date (inclusive). Default: current date */
  from?: ChronosInput;
  /** End date (inclusive). Default: 4 weeks from now */
  to?: ChronosInput;
  /** Output format. Default: 'local' */
  format?: 'local' | 'utc';
 /**
  * An array of weekdays to exclude from the date range.
  * - Accepts either weekday names (e.g., `'Saturday'`, `'Sunday'`) or numeric indices (0 for Sunday to 6 for Saturday).
  * - Ignored if `onlyDays` is provided.
  */
 skipDays?: Array<WeekDay> | Array<Enumerate<7>>;
 /**
  * An array of weekdays to explicitly include in the date range.
  * - Accepts either weekday names (e.g., `'Monday'`, `'Wednesday'`) or numeric indices (0 for Sunday to 6 for Saturday).
  * - When provided, this overrides `skipDays` and includes only the specified days.
  */
 onlyDays?: Array<WeekDay> | Array<Enumerate<7>>;
  /** Round dates to start of day. Default: false */
  roundDate?: boolean;
}

Return Value​

string[] - Array of ISO date strings

Behavior​

  • Fixed ranges: Includes all dates between from and to (inclusive)
  • Relative ranges: Generates dates forward from current date
  • onlyDays takes precedence over skipDays when both are provided
  • Defaults to 4-week range when no options provided

Examples​

// Get all dates in January 2025
new Chronos().getDatesInRange({
  from: '2025-01-01',
  to: '2025-01-31',
  skipDays: ['Saturday', 'Sunday'] // or [6, 0]
});

// Include only Fridays in a full month range
const now = new Chronos();
now.getDatesInRange({
  from: now.startOf('month'),
  to: now.endOf('month'),
  onlyDays: ['Friday'],
  roundDate: true
});

// Include only Mondays and Wednesdays in the range
new Chronos().getDatesInRange({
  from: '2025-07-01',
  to: '2025-07-15',
  onlyDays: ['Monday', 'Wednesday']
});

Notes​

Important
  • Weekday names must exactly match: 'Monday', 'Tuesday', etc. (case-sensitive)
  • When using onlyDays, all other days are excluded regardless of skipDays
Similar Static Method