util-helpers 4.19.4 → 4.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "util-helpers",
-  "version": "4.19.4",
+  "version": "4.20.0",
   "description": "一个基于业务场景的工具方法库",
   "main": "lib/index.js",
   "module": "esm/index.js",
@@ -50,31 +50,32 @@
   },
   "homepage": "https://doly-dev.github.io/util-helpers/index.html",
   "devDependencies": {
-    "@babel/core": "^7.22.5",
-    "@babel/preset-env": "^7.22.5",
+    "@babel/core": "^7.22.10",
+    "@babel/preset-env": "^7.22.10",
     "@babel/preset-typescript": "^7.22.5",
-    "@commitlint/cli": "^17.6.6",
-    "@commitlint/config-conventional": "^17.6.6",
-    "@rollup/plugin-commonjs": "^25.0.3",
-    "@rollup/plugin-node-resolve": "^15.1.0",
+    "@commitlint/cli": "^17.7.1",
+    "@commitlint/config-conventional": "^17.7.0",
+    "@rollup/plugin-commonjs": "^25.0.4",
+    "@rollup/plugin-node-resolve": "^15.2.1",
     "@rollup/plugin-replace": "^5.0.2",
     "@rollup/plugin-terser": "^0.4.3",
     "@rollup/plugin-typescript": "^11.1.2",
-    "@types/jest": "^29.5.2",
-    "@typescript-eslint/eslint-plugin": "^5.60.1",
-    "@typescript-eslint/parser": "^5.60.1",
-    "babel-jest": "^29.5.0",
+    "@types/jest": "^29.5.4",
+    "@typescript-eslint/eslint-plugin": "^5.62.0",
+    "@typescript-eslint/parser": "^5.62.0",
+    "babel-jest": "^29.6.3",
     "babel-plugin-minify-replace": "^0.5.0",
     "cross-env": "^7.0.3",
     "cz-conventional-changelog": "^3.3.0",
     "docdash": "^2.0.1",
-    "eslint": "^8.44.0",
-    "jest": "^29.5.0",
-    "jest-environment-jsdom": "^29.5.0",
+    "eslint": "^8.47.0",
+    "jest": "^29.6.3",
+    "jest-canvas-mock": "^2.5.2",
+    "jest-environment-jsdom": "^29.6.3",
     "jsdoc": "^4.0.2",
-    "lint-staged": "^13.2.3",
+    "lint-staged": "^13.3.0",
     "prettier": "^2.8.8",
-    "rollup": "^3.26.3",
+    "rollup": "^3.28.1",
     "typescript": "^5.1.6",
     "yorkie": "^2.0.0"
   },
@@ -92,7 +93,7 @@
     }
   },
   "dependencies": {
-    "tslib": "^2.6.0",
-    "ut2": "^1.3.2"
+    "tslib": "^2.6.2",
+    "ut2": "^1.4.4"
   }
 }

package/types/compressImage.d.ts

@@ -0,0 +1,27 @@
+type Info = {
+    image: HTMLImageElement;
+    blob: Blob;
+    canvas: HTMLCanvasElement;
+    context: CanvasRenderingContext2D;
+};
+type Options = {
+    width?: number;
+    height?: number;
+    rotate?: number;
+    offset?: [number, number] | ((info: Info, options: Options) => [number, number]);
+    cacheImage?: boolean;
+    background?: string;
+    canvasWidth?: number | ((info: Info, options: Options) => number);
+    canvasHeight?: number | ((info: Info, options: Options) => number);
+    format?: 'blob' | 'dataURL';
+    type?: string;
+    quality?: number;
+    beforeCompress?: (imageWithBlob: Pick<Info, 'image' | 'blob'>, options: Options) => void;
+    beforeDraw?: (info: Info, options: Options) => void;
+    afterDraw?: (info: Info, options: Options) => void;
+};
+declare function compressImage(img: string | Blob, options: Omit<Options, 'format'> & {
+    format: 'dataURL';
+}): Promise<string>;
+declare function compressImage(img: string | Blob, options?: Options): Promise<Blob>;
+export default compressImage;

package/types/divide.d.ts

@@ -4,7 +4,7 @@
  * @static
  * @alias module:Math.divide
  * @since 3.1.0
- * @param {...number|string} nums 被除数和除数
+ * @param {...(number|string)} nums 被除数和除数
  * @returns {number} 商数
  * @example
  *

package/types/download.d.ts

@@ -33,6 +33,8 @@ type DownloadOptions = {
  *
  * <em style="font-weight: bold;">注意：该方法仅适用于浏览器端，兼容 IE10+ 和现代浏览器。</em>
  *
+ * <em style="font-weight: bold;">注意：微信浏览器不支持H5下载文件。</em>
+ *
  * @static
  * @alias module:Other.download
  * @since 4.16.0

package/types/gcd.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 最大公约数，使用辗转相除法。
+ *
+ * 遵循以下约定：
+ *
+ * 1. 如果参数中包含无效数值，返回 `NaN` 。
+ * 2. 如果全部参数都为 `0` ，返回 `0` 。
+ * 3. 如果参数包含 `0` ，仅计算非零的数。
+ * 4. 如果参数为负数，将转为绝对值的正数。
+ * 5. 如果参数包含小数点，将转为四舍五入的整数。
+ *
+ * @static
+ * @alias module:Math.gcd
+ * @since 4.20.0
+ * @see {@link https://baike.baidu.com/item/最大公约数 | 最大公约数}
+ * @param {...(number|string)} nums 两个或多个整数。
+ * @returns {number} 最大公约数。
+ * @example
+ *
+ * gcd(8, 14); // 2
+ * gcd(57, 48); // 3
+ * gcd(140, 21, 42); // 7
+ * gcd('foo', 'bar'); // NaN
+ * gcd(0, 10); // 10
+ * gcd(2.3, 3.8, 8, -10); // 2
+ *
+ */
+declare function gcd(...nums: (string | number)[]): number;
+export default gcd;

package/types/getImageInfo.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 获取图片信息。
+ *
+ * <em style="font-weight: bold;">注意：该方法仅适用于浏览器端。</em>
+ *
+ * @static
+ * @alias module:Other.getImageInfo
+ * @since 4.20.0
+ * @param {string | Blob} img 图片地址或 blob 对象
+ * @param {boolean} [useCache=true] 缓存最近一次成功结果，当图片地址或 blob 对象一致时，直接返回该缓存。避免连续请求同一个图片资源，重复加载问题。
+ * @returns {Promise<ImageInfo>} 图片信息
+ * @example
+ *
+ * getImageInfo(file).then(imageInfo=>{
+ *    // do something
+ * });
+ *
+ * getImageInfo('https://dummyimage.com/200x300').then(imageInfo=>{
+ *   // do something
+ * });
+ *
+ * getImageInfo('data:image/png;base64,PGEgaWQ9ImEiPjxiIGlkPSJiIj5oZXkhPC9iPjwvYT4=').then(imageInfo=>{
+ *   // do something
+ * });
+ *
+ */
+declare function getImageInfo(img: string | Blob, useCache?: boolean): Promise<{
+    width: number;
+    height: number;
+    contrast: string;
+    measure: string;
+    size: string;
+    bytes: number;
+    image: HTMLImageElement;
+    blob: Blob;
+}>;
+export default getImageInfo;

package/types/index.d.ts

@@ -91,6 +91,8 @@ 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 gcd } from './gcd';
+export { default as lcm } from './lcm';
 /**
  * 其他
  *
@@ -99,7 +101,11 @@ export { default as round } from './round';
  */
 export { default as ajax } from './ajax';
 export { default as calculateCursorPosition } from './calculateCursorPosition';
+export { default as compressImage } from './compressImage';
 export { default as download } from './download';
+export { default as getImageInfo } from './getImageInfo';
+export { default as loadImage } from './loadImage';
+export { default as loadImageWithBlob } from './loadImageWithBlob';
 export { default as loadScript } from './loadScript';
 export { default as randomString } from './randomString';
 export { default as strlen } from './strlen';

package/types/lcm.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 最小公倍数。
+ *
+ * 遵循以下约定：
+ *
+ * 1. 如果参数中包含无效数值，返回 `NaN` 。
+ * 2. 如果只有一个参数，另一个参数默认为 `1` 。
+ * 3. 如果全部参数都为 `0` ，返回 `NaN` 。因为作为除数的最大公约数为 `0` ，结果为 `NaN` 。
+ * 4. 如果全部参数都为 `Infinity` ，返回 `NaN` 。因为除数和被除数都是 `Infinity` ，结果为 `NaN` 。
+ * 5. 如果参数包含 `0` ，返回 `0` 。
+ * 6. 如果参数为负数，将转为绝对值的正数。
+ * 7. 如果参数包含小数点，将转为四舍五入的整数。
+ *
+ * @static
+ * @alias module:Math.lcm
+ * @since 4.20.0
+ * @see {@link https://baike.baidu.com/item/最小公倍数 | 最小公倍数}
+ * @param {...(number|string)} nums 两个或多个整数。
+ * @returns {number} 最小公倍数。
+ * @example
+ *
+ * lcm(3, 4); // 12
+ * lcm(8, 4); // 8
+ * lcm(2, 4, 8); // 32
+ * lcm('foo', 'bar'); // NaN
+ * lcm(0, 10); // 0
+ * lcm(2.3, 3.8, 8, -10); // 320
+ *
+ */
+declare function lcm(...nums: (string | number)[]): number;
+export default lcm;

package/types/loadImage.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 加载图片。
+ *
+ * <em style="font-weight: bold;">注意：该方法仅适用于浏览器端。</em>
+ *
+ * @static
+ * @alias module:Other.loadImage
+ * @since 4.20.0
+ * @param {string | Blob} img 图片地址或 blob 对象
+ * @param {boolean} [useCache=true] 缓存最近一次成功结果，当图片地址或 blob 对象一致时，直接返回该缓存。避免连续请求同一个图片资源，重复加载问题。
+ * @returns {Promise<HTMLImageElement>} HTML图片元素
+ * @example
+ *
+ * loadImage(file).then(image=>{
+ *    // do something
+ * });
+ *
+ * loadImage('https://dummyimage.com/200x300').then(image=>{
+ *   // do something
+ * });
+ *
+ * loadImage('data:image/png;base64,PGEgaWQ9ImEiPjxiIGlkPSJiIj5oZXkhPC9iPjwvYT4=').then(image=>{
+ *   // do something
+ * });
+ *
+ */
+declare function loadImage(img: string | Blob, useCache?: boolean): Promise<HTMLImageElement>;
+export default loadImage;

package/types/loadImageWithBlob.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @typedef {Object} ImageWithBlob HTML图片元素和 blob 对象
+ * @property {HTMLImageElement} image HTML图片元素
+ * @property {Blob} blob blob 对象
+ */
+/**
+ * 加载图片，返回图片元素和 blob 对象。
+ *
+ * <em style="font-weight: bold;">注意：该方法仅适用于浏览器端。</em>
+ *
+ * @method
+ * @alias module:Other.loadImageWithBlob
+ * @since 4.20.0
+ * @param {string | Blob} img 图片地址或 blob 对象
+ * @param {boolean} [useCache=true] 缓存最近一次成功结果，当图片地址或 blob 对象一致时，直接返回该缓存。避免连续请求同一个图片资源，重复加载问题。
+ * @returns {Promise<ImageWithBlob>} HTML图片元素和 blob 对象
+ * @example
+ *
+ * loadImage(file).then(({image, blob})=>{
+ *    // do something
+ * });
+ *
+ * loadImage('https://dummyimage.com/200x300').then(({image, blob})=>{
+ *   // do something
+ * });
+ *
+ * loadImage('data:image/png;base64,PGEgaWQ9ImEiPjxiIGlkPSJiIj5oZXkhPC9iPjwvYT4=').then(({image, blob})=>{
+ *   // do something
+ * });
+ *
+ */
+declare function loadImageWithBlob(img: string | Blob, useCache?: boolean): Promise<{
+    image: HTMLImageElement;
+    blob: Blob;
+}>;
+export default loadImageWithBlob;

package/types/loadScript.d.ts

@@ -5,15 +5,17 @@ type ScriptAttribute = Pick<HTMLScriptElement, 'async' | 'crossOrigin' | 'defer'
 /**
  * 加载 js 文件。
  *
- * 默认属性 `async=true` `type=text/javascript` 。如果加载失败，默认会删除该 `script` 的 `dom` 标签。
- *
  * <em style="font-weight: bold;">注意：该方法仅适用于浏览器端。</em>
  *
  * @static
  * @alias module:Other.loadScript
  * @since 4.19.0
  * @param {string} src  js 地址。
- * @param {Object} [options] script 标签属性。比如 `async` `defer` `onload` `onerror` `id` 等。如果需要设置属性，可以使用 `attrs` 。如果加载失败或错误不想删除，可以使用 `destroyOnError=false` 。
+ * @param {Object} [options] script 标签属性。比如 `defer` `onload` `onerror` `id` 等，下面列举部分带有默认值或额外扩展的配置。
+ * @param {boolean} [options.destroyOnError=true] 如果加载失败或错误，自动删除 dom 中的 script 标签。
+ * @param {Object} [options.attrs] 自定义 script 属性，通过 script.setAttribute 设置。
+ * @param {boolean} [options.async=true] 异步加载。
+ * @param {string} [options.type='text/javascript'] 类型。
  * @return {Promise<HTMLScriptElement>} 异步返回 script 元素。
  * @example
  *

package/types/minus.d.ts

@@ -4,7 +4,7 @@
  * @static
  * @alias module:Math.minus
  * @since 3.1.0
- * @param {...number|string} nums 相减的数
+ * @param {...(number|string)} nums 相减的数
  * @returns {number} 差
  * @example
  *

package/types/plus.d.ts

@@ -4,7 +4,7 @@
  * @static
  * @alias module:Math.plus
  * @since 3.1.0
- * @param {...number|string} nums 相加的数
+ * @param {...(number|string)} nums 相加的数
  * @returns {number} 总和
  * @example
  *

package/types/times.d.ts

@@ -4,7 +4,7 @@
  * @static
  * @alias module:Math.times
  * @since 3.1.0
- * @param {...number|string} nums 相乘的数
+ * @param {...(number|string)} nums 相乘的数
  * @returns {number} 乘积
  * @example
  *