nhb-toolbox
Version:
A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.
86 lines (85 loc) • 6.01 kB
TypeScript
import type { LooseLiteral } from '../../utils/types';
import type { $Chronos, TimeZone, TimeZoneIdentifier, TimeZoneName, UTCOffset } from '../types';
declare module '../Chronos' {
interface Chronos {
/**
* @instance Creates a new instance of `Chronos` for the specified time zone identifier.
*
* @remarks Using time zone identifier to create time zone instance is the best option as it extracts info from {@link Intl.supportedValuesOf} API.
*
* @param tzId - Time zone identifier (e.g., `'Africa/Harare'`). See: {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones IANA TZ Database on Wikipedia}.
* @returns A new instance of `Chronos` with time in the given time zone identifier. Invalid input sets time-zone to `UTC`.
*/
timeZone(tzId: TimeZoneIdentifier): Chronos;
/**
* @instance Creates a new instance of `Chronos` for the specified abbreviated time zone name.
*
* @remarks Use abbreviated time zone name to create time zone instance only when you can't figure out the time zone identifier {@link TimeZoneIdentifier}.
*
* @param zone - Standard time zone abbreviation (e.g., `'IST'`, `'UTC'`, `'EST'` etc.). See: {@link https://en.wikipedia.org/wiki/List_of_time_zone_abbreviations Time zone abbreviations on Wikipedia}.
* @returns A new instance of `Chronos` with time in the given time zone abbreviation. Invalid input sets time-zone to `UTC`.
*/
timeZone(zone: TimeZone): Chronos;
/**
* @instance Creates a new instance of `Chronos` for the specified UTC offset.
*
* @remarks Use UTC offset only to create a fictional/unlisted time zone instance.
*
* @param utc - UTC Offset in `UTC±HH:mm` format for fictional or unlisted time zone (e.g., `'UTC+06:15'`).
* @returns A new instance of `Chronos` with time in the given utc offset. Invalid input sets time-zone to `UTC`.
*/
timeZone(utc: UTCOffset): Chronos;
/**
* @instance Creates a new instance of `Chronos` for the specified time zone id, abbreviation or UTC offset.
*
* @remarks
* - Using time zone identifier to create time zone instance is the best option as it extracts info from {@link Intl.supportedValuesOf} API.
* - Use abbreviated time zone name to create time zone instance only when you can't figure out the time zone identifier.
* - Use UTC offset only to create a fictional/unlisted time zone instance.
*
* @param tz - A time zone identifier ({@link TimeZoneIdentifier}), time zone abbreviation ({@link TimeZone}), or UTC offset ({@link UTCOffset}).
* @returns A new instance of `Chronos` with time in the given parameter. Invalid input sets time zone to `UTC`.
*/
timeZone(tz: TimeZoneIdentifier | TimeZone | UTCOffset): Chronos;
/**
* @instance Returns the current time zone name as a full descriptive string (e.g. `"Bangladesh Standard Time"`).
*
* @remarks
* - 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:00"`).
* - To retrieve the local system's native time zone name (or its identifier if the name is unavailable), use the {@link $getNativeTimeZoneName} instance method.
* - To retrieve the local system's native time zone identifier, use the {@link $getNativeTimeZoneId} instance method.
*
* @param utc Optional UTC offset in `"UTC+06:00"` format. When passed, it bypasses the current time zone offset.
* @returns Time zone name in full descriptive string or UTC offset if it is not a valid time zone.
*/
getTimeZoneName(utc?: UTCOffset): LooseLiteral<TimeZoneName | UTCOffset>;
/**
* @instance Returns the current time zone abbreviation (e.g. `"BST"` for `Bangladesh Standard Time`).
*
* @remarks
* - This method uses a predefined mapping of UTC offsets to abbreviated time zone codes.
* - If multiple time zones share the same UTC offset, it returns the **first abbreviation** from the list.
* - If no abbreviation is found it abbreviates full time zone name from {@link TIME_ZONE_LABELS} using UTC offset.
* - If no match is found (for unlisted or fictional utc offset), it returns the UTC offset (e.g. `"UTC+06:00"`).
* - To retrieve the local system's native time zone name (or its identifier if the name is unavailable), use the {@link $getNativeTimeZoneName} instance method.
* - To retrieve the local system's native time zone identifier, use the {@link $getNativeTimeZoneId} instance method.
*
* @param utc Optional UTC offset in `"UTC+06:00"` format. When passed, it bypasses the current time zone offset.
* @returns Time zone name in full descriptive string or UTC offset if it is not a valid time zone.
*/
getTimeZoneNameShort(utc?: UTCOffset): LooseLiteral<TimeZone | UTCOffset>;
/**
* @instance Returns the current time zone abbreviation (e.g. `"BST"` for `Bangladesh Standard Time`).
*
* @remarks This method is an alias for {@link getTimeZoneNameShort}.
*
* @param utc Optional UTC offset in `"UTC+06:00"` format. When passed, it bypasses the current time zone offset.
* @returns Time zone name in full descriptive string or UTC offset if it is not a valid time zone.
*/
getTimeZoneNameAbbr(utc?: UTCOffset): LooseLiteral<TimeZone | UTCOffset>;
}
}
/** * Plugin to inject `timeZone` related methods */
export declare const timeZonePlugin: ($Chronos: $Chronos) => void;