@mudbean/utils 2.0.5

package/es/object/createConstructor.js

@@ -0,0 +1,56 @@
+/**
+ * # 构建一个 Constructor 构造函数
+ *
+ * 接收一个构造函数，然后返回 TS 能识别的构造函数自身
+ *
+ * 函数本身并没有执行任何逻辑，仅是简单的返回了实参自身
+ *
+ * 而经过该函数的包装，构造函数成了能够被 TS 识别为可用 new 实例的构造函数
+ *
+ * @param constructor - 传入一个构造函数
+ * @returns 返回传入的构造函数
+ * @example
+ * ```ts
+ * import { createConstructor } from "@mudbean/utils";
+ *
+ * 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 用法
+ * @param target
+ * @param bar
+ */
+function ObjectAssign(target, bar) {
+    const keys = Object.keys(bar);
+    keys.forEach(key => (target[key] = bar[key]));
+    return target;
+}
+
+export { ObjectAssign, createConstructor };

package/es/object/index.d.ts

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

package/es/performance.d.ts

@@ -0,0 +1,61 @@
+type Callback = (...args: any[]) => void;
+/**
+ * 节流和防抖返回值类型
+ */
+export interface DebounceAndThrottleReturnType<F extends Callback> {
+    (...args: Parameters<F>): void;
+    cancel(): void;
+}
+/**  第二参数  */
+export type debounce_throttle_options = {
+    delay?: number;
+    this?: null | unknown;
+} | number;
+/**
+ * # 防抖
+ *
+ * @param   callback 回调函数
+ * @param   options    延迟时间（毫秒），默认 200 (ms) 或包含 this 的配置
+ * @returns   返回的闭包函数
+ * @example
+ *
+ * ```ts
+ * import { debounce } from '@mudbean/utils';
+ *
+ * const debounce = (callback: Function, delay = 300) => {
+ *   let timer: any = null
+ *
+ *   return (...args: any[]) => clearTimeout(timer)
+ * }
+ *
+ * debounce(); // 未执行
+ * debounce(); // 未执行
+ * debounce(); // 未执行
+ * debounce(); // 执行
+ * ```
+ */
+export declare function debounce<F extends Callback>(callback: F, options?: debounce_throttle_options): DebounceAndThrottleReturnType<F>;
+/**
+ * # 节流
+ *
+ * @param callback   回调函数
+ * @param options      延迟时间（毫秒），默认 200 (ms) 或设置 this
+ * @returns   返回的闭包函数
+ * @example
+ *
+ * ```ts
+ * import { throttle , sleep } form "@mudbean/utils";
+ *
+ * const a_throttle_fn = throttle(()=> {
+ *    console.log("hello");
+ * }, 1200);
+ *
+ * a_throttle_fn(); // 正常打印
+ * a_throttle_fn(); // 跳过打印
+ * await sleep(1200);   // 等待 1200ms
+ * a_throttle_fn(); // 正常打印
+ * a_throttle_fn(); // 跳过打印
+ * ```
+ */
+export declare function throttle<F extends Callback>(callback: F, options?: debounce_throttle_options): DebounceAndThrottleReturnType<F>;
+export {};

package/es/performance.js

@@ -0,0 +1,135 @@
+import { isFunction, isNumber, isUndefined, isNull } from '@mudbean/is';
+
+/**
+ * 防抖和节流
+ */
+/**
+ * # 防抖
+ *
+ * @param   callback 回调函数
+ * @param   options    延迟时间（毫秒），默认 200 (ms) 或包含 this 的配置
+ * @returns   返回的闭包函数
+ * @example
+ *
+ * ```ts
+ * import { debounce } from '@mudbean/utils';
+ *
+ * const debounce = (callback: Function, delay = 300) => {
+ *   let timer: any = null
+ *
+ *   return (...args: any[]) => clearTimeout(timer)
+ * }
+ *
+ * debounce(); // 未执行
+ * debounce(); // 未执行
+ * debounce(); // 未执行
+ * debounce(); // 执行
+ * ```
+ */
+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   返回的闭包函数
+ * @example
+ *
+ * ```ts
+ * import { throttle , sleep } form "@mudbean/utils";
+ *
+ * const a_throttle_fn = throttle(()=> {
+ *    console.log("hello");
+ * }, 1200);
+ *
+ * a_throttle_fn(); // 正常打印
+ * a_throttle_fn(); // 跳过打印
+ * await sleep(1200);   // 等待 1200ms
+ * a_throttle_fn(); // 正常打印
+ * a_throttle_fn(); // 跳过打印
+ * ```
+ */
+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.d.ts

@@ -0,0 +1,28 @@
+import { autoEscapedRegExpOptions } from './types';
+/**
+ * # 适用于简单的文本字符串自动转化为简单模式正则表达式
+ *
+ * *若字符串包含且需保留字符类、组、反向引用、量词等时，该方法可能不适用*
+ *
+ * @param pattern 待转化的文本字符串
+ * @param options 转化选项。 为文本字符串时，默认为正则表达式的标志，还可指定是否匹配开头或结尾
+ * @returns 正则表达式
+ * @example
+ * ```ts
+ * import { autoEscapedRegExp } from '@mudbean/utils';
+ *
+ * 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\]\$/
+ * ```
+ */
+export declare function autoEscapedRegExp(pattern: string, options?: string | autoEscapedRegExpOptions): RegExp;

package/es/regexp/autoEscapedRegExp.js

@@ -0,0 +1,42 @@
+import { isString, isUndefined } from '@mudbean/is';
+import { escapeRegExp } from './escapeRegExp.js';
+import { parse } from './parse.js';
+
+/**
+ * # 适用于简单的文本字符串自动转化为简单模式正则表达式
+ *
+ * *若字符串包含且需保留字符类、组、反向引用、量词等时，该方法可能不适用*
+ *
+ * @param pattern 待转化的文本字符串
+ * @param options 转化选项。 为文本字符串时，默认为正则表达式的标志，还可指定是否匹配开头或结尾
+ * @returns 正则表达式
+ * @example
+ * ```ts
+ * import { autoEscapedRegExp } from '@mudbean/utils';
+ *
+ * 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.d.ts

@@ -0,0 +1,16 @@
+/**
+ * # 将一个字符串转化为符合正则要求的字符串
+ *
+ * @param str 需要转义的字符串
+ * @requires escapeRegExp 转化后字符串
+ * @example
+ * ```ts
+ * import { escapeRegExp  } from '@mudbean/utils';
+ *
+ * escapeRegExp('a.b.c'); // 'a\\.b\\.c'
+ * escapeRegExp('a\\.b\\.c'); // 'a\\\\.b\\\\.c'
+ * escapeRegExp('[a-z]'); // '\\[a-z\\]'
+ * escapeRegExp('^abc$'); // '\\^abc\\$'
+ * ```
+ */
+export declare function escapeRegExp(str: string): string;

package/es/regexp/escapeRegExp.js

@@ -0,0 +1,20 @@
+/**
+ * # 将一个字符串转化为符合正则要求的字符串
+ *
+ * @param str 需要转义的字符串
+ * @requires escapeRegExp 转化后字符串
+ * @example
+ * ```ts
+ * import { escapeRegExp  } from '@mudbean/utils';
+ *
+ * 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/index.d.ts

@@ -0,0 +1,2 @@
+export { escapeRegExp } from './escapeRegExp';
+export { autoEscapedRegExp } from './autoEscapedRegExp';

package/es/regexp/parse.d.ts

@@ -0,0 +1,6 @@
+import type { autoEscapedRegExpOptions } from './types';
+/**
+ * # 解析 options
+ * @param options
+ */
+export declare function parse(options: string | autoEscapedRegExpOptions): autoEscapedRegExpOptions;

package/es/regexp/parse.js

@@ -0,0 +1,29 @@
+import { isString, isNull } from '@mudbean/is';
+
+/**
+ * # 解析 options
+ * @param 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/regexp/types.d.ts

@@ -0,0 +1,10 @@
+export interface autoEscapedRegExpOptions {
+    /**
+     */
+    flags?: string;
+    /**
+     * 匹配开头
+     */
+    start?: boolean;
+    end?: boolean;
+}

package/es/sleep.d.ts

@@ -0,0 +1,25 @@
+/**
+ * # 线程休息
+ *
+ * 但从调用到执行完毕总是与期望的时间并不相吻合，除非执行是线型的（也不保证时间的严格性）
+ *
+ * - 宏任务：整体代码、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>
+ *
+ * *如果参数为非法数值，将会抛出 TypeError *
+ *
+ * @param delay 睡觉时长（机器时间，毫秒为单位）
+ * @returns 🈳
+ * @example
+ *
+ * ```ts
+ * import { sleep } from '@mudbean/utils';
+ *
+ * console.log(Date.now()); // 1748058118471
+ * await sleep(1000);
+ * console.log(Date.now()); // 1748058119473
+ * ```
+ */
+export declare function sleep(delay?: number): Promise<void>;

package/es/sleep.js

@@ -0,0 +1,35 @@
+import { isZero } from '@mudbean/is';
+
+/**
+ * # 线程休息
+ *
+ * 但从调用到执行完毕总是与期望的时间并不相吻合，除非执行是线型的（也不保证时间的严格性）
+ *
+ * - 宏任务：整体代码、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>
+ *
+ * *如果参数为非法数值，将会抛出 TypeError *
+ *
+ * @param delay 睡觉时长（机器时间，毫秒为单位）
+ * @returns 🈳
+ * @example
+ *
+ * ```ts
+ * import { sleep } from '@mudbean/utils';
+ *
+ * console.log(Date.now()); // 1748058118471
+ * await sleep(1000);
+ * console.log(Date.now()); // 1748058119473
+ * ```
+ */
+async function sleep(delay = 1000) {
+    if (!isFinite(delay) || delay < 4)
+        throw new TypeError('delay 应该是一个正常的数值');
+    if (isZero(delay))
+        return Promise.resolve();
+    return new Promise(resolve => setTimeout(resolve, delay));
+}
+
+export { sleep };

package/package.json

@@ -0,0 +1,118 @@
+{
+  "type": "module",
+  "version": "2.0.5",
+  "name": "@mudbean/utils",
+  "license": "MIT",
+  "dependencies": {
+    "@mudbean/is": "^2.0.2"
+  },
+  "main": "cjs/index.js",
+  "module": "es/index.js",
+  "types": "es/index.d.ts",
+  "author": {
+    "name": "泥豆君",
+    "email": "Mr.MudBean@outlook.com",
+    "url": "https://mudbean.cn"
+  },
+  "description": "一点点 🤏  js 函数",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "es",
+    "cjs",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "import": "./es/index.js",
+      "default": "./es/index.js",
+      "require": "./cjs/index.js",
+      "types": "./es/index.d.ts"
+    },
+    "./array": {
+      "default": "./es/array/index.js",
+      "import": "./es/array/index.js",
+      "require": "./cjs/array/index.js",
+      "types": "./es/array/index.d.ts"
+    },
+    "./className": {
+      "default": "./es/className.js",
+      "import": "./es/className.js",
+      "require": "./cjs/className.js",
+      "types": "./es/className.d.ts"
+    },
+    "./createBezier": {
+      "default": "./es/createBezier.js",
+      "import": "./es/createBezier.js",
+      "require": "./cjs/createBezier.js",
+      "types": "./es/createBezier.d.ts"
+    },
+    "./getRandomNumber": {
+      "default": "./es/getRandomNumber.js",
+      "import": "./es/getRandomNumber.js",
+      "require": "./cjs/getRandomNumber.js",
+      "types": "./es/getRandomNumber.d.ts"
+    },
+    "./getRandomString": {
+      "default": "./es/getRandomString.js",
+      "import": "./es/getRandomString.js",
+      "require": "./cjs/getRandomString.js",
+      "types": "./es/getRandomString.d.ts"
+    },
+    "./isNode": {
+      "default": "./es/isNode.js",
+      "import": "./es/isNode.js",
+      "require": "./cjs/isNode.js",
+      "types": "./es/isNode.d.ts"
+    },
+    "./object": {
+      "default": "./es/object/index.js",
+      "import": "./es/object/index.js",
+      "require": "./cjs/object/index.js",
+      "types": "./es/object/index.d.ts"
+    },
+    "./performance": {
+      "default": "./es/performance.js",
+      "import": "./es/performance.js",
+      "require": "./cjs/performance.js",
+      "types": "./es/performance.d.ts"
+    },
+    "./regexp": {
+      "default": "./es/regexp/index.js",
+      "import": "./es/regexp/index.js",
+      "require": "./cjs/regexp/index.js",
+      "types": "./es/regexp/index.d.ts"
+    },
+    "./sleep": {
+      "default": "./es/sleep.js",
+      "import": "./es/sleep.js",
+      "require": "./cjs/sleep.js",
+      "types": "./es/sleep.d.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrMudBean/utils.git"
+  },
+  "keywords": [
+    "js utils",
+    "js 工具",
+    "mudbean"
+  ],
+  "homepage": "https://npm.lmssee.cn/utils",
+  "bugs": {
+    "url": "https://github.com/MrMudBean/utils/issues",
+    "email": "Mr.MudBean@outlook.com"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "browserslist": [
+    "last 2 versions not ie <= 11"
+  ]
+}