util-helpers 4.3.0 → 4.6.0

package/lib/parseIdCard.js

@@ -49,38 +49,58 @@ var Provinces = [// 华北地区：北京市|110000，天津市|120000，河北
 //   ['8', '港澳地区']
 // ];
 
+/**
+ * @typedef {Object} IdCardOrigin - 解析身份证原数据
+ * @property {string} province - 省份编码
+ * @property {string} city - 城市编码
+ * @property {string} area - 地区编码
+ * @property {string} year - 出生年
+ * @property {string} month - 出生月
+ * @property {string} day - 出生日
+ * @property {string} gender - 性别 能整除2为女，否则为男
+ */
+
+/**
+ * @typedef {Object} IdCardInfo - 身份证信息
+ * @property {string} province - 省份
+ * @property {string} birthday - 生日
+ * @property {string} gender - 性别
+ * @property {IdCardOrigin} origin - 解析身份证原数据
+ */
+
 /**
  * 解析身份证号码，支持15、18位身份证号码
- * 
+ *
  * @static
  * @alias module:Processor.parseIdCard
  * @since 4.0.0
  * @see 参考 {@link https://baike.baidu.com/item/居民身份证号码|居民身份证号码}
  * @param {string} id 身份证号码，支持15位
- * @returns null 或 省份、生日、性别，省/市/区/年/月/日/性别编码
+ * @returns {null|IdCardInfo} null 或 省份、生日、性别，省/市/区/年/月/日/性别编码
  * @example
  * parseIdCard('123456789123456');
  * // => null
- * 
+ *
  * // 18位身份证号码
  * parseIdCard('130701199310302288')
  * // =>
  * {
-  birthday: "1993-10-30",
-  gender: "女",
-  origin: { province: "13", city: "07", area: "01", year: "1993", month: "10", day: "30", gender: "8" },
-  province: "河北省"
-}
+ *   birthday: "1993-10-30",
+ *   gender: "女",
+ *   origin: { province: "13", city: "07", area: "01", year: "1993", month: "10", day: "30", gender: "8" },
+ *   province: "河北省"
+ * }
+ *
  * // 15位身份证号码
  * parseIdCard('130701931030228');
  * // =>
  * {
-  birthday: "93-10-30",
-  gender: "女",
-  origin: { province: "13", city: "07", area: "01", year: "93", month: "10", day: "30", gender: "8" },
-  province: "河北省"
-}
- * 
+ *   birthday: "93-10-30",
+ *   gender: "女",
+ *   origin: { province: "13", city: "07", area: "01", year: "93", month: "10", day: "30", gender: "8" },
+ *   province: "河北省"
+ * }
+ *
  */
 
 function parseIdCard(id) {

package/lib/safeDate.js

@@ -0,0 +1,57 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = void 0;
+
+var _isNil = _interopRequireDefault(require("./utils/type/isNil"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
+
+function _construct(Parent, args, Class) { if (_isNativeReflectConstruct()) { _construct = Reflect.construct; } else { _construct = function _construct(Parent, args, Class) { var a = [null]; a.push.apply(a, args); var Constructor = Function.bind.apply(Parent, a); var instance = new Constructor(); if (Class) _setPrototypeOf(instance, Class.prototype); return instance; }; } return _construct.apply(null, arguments); }
+
+function _isNativeReflectConstruct() { if (typeof Reflect === "undefined" || !Reflect.construct) return false; if (Reflect.construct.sham) return false; if (typeof Proxy === "function") return true; try { Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {})); return true; } catch (e) { return false; } }
+
+function _setPrototypeOf(o, p) { _setPrototypeOf = Object.setPrototypeOf || function _setPrototypeOf(o, p) { o.__proto__ = p; return o; }; return _setPrototypeOf(o, p); }
+
+// TODO: 函数重载，类型参照 Date
+
+/**
+ * 创建一个 Date 实例日期对象，同 new Date() 。<br/>
+ * 规避了苹果设备浏览器不支持部分格式（YYYY-MM-DD HH-mm 或 YYYY.MM.DD）。
+ *
+ * @static
+ * @alias module:Processor.safeDate
+ * @see 参考 {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Date|Date}
+ * @since 4.4.0
+ * @param {string|number|Date} [value] 日期时间字符串、毫秒数、日期对象
+ * @param {...number} args 月/日/时/分/秒/毫秒
+ * @returns {Date} Date 实例日期对象
+ * @example
+ * safeDate('2022-1-1'); // Sat Jan 01 2022 00:00:00 GMT+0800 (中国标准时间)
+ * safeDate('2022/1/1'); // Sat Jan 01 2022 00:00:00 GMT+0800 (中国标准时间)
+ * safeDate('2022.1.1'); // Sat Jan 01 2022 00:00:00 GMT+0800 (中国标准时间)
+ * 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;
+
+  for (var _len = arguments.length, args = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
+    args[_key - 1] = arguments[_key];
+  }
+
+  if (args && args.length > 0) {
+    // @ts-ignore
+    return _construct(Date, [safeValue].concat(args));
+  } // @ts-ignore
+
+
+  return (0, _isNil["default"])(safeValue) ? new Date() : new Date(safeValue);
+}
+
+var _default = safeDate;
+exports["default"] = _default;

package/lib/setDataURLPrefix.js

@@ -6,8 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports["default"] = void 0;
 
 /**
- * 设置 DataURL 前缀、MIME 类型、base64 标识。<br/><br/>
- *
+ * 设置 DataURL 前缀、MIME 类型、base64 标识。<br/>
  * 如果你需要获取DataURL 的 MIME 类型和数据本身，推荐使用 <a href="https://www.npmjs.com/package/data-urls">data-urls</a>。
  *
  * @static

package/lib/validatePassword.js

@@ -126,6 +126,22 @@ function hasUnallowableCharacter(val) {
   });
   return ret;
 }
+/**
+ * @typedef {Object} PasswordContaines - 验证密码的包含内容
+ * @property {boolean} number - 包含数字
+ * @property {boolean} lowerCaseLetter - 包含小写字母
+ * @property {boolean} upperCaseLetter - 包含大写字母
+ * @property {boolean} specialCharacter - 包含特殊字符
+ * @property {boolean} unallowableCharacter - 包含非法字符
+ */
+
+/**
+ * @typedef {Object} ValidatePasswordReturn - 验证结果
+ * @property {boolean} validated - 验证结果，根据密码强度、是否包含非法字符得出
+ * @property {number} level - 强度级别，包含数字/大小写字母/特殊字符
+ * @property {PasswordContaines} containes - 包含内容
+ */
+
 /**
  * 验证密码（数字、大小写字母、特殊字符、非法字符）
  *
@@ -138,7 +154,7 @@ function hasUnallowableCharacter(val) {
  * @param {number} [options.level=2] 密码强度 1-包含一种字符 2-包含两种字符 3-包含三种字符。（大写字母、小写字母、数字、特殊字符）
  * @param {boolean} [options.ignoreCase=false] 是否忽略大小写，为 ture 时，大小写字母视为一种字符
  * @param {string} [options.special="!@#$%^&*()-=_+[]\|{},./?<>~"] 支持的特殊字符
- * @returns 验证结果
+ * @returns {ValidatePasswordReturn} 验证结果
  * @example
  *
  * validatePassword('a12345678');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "util-helpers",
-  "version": "4.3.0",
+  "version": "4.6.0",
   "description": "一个基于业务场景的工具方法库",
   "main": "lib/index.js",
   "module": "esm/index.js",

package/types/calculateCursorPosition.d.ts

@@ -0,0 +1,25 @@
+export default calculateCursorPosition;
+/**
+ * 计算输入框的值格式化后光标位置
+ *
+ * @static
+ * @alias module:Other.calculateCursorPosition
+ * @since 4.6.0
+ * @see 格式化手机号码 {@link https://doly-dev.github.io/util-helpers/module-Processor.html#.formatMobile|formatMobile}
+ * @see 格式化银行卡号 {@link https://doly-dev.github.io/util-helpers/module-Processor.html#.formatBankCard|formatBankCard}
+ * @see 示例 {@link https://2950v9.csb.app/|点击查看}
+ * @param {number} prevPos 赋值前的光标位置，onChange/onInput的光标位置 e.target.selectionEnd
+ * @param {string} prevCtrlValue 上一个格式化后的值
+ * @param {string} rawValue 当前输入原值
+ * @param {string} ctrlValue 当前格式化后的值
+ * @param {Object} [options] 配置项
+ * @param {string[]|string} [options.placeholderChar=' '] 占位符
+ * @param {RegExp} [options.maskReg=/\D/g] 需要遮盖的字符规则。默认去掉非数字，意味着 ctrlValue 需要去掉非数字。
+ * @param {'mobile'|'bankCard'} [options.type] 格式化类型，内置手机号码和银行卡号特殊处理
+ * @returns {number} 格式化后的光标位置
+ */
+declare function calculateCursorPosition(prevPos: number, prevCtrlValue: string, rawValue: string, ctrlValue: string, { placeholderChar, maskReg, type }?: {
+    placeholderChar?: string | string[] | undefined;
+    maskReg?: RegExp | undefined;
+    type?: "mobile" | "bankCard" | undefined;
+} | undefined): number;

package/types/formatMobile.d.ts

@@ -0,0 +1,27 @@
+export default formatMobile;
+/**
+ * 格式化手机号码
+ *
+ * @static
+ * @alias module:Processor.formatMobile
+ * @since 4.5.0
+ * @param {string} mobileNo 手机号码
+ * @param {object} [options] 配置项
+ * @param {string} [options.char=' '] 间隔字符
+ * @returns {string} 格式化后的手机号码
+ * @example
+ * formatMobile('13345678900') // '133 4567 8900'
+ * formatMobile('13345678900', { char: '-' }) // '133-4567-8900'
+ *
+ * // 脱敏手机号码
+ * formatMobile('133****1234') // '133 **** 1234'
+ * formatMobile('133****1234', { char: '-' }) // '133-****-1234'
+ *
+ * // 手机号码位数不够
+ * formatMobile('133') // '133'
+ * formatMobile('133456') // '133 456'
+ * formatMobile('13345678') // '133 4567 8'
+ */
+declare function formatMobile(mobileNo: string, { char }?: {
+    char?: string | undefined;
+} | undefined): string;

package/types/index.d.ts

@@ -29,10 +29,13 @@ export { default as blobToDataURL } from "./blobToDataURL";
 export { default as dataURLToBlob } from "./dataURLToBlob";
 export { default as setDataURLPrefix } from "./setDataURLPrefix";
 export { default as normalizeString } from "./normalizeString";
+export { default as safeDate } from "./safeDate";
+export { default as formatMobile } from "./formatMobile";
 export { default as plus } from "./plus";
 export { default as minus } from "./minus";
 export { default as times } from "./times";
 export { default as divide } from "./divide";
 export { default as round } from "./round";
 export { default as waitTime } from "./waitTime";
+export { default as calculateCursorPosition } from "./calculateCursorPosition";
 export { setDisableWarning } from "./utils/config";

package/types/isHMCard.d.ts

@@ -8,5 +8,17 @@ export default isHMCard;
  * @see 参考 {@link https://zh.wikipedia.org/wiki/港澳居民来往内地通行证|港澳居民来往内地通行证}
  * @param {*} value 要检测的值
  * @returns {boolean} 是否为港澳居民来往内地通行证
+ * @example
+ * // 第一代 11 位
+ * isHMCard('h3203117707') // true
+ * isHMCard('H3203117707') // true
+ * isHMCard('m3203117707') // true
+ * isHMCard('M3203117707') // true
+ *
+ * // 第二代 9 位
+ * isHMCard('h32031177') // true
+ * isHMCard('H32031177') // true
+ * isHMCard('m32031177') // true
+ * isHMCard('M32031177') // true
  */
 declare function isHMCard(value: any): boolean;

package/types/isTWCard.d.ts

@@ -8,5 +8,11 @@ export default isTWCard;
  * @see 参考 {@link https://zh.wikipedia.org/wiki/台湾居民来往大陆通行证|台湾居民来往大陆通行证}
  * @param {*} value 要检测的值
  * @returns {boolean} 是否为台湾居民来往大陆通行证
+ * @example
+ * isTWCard('12345678') // true
+ * isTWCard('07257456') // true
+ *
+ * // 一次性短期
+ * isTWCard('F290299977') // true
  */
 declare function isTWCard(value: any): boolean;

package/types/normalizeString.d.ts

@@ -4,6 +4,7 @@ export default normalizeString;
  *
  * @static
  * @alias module:Processor.normalizeString
+ * @see 参考 {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/String#string_instances|String}
  * @since 4.3.0
  * @param {*} value 待处理的值
  * @returns {string} 规整化的值

package/types/parseIdCard.d.ts

@@ -1,4 +1,75 @@
 export default parseIdCard;
+/**
+ * - 解析身份证原数据
+ */
+export type IdCardOrigin = {
+    /**
+     * - 省份编码
+     */
+    province: string;
+    /**
+     * - 城市编码
+     */
+    city: string;
+    /**
+     * - 地区编码
+     */
+    area: string;
+    /**
+     * - 出生年
+     */
+    year: string;
+    /**
+     * - 出生月
+     */
+    month: string;
+    /**
+     * - 出生日
+     */
+    day: string;
+    /**
+     * - 性别 能整除2为女，否则为男
+     */
+    gender: string;
+};
+/**
+ * - 身份证信息
+ */
+export type IdCardInfo = {
+    /**
+     * - 省份
+     */
+    province: string;
+    /**
+     * - 生日
+     */
+    birthday: string;
+    /**
+     * - 性别
+     */
+    gender: string;
+    /**
+     * - 解析身份证原数据
+     */
+    origin: IdCardOrigin;
+};
+/**
+ * @typedef {Object} IdCardOrigin - 解析身份证原数据
+ * @property {string} province - 省份编码
+ * @property {string} city - 城市编码
+ * @property {string} area - 地区编码
+ * @property {string} year - 出生年
+ * @property {string} month - 出生月
+ * @property {string} day - 出生日
+ * @property {string} gender - 性别 能整除2为女，否则为男
+ */
+/**
+ * @typedef {Object} IdCardInfo - 身份证信息
+ * @property {string} province - 省份
+ * @property {string} birthday - 生日
+ * @property {string} gender - 性别
+ * @property {IdCardOrigin} origin - 解析身份证原数据
+ */
 /**
  * 解析身份证号码，支持15、18位身份证号码
  *
@@ -7,7 +78,7 @@ export default parseIdCard;
  * @since 4.0.0
  * @see 参考 {@link https://baike.baidu.com/item/居民身份证号码|居民身份证号码}
  * @param {string} id 身份证号码，支持15位
- * @returns null 或 省份、生日、性别，省/市/区/年/月/日/性别编码
+ * @returns {null|IdCardInfo} null 或 省份、生日、性别，省/市/区/年/月/日/性别编码
  * @example
  * parseIdCard('123456789123456');
  * // => null
@@ -16,33 +87,21 @@ export default parseIdCard;
  * parseIdCard('130701199310302288')
  * // =>
  * {
-  birthday: "1993-10-30",
-  gender: "女",
-  origin: { province: "13", city: "07", area: "01", year: "1993", month: "10", day: "30", gender: "8" },
-  province: "河北省"
-}
+ *   birthday: "1993-10-30",
+ *   gender: "女",
+ *   origin: { province: "13", city: "07", area: "01", year: "1993", month: "10", day: "30", gender: "8" },
+ *   province: "河北省"
+ * }
+ *
  * // 15位身份证号码
  * parseIdCard('130701931030228');
  * // =>
  * {
-  birthday: "93-10-30",
-  gender: "女",
-  origin: { province: "13", city: "07", area: "01", year: "93", month: "10", day: "30", gender: "8" },
-  province: "河北省"
-}
+ *   birthday: "93-10-30",
+ *   gender: "女",
+ *   origin: { province: "13", city: "07", area: "01", year: "93", month: "10", day: "30", gender: "8" },
+ *   province: "河北省"
+ * }
  *
  */
-declare function parseIdCard(id: string): {
-    province: string;
-    birthday: string;
-    gender: string;
-    origin: {
-        province: string;
-        city: string;
-        area: string;
-        year: string;
-        month: string;
-        day: string;
-        gender: string;
-    };
-} | null;
+declare function parseIdCard(id: string): null | IdCardInfo;

package/types/safeDate.d.ts

@@ -0,0 +1,22 @@
+export default safeDate;
+/**
+ * 创建一个 Date 实例日期对象，同 new Date() 。<br/>
+ * 规避了苹果设备浏览器不支持部分格式（YYYY-MM-DD HH-mm 或 YYYY.MM.DD）。
+ *
+ * @static
+ * @alias module:Processor.safeDate
+ * @see 参考 {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Date|Date}
+ * @since 4.4.0
+ * @param {string|number|Date} [value] 日期时间字符串、毫秒数、日期对象
+ * @param {...number} args 月/日/时/分/秒/毫秒
+ * @returns {Date} Date 实例日期对象
+ * @example
+ * safeDate('2022-1-1'); // Sat Jan 01 2022 00:00:00 GMT+0800 (中国标准时间)
+ * safeDate('2022/1/1'); // Sat Jan 01 2022 00:00:00 GMT+0800 (中国标准时间)
+ * safeDate('2022.1.1'); // Sat Jan 01 2022 00:00:00 GMT+0800 (中国标准时间)
+ * 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 (中国标准时间)
+ *
+ */
+declare function safeDate(value?: string | number | Date | undefined, ...args: number[]): Date;

package/types/setDataURLPrefix.d.ts

@@ -1,7 +1,6 @@
 export default setDataURLPrefix;
 /**
- * 设置 DataURL 前缀、MIME 类型、base64 标识。<br/><br/>
- *
+ * 设置 DataURL 前缀、MIME 类型、base64 标识。<br/>
  * 如果你需要获取DataURL 的 MIME 类型和数据本身，推荐使用 <a href="https://www.npmjs.com/package/data-urls">data-urls</a>。
  *
  * @static

package/types/validatePassword.d.ts

@@ -1,4 +1,60 @@
 export default validatePassword;
+/**
+ * - 验证密码的包含内容
+ */
+export type PasswordContaines = {
+    /**
+     * - 包含数字
+     */
+    number: boolean;
+    /**
+     * - 包含小写字母
+     */
+    lowerCaseLetter: boolean;
+    /**
+     * - 包含大写字母
+     */
+    upperCaseLetter: boolean;
+    /**
+     * - 包含特殊字符
+     */
+    specialCharacter: boolean;
+    /**
+     * - 包含非法字符
+     */
+    unallowableCharacter: boolean;
+};
+/**
+ * - 验证结果
+ */
+export type ValidatePasswordReturn = {
+    /**
+     * - 验证结果，根据密码强度、是否包含非法字符得出
+     */
+    validated: boolean;
+    /**
+     * - 强度级别，包含数字/大小写字母/特殊字符
+     */
+    level: number;
+    /**
+     * - 包含内容
+     */
+    containes: PasswordContaines;
+};
+/**
+ * @typedef {Object} PasswordContaines - 验证密码的包含内容
+ * @property {boolean} number - 包含数字
+ * @property {boolean} lowerCaseLetter - 包含小写字母
+ * @property {boolean} upperCaseLetter - 包含大写字母
+ * @property {boolean} specialCharacter - 包含特殊字符
+ * @property {boolean} unallowableCharacter - 包含非法字符
+ */
+/**
+ * @typedef {Object} ValidatePasswordReturn - 验证结果
+ * @property {boolean} validated - 验证结果，根据密码强度、是否包含非法字符得出
+ * @property {number} level - 强度级别，包含数字/大小写字母/特殊字符
+ * @property {PasswordContaines} containes - 包含内容
+ */
 /**
  * 验证密码（数字、大小写字母、特殊字符、非法字符）
  *
@@ -11,7 +67,7 @@ export default validatePassword;
  * @param {number} [options.level=2] 密码强度 1-包含一种字符 2-包含两种字符 3-包含三种字符。（大写字母、小写字母、数字、特殊字符）
  * @param {boolean} [options.ignoreCase=false] 是否忽略大小写，为 ture 时，大小写字母视为一种字符
  * @param {string} [options.special="!@#$%^&*()-=_+[]\|{},./?<>~"] 支持的特殊字符
- * @returns 验证结果
+ * @returns {ValidatePasswordReturn} 验证结果
  * @example
  *
  * validatePassword('a12345678');
@@ -75,14 +131,4 @@ declare function validatePassword(value: string, { level, ignoreCase, special }?
     level?: number | undefined;
     ignoreCase?: boolean | undefined;
     special?: string | undefined;
-} | undefined): {
-    validated: boolean;
-    level: number;
-    containes: {
-        number: boolean;
-        lowerCaseLetter: boolean;
-        upperCaseLetter: boolean;
-        specialCharacter: boolean;
-        unallowableCharacter: boolean;
-    };
-};
+} | undefined): ValidatePasswordReturn;