Conversion Methods

clone()

Signature

clone(): Chronos

Return Type

Chronos - New independent instance with identical date value

Behavior & Notes

• Creates a new instance with the same timestamp as the original
• Preserves the original's internal metadata (origin tracking)
• While Chronos is immutable, cloning is still useful for:
  • Maintaining separate metadata histories
  • Explicitly creating new instances for semantic clarity
  • Working with libraries/frameworks that check object identity

Example

const original = new Chronos('2025-01-15T12:00:00');
const copy = original.clone();

console.log(original.isEqual(copy)); // true (same timestamp)
console.log(original === copy); // false (different instances)

// With immutable operations:
const modified = original.add(1, 'day');
console.log(original.format()); // "Wed, Jan 15, 2025 12:00:00"
console.log(modified.format()); // "Thu, Jan 16, 2025 12:00:00"

Key Use Cases

• Metadata Preservation

const base = new Chronos('2025-01-01');
const modified = base.clone().subtract(3, 'days');

// Track different origins while maintaining immutability
console.log(base.origin);     // "root" 
console.log(modified.origin); // "clone"

Comparison with Alternatives

Approach	Instance Identity	Preserves Metadata	Performance
clone()	New instance	✅ Yes	⚠️ Slight overhead
new Chronos()	New instance	❌ No	⚠️ Slight overhead
Direct reference	Same instance	✅ Yes	✅ Best

tip

Use clone() when you need:

• Explicit control over instance creation
• To preserve metadata history
• Clear code semantics around date derivation

NOTE

While Chronos's immutability makes cloning less critical for safety, it remains valuable for:

• Tracking different origin points in complex date pipelines
• Integration with systems that care about object identity
• Making derivation operations more explicit in code

---

toDate()

Signature

toDate(): Date

Return Type

Date - Native Date object

Notes

• Returns new Date instance

Example

new Chronos('2025-01-15').toDate(); // Date object

---

toUTC()

Returns new Chronos instance in UTC time.

Signature

toUTC(): Chronos

Return Type

Chronos - UTC instance

Example

new Chronos('2025-01-15').toUTC(); // UTC-converted instance

---

toLocal()

Returns new Chronos instance in local time

Signature

toLocal(): Chronos

Return Type

Chronos - Local time instance

Example

Chronos.utc('2025-01-15').toLocal(); // Local time instance

---

timeZone()

Creates a new instance of Chronos for the specified time zone identifier, abbreviated time zone name or UTC offset.

Note

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

Signature

timeZone(tzId: TimeZoneIdentifier): Chronos;
timeZone(zone: TimeZone): Chronos;
timeZone(utc: UTCOffset): Chronos;
timeZone(utc: TimeZoneIdentifier | TimeZone | UTCOffset): Chronos;

Parameters

• tzId: IANA timezone identifier (e.g., 'Africa/Harare', 'America/New_York')
• zone: Standard timezone abbreviation (e.g., 'EST', 'IST', 'UTC')
• utc: UTC offset in UTC±HH:mm format for fictional/unlisted timezones (e.g., 'UTC+06:15')

Return Type

Chronos - New instance configured with the specified timezone context

Overloads

Timezone Identifier

Creates a new instance using an IANA timezone identifier. This is the recommended approach for accurate timezone handling.

new Chronos('2025-01-15').timeZone('Asia/Dhaka');
new Chronos('2025-01-15').timeZone('America/Los_Angeles');

Timezone Abbreviation

Creates a new instance using a standard timezone abbreviation. Use when timezone identifiers are not available.

new Chronos('2025-01-15').timeZone('EST'); // Eastern Standard Time
new Chronos('2025-01-15').timeZone('IST'); // Indian Standard Time

UTC Offset

Creates a new instance using a UTC offset for fictional or unlisted timezones.

new Chronos('2025-01-15').timeZone('UTC+08:00'); // 8 hours ahead of UTC
new Chronos('2025-01-15').timeZone('UTC-05:30'); // 5 hours 30 minutes behind UTC

Example

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

// Register plugin
Chronos.use(timeZonePlugin);

// Using IANA identifier (recommended)
const dhakaTime = new Chronos('2025-01-15').timeZone('Asia/Dhaka');

// Using timezone abbreviation
const easternTime = new Chronos('2025-01-15').timeZone('EST');

// Using UTC offset
const customOffset = new Chronos('2025-01-15').timeZone('UTC+06:30');

Remarks

• Timezone identifiers provide the most accurate timezone handling and are recommended for production use
• Timezone abbreviations should be used only when identifiers are not available, as they may have ambiguous interpretations
• UTC offsets are suitable for fictional timezones or regions not covered by the IANA database
• Invalid input automatically falls back to UTC timezone
• Returns a new Chronos instance - the original instance remains unchanged

---

toObject()

Converts to object with all date unit parts

Signature

toObject(): ChronosObject

Return Type

ChronosObject - Date components

/** Iterable `Chronos` object properties */
interface ChronosObject {
 /** Full year (e.g., 2025). */
 year: number;
 /** Month index starting from 0 (January = 0). */
 month: Enumerate<12>;
 /** ISO month number starting from 1 (January = 1). */
 isoMonth: NumberRange<1, 12>;
 /** Day of the month (1–31). */
 date: NumberRange<1, 31>;
 /** Day of the week index (0–6, Sunday = 0). */
 weekDay: Enumerate<7>;
 /** ISO day of the week number (1–7, Monday = 1). */
 isoWeekDay: NumberRange<1, 7>;
 /** Hour of the day (0–23). */
 hour: Enumerate<24>;
 /** Minute of the hour (0–59). */
 minute: Enumerate<60>;
 /** Second of the minute (0–59). */
 second: Enumerate<60>;
 /** Milliseconds within the second. */
 millisecond: Milliseconds;
 /** Timestamp in milliseconds since the Unix epoch. */
 timestamp: number;
 /** Unix timestamp in seconds since the epoch. */
 unix: number;
}

Example

new Chronos('2025-01-15').toObject();
// {year: 2025, month: 0, isoMonth: 1, ...}

---

toArray()

Converts to array with all date unit parts

Signature

toArray(): TupleOf<number, 12>

Return Type

TupleOf<number, 12> - Date component values as array (tuple) of numbers (12 elements, the values of ChronosObject from toObject method)

Example

new Chronos('2025-01-15').toArray();
// [ 2025, 0, 1, 15, 3, 3, 6, 0, 0, 0, 1736899200000, 1736899200 ]