Skip to main content

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.isSame(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);     // "constructor" 
console.log(modified.origin); // "clone"

Comparison with Alternatives​

ApproachInstance IdentityPreserves MetadataPerformance
clone()New instance✅ Yes⚠️ Slight overhead
new Chronos()New instance❌ No⚠️ Slight overhead
Direct referenceSame 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()​

Signature​

toUTC(): Chronos

Return Type​

Chronos - UTC instance

Example​

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

toLocal()​

Signature​

toLocal(): Chronos

Return Type​

Chronos - Local time instance

Example​

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

timeZone()​

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(zone: TimeZone | UTCOffSet): Chronos

Parameters​

  • zone: Timezone identifier or offset

Return Type​

Chronos - Instance in specified timezone

Example​

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

Chronos.use(timeZonePlugin);

new Chronos('2025-01-15').timeZone('EST'); // Eastern Time instance
new Chronos('2025-01-15').timeZone('UTC+08:00'); // 8 hours ahead of UTC/GMT

toObject()​

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

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 ]