dayjs-tz-helper/dist/index.d.ts

Day.js 時區輔助套件，提供安全解析時區日期字串與時間戳轉換功能 (Day.js timezone helper for safe timezone date string parsing and timestamp conversion)

/// <reference types="dayjs/plugin/timezone.d.ts" />
/// <reference types="dayjs/plugin/utc.d.ts" />

import dayjs from 'dayjs';
import { ConfigType } from 'dayjs';

/**
 * 偵測結尾是否為不安全的時區偏移日期字串
 * Detect if the string ends with an unsafe timezone offset date string
 *
 * 偵測結尾是否為 `.000Z`、`Z`、`+00:00` 等格式
 * Detect if the string ends with `.000Z`, `Z`, `+00:00`, etc.
 *
 * @param {string} date - 日期字串 / Date string
 * @returns {boolean} 是否為不安全的偏移日期字串 / Whether it is an unsafe offset date string
 */
export declare function _isUnsafeOffsetDateString(date: string): boolean;
/**
 * 偵測是否為 UTC 或 GMT 日期字串
 * Detect if it is a UTC or GMT date string
 *
 * @param {string} date - 日期字串 / Date string
 * @returns {boolean} 是否為 UTC/GMT 日期字串 / Whether it is a UTC/GMT date string
 */
export declare function _isUnsafeUTCDateString(date: string): boolean;
/**
 * 時區類型 - 支援 IANA 時區資料庫中的時區名稱
 * Timezone type - supports timezone names from IANA database
 *
 * Day.js 透過 Internationalization API 支援時區，無需在程式碼中包含額外的時區資料。
 * Day.js supports timezone via the Internationalization API, no extra timezone data needed in code bundle.
 *
 * @see https://day.js.org/docs/en/timezone/timezone
 * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 */
export type ITimezone = string | "GMT" | "Asia/Taipei" | "Asia/Tokyo" | "America/New_York";
/**
 * tzDayjsSafeParse 選項介面
 * tzDayjsSafeParse options interface
 */
export interface IOptionsTzDayjsSafeParse {
	/**
	 * 時區設定
	 * Timezone setting
	 *
	 * Day.js 透過 Internationalization API 支援時區，無需在程式碼中包含額外的時區資料。
	 * Day.js supports timezone via the Internationalization API, no extra timezone data needed in code bundle.
	 *
	 * @see https://day.js.org/docs/en/timezone/timezone
	 * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
	 */
	timezone?: ITimezone;
	/**
	 * 最小有效時間戳
	 * Minimum valid timestamp
	 *
	 * 若設為 `true` 或 `0`，代表 `1970-01-01T00:00:00.000Z`
	 * If set to `true` or `0`, it represents `1970-01-01T00:00:00.000Z`
	 *
	 * 僅在輸入為數字時生效
	 * Only works when the input is a number
	 */
	minValidTimestamp?: number | boolean;
	/**
	 * 是否將輸入時間戳視為 Unix 時間戳（秒）
	 * Whether to use input timestamp as Unix Timestamp (seconds)
	 *
	 * 相當於 `dayjs.unix(1318781876.721)` 或 `dayjs(timestamp * 1000)`
	 * Equivalent to `dayjs.unix(1318781876.721)` or `dayjs(timestamp * 1000)`
	 *
	 * 僅在輸入為數字時生效
	 * Only works when the input is a number
	 *
	 * @see https://day.js.org/docs/en/parse/unix-timestamp
	 */
	isUnixTimestampSeconds?: boolean;
}
/**
 * 安全解析時區日期字串
 * Safely parse timezone date string
 *
 * 處理多種邊界情況，包括 UTC 偏移、浮點數字串、Unix 時間戳等
 * Handle various edge cases including UTC offset, float string, Unix timestamp, etc.
 *
 * @example
 * tzDayjsSafeParse('2023-03-31T04:00:00.000Z')
 * tzDayjsSafeParse('2023-03-31T12:00:00+08:00')
 * tzDayjsSafeParse('2023-03-31T04:00:00.800Z')
 * tzDayjsSafeParse('2023-03-31T04:00:00+00:00')
 * // => 2023-03-31T04:00:00Z
 * // => 1680235200
 * @example
 * tzDayjsSafeParse('Fri, 31 Mar 2023 04:00:00', 'GMT')
 *
 * @param {ConfigType} [dateOrMilliseconds] - 日期或毫秒時間戳 / Date or millisecond timestamp
 * @param {ITimezone | IOptionsTzDayjsSafeParse} [timezoneOrOptions] - 時區設定 / Timezone setting
 * @returns {dayjs.Dayjs} 解析後的 dayjs 物件 / Parsed dayjs object
 *
 * @see https://github.com/iamkun/dayjs/issues/2300
 * @see https://github.com/iamkun/dayjs/issues/2303
 * @see https://day.js.org/docs/en/timezone/timezone
 * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 */
export declare function tzDayjsSafeParse(dateOrMilliseconds?: dayjs.ConfigType, timezoneOrOptions?: ITimezone | IOptionsTzDayjsSafeParse): dayjs.Dayjs;
/**
 * 秒轉毫秒
 * Convert seconds to milliseconds
 *
 * @param {number} timestamp - Unix 時間戳（秒）/ Unix timestamp (seconds)
 * @returns {number} 毫秒時間戳 / Millisecond timestamp
 */
export declare function secondsToMilliseconds(timestamp: number): number;
/**
 * 毫秒轉秒
 * Convert milliseconds to seconds
 *
 * @param {number} timestamp - 毫秒時間戳 / Millisecond timestamp
 * @returns {number} Unix 時間戳（秒）/ Unix timestamp (seconds)
 */
export declare function millisecondsToSeconds(timestamp: number): number;

export {
	tzDayjsSafeParse as default,
};

export {};