a-js-tools 1.0.13-beta.5 → 2.0.0

package/cjs/isNode.js

@@ -0,0 +1,27 @@
+'use strict';
+
+var aTypeOfJs = require('a-type-of-js');
+
+/**
+ *
+ * 判断当前环境是否为 node 环境
+ *
+ */
+function isNode() {
+    return !aTypeOfJs.isUndefined((globalThis &&
+        globalThis.process &&
+        globalThis.process.versions &&
+        globalThis.process.versions.node) ||
+        undefined);
+}
+/**
+ *
+ * 是否为浏览器环境
+ *
+ */
+function isBrowser() {
+    return !isNode();
+}
+
+exports.isBrowser = isBrowser;
+exports.isNode = isNode;

package/cjs/object/createConstructor.js

@@ -0,0 +1,58 @@
+'use strict';
+
+/**
+ *
+ * 构建一个 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) {
+    constructor.prototype.apply = Function.apply;
+    constructor.prototype.bind = Function.bind;
+    constructor.prototype.call = Function.call;
+    constructor.prototype.length = Function.length;
+    // constructor.prototype.arguments = Function.arguments;
+    constructor.prototype.name = Function.name;
+    constructor.prototype.toString = Function.toString;
+    return constructor;
+}
+/** 对象的 assign 用法 */
+function ObjectAssign(target, bar) {
+    const keys = Object.keys(bar);
+    keys.forEach(key => (target[key] = bar[key]));
+    return target;
+}
+
+exports.ObjectAssign = ObjectAssign;
+exports.createConstructor = createConstructor;

package/cjs/performance.js

@@ -0,0 +1,124 @@
+'use strict';
+
+var aTypeOfJs = require('a-type-of-js');
+var isFunction = require('a-type-of-js/isFunction');
+var isNumber = require('a-type-of-js/isNumber');
+
+/**
+ * 防抖和节流
+ *
+ * @packageDocumentation
+ * @module @a-js-tools/performance
+ * @license MIT
+ */
+/**
+ *
+ * 防抖
+ *
+ * @param   callback 回调函数
+ * @param   options    延迟时间（毫秒），默认 200 (ms) 或包含 this 的配置
+ * @returns   返回的闭包函数
+ * @example
+ *
+ * ```ts
+ * const debounce = (callback: Function, delay = 300) => {
+ *   let timer: any = null
+ *   return (...args: any[]) => {
+ *     clearTimeout(timer)
+ *   }
+ * }
+ *
+ */
+function debounce(callback, options = 200) {
+    if (!isFunction.isFunction(callback))
+        throw new TypeError('callback must be a function');
+    if (isNumber.isNumber(options))
+        options = {
+            delay: options,
+            this: null,
+        };
+    if (aTypeOfJs.isUndefined(options.delay) ||
+        !isFinite(options.delay) ||
+        options.delay < 0)
+        // 强制转换非数值
+        options.delay = 200;
+    /**  定时器返回的 id  */
+    let timeoutId;
+    const clear = () => {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+            timeoutId = undefined;
+        }
+    };
+    const result = (...args) => {
+        clear();
+        timeoutId = setTimeout(() => {
+            try {
+                const _this = options && options.this ? options.this : null;
+                // 由于 Reflect.apply 并不能在 ES5 中使用，所以我们并不能保证能执行成功
+                callback.apply(_this, args);
+                // Reflect.apply(callback, options?.this ?? null, args);
+            }
+            catch (error) {
+                console.log('Debounce callback throw an error', error);
+            }
+        }, Math.max(options.delay || 5, 5));
+    };
+    result.cancel = () => clear();
+    return result;
+}
+/**
+ *   节流
+ *
+ * @param callback   回调函数
+ * @param options      延迟时间（毫秒），默认 200 (ms) 或设置 this
+ * @returns   返回的闭包函数
+ */
+function throttle(callback, options = 200) {
+    if (!isFunction.isFunction(callback))
+        throw new TypeError('callback must be a function');
+    if (isNumber.isNumber(options))
+        options = {
+            delay: options,
+            this: null,
+        };
+    if (aTypeOfJs.isUndefined(options.delay) ||
+        !isFinite(options.delay) ||
+        options.delay < 0)
+        // 强制转换非数值
+        options.delay = 200;
+    /**  延迟控制插销   */
+    let inThrottle = false;
+    /**  延迟控制   */
+    let timeoutId = null;
+    const delay = options && options.delay ? options.delay : 5;
+    const throttled = (...args) => {
+        if (inThrottle)
+            return;
+        try {
+            const _this = options && options.this ? options.this : null;
+            callback.apply(_this, args);
+        }
+        catch (error) {
+            console.error('Throttle 执行回调抛出问题', error);
+        }
+        inThrottle = true;
+        if (!aTypeOfJs.isNull(timeoutId))
+            clearTimeout(timeoutId);
+        timeoutId = setTimeout(() => {
+            inThrottle = false;
+            timeoutId = null;
+        }, Math.max(delay, 5));
+    };
+    throttled.cancel = () => {
+        if (!aTypeOfJs.isNull(timeoutId)) {
+            clearTimeout(timeoutId);
+        }
+        inThrottle = false;
+        timeoutId = null;
+    };
+    return throttled;
+}
+
+exports.debounce = debounce;
+exports.throttle = throttle;

package/cjs/regexp/autoEscapedRegExp.js

@@ -0,0 +1,48 @@
+'use strict';
+
+var aTypeOfJs = require('a-type-of-js');
+var escapeRegExp = require('./escapeRegExp.js');
+var parse = require('./parse.js');
+
+/**
+ *
+ * ##  适用于简单的文本字符串自动转化为简单模式正则表达式
+ *
+ * *若字符串包含且需保留字符类、组、反向引用、量词等时，该方法可能不适用*
+ *
+ * @param pattern 待转化的文本字符串
+ * @param options 转化选项。 为文本字符串时，默认为正则表达式的标志，还可指定是否匹配开头或结尾
+ * @returns 正则表达式
+ * @example
+ *
+ * ```ts
+ * import { autoEscapedRegExp } from 'a-regexp';
+ *
+ * autoEscapedRegExp('abc'); // => /abc/
+ * autoEscapedRegExp('abc', 'gim'); // => /abc/gim
+ * autoEscapedRegExp('abc',  { flags: 'g', start: true }); // => /^abc/g
+ * autoEscapedRegExp('abc',  { flags: 'g', end: true }); // => /abc$/g
+ * autoEscapedRegExp('abc',  { start: true, end: true }); // => /^abc$/
+ *
+ * // 转化特殊字符类、组、反向引用、量词等
+ * // 无法保留匹配规则
+ * autoEscapedRegExp('a-zA-Z0-9'); // => /a-zA-Z0-9/
+ * autoEscapedRegExp('a-zA-Z0-9', 'g'); // => /a-zA-Z0-9/g
+ * autoEscapedRegExp('[a-zA-Z0-9]'); // => /\[a-zA-Z0-9\]/
+ * autoEscapedRegExp('^[a-zA-Z0-9]+$'); // => /\^\[a-zA-Z0-9\]\$/
+ *
+ * ```
+ *
+ */
+function autoEscapedRegExp(pattern, options) {
+    if (!aTypeOfJs.isString(pattern))
+        throw new TypeError('pattern must be a 字符串');
+    pattern = escapeRegExp.escapeRegExp(pattern);
+    /** 简单转化  */
+    if (aTypeOfJs.isUndefined(options))
+        return new RegExp(pattern);
+    options = parse.parse(options);
+    return new RegExp(`${options.start ? '^' : ''}${pattern}${options.end ? '$' : ''}`, options.flags);
+}
+
+exports.autoEscapedRegExp = autoEscapedRegExp;

package/cjs/regexp/escapeRegExp.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ *
+ * 将一个字符串转化为符合正则要求的字符串
+ *
+ * @param str 需要转义的字符串
+ * @requires escapeRegExp 转化后字符串
+ * @example
+ *
+ * ```ts
+ *  import { escapeRegExp  } from 'a-js-tools';
+ *
+ *  escapeRegExp('a.b.c'); // 'a\\.b\\.c'
+ *  escapeRegExp('a\\.b\\.c'); // 'a\\\\.b\\\\.c'
+ *  escapeRegExp('[a-z]'); // '\\[a-z\\]'
+ *  escapeRegExp('^abc$'); // '\\^abc\\$'
+ * ```
+ */
+function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+exports.escapeRegExp = escapeRegExp;

package/cjs/regexp/parse.js

@@ -0,0 +1,32 @@
+'use strict';
+
+var aTypeOfJs = require('a-type-of-js');
+
+/**
+ *
+ * 解析 options
+ *
+ */
+function parse(options) {
+    // 处理 options
+    if (aTypeOfJs.isString(options)) {
+        options = {
+            flags: options,
+        };
+    }
+    // 处理 flags
+    if (!aTypeOfJs.isString(options.flags))
+        options.flags = '';
+    else {
+        // 需求是保留字符串中的某一部分，使用
+        const regexp = /[migsuy]/g;
+        const matchResult = options.flags.match(regexp);
+        if (aTypeOfJs.isNull(matchResult))
+            options.flags = '';
+        else
+            options.flags = [...new Set(matchResult)].join('');
+    }
+    return options;
+}
+
+exports.parse = parse;

package/cjs/sleep.js

@@ -0,0 +1,38 @@
+'use strict';
+
+var isNumber = require('a-type-of-js/isNumber');
+
+/**
+ *
+ * ## 线程休息
+ *
+ * 但从调用到执行完毕总是与期望的时间并不相吻合，除非执行是线型的（也不保证时间的严格性）
+ *
+ * - 宏任务：整体代码、setTimeout、DOM 事件回调、requestAnimationFrame、setImmediate、setInterval、I/O操作、UI渲染等
+ * - 微任务：Promise的then/catch/finally、process.nextTick（Node.js）、MutationObserver、queueMicrotask（显示添加微任务）等
+ *
+ * <span style="color:#ff0;">*Node.js中的process.nextTick优先级高于其他微任务*</span>
+ *
+ * @param delay 睡觉时长（机器时间，毫秒为单位）
+ * @returns 🈳
+ * @example
+ *
+ * ```ts
+ * import { sleep } from 'a-js-tools';
+ *
+ * console.log(Date.now()); // 1748058118471
+ * await sleep(1000);
+ * console.log(Date.now()); // 1748058119473
+ *
+ * ```
+ *
+ */
+async function sleep(delay = 1000) {
+    if (!isFinite(delay) || delay < 0)
+        throw new TypeError('delay 应该是一个正常的数值');
+    if (isNumber.isZero(delay))
+        return Promise.resolve();
+    return new Promise(resolve => setTimeout(resolve, delay));
+}
+
+exports.sleep = sleep;

package/es/array/difference.js

@@ -0,0 +1,49 @@
+import { isArray, isEmptyArray } from 'a-type-of-js';
+
+/**
+ *  求给出的两个数组的差值（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));
+ * ```
+ *
+ */
+function difference(a, b) {
+    if (!isArray(a) || !isArray(b)) {
+        throw new TypeError('参数需为数组');
+    }
+    if (isEmptyArray(a) || isEmptyArray(b)) {
+        return a;
+    }
+    /**  获取两个数组中长度较小的  */
+    // 参数有顺序要求
+    // const [shorter, longer] = a.length > b.length ? [b, a] : [a, b];
+    // const shorterSet = new Set(shorter);
+    const bSet = new Set(b);
+    return a.filter(i => !bSet.has(i));
+}
+
+export { difference };

package/es/array/index.js

@@ -0,0 +1,148 @@
+import { intersection } from './intersection.js';
+import { union } from './union.js';
+import { difference } from './difference.js';
+import { symmetricDifference } from './symmetricDifference.js';
+
+/**
+ *
+ * 数组的一些方法
+ *
+ * - 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,
+};
+
+export { difference, enArr, intersection, symmetricDifference, union };

package/es/array/intersection.js

@@ -0,0 +1,43 @@
+import { isArray, isEmptyArray } from 'a-type-of-js';
+
+/**
+ *
+ * 两个数组的交集
+ *
+ * @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]
+ *
+ * ```
+ *
+ */
+function intersection(a, b) {
+    if (!isArray(a) || !isArray(b)) {
+        throw new TypeError('参数必须是数组类型数据');
+    }
+    // 任意数组为空，则返回空数组
+    if (isEmptyArray(a) || isEmptyArray(b)) {
+        return [];
+    }
+    /**
+     * 在实际运算中， new Set() 的 开销为 O(n) ,filter 的开销也为 O(n)
+     *
+     * 但是以较短的数组创建 Set ，可以节省内存开销
+     */
+    const [shorter, longer] = a.length <= b.length ? [a, b] : [b, a];
+    // 提前创建工具 Set
+    const shortSet = new Set(shorter);
+    return longer.filter(item => shortSet.has(item));
+}
+
+export { intersection };

package/es/array/symmetricDifference.js

@@ -0,0 +1,49 @@
+import { isArray, isEmptyArray } from 'a-type-of-js';
+import { difference } from './difference.js';
+
+/**
+ *
+ * 对称差集 （ 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, []));
+ *
+ * ```
+ *
+ */
+function symmetricDifference(a, b) {
+    if (!isArray(a) || !isArray(b)) {
+        throw new TypeError('参数必须是数组');
+    }
+    if (isEmptyArray(a)) {
+        return [...b];
+    }
+    if (isEmptyArray(b)) {
+        return [...a];
+    }
+    return [...difference(a, b), ...difference(b, a)];
+}
+
+export { symmetricDifference };