a-js-tools 0.6.0 → 0.6.2

package/LICENSE

@@ -1,5 +1,7 @@
-Copyright (c) <2024> <earthnut.dev>
+# MIT License
 
+Copyright (c) <2024> <earthnut.dev>
+    
 Permission to use, copy, modify, and/or distribute this software for any  
 purpose with or without fee is hereby granted, provided that the above  
 copyright notice and this permission notice appear in all copies.
@@ -11,3 +13,13 @@ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN  
 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF  
 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+# MIT 许可证
+
+版权所有 (c) [2024] [花生亻]
+
+特此免费授予任何获得本软件及相关文档文件（以下简称“软件”）副本的人不受限制地处置该软件的权利，包括不受限制地使用、复制、修改、合并、发布、分发、再许可和/或出售该软件副本的权利，并允许向其提供该软件的人这样做，但须遵守以下条件：
+
+上述版权声明和本许可声明应包含在所有副本或软件的重要部分中。
+
+软件按“原样”提供，不附带任何形式的明示或暗示的保证，包括但不限于适销性、特定用途适用性和不侵权的保证。在任何情况下，作者或版权持有人均不对因合同、侵权或其他方式引起的任何索赔、损害或其他责任负责，无论是在与软件或软件的使用或其他交易有关的任何诉讼中。

package/README.md

@@ -1,4 +1,4 @@
-# a-js-tools
+# 一点点 🤏 js 函数
 
 [![version](<https://img.shields.io/npm/v/a-js-tools.svg?logo=npm&logoColor=rgb(0,0,0)&label=版本号&labelColor=rgb(73,73,228)&color=rgb(0,0,0)>)](https://www.npmjs.com/package/a-js-tools) [![Coverage Status](<https://img.shields.io/coverallsCoverage/github/earthnutDev/a-js-tools?logo=coveralls&label=coveralls&labelColor=rgb(12, 244, 39)&color=rgb(0,0,0)>)](https://coveralls.io/github/earthnutDev/a-js-tools?branch=main) [![codecov](<https://img.shields.io/codecov/c/github/earthnutDev/a-js-tools/main?logo=codecov&label=codecov&labelColor=rgb(7, 245, 245)&color=rgb(0,0,0)>)](https://codecov.io/gh/earthnutDev/a-js-tools) [![issues 提交](<https://img.shields.io/badge/issues-提交-rgb(255,0,63)?logo=github>)](https://github.com/earthnutDev/a-js-tools/issues)
 一个纯函数的工具
@@ -6,7 +6,7 @@
 ## 安装
 
 ```sh
-npm install   a-js-tools  --save
+npm install --save a-js-tools
 ```
 
 ## 纯函数

package/cjs/src/array/index.cjs

@@ -5,10 +5,145 @@ var union = require('./union.cjs');
 var difference = require('./difference.cjs');
 var symmetricDifference = require('./symmetricDifference.cjs');
 
+/**
+ *
+ * 数组的一些方法
+ *
+ * - union 两个数组的并集（排除共有项）
+ * - intersection 两个数组的交集（共有项）
+ * - difference 两个数组的差集 （A - B）
+ * - symmetricDifference  对称差集 （ A △ B）
+ *
+ */
 const enArr = {
+    /**
+     *
+     * 数组的并集
+     *
+     *  <span style="color:#f36;">请注意，参数有不为数组时直接抛出 TypeError</span>
+     * @param arrays  - 多个数组
+     * @returns 联合后的数组
+     *
+     *
+     * @example
+     *
+     * ```ts
+     * import { union } from 'a-js-tools';
+     *
+     * const log = console.log;
+     *
+     * // []
+     * log(union());
+     *
+     * // [1, 2, 3]
+     * log(union([1, 2, 3]));
+     *
+     * //  TypeError
+     * log(union([1, 2, 3], 'i'));
+     * log(union([1, 2, 3], undefined));
+     * log(union([1, 2, 3], null));
+     * log(union([1, 2, 3], 4));
+     * log(union([1, 2, 3], {}));
+     * log(union([1, 2, 3], false));
+     *
+     * // [1, 2, 3, 4, 6]
+     * log(union([1, 2, 3], [2, 4, 6]));
+     *
+     * // [1, 2, 3, 4, 6]
+     * log(union([1, 2, 3], [2, 4, 6], [1, 2, 3]));
+     *
+     * // [1, 2, 3, 4, 6]
+     * log(union([1, 2, 3], [2, 4, 6], [1, 2, 3], [1, 2, 3]));
+     * ```
+     *
+     */
     union: union.union,
+    /**
+     *
+     * 两个数组的交集
+     *
+     * @param a 数组 1️⃣
+     * @param b 数组 2️⃣
+     * @returns 返回两个数组的交集
+     * @example
+     *
+     * ```ts
+     * import { intersection } from 'a-js-tools';
+     *
+     * const log = console.log;
+     *
+     *
+     * log(intersection([1, 2, 3, 4], [2, 3])); // [2, 3]
+     * log(intersection([1, 3, 5, 7], [2, 3, 4])); // [3]
+     *
+     * ```
+     *
+     */
     intersection: intersection.intersection,
+    /**
+     *  求给出的两个数组的差值（A - B）
+     *
+     * @param a  - 第一个数组
+     * @param b - 第二个数组
+     * @throws {TypeError} 当两个参数有一个不是
+     * @description 当两个参数有一个不是数组时将抛出
+     * @returns 返回第一个参数相对第二个参数的差值
+     * @example
+     *
+     * ```ts
+     * import { difference} from 'a-js-tools';
+     *
+     * const log = console.log;
+     *
+     *
+     * log(difference([], [1, 2, 3])); // []
+     *
+     * log([1, 2, 3], []); //[1, 2, 3]
+     *
+     * log([1, 2, 3, 4, 5, 6, 7], [1, 2, 3, 4, 5]); //[6, 7]
+     *
+     * // 将抛出 TypeError
+     * log(difference([1, 2, 3], 'a'));
+     * log(difference([1, 2, 3], 1));
+     * log(difference([1, 2, 3], undefined));
+     * log(difference([1, 2, 3], null));
+     * log(difference([1, 2, 3],  true));
+     * ```
+     *
+     */
     difference: difference.difference,
+    /**
+     *
+     * 对称差集 （ A △ B）
+     *
+     * @param a  - 数组 a
+     * @param b  - 数组 b
+     * @returns - 返回一个全新的数组
+     *
+     * @example
+     *
+     * ```ts
+     * import { symmetricDifference } from 'a-js-tools';
+     *
+     * const log = console.log;
+     *
+     * log(symmetricDifference([1, 2], [2, 3])); // [1, 3]
+     *
+     * log(symmetricDifference([1, 2, 3], [1, 2, 4])); // [3, 4]
+     *
+     * log(symmetricDifference([1, 2, 3], [1, 2, 3])); // []
+     *
+     *
+     * /// TypeError
+     * log(symmetricDifference(1, []));
+     * log(symmetricDifference(undefined, []));
+     * log(symmetricDifference(null, []));
+     * log(symmetricDifference('a', []));
+     * log(symmetricDifference(true, []));
+     *
+     * ```
+     *
+     */
     symmetricDifference: symmetricDifference.symmetricDifference,
 };
 

package/cjs/src/object/createConstructor.cjs

@@ -4,6 +4,38 @@
  *
  * 构建一个 Constructor 构造函数
  *
+ * 接收一个构造函数，然后返回 TS 能识别的构造函数自身
+ *
+ * 函数本身并没有执行任何逻辑，仅是简单的返回了实参自身
+ *
+ * 而经过该函数的包装，构造函数成了能够被 TS 识别为可用 new 实例的构造函数
+ *
+ * @param constructor - 传入一个构造函数
+ * @returns 返回传入的构造函数
+ *
+ * ```ts
+ * import { createConstructor } from "a-js-tools";
+ *
+ * type Tom = {
+ *   a: number
+ * }
+ *
+ * function _Tom (this: TomType): Tom {
+ *    this.a = 1;
+ *
+ *    return this;
+ * }
+ *
+ * // 逻辑上没有错，但是会造成 ts 显示
+ * // 其目标缺少构造签名的 "new" 表达式隐式具有 "any" 类型。ts(7009)
+ * const a = new _Tom();
+ *
+ * const tomConstructor = createConstructor(_tom);
+ *
+ * const b = new tomConstructor(); // 这时就不会显示错误
+ *
+ * ```
+ *
  */
 function createConstructor(constructor) {
     return constructor;

package/mjs/src/array/index.mjs

@@ -3,10 +3,145 @@ import { union } from './union.mjs';
 import { difference } from './difference.mjs';
 import { symmetricDifference } from './symmetricDifference.mjs';
 
+/**
+ *
+ * 数组的一些方法
+ *
+ * - union 两个数组的并集（排除共有项）
+ * - intersection 两个数组的交集（共有项）
+ * - difference 两个数组的差集 （A - B）
+ * - symmetricDifference  对称差集 （ A △ B）
+ *
+ */
 const enArr = {
+    /**
+     *
+     * 数组的并集
+     *
+     *  <span style="color:#f36;">请注意，参数有不为数组时直接抛出 TypeError</span>
+     * @param arrays  - 多个数组
+     * @returns 联合后的数组
+     *
+     *
+     * @example
+     *
+     * ```ts
+     * import { union } from 'a-js-tools';
+     *
+     * const log = console.log;
+     *
+     * // []
+     * log(union());
+     *
+     * // [1, 2, 3]
+     * log(union([1, 2, 3]));
+     *
+     * //  TypeError
+     * log(union([1, 2, 3], 'i'));
+     * log(union([1, 2, 3], undefined));
+     * log(union([1, 2, 3], null));
+     * log(union([1, 2, 3], 4));
+     * log(union([1, 2, 3], {}));
+     * log(union([1, 2, 3], false));
+     *
+     * // [1, 2, 3, 4, 6]
+     * log(union([1, 2, 3], [2, 4, 6]));
+     *
+     * // [1, 2, 3, 4, 6]
+     * log(union([1, 2, 3], [2, 4, 6], [1, 2, 3]));
+     *
+     * // [1, 2, 3, 4, 6]
+     * log(union([1, 2, 3], [2, 4, 6], [1, 2, 3], [1, 2, 3]));
+     * ```
+     *
+     */
     union,
+    /**
+     *
+     * 两个数组的交集
+     *
+     * @param a 数组 1️⃣
+     * @param b 数组 2️⃣
+     * @returns 返回两个数组的交集
+     * @example
+     *
+     * ```ts
+     * import { intersection } from 'a-js-tools';
+     *
+     * const log = console.log;
+     *
+     *
+     * log(intersection([1, 2, 3, 4], [2, 3])); // [2, 3]
+     * log(intersection([1, 3, 5, 7], [2, 3, 4])); // [3]
+     *
+     * ```
+     *
+     */
     intersection,
+    /**
+     *  求给出的两个数组的差值（A - B）
+     *
+     * @param a  - 第一个数组
+     * @param b - 第二个数组
+     * @throws {TypeError} 当两个参数有一个不是
+     * @description 当两个参数有一个不是数组时将抛出
+     * @returns 返回第一个参数相对第二个参数的差值
+     * @example
+     *
+     * ```ts
+     * import { difference} from 'a-js-tools';
+     *
+     * const log = console.log;
+     *
+     *
+     * log(difference([], [1, 2, 3])); // []
+     *
+     * log([1, 2, 3], []); //[1, 2, 3]
+     *
+     * log([1, 2, 3, 4, 5, 6, 7], [1, 2, 3, 4, 5]); //[6, 7]
+     *
+     * // 将抛出 TypeError
+     * log(difference([1, 2, 3], 'a'));
+     * log(difference([1, 2, 3], 1));
+     * log(difference([1, 2, 3], undefined));
+     * log(difference([1, 2, 3], null));
+     * log(difference([1, 2, 3],  true));
+     * ```
+     *
+     */
     difference,
+    /**
+     *
+     * 对称差集 （ A △ B）
+     *
+     * @param a  - 数组 a
+     * @param b  - 数组 b
+     * @returns - 返回一个全新的数组
+     *
+     * @example
+     *
+     * ```ts
+     * import { symmetricDifference } from 'a-js-tools';
+     *
+     * const log = console.log;
+     *
+     * log(symmetricDifference([1, 2], [2, 3])); // [1, 3]
+     *
+     * log(symmetricDifference([1, 2, 3], [1, 2, 4])); // [3, 4]
+     *
+     * log(symmetricDifference([1, 2, 3], [1, 2, 3])); // []
+     *
+     *
+     * /// TypeError
+     * log(symmetricDifference(1, []));
+     * log(symmetricDifference(undefined, []));
+     * log(symmetricDifference(null, []));
+     * log(symmetricDifference('a', []));
+     * log(symmetricDifference(true, []));
+     *
+     * ```
+     *
+     */
     symmetricDifference,
 };
 

package/mjs/src/object/createConstructor.mjs

@@ -2,6 +2,38 @@
  *
  * 构建一个 Constructor 构造函数
  *
+ * 接收一个构造函数，然后返回 TS 能识别的构造函数自身
+ *
+ * 函数本身并没有执行任何逻辑，仅是简单的返回了实参自身
+ *
+ * 而经过该函数的包装，构造函数成了能够被 TS 识别为可用 new 实例的构造函数
+ *
+ * @param constructor - 传入一个构造函数
+ * @returns 返回传入的构造函数
+ *
+ * ```ts
+ * import { createConstructor } from "a-js-tools";
+ *
+ * type Tom = {
+ *   a: number
+ * }
+ *
+ * function _Tom (this: TomType): Tom {
+ *    this.a = 1;
+ *
+ *    return this;
+ * }
+ *
+ * // 逻辑上没有错，但是会造成 ts 显示
+ * // 其目标缺少构造签名的 "new" 表达式隐式具有 "any" 类型。ts(7009)
+ * const a = new _Tom();
+ *
+ * const tomConstructor = createConstructor(_tom);
+ *
+ * const b = new tomConstructor(); // 这时就不会显示错误
+ *
+ * ```
+ *
  */
 function createConstructor(constructor) {
     return constructor;

package/package.json

@@ -1,11 +1,11 @@
 {
   "type": "module",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "name": "a-js-tools",
   "description": "一点点 🤏  js 函数",
-  "license": "ISC",
+  "license": "MIT",
   "dependencies": {
-    "a-type-of-js": ">=0.2.0 <1.0.0"
+    "a-type-of-js": ">=0.3.0 <1.0.0"
   },
   "main": "cjs/index.cjs",
   "module": "mjs/index.mjs",
@@ -42,7 +42,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "engines": {
-    "node": ">=12.0.0"
+    "node": ">=15.0.0"
   },
   "browserslist": [
     "last 2 versions not ie <= 11"

package/types/src/array/index.d.ts

@@ -3,9 +3,144 @@ import { union } from './union';
 import { difference } from './difference';
 import { symmetricDifference } from './symmetricDifference';
 export { union, intersection, difference, symmetricDifference };
+/**
+ *
+ * 数组的一些方法
+ *
+ * - union 两个数组的并集（排除共有项）
+ * - intersection 两个数组的交集（共有项）
+ * - difference 两个数组的差集 （A - B）
+ * - symmetricDifference  对称差集 （ A △ B）
+ *
+ */
 export declare const enArr: {
+    /**
+     *
+     * 数组的并集
+     *
+     *  <span style="color:#f36;">请注意，参数有不为数组时直接抛出 TypeError</span>
+     * @param arrays  - 多个数组
+     * @returns 联合后的数组
+     *
+     *
+     * @example
+     *
+     * ```ts
+     * import { union } from 'a-js-tools';
+     *
+     * const log = console.log;
+     *
+     * // []
+     * log(union());
+     *
+     * // [1, 2, 3]
+     * log(union([1, 2, 3]));
+     *
+     * //  TypeError
+     * log(union([1, 2, 3], 'i'));
+     * log(union([1, 2, 3], undefined));
+     * log(union([1, 2, 3], null));
+     * log(union([1, 2, 3], 4));
+     * log(union([1, 2, 3], {}));
+     * log(union([1, 2, 3], false));
+     *
+     * // [1, 2, 3, 4, 6]
+     * log(union([1, 2, 3], [2, 4, 6]));
+     *
+     * // [1, 2, 3, 4, 6]
+     * log(union([1, 2, 3], [2, 4, 6], [1, 2, 3]));
+     *
+     * // [1, 2, 3, 4, 6]
+     * log(union([1, 2, 3], [2, 4, 6], [1, 2, 3], [1, 2, 3]));
+     * ```
+     *
+     */
     union: typeof union;
+    /**
+     *
+     * 两个数组的交集
+     *
+     * @param a 数组 1️⃣
+     * @param b 数组 2️⃣
+     * @returns 返回两个数组的交集
+     * @example
+     *
+     * ```ts
+     * import { intersection } from 'a-js-tools';
+     *
+     * const log = console.log;
+     *
+     *
+     * log(intersection([1, 2, 3, 4], [2, 3])); // [2, 3]
+     * log(intersection([1, 3, 5, 7], [2, 3, 4])); // [3]
+     *
+     * ```
+     *
+     */
     intersection: typeof intersection;
+    /**
+     *  求给出的两个数组的差值（A - B）
+     *
+     * @param a  - 第一个数组
+     * @param b - 第二个数组
+     * @throws {TypeError} 当两个参数有一个不是
+     * @description 当两个参数有一个不是数组时将抛出
+     * @returns 返回第一个参数相对第二个参数的差值
+     * @example
+     *
+     * ```ts
+     * import { difference} from 'a-js-tools';
+     *
+     * const log = console.log;
+     *
+     *
+     * log(difference([], [1, 2, 3])); // []
+     *
+     * log([1, 2, 3], []); //[1, 2, 3]
+     *
+     * log([1, 2, 3, 4, 5, 6, 7], [1, 2, 3, 4, 5]); //[6, 7]
+     *
+     * // 将抛出 TypeError
+     * log(difference([1, 2, 3], 'a'));
+     * log(difference([1, 2, 3], 1));
+     * log(difference([1, 2, 3], undefined));
+     * log(difference([1, 2, 3], null));
+     * log(difference([1, 2, 3],  true));
+     * ```
+     *
+     */
     difference: typeof difference;
+    /**
+     *
+     * 对称差集 （ A △ B）
+     *
+     * @param a  - 数组 a
+     * @param b  - 数组 b
+     * @returns - 返回一个全新的数组
+     *
+     * @example
+     *
+     * ```ts
+     * import { symmetricDifference } from 'a-js-tools';
+     *
+     * const log = console.log;
+     *
+     * log(symmetricDifference([1, 2], [2, 3])); // [1, 3]
+     *
+     * log(symmetricDifference([1, 2, 3], [1, 2, 4])); // [3, 4]
+     *
+     * log(symmetricDifference([1, 2, 3], [1, 2, 3])); // []
+     *
+     *
+     * /// TypeError
+     * log(symmetricDifference(1, []));
+     * log(symmetricDifference(undefined, []));
+     * log(symmetricDifference(null, []));
+     * log(symmetricDifference('a', []));
+     * log(symmetricDifference(true, []));
+     *
+     * ```
+     *
+     */
     symmetricDifference: typeof symmetricDifference;
 };

package/types/src/object/createConstructor.d.ts

@@ -2,6 +2,7 @@
  *
  * 构建构建的构建函数
  *
+ *
  */
 export interface CreateConstructor<T, Args extends unknown[] = unknown[]> {
     new (...args: Args): T;
@@ -10,5 +11,37 @@ export interface CreateConstructor<T, Args extends unknown[] = unknown[]> {
  *
  * 构建一个 Constructor 构造函数
  *
+ * 接收一个构造函数，然后返回 TS 能识别的构造函数自身
+ *
+ * 函数本身并没有执行任何逻辑，仅是简单的返回了实参自身
+ *
+ * 而经过该函数的包装，构造函数成了能够被 TS 识别为可用 new 实例的构造函数
+ *
+ * @param constructor - 传入一个构造函数
+ * @returns 返回传入的构造函数
+ *
+ * ```ts
+ * import { createConstructor } from "a-js-tools";
+ *
+ * type Tom = {
+ *   a: number
+ * }
+ *
+ * function _Tom (this: TomType): Tom {
+ *    this.a = 1;
+ *
+ *    return this;
+ * }
+ *
+ * // 逻辑上没有错，但是会造成 ts 显示
+ * // 其目标缺少构造签名的 "new" 表达式隐式具有 "any" 类型。ts(7009)
+ * const a = new _Tom();
+ *
+ * const tomConstructor = createConstructor(_tom);
+ *
+ * const b = new tomConstructor(); // 这时就不会显示错误
+ *
+ * ```
+ *
  */
 export declare function createConstructor<T, Args extends unknown[] = unknown[]>(constructor: (...argumentList: Args) => T): CreateConstructor<T, Args>;