@das-fed/upf-utils 6.4.0-dev.243 → 6.4.0-dev.245

package/common-tools/timezone-format/get-iana-data/dayjs-timezone-iana-plugin.d.ts

@@ -0,0 +1,72 @@
+export interface TimeZoneRule {
+    u: number[];
+    o: number[];
+}
+export interface IanaDb {
+    [zone: string]: TimeZoneRule;
+}
+/** `dayjs.extend` 时无需传 IANA 数据；须先 `await plugin.preloadFromApi()`（默认请求内置路径并带 accessToken） */
+export type DayjsTimezoneIanaOption = undefined;
+export interface PackedIanaData {
+    version?: string;
+    zones: string[];
+    links?: string[];
+}
+export type ParsePackedIanaResponse = (json: unknown) => PackedIanaData;
+/** 默认 `fetch` 请求的第二个参数；自定义 `fetchJson` 时也会传入 */
+export type IanaFetchJson = (url: string, init?: RequestInit) => Promise<unknown>;
+export interface PreloadDayjsIanaOptions {
+    /** 默认 `/api/admin/basic-application/sys-info/v1/license/time-zone-packed-data`；未传则请求内置地址 */
+    url?: string;
+    /**
+     * 设置 `Authorization`；未传时从 `localStorage.getItem('accessToken')` 生成 `Bearer <token>`。
+     * 传 `''` 表示不附加鉴权头。
+     */
+    authorization?: string;
+    /** 额外请求头；与 `authorization` 合并，同名时以 `authorization` 为准 */
+    headers?: Record<string, string>;
+    /** 默认使用全局 `fetch`；Node 等环境可传入实现 */
+    fetchJson?: IanaFetchJson;
+    /** 接口外层包裹时在此解析为 `{ version?, zones, links? }` */
+    parseResponse?: ParsePackedIanaResponse;
+}
+type DayjsLike = {
+    utc: () => DayjsLike;
+    valueOf: () => number;
+    utcOffset: (offset: number, keepLocalTime?: boolean) => DayjsLike;
+    tz: (zone?: string, keepLocalTime?: boolean) => DayjsLike;
+};
+type DayjsClassLike = {
+    prototype: {
+        tz?: (zone?: string) => DayjsLike;
+    };
+};
+type DayjsFactoryLike = {
+    (value?: unknown, format?: string): DayjsLike;
+    utc?: (value?: unknown, format?: string) => DayjsLike;
+    tz?: DayjsTimezoneFactoryLike;
+};
+type DayjsTimezoneFactoryLike = {
+    (value?: unknown, timezoneOrFormat?: string, timezone?: string): DayjsLike;
+    setDefault?: (zone: string) => void;
+    guess?: () => string;
+};
+type DayjsPlugin = (option: DayjsTimezoneIanaOption | undefined, dayjsClass: DayjsClassLike, dayjsFactory: DayjsFactoryLike) => void;
+export type DayjsTimezoneIanaPlugin = DayjsPlugin & {
+    /** 请求接口并解析 packed 数据，写入内部缓存；须在 `dayjs.extend(plugin)` 之前 await 完成 */
+    preloadFromApi: (options?: PreloadDayjsIanaOptions) => Promise<PackedIanaData>;
+    /** 直接写入已获取的 packed 数据，避免业务层为了复用接口结果再发起请求 */
+    preloadFromData: (packedData: PackedIanaData) => PackedIanaData;
+    /** 返回最近一次写入的 packed 数据，供公共工具同步已知时区集合 */
+    getCachedPackedData: () => PackedIanaData | null;
+    /** 清空内部缓存（测试或切换数据源时使用） */
+    clearIanaCache: () => void;
+};
+export declare function assertPackedIanaData(json: unknown): PackedIanaData;
+export declare function preloadDayjsIanaFromData(packedData: PackedIanaData): PackedIanaData;
+export declare function getCachedDayjsPackedIanaData(): PackedIanaData | null;
+export declare function preloadDayjsIanaFromApi(options?: PreloadDayjsIanaOptions): Promise<PackedIanaData>;
+export declare function clearDayjsIanaCache(): void;
+export declare function createIanaDbFromPackedData(packedData: PackedIanaData): IanaDb;
+declare const plugin: DayjsTimezoneIanaPlugin;
+export default plugin;

package/common-tools/timezone-format/get-iana-data/iana-api-fetch.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 内置 IANA packed 数据接口路径（与网关 / 前端 base 拼接）。
+ */
+export declare const TIME_ZONE_PACKED_DATA_URL: string;
+/**
+ * 从浏览器 localStorage 读取 accessToken（非浏览器或无此项时返回 null）。
+ */
+export declare function getAccessTokenFromLocalStorage(): string | null;
+/**
+ * 默认 Authorization：`Bearer <accessToken>`；若 token 已含 `Bearer ` 则原样使用。
+ */
+export declare function getDefaultIanaAuthorization(): string | undefined;
+/**
+ * 构造 IANA 接口请求的 fetch init（Authorization 与其它头）。
+ * - 未传 `authorization` 时，自动使用 `localStorage.getItem('accessToken')` 生成 `Authorization`。
+ * - 传入 `authorization: ''` 表示不附加 Authorization（用于测试等场景）。
+ */
+export declare function buildIanaFetchInit(options?: {
+    authorization?: string;
+    headers?: Record<string, string>;
+}): RequestInit | undefined;

package/common-tools/timezone-format/get-iana-data/moment-iana-loader.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 将接口返回的 packed IANA 数据（与 moment-timezone 数据格式一致）注册到当前 moment 实例上。
+ * 业务侧须先：`import moment from 'moment'; import 'moment-timezone';`，再传入同一个 `moment`。
+ */
+export interface PackedIanaTzData {
+    version?: string;
+    zones: string[];
+    links?: string[];
+}
+export interface MomentWithTimezone {
+    tz: {
+        load: (data: PackedIanaTzData) => void;
+    };
+}
+export declare function assertPackedIanaTzData(json: unknown): PackedIanaTzData;
+export declare function loadIanaData(moment: MomentWithTimezone, data: PackedIanaTzData): void;
+export type ParseIanaResponse = (json: unknown) => PackedIanaTzData;
+export type IanaMomentFetchJson = (url: string, init?: RequestInit) => Promise<unknown>;
+export interface LoadIanaFromApiOptions {
+    /** 设置请求头 `Authorization`（完整值，如 `Bearer <token>`） */
+    authorization?: string;
+    /** 额外请求头；与 `authorization` 合并，同名时以 `authorization` 为准 */
+    headers?: Record<string, string>;
+    /** 自定义请求，默认使用全局 fetch */
+    fetchJson?: IanaMomentFetchJson;
+    /** 当接口外层有包裹时，在此取出 { version, zones, links } */
+    parseResponse?: ParseIanaResponse;
+}
+export declare function loadIanaFromApi(moment: MomentWithTimezone, urlOrOptions?: string | LoadIanaFromApiOptions, maybeOptions?: LoadIanaFromApiOptions): Promise<PackedIanaTzData>;

package/common-tools/timezone-format/index.d.ts

@@ -1,6 +1,54 @@
 import { Dayjs } from 'dayjs';
+import { default as dayjsTimezoneIanaPlugin, PackedIanaData, PreloadDayjsIanaOptions } from './get-iana-data/dayjs-timezone-iana-plugin';
+import { loadIanaData as loadMomentIanaData, loadIanaFromApi as loadMomentIanaFromApi, LoadIanaFromApiOptions, MomentWithTimezone, PackedIanaTzData } from './get-iana-data/moment-iana-loader';
 
-type TimeValue = string | number | Date | Dayjs | null | undefined;
+export * from './get-iana-data';
+export { dayjsTimezoneIanaPlugin, loadMomentIanaData, loadMomentIanaFromApi };
+export type TimeValue = string | number | Date | Dayjs | null | undefined;
+export type TimeZoneFlag = number | string | null | undefined;
+export type TimeZoneDateLibrary = 'dayjs' | 'moment';
+export type TimeZoneInputMode = 'instant' | 'local';
+interface MomentFormatValue {
+    tz?: (timeZone: string) => MomentFormatValue;
+    format: (format?: string) => string;
+    isValid?: () => boolean;
+}
+export interface MomentTimezoneFormatInstance extends MomentWithTimezone {
+    (value?: unknown): MomentFormatValue;
+    tz: MomentWithTimezone['tz'] & {
+        (value?: unknown, timeZone?: string): MomentFormatValue;
+        guess?: () => string;
+        setDefault?: (zone: string) => void;
+    };
+}
+export interface TimeZoneOption {
+    /** IANA 时区标识，如 Asia/Shanghai。 */
+    timeZoneId: string;
+    /** 后端下发的本地化展示名。 */
+    tzShowName?: string;
+    /** 关联城市名，保留给后续业务自定义展示。 */
+    cities?: string[];
+    /** 1 表示存在夏令时规则，0 表示固定偏移。 */
+    dynamicOffsetFlag?: TimeZoneFlag;
+    /** 1 表示当前处于夏令时，0 表示当前非夏令时。 */
+    currentDstFlag?: TimeZoneFlag;
+    /** 标准 UTC 偏移量文本，如 +08:00。 */
+    baseUtcOffsetText?: string;
+    /** 当前实际 UTC 偏移量文本，包含夏令时偏移。 */
+    currentUtcOffsetText?: string;
+}
+export interface TimeZoneDisplayOption {
+    /** IANA 时区标识，作为下拉 value。 */
+    value: string;
+    /** 下拉展示文本。 */
+    label: string;
+    /** 主展示区使用的时区名称。 */
+    zoneName: string;
+    /** 是否存在夏令时规则。 */
+    hasDST: boolean;
+    /** 当前是否处于夏令时。 */
+    isDST: boolean;
+}
 export interface TimeZoneDisplayOptions {
     value?: TimeValue;
     locale?: string;
@@ -21,8 +69,64 @@ export interface TimeZoneDisplayResult {
     isDaylightSavingTime: boolean;
     daylightSavingLabel: string;
 }
+export interface FormatClientLocalDateTimeLineOptions {
+    showZoneLabel?: boolean;
+    zoneLabel?: string;
+    /** 是否存在夏令时规则；未传时回退本地规则判断。 */
+    hasDST?: boolean;
+    /** 当前是否处于夏令时；未传时回退本地规则判断。 */
+    isDST?: boolean;
+    standardTimeLabel?: string;
+    daylightSavingLabel?: string;
+    format?: string;
+}
+export interface FormatLocalDateTimeOptions {
+    /** 输出格式，默认 YYYY-MM-DD HH:mm:ss。 */
+    format?: string;
+    /** 目标 IANA 时区；为空时保持时间库本机格式化行为。 */
+    timeZone?: string | null;
+    /** 使用的时间库，默认 dayjs；c3 可传 moment。 */
+    dateLibrary?: TimeZoneDateLibrary;
+    /** moment 模式必须传当前应用同一个 moment-timezone 实例。 */
+    moment?: MomentTimezoneFormatInstance;
+    /** instant 表示转换真实时间点，local 表示把输入文本按目标时区本地时间解析。 */
+    inputMode?: TimeZoneInputMode;
+    /** 未传 timeZone 时是否读取 sessionStorage/客户端时区。默认 false，兼容旧 toLocalDate。 */
+    useClientTimeZone?: boolean;
+}
+export interface ApplyIanaTimeZoneOptions {
+    /** 指定默认时区，后续 dayjs.tz(value) 可直接使用。 */
+    defaultTimeZone?: string;
+}
+export interface LoadIanaTimeZoneOptions extends PreloadDayjsIanaOptions, ApplyIanaTimeZoneOptions {
+}
+export interface ApplyIanaTimeZoneResult {
+    data: PackedIanaData;
+    knownTimeZones: string[];
+}
+export interface LoadMomentIanaTimeZoneOptions extends LoadIanaFromApiOptions {
+    url?: string;
+}
+export declare const isKnownTimeZone: (timeZone?: string | null) => any;
+export declare const rebuildKnownTimeZoneIds: (data: Pick<PackedIanaData, "zones" | "links">) => any;
+export declare const getKnownTimeZoneIds: () => any;
+export declare const applyDayjsIanaTimeZoneData: (data: PackedIanaData, options?: ApplyIanaTimeZoneOptions) => Promise<ApplyIanaTimeZoneResult>;
+export declare const loadDayjsIanaTimeZoneData: (options?: LoadIanaTimeZoneOptions) => Promise<ApplyIanaTimeZoneResult>;
+export declare const applyMomentIanaTimeZoneData: (moment: MomentWithTimezone, data: PackedIanaTzData) => PackedIanaTzData;
+export declare const loadMomentIanaTimeZoneData: (moment: MomentWithTimezone, options?: LoadMomentIanaTimeZoneOptions) => unknown;
 export declare const getClientTimeZone: () => any;
+export declare const resolveTimeZone: (timeZone?: string | null) => any;
+export declare const setDefaultTimeZone: (timeZone?: string | null) => boolean;
 export declare const normalizeLocaleCode: (locale?: string, supportedLocales?: string[]) => any;
-export declare const isDaylightSavingTime: (timeZone?: string, value?: TimeValue) => boolean;
+export declare const getZoneUtcOffset: (value: TimeValue, timeZone?: string | null) => any;
+export declare const formatInTimeZone: (value?: TimeValue, timeZone?: string | null, format?: string) => any;
+export declare const formatLocalDateTime: (value?: TimeValue, options?: FormatLocalDateTimeOptions | string) => string;
+export declare const toLocalDate: (value?: TimeValue, format?: string, options?: Omit<FormatLocalDateTimeOptions, "format">) => string;
+export declare const formatTimeZoneOffsetLabel: (value?: TimeValue, timeZone?: string | null) => string;
+export declare const resolveUtcOffsetFallback: (option: Pick<TimeZoneOption, "timeZoneId" | "baseUtcOffsetText" | "currentUtcOffsetText">, referenceDate?: Date) => string;
+export declare const timeZoneHasDST: (timeZone?: string | null, value?: TimeValue) => boolean;
+export declare const timeZoneIsDST: (timeZone?: string | null, value?: TimeValue) => boolean;
+export declare const isDaylightSavingTime: (timeZone?: string | null, value?: TimeValue) => boolean;
+export declare const buildTimeZoneDisplayOptions: (options: TimeZoneOption[], referenceDate?: Date) => TimeZoneDisplayOption[];
+export declare const formatClientLocalDateTimeLine: (value: TimeValue, timeZone?: string | null, options?: FormatClientLocalDateTimeLineOptions) => any;
 export declare const getTimeZoneDisplayInfo: (options?: TimeZoneDisplayOptions) => TimeZoneDisplayResult;
-export {};