@megaorm/utc/dist/index.d.ts

This package is designed for handling date and time manipulation in UTC (Coordinated Universal Time).

/**
 * Custom error class for handling UTC-related errors.
 *
 */
export declare class UTCError extends Error {
}
/**
 * Formats a Date object as a string in the format `YYYY-MM-DD hh:mm:ss`.
 *
 * @param date The Date object to format.
 * @returns A string representing the date in the format `YYYY-MM-DD hh:mm:ss`.
 *
 * @example
 * const now = new Date();
 * console.log(formatDate(now)); // '2024-10-24 10:00:00'
 */
export declare function formatDate(date: Date): string;
/**
 * Extracts the date part from a datetime string `YYYY-MM-DD`.
 *
 * @param datetime The datetime string in `YYYY-MM-DD hh:mm:ss` format.
 * @returns A string representing the date part `YYYY-MM-DD`.
 *
 * @example
 * console.log(parseDate('2024-10-24 10:00:00')); // '2024-10-24'
 */
export declare function parseDate(datetime: string): string;
/**
 * Extracts the time part from a datetime string `hh:mm:ss`.
 *
 * @param datetime The datetime string in `YYYY-MM-DD hh:mm:ss` format.
 * @returns A string representing the date part `hh:mm:ss`.
 *
 * @example
 * console.log(parseDate('2024-10-24 10:00:00')); // '10:00:00'
 */
export declare function parseTime(datetime: string): string;
/**
 * Returns the current UTC date and time in `YYYY-MM-DD hh:mm:ss` format.
 *
 * @returns A string representing the UTC date and time in the format `YYYY-MM-DD hh:mm:ss`.
 */
export declare function getDateTime(): string;
/**
 * Returns the current UTC date in 'YYYY-MM-DD' format.
 *
 * @param datetime The UTC datetime string to get the date from in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns A string representing the UTC date in the format `YYYY-MM-DD`.
 */
export declare function getDate(datetime?: string): string;
/**
 * Returns the current UTC time in 'hh:mm:ss' format.
 *
 * @param datetime The UTC datetime string to get the time from in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns A string representing the UTC time in the format `hh:mm:ss`.
 */
export declare function getTime(datetime?: string): string;
/**
 * Returns the current UTC year as an integer.
 *
 * @param datetime The UTC datetime string to get the year from in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The UTC year as a number.
 */
export declare function getYear(datetime?: string): number;
/**
 * Returns the current UTC month as an integer (0-11).
 *
 * @param datetime The UTC datetime string to get the month from in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The UTC month as a number (0-11, where 0 = January, 11 = December).
 * @throws UTCError if the datetime is not valid.
 */
export declare function getMonth(datetime?: string): number;
/**
 * Returns the current UTC day of the month as an integer (1-31).
 *
 * @param datetime The UTC datetime string to get the day from in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The UTC day of the month as a number (1-31).
 * @throws UTCError if the datetime is not valid.
 */
export declare function getDay(datetime?: string): number;
/**
 * Returns the current UTC hour as an integer.
 *
 * @param datetime The UTC datetime string to get the hour from in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The UTC hour as a number (0-23).
 */
export declare function getHour(datetime?: string): number;
/**
 * Returns the current UTC minute as an integer.
 *
 * @param datetime The UTC datetime string to get the minute from in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The UTC minute as a number (0-59).
 */
export declare function getMinute(datetime?: string): number;
/**
 * Returns the current UTC second as an integer.
 *
 * @param datetime The UTC datetime string to get the second from in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The UTC second as a number (0-59).
 */
export declare function getSecond(datetime?: string): number;
/**
 * Sets the UTC year of the given datetime.
 *
 * @param datetime The UTC datetime string to set the year for in 'YYYY-MM-DD hh:mm:ss' format.
 * @param year The year to set.
 * @returns A string representing the updated datetime with the new UTC year.
 * @throws UTCError if the datetime is not valid.
 */
export declare function setYear(datetime: string, year: number): string;
/**
 * Sets the UTC month of the given datetime.
 *
 * @param datetime The UTC datetime string to set the month for in 'YYYY-MM-DD hh:mm:ss' format.
 * @param month The month to set (0-11, where 0 = January, 11 = December).
 * @returns A string representing the updated datetime with the new UTC month.
 * @throws UTCError if the datetime is not valid.
 */
export declare function setMonth(datetime: string, month: number): string;
/**
 * Sets the UTC day of the given datetime.
 *
 * @param datetime The UTC datetime string to set the day for in 'YYYY-MM-DD hh:mm:ss' format.
 * @param day The day to set (1-31).
 * @returns A string representing the updated datetime with the new UTC day.
 * @throws UTCError if the datetime is not valid.
 */
export declare function setDay(datetime: string, day: number): string;
/**
 * Sets the UTC hour of the given datetime.
 *
 * @param datetime The UTC datetime string to set the hour for in 'YYYY-MM-DD hh:mm:ss' format.
 * @param hour The hour to set (0-23).
 * @returns A string representing the updated datetime with the new UTC hour.
 * @throws UTCError if the datetime is not valid.
 */
export declare function setHour(datetime: string, hour: number): string;
/**
 * Sets the UTC minute of the given datetime.
 *
 * @param datetime The UTC datetime string to set the minute for in 'YYYY-MM-DD hh:mm:ss' format.
 * @param minute The minute to set (0-59).
 * @returns A string representing the updated datetime with the new UTC minute.
 * @throws UTCError if the datetime is not valid.
 */
export declare function setMinute(datetime: string, minute: number): string;
/**
 * Sets the UTC second of the given datetime.
 *
 * @param datetime The UTC datetime string to set the second for in 'YYYY-MM-DD hh:mm:ss' format.
 * @param second The second to set (0-59).
 * @returns A string representing the updated datetime with the new UTC second.
 * @throws UTCError if the datetime is not valid.
 */
export declare function setSecond(datetime: string, second: number): string;
/**
 * Adds a specified number of years to the current UTC datetime or the provided datetime.
 *
 * @param years The number of years to add.
 * @param datetime The UTC datetime string to modify in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The modified datetime string with the added years in 'YYYY-MM-DD hh:mm:ss' format.
 * @throws `UTCError` if the number of years is not a positive integer or if invalid datetime is provided.
 */
export declare function addYears(years: number, datetime?: string): string;
/**
 * Adds a specified number of months to the current UTC datetime or the provided datetime.
 *
 * @param months The number of months to add.
 * @param datetime The UTC datetime string to modify in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The modified datetime string with the added months in 'YYYY-MM-DD hh:mm:ss' format.
 * @throws `UTCError` if the number of months is not a positive integer or if invalid datetime is provided.
 */
export declare function addMonths(months: number, datetime?: string): string;
/**
 * Adds a specified number of days to the current UTC datetime or the provided datetime.
 *
 * @param days The number of days to add.
 * @param datetime The UTC datetime string to modify in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The modified datetime string with the added days in 'YYYY-MM-DD hh:mm:ss' format.
 * @throws `UTCError` if the number of days is not a positive integer or if invalid datetime is provided.
 */
export declare function addDays(days: number, datetime?: string): string;
/**
 * Adds a specified number of hours to the current UTC datetime or the provided datetime.
 *
 * @param hours The number of hours to add.
 * @param datetime The UTC datetime string to modify in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The modified datetime string with the added hours in 'YYYY-MM-DD hh:mm:ss' format.
 * @throws `UTCError` if the number of hours is not a positive integer or if invalid datetime is provided.
 */
export declare function addHours(hours: number, datetime?: string): string;
/**
 * Adds a specified number of minutes to the current UTC datetime or the provided datetime.
 *
 * @param minutes The number of minutes to add.
 * @param datetime The UTC datetime string to modify in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The modified datetime string with the added minutes in 'YYYY-MM-DD hh:mm:ss' format.
 * @throws `UTCError` if the number of minutes is not a positive integer or if invalid datetime is provided.
 */
export declare function addMinutes(minutes: number, datetime?: string): string;
/**
 * Adds a specified number of seconds to the current UTC datetime or the provided datetime.
 *
 * @param seconds The number of seconds to add.
 * @param datetime The UTC datetime string to modify in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The modified datetime string with the added seconds in 'YYYY-MM-DD hh:mm:ss' format.
 * @throws `UTCError` if the number of seconds is not a positive integer or if invalid datetime is provided.
 */
export declare function addSeconds(seconds: number, datetime?: string): string;
/**
 * Subtracts a specified number of years from the current UTC datetime or the provided datetime.
 *
 * @param years The number of years to subtract.
 * @param datetime The UTC datetime string to modify in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The modified datetime string with the subtracted years in 'YYYY-MM-DD hh:mm:ss' format.
 * @throws `UTCError` if the number of years is not a positive integer or if invalid datetime is provided.
 */
export declare function removeYears(years: number, datetime?: string): string;
/**
 * Subtracts a specified number of months from the current UTC datetime or the provided datetime.
 *
 * @param months The number of months to subtract.
 * @param datetime The UTC datetime string to modify in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The modified datetime string with the subtracted months in 'YYYY-MM-DD hh:mm:ss' format.
 * @throws `UTCError` if the number of months is not a positive integer or if invalid datetime is provided.
 */
export declare function removeMonths(months: number, datetime?: string): string;
/**
 * Subtracts a specified number of days from the current UTC datetime or the provided datetime.
 *
 * @param days The number of days to subtract.
 * @param datetime The UTC datetime string to modify in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The modified datetime string with the subtracted days in 'YYYY-MM-DD hh:mm:ss' format.
 * @throws `UTCError` if the number of days is not a positive integer or if invalid datetime is provided.
 */
export declare function removeDays(days: number, datetime?: string): string;
/**
 * Subtracts a specified number of hours from the current UTC datetime or the provided datetime.
 *
 * @param hours The number of hours to subtract.
 * @param datetime The UTC datetime string to modify in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The modified datetime string with the subtracted hours in 'YYYY-MM-DD hh:mm:ss' format.
 * @throws `UTCError` if the number of hours is not a positive integer or if invalid datetime is provided.
 */
export declare function removeHours(hours: number, datetime?: string): string;
/**
 * Subtracts a specified number of minutes from the current UTC datetime or the provided datetime.
 *
 * @param minutes The number of minutes to subtract.
 * @param datetime The UTC datetime string to modify in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The modified datetime string with the subtracted minutes in 'YYYY-MM-DD hh:mm:ss' format.
 * @throws `UTCError` if the number of minutes is not a positive integer or if invalid datetime is provided.
 */
export declare function removeMinutes(minutes: number, datetime?: string): string;
/**
 * Subtracts a specified number of seconds from the current UTC datetime or the provided datetime.
 *
 * @param seconds The number of seconds to subtract.
 * @param datetime The UTC datetime string to modify in 'YYYY-MM-DD hh:mm:ss' format.
 * @returns The modified datetime string with the subtracted seconds in 'YYYY-MM-DD hh:mm:ss' format.
 * @throws `UTCError` if the number of seconds is not a positive integer or if invalid datetime is provided.
 */
export declare function removeSeconds(seconds: number, datetime?: string): string;
/**
 * Converts a datetime string from a specific timezone to UTC.
 *
 * @param dateime A string representing a date and time in the format: `YYYY-MM-DD hh:mm:ss`.
 * @param timezone The IANA time zone string (e.g., 'America/New_York').
 * @returns A string representing the equivalent UTC date and time in the format `YYYY-MM-DD hh:mm:ss`.
 * @throws `UTCError` if the date or timezone format is invalid.
 *
 * @example
 * // Convert date in Europe/London to UTC
 * console.log(UTC.from.date('2024-06-15 12:00:00', 'Europe/London'));
 * // Output: '2024-06-15 11:00:00' (1-hour difference)
 *
 * // Convert date in Australia/Sydney to UTC
 * console.log(UTC.from.date('2024-12-25 15:00:00', 'Australia/Sydney'));
 * // Output: '2024-12-25 04:00:00' (11-hour difference from UTC)
 *
 * // Convert an ISO format date in America/New_York to UTC
 * console.log(UTC.from.date('2024-02-09 13:45:30', 'America/New_York'));
 * // Output: '2024-02-09 18:45:30' (5-hour difference)
 */
export declare function toUTC(datetime: string, timezone: string): string;
/**
 * The `UTC` class provides utility methods to get the current UTC date/time,
 * convert dates and timestamps from specific time zones to UTC,
 * and manipulate future and past UTC dates.
 */
export declare class UTC {
    static toUTC: typeof toUTC;
    static formatDate: typeof formatDate;
    static parseDate: typeof parseDate;
    static parseTime: typeof parseTime;
    /**
     * Provides methods to retrieve various formats of the current UTC date and time.
     */
    static get: {
        date: typeof getDate;
        time: typeof getTime;
        year: typeof getYear;
        month: typeof getMonth;
        day: typeof getDay;
        hour: typeof getHour;
        minute: typeof getMinute;
        second: typeof getSecond;
        datetime: typeof getDateTime;
    };
    /**
     * Provides methods to retrieve various formats of the current UTC date and time.
     */
    static set: {
        year: typeof setYear;
        month: typeof setMonth;
        day: typeof setDay;
        hour: typeof setHour;
        minute: typeof setMinute;
        second: typeof setSecond;
    };
    /**
     * Provides methods to calculate future dates in UTC by adding a specified amount of time.
     */
    static future: {
        year: typeof addYears;
        month: typeof addMonths;
        day: typeof addDays;
        hour: typeof addHours;
        minute: typeof addMinutes;
        second: typeof addSeconds;
    };
    /**
     * Provides methods to calculate past dates in UTC by subtracting a specified amount of time.
     */
    static past: {
        year: typeof removeYears;
        month: typeof removeMonths;
        day: typeof removeDays;
        hour: typeof removeHours;
        minute: typeof removeMinutes;
        second: typeof removeSeconds;
    };
}