sculp-js 1.19.1 → 1.19.3

package/dist/esm/date.mjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.1
+ * sculp-js v1.19.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
@@ -111,19 +111,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') {
@@ -152,61 +158,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} 计算后的目标日期
- */
-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} 转换后的目标日期时间
+ * 调整日期（增加或减少特定时间单位）
+ * @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 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,
@@ -214,17 +272,11 @@ var date = {
   dateToStart,
   dateToEnd,
   formatDate,
-  calculateDate,
-  calculateDateTime
+  adjustDate,
+  /**
+   * @deprecated 已废弃，请使用 adjustDate
+   */
+  calculateDate: adjustDate
 };
 
-export {
-  calculateDate,
-  calculateDateTime,
-  dateParse,
-  dateToEnd,
-  dateToStart,
-  date as default,
-  formatDate,
-  isValidDate
-};
+export { adjustDate, dateParse, dateToEnd, dateToStart, date as default, formatDate, isValidDate };

package/dist/esm/dom.mjs

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

package/dist/esm/download.mjs

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

package/dist/esm/file.mjs

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

package/dist/esm/func.mjs

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

package/dist/esm/index.mjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.1
+ * sculp-js v1.19.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
@@ -11,15 +11,7 @@ export { copyText, fallbackCopyText } from './clipboard.mjs';
 import * as cookie from './cookie.mjs';
 export { cookieDel, cookieGet, cookieSet } from './cookie.mjs';
 import * as date from './date.mjs';
-export {
-  calculateDate,
-  calculateDateTime,
-  dateParse,
-  dateToEnd,
-  dateToStart,
-  formatDate,
-  isValidDate
-} from './date.mjs';
+export { adjustDate, dateParse, dateToEnd, dateToStart, formatDate, isValidDate } from './date.mjs';
 import * as dom from './dom.mjs';
 export {
   addClass,
@@ -66,14 +58,20 @@ export {
 import * as type from './type.mjs';
 export {
   arrayLike,
+  is,
+  isArguments,
   isArray,
+  isArrayBuffer,
+  isAsyncFunction,
   isBigInt,
   isBoolean,
+  isDataView,
   isDate,
   isEmpty,
   isError,
   isFunction,
   isJsonString,
+  isMap,
   isNaN,
   isNodeList,
   isNull,
@@ -82,9 +80,12 @@ export {
   isNumber,
   isObject,
   isPrimitive,
+  isPromise,
   isRegExp,
+  isSet,
   isString,
   isSymbol,
+  isTypedArray,
   isUndefined,
   objectHas,
   typeIs

package/dist/esm/isEqual.mjs

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

package/dist/esm/math.mjs

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

package/dist/esm/number.mjs

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

package/dist/esm/object.mjs

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

package/dist/esm/path.mjs

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

package/dist/esm/qs.mjs

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

package/dist/esm/random.mjs

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

package/dist/esm/string.mjs

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

package/dist/esm/tooltip.mjs

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

package/dist/esm/tree.mjs

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

package/dist/esm/type.mjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.1
+ * sculp-js v1.19.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
@@ -28,17 +28,37 @@ function arrayLike(any) {
   return objectHas(any, 'length');
 }
 /**
- * 判断任意值的数据类型，检查非对象时不如typeof、instanceof的性能高
+ * 判断任意值的数据类型，检查非对象时不如 typeof、instanceof 的性能高
  *
  * 当检查类对象时是不可靠的，对象可以通过定义 Symbol.toStringTag 属性来更改检查结果
  *
  * 详见：https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Object/toString
  * @param {unknown} any
- * @returns
+ * @returns {TypeTag} 类型标签字符串
  */
 function typeIs(any) {
   return toString.call(any).slice(8, -1);
 }
+/**
+ * 判断值是否为指定类型（带类型守卫）
+ * @param {unknown} value - 要检查的值
+ * @param {TypeTag} type - 期望的类型
+ * @returns {boolean} 如果值是指定类型则返回 true
+ * @example
+ * is(value, 'String')
+ * is(value, 'Array')
+ * is(value, 'Date')
+ *
+ * @example
+ * // 使用类型守卫
+ * if (is(value, 'String')) {
+ *   // value 在这里被推断为 string 类型
+ *   console.log(value.toUpperCase());
+ * }
+ */
+function is(value, type) {
+  return typeIs(value) === type;
+}
 // 基本数据类型判断
 const isString = any => typeof any === 'string';
 const isBoolean = any => typeof any === 'boolean';
@@ -65,6 +85,34 @@ const isNaN = any => Number.isNaN(any);
 const isDate = any => typeIs(any) === 'Date';
 const isError = any => typeIs(any) === 'Error';
 const isRegExp = any => typeIs(any) === 'RegExp';
+const isPromise = any => typeIs(any) === 'Promise';
+const isMap = any => typeIs(any) === 'Map';
+const isSet = any => typeIs(any) === 'Set';
+/**
+ * 判断是否为 TypedArray
+ * @param {unknown} any
+ * @returns {boolean}
+ */
+const isTypedArray = any => {
+  const tag = typeIs(any);
+  return (
+    tag === 'Int8Array' ||
+    tag === 'Uint8Array' ||
+    tag === 'Uint8ClampedArray' ||
+    tag === 'Int16Array' ||
+    tag === 'Uint16Array' ||
+    tag === 'Int32Array' ||
+    tag === 'Uint32Array' ||
+    tag === 'Float32Array' ||
+    tag === 'Float64Array' ||
+    tag === 'BigInt64Array' ||
+    tag === 'BigUint64Array'
+  );
+};
+const isDataView = any => typeIs(any) === 'DataView';
+const isArrayBuffer = any => typeIs(any) === 'ArrayBuffer';
+const isArguments = any => typeIs(any) === 'Arguments';
+const isAsyncFunction = any => typeIs(any) === 'AsyncFunction';
 /**
  * 判断一个字符串是否为有效的 JSON, 若有效则返回有效的JSON对象，否则false
  * @param {string} str
@@ -128,6 +176,9 @@ function isNodeList(value) {
 }
 var type = {
   typeIs,
+  is,
+  TypeMapping: undefined,
+  TypeTag: undefined,
   objectHas,
   arrayLike,
   isString,
@@ -147,6 +198,14 @@ var type = {
   isDate,
   isError,
   isRegExp,
+  isPromise,
+  isMap,
+  isSet,
+  isTypedArray,
+  isDataView,
+  isArrayBuffer,
+  isArguments,
+  isAsyncFunction,
   isJsonString,
   isEmpty,
   isNodeList
@@ -155,14 +214,20 @@ var type = {
 export {
   arrayLike,
   type as default,
+  is,
+  isArguments,
   isArray,
+  isArrayBuffer,
+  isAsyncFunction,
   isBigInt,
   isBoolean,
+  isDataView,
   isDate,
   isEmpty,
   isError,
   isFunction,
   isJsonString,
+  isMap,
   isNaN,
   isNodeList,
   isNull,
@@ -171,9 +236,12 @@ export {
   isNumber,
   isObject,
   isPrimitive,
+  isPromise,
   isRegExp,
+  isSet,
   isString,
   isSymbol,
+  isTypedArray,
   isUndefined,
   objectHas,
   typeIs

package/dist/esm/unicodeToolkit.mjs

@@ -1,5 +1,5 @@
 /*!
- * sculp-js v1.19.1
+ * sculp-js v1.19.3
  * (c) 2023-present chandq
  * Released under the MIT License.
  */
@@ -8,24 +8,6 @@
  * 增强型 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 原始字符串
@@ -113,6 +95,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/esm/unique.mjs

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

package/dist/esm/url.mjs

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

package/dist/esm/validator.mjs

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

package/dist/esm/variable.mjs

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

package/dist/esm/watermark.mjs

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

package/dist/types/base64.d.ts

@@ -1,25 +1,25 @@
 /**
- * 字符串编码成Base64, 平替浏览器的btoa, 不包含中文的处理 （适用于任何环境，包括小程序）
+ * 字符串编码成 Base64（适用于任何环境，包括小程序）
  * @param {string} string
  * @returns {string}
  */
 export declare function weBtoa(string: string): string;
 /**
- * Base64解码为原始字符串，平替浏览器的atob, 不包含中文的处理（适用于任何环境，包括小程序）
+ * Base64 解码为原始字符串（适用于任何环境，包括小程序）
  * @param {string} string
  * @returns {string}
  */
 export declare function weAtob(string: string): string;
 /**
- * 将base64编码的字符串转换为原始字符串，包括对中文内容的处理(高性能，且支持Web、Node、小程序等任意平台)
- * @param base64 base64编码的字符串
+ * 将 base64 编码的字符串转换为原始字符串，包括对中文内容的处理 (高性能，且支持 Web、Node、小程序等任意平台)
+ * @param base64 base64 编码的字符串
  * @returns 原始字符串，包括中文内容
  */
 export declare function b64decode(base64: string): string;
 /**
- * 将原始字符串，包括中文内容，转换为base64编码的字符串(高性能，且支持Web、Node、小程序等任意平台)
+ * 将原始字符串，包括中文内容，转换为 base64 编码的字符串 (高性能，且支持 Web、Node、小程序等任意平台)
  * @param rawStr 原始字符串，包括中文内容
- * @returns base64编码的字符串
+ * @returns base64 编码的字符串
  */
 export declare function b64encode(rawStr: string): string;
 declare const _default: {