Duration Plugin
Duration Plugin — Chronos Plugin Documentation.
About Duration Plugin
Duration plugin is a plugin that adds duration-related methods to Chronos.
Import & Usage
Import
To use the Duration Plugin, import it first:
import { Chronos, chronos } from "chronos-date";
import { durationPlugin } from 'chronos-date/plugins/durationPlugin';Register
Now you can use the plugin's methods:
// Register the plugin globally
Chronos.use(durationPlugin);
// or
chronos.use(durationPlugin);
// or
Chronos.register(durationPlugin);
// or
chronos.register(durationPlugin);Usage
Example usage of the durationPlugin:
const c = new Chronos();
const duration = c.duration('2018-01-18');
console.log(duration);
const durationString = c.durationString({ toTime: '2018-01-18' });
console.log(durationString);Example Usage
Overview
The durationPlugin adds duration-related functionalities to Chronos, enabling:
- Time duration breakdown between two time points
- Human-readable formatted duration string between two time points
Methods Added by the Plugin
Note
All these methods are provided by durationPlugin. You must register it using Chronos.use(durationPlugin) before calling them. Once registered, all Chronos instances will have access to these methods.
| Method | Description | Returns |
|---|---|---|
duration | Returns the full time duration breakdown between two time points. | TimeDuration |
durationString | Returns a human-readable formatted duration string between two time points. | string |
API Reference
duration()
Returns the full time duration breakdown between current input (start) and another time (to) as TimeDuration object.
Signature
duration(toTime?: ChronosInput, absolute?: boolean): TimeDurationParameters
toTime: End date (default:now)absolute: Return absolute value, always positive iftrue(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
import { durationPlugin } from 'chronos-date/plugins/durationPlugin';
Chronos.use(durationPlugin);
new Chronos('2020-01-01').duration('2025-01-01');
// {years: 3, months: 0, days: 0, ...}See Also
- For string output, please refer to durationString method.
durationString()
Returns a human-readable formatted duration string between the current instance (start) and another time (to).
Signature
durationString(options?: DurationOptions): stringParameters
DurationOptions configuration object:
| Parameter | Type | Default | Description |
|---|---|---|---|
toTime | ChronosInput | now | The end time to calculate duration against |
absolute | boolean | true | Return absolute value, always positive if true |
maxUnits | NumberRange<1, 7> | 7 | Maximum number of time units to display |
separator | string | ", " | Separator between units in the output string |
style | "full" | "short" | "full" | Display format: "full" for full words, "short" for abbreviations |
showZero | boolean | false | Whether 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
import { durationPlugin } from 'chronos-date/plugins/durationPlugin';
Chronos.use(durationPlugin);
// 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
showZeroisfalse(default), only units with non-zero values are included in the output. - The
maxUnitsparameter limits the number of time units displayed, starting from the largest unit (years). It respectsshowZerooption. - The method automatically handles pluralization in
"full"style (e.g.,"1 second"vs"2 seconds"). - If all filtered values are zero and
showZeroisfalse, 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.
Last updated: Wed, Jun 24, 2026 09:04:13AM (UTC)