Skip to main content

Name Getter Methods

Get Names of the Parts of Date, e.g. Day, Month, Season, Zodiac Signs etc.

day()​

Get the name of a weekday

Signature​

day(index?: Enumerate<7>): WeekDay

Parameter​

  • index (optional): A number from 0 to 6 representing the day of the week, where 0 is Sunday and 6 is Saturday. If omitted, it defaults to the current day from the Chronos instance.

Return Value​

  • WeekDay — The full name of the corresponding weekday ("Sunday", "Monday", ..., "Saturday").

Example Usage​

new Chronos('2025-05-29').day(); // "Thursday"
new Chronos().day(0);            // "Sunday"
info
  • This method supports overriding the current day with a specific index.
  • Internally, it maps indices 0–6 to the English names of the weekdays.

monthName()​

Get the name of a month

Signature​

monthName(index?: Enumerate<12>): MonthName

Parameters​

  • index (optional): A number from 0 to 11 representing the month, where 0 is January and 11 is December. If omitted, it defaults to the current month from the Chronos instance.

Return Value​

  • MonthName — The full name of the month ("January", "February", ..., "December").

Example Usage​

new Chronos('2025-05-29').monthName(); // "May"
new Chronos().monthName(11);           // "December"
info
  • This method supports overriding the current month with a specific index.
  • Internally, it maps indices 0–11 to the English names of the months.

$getNativeTimeZoneName()​

Retrieves the local system's current timezone name, falling back to its IANA timezone identifier if the name cannot be determined.

Signature​

$getNativeTimeZoneName(tzId?: $TimeZoneIdentifier): LooseLiteral<TimeZoneNameNative | $TimeZoneIdentifier>

Parameters​

  • tzId Optional time zone identifier to get time zone name for that identifier.

Return Type​

  • LooseLiteral<TimeZoneNameNative | $TimeZoneIdentifier> - The resolved timezone name or IANA identifier as fallback

Example​

const ch = new Chronos('2025-01-15');

// Get native timezone name
console.log(ch.$getNativeTimeZoneName());
// → "Bangladesh Standard Time" (if in Asia/Dhaka)
// → "Eastern Standard Time" (if in America/New_York)
// → "Asia/Dhaka" (fallback if name unavailable)

Remarks​

  • Always reflects the local machine's timezone name regardless of whether timeZone(), utc(), or toUTC() methods have been applied
  • For modified instances, use the timeZoneName public property instead to get the current instance's timezone context
  • Uses Intl.DateTimeFormat with timeZoneName: 'long' to resolve the display name
  • Falls back to the IANA identifier when no display name can be determined

Usage Notes​

const ch = new Chronos('2025-01-15').timeZone('UTC+02:45');

// These reflect the modified instance's timezone
console.log(ch.timeZoneName); // → "UTC+02:45"

// These always reflect the native system timezone
console.log(ch.$getNativeTimeZoneName());   // → "Bangladesh Standard Time"

$getNativeTimeZoneId()​

Retrieves the IANA timezone identifier for the local system's current timezone.

Signature​

$getNativeTimeZoneId(): TimeZoneIdNative

Return Type​

  • TimeZoneIdNative - The local system's IANA timezone identifier

Example​

const ch = new Chronos('2025-01-15');

// Get native IANA timezone identifier
console.log(ch.$getNativeTimeZoneId());
// → "Asia/Dhaka" (if in Bangladesh)
// → "America/New_York" (if in Eastern Time)
// → "Europe/London" (if in UK)

Remarks​

  • Always returns the local machine's timezone identifier regardless of whether timeZone(), utc(), or toUTC() methods have been applied
  • For modified instances, use the timeZoneId public property instead to get the current instance's timezone context
  • Directly accesses Intl.DateTimeFormat().resolvedOptions().timeZone for the system identifier
  • Returns standardized IANA timezone identifiers (e.g., "Asia/Dhaka", "America/New_York")

Usage Notes​

const ch = new Chronos('2025-01-15').timeZone('UTC+02:45');

// These reflect the modified instance's timezone
console.log(ch.timeZoneId);   // → "UTC+02:45"

// These always reflect the native system timezone
console.log(ch.$getNativeTimeZoneId()); // → "Asia/Dhaka"

getTimeZoneName()​

Get full time zone name or UTC offset

Note

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

Signature​

getTimeZoneName(utc?: UTCOffset): LooseLiteral<UTCOffset>

Parameters​

  • utc? — (Optional) A UTC offset string in the format "UTC+06:00", "UTC-04:30", etc.
    • If provided, it bypasses the instance's current offset and returns the name mapped to this offset instead.

Return Value​

  • LooseLiteral<UTCOffset> — The current time zone name as a full descriptive string (e.g. "Bangladesh Standard Time") or the fallback UTC offset (UTCOffset).

Example Usage​

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

Chronos.use(timeZonePlugin);

new Chronos().getTimeZoneName(); // "Bangladesh Standard Time"

// If it's a custom time zone or does not math with predefined time zones:
new Chronos().getTimeZoneName(); // "UTC+06:45"

new Chronos().getTimeZoneName('UTC+03:00'); 
// → "Arab Standard Time" (uses provided offset)

new Chronos().getTimeZoneName('UTC+06:15'); 
// → "UTC+06:15" (no matching time zone found)
info
  • This method uses a predefined mapping of UTC offsets to time zone names.
  • If multiple time zones share the same UTC offset, it returns the first match from the predefined list.
  • If no match is found (which is rare), it falls back to returning the UTC offset (e.g. "UTC+06:15").
  • Passing a custom utc offset overrides system/instance's offset detection.
  • To retrieve the local system's native time zone name (or its identifier if the name is unavailable), use the $getNativeTimeZoneName instance method.
  • To retrieve the local system's native time zone identifier, use the $getNativeTimeZoneId instance method.

getTimeZoneNameShort()​

Get abbreviated time zone name or UTC offset

Note

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

Signature​

getTimeZoneNameShort(utc?: UTCOffset): TimeZone | UTCOffset

Parameters​

  • utc? — (Optional) A UTC offset string in the format "UTC+06:00", "UTC-04:30", etc.
    • If provided, it bypasses the instance's current offset and returns the name mapped to this offset instead.

Return Value​

  • TimeZone | UTCOffset — The current time zone abbreviation (e.g. "BST" for Bangladesh Standard Time).

Example Usage​

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

Chronos.use(timeZonePlugin);

new Chronos().getTimeZoneNameShort(); // "BST"

// If it's a custom time zone or does not math with predefined time zones:
new Chronos().getTimeZoneNameShort(); // "UTC+06:45"

new Chronos().getTimeZoneNameShort('UTC+03:00'); 
// → "Arab Standard Time" (uses provided offset)

new Chronos().getTimeZoneNameShort('UTC+06:15'); 
// → "UTC+06:15" (no matching time zone found)
info
  • This method uses a predefined mapping of UTC offsets to time zone names.
  • If multiple time zones share the same UTC offset, it returns the first match from the predefined list.
  • If no match is found (which is rare), it falls back to returning the UTC offset (e.g. "UTC+06:15").
  • Passing a custom utc offset overrides system/instance's offset detection.
  • To retrieve the local system's native time zone name (or its identifier if the name is unavailable), use the $getNativeTimeZoneName instance method.
  • To retrieve the local system's native time zone identifier, use the $getNativeTimeZoneId instance method.

ALias​

Also available as getTimeZoneNameAbbr() alias.

season()​

Get season name

Signature​

season(options?: SeasonOptions): string

Alias​

  • getSeasonName is an alias for season method.

Overview​

The season() method determines the current season based on either predefined regional presets or custom season definitions. It supports both month-based and exact date-based season boundaries.

Note

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

Usage​

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

Chronos.use(seasonPlugin);

// Using default preset (Western seasons)
const now = new Chronos();
console.log(now.season()); // "Spring" (if between March-May)

// Using a specific preset
console.log(now.season({ preset: 'japan' }));

// Custom seasons
const customSeasons = [
  { name: 'Peak Time', boundary: { startDate: '11-20', endDate: '01-10' } }
];
console.log(now.season({ seasons: customSeasons }));

Configuration​

SeasonOptions​

interface SeasonOptions {
  seasons?: SeasonDefinition[];
  preset?: SeasonPreset;
}
  • seasons: Custom array of season definitions (overrides preset if provided)
  • preset: Name of predefined season configuration (default: 'default' - Western Seasons)

SeasonDefinition​

interface SeasonDefinition {
  name: string;
  boundary: MonthBoundary | DateBoundary;
}

Boundary can be either:

  • Month-based: { startMonth: 0-11, endMonth: 0-11 } (0=January)
  • Date-based: { startDate: 'MM-DD', endDate: 'MM-DD' }
Boundary Handling
  • Supports wrap-around seasons (e.g., Winter: Dec-Feb)
  • Boundaries are inclusive
  • Returns 'Unknown' if no season matches

Available Presets​

[
  { name: 'Spring', boundary: { startMonth: 2, endMonth: 4 } },  // Mar-May
  { name: 'Summer', boundary: { startMonth: 5, endMonth: 7 } },  // Jun-Aug
  { name: 'Autumn', boundary: { startMonth: 8, endMonth: 10 } }, // Sep-Nov
  { name: 'Winter', boundary: { startMonth: 11, endMonth: 1 } }  // Dec-Feb
]
Custom Seasons

You can create completely custom season configurations by providing your own array of SeasonDefinition objects:

const gamingSeasons = [
  { name: 'Pre-Season', boundary: { startMonth: 0, endMonth: 2 } },
  { name: 'Competitive', boundary: { startDate: '03-01', endDate: '09-30' } },
  { name: 'Off-Season', boundary: { startMonth: 10, endMonth: 11 } }
];

const currentSeason = new Chronos().season({ seasons: gamingSeasons });

Type Definitions​

type SeasonPreset = 
  | 'default'
  | 'bangladesh'
  | 'india'
  | 'tamil'
  | 'vedic'
  | 'philippines'
  | 'academic_us'
  | 'japan'
  | 'australia'
  | 'ethiopia';

type MonthDateString = `${MonthString}-${DateString}`; // 'MM-DD' format

interface DateBoundary {
  startDate: MonthDateString;
  endDate: MonthDateString;
}

interface MonthBoundary {
  startMonth: number; // 0-11 (0=January)
  endMonth: number;   // 0-11
}
Note

When using month-based boundaries (MonthBoundary), the season calculation only considers the month component and ignores specific dates within the month.

getZodiacSign()​

Signature​

getZodiacSign(options?: ZodiacOptions): ZodiacSign

Alias​

  • zodiac is an alias for getZodiacSign method.

Overview​

The getZodiacSign() method determines the zodiac sign based on either predefined presets (Western or Vedic) or custom zodiac definitions. It supports both instance date and custom birthdate inputs.

Note

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

Usage​

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

Chronos.use(zodiacPlugin);

// Using default preset (Western)
const now = new Chronos();
console.log(now.getZodiacSign()); // "Leo" (if between Jul 23-Aug 22)

// Using Vedic preset
console.log(now.getZodiacSign({ preset: 'vedic' }));

// Custom birthdate
console.log(now.getZodiacSign({ birthDate: '05-21' })); // "Gemini"

// Custom zodiac definitions
const customZodiac = [
  ['Aries', [3, 21]],
  ['Taurus', [4, 20]],
  // ...other signs
];
console.log(now.getZodiacSign({ custom: customZodiac }));

Configuration​

ZodiacOptions​

interface ZodiacOptions {
  birthDate?: MonthDateString; // 'MM-DD' format (1-based month)
  preset?: ZodiacPreset;       // 'western' | 'vedic' | 'tropical' | 'sidereal'
  custom?: ZodiacArray;        // Custom zodiac definitions
}
  • birthDate: Optional date in 'MM-DD' format to use instead of instance date
  • preset: Name of predefined zodiac configuration (default: 'western')
  • custom: Custom array of zodiac definitions (overrides preset if provided)

Available Presets​

[
  ['Capricorn', [12, 22]],
  ['Aquarius', [1, 20]],
  ['Pisces', [2, 19]],
  ['Aries', [3, 21]],
  ['Taurus', [4, 20]],
  ['Gemini', [5, 21]],
  ['Cancer', [6, 21]],
  ['Leo', [7, 23]],
  ['Virgo', [8, 23]],
  ['Libra', [9, 23]],
  ['Scorpio', [10, 23]],
  ['Sagittarius', [11, 22]],
  ['Capricorn', [12, 22]]
]
Custom Zodiac

You can create custom zodiac configurations by providing your own array of zodiac definitions but must use the 12 existing zodiac sign names, only date ranges are customizable:

const customZodiac = [
  ['Capricorn', [1, 1]], 
  ['Sagittarius', [2, 1]],
  // ...other signs
];

const currentSign = new Chronos().getZodiacSign({ custom: customZodiac });

Type Definitions​

type ZodiacPreset = 'western' | 'vedic' | 'tropical' | 'sidereal';
type ZodiacSign = 'Aries' | 'Taurus' | ...; // All zodiac sign names
type ZodiacArray = Array<[ZodiacSign, [month: 1 | 2 | ... | 12, day: 1 | 2 | ... | 31]]>;
Date Handling
  • Month values are 1-based (1 = January)
  • Supports both instance date and custom birthdate input
  • Returns the first sign if no matches found (shouldn't occur with proper definitions)

getPartOfDay()​

Note

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

Signature​

getPartOfDay(config?: Partial<DayPartConfig>): DayPart

Parameters​

  • config: Custom day part ranges

Return Type​

DayPart - Current part of day

Default Ranges​

PartRange
midnight00:00-01:00
lateNight02:00-04:00
morning05:00-11:00
afternoon12:00-16:00
evening17:00-20:00
night21:00-23:00

Example​

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

Chronos.use(dayPartPlugin);

new Chronos('2025-01-15T09:00:00').getPartOfDay(); // "morning"