nhb-toolbox/dist/dts/date/utils.d.ts

A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.

import type { Maybe, Numeric } from '../types/index';
import type { $TimeZoneIdentifier, ClockTime, DateArgs, DateFormatOptions, HourMinutes, ISODateFormat, ISOTimeString, StrictFormat, TimeOnlyFormat, TimestampOptions, TimeZoneDetails, TimeZoneIdNative, UTCOffset } from './types';
/**
 * * Extracts the hour and minute from a time string in `HH:MM` or `-HH:MM` format.
 *
 * @param time - The time string to extract from.
 * @return The extracted hour and minute as number tuple.
 */
export declare function extractHourMinute(time: `-${ClockTime}` | ClockTime): [number, number];
/**
 * * Converts a time string `HH:MM` or `-HH:MM` into total minutes from `00:00`.
 *
 * @param time - The time in `HH:MM` or `-HH:MM` format.
 * @returns The total minutes elapsed since `00:00`.
 */
export declare function getTotalMinutes(time: `-${ClockTime}` | ClockTime): number;
/**
 * * Returns the current date and time as `Date` object.
 * - All the methods and properties of `new Date()` are accessible.
 *
 * @remarks This function is a simple wrapper around `new Date()` and is provided for consistency and potential future enhancements.
 *
 * @returns The current date and time as a `Date` object.
 */
export declare function getCurrentDateTime(): Date;
/**
 * * Extract Time in `HH:MM` format from given UTC value.
 *
 * @param utc UTC value in `UTC-01:30` or `UTC+01:30` format.
 * @returns The UTC value in `HH:MM` format.
 */
export declare function extractTimeFromUTC(utc: UTCOffset): `-${ClockTime}` | ClockTime;
/**
 * * Converts a UTC value in `UTC-01:30` or `UTC+01:30` format into total minutes in number.
 *
 * @param time - UTC value in `UTC-01:30` or `UTC+01:30` format.
 * @returns The total minutes elapsed since `00:00`.
 */
export declare function extractMinutesFromUTC(utc: UTCOffset): number;
/**
 * * Converts a number of minutes into a time string in "HH:MM" format.
 *
 * @param minutes - The number of minutes to convert. Can be a number or a numeric string.
 * @returns A string representing the time in "HH:MM" format.
 *
 * @remarks Always returns the absolute value of the minutes, ignoring the sign if they are negative.
 *
 * @example
 * convertMinutesToTime(75); // "1:15"
 * convertMinutesToTime(-45); // "0:45"
 */
export declare function convertMinutesToTime(minutes: Numeric): HourMinutes;
/**
 * * Converts a minute-based offset to a UTC offset string in the format `UTC±HH:MM`.
 *
 * @param minutes - The offset in minutes (positive or negative).
 * @returns A formatted UTC offset string like `UTC+05:30` or `UTC-04:00`.
 */
export declare function formatUTCOffset(minutes: Numeric): UTCOffset;
/** Get the current system's time zone identifier using {@link Intl.DateTimeFormat} API. */
export declare function getNativeTimeZoneId(): TimeZoneIdNative;
/**
 * * Retrieves comprehensive time zone details using the {@link Intl.DateTimeFormat} API.
 * @param tzId Optional timezone identifier. Defaults to the system timezone.
 * @param date Optional date for which to resolve the information.
 * @returns Object containing time zone identifier, names, and offset.
 */
export declare function getTimeZoneDetails(tzId?: $TimeZoneIdentifier, date?: Date): TimeZoneDetails;
/**
 * * Resolves all IANA time-zone identifiers that match a given UTC offset.
 *
 * @remarks
 * - Uses an internal in-memory cache that persists for the lifetime of the running application.
 * - The cache is lazily populated so the `offset`-to-`time-zone` mapping is computed only once per offset.
 * - Offset and time-zone identifier detection uses the {@link Intl.DateTimeFormat} API.
 *
 * @param offset The UTC offset in `"UTC±HH:MM"` format.
 * @returns An array of matching IANA time-zone identifiers, or an empty array if the offset is invalid.
 */
export declare function getTimeZoneIds(offset: UTCOffset): TimeZoneIdNative[];
/**
 * * Formats a date into a specified string format.
 *
 * @param options Options to control date and time formatting.
 *
 * @remarks
 * - If no date is provided, the current date and time will be used.
 * - If the provided date is invalid, the function will return `'Invalid Date!'`.
 * - The default format is `'dd, mmm DD, YYYY HH:mm:ss'` (e.g., `'Sun, Apr 06, 2025 16:11:55'`).
 * - By default, local time is used; set `useUTC` to `true` to format in UTC.
 * - The format string supports various tokens for date and time components, as well as literal text enclosed in square brackets.
 * - See {@link https://toolbox.nazmul-nhb.dev/docs/utilities/date/formatDate#format-tokens format tokens} for details on supported tokens.
 * - For more complex date/time manipulations, consider using the {@link https://toolbox.nazmul-nhb.dev/docs/classes/Chronos Chronos} class.
 *
 * @returns Date/time string in specified format.
 */
export declare function formatDate(options?: DateFormatOptions): string;
/**
 * * Formats a time-only string into a formatted time string.
 *
 * @param time - Time string to be formatted. Supported formats include:
 * - `HH:mm` → e.g., `'14:50'`
 * - `HH:mm:ss` → e.g., `'14:50:00'`
 * - `HH:mm:ss.mss` → e.g., `'14:50:00.800'`
 * - `HH:mm+TimeZoneOffset(HH)` → e.g., `'14:50+06'`
 * - `HH:mm+TimeZoneOffset(HH:mm)` → e.g., `'14:50+06:00'`
 * - `HH:mm:ss+TimeZoneOffset(HH)` → e.g., `'14:50:00+06'`
 * - `HH:mm:ss+TimeZoneOffset(HH:mm)` → e.g., `'14:50:00+05:30'`
 * - `HH:mm:ss.mss+TimeZoneOffset(HH)` → e.g., `'14:50:00.800+06'`
 * - `HH:mm:ss.mss+TimeZoneOffset(HH:mm)` → e.g., `'14:50:00.800+06:30'`
 *
 * - *Input will default to today's date and assume local timezone if no offset is provided.*
 *
 * @param format - Format tokens accepted by {@link formatDate} method ({@link TimeOnlyFormat}) for time part only.
 *                 Default: `hh:mm:ss a` → 02:33:36 pm.
 * @returns Formatted time string in local (System) time.
 */
export declare function formatTimePart(time: string, format?: TimeOnlyFormat): string;
/**
 * * Formats a date as a relative time string (e.g., "5m ago", "2h from now").
 *
 * @param date - The date to format, which can be a `Date` object, a date string, or a timestamp number.
 * @param format - Optional format string for dates older than 7 days. Defaults to `'mmm D, yyyy hh:mm a'`.
 * @returns A relative time string if the date is within the last 7 days, otherwise a formatted date string.
 *
 * @remarks
 * - If date is provided but `undefined`, current date and time will be used.
 * - If the provided date is invalid, the function will return `'Invalid Date!'`.
 * - For dates within the last 7 days, the output will be in the format of "Xm ago" or "Xh from now".
 * - For dates older than 7 days, the output will be formatted using the provided `format` string or the default format if none is provided.
 *
 * @example
 * formatDateRelative(Date.now() - 5 * 60000); // "5m ago"
 * formatDateRelative(Date.now() + 2 * 3600000); // "2h from now"
 * formatDateRelative(Date.now() - 10 * 86400000); // "Apr 6, 2026 04:11 PM" (formatted date string)
 */
export declare function formatDateRelative(date: Maybe<DateArgs>, format?: StrictFormat): string;
/**
 * * Get timestamp in ISO 8601 format for the current date and time.
 *
 * @returns Timestamp string in ISO 8601 format.
 */
export declare function getTimestamp(): ISOTimeString;
/**
 * * Get timestamp in ISO 8601 format.
 *
 * @param value - Date value to convert to timestamp. Supported formats include:
 * - `Date` object → e.g., `new Date()`
 * - Date string → e.g., `'2025-04-06'`, `'2025-04-06 16:11:55'`, `'April 6, 2025 16:11:55'` etc.
 * - Timestamp number → e.g., `1712748715000`
 * @param format - Format of the output timestamp.
 * - Use `format: 'local'` to include the current system timezone offset.
 * - Default is `'utc'` which returns timestamp in UTC format (ending with 'Z').
 *
 * @remarks If the provided {@link value} is invalid, the current date and time will be used.
 *
 * @returns Timestamp string in ISO 8601 format.
 */
export declare function getTimestamp(value: DateArgs, format?: ISODateFormat): ISOTimeString;
/**
 * * Get timestamp in ISO 8601 format.
 *
 * @param options Options to control date input and output format.
 *
 * @remarks
 * - If the provided {@link TimestampOptions.value value} is invalid, the current date and time will be used.
 * - Use {@link TimestampOptions.format format}: `'local'` to include the current system time & timezone offset.
 *
 * @returns Timestamp string in ISO 8601 format.
 */
export declare function getTimestamp(options: TimestampOptions): ISOTimeString;