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()​

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 (default: 1)

Return Type​

Chronos - Returns a new Chronos instance rounded to the nearest point based on the specified unit and granularity

Behavior & Notes​

  • Rounding is based on the proximity to the start or end of the specified time unit
  • nearest defines the multiple to round to (e.g., 15-minute intervals)
  • If an invalid unit is passed, returns the original instance unchanged
  • Returns a new immutable 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
    • Example: A Wednesday closer to next Monday rounds forward

  • 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​

// 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 values (default: true)

Return Type​

TimeDuration - Object with breakdown

interface TimeDuration {
  years: number;
  months: number;
  days: number;
  hours: number;
  minutes: number;
  seconds: number;
  milliseconds: number;
}

Example​

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

round()​

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.

Example​

new Chronos('2025-01-15T14:35:30').round('hour');        // 2025-01-15T15:00:00
new Chronos('2025-01-15T14:35:30').round('minute', 15);  // 2025-01-15T14:30:00

Behavior & Notes​

  • Rounding is based on the proximity to the start or end of the specified time unit.
  • nearest defines the multiple to round to (e.g., 15-minute intervals).
  • Rounding applies fractional logic based on how far into the unit the date is.

Unit-specific Notes​

  • millisecond / second / minute / hour / day: Uses sub-unit fractions (e.g., seconds from minutes) for precise rounding.
  • month: Rounding is based on how far into the month the date is (e.g., the 15th of May is halfway through). If the date is past the midpoint of the month, it rounds forward; otherwise, it rounds back. Internally, month indices are 0-based, but the resulting date is standard ISO-formatted.
  • year: Considers day-of-year progress relative to leap years.
  • week:
    • Uses ISO 8601 convention: weeks start on Monday.
    • 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.

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