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

playground.ts

Remarks

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

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

$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

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")

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

playground.ts

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

playground.ts

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

playground.ts

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<Sign extends string = ZodiacSign>(options?: ZodiacOptions<Sign>): Sign

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

playground.ts

Configuration

ZodiacOptions

interface ZodiacOptions<Sign extends string = ZodiacSign> {
  birthDate?: MonthDateString;      // 'MM-DD' format (1-based month)
  preset?: ZodiacPreset;      // 'western' | 'vedic' | 'tropical' | 'sidereal'
  custom?: ZodiacArray<Sign> | Readonly<ZodiacArray<Sign>>;     // 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]]
]

Custom Zodiac

You can create custom zodiac configurations by providing your own array of zodiac definitions with any zodiac sign names:

const customZodiac = [
  ['Capricorn', [1, 1]], 
  ['Sagittarius', [2, 1]],
  ['A', [3, 1]],
  ['B', [6, 1]],
  ['C', [9, 1]],
  ['D', [12, 1]],
  // ...other signs, zodiac names can be any string
] as const;

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<Sign extends string = ZodiacSign> = Array<
  [Sign, [NumberRange<1, 12>, NumberRange<1, 31>]] | Readonly<[Sign, Readonly<[NumberRange<1, 12>, NumberRange<1, 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 presets or proper definitions)

getZodiacMeta()

Signature

getZodiacMeta<Sign extends string = ZodiacSign>(sign: Sign, options?: ZodiacMetaOptions<Sign>): ZodiacMeta<Sign>

Overview

The getZodiacMeta() method retrieves detailed metadata for a specific zodiac sign based on either predefined presets (Western or Vedic) or custom zodiac definitions. It returns the sign's chronological position, inclusive date range, and handles year-boundary wrapping correctly.

Note

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

Usage

playground.ts

Configuration

ZodiacMetaOptions

interface ZodiacMetaOptions<Sign extends string = ZodiacSign> {
  preset?: ZodiacPreset;      // 'western' | 'vedic' | 'tropical' | 'sidereal'
  custom?: ZodiacArray<Sign> | Readonly<ZodiacArray<Sign>>;     // Custom zodiac definitions
}

preset: Name of predefined zodiac configuration (default: 'western')
custom: Custom array of zodiac definitions (overrides preset if provided)

Return Value

ZodiacMeta

interface ZodiacMeta<Sign extends string = ZodiacSign> {
  index: number;      // 0-based chronological position
  sign: Sign;         // The zodiac sign name
  start: MonthDateString;    // Inclusive start date in 'MM-DD' format
  end: MonthDateString;      // Inclusive end date in 'MM-DD' format
}

index

The index property represents the chronological position (0-based) of the zodiac sign within the resolved and sorted zodiac list.

Important Notes about Index

The index is determined by the Gregorian month–day ordering of zodiac start dates
Index values may differ between zodiac variants (e.g., Western vs Vedic)
This index should not be interpreted as a traditional or mythological zodiac ordering
It's primarily useful for programmatic sorting and comparison within the same zodiac variant

Available Presets

The same presets as getZodiacSign() are available:

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

Year-Boundary Handling

The method correctly handles zodiac signs that wrap around year boundaries:

playground.ts

Error Handling

The method throws a RangeError if the provided sign does not exist in the resolved zodiac list:

playground.ts

Common Use Cases

1 Display sign information:

function displayZodiacInfo(sign: string) {
  const meta = chronos.getZodiacMeta(sign);
  console.log(`${meta.sign}: ${meta.start} to ${meta.end}`);
}

2 Sort signs chronologically:

const signs = ['Leo', 'Aries', 'Capricorn', 'Libra'];
const sortedSigns = signs.sort((a, b) => {
  const metaA = chronos.getZodiacMeta(a);
  const metaB = chronos.getZodiacMeta(b);
  return metaA.index - metaB.index;
});
// Result: ['Aries', 'Leo', 'Libra', 'Capricorn']

3 Validate date ranges:

function isDateInSign(date: MonthDateString, sign: string): boolean {
  const meta = chronos.getZodiacMeta(sign);
  // Implementation to check if date falls within meta.start to meta.end
  // considering year-boundary wrapping
}

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

Part	Range
midnight	00:00-01:00
lateNight	02:00-04:00
morning	05:00-11:00
afternoon	12:00-16:00
evening	17:00-20:00
night	21:00-23:00

Example

playground.ts

On this page