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

package/es/array/union.js

@@ -0,0 +1,63 @@
+import { isEmptyArray, isArray } from 'a-type-of-js';
+
+/**
+ *
+ * 数组的并集
+ *
+ *  <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]));
+ * ```
+ *
+ */
+function union(...arrays) {
+    if (isEmptyArray(arrays)) {
+        return [];
+    }
+    if (arrays.some(i => !isArray(i))) {
+        throw new TypeError('参数必须都是数组形式的元素');
+    }
+    if (arrays.length === 1) {
+        return [...arrays[0]];
+    }
+    const resultSet = new Set();
+    for (const array of arrays) {
+        for (const item of array) {
+            resultSet.add(item);
+        }
+    }
+    return Array.from(resultSet);
+}
+
+export { union };

package/es/className.js

@@ -0,0 +1,55 @@
+/**
+ * 驼峰命名与连字符命名法的互换
+ *
+ * @packageDocumentation
+ * @module @a-js-tools/class-name
+ * @license MIT
+ */
+/**
+ *
+ * 连字符连接转化为小/大驼峰命名法
+ *
+ * @param str    待转化文本
+ * @param dividingType   连字符，缺省值为 "-"
+ * @param initial 是否转换第一个字符。默认值为 false （小驼峰类型）
+ * @returns 驼峰命名法字符串（e.g. “helloWorld”）
+ *
+ */
+function toLowerCamelCase(
+/**  待转化文本  */
+str, 
+/**  连字符，缺省值为 "-"  */
+dividingType = '-', 
+/** 是否转换第一个字符。默认值为 false （小驼峰类型） */
+initial = false) {
+    let result = str;
+    /**
+     * 匹配规则
+     *
+     * - 匹配到分隔符，将分隔符后面的字符转化为大写
+     */
+    const template = /[\\]|[\^]|[?]|[-]|[.]|[(]|[)]|[|]|[[]\[\]]|[{]|[}]|[+]|[*]|[$]/;
+    /**  转化首字符   */
+    const toTransform = (_str, _dividingType) => _str.replace(new RegExp(`${template.test(_dividingType) ? `\\${_dividingType}` : _dividingType}([a-zA-Z])`, 'g'), (match, p1) => p1.toUpperCase());
+    // 多分隔符转化
+    dividingType
+        .split('')
+        .forEach((item) => (result = toTransform(result, item)));
+    return initial
+        ? result.replace(/^./, (match) => match.toUpperCase())
+        : result;
+}
+/**
+ * 驼峰命名法转化为连字符连接
+ *
+ * @param str          待转化文本
+ * @param dividingType       分割符
+ * @returns 分割符转化的文本 (e.g. 'hello-world')
+ *
+ */
+function toSplitCase(str, dividingType = '-') {
+    const result = str.replace(/[A-Z]/g, (match) => dividingType.concat(match.toLowerCase()));
+    return result.startsWith(dividingType) ? result.substring(1) : result;
+}
+
+export { toLowerCamelCase, toSplitCase };

package/es/getRandomNumber.js

@@ -0,0 +1,73 @@
+import { isNaN, isNumber } from 'a-type-of-js';
+
+/**
+ * 过去随机数
+ *
+ * @packageDocumentation
+ * @module @a-js-tools/get-random-number
+ * @license MIT
+ */
+/**
+ *
+ * 获取一个随机的整数类型
+ *
+ * 您可以传入两个参数并获取它们之间的任意数字，返回值<span style="color:#ff0;">*会包含端值*</span>
+ *
+ * 如果只传递一个参数，则如果提供的值为负数，则得到一个小于（或大于）该数字的整数
+ *
+ * @param   max 较大值 ，不允许为`NaN`
+ * @param   min 较小值，不允许为 `NaN`
+ * @returns  任意的整数
+ */
+function getRandomInt(max = 1, min = 0) {
+    //  判断是否为 NaN 或 不是数字
+    if (!isFinite(max) ||
+        !isFinite(min) ||
+        isNaN(max) ||
+        isNaN(min) ||
+        !isNumber(max) ||
+        !isNumber(min)) {
+        throw new TypeError('getRandomInt: max or min is NaN or is not a number');
+    }
+    /**  获取最小值  */
+    let _min = Math.ceil(Number(min)), 
+    /**  获取最大值  */
+    _max = Math.floor(Number(max));
+    //  两值相等时，直接返回最大值
+    if (_max === _min)
+        return _max;
+    //  两值交换
+    if (_min > _max)
+        [_max, _min] = [_min, _max];
+    return Math.round(Math.random() * (_max - _min) + _min);
+}
+/**
+ *
+ * 获取任意的浮点数
+ *
+ * 您可以传入两个参数并获取它们之间的任意数字
+ *
+ * 如果只传入一个参数，则如果提供的值为负数，则获取小于（或大于）该数字的浮点数
+ *
+ * @param   max 较大数，缺省值为 1
+ * @param min 较小值，缺省值为 0
+ * @returns  任意的浮点数
+ */
+function getRandomFloat(max = 1, min = 0) {
+    //  判断是否为 NaN 或 不是数字
+    if (!isFinite(max) ||
+        !isFinite(min) ||
+        isNaN(max) ||
+        isNaN(min) ||
+        !isNumber(max) ||
+        !isNumber(min)) {
+        throw new TypeError('getRandomInt: max or min is NaN or is not a number');
+    }
+    if (max == min)
+        max++;
+    if (min > max)
+        [max, min] = [min, max];
+    return Math.random() * (max - min) + min;
+}
+
+export { getRandomFloat, getRandomInt };

package/es/getRandomString.js

@@ -0,0 +1,124 @@
+import { isPlainObject, isNumber, isNaN, isUndefined } from 'a-type-of-js';
+import { ObjectAssign } from './object/createConstructor.js';
+import { getRandomInt } from './getRandomNumber.js';
+
+/**
+ * 获取随机字符串
+ *
+ * @packageDocumentation
+ * @module @a-js-tools/get-random-string
+ * @license MIT
+ */
+/**
+ *
+ *  获取简单的随机字符串
+ *
+ *  @param   options - 字符串长度
+ *  @returns  - 随机字符串
+ *
+ *
+ */
+function getRandomString(options) {
+    //   验证输入参数
+    if (
+    // 参数类型错误
+    (!isPlainObject(options) && !isNumber(options)) ||
+        // 参数为 NaN
+        (isNumber(options) && isNaN(options)) ||
+        // 参数为数字时为无穷大
+        (isNumber(options) && !isFinite(options)) ||
+        // 参数为数字时为非整数
+        (isNumber(options) && !Number.isInteger(options)) ||
+        // 参数为数字时为负数
+        (isNumber(options) && Number.isInteger(options) && options < 1) ||
+        // 参数为数值然而却小于 1
+        (isNumber(options) && options < 1) ||
+        // 参数为对象但是 length 属性非数值
+        (isPlainObject(options) &&
+            (!isNumber(options.length) ||
+                options.length < 1 ||
+                !Number.isInteger(options.length))))
+        throw new TypeError('参数类型错误 ❌ (getRandomString)');
+    const initOptions = {
+        length: 32,
+        chars: 'abcdefghijklmnopqrstuvwxyz',
+        chars2: '0123456789',
+        chars3: '!@#$%^&*()_+~`|}{[]:;?><,./-=',
+        type: 'string',
+        includeUppercaseLetters: false,
+        includeNumbers: false,
+        includeSpecial: false,
+    };
+    /// 生成 UUID
+    if (initOptions.type === 'uuid')
+        return crypto.randomUUID();
+    // 验证输入参数
+    if (isNumber(options) && Number.isInteger(options) && options > 0)
+        ObjectAssign(initOptions, { length: options });
+    if (isPlainObject(options)) {
+        ObjectAssign(initOptions, options);
+        initOptions.length = initOptions.length < 1 ? 32 : initOptions.length;
+    }
+    /**  生成随机字符串  */
+    const templateCharsArr = initOptions.chars.split('');
+    // 添加大写字母
+    if (initOptions.includeUppercaseLetters)
+        interleaveString(templateCharsArr, initOptions.chars.toUpperCase());
+    // 添加数字
+    if (initOptions.includeNumbers)
+        interleaveString(templateCharsArr, initOptions.chars2);
+    // 添加特殊字符
+    if (initOptions.includeSpecial)
+        interleaveString(templateCharsArr, initOptions.chars3);
+    /** 结果字符串 */
+    let result = '';
+    /** 混淆后的字符串 */
+    const str = templateCharsArr.join('');
+    /** 混淆后字符长度 */
+    const strLen = str.length;
+    if (globalThis && globalThis.crypto && globalThis.crypto.getRandomValues) {
+        // 使用密码学安全的随机数生成器
+        const bytes = globalThis.crypto.getRandomValues(new Uint8Array(initOptions.length));
+        /**  获取最后的 chars 数据  */
+        // 循环遍历
+        bytes.forEach(byte => (result += str[byte % strLen]));
+    }
+    else {
+        for (let i = 0; i < initOptions.length; i++)
+            result += str[getRandomInt(strLen - 1)];
+    }
+    /**
+     *
+     *  字符串交叉函数
+     *
+     *  非线形串交叉，对相交叉
+     *
+     *  @param  str1 - 字符串1
+     *  @param  str2 - 字符串2
+     *  @returns - 交叉后的字符串
+     *  @example
+     *  ```ts
+     *  interleaveString('abc', '123') // 'a1b2c3'
+     *  ```
+     */
+    function interleaveString(str1, str2) {
+        const str1Length = str1.length, str2Length = str2.length;
+        const maxLength = Math.max(str1Length, str2Length);
+        for (let i = 0; i < maxLength; i++) {
+            if (i < str1Length && !isUndefined(str2[i])) {
+                str1[i] += str2[i];
+            }
+            else if (i < str2Length) {
+                str1[i] = str2[i];
+            }
+        }
+    }
+    /// 结果字符串不包含字符
+    if (!/[a-zA-Z]/.test(result))
+        return String.fromCharCode(getRandomInt(97, 122)).concat(result.slice(1));
+    while (!/^[a-zA-Z]$/.test(result[0]))
+        result = result.slice(1) + result[0];
+    return result;
+}
+
+export { getRandomString };

package/es/index.js

@@ -0,0 +1,14 @@
+export { toLowerCamelCase, toSplitCase } from './className.js';
+export { ObjectAssign, createConstructor } from './object/createConstructor.js';
+export { getRandomFloat, getRandomInt } from './getRandomNumber.js';
+export { getRandomString } from './getRandomString.js';
+export { debounce, throttle } from './performance.js';
+export { escapeRegExp } from './regexp/escapeRegExp.js';
+export { autoEscapedRegExp } from './regexp/autoEscapedRegExp.js';
+export { isBrowser, isNode } from './isNode.js';
+export { enArr } from './array/index.js';
+export { sleep } from './sleep.js';
+export { intersection } from './array/intersection.js';
+export { union } from './array/union.js';
+export { difference } from './array/difference.js';
+export { symmetricDifference } from './array/symmetricDifference.js';

package/es/isNode.js

@@ -0,0 +1,24 @@
+import { isUndefined } from 'a-type-of-js';
+
+/**
+ *
+ * 判断当前环境是否为 node 环境
+ *
+ */
+function isNode() {
+    return !isUndefined((globalThis &&
+        globalThis.process &&
+        globalThis.process.versions &&
+        globalThis.process.versions.node) ||
+        undefined);
+}
+/**
+ *
+ * 是否为浏览器环境
+ *
+ */
+function isBrowser() {
+    return !isNode();
+}
+
+export { isBrowser, isNode };

package/es/object/createConstructor.js

@@ -0,0 +1,55 @@
+/**
+ *
+ * 构建一个 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;
+}
+
+export { ObjectAssign, createConstructor };

package/es/performance.js

@@ -0,0 +1,121 @@
+import { isUndefined, isNull } from 'a-type-of-js';
+import { isFunction } from 'a-type-of-js/isFunction';
+import { isNumber } from '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(callback))
+        throw new TypeError('callback must be a function');
+    if (isNumber(options))
+        options = {
+            delay: options,
+            this: null,
+        };
+    if (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(callback))
+        throw new TypeError('callback must be a function');
+    if (isNumber(options))
+        options = {
+            delay: options,
+            this: null,
+        };
+    if (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 (!isNull(timeoutId))
+            clearTimeout(timeoutId);
+        timeoutId = setTimeout(() => {
+            inThrottle = false;
+            timeoutId = null;
+        }, Math.max(delay, 5));
+    };
+    throttled.cancel = () => {
+        if (!isNull(timeoutId)) {
+            clearTimeout(timeoutId);
+        }
+        inThrottle = false;
+        timeoutId = null;
+    };
+    return throttled;
+}
+
+export { debounce, throttle };

package/es/regexp/autoEscapedRegExp.js

@@ -0,0 +1,46 @@
+import { isString, isUndefined } from 'a-type-of-js';
+import { escapeRegExp } from './escapeRegExp.js';
+import { parse } from './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 (!isString(pattern))
+        throw new TypeError('pattern must be a 字符串');
+    pattern = escapeRegExp(pattern);
+    /** 简单转化  */
+    if (isUndefined(options))
+        return new RegExp(pattern);
+    options = parse(options);
+    return new RegExp(`${options.start ? '^' : ''}${pattern}${options.end ? '$' : ''}`, options.flags);
+}
+
+export { autoEscapedRegExp };

package/es/regexp/escapeRegExp.js

@@ -0,0 +1,22 @@
+/**
+ *
+ * 将一个字符串转化为符合正则要求的字符串
+ *
+ * @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, '\\$&');
+}
+
+export { escapeRegExp };

package/es/regexp/parse.js

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

package/es/sleep.js

@@ -0,0 +1,36 @@
+import { isZero } from '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 (isZero(delay))
+        return Promise.resolve();
+    return new Promise(resolve => setTimeout(resolve, delay));
+}
+
+export { sleep };

package/es/src/index.d.ts

@@ -0,0 +1,11 @@
+export { toLowerCamelCase, toSplitCase } from './className';
+export type { CreateConstructor } from './object/createConstructor';
+export { createConstructor, ObjectAssign } from './object/createConstructor';
+export { getRandomFloat, getRandomInt } from './getRandomNumber';
+export { getRandomString } from './getRandomString';
+export { throttle, debounce } from './performance';
+export type { DebounceAndThrottleReturnType, debounce_throttle_options, } from './performance';
+export { escapeRegExp, autoEscapedRegExp } from './regexp';
+export { isBrowser, isNode } from './isNode';
+export { intersection, enArr, union, difference, symmetricDifference, } from './array';
+export { sleep } from './sleep';

package/es/src/object/index.d.ts

@@ -0,0 +1,2 @@
+export type { CreateConstructor } from './createConstructor';
+export { createConstructor } from './createConstructor';