sculp-js 1.19.0 → 1.19.2

package/dist/cjs/array.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/async.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/base64.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/clipboard.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/cloneDeep.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/cookie.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/date.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
@@ -115,19 +115,25 @@ function dateToEnd(value) {
   return dateParse(d.getTime() - 1);
 }
 /**
- * 格式化为日期对象(带自定义格式化模板)
+ * 格式化为日期对象 (带自定义格式化模板)
  * @param {Date} value - 可以是数值、字符串或 Date 对象
  * @param {string} [format] - 模板，默认是 YYYY-MM-DD HH:mm:ss，模板字符：
- * - YYYY：年
- * - yyyy: 年
- * - MM：月
- * - DD：日
- * - dd: 日
- * - HH：时（24 小时制）
- * - mm：分
- * - ss：秒
- * - SSS：毫秒
- * - ww: 周
+ * - YYYY/yyyy：年
+ * - MM：月（补零）
+ * - M：月（不补零）
+ * - DD/dd：日（补零）
+ * - D/d：日（不补零）
+ * - HH：时（24 小时制，补零）
+ * - H：时（24 小时制，不补零）
+ * - mm：分（补零）
+ * - m：分（不补零）
+ * - ss：秒（补零）
+ * - s：秒（不补零）
+ * - SSS：毫秒（3 位）
+ * - SS：毫秒（2 位）
+ * - S：毫秒（1 位）
+ * - ww：中文完整星期（如：周日）
+ * - w：中文星期（如：周日）
  * @returns {string}  格式化后的日期字符串
  */
 function formatDate(value, format = 'YYYY-MM-DD HH:mm:ss') {
@@ -156,61 +162,113 @@ function formatDate(value, format = 'YYYY-MM-DD HH:mm:ss') {
   return fmt;
 }
 /**
- * 计算向前或向后N天的具体日期
- * @param {DateValue} originDate - 参考日期
- * @param {number} n - 正数：向后推算；负数：向前推算
- * @param {string} sep - 日期格式的分隔符
- * @returns {string} 计算后的目标日期
+ * 调整日期（增加或减少特定时间单位）
+ * @param {DateValue} originDate - 参考日期，可以是 Date 对象、时间戳或日期字符串
+ * @param {CalculateDateOptions} options - 配置项，支持多种时间单位
+ * @returns {string | Date} 计算后的日期/日期时间字符串或 Date 对象
+ * @example
+ * // 基础用法（向后 2 天）
+ * adjustDate('2024-01-01', { days: 2 }) // '2024-01-03'
+ *
+ * // 向前 2 天
+ * adjustDate('2024-01-01', { days: -2 }) // '2023-12-30'
+ *
+ * // 向后 1 年 2 个月 3 天
+ * adjustDate('2024-01-01', { years: 1, months: 2, days: 3 }) // '2025-03-04'
+ *
+ * // 向后 2 周
+ * adjustDate('2024-01-01', { weeks: 2 }) // '2024-01-15'
+ *
+ * // 包含时间（向后 2 天 3 小时 30 分钟）
+ * adjustDate('2024-01-01 10:30:00', { days: 2, hours: 3, minutes: 30 }) // '2024-01-03 14:00'
+ *
+ * // 自定义格式
+ * adjustDate('2024-01-01', { days: 2, format: 'YYYY/MM/DD' }) // '2024/01/03'
+ * adjustDate('2024-01-01', { days: 2, format: 'YYYY 年 MM 月 DD 日' }) // '2024 年 01 月 03 日'
+ *
+ * // 时间戳输入
+ * adjustDate(1717330884896, { days: 2 }) // '2024-06-04'
+ *
+ * // 精确到毫秒
+ * adjustDate('2024-01-01 10:30:00', { hours: 1, minutes: 30, seconds: 45, milliseconds: 500 })
+ *
+ * // 返回 Date 对象
+ * adjustDate('2024-01-01', { days: 2, returnDate: true }) // Date 对象
  */
-function calculateDate(originDate, n, sep = '-') {
-  //originDate 为字符串日期 如:'2019-01-01' n为你要传入的参数，当前为0，前一天为-1，后一天为1
-  const date = new Date(originDate); //这边给定一个特定时间
-  const newDate = new Date(date.getFullYear(), date.getMonth(), date.getDate());
-  const millisecondGap = newDate.getTime() + 1000 * 60 * 60 * 24 * parseInt(String(n)); //计算前几天用减，计算后几天用加，最后一个就是多少天的数量
-  const targetDate = new Date(millisecondGap);
-  const finalNewDate =
-    targetDate.getFullYear() +
-    sep +
-    String(targetDate.getMonth() + 1).padStart(2, '0') +
-    '-' +
-    String(targetDate.getDate()).padStart(2, '0');
-  return finalNewDate;
-}
-/**
- * 计算向前或向后N天的具体日期时间
- * @param {DateValue} originDateTime - 参考日期时间
- * @param {number} n - 正数：向后推算；负数：向前推算
- * @param {string} dateSep - 日期分隔符
- * @param {string} timeSep - 时间分隔符
- * @returns {string} 转换后的目标日期时间
- */
-function calculateDateTime(originDateTime, n, dateSep = '-', timeSep = ':') {
-  const date = new Date(originDateTime);
-  const separator1 = dateSep;
-  const separator2 = timeSep;
-  const dateTime = new Date(
-    date.getFullYear(),
-    date.getMonth(),
-    date.getDate(),
-    date.getHours(),
-    date.getMinutes(),
-    date.getSeconds()
-  );
-  const millisecondGap = dateTime.getTime() + 1000 * 60 * 60 * 24 * parseInt(String(n)); //计算前几天用减，计算后几天用加，最后一个就是多少天的数量
-  const targetDateTime = new Date(millisecondGap);
-  return (
-    targetDateTime.getFullYear() +
-    separator1 +
-    String(targetDateTime.getMonth() + 1).padStart(2, '0') +
-    separator1 +
-    String(targetDateTime.getDate()).padStart(2, '0') +
-    ' ' +
-    String(targetDateTime.getHours()).padStart(2, '0') +
-    separator2 +
-    String(targetDateTime.getMinutes()).padStart(2, '0') +
-    separator2 +
-    String(targetDateTime.getSeconds()).padStart(2, '0')
-  );
+function adjustDate(originDate, options = {}) {
+  const {
+    format,
+    returnDate = false,
+    years = 0,
+    months = 0,
+    weeks = 0,
+    days = 0,
+    hours = 0,
+    minutes = 0,
+    seconds = 0,
+    milliseconds = 0
+  } = options;
+  const date = dateParse(originDate);
+  const targetDate = new Date(date);
+  // 保存原始日期以便处理月末边界
+  const originalDay = date.getDate();
+  const originalMonthDays = new Date(date.getFullYear(), date.getMonth() + 1, 0).getDate();
+  const isEndOfMonth = originalDay === originalMonthDays;
+  targetDate.setFullYear(targetDate.getFullYear() + years);
+  // 处理月末边界：如果原始日期是月末，需要特殊处理
+  if (months !== 0) {
+    const targetMonthIndex = targetDate.getMonth() + months;
+    const targetMonthDays = new Date(targetDate.getFullYear(), targetMonthIndex + 1, 0).getDate();
+    // 先将日期设为 1 号，避免 setMonth 时因日期过大而自动进位
+    targetDate.setDate(1);
+    targetDate.setMonth(targetMonthIndex);
+    // 如果原始日期是月末，则调整为目标月份的月末
+    if (isEndOfMonth) {
+      targetDate.setDate(targetMonthDays);
+    } else if (originalDay > targetMonthDays) {
+      // 如果原始日期大于目标月份的最大天数，也调整为目标月份的月末
+      targetDate.setDate(targetMonthDays);
+    } else {
+      // 否则保持原始日期
+      targetDate.setDate(originalDay);
+    }
+  }
+  // 处理天数（不包括月份变化）
+  if (days !== 0 || weeks !== 0) {
+    targetDate.setDate(targetDate.getDate() + days + weeks * 7);
+  }
+  targetDate.setHours(targetDate.getHours() + hours);
+  targetDate.setMinutes(targetDate.getMinutes() + minutes);
+  targetDate.setSeconds(targetDate.getSeconds() + seconds);
+  targetDate.setMilliseconds(targetDate.getMilliseconds() + milliseconds);
+  if (returnDate) {
+    return targetDate;
+  }
+  if (format) {
+    return formatDate(targetDate, format);
+  }
+  const year = targetDate.getFullYear();
+  const month = String(targetDate.getMonth() + 1).padStart(2, '0');
+  const day = String(targetDate.getDate()).padStart(2, '0');
+  const hoursStr = String(targetDate.getHours()).padStart(2, '0');
+  const minutesStr = String(targetDate.getMinutes()).padStart(2, '0');
+  const secondsStr = String(targetDate.getSeconds()).padStart(2, '0');
+  const hasTimeParam =
+    options.hasOwnProperty('hours') ||
+    options.hasOwnProperty('minutes') ||
+    options.hasOwnProperty('seconds') ||
+    options.hasOwnProperty('milliseconds');
+  if (hasTimeParam) {
+    if (options.hasOwnProperty('milliseconds')) {
+      const msStr = String(targetDate.getMilliseconds()).padStart(3, '0');
+      return `${year}-${month}-${day} ${hoursStr}:${minutesStr}:${secondsStr}.${msStr}`;
+    }
+    if (options.hasOwnProperty('seconds')) {
+      return `${year}-${month}-${day} ${hoursStr}:${minutesStr}:${secondsStr}`;
+    }
+    return `${year}-${month}-${day} ${hoursStr}:${minutesStr}`;
+  }
+  return `${year}-${month}-${day}`;
 }
 var date = {
   isValidDate,
@@ -218,12 +276,14 @@ var date = {
   dateToStart,
   dateToEnd,
   formatDate,
-  calculateDate,
-  calculateDateTime
+  adjustDate,
+  /**
+   * @deprecated 已废弃，请使用 adjustDate
+   */
+  calculateDate: adjustDate
 };
 
-exports.calculateDate = calculateDate;
-exports.calculateDateTime = calculateDateTime;
+exports.adjustDate = adjustDate;
 exports.dateParse = dateParse;
 exports.dateToEnd = dateToEnd;
 exports.dateToStart = dateToStart;

package/dist/cjs/dom.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/download.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/file.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/func.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/index.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
@@ -37,6 +37,7 @@ var cloneDeep = require('./cloneDeep.cjs');
 var isEqual = require('./isEqual.cjs');
 var unicodeToolkit = require('./unicodeToolkit.cjs');
 
+// 导出默认对象（使用类型断言避免私有类型问题）
 var index = {
   ...array,
   ...clipboard,
@@ -78,8 +79,7 @@ exports.fallbackCopyText = clipboard.fallbackCopyText;
 exports.cookieDel = cookie.cookieDel;
 exports.cookieGet = cookie.cookieGet;
 exports.cookieSet = cookie.cookieSet;
-exports.calculateDate = date.calculateDate;
-exports.calculateDateTime = date.calculateDateTime;
+exports.adjustDate = date.adjustDate;
 exports.dateParse = date.dateParse;
 exports.dateToEnd = date.dateToEnd;
 exports.dateToStart = date.dateToStart;

package/dist/cjs/isEqual.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/math.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/number.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/object.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/path.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/qs.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/random.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/string.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/tooltip.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/tree.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/type.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/unicodeToolkit.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
@@ -12,24 +12,6 @@ Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toString
  * 增强型 Unicode/HTML/UTF-8 编码解码工具
  */
 class UnicodeToolkit {
-  // 基础 HTML 实体映射
-  static ENTITY_MAP = {
-    '&': '&',
-    '<': '&lt;',
-    '>': '&gt;',
-    '"': '&quot;',
-    "'": '&#39;'
-  };
-  static NAMED_ENTITIES = {
-    '&quot;': '"',
-    '&amp;': '&',
-    '&lt;': '<',
-    '&gt;': '>',
-    '&nbsp;': '\u00A0',
-    '&copy;': '©',
-    '&trade;': '™',
-    '&reg;': '®'
-  };
   /**
    * 编码函数
    * @param {string} str 原始字符串
@@ -117,6 +99,24 @@ class UnicodeToolkit {
     return decoded;
   }
 }
+// 基础 HTML 实体映射
+UnicodeToolkit.ENTITY_MAP = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;'
+};
+UnicodeToolkit.NAMED_ENTITIES = {
+  '&quot;': '"',
+  '&amp;': '&',
+  '&lt;': '<',
+  '&gt;': '>',
+  '&nbsp;': '\u00A0',
+  '&copy;': '©',
+  '&trade;': '™',
+  '&reg;': '®'
+};
 var unicodeToolkit = {
   UnicodeToolkit
 };

package/dist/cjs/unique.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/url.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/validator.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/variable.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/cjs/watermark.cjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/array.mjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/async.mjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/base64.mjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/clipboard.mjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/cloneDeep.mjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */

package/dist/esm/cookie.mjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.0
+ * sculp-js v1.19.2
  * (c) 2023-present chandq
  * Released under the MIT License.
  */