@cloudcome/utils-core 1.19.0 → 1.20.0

package/dist/date.cjs

@@ -1,223 +1,1030 @@
-"use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const _const = require("./const.cjs");
-const core = require("./core.cjs");
-const number = require("./string2.cjs");
-const type = require("./type.cjs");
-const dateOfStartMap = [
-  ["s", (d) => d.setMilliseconds(0)],
-  ["m", (d) => d.setSeconds(0)],
-  ["h", (d) => d.setMinutes(0)],
-  ["D", (d) => d.setHours(0)],
-  ["W", (d) => d.setDate(d.getDate() - (d.getDay() + 6) % 7)],
-  ["M", (d) => d.setDate(1)],
-  ["Y", (d) => d.setMonth(0)]
+const require_type = require("./type.cjs");
+const require_string = require("./string2.cjs");
+//#region src/date/const.ts
+/**
+* 一秒的毫秒数
+*/
+var DATE_SECOND_MS = 1e3;
+/**
+* 一分钟的毫秒数
+*/
+var DATE_MINUTE_MS = 60 * DATE_SECOND_MS;
+/**
+* 一小时的毫秒数
+*/
+var DATE_HOUR_MS = 60 * DATE_MINUTE_MS;
+/**
+* 一天的毫秒数
+*/
+var DATE_DAY_MS = 24 * DATE_HOUR_MS;
+/**
+* 一个月（30天）的毫秒数
+*/
+var DATE_MONTH_MS = 30 * DATE_DAY_MS;
+/**
+* 一年（365天）的毫秒数
+*/
+var DATE_YEAR_MS = 365 * DATE_DAY_MS;
+//#endregion
+//#region src/date/timezone.ts
+/**
+* 时区偏移量毫秒常量（1分钟 = 60 * 1000 毫秒）
+*/
+var TIMEZONE_OFFSET_MS = 60 * 1e3;
+/**
+* 时区日期类，用于处理不同时区的日期时间
+*/
+var TimezoneDate = class TimezoneDate {
+	/**
+	* 内部时间戳
+	*/
+	#timestamp;
+	/**
+	* 目标时区的日期对象
+	*/
+	#targetDate;
+	/**
+	* UTC 日期对象
+	*/
+	#utcDate;
+	/**
+	* 本地时区偏移量（分钟）
+	*/
+	#localTimezoneOffset = TimezoneDate.getTimezoneOffset();
+	/**
+	* 本地时区偏移量（毫秒）
+	*/
+	#localTimezoneOffsetMS = this.#localTimezoneOffset * TIMEZONE_OFFSET_MS;
+	/**
+	* 目标时区偏移量（分钟）
+	*/
+	#targetTimezoneOffset = 0;
+	/**
+	* 目标时区偏移量（毫秒）
+	*/
+	#targetTimezoneOffsetMS = 0;
+	/**
+	* 构造函数选项
+	*/
+	#options;
+	/**
+	* 构造一个 TimezoneDate 实例
+	* @param options - 配置选项
+	*/
+	constructor(options) {
+		this.#options = (options instanceof TimezoneDate ? {
+			timestamp: options.getTime(),
+			utcOffset: options.getUTCOffset()
+		} : options) || {};
+		const { utcOffset, timestamp, value } = this.#options;
+		this.#targetTimezoneOffset = require_type.isNumber(utcOffset) ? TimezoneDate.getTimezoneOffset(utcOffset) : this.#localTimezoneOffset;
+		this.#targetTimezoneOffsetMS = this.#targetTimezoneOffset * TIMEZONE_OFFSET_MS;
+		if (Array.isArray(value) && value.length > 0) {
+			const [fullYear, month, day, hours, minutes, seconds, milliseconds] = value;
+			const timestamp = Date.UTC(fullYear ?? 0, month ?? 0, day ?? 1, hours ?? 0, minutes ?? 0, seconds ?? 0, milliseconds ?? 0);
+			this.#timestamp = timestamp + this.#targetTimezoneOffsetMS;
+		} else this.#timestamp = timestamp || Date.now();
+		this.#targetDate = new Date(this.#timestamp + this.#localTimezoneOffsetMS - this.#targetTimezoneOffsetMS);
+		this.#utcDate = new Date(this.#timestamp + this.#localTimezoneOffsetMS);
+	}
+	/**
+	* 更新内部时间戳
+	*/
+	#updateTimestamp() {
+		this.#timestamp = this.#targetDate.getTime() + this.#targetTimezoneOffsetMS - this.#localTimezoneOffsetMS;
+		this.#utcDate = new Date(this.#timestamp + this.#localTimezoneOffsetMS);
+	}
+	/**
+	* 获取时区偏移量（分钟）
+	* @returns 时区偏移量
+	*/
+	getTimezoneOffset() {
+		return this.#targetTimezoneOffset;
+	}
+	/**
+	* 获取时区偏移量（UTC）
+	* @returns 时区序号
+	*/
+	getUTCOffset() {
+		return TimezoneDate.getUTCOffset(this.#targetTimezoneOffset);
+	}
+	/**
+	* 获取年份
+	* @returns 年份
+	*/
+	getFullYear() {
+		return this.#targetDate.getFullYear();
+	}
+	/**
+	* 获取月份
+	* @returns 月份 (0-11)
+	*/
+	getMonth() {
+		return this.#targetDate.getMonth();
+	}
+	/**
+	* 获取日期
+	* @returns 日期 (1-31)
+	*/
+	getDate() {
+		return this.#targetDate.getDate();
+	}
+	/**
+	* 获取小时
+	* @returns 小时 (0-23)
+	*/
+	getHours() {
+		return this.#targetDate.getHours();
+	}
+	/**
+	* 获取分钟
+	* @returns 分钟 (0-59)
+	*/
+	getMinutes() {
+		return this.#targetDate.getMinutes();
+	}
+	/**
+	* 获取秒数
+	* @returns 秒数 (0-59)
+	*/
+	getSeconds() {
+		return this.#targetDate.getSeconds();
+	}
+	/**
+	* 获取毫秒
+	* @returns 毫秒 (0-999)
+	*/
+	getMilliseconds() {
+		return this.#targetDate.getMilliseconds();
+	}
+	/**
+	* 设置年份
+	* @param year - 年份
+	* @param month - 月份
+	* @param date - 日期
+	* @returns 时间戳
+	*/
+	setFullYear(year, month, date) {
+		this.#targetDate.setFullYear(year);
+		this.#updateTimestamp();
+		if (require_type.isNumber(month)) this.setMonth(month);
+		if (require_type.isNumber(date)) this.setDate(date);
+		return this.getTime();
+	}
+	/**
+	* 设置月份
+	* @param month - 月份
+	* @param date - 日期
+	* @returns 时间戳
+	*/
+	setMonth(month, date) {
+		this.#targetDate.setMonth(month);
+		this.#updateTimestamp();
+		if (require_type.isNumber(date)) this.setDate(date);
+		return this.getTime();
+	}
+	/**
+	* 设置日期
+	* @param date - 日期
+	* @returns 时间戳
+	*/
+	setDate(date) {
+		this.#targetDate.setDate(date);
+		this.#updateTimestamp();
+		return this.getTime();
+	}
+	/**
+	* 设置小时
+	* @param hours - 小时
+	* @param minutes - 分钟
+	* @param seconds - 秒数
+	* @param milliseconds - 毫秒
+	* @returns 时间戳
+	*/
+	setHours(hours, minutes, seconds, milliseconds) {
+		this.#targetDate.setHours(hours);
+		this.#updateTimestamp();
+		if (require_type.isNumber(minutes)) this.setMinutes(minutes);
+		if (require_type.isNumber(seconds)) this.setSeconds(seconds);
+		if (require_type.isNumber(milliseconds)) this.setMilliseconds(milliseconds);
+		return this.getTime();
+	}
+	/**
+	* 设置分钟
+	* @param minutes - 分钟
+	* @param seconds - 秒数
+	* @param milliseconds - 毫秒
+	* @returns 时间戳
+	*/
+	setMinutes(minutes, seconds, milliseconds) {
+		this.#targetDate.setMinutes(minutes);
+		this.#updateTimestamp();
+		if (require_type.isNumber(seconds)) this.setSeconds(seconds);
+		if (require_type.isNumber(milliseconds)) this.setMilliseconds(milliseconds);
+		return this.getTime();
+	}
+	/**
+	* 设置秒数
+	* @param seconds - 秒数
+	* @param milliseconds - 毫秒
+	* @returns 时间戳
+	*/
+	setSeconds(seconds, milliseconds) {
+		this.#targetDate.setSeconds(seconds);
+		this.#updateTimestamp();
+		if (require_type.isNumber(milliseconds)) this.setMilliseconds(milliseconds);
+		return this.getTime();
+	}
+	/**
+	* 设置毫秒
+	* @param milliseconds - 毫秒
+	* @returns 时间戳
+	*/
+	setMilliseconds(milliseconds) {
+		this.#targetDate.setMilliseconds(milliseconds);
+		this.#updateTimestamp();
+		return this.getTime();
+	}
+	/**
+	* 获取时间戳
+	* @returns 时间戳
+	*/
+	getTime() {
+		return this.#timestamp;
+	}
+	/**
+	* 获取星期几
+	* @returns 星期几 (0-6, 0表示周日)
+	*/
+	getDay() {
+		return this.#targetDate.getDay();
+	}
+	/**
+	* 转换为 ISO 格式的字符串
+	* @returns ISO 格式的时间字符串
+	*/
+	toISOString() {
+		return dateFormat(this.#utcDate, "YYYY-MM-DDTHH:mm:ss.SSSZ");
+	}
+	/**
+	* 转换为指定时区的 TimezoneDate 对象
+	* @param td - 需要转换的日期对象
+	* @param offset - 目标时区分钟偏移量，默认为当前时区
+	* @returns 返回一个 TimezoneDate 对象
+	* @example
+	* ```js
+	* // 转换为 UTC 时间
+	* const utc0Td = TimezoneDate.changeUtcOffset(new TimezoneDate(), 0);
+	*
+	* // 转换为东八区时间
+	* const utc8Td = TimezoneDate.changeUtcOffset(new TimezoneDate(), 8);
+	* ```
+	*/
+	static changeUtcOffset(td, utcOffset) {
+		return new TimezoneDate({
+			utcOffset,
+			timestamp: td.getTime()
+		});
+	}
+	/**
+	* 获取时区分钟偏移量
+	* @param utcOffset - 默认使用当前时区
+	* @returns 时区分钟偏移量
+	*/
+	static getTimezoneOffset(utcOffset) {
+		return require_type.isNumber(utcOffset) ? utcOffset * -60 : (/* @__PURE__ */ new Date()).getTimezoneOffset();
+	}
+	/**
+	* 获取时区序号
+	* @param timezoneOffset - 默认使用当前时区分钟偏移量
+	* @returns 时区序号
+	*/
+	static getUTCOffset(timezoneOffset = TimezoneDate.getTimezoneOffset()) {
+		return timezoneOffset / -60;
+	}
+};
+//#endregion
+//#region src/date/core.ts
+/**
+* 判断一个值是否为有效的日期对象
+* @param unknown - 需要判断的值
+* @returns 如果值是有效的日期对象则返回 true，否则返回 false
+* @example
+* ```typescript
+* isValidDate(new Date()); // true
+* isValidDate('2023-01-01'); // false
+* isValidDate(NaN); // false
+* ```
+*/
+function isValidDate(unknown) {
+	return unknown instanceof Date && !Number.isNaN(unknown.getTime()) || unknown instanceof TimezoneDate && !Number.isNaN(unknown.getTime());
+}
+function _guessDateSeparator(value) {
+	if (!require_type.isString(value)) return;
+	const value2 = value.replace(/-/g, "/");
+	return new Date(value2);
+}
+function _guessDateTimezone(value) {
+	if (!require_type.isString(value)) return;
+	const re = /([+-])(\d\d)(\d\d)$/;
+	const matches = re.exec(value);
+	if (!matches) return;
+	const value2 = value.replace(re, "Z");
+	const d = new Date(value2);
+	if (!isValidDate(d)) return;
+	const [, flag, hours, minutes] = matches;
+	const hours2 = Number.parseInt(hours, 10);
+	const minutes2 = Number.parseInt(minutes, 10);
+	const offset = (a, b) => flag === "+" ? a - b : a + b;
+	d.setHours(offset(d.getHours(), hours2));
+	d.setMinutes(offset(d.getMinutes(), minutes2));
+	return d;
+}
+/**
+* 解析为Date对象
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 解析后的 Date 对象
+* @throws {SyntaxError} 如果无法解析为有效的日期对象，则抛出错误
+* @example
+* ```typescript
+* dateParse('2023-01-01'); // Date对象
+* dateParse(1672531200000); // Date对象
+* dateParse(new Date()); // Date对象
+* dateParse('invalid date'); // 抛出 SyntaxError
+* ```
+*/
+function dateParse(dateValue) {
+	const d1 = require_type.isDate(dateValue) ? new Date(dateValue) : dateValue instanceof TimezoneDate ? new TimezoneDate(dateValue) : new Date(dateValue);
+	if (isValidDate(d1)) return d1;
+	const d2 = _guessDateSeparator(dateValue);
+	if (isValidDate(d2)) return d2;
+	const d3 = _guessDateTimezone(dateValue);
+	if (isValidDate(d3)) return d3;
+	throw new SyntaxError(`${dateValue.toString()} 不是一个合法的日期值`);
+}
+function _pad(num, len = 2) {
+	return `${num}`.padStart(len, "0");
+}
+var rules = [
+	[/Y{4}/gi, (date) => date.getFullYear()],
+	[/Y{2}/gi, (date) => date.getFullYear() % 100],
+	[/M{2}/g, (date) => _pad(date.getMonth() + 1)],
+	[/M{1}/g, (date) => date.getMonth() + 1],
+	[/D{2}/gi, (date) => _pad(date.getDate())],
+	[/D{1}/gi, (date) => date.getDate()],
+	[/H{2}/g, (date) => _pad(date.getHours())],
+	[/H{1}/g, (date) => date.getHours()],
+	[/h{2}/g, (date) => {
+		const h = date.getHours();
+		return _pad(h === 0 ? 12 : h > 12 ? h - 12 : h);
+	}],
+	[/h{1}/g, (date) => {
+		const h = date.getHours();
+		return h === 0 ? 12 : h > 12 ? h - 12 : h;
+	}],
+	[/m{2}/g, (date) => _pad(date.getMinutes())],
+	[/m{1}/g, (date) => date.getMinutes()],
+	[/s{2}/g, (date) => _pad(date.getSeconds())],
+	[/s{1}/g, (date) => date.getSeconds()],
+	[/S{3}/g, (date) => _pad(date.getMilliseconds(), 3)],
+	[/S{2}/g, (date) => _pad(date.getMilliseconds(), 2)],
+	[/S{1}/g, (date) => date.getMilliseconds()]
+];
+/**
+* 格式化为日期字符串(带自定义格式化模板)
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @param format - 模板，默认是 'YYYY-MM-DD HH:mm:ss'，模板字符：
+* - YYYY：年
+* - yyyy: 年
+* - MM：月
+* - DD：日
+* - dd: 日
+* - HH：时（24 小时制）
+* - hh：时（12 小时制）
+* - mm：分
+* - ss：秒
+* - SSS：毫秒
+* @returns 格式化后的日期字符串
+* @example
+* ```typescript
+* dateFormat(new Date(), 'YYYY-MM-DD'); // '2023-01-01'
+* dateFormat(1672531200000, 'YYYY/MM/DD HH:mm:ss'); // '2023/01/01 00:00:00'
+* dateFormat('2023-01-01', 'YYYY年MM月DD日'); // '2023年01月01日'
+* ```
+*/
+function dateFormat(dateValue, format = "YYYY-MM-DD HH:mm:ss") {
+	const date = dateParse(dateValue);
+	let result = format;
+	for (const rule of rules) result = result.replace(rule[0], String(rule[1](date)));
+	return result;
+}
+//#endregion
+//#region src/date/start-end.ts
+/**
+* 各时间单位起始时间映射表
+* 包含将日期设置到单位起始时间的函数
+*/
+var dateOfStartMap = [
+	["s", (d) => d.setMilliseconds(0)],
+	["m", (d) => d.setSeconds(0)],
+	["h", (d) => d.setMinutes(0)],
+	["D", (d) => d.setHours(0)],
+	["W", (d) => d.setDate(d.getDate() - (d.getDay() + 6) % 7)],
+	["M", (d) => d.setDate(1)],
+	["Y", (d) => d.setMonth(0)]
 ];
+/**
+* 返回指定时间单位的起始时间
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @param symbol - 时间单位符号，可选值为 'Y'（年）、'M'（月）、'W'（周）、'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, 'W'); // 2023-06-12 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, symbol = "D") {
-  const date = core.dateParse(dateValue);
-  for (const [sym, fn] of dateOfStartMap) {
-    fn(date);
-    if (symbol === sym) break;
-  }
-  return date;
+	const date = dateParse(dateValue);
+	for (const [sym, fn] of dateOfStartMap) {
+		fn(date);
+		if (symbol === sym) break;
+	}
+	return date;
 }
+/**
+* 返回秒级起始时间
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回秒级起始时间，毫秒部分为 0
+*/
 function dateStartInSecond(dateValue) {
-  return _dateStart(dateValue, "s");
+	return _dateStart(dateValue, "s");
 }
+/**
+* 返回分钟级起始时间
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回分钟级起始时间，秒和毫秒部分为 0
+*/
 function dateStartInMinute(dateValue) {
-  return _dateStart(dateValue, "m");
+	return _dateStart(dateValue, "m");
 }
+/**
+* 返回小时级起始时间
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回小时级起始时间，分钟、秒和毫秒部分为 0
+*/
 function dateStartInHour(dateValue) {
-  return _dateStart(dateValue, "h");
+	return _dateStart(dateValue, "h");
 }
+/**
+* 返回天级起始时间
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回天级起始时间，小时、分钟、秒和毫秒部分为 0
+*/
 function dateStartInDay(dateValue) {
-  return _dateStart(dateValue, "D");
+	return _dateStart(dateValue, "D");
 }
+/**
+* 返回周级起始时间（周一 00:00:00.000）
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回当周周一的起始时间，时间部分为 0
+*/
 function dateStartInWeek(dateValue) {
-  return _dateStart(dateValue, "W");
+	return _dateStart(dateValue, "W");
 }
+/**
+* 返回月级起始时间
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回月级起始时间，日期为当月第一天，时间部分为 0
+*/
 function dateStartInMonth(dateValue) {
-  return _dateStart(dateValue, "M");
+	return _dateStart(dateValue, "M");
 }
+/**
+* 返回年级起始时间
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回年级起始时间，月份为 1 月，日期为 1 日，时间部分为 0
+*/
 function dateStartInYear(dateValue) {
-  return _dateStart(dateValue, "Y");
-}
-const dateOfEndMap = [
-  ["s", (d) => d.setMilliseconds(999)],
-  ["m", (d) => d.setSeconds(59)],
-  ["h", (d) => d.setMinutes(59)],
-  ["D", (d) => d.setHours(23)],
-  ["W", (d) => d.setDate(d.getDate() + (7 - d.getDay()) % 7)],
-  [
-    "M",
-    (d) => {
-      const d2 = core.dateParse(d);
-      d2.setMonth(d.getMonth() + 1);
-      d2.setDate(0);
-      d.setDate(d2.getDate());
-    }
-  ],
-  [
-    "Y",
-    (d) => {
-      d.setMonth(11);
-      d.setDate(31);
-    }
-  ]
+	return _dateStart(dateValue, "Y");
+}
+/**
+* 各时间单位结束时间映射表
+* 包含将日期设置到单位结束时间的函数
+*/
+var dateOfEndMap = [
+	["s", (d) => d.setMilliseconds(999)],
+	["m", (d) => d.setSeconds(59)],
+	["h", (d) => d.setMinutes(59)],
+	["D", (d) => d.setHours(23)],
+	["W", (d) => d.setDate(d.getDate() + (7 - d.getDay()) % 7)],
+	["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'（月）、'W'（周）、'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, 'W'); // 2023-06-18 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, symbol = "D") {
-  const date = core.dateParse(dateValue);
-  for (const [sym, fn] of dateOfEndMap) {
-    fn(date);
-    if (symbol === sym) break;
-  }
-  return date;
+	const date = dateParse(dateValue);
+	for (const [sym, fn] of dateOfEndMap) {
+		fn(date);
+		if (symbol === sym) break;
+	}
+	return date;
 }
+/**
+* 返回秒级结束时间
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回秒级结束时间，毫秒部分为 999
+*/
 function dateEndInSecond(dateValue) {
-  return _dateEnd(dateValue, "s");
+	return _dateEnd(dateValue, "s");
 }
+/**
+* 返回分钟级结束时间
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回分钟级结束时间，秒为 59，毫秒为 999
+*/
 function dateEndInMinute(dateValue) {
-  return _dateEnd(dateValue, "m");
+	return _dateEnd(dateValue, "m");
 }
+/**
+* 返回小时级结束时间
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回小时级结束时间，分钟为 59，秒为 59，毫秒为 999
+*/
 function dateEndInHour(dateValue) {
-  return _dateEnd(dateValue, "h");
+	return _dateEnd(dateValue, "h");
 }
+/**
+* 返回天级结束时间
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回天级结束时间，小时为 23，分钟为 59，秒为 59，毫秒为 999
+*/
 function dateEndInDay(dateValue) {
-  return _dateEnd(dateValue, "D");
+	return _dateEnd(dateValue, "D");
 }
+/**
+* 返回周级结束时间（周日 23:59:59.999）
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回当周周日的结束时间，时间为 23:59:59.999
+*/
 function dateEndInWeek(dateValue) {
-  return _dateEnd(dateValue, "W");
+	return _dateEnd(dateValue, "W");
 }
+/**
+* 返回月级结束时间
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回月级结束时间，日期为当月最后一天，时间为 23:59:59.999
+*/
 function dateEndInMonth(dateValue) {
-  return _dateEnd(dateValue, "M");
+	return _dateEnd(dateValue, "M");
 }
+/**
+* 返回年级结束时间
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回年级结束时间，月份为 12 月，日期为 31 日，时间为 23:59:59.999
+*/
 function dateEndInYear(dateValue) {
-  return _dateEnd(dateValue, "Y");
+	return _dateEnd(dateValue, "Y");
 }
+//#endregion
+//#region src/date/days.ts
+/**
+* 计算指定日期所在年或月的天数
+* @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, unit) {
-  const d = core.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()) / _const.DATE_DAY_MS);
+	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 (闰年)
+* ```
+*/
 function dateDaysInMonth(dateValue) {
-  return _dateDays(dateValue, "M");
+	return _dateDays(dateValue, "M");
 }
+/**
+* 计算指定日期所在年份的天数
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @returns 返回指定日期所在年份的天数
+* @example
+* ```typescript
+* dateDaysInYear(new Date('2023-02-15')); // 365
+* dateDaysInYear(new Date('2024-02-15')); // 366 (闰年)
+* ```
+*/
 function dateDaysInYear(dateValue) {
-  return _dateDays(dateValue, "Y");
-}
-const defaultDiffTemplates = [
-  [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日"]
-];
-function dateRelative(dateValue, refDateValue, templates) {
-  const now = Date.now();
-  const refDateValueFinal = type.isArray(refDateValue) ? now : refDateValue || now;
-  const templatesFinal = type.isArray(templates) ? templates : type.isArray(refDateValue) ? refDateValue : defaultDiffTemplates;
-  const d1 = core.dateParse(dateValue);
-  const d2 = core.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 * 1e3;
-    const maxFinal = max * 1e3;
-    if (absDiff < maxFinal) {
-      const template = isAgo ? agoTemplate : featureTemplate || agoTemplate;
-      const length = unitFinal === 0 ? 0 : Math.max(Math.floor(absDiff / unitFinal), 1);
-      relative = unitFinal === 0 ? core.dateFormat(dateValue, template) : number.stringFormat(template, { n: length });
-      break;
-    }
-  }
-  return relative;
+	return _dateDays(dateValue, "Y");
 }
+//#endregion
+//#region src/date/is.ts
+/**
+* 判断给定的年份是否为闰年
+* @param year - 需要判断的年份
+* @returns 如果年份是闰年则返回 true，否则返回 false
+* @example
+* ```typescript
+* isLeapYear(2020); // true
+* isLeapYear(2021); // false
+* isLeapYear(2000); // true
+* isLeapYear(1900); // false
+* ```
+*/
 function isLeapYear(year) {
-  if (year % 4 !== 0) return false;
-  if (year % 100 !== 0) return true;
-  if (year % 400 !== 0) return false;
-  return true;
+	if (year % 4 !== 0) return false;
+	if (year % 100 !== 0) return true;
+	if (year % 400 !== 0) return false;
+	return true;
 }
+/**
+* 比较两个日期在指定精度下是否相同
+* @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, date2, sameSymbol = "D") {
-  const defines = [
-    ["Y", (d) => d.getFullYear()],
-    ["M", (d) => d.getMonth()],
-    ["D", (d) => d.getDate()],
-    ["h", (d) => d.getHours()],
-    ["m", (d) => d.getMinutes()],
-    ["s", (d) => d.getSeconds()],
-    ["S", (d) => d.getMilliseconds()]
-  ];
-  const d1 = core.dateParse(date1);
-  const d2 = core.dateParse(date2);
-  for (const [sym, fn] of defines) {
-    if (fn(d1) !== fn(d2)) {
-      return false;
-    }
-    if (sym === sameSymbol) break;
-  }
-  return true;
+	const defines = [
+		["Y", (d) => d.getFullYear()],
+		["M", (d) => d.getMonth()],
+		["D", (d) => d.getDate()],
+		["h", (d) => d.getHours()],
+		["m", (d) => d.getMinutes()],
+		["s", (d) => d.getSeconds()],
+		["S", (d) => d.getMilliseconds()]
+	];
+	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
+* ```
+*/
 function isSameDateInYear(date1, date2) {
-  return _isSameDateIn(date1, date2, "Y");
+	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
+* ```
+*/
 function isSameDateInMonth(date1, date2) {
-  return _isSameDateIn(date1, date2, "M");
+	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
+* ```
+*/
 function isSameDateInDay(date1, date2) {
-  return _isSameDateIn(date1, date2, "D");
+	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
+* ```
+*/
 function isSameDateInHour(date1, date2) {
-  return _isSameDateIn(date1, date2, "h");
+	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
+* ```
+*/
 function isSameDateInMinute(date1, date2) {
-  return _isSameDateIn(date1, date2, "m");
+	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
+* ```
+*/
 function isSameDateInSecond(date1, date2) {
-  return _isSameDateIn(date1, date2, "s");
-}
-var EWeekStart = /* @__PURE__ */ ((EWeekStart2) => {
-  EWeekStart2[EWeekStart2["sunday"] = 0] = "sunday";
-  EWeekStart2[EWeekStart2["monday"] = 1] = "monday";
-  EWeekStart2[EWeekStart2["tuesday"] = 2] = "tuesday";
-  EWeekStart2[EWeekStart2["wednesday"] = 3] = "wednesday";
-  EWeekStart2[EWeekStart2["thursday"] = 4] = "thursday";
-  EWeekStart2[EWeekStart2["friday"] = 5] = "friday";
-  EWeekStart2[EWeekStart2["saturday"] = 6] = "saturday";
-  return EWeekStart2;
-})(EWeekStart || {});
-function _dateWeeks(dateValue, type2, weekStart = 0) {
-  const date = core.dateParse(dateValue);
-  const year = date.getFullYear();
-  const month = date.getMonth();
-  const firstDate = type2 === "Y" ? new Date(year, 0, 1) : new Date(year, month, 1);
-  const firstWeek = firstDate.getDay();
-  const days = Math.ceil((date.getTime() - firstDate.getTime()) / _const.DATE_DAY_MS);
-  return Math.ceil((firstWeek + days - weekStart) / 7);
+	return _isSameDateIn(date1, date2, "s");
 }
+//#endregion
+//#region src/date/relative.ts
+var defaultDiffTemplates = [
+	[
+		0,
+		10,
+		"刚刚"
+	],
+	[
+		1,
+		60,
+		"{n} 秒前",
+		"{n} 秒后"
+	],
+	[
+		60,
+		3600,
+		"{n} 分钟前",
+		"{n} 分钟后"
+	],
+	[
+		3600,
+		3600 * 24,
+		"{n} 小时前",
+		"{n} 小时后"
+	],
+	[
+		0,
+		3600 * 24 * 2,
+		"昨天",
+		"明天"
+	],
+	[
+		0,
+		3600 * 24 * 3,
+		"前天",
+		"后天"
+	],
+	[
+		3600 * 24,
+		3600 * 24 * 30,
+		"{n} 天前",
+		"{n} 天后"
+	],
+	[
+		0,
+		Number.POSITIVE_INFINITY,
+		"YYYY年MM月DD日"
+	]
+];
+function dateRelative(dateValue, refDateValue, templates) {
+	const now = Date.now();
+	const refDateValueFinal = require_type.isArray(refDateValue) ? now : refDateValue || now;
+	const templatesFinal = require_type.isArray(templates) ? templates : require_type.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 * 1e3;
+		if (absDiff < max * 1e3) {
+			const template = isAgo ? agoTemplate : featureTemplate || agoTemplate;
+			const length = unitFinal === 0 ? 0 : Math.max(Math.floor(absDiff / unitFinal), 1);
+			relative = unitFinal === 0 ? dateFormat(dateValue, template) : require_string.stringFormat(template, { n: length });
+			break;
+		}
+	}
+	return relative;
+}
+//#endregion
+//#region src/date/weeks.ts
+var EWeekStart = /* @__PURE__ */ function(EWeekStart) {
+	/**
+	* 周日作为一周的起始日
+	*/
+	EWeekStart[EWeekStart["sunday"] = 0] = "sunday";
+	/**
+	* 周一作为一周的起始日
+	*/
+	EWeekStart[EWeekStart["monday"] = 1] = "monday";
+	/**
+	* 周二作为一周的起始日
+	*/
+	EWeekStart[EWeekStart["tuesday"] = 2] = "tuesday";
+	/**
+	* 周三作为一周的起始日
+	*/
+	EWeekStart[EWeekStart["wednesday"] = 3] = "wednesday";
+	/**
+	* 周四作为一周的起始日
+	*/
+	EWeekStart[EWeekStart["thursday"] = 4] = "thursday";
+	/**
+	* 周五作为一周的起始日
+	*/
+	EWeekStart[EWeekStart["friday"] = 5] = "friday";
+	/**
+	* 周六作为一周的起始日
+	*/
+	EWeekStart[EWeekStart["saturday"] = 6] = "saturday";
+	return EWeekStart;
+}({});
+/**
+* 计算指定日期所在年份或月份的周数
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @param type - 计算范围，'Y' 表示年份，'M' 表示月份
+* @param weekStart - 一周的起始日，默认为 0（周日）
+* @returns 返回指定日期所在年份或月份的周数
+* @example
+* ```typescript
+* const date = new Date(2023, 0, 1); // 2023-01-01
+* _dateWeeks(date, 'Y'); // 1 (计算年份的周数)
+* _dateWeeks(date, 'M'); // 1 (计算月份的周数)
+* _dateWeeks(date, 'Y', 1); // 1 (周一作为一周的起始日，计算年份的周数)
+* ```
+*/
+function _dateWeeks(dateValue, type, weekStart = 0) {
+	const date = dateParse(dateValue);
+	const year = date.getFullYear();
+	const month = date.getMonth();
+	const firstDate = type === "Y" ? new Date(year, 0, 1) : new Date(year, month, 1);
+	const firstWeek = firstDate.getDay();
+	const days = Math.ceil((date.getTime() - firstDate.getTime()) / DATE_DAY_MS);
+	return Math.ceil((firstWeek + days - weekStart) / 7);
+}
+/**
+* 计算指定日期所在年份的周数
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @param weekStart - 一周的起始日，默认为 0（周日）
+* @returns 返回指定日期所在年份的周数
+* @example
+* ```typescript
+* const date = new Date(2023, 0, 1); // 2023-01-01
+* weeksOfYear(date); // 1
+* weeksOfYear(date, 1); // 1 (周一作为一周的起始日)
+* ```
+*/
 function weeksOfYear(dateValue, weekStart = 0) {
-  return _dateWeeks(dateValue, "Y", weekStart);
+	return _dateWeeks(dateValue, "Y", weekStart);
 }
+/**
+* 计算指定日期所在月份的周数
+* @param dateValue - 可以是数值、字符串或 Date 对象
+* @param weekStart - 一周的起始日，默认为 0（周日）
+* @returns 返回指定日期所在月份的周数
+* @example
+* ```typescript
+* const date = new Date(2023, 0, 1); // 2023-01-01
+* weeksOfMonth(date); // 1
+* weeksOfMonth(date, 1); // 1 (周一作为一周的起始日)
+* ```
+*/
 function weeksOfMonth(dateValue, weekStart = 0) {
-  return _dateWeeks(dateValue, "M", weekStart);
-}
-exports.DATE_DAY_MS = _const.DATE_DAY_MS;
-exports.DATE_HOUR_MS = _const.DATE_HOUR_MS;
-exports.DATE_MINUTE_MS = _const.DATE_MINUTE_MS;
-exports.DATE_MONTH_MS = _const.DATE_MONTH_MS;
-exports.DATE_SECOND_MS = _const.DATE_SECOND_MS;
-exports.DATE_YEAR_MS = _const.DATE_YEAR_MS;
-exports.TimezoneDate = core.TimezoneDate;
-exports.dateFormat = core.dateFormat;
-exports.dateParse = core.dateParse;
-exports.isValidDate = core.isValidDate;
+	return _dateWeeks(dateValue, "M", weekStart);
+}
+//#endregion
+exports.DATE_DAY_MS = DATE_DAY_MS;
+exports.DATE_HOUR_MS = DATE_HOUR_MS;
+exports.DATE_MINUTE_MS = DATE_MINUTE_MS;
+exports.DATE_MONTH_MS = DATE_MONTH_MS;
+exports.DATE_SECOND_MS = DATE_SECOND_MS;
+exports.DATE_YEAR_MS = DATE_YEAR_MS;
 exports.EWeekStart = EWeekStart;
+exports.TimezoneDate = TimezoneDate;
 exports._dateWeeks = _dateWeeks;
 exports.dateDaysInMonth = dateDaysInMonth;
 exports.dateDaysInYear = dateDaysInYear;
@@ -228,6 +1035,8 @@ exports.dateEndInMonth = dateEndInMonth;
 exports.dateEndInSecond = dateEndInSecond;
 exports.dateEndInWeek = dateEndInWeek;
 exports.dateEndInYear = dateEndInYear;
+exports.dateFormat = dateFormat;
+exports.dateParse = dateParse;
 exports.dateRelative = dateRelative;
 exports.dateStartInDay = dateStartInDay;
 exports.dateStartInHour = dateStartInHour;
@@ -243,6 +1052,8 @@ exports.isSameDateInMinute = isSameDateInMinute;
 exports.isSameDateInMonth = isSameDateInMonth;
 exports.isSameDateInSecond = isSameDateInSecond;
 exports.isSameDateInYear = isSameDateInYear;
+exports.isValidDate = isValidDate;
 exports.weeksOfMonth = weeksOfMonth;
 exports.weeksOfYear = weeksOfYear;
-//# sourceMappingURL=date.cjs.map
+
+//# sourceMappingURL=date.cjs.map