util-helpers 4.15.3 → 4.16.0

package/esm/ajax.js

@@ -0,0 +1,149 @@
+import _typeof from "@babel/runtime/helpers/typeof";
+/**
+ * @typedef {XMLHttpRequest['onloadstart']} XMLHttpRequestEvent XMLHttpRequest 事件对象
+ */
+
+/**
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/API/XMLHttpRequest|XMLHttpRequest}
+ * @typedef {Object} AjaxOptions ajax配置项
+ * @property {string} [method="get"] 创建请求时使用的方法
+ * @property {Document | XMLHttpRequestBodyInit | null} [data=null] 请求体被发送的数据
+ * @property {Object.<string, string>} [headers] 自定义请求头
+ * @property {XMLHttpRequestResponseType} [responseType] 响应类型
+ * @property {number} [timeout] 请求超时的毫秒数
+ * @property {boolean} [withCredentials=false] 跨域请求时是否需要使用凭证
+ * @property {boolean} [async=true] 是否异步执行操作
+ * @property {string|null} [user=null] 用户名，用于认证用途
+ * @property {string|null} [password=null] 密码，用于认证用途
+ * @property {XMLHttpRequestEvent} [onLoadStart] 接收到响应数据时触发
+ * @property {XMLHttpRequestEvent} [onProgress] 请求接收到更多数据时，周期性地触发
+ * @property {XMLHttpRequestEvent} [onAbort] 当 request 被停止时触发，例如当程序调用 XMLHttpRequest.abort() 时
+ * @property {XMLHttpRequestEvent} [onTimeout] 在预设时间内没有接收到响应时触发
+ * @property {XMLHttpRequestEvent} [onError] 当 request 遭遇错误时触发
+ * @property {XMLHttpRequestEvent} [onLoad] 请求成功完成时触发
+ * @property {XMLHttpRequestEvent} [onLoadEnd] 请求结束时触发，无论请求成功 (load) 还是失败 (abort 或 error)
+ */
+
+/**
+ * 请求<br/><br/>
+ * 
+ * <em style="font-weight: bold;">注意：该方法仅适用于浏览器端。</em>
+ * 
+ * @static
+ * @alias module:Other.ajax
+ * @since 4.16.0
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/API/XMLHttpRequest|XMLHttpRequest}
+ * @param {string} url 地址
+ * @param {AjaxOptions} [options] 配置项
+ * @returns {Promise<ProgressEvent<EventTarget>>}
+ * @example
+ * ajax('/somefile').then(res=>{
+ *   // do something
+ * });
+ * 
+ * ajax('/api', { method: 'post' }).then(res=>{
+ *   // do something
+ * });
+ */
+function ajax(url, options) {
+  var _ref = options || {},
+    _ref$method = _ref.method,
+    method = _ref$method === void 0 ? 'get' : _ref$method,
+    _ref$data = _ref.data,
+    data = _ref$data === void 0 ? null : _ref$data,
+    timeout = _ref.timeout,
+    headers = _ref.headers,
+    _ref$withCredentials = _ref.withCredentials,
+    withCredentials = _ref$withCredentials === void 0 ? false : _ref$withCredentials,
+    _ref$async = _ref.async,
+    async = _ref$async === void 0 ? true : _ref$async,
+    _ref$user = _ref.user,
+    user = _ref$user === void 0 ? null : _ref$user,
+    _ref$password = _ref.password,
+    password = _ref$password === void 0 ? null : _ref$password,
+    responseType = _ref.responseType,
+    onAbort = _ref.onAbort,
+    onError = _ref.onError,
+    onLoad = _ref.onLoad,
+    onLoadEnd = _ref.onLoadEnd,
+    onLoadStart = _ref.onLoadStart,
+    onProgress = _ref.onProgress,
+    onTimeout = _ref.onTimeout;
+  return new Promise(function (resolve, reject) {
+    var xhr = new XMLHttpRequest();
+    xhr.open(method.toLowerCase(), url, async, user, password);
+
+    // 设置请求超时
+    if (typeof timeout === 'number' && timeout > 0) {
+      xhr.timeout = timeout;
+    }
+
+    // 跨域请求时是否需要使用凭证
+    xhr.withCredentials = withCredentials;
+
+    // 设置响应类型
+    if (responseType) {
+      xhr.responseType = responseType;
+    }
+
+    // 设置请求头
+    if (_typeof(headers) === 'object') {
+      Object.keys(headers).map(function (item) {
+        xhr.setRequestHeader(item, headers[item]);
+      });
+    }
+
+    /**
+     * 请求成功异步调用
+     * @param {XMLHttpRequestEvent} [cb] 回调方法
+     */
+    var wrapSuccess = function wrapSuccess(cb) {
+      /**
+       * 内部方法
+       * @param {ProgressEvent<EventTarget>} e 事件对象
+       */
+      return function (e) {
+        resolve(e);
+        cb === null || cb === void 0 ? void 0 : cb.call(xhr, e);
+      };
+    };
+
+    /**
+     * 请求失败（中断/超时/失败）处理
+       * @param {XMLHttpRequestEvent} [cb] 回调方法
+     */
+    var wrapError = function wrapError(cb) {
+      /**
+       * 内部方法
+       * @param {ProgressEvent<EventTarget>} e 事件对象
+       */
+      return function (e) {
+        reject(e);
+        cb === null || cb === void 0 ? void 0 : cb.call(xhr, e);
+      };
+    };
+
+    // 事件处理
+    /**@type {Object.<keyof XMLHttpRequestEventTargetEventMap, XMLHttpRequestEvent | undefined>} */
+    var events = {
+      loadstart: onLoadStart,
+      progress: onProgress,
+      abort: wrapError(onAbort),
+      timeout: wrapError(onTimeout),
+      error: wrapError(onError),
+      load: wrapSuccess(onLoad),
+      loadend: onLoadEnd
+    };
+    /**@type {(keyof XMLHttpRequestEventTargetEventMap)[]} */
+    // @ts-ignore
+    var eventNames = Object.keys(events);
+    eventNames.map(function (item) {
+      var func = events[item];
+      if (func) {
+        xhr.addEventListener(item, func);
+      }
+    });
+    xhr.send(data);
+  });
+}
+export default ajax;

package/esm/blobToDataURL.js

@@ -2,13 +2,19 @@
 //  方法1：将file或者blob类型文件转成base64数据，再作为src赋值给img标签
 //  方法2：使用 window.URL.createObjectURL(blob) 为blob、file 创建一个指向该参数对象的URL
 
+import fileReader from "./fileReader";
+
 /**
- * 将 Blob 或 File 对象转成 data:URL 格式的 Base64 字符串。
+ * 将 Blob 或 File 对象转成 data:URL 格式的 Base64 字符串<br/><br/>
+ * 
+ * <em style="font-weight: bold;">注意：该方法仅适用于浏览器端。</em>
  *
  * @static
  * @alias module:Processor.blobToDataURL
  * @see 参考 {@link https://developer.mozilla.org/zh-CN/docs/Web/API/FileReader/readAsDataURL|FileReader.readAsDataURL()}
  * @since 4.1.0
+ * @ignore
+ * @deprecated 请使用 `fileReader` 方法
  * @param {Blob} blob Blob 或 File 对象
  * @returns {Promise<string>} data:URL 格式的 Base64 字符串。
  * @example
@@ -26,16 +32,6 @@
  * });
  */
 function blobToDataURL(blob) {
-  return new Promise(function (resolve, reject) {
-    var reader = new FileReader();
-    reader.readAsDataURL(blob);
-    // @ts-ignore
-    reader.onload = function () {
-      return resolve(reader.result);
-    };
-    reader.onerror = function (error) {
-      return reject(error);
-    };
-  });
+  return fileReader(blob);
 }
 export default blobToDataURL;

package/esm/dataURLToBlob.js

@@ -12,17 +12,18 @@
  * dataURLToBlob(dataurl); // Blob {size: 32, type: 'text/html'}
  */
 function dataURLToBlob(dataurl) {
-  var arr = dataurl.split(',');
-  // @ts-ignore
-  var mime = arr[0].match(/:(.*?);/)[1];
-  var bstr = atob(arr[1]);
+  var parts = dataurl.split(',');
+  var meta = parts[0].substring(5).split(';');
+  var type = meta[0];
+  var decoder = meta.indexOf('base64') !== -1 ? atob : decodeURIComponent;
+  var bstr = decoder(parts[1]);
   var n = bstr.length;
   var u8arr = new Uint8Array(n);
   while (n--) {
     u8arr[n] = bstr.charCodeAt(n);
   }
   return new Blob([u8arr], {
-    type: mime
+    type: type
   });
 }
 export default dataURLToBlob;

package/esm/download.js

@@ -0,0 +1,156 @@
+import _typeof from "@babel/runtime/helpers/typeof";
+// 如果修改文档，请同步修改 interface.doc.js
+
+import dataURLToBlob from "./dataURLToBlob";
+import isUrl from "./isUrl";
+import ajax from "./ajax";
+import { isBlob } from "./utils/type";
+
+/**
+ * 下载文件
+ * 
+ * @param {string} blobUrl blob 地址
+ * @param {string} [fileName] 文件名称
+ */
+function saver(blobUrl, fileName) {
+  var anchor = document.createElement('a');
+  // anchor.href = decodeURIComponent(blobUrl);
+  anchor.href = blobUrl;
+  anchor.style.display = 'none';
+  anchor.setAttribute('download', fileName || '');
+
+  /**
+   * 处理点击事件，防止事件冒泡到 body/html 的点击事件。
+   * 
+   * @param {MouseEvent} e 鼠标事件对象
+   */
+  function handleClick(e) {
+    e.stopPropagation();
+    anchor.removeEventListener('click', handleClick);
+  }
+  anchor.addEventListener('click', handleClick);
+  document.body.appendChild(anchor);
+  anchor.click();
+  document.body.removeChild(anchor);
+}
+
+/**
+ * @typedef {import('./ajax.js').AjaxOptions} AjaxOptions ajax 配置项
+ */
+
+/**
+ * @callback TransformRequest
+ * @param {AjaxOptions} options ajax 配置项
+ * @returns {AjaxOptions}
+ */
+
+/**
+ * @callback TransformResponse
+ * @param {Blob} res 响应的Blob对象。如果你通过 transformRequest 修改了 responseType ，该参数将是该类型响应值。
+ * @returns {Blob}
+ */
+
+/**
+ * @typedef {Object} DownloadOptions 下载配置项
+ * @property {string} [options.fileName] 文件名称
+ * @property {string} [options.type] MIME 类型
+ * @property {'url'|'text'} [options.dataType] 手动设置数据类型，默认会根据传入的数据判断类型，主要是为了区分 url 和 text 。<br/>如果你要下载的文本是 url ，请设置 'text' ；如果你要下载的 url 是绝对/相对路径，请设置 'url' 。
+ * @property {TransformRequest} [options.transformRequest] 请求前触发，XHR 对象或配置调整
+ * @property {TransformResponse} [options.transformResponse] 请求成功后触发，在传递给 then/catch 前，允许修改响应数据
+ */
+
+/**
+ * 下载<br/><br/>
+ * 
+ * <em style="font-weight: bold;">注意：该方法仅适用于浏览器端，兼容 IE10+ 和现代浏览器。</em>
+ * 
+ * @static
+ * @alias module:Other.download
+ * @since 4.16.0
+ * @see {@link https://zh.wikipedia.org/wiki/多用途互聯網郵件擴展|多用途互联网邮件扩展}
+ * @param {string|Blob|ArrayBuffer|Int8Array|Uint8Array|Uint8ClampedArray|Int16Array|Uint16Array|Int32Array|Uint32Array|Float32Array|Float64Array|BigInt64Array|BigUint64Array} data 字符串、blob数据或url地址
+ * @param {string|DownloadOptions} [options] 文件名称 或 配置项
+ * @returns {Promise<void>}
+ * @example
+ * // 文本
+ * download('hello world', 'text.txt');
+ * 
+ * // 远程文件
+ * download('/xxx.jpg', { dataType: 'url' });
+ * 
+ * // blob文件
+ * download(new Blob(['hello world']), 'text.txt');
+ * 
+ */
+function download(data, options) {
+  var config = _typeof(options) === 'object' ? options : {};
+  if (typeof options === 'string') {
+    config.fileName = options;
+  }
+  var fileName = config.fileName,
+    type = config.type,
+    dataType = config.dataType,
+    transformRequest = config.transformRequest,
+    transformResponse = config.transformResponse;
+
+  /** @type {Blob|undefined} */
+  var payload;
+
+  // dataURLs、blob url、url、string
+  if (typeof data === 'string') {
+    if (!dataType && /^blob:.*?\/.*/.test(data)) {
+      // blob url
+      saver(data, fileName);
+      return Promise.resolve();
+    } else if (!dataType && /^data:([\w+-]+\/[\w+.-]+)?[,;]/.test(data)) {
+      // dataURLs
+      payload = dataURLToBlob(data);
+    } else if (dataType === 'url' || !dataType && isUrl(data)) {
+      // url
+      /** @type {AjaxOptions} */
+      var defaultAjaxOptions = {
+        responseType: 'blob'
+      };
+      // 请求前配置调整
+      var ajaxOptions = typeof transformRequest === 'function' ? transformRequest(defaultAjaxOptions) : defaultAjaxOptions;
+      return ajax(data, ajaxOptions).then(function (e) {
+        /** @type {Blob} */
+        // @ts-ignore
+        // 响应结果调整
+        var res = typeof transformResponse === 'function' ? transformResponse(e.target.response) : e.target.response;
+        var currentFileName = fileName || data.split("?")[0].split("#")[0].split("/").pop();
+        return download(res, {
+          fileName: currentFileName,
+          type: type || (isBlob(res) ? res.type : undefined)
+        });
+      });
+    } else {
+      // string
+      payload = new Blob([data], {
+        type: type || 'text/plain'
+      });
+    }
+  } else if (isBlob(data)) {
+    // @ts-ignore
+    payload = data;
+  }
+
+  // html、TypedArray
+  if (!(payload instanceof Blob)) {
+    payload = new Blob([data], {
+      type: type
+    });
+  }
+
+  // @ts-ignore
+  if (navigator.msSaveBlob) {
+    // @ts-ignore
+    navigator.msSaveBlob(payload, fileName || 'download');
+  } else {
+    var url = URL.createObjectURL(payload);
+    saver(url, fileName);
+    URL.revokeObjectURL(url);
+  }
+  return Promise.resolve();
+}
+export default download;

package/esm/fileReader.js

@@ -0,0 +1,67 @@
+var FileReaderMethodMap = {
+  arrayBuffer: 'readAsArrayBuffer',
+  binaryString: 'readAsBinaryString',
+  dataURL: 'readAsDataURL',
+  text: 'readAsText'
+};
+
+/**
+ * @overload
+ * @param {Blob} blob
+ * @param {'arrayBuffer'} type
+ * @returns {Promise<ArrayBuffer>}
+ */
+
+/**
+ * @overload
+ * @param {Blob} blob
+ * @param {'binaryString'|'binaryString'|'dataURL'|'text'} [type='dataURL']
+ * @returns {Promise<string>}
+ */
+
+/**
+ * 读取 Blob 或 File 对象<br/><br/>
+ * 
+ * <em style="font-weight: bold;">注意：该方法仅适用于浏览器端。</em>
+ *
+ * @static
+ * @alias module:Processor.fileReader
+ * @see 参考 {@link https://developer.mozilla.org/zh-CN/docs/Web/API/FileReader|FileReader}
+ * @since 4.16.0
+ * @param {Blob} blob Blob 或 File 对象
+ * @param {'arrayBuffer'|'binaryString'|'dataURL'|'text'} [type='dataURL'] Blob 或 File 对象
+ * @returns {Promise<string|ArrayBuffer>} 文件的内容
+ * @example
+ * const aFileParts = ['<a id="a"><b id="b">hey!</b></a>']; // 一个包含DOMString的数组
+ * const htmlBlob = new Blob(aFileParts, { type: 'text/html' }); // 得到 blob
+ *
+ * fileReader(htmlBlob).then(data=>{
+ *   console.log(data); // data:text/html;base64,PGEgaWQ9ImEiPjxiIGlkPSJiIj5oZXkhPC9iPjwvYT4=
+ * });
+ *
+ * const textBlob = new Blob(aFileParts, { type: 'text/plain' });
+ *
+ * fileReader(textBlob, 'text').then(data=>{
+ *   console.log(data); // <a id="a"><b id="b">hey!</b></a>
+ * });
+ */
+function fileReader(blob) {
+  var type = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'dataURL';
+  var method = FileReaderMethodMap[type];
+  if (!method) {
+    method = FileReaderMethodMap.dataURL;
+  }
+  return new Promise(function (resolve, reject) {
+    var reader = new FileReader();
+    // @ts-ignore
+    reader[method](blob);
+    // @ts-ignore
+    reader.onload = function () {
+      return resolve(reader.result);
+    };
+    reader.onerror = function (error) {
+      return reject(error);
+    };
+  });
+}
+export default fileReader;

package/esm/index.js

@@ -40,6 +40,7 @@ export { default as numberToChinese } from './numberToChinese';
 export { default as bytesToSize } from './bytesToSize';
 export { default as parseIdCard } from './parseIdCard';
 export { default as blobToDataURL } from './blobToDataURL';
+export { default as fileReader } from './fileReader';
 export { default as dataURLToBlob } from './dataURLToBlob';
 export { default as setDataURLPrefix } from './setDataURLPrefix';
 export { default as normalizeString } from './normalizeString';
@@ -98,10 +99,12 @@ export { default as round } from './round';
  * @module Other
  * @since 4.2.0
  */
-export { default as waitTime } from './waitTime';
+export { default as ajax } from './ajax';
 export { default as calculateCursorPosition } from './calculateCursorPosition';
+export { default as download } from './download';
 export { default as randomString } from './randomString';
 export { default as strlen } from './strlen';
+export { default as waitTime } from './waitTime';
 
 /**
  * 树结构数据查询、过滤、转换等处理方法

package/esm/interface.doc.js

@@ -0,0 +1,124 @@
+/* eslint-disable no-unused-vars */
+// 该文件用于 jsdoc 生成文件。因为一些 typescript 语法， jsdoc 不支持，导致生成文档报错。
+
+/**
+ * 转换字段名，返回一个转换字段后的值，不改变原值。
+ * 
+ * @static
+ * @alias module:Tree.transformFieldNames
+ * @since 4.14.0
+ * @param {object[]} data 对象数组。如果是树结构数据，需要指定第三个参数 childrenField
+ * @param {object} fieldNames 字段名映射
+ * @param {string} [childrenField] 子级数据字段名
+ * @param {'spread'|'self'} [nodeAssign='spread'] 节点赋值方式。spread表示使用展开运算符创建新值，self表示使用自身对象。
+ * @returns {object[]}
+ * @example
+ * 
+ * const options = [{code: '1', name: 'one'},{code:'2', name:'two'}];
+ * const newOptions = transformFieldNames(options, {label: 'name', value: 'code'});
+ * // [{value: '1', label: 'one'},{value:'2', label:'two'}]
+ * 
+ * // 嵌套数据，指定子级字段名 children
+ * const options2 = [{code: '1', name: 'one'},{code:'2', name:'two', children: [{code:'2-1', name:'two-one', children: [{code: '2-1-1', name:'two-one-one'}]}]}];
+ * const newOptions2 = transformFieldNames(options2, {label: 'name', value: 'code'}, 'children');
+ * // [{value: '1', label: 'one'},{value:'2', label:'two', children: [{value: '2-1', label:'two-one', children: [{value: '2-1-1', label:'two-one-one'}]}]}]
+ * 
+ * const options3 = [{code: '1', name: 'one'},{code:'2', name:'two', childs: [{code:'2-1', name:'two-one'}]}];
+ * const newOptions3 = transformFieldNames(options3, {label: 'name', value: 'code'}, 'childs');
+ * // [{value: '1', label: 'one'},{value:'2', label:'two', childs: [{value: '2-1', label:'two-one'}]}]
+ * 
+ * // 嵌套数据，并替换子集字段名
+ * const newOptions4 = transformFieldNames(options3, {label: 'name', value: 'code', children: 'childs'}, 'childs');
+ * // [{value: '1', label: 'one'},{value:'2', label:'two', children: [{value: '2-1', label:'two-one'}]}]
+ */
+function transformFieldNames(data, fieldNames, childrenField) {}
+
+/**
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/API/XMLHttpRequest|XMLHttpRequest}
+ * @typedef {Object} AjaxOptions ajax配置项
+ * @property {string} [method="get"] 创建请求时使用的方法
+ * @property {*} [data=null] 请求体被发送的数据
+ * @property {object} [headers] 自定义请求头
+ * @property {string} [responseType] 响应类型
+ * @property {number} [timeout] 请求超时的毫秒数
+ * @property {boolean} [withCredentials=false] 跨域请求时是否需要使用凭证
+ * @property {boolean} [async=true] 是否异步执行操作
+ * @property {string|null} [user=null] 用户名，用于认证用途
+ * @property {string|null} [password=null] 密码，用于认证用途
+ * @property {function} [onLoadStart] 接收到响应数据时触发
+ * @property {function} [onProgress] 请求接收到更多数据时，周期性地触发
+ * @property {function} [onAbort] 当 request 被停止时触发，例如当程序调用 XMLHttpRequest.abort() 时
+ * @property {function} [onTimeout] 在预设时间内没有接收到响应时触发
+ * @property {function} [onError] 当 request 遭遇错误时触发
+ * @property {function} [onLoad] 请求成功完成时触发
+ * @property {function} [onLoadEnd] 请求结束时触发，无论请求成功 (load) 还是失败 (abort 或 error)
+ */
+
+/**
+ * 请求<br/><br/>
+ * 
+ * <em style="font-weight: bold;">注意：该方法仅适用于浏览器端。</em>
+ * 
+ * @static
+ * @alias module:Other.ajax
+ * @since 4.16.0
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/API/XMLHttpRequest|XMLHttpRequest}
+ * @param {string} url 地址
+ * @param {AjaxOptions} [options] 配置项
+ * @returns {Promise<object>} XHR 事件对象
+ * @example
+ * ajax('/somefile').then(res=>{
+ *   // do something
+ * });
+ * 
+ * ajax('/api', { method: 'post' }).then(res=>{
+ *   // do something
+ * });
+ */
+function ajax(url, options) {}
+
+/**
+ * @callback TransformRequest
+ * @param {AjaxOptions} options ajax 配置项
+ * @returns {AjaxOptions}
+ */
+
+/**
+ * @callback TransformResponse
+ * @param {Blob} res 响应的Blob对象。如果你通过 transformRequest 修改了 responseType ，该参数将是该类型响应值。
+ * @returns {Blob}
+ */
+
+/**
+ * @typedef {Object} DownloadOptions 下载配置项
+ * @property {string} [options.fileName] 文件名称
+ * @property {string} [options.type] MIME 类型
+ * @property {'url'|'text'} [options.dataType] 手动设置数据类型，默认会根据传入的数据判断类型，主要是为了区分 url 和 text 。<br/>如果你要下载的文本是 url ，请设置 'text' ；如果你要下载的 url 是绝对/相对路径，请设置 'url' 。
+ * @property {TransformRequest} [options.transformRequest] 请求前触发，XHR 对象或配置调整
+ * @property {TransformResponse} [options.transformResponse] 请求成功后触发，在传递给 then/catch 前，允许修改响应数据
+ */
+
+/**
+ * 下载<br/><br/>
+ * 
+ * <em style="font-weight: bold;">注意：该方法仅适用于浏览器端，兼容 IE10+ 和现代浏览器。</em>
+ * 
+ * @static
+ * @alias module:Other.download
+ * @since 4.16.0
+ * @see {@link https://zh.wikipedia.org/wiki/多用途互聯網郵件擴展|MIME}
+ * @param {string|Blob|TypedArray} data 字符串、blob数据或url地址
+ * @param {string|DownloadOptions} [options] 文件名称 或 配置项
+ * @returns {Promise<void>}
+ * @example
+ * // 文本
+ * download('hello world', 'text.txt');
+ * 
+ * // 远程文件
+ * download('/xxx.jpg', { dataType: 'url' });
+ * 
+ * // blob文件
+ * download(new Blob(['hello world']), 'text.txt');
+ * 
+ */
+function download(data, fileName, options) {}

package/esm/numberToChinese.js

@@ -130,8 +130,9 @@ function mapNumberChar(num) {
 }
 
 /**
- * 数字转中文数字
- * 不在安全数字 -9007199254740991～9007199254740991 内，处理会有异常
+ * 数字转中文数字<br/><br/>
+ * 
+ * 如果数字不在安全数字 -9007199254740991～9007199254740991 范围内，处理会有异常。
  *
  * @static
  * @alias module:Processor.numberToChinese

package/esm/parseIdCard.js

@@ -71,7 +71,7 @@ var Provinces = [
  * @since 4.0.0
  * @see 参考 {@link https://baike.baidu.com/item/居民身份证号码|居民身份证号码}
  * @param {string} id 身份证号码，支持15位
- * @returns {null|IdCardInfo} null 或 省份、生日、性别，省/市/区/年/月/日/性别编码
+ * @returns {IdCardInfo | null} 省份、生日、性别，省/市/区/年/月/日/性别编码。如果解析失败将返回 null 。
  * @example
  * 
  * parseIdCard('123456789123456'); // null

package/esm/safeDate.js

@@ -1,11 +1,32 @@
 import _construct from "@babel/runtime/helpers/construct";
-import isNil from './utils/type/isNil';
+/**
+ * @overload
+ * @return {Date}
+ */
 
-// TODO: 函数重载，类型参照 Date
+/**
+ * @overload
+ * @param {number | string | Date} value Unix时间戳、时间戳字符串 dateString 、Date 日期对象
+ * @return {Date}
+ */
 
 /**
- * 创建一个 Date 实例日期对象，同 new Date() 。<br/>
- * 规避了苹果设备浏览器不支持部分格式（YYYY-MM-DD HH-mm 或 YYYY.MM.DD）。
+ * @overload
+ * @param {number} year 表示年份的整数值。0 到 99 会被映射至 1900 年至 1999 年，其他值代表实际年份。
+ * @param {number} monthIndex 表示月份的整数值，从 0（1 月）到 11（12 月）。
+ * @param {number} [date] 表示一个月中的第几天的整数值，从 1 开始。默认值为 1。
+ * @param {number} [hours] 表示一天中的小时数的整数值 (24 小时制)。默认值为 0（午夜）。
+ * @param {number} [minutes] 表示一个完整时间（如 01:10:00）中的分钟部分的整数值。默认值为 0。
+ * @param {number} [seconds] 表示一个完整时间（如 01:10:00）中的秒部分的整数值。默认值为 0。
+ * @param {number} [ms] 表示一个完整时间的毫秒部分的整数值。默认值为 0。
+ * @return {Date}
+ */
+
+/**
+ * 创建一个 Date 实例日期对象，同 <a href="https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Date#%E5%8F%82%E6%95%B0">new Date()</a> <br/><br/>
+ * 
+ * 规避了苹果设备浏览器不支持部分格式（例如，YYYY-MM-DD HH-mm 或 YYYY.MM.DD）。<br/>
+ * 如果参数为 undefined 正常返回 Date 。
  *
  * @static
  * @alias module:Processor.safeDate
@@ -22,8 +43,6 @@ import isNil from './utils/type/isNil';
  * safeDate('2022.1.1 11:11'); // Sat Jan 01 2022 11:11:00 GMT+0800 (中国标准时间)
  * safeDate(99, 1); // Mon Feb 01 1999 00:00:00 GMT+0800 (中国标准时间)
  * safeDate(1646711233171); // Tue Mar 08 2022 11:47:13 GMT+0800 (中国标准时间)
- * 
- *
  */
 function safeDate(value) {
   var safeValue = typeof value === 'string' ? value.replace(/[\\.-]/g, '/') : value;
@@ -34,8 +53,6 @@ function safeDate(value) {
     // @ts-ignore
     return _construct(Date, [safeValue].concat(args));
   }
-
-  // @ts-ignore
-  return isNil(safeValue) ? new Date() : new Date(safeValue);
+  return typeof safeValue === 'undefined' ? new Date() : new Date(safeValue);
 }
 export default safeDate;