houser-js-utils/dist/TimeZoneUtils.d.ts

A comprehensive collection of TypeScript utility functions for common development tasks including array manipulation, string processing, date handling, random number generation, validation, and much more.

/**
 * @module TimeZoneUtils
 * @description Utility functions for working with time zones, including getting time zone details, managing time zone lists, and handling user time zone preferences. Provides comprehensive support for IANA time zones with proper formatting and validation.
 * @example
 * ```typescript
 * import { TimeZoneUtils } from 'houser-js-utils';
 *
 * // Get user's time zone
 * const userTimeZone = TimeZoneUtils.getUsersTimeZone();
 * console.log(`User's time zone: ${userTimeZone.name} (${userTimeZone.shortName})`);
 *
 * // Get filtered time zones
 * const timeZones = TimeZoneUtils.getTimeZones(['America/New_York', 'Europe/London']);
 *
 * // Get time zone options for select element
 * const options = TimeZoneUtils.getTimeZonesOptions('America/New_York', 'Europe/London');
 * ```
 */
/**
 * Interface for time zone data
 * @interface TimeZone
 * @property {string} name - The IANA time zone name (e.g., 'America/New_York')
 * @property {string} shortName - The abbreviated time zone name (e.g., 'EDT')
 */
interface TimeZone {
    name: string;
    shortName: string;
}
/**
 * Creates an HTML option element string for a time zone
 */
export declare const createTimeZoneOption: (name: string, shortName: string) => string;
export declare const TimeZoneUtils: {
    /**
     * Gets details for a specific time zone
     * @param timeZone - The IANA time zone name
     * @returns Object containing time zone name and short name
     * @throws Error if the time zone is invalid
     * @example
     * ```typescript
     * const details = TimeZoneUtils.getTimeZoneDetails('America/New_York');
     * console.log(details);
     * // Output: { name: 'America/New_York', shortName: 'EDT' }
     * ```
     */
    getTimeZoneDetails(timeZone: string): TimeZone;
    /**
     * Gets a list of time zones, optionally filtered and with user's time zone first
     * @param filters - Optional array of time zone names to filter by
     * @param showUsersFirst - Whether to show user's time zone first in the list
     * @returns Array of time zone objects
     * @example
     * ```typescript
     * // Get all time zones with user's time zone first
     * const allTimeZones = TimeZoneUtils.getTimeZones();
     *
     * // Get filtered time zones without user's time zone first
     * const filteredTimeZones = TimeZoneUtils.getTimeZones(
     *   ['America/New_York', 'Europe/London'],
     *   false
     * );
     * ```
     */
    getTimeZones(filters?: string[], showUsersFirst?: boolean): TimeZone[];
    /**
     * Gets HTML option elements for time zones
     * @param filters - Optional array of time zone names to filter by
     * @returns Array of HTML option strings
     * @example
     * ```typescript
     * // Get options for specific time zones
     * const options = TimeZoneUtils.getTimeZonesOptions(
     *   'America/New_York',
     *   'Europe/London'
     * );
     *
     * // Use in select element
     * const select = document.createElement('select');
     * select.innerHTML = options.join('');
     * ```
     */
    getTimeZonesOptions(...filters: string[]): string[];
    /**
     * Gets the user's time zone
     * @returns Time zone object for user's time zone
     * @example
     * ```typescript
     * const userTimeZone = TimeZoneUtils.getUsersTimeZone();
     * console.log(`User's time zone: ${userTimeZone.name} (${userTimeZone.shortName})`);
     * ```
     */
    getUsersTimeZone(): TimeZone;
    /**
     * Gets the user's time zone name
     * @returns User's IANA time zone name
     * @example
     * ```typescript
     * const timeZoneName = TimeZoneUtils.getUsersTimeZoneName();
     * console.log(`User's time zone name: ${timeZoneName}`);
     * ```
     */
    getUsersTimeZoneName(): string;
    /**
     * Checks if a time zone name is valid
     * @param timeZone - The IANA time zone name to check
     * @returns True if the time zone is valid
     * @example
     * ```typescript
     * const isValid = TimeZoneUtils.isValidTimeZone('America/New_York');
     * console.log(`Is valid time zone: ${isValid}`);
     * ```
     */
    isValidTimeZone(timeZone: string): boolean;
};
export {};