Chronos
Chronos - Play with Time and Date, Be a Time Master like Chronos
About Chronos
In ancient Greek mythology, Chronos is the primordial embodiment of time — not merely tracking moments, but defining their very existence. Like its mythological namesake, the Chronos class offers precise, immutable, and expressive control over time within your application.
Designed to go beyond Date, it empowers you to manipulate, format, compare, and traverse time with clarity, reliability, and confidence — all while staying immutable and framework-agnostic.
Whether you're building a calendar, a countdown, or scheduling logic, Chronos gives you the power to shape time as you see fit.
API Reference for Chronos
This documentation provides a detailed guide to the Chronos class, a comprehensive date and time manipulation class. The methods are grouped into logical categories for easier navigation.
For chronos function
For chronos function, a Chronos wrapper, refer to the Wrapper Function
Import
import { Chronos } from 'chronos-date';Plugin System
Chronos supports a modular plugin system that allows you to extend its capabilities without bloating the core. Plugin methods are not available by default, you must explicitly install them using the .use() or .register() static method.
How it works
Info
Each plugin enhances the Chronos prototype and becomes available globally after registration.
Constructor Signatures
constructor();
constructor(value: number);
constructor(value: string);
constructor(value: Date);
constructor(value: Chronos);
constructor(year: number, month?: NumberRange<1, 12>, date?: NumberRange<1, 31>, hours?: Enumerate<24>, minutes?: Enumerate<60>, seconds?: Enumerate<60>, ms?: Milliseconds); //
constructor(year: number, month: number, date?: number, hours?: number, minutes?: number, seconds?: number, ms?: number);
constructor(value?: ChronosInput);ChronosInput
type ChronosInput = number | string | Date | Chronos;Public & Protected Properties
These properties provide non-destructive, read-only (only the core ones) access to the copies of internal states of a Chronos instance for debugging, inspection, or meta-awareness.
Info
However, in JavaScript, these properties can technically be mutated (Compile-time Error occurs in TypScript if these properties are tried to be mutated), but such mutations (changes) do not affect the Chronos instance itself. The class internally manages equivalent strict readonly/private state. These public properties exist purely for developer convenience and sugar.
native
Returns the underlying native JavaScript Date object used internally by the Chronos instance. This is useful for interoperability with APIs or libraries that expect a native Date.
Info
Equivalent to toDate() instance method.
origin
Indicates how the current Chronos instance was created. This can be helpful for debugging flow logic or tracing method chains in complex date-time pipelines.
Possible values:
'root': if the instance was directly constructed- A method name string such as
'addDays','startOf', etc., if the instance was produced as the result of a method call (which can create a new instance ofChronos). If no such method was called it shows the last previous method name asorigin, if there is none, it showsroot.
utcOffset
Returns the current UTC offset in UTC±HH:mm format (e.g., "UTC+06:00", "UTC-05:30").
Info
- Also accessible via
getTimeZoneOffset()instance method withoutUTCprefix (returns in±HH:mmformat). - This value is automatically updated when using timezone or UTC manipulation methods.
Caution
This property is mutable, but modifying it has no effect on the Chronos instance. Any logic that relies on the mutated value may behave incorrectly, as Chronos internally derives its actual state from private fields.
timeZoneName
Represents the current timezone name (e.g., "Bangladesh Standard Time"), or falls back to the corresponding timezone identifier (e.g., "Asia/Dhaka") if no name can be resolved.
Remarks
- Invoking the
timeZone()method sets the timezone name that corresponds to the specified UTC offset, or the UTC offset itself if no name exists. For more details on this behavior, seegetTimeZoneName(). - To retrieve the local system's native timezone name (or its identifier if the name is unavailable), use the
$getNativeTimeZoneName()instance method.
Caution
This property is mutable, but modifying it has no effect on the Chronos instance. Any logic that relies on the mutated value may behave incorrectly, as Chronos internally derives its actual state from private fields.
timeZoneId
Represents the current timezone context, which can be a single identifier, an array of equivalent identifiers, or a UTC offset.
Possible return types:
$TimeZoneIdentifier— e.g.,"Asia/Dhaka". Returned when thetimeZone()method has not been invoked (default behavior).- Array of
$TimeZoneIdentifier— e.g.,['Asia/Kathmandu', 'Asia/Katmandu'], used when multiple timezones share the same UTC offset such as"UTC+05:45". UTCOffset— e.g.,"UTC+06:45"or"UTC+02:15", returned when no named timezone corresponds to a given offset.
Remarks
- By default, when
timeZone()is not applied, a single$TimeZoneIdentifierstring is provided. - When applied, it may instead return a single identifier string, an array of equivalent identifiers, or a UTC offset string.
- To retrieve the local system's native timezone identifier, use the
$getNativeTimeZoneId()instance method.
Caution
This property is mutable, but modifying it has no effect on the Chronos instance. Any logic that relies on the mutated value may behave incorrectly, as Chronos internally derives its actual state from private fields.
$tzTracker
Warning
Protected Internal flag used to track instances created via the timeZone() method. This value participates in the internal resolution of time-zone name, identifier, and offset. Although it is protected, it can still be mutated in JavaScript/TypeScript; and doing so may de-synchronize these time-zone properties and lead to inconsistent results. Avoid modifying this field unless you fully understand the implications.
Available Methods
Last updated: Tue, Jun 23, 2026 07:34:42PM (UTC)