vtils/date/index.d.ts

一个面向业务的 JavaScript/TypeScript 实用程序库。

/**
 * 日期时间工具库。基于 {@link https://date-fns.org/v2.14.0/docs/Getting-Started | date-fns}。
 *
 * @packageDocumentation
 */

import { enUS as enUSLocale } from 'date-fns/locale';
import { zhCN as zhCNLocale } from 'date-fns/locale';

/**
 * 增强版的 toDate，支持：
 * - 秒时间戳、毫秒时间戳；
 * - Date 实例；
 * - 符合 ISO 标准的时间字符串。
 *
 * @param value 要转换的值
 * @returns 返回转换后的 Date 实例
 */
export declare function anyToDate(value: string | number | Date): Date;

export { enUSLocale }

/**
 * 格式化日期。
 *
 * @public
 * @param date 要格式化的日期，支持 Date、秒或毫秒时间戳
 * @param renderer 渲染器
 * @returns 返回格式化后的日期
 * @example
 * ```typescript
 * formatDate(
 *   new Date(2020, 5 - 1, 20, 13, 14, 21),
 *   _ => `${_.yyyy}-${_.mm}-${_.dd} ${_.hh}:${_.ii}:${_.ss}`,
 * ) // => '2020-05-20 13:14:21'
 * ```
 */
export declare function formatDate(date: Date | number, renderer: FormatDateRenderer): string;

/**
 * 日期格式化占位符。
 *
 * @public
 */
export declare enum FormatDatePlaceholder {
    /**
     * 年：`44, 1, 1900, 2017`
     */
    y = "y",
    /**
     * 年：`0044, 0001, 1900, 2017`
     */
    yyyy = "yyyy",
    /**
     * 月：`1, 2, ..., 12`
     */
    m = "M",
    /**
     * 月：`01, 02, ..., 12`
     */
    mm = "MM",
    /**
     * 日：`1, 2, ..., 31`
     */
    d = "d",
    /**
     * 日：`01, 02, ..., 31`
     */
    dd = "dd",
    /**
     * 时：`0, 1, 2, ..., 23`
     */
    h = "H",
    /**
     * 时：`00, 01, 02, ..., 23`
     */
    hh = "HH",
    /**
     * 分：`0, 1, ..., 59`
     */
    i = "m",
    /**
     * 分：`00, 01, ..., 59`
     */
    ii = "mm",
    /**
     * 秒：`0, 1, ..., 59`
     */
    s = "s",
    /**
     * 秒：`00, 01, ..., 59`
     */
    ss = "ss"
}

/**
 * 日期格式化渲染器。
 *
 * @public
 * @param placeholders 占位符
 * @returns 返回渲染字符串
 */
export declare type FormatDateRenderer = ((placeholders: typeof FormatDatePlaceholder) => string) | string;

/**
 * 将时间转化为 `xxx前` 表示。
 *
 * @param date 时间
 */
export declare function formatDistanceAgo(date: number | Date): string;

/**
 * 将时间转化为 `xxx前/后` 表示。
 *
 * @param date 时间
 * @param baseDate 基准时间（默认当前时间）
 */
export declare function formatDistancePlus(date: Date, baseDate?: Date): string;

export declare function intervalToRestrictiveDuration(start: string | number | Date, end: string | number | Date, target?: IntervalToRestrictiveDurationTarget): IntervalToRestrictiveDurationResult;

export declare interface IntervalToRestrictiveDurationResult {
    years: number;
    months: number;
    days: number;
    hours: number;
    minutes: number;
    seconds: number;
    milliseconds: number;
}

export declare type IntervalToRestrictiveDurationTarget = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond';

/**
 * @deprecated use `import { ms } from 'vtils'` instead
 */
export declare const ms: typeof ms_2;

/**
 * 获取毫秒值。
 *
 * @param value 值
 * @param unit 单位
 * @param returnSeconds 是否返回秒值
 */
declare function ms_2(value: number, unit: MsUnit, returnSeconds?: boolean): number;

/**
 * 获取毫秒值。
 *
 * @param value 值
 * @param returnSeconds 是否返回秒值
 */
declare function ms_2(value: MsValue, returnSeconds?: boolean): number;

declare type MsNumberValue = number;

declare type MsStringValue = `${number}${MsUnit}`;

declare type MsUnit = 'y' | 'w' | 'd' | 'h' | 'm' | 's' | 'ms';

declare type MsValue = MsNumberValue | MsStringValue;

/**
 * 数字星期。
 *
 * @public
 */
export declare type NumeralDay = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;

/**
 * 数字星期转中文星期。`0` 和 `7` 都视为星期日。
 *
 * @public
 * @param day 数字的星期几
 * @returns 返回中文的星期几
 * @example
 * ```typescript
 * numeralDayToChineseDay(0) // => 日
 * numeralDayToChineseDay(1) // => 一
 * numeralDayToChineseDay(5) // => 五
 * numeralDayToChineseDay(7) // => 日
 * ```
 */
export declare function numeralDayToChineseDay(day: NumeralDay): string;

export { zhCNLocale }


export * from "date-fns/add";
export * from "date-fns/addBusinessDays";
export * from "date-fns/addDays";
export * from "date-fns/addHours";
export * from "date-fns/addISOWeekYears";
export * from "date-fns/addMilliseconds";
export * from "date-fns/addMinutes";
export * from "date-fns/addMonths";
export * from "date-fns/addQuarters";
export * from "date-fns/addSeconds";
export * from "date-fns/addWeeks";
export * from "date-fns/addYears";
export * from "date-fns/areIntervalsOverlapping";
export * from "date-fns/clamp";
export * from "date-fns/closestIndexTo";
export * from "date-fns/closestTo";
export * from "date-fns/compareAsc";
export * from "date-fns/compareDesc";
export * from "date-fns/constructFrom";
export * from "date-fns/daysToWeeks";
export * from "date-fns/differenceInBusinessDays";
export * from "date-fns/differenceInCalendarDays";
export * from "date-fns/differenceInCalendarISOWeekYears";
export * from "date-fns/differenceInCalendarISOWeeks";
export * from "date-fns/differenceInCalendarMonths";
export * from "date-fns/differenceInCalendarQuarters";
export * from "date-fns/differenceInCalendarWeeks";
export * from "date-fns/differenceInCalendarYears";
export * from "date-fns/differenceInDays";
export * from "date-fns/differenceInHours";
export * from "date-fns/differenceInISOWeekYears";
export * from "date-fns/differenceInMilliseconds";
export * from "date-fns/differenceInMinutes";
export * from "date-fns/differenceInMonths";
export * from "date-fns/differenceInQuarters";
export * from "date-fns/differenceInSeconds";
export * from "date-fns/differenceInWeeks";
export * from "date-fns/differenceInYears";
export * from "date-fns/eachDayOfInterval";
export * from "date-fns/eachHourOfInterval";
export * from "date-fns/eachMinuteOfInterval";
export * from "date-fns/eachMonthOfInterval";
export * from "date-fns/eachQuarterOfInterval";
export * from "date-fns/eachWeekOfInterval";
export * from "date-fns/eachWeekendOfInterval";
export * from "date-fns/eachWeekendOfMonth";
export * from "date-fns/eachWeekendOfYear";
export * from "date-fns/eachYearOfInterval";
export * from "date-fns/endOfDay";
export * from "date-fns/endOfDecade";
export * from "date-fns/endOfHour";
export * from "date-fns/endOfISOWeek";
export * from "date-fns/endOfISOWeekYear";
export * from "date-fns/endOfMinute";
export * from "date-fns/endOfMonth";
export * from "date-fns/endOfQuarter";
export * from "date-fns/endOfSecond";
export * from "date-fns/endOfToday";
export * from "date-fns/endOfTomorrow";
export * from "date-fns/endOfWeek";
export * from "date-fns/endOfYear";
export * from "date-fns/endOfYesterday";
export * from "date-fns/format";
export * from "date-fns/formatDistance";
export * from "date-fns/formatDistanceStrict";
export * from "date-fns/formatDistanceToNow";
export * from "date-fns/formatDistanceToNowStrict";
export * from "date-fns/formatDuration";
export * from "date-fns/formatISO";
export * from "date-fns/formatISO9075";
export * from "date-fns/formatISODuration";
export * from "date-fns/formatRFC3339";
export * from "date-fns/formatRFC7231";
export * from "date-fns/formatRelative";
export * from "date-fns/fromUnixTime";
export * from "date-fns/getDate";
export * from "date-fns/getDay";
export * from "date-fns/getDayOfYear";
export * from "date-fns/getDaysInMonth";
export * from "date-fns/getDaysInYear";
export * from "date-fns/getDecade";
export * from "date-fns/getDefaultOptions";
export * from "date-fns/getHours";
export * from "date-fns/getISODay";
export * from "date-fns/getISOWeek";
export * from "date-fns/getISOWeekYear";
export * from "date-fns/getISOWeeksInYear";
export * from "date-fns/getMilliseconds";
export * from "date-fns/getMinutes";
export * from "date-fns/getMonth";
export * from "date-fns/getOverlappingDaysInIntervals";
export * from "date-fns/getQuarter";
export * from "date-fns/getSeconds";
export * from "date-fns/getTime";
export * from "date-fns/getUnixTime";
export * from "date-fns/getWeek";
export * from "date-fns/getWeekOfMonth";
export * from "date-fns/getWeekYear";
export * from "date-fns/getWeeksInMonth";
export * from "date-fns/getYear";
export * from "date-fns/hoursToMilliseconds";
export * from "date-fns/hoursToMinutes";
export * from "date-fns/hoursToSeconds";
export * from "date-fns/interval";
export * from "date-fns/intervalToDuration";
export * from "date-fns/intlFormat";
export * from "date-fns/intlFormatDistance";
export * from "date-fns/isAfter";
export * from "date-fns/isBefore";
export * from "date-fns/isDate";
export * from "date-fns/isEqual";
export * from "date-fns/isExists";
export * from "date-fns/isFirstDayOfMonth";
export * from "date-fns/isFriday";
export * from "date-fns/isFuture";
export * from "date-fns/isLastDayOfMonth";
export * from "date-fns/isLeapYear";
export * from "date-fns/isMatch";
export * from "date-fns/isMonday";
export * from "date-fns/isPast";
export * from "date-fns/isSameDay";
export * from "date-fns/isSameHour";
export * from "date-fns/isSameISOWeek";
export * from "date-fns/isSameISOWeekYear";
export * from "date-fns/isSameMinute";
export * from "date-fns/isSameMonth";
export * from "date-fns/isSameQuarter";
export * from "date-fns/isSameSecond";
export * from "date-fns/isSameWeek";
export * from "date-fns/isSameYear";
export * from "date-fns/isSaturday";
export * from "date-fns/isSunday";
export * from "date-fns/isThisHour";
export * from "date-fns/isThisISOWeek";
export * from "date-fns/isThisMinute";
export * from "date-fns/isThisMonth";
export * from "date-fns/isThisQuarter";
export * from "date-fns/isThisSecond";
export * from "date-fns/isThisWeek";
export * from "date-fns/isThisYear";
export * from "date-fns/isThursday";
export * from "date-fns/isToday";
export * from "date-fns/isTomorrow";
export * from "date-fns/isTuesday";
export * from "date-fns/isValid";
export * from "date-fns/isWednesday";
export * from "date-fns/isWeekend";
export * from "date-fns/isWithinInterval";
export * from "date-fns/isYesterday";
export * from "date-fns/lastDayOfDecade";
export * from "date-fns/lastDayOfISOWeek";
export * from "date-fns/lastDayOfISOWeekYear";
export * from "date-fns/lastDayOfMonth";
export * from "date-fns/lastDayOfQuarter";
export * from "date-fns/lastDayOfWeek";
export * from "date-fns/lastDayOfYear";
export * from "date-fns/lightFormat";
export * from "date-fns/max";
export * from "date-fns/milliseconds";
export * from "date-fns/millisecondsToHours";
export * from "date-fns/millisecondsToMinutes";
export * from "date-fns/millisecondsToSeconds";
export * from "date-fns/min";
export * from "date-fns/minutesToHours";
export * from "date-fns/minutesToMilliseconds";
export * from "date-fns/minutesToSeconds";
export * from "date-fns/monthsToQuarters";
export * from "date-fns/monthsToYears";
export * from "date-fns/nextDay";
export * from "date-fns/nextFriday";
export * from "date-fns/nextMonday";
export * from "date-fns/nextSaturday";
export * from "date-fns/nextSunday";
export * from "date-fns/nextThursday";
export * from "date-fns/nextTuesday";
export * from "date-fns/nextWednesday";
export * from "date-fns/parse";
export * from "date-fns/parseISO";
export * from "date-fns/parseJSON";
export * from "date-fns/previousDay";
export * from "date-fns/previousFriday";
export * from "date-fns/previousMonday";
export * from "date-fns/previousSaturday";
export * from "date-fns/previousSunday";
export * from "date-fns/previousThursday";
export * from "date-fns/previousTuesday";
export * from "date-fns/previousWednesday";
export * from "date-fns/quartersToMonths";
export * from "date-fns/quartersToYears";
export * from "date-fns/roundToNearestMinutes";
export * from "date-fns/secondsToHours";
export * from "date-fns/secondsToMilliseconds";
export * from "date-fns/secondsToMinutes";
export * from "date-fns/set";
export * from "date-fns/setDate";
export * from "date-fns/setDay";
export * from "date-fns/setDayOfYear";
export * from "date-fns/setDefaultOptions";
export * from "date-fns/setHours";
export * from "date-fns/setISODay";
export * from "date-fns/setISOWeek";
export * from "date-fns/setISOWeekYear";
export * from "date-fns/setMilliseconds";
export * from "date-fns/setMinutes";
export * from "date-fns/setMonth";
export * from "date-fns/setQuarter";
export * from "date-fns/setSeconds";
export * from "date-fns/setWeek";
export * from "date-fns/setWeekYear";
export * from "date-fns/setYear";
export * from "date-fns/startOfDay";
export * from "date-fns/startOfDecade";
export * from "date-fns/startOfHour";
export * from "date-fns/startOfISOWeek";
export * from "date-fns/startOfISOWeekYear";
export * from "date-fns/startOfMinute";
export * from "date-fns/startOfMonth";
export * from "date-fns/startOfQuarter";
export * from "date-fns/startOfSecond";
export * from "date-fns/startOfToday";
export * from "date-fns/startOfTomorrow";
export * from "date-fns/startOfWeek";
export * from "date-fns/startOfWeekYear";
export * from "date-fns/startOfYear";
export * from "date-fns/startOfYesterday";
export * from "date-fns/sub";
export * from "date-fns/subBusinessDays";
export * from "date-fns/subDays";
export * from "date-fns/subHours";
export * from "date-fns/subISOWeekYears";
export * from "date-fns/subMilliseconds";
export * from "date-fns/subMinutes";
export * from "date-fns/subMonths";
export * from "date-fns/subQuarters";
export * from "date-fns/subSeconds";
export * from "date-fns/subWeeks";
export * from "date-fns/subYears";
export * from "date-fns/toDate";
export * from "date-fns/transpose";
export * from "date-fns/weeksToDays";
export * from "date-fns/yearsToDays";
export * from "date-fns/yearsToMonths";
export * from "date-fns/yearsToQuarters";

export { }