@cloudcome/utils-core 0.0.0 → 1.1.1

package/src/date/days.ts

@@ -0,0 +1,51 @@
+import { DATE_DAY_MS } from './const';
+import { type TDateValue, dateParse } from './core';
+import { dateEndInMonth, dateEndInYear, dateStartInMonth, dateStartInYear } from './start-end';
+
+/**
+ * 计算指定日期所在年或月的天数
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @param unit - 时间单位符号，可选值为 'Y'（年）、'M'（月），默认为 'M'
+ * @returns 返回指定日期所在年或月的天数
+ * @example
+ * ```typescript
+ * dateDays(new Date('2023-02-15')); // 28
+ * dateDays(new Date('2024-02-15')); // 29 (闰年)
+ * dateDays(new Date('2023-02-15'), 'Y'); // 365
+ * dateDays(new Date('2024-02-15'), 'Y'); // 366 (闰年)
+ * ```
+ */
+function _dateDays(dateValue: TDateValue, unit: 'Y' | 'M') {
+  const d = dateParse(dateValue);
+  const ds = unit === 'M' ? dateStartInMonth(d) : dateStartInYear(d);
+  const de = unit === 'M' ? dateEndInMonth(d) : dateEndInYear(d);
+  return Math.ceil((de.getTime() - ds.getTime()) / DATE_DAY_MS);
+}
+
+/**
+ * 计算指定日期所在月份的天数
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @returns 返回指定日期所在月份的天数
+ * @example
+ * ```typescript
+ * dateDaysInMonth(new Date('2023-02-15')); // 28
+ * dateDaysInMonth(new Date('2024-02-15')); // 29 (闰年)
+ * ```
+ */
+export function dateDaysInMonth(dateValue: TDateValue) {
+  return _dateDays(dateValue, 'M');
+}
+
+/**
+ * 计算指定日期所在年份的天数
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @returns 返回指定日期所在年份的天数
+ * @example
+ * ```typescript
+ * dateDaysInYear(new Date('2023-02-15')); // 365
+ * dateDaysInYear(new Date('2024-02-15')); // 366 (闰年)
+ * ```
+ */
+export function dateDaysInYear(dateValue: TDateValue) {
+  return _dateDays(dateValue, 'Y');
+}

package/src/date/is.ts

@@ -0,0 +1,186 @@
+import { type TDateLike, type TDateValue, dateParse } from './core';
+
+/**
+ * 判断给定的年份是否为闰年
+ * @param year - 需要判断的年份
+ * @returns 如果年份是闰年则返回 true，否则返回 false
+ * @example
+ * ```typescript
+ * isLeapYear(2020); // true
+ * isLeapYear(2021); // false
+ * isLeapYear(2000); // true
+ * isLeapYear(1900); // false
+ * ```
+ */
+export function isLeapYear(year: number): boolean {
+  if (year % 4 !== 0) return false;
+  if (year % 100 !== 0) return true;
+  if (year % 400 !== 0) return false;
+  return true;
+}
+
+/**
+ * 日期比较精度枚举类型
+ * - Y = 年
+ * - M = 月
+ * - D = 天
+ * - h = 小时
+ * - m = 分钟
+ * - s = 秒
+ * - S = 毫秒
+ */
+type _DateSameSymbol = 'Y' | 'M' | 'D' | 'h' | 'm' | 's' | 'S';
+
+/**
+ * 比较两个日期在指定精度下是否相同
+ * @param date1 - 第一个日期，可以是数值、字符串或 Date 对象
+ * @param date2 - 第二个日期，可以是数值、字符串或 Date 对象
+ * @param sameSymbol - 比较精度，默认为 'D'（天，即年月日天都相同）
+ * @returns 如果两个日期在指定精度下相同则返回 true，否则返回 false
+ * @example
+ * ```typescript
+ * const date1 = new Date(2023, 5, 15, 12, 30, 45, 500);
+ * const date2 = new Date(2023, 5, 15, 13, 30, 45, 500);
+ *
+ * // 比较年份
+ * isSameDate(date1, date2, 'Y'); // true
+ *
+ * // 比较月份（年份也要相同）
+ * isSameDate(date1, date2, 'M'); // true
+ *
+ * // 比较日期（默认，年份、月份也要相同）
+ * isSameDate(date1, date2); // true
+ *
+ * // 比较小时（年、月、日也要相同）
+ * isSameDate(date1, date2, 'h'); // false
+ *
+ * // 比较分钟（年、月、日、小时也要相同）
+ * isSameDate(date1, date2, 'm'); // false
+ *
+ * // 比较秒（年、月、日、小时、分钟也要相同）
+ * isSameDate(date1, date2, 's'); // false
+ *
+ * // 比较毫秒（年、月、日、小时、分钟、秒数也要相同）
+ * isSameDate(date1, date2, 'S'); // false
+ * ```
+ */
+function _isSameDateIn(date1: TDateValue, date2: TDateValue, sameSymbol: _DateSameSymbol = 'D') {
+  const defines = [
+    ['Y', (d: TDateLike) => d.getFullYear()],
+    ['M', (d: TDateLike) => d.getMonth()],
+    ['D', (d: TDateLike) => d.getDate()],
+    ['h', (d: TDateLike) => d.getHours()],
+    ['m', (d: TDateLike) => d.getMinutes()],
+    ['s', (d: TDateLike) => d.getSeconds()],
+    ['S', (d: TDateLike) => d.getMilliseconds()],
+  ] as const;
+
+  const d1 = dateParse(date1);
+  const d2 = dateParse(date2);
+
+  for (const [sym, fn] of defines) {
+    if (fn(d1) !== fn(d2)) {
+      return false;
+    }
+
+    if (sym === sameSymbol) break;
+  }
+
+  return true;
+}
+
+/**
+ * 比较两个日期的年份是否相同
+ * @param date1 - 第一个日期，可以是数值、字符串或 Date 对象
+ * @param date2 - 第二个日期，可以是数值、字符串或 Date 对象
+ * @returns 如果两个日期的年份相同则返回 true，否则返回 false
+ * @example
+ * ```typescript
+ * const date1 = new Date(2023, 5, 15);
+ * const date2 = new Date(2023, 6, 20);
+ * isSameDateInYear(date1, date2); // true
+ * ```
+ */
+export function isSameDateInYear(date1: TDateValue, date2: TDateValue) {
+  return _isSameDateIn(date1, date2, 'Y');
+}
+
+/**
+ * 比较两个日期的年份和月份是否相同
+ * @param date1 - 第一个日期，可以是数值、字符串或 Date 对象
+ * @param date2 - 第二个日期，可以是数值、字符串或 Date 对象
+ * @returns 如果两个日期的年份和月份相同则返回 true，否则返回 false
+ * @example
+ * ```typescript
+ * const date1 = new Date(2023, 5, 15);
+ * const date2 = new Date(2023, 5, 20);
+ * isSameDateInMonth(date1, date2); // true
+ * ```
+ */
+export function isSameDateInMonth(date1: TDateValue, date2: TDateValue) {
+  return _isSameDateIn(date1, date2, 'M');
+}
+
+/**
+ * 比较两个日期的年份、月份和天数是否相同
+ * @param date1 - 第一个日期，可以是数值、字符串或 Date 对象
+ * @param date2 - 第二个日期，可以是数值、字符串或 Date 对象
+ * @returns 如果两个日期的年份、月份和天数相同则返回 true，否则返回 false
+ * @example
+ * ```typescript
+ * const date1 = new Date(2023, 5, 15);
+ * const date2 = new Date(2023, 5, 15);
+ * isSameDateInDay(date1, date2); // true
+ * ```
+ */
+export function isSameDateInDay(date1: TDateValue, date2: TDateValue) {
+  return _isSameDateIn(date1, date2, 'D');
+}
+
+/**
+ * 比较两个日期的年份、月份、天数和小时是否相同
+ * @param date1 - 第一个日期，可以是数值、字符串或 Date 对象
+ * @param date2 - 第二个日期，可以是数值、字符串或 Date 对象
+ * @returns 如果两个日期的年份、月份、天数和小时相同则返回 true，否则返回 false
+ * @example
+ * ```typescript
+ * const date1 = new Date(2023, 5, 15, 12);
+ * const date2 = new Date(2023, 5, 15, 12);
+ * isSameDateInHour(date1, date2); // true
+ * ```
+ */
+export function isSameDateInHour(date1: TDateValue, date2: TDateValue) {
+  return _isSameDateIn(date1, date2, 'h');
+}
+
+/**
+ * 比较两个日期的年份、月份、天数、小时和分钟是否相同
+ * @param date1 - 第一个日期，可以是数值、字符串或 Date 对象
+ * @param date2 - 第二个日期，可以是数值、字符串或 Date 对象
+ * @returns 如果两个日期的年份、月份、天数、小时和分钟相同则返回 true，否则返回 false
+ * @example
+ * ```typescript
+ * const date1 = new Date(2023, 5, 15, 12, 30);
+ * const date2 = new Date(2023, 5, 15, 12, 30);
+ * isSameDateInMinute(date1, date2); // true
+ * ```
+ */
+export function isSameDateInMinute(date1: TDateValue, date2: TDateValue) {
+  return _isSameDateIn(date1, date2, 'm');
+}
+
+/**
+ * 比较两个日期的年份、月份、天数、小时、分钟和秒数是否相同
+ * @param date1 - 第一个日期，可以是数值、字符串或 Date 对象
+ * @param date2 - 第二个日期，可以是数值、字符串或 Date 对象
+ * @returns 如果两个日期的年份、月份、天数、小时、分钟和秒数相同则返回 true，否则返回 false
+ * @example
+ * ```typescript
+ * const date1 = new Date(2023, 5, 15, 12, 30, 45);
+ * const date2 = new Date(2023, 5, 15, 12, 30, 45);
+ * isSameDateInSecond(date1, date2); // true
+ * ```
+ */
+export function isSameDateInSecond(date1: TDateValue, date2: TDateValue) {
+  return _isSameDateIn(date1, date2, 's');
+}

package/src/date/relative.ts

@@ -0,0 +1,92 @@
+import { stringFormat } from '@/string';
+import { isArray } from '@/type';
+import { type TDateValue, dateFormat, dateParse } from './core';
+
+export type TDateRelativeTemplate = [
+  number /*单位时间差，为 0 表示不计算单位差值，单位秒*/,
+  number /*最大时间差，单位：秒*/,
+  string /*过去模板字符串，%d 表述单位差值*/,
+  string? /*将来模板字符串，%d 表述单位差值，可选*/,
+];
+export type TDateRelativeTemplates = TDateRelativeTemplate[];
+
+const defaultDiffTemplates: TDateRelativeTemplates = [
+  [0, 10, '刚刚'],
+  [1, 60, '{n} 秒前', '{n} 秒后'],
+  [60, 60 * 60, '{n} 分钟前', '{n} 分钟后'],
+  [60 * 60, 60 * 60 * 24, '{n} 小时前', '{n} 小时后'],
+  [0, 60 * 60 * 24 * 2, '昨天', '明天'],
+  [0, 60 * 60 * 24 * 3, '前天', '后天'],
+  [60 * 60 * 24, 60 * 60 * 24 * 30, '{n} 天前', '{n} 天后'],
+  [0, Number.POSITIVE_INFINITY, 'YYYY年MM月DD日'],
+];
+
+/**
+ * 相对时间
+ * @param {TDateValue} dateValue 比较的时间
+ * @param {TDateValue} [refDateValue] 相对的时间，默认为当前
+ * @param {TDateRelativeTemplates} [templates] 模板
+ * @returns {string} 格式化后的相对时间字符串
+ * @example
+ * ```typescript
+ * // 默认模板
+ * dateRelative(new Date('2023-01-01')); // '刚刚'
+ * dateRelative(new Date('2023-01-01'), new Date('2023-01-02')); // '昨天'
+ * dateRelative(new Date('2023-01-01'), new Date('2023-01-04')); // '3 天前'
+ * dateRelative(new Date('2023-01-01'), new Date('2023-02-01')); // '2023年01月01日'
+ * ```
+ * @example
+ * ```typescript
+ * // 自定义模板
+ * const templates: DateRelativeTemplates = [
+ *   [0, 10, '刚刚'],
+ *   [1, 60, '{n} 秒前', '{n} 秒后'],
+ *   [60, 60 * 60, '{n} 分钟前', '{n} 分钟后'],
+ *   [60 * 60, 60 * 60 * 24, '{n} 小时前', '{n} 小时后'],
+ *   [0, 60 * 60 * 24 * 2, '昨天', '明天'],
+ *   [0, 60 * 60 * 24 * 3, '前天', '后天'],
+ *   [60 * 60 * 24, 60 * 60 * 24 * 30, '{n} 天前', '{n} 天后'],
+ *   [0, Number.POSITIVE_INFINITY, 'YYYY年MM月DD日'],
+ * ];
+ * dateRelative(new Date('2023-01-01'), new Date('2023-01-02'), templates); // '昨天'
+ * dateRelative(new Date('2023-01-01'), new Date('2023-01-04'), templates); // '3 天前'
+ * dateRelative(new Date('2023-01-01'), new Date('2023-02-01'), templates); // '2023年01月01日'
+ * ```
+ */
+export function dateRelative(
+  dateValue: TDateValue,
+  refDateValue: TDateValue,
+  templates: TDateRelativeTemplates,
+): string;
+export function dateRelative(dateValue: TDateValue, refDateValue: TDateValue): string;
+export function dateRelative(dateValue: TDateValue, templates: TDateRelativeTemplates): string;
+export function dateRelative(dateValue: TDateValue): string;
+export function dateRelative(
+  dateValue: TDateValue,
+  refDateValue?: TDateValue | TDateRelativeTemplates,
+  templates?: TDateRelativeTemplates,
+): string {
+  const now = Date.now();
+  const refDateValueFinal = isArray(refDateValue) ? now : refDateValue || now;
+  const templatesFinal = isArray(templates) ? templates : isArray(refDateValue) ? refDateValue : defaultDiffTemplates;
+  const d1 = dateParse(dateValue);
+  const d2 = dateParse(refDateValueFinal);
+  const diff = d1.getTime() - d2.getTime();
+  const isAgo = diff < 0;
+  const absDiff = Math.abs(diff);
+  let relative = '';
+
+  for (const [base, max, agoTemplate, featureTemplate] of templatesFinal) {
+    const unitFinal = base * 1000;
+    const maxFinal = max * 1000;
+
+    if (absDiff < maxFinal) {
+      const template = isAgo ? agoTemplate : featureTemplate || agoTemplate;
+      const length = unitFinal === 0 ? 0 : Math.max(Math.floor(absDiff / unitFinal), 1);
+      relative = unitFinal === 0 ? dateFormat(dateValue, template) : stringFormat(template, { n: length });
+      break;
+    }
+  }
+
+  return relative;
+}

package/src/date/start-end.ts

@@ -0,0 +1,246 @@
+import { type TDateLike, type TDateValue, dateParse } from './core';
+
+/**
+ * 时间单位符号枚举
+ * - 'Y': 年
+ * - 'M': 月
+ * - 'D': 天
+ * - 'W': 周
+ * - 'h': 小时
+ * - 'm': 分钟
+ * - 's': 秒
+ */
+type _TDateOfSymbol = 'Y' | 'M' | 'D' | 'W' | 'h' | 'm' | 's';
+
+/**
+ * 各时间单位起始时间映射表
+ * 包含将日期设置到单位起始时间的函数
+ */
+const dateOfStartMap: [_TDateOfSymbol, (date: TDateLike) => unknown][] = [
+  ['s', (d) => d.setMilliseconds(0)],
+  ['m', (d) => d.setSeconds(0)],
+  ['h', (d) => d.setMinutes(0)],
+  ['D', (d) => d.setHours(0)],
+  ['W', (d) => d.setHours(0)],
+  ['M', (d) => d.setDate(1)],
+  ['Y', (d) => d.setMonth(0)],
+];
+
+/**
+ * 返回指定时间单位的起始时间
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @param symbol - 时间单位符号，可选值为 'Y'（年）、'M'（月）、'D'（天）、'h'（小时）、'm'（分钟）、's'（秒），默认为 'D'
+ * @returns 返回指定时间单位的起始时间
+ * @example
+ * ```typescript
+ * const date = new Date(2023, 5, 15, 12, 30, 45, 500); // 2023-06-15 12:30:45.500
+ *
+ * // 返回秒级起始时间
+ * dateOfStart(date, 's'); // 2023-06-15 12:30:45.000
+ *
+ * // 返回分钟级起始时间
+ * dateOfStart(date, 'm'); // 2023-06-15 12:30:00.000
+ *
+ * // 返回小时级起始时间
+ * dateOfStart(date, 'h'); // 2023-06-15 12:00:00.000
+ *
+ * // 返回天级起始时间
+ * dateOfStart(date, 'D'); // 2023-06-15 00:00:00.000
+ *
+ * // 返回月级起始时间
+ * dateOfStart(date, 'M'); // 2023-06-01 00:00:00.000
+ *
+ * // 返回年级起始时间
+ * dateOfStart(date, 'Y'); // 2023-01-01 00:00:00.000
+ *
+ * // 默认返回天级起始时间
+ * dateOfStart(date); // 2023-06-15 00:00:00.000
+ * ```
+ */
+function _dateStart(dateValue: TDateValue, symbol: _TDateOfSymbol = 'D') {
+  const date = dateParse(dateValue);
+
+  for (const [sym, fn] of dateOfStartMap) {
+    fn(date);
+    if (symbol === sym) break;
+  }
+
+  return date;
+}
+
+/**
+ * 返回秒级起始时间
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @returns 返回秒级起始时间，毫秒部分为 0
+ */
+export function dateStartInSecond(dateValue: TDateValue) {
+  return _dateStart(dateValue, 's');
+}
+
+/**
+ * 返回分钟级起始时间
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @returns 返回分钟级起始时间，秒和毫秒部分为 0
+ */
+export function dateStartInMinute(dateValue: TDateValue) {
+  return _dateStart(dateValue, 'm');
+}
+
+/**
+ * 返回小时级起始时间
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @returns 返回小时级起始时间，分钟、秒和毫秒部分为 0
+ */
+export function dateStartInHour(dateValue: TDateValue) {
+  return _dateStart(dateValue, 'h');
+}
+
+/**
+ * 返回天级起始时间
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @returns 返回天级起始时间，小时、分钟、秒和毫秒部分为 0
+ */
+export function dateStartInDay(dateValue: TDateValue) {
+  return _dateStart(dateValue, 'D');
+}
+
+/**
+ * 返回月级起始时间
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @returns 返回月级起始时间，日期为当月第一天，时间部分为 0
+ */
+export function dateStartInMonth(dateValue: TDateValue) {
+  return _dateStart(dateValue, 'M');
+}
+
+/**
+ * 返回年级起始时间
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @returns 返回年级起始时间，月份为 1 月，日期为 1 日，时间部分为 0
+ */
+export function dateStartInYear(dateValue: TDateValue) {
+  return _dateStart(dateValue, 'Y');
+}
+
+/**
+ * 各时间单位结束时间映射表
+ * 包含将日期设置到单位结束时间的函数
+ */
+const dateOfEndMap: [_TDateOfSymbol, (date: TDateLike) => unknown][] = [
+  ['s', (d) => d.setMilliseconds(999)],
+  ['m', (d) => d.setSeconds(59)],
+  ['h', (d) => d.setMinutes(59)],
+  ['D', (d) => d.setHours(23)],
+  [
+    'M',
+    (d) => {
+      const d2 = dateParse(d);
+      d2.setMonth(d.getMonth() + 1);
+      d2.setDate(0);
+      d.setDate(d2.getDate());
+    },
+  ],
+  [
+    'Y',
+    (d) => {
+      d.setMonth(11);
+      d.setDate(31);
+    },
+  ],
+];
+
+/**
+ * 返回指定时间单位的结束时间
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @param symbol - 时间单位符号，可选值为 'Y'（年）、'M'（月）、'D'（天）、'h'（小时）、'm'（分钟）、's'（秒），默认为 'D'
+ * @returns 返回指定时间单位的结束时间
+ * @example
+ * ```typescript
+ * const date = new Date(2023, 5, 15, 12, 30, 45, 500); // 2023-06-15 12:30:45.500
+ *
+ * // 返回秒级结束时间
+ * dateOfEnd(date, 's'); // 2023-06-15 12:30:45.999
+ *
+ * // 返回分钟级结束时间
+ * dateOfEnd(date, 'm'); // 2023-06-15 12:30:59.999
+ *
+ * // 返回小时级结束时间
+ * dateOfEnd(date, 'h'); // 2023-06-15 12:59:59.999
+ *
+ * // 返回天级结束时间
+ * dateOfEnd(date, 'D'); // 2023-06-15 23:59:59.999
+ *
+ * // 返回月级结束时间
+ * dateOfEnd(date, 'M'); // 2023-06-30 23:59:59.999
+ *
+ * // 返回年级结束时间
+ * dateOfEnd(date, 'Y'); // 2023-12-31 23:59:59.999
+ *
+ * // 默认返回天级结束时间
+ * dateOfEnd(date); // 2023-06-15 23:59:59.999
+ * ```
+ */
+function _dateEnd(dateValue: TDateValue, symbol: _TDateOfSymbol = 'D') {
+  const date = dateParse(dateValue);
+
+  for (const [sym, fn] of dateOfEndMap) {
+    fn(date);
+    if (symbol === sym) break;
+  }
+
+  return date;
+}
+
+/**
+ * 返回秒级结束时间
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @returns 返回秒级结束时间，毫秒部分为 999
+ */
+export function dateEndInSecond(dateValue: TDateValue) {
+  return _dateEnd(dateValue, 's');
+}
+
+/**
+ * 返回分钟级结束时间
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @returns 返回分钟级结束时间，秒为 59，毫秒为 999
+ */
+export function dateEndInMinute(dateValue: TDateValue) {
+  return _dateEnd(dateValue, 'm');
+}
+
+/**
+ * 返回小时级结束时间
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @returns 返回小时级结束时间，分钟为 59，秒为 59，毫秒为 999
+ */
+export function dateEndInHour(dateValue: TDateValue) {
+  return _dateEnd(dateValue, 'h');
+}
+
+/**
+ * 返回天级结束时间
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @returns 返回天级结束时间，小时为 23，分钟为 59，秒为 59，毫秒为 999
+ */
+export function dateEndInDay(dateValue: TDateValue) {
+  return _dateEnd(dateValue, 'D');
+}
+
+/**
+ * 返回月级结束时间
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @returns 返回月级结束时间，日期为当月最后一天，时间为 23:59:59.999
+ */
+export function dateEndInMonth(dateValue: TDateValue) {
+  return _dateEnd(dateValue, 'M');
+}
+
+/**
+ * 返回年级结束时间
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @returns 返回年级结束时间，月份为 12 月，日期为 31 日，时间为 23:59:59.999
+ */
+export function dateEndInYear(dateValue: TDateValue) {
+  return _dateEnd(dateValue, 'Y');
+}