zhiaiwan-utils 1.0.3

package/dist/esm/tree/findTreeNode.js

@@ -0,0 +1,39 @@
+import { normalizeTreeMaxDepth } from '../_internal/baseTreeTraverse';
+import forEachTree from './forEachTree';
+/**
+ * 在树中查找第一个满足 `options.predicate` 的节点；找到后立即停止 DFS 遍历。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 遍历与匹配配置，含 `predicate`、`maxDepth` 及字段映射项
+ * @returns 命中的节点；`predicate` 未传或非函数时返回 `null`，未找到时返回 `undefined`
+ *
+ * @example
+ * ```ts
+ * findTreeNode(
+ *   { id: 1, title: '根', children: [{ id: 2, title: '子' }] },
+ *   { predicate: (node) => node.id === 2 },
+ * );
+ * // => { id: 2, title: '子' }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function findTreeNode(tree, options) {
+    if (typeof (options === null || options === void 0 ? void 0 : options.predicate) !== 'function') {
+        return null;
+    }
+    if (tree == null) {
+        return undefined;
+    }
+    const { predicate, maxDepth: maxDepthInput, ...traverseOptions } = options;
+    const maxDepth = normalizeTreeMaxDepth(maxDepthInput);
+    let matched;
+    forEachTree(tree, (node, parent, depth, index, meta) => {
+        if (predicate(node, parent, depth, index, meta)) {
+            matched = node;
+            return false;
+        }
+    }, { ...traverseOptions, maxDepth });
+    return matched;
+}

package/dist/esm/tree/forEachTree.js

@@ -0,0 +1,27 @@
+import baseTreeTraverse from '../_internal/baseTreeTraverse';
+/**
+ * 深度优先遍历树；iteratee 返回 `false` 时立即停止，并返回原树。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param iteratee - 每次访问节点时调用，接收 `(node, parent, depth, index, meta)`，`meta` 含 `parentNodes`
+ * @param options - 遍历选项，含 `maxDepth`、`childrenKey`、`keyField`、`parentIdField`、`labelField`、`getKey`、`getParentKey`、`getLabel`
+ * @returns 原树
+ *
+ * @example
+ * ```ts
+ * forEachTree(
+ *   { id: 1, children: [{ id: 2 }, { id: 3 }] },
+ *   (node) => {
+ *     if (node.id === 2) return false;
+ *   },
+ * );
+ * // 访问 1、2 后停止
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function forEachTree(tree, iteratee, options) {
+    baseTreeTraverse(tree, iteratee, options, 'dfs', true);
+    return tree;
+}

package/dist/esm/tree/getParentNodes.js

@@ -0,0 +1,43 @@
+import { normalizeTreeMaxDepth } from '../_internal/baseTreeTraverse';
+import forEachTree from './forEachTree';
+/**
+ * 查找第一个满足 `options.predicate` 的目标节点，并返回其全部父级节点（从根到直接父节点，不含目标节点本身）。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 遍历与匹配配置，含 `predicate`、`maxDepth` 及字段映射项
+ * @returns 父级节点数组；根节点命中时返回 `[]`；`predicate` 未传或非函数时返回 `null`；未找到或空树时返回 `undefined`
+ *
+ * @example
+ * ```ts
+ * getParentNodes(
+ *   {
+ *     id: 1,
+ *     title: '根',
+ *     children: [{ id: 2, title: '子', children: [{ id: 3, title: '孙' }] }],
+ *   },
+ *   { predicate: (node) => node.id === 3 },
+ * );
+ * // => [{ id: 1, title: '根' }, { id: 2, title: '子' }]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function getParentNodes(tree, options) {
+    if (typeof (options === null || options === void 0 ? void 0 : options.predicate) !== 'function') {
+        return null;
+    }
+    if (tree == null) {
+        return undefined;
+    }
+    const { predicate, maxDepth: maxDepthInput, ...traverseOptions } = options;
+    const maxDepth = normalizeTreeMaxDepth(maxDepthInput);
+    let parentNodes;
+    forEachTree(tree, (node, parent, depth, index, meta) => {
+        if (predicate(node, parent, depth, index, meta)) {
+            parentNodes = meta.parentNodes;
+            return false;
+        }
+    }, { ...traverseOptions, maxDepth });
+    return parentNodes;
+}

package/dist/esm/tree/getTreeDepth.js

@@ -0,0 +1,32 @@
+import baseTreeTraverse from '../_internal/baseTreeTraverse';
+/**
+ * 获取树（或森林）的最大深度；根节点 `depth` 为 `0`。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 与 `forEachTree` 相同的 `TreeTraverseOptions`（`maxDepth` 限制下探范围）
+ * @returns 最大深度；`null`/`undefined` 时返回 `0`
+ *
+ * @example
+ * ```ts
+ * getTreeDepth({
+ *   id: 1,
+ *   children: [{ id: 2, children: [{ id: 3 }] }],
+ * });
+ * // => 2
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function getTreeDepth(tree, options) {
+    if (tree == null) {
+        return 0;
+    }
+    let maxDepth = 0;
+    baseTreeTraverse(tree, (_node, _parent, depth) => {
+        if (depth > maxDepth) {
+            maxDepth = depth;
+        }
+    }, options, 'dfs', false, true);
+    return maxDepth;
+}

package/dist/esm/tree/index.js

@@ -0,0 +1,12 @@
+export { default as traverseTree } from './traverseTree';
+export { default as traverseTreeBfs } from './traverseTreeBfs';
+export { default as forEachTree } from './forEachTree';
+export { default as findTreeNode } from './findTreeNode';
+export { default as filterTreeNodes } from './filterTreeNodes';
+export { default as getParentNodes } from './getParentNodes';
+export { default as toTree } from './toTree';
+export { default as toFlatList } from './toFlatList';
+export { default as getTreeDepth } from './getTreeDepth';
+export { default as mapTree } from './mapTree';
+export { default as pruneTree } from './pruneTree';
+export { DEFAULT_TREE_TRAVERSE_FIELDS } from '../_internal/baseTreeTraverse';

package/dist/esm/tree/mapTree.js

@@ -0,0 +1,95 @@
+import { resolveTreeTraverseOptions, } from '../_internal/baseTreeTraverse';
+function getChildNodes(node, childrenKey) {
+    if (node == null || typeof node !== 'object') {
+        return [];
+    }
+    const children = node[childrenKey];
+    return Array.isArray(children) ? children : [];
+}
+function shouldDescendTree(resolved, depth) {
+    return resolved.maxDepth === 0 || depth < resolved.maxDepth;
+}
+function isTreeCycle(node, nodeKey, pathKeys, pathObjects) {
+    if (pathKeys.has(nodeKey)) {
+        return true;
+    }
+    if (node != null && typeof node === 'object' && pathObjects.has(node)) {
+        return true;
+    }
+    return false;
+}
+function enterTreePath(node, nodeKey, pathKeys, pathObjects) {
+    pathKeys.add(nodeKey);
+    if (node != null && typeof node === 'object') {
+        pathObjects.add(node);
+    }
+}
+function exitTreePath(node, nodeKey, pathKeys, pathObjects) {
+    pathKeys.delete(nodeKey);
+    if (node != null && typeof node === 'object') {
+        pathObjects.delete(node);
+    }
+}
+function mapTreeNode(node, parent, parentNodes, depth, index, mapper, resolved, pathKeys, pathObjects) {
+    const { childrenKey, getKey } = resolved;
+    const nodeKey = getKey(node);
+    if (isTreeCycle(node, nodeKey, pathKeys, pathObjects)) {
+        return undefined;
+    }
+    enterTreePath(node, nodeKey, pathKeys, pathObjects);
+    const mapped = mapper(node, parent, depth, index, { parentNodes });
+    const record = mapped;
+    if (shouldDescendTree(resolved, depth)) {
+        const children = getChildNodes(node, childrenKey);
+        const mappedChildren = [];
+        for (let childIndex = 0; childIndex < children.length; childIndex++) {
+            const mappedChild = mapTreeNode(children[childIndex], node, parentNodes.concat(node), depth + 1, childIndex, mapper, resolved, pathKeys, pathObjects);
+            if (mappedChild !== undefined) {
+                mappedChildren.push(mappedChild);
+            }
+        }
+        if (mappedChildren.length > 0) {
+            record[childrenKey] = mappedChildren;
+        }
+        else {
+            delete record[childrenKey];
+        }
+    }
+    else {
+        delete record[childrenKey];
+    }
+    exitTreePath(node, nodeKey, pathKeys, pathObjects);
+    return mapped;
+}
+/**
+ * 映射树节点并保留树形结构；不修改原树，返回新树。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param mapper - 节点映射函数，签名为 `(node, parent, depth, index, meta)`，`meta` 含 `parentNodes`
+ * @param options - 与 `forEachTree` 相同的 `TreeTraverseOptions`（`maxDepth` 限制递归深度）
+ * @returns 映射后的新树；`null`/`undefined` 原样返回
+ *
+ * @example
+ * ```ts
+ * mapTree(
+ *   { id: 1, title: '根', children: [{ id: 2, title: '子' }] },
+ *   (node) => ({ ...node, title: `[${node.title}]` }),
+ * );
+ * // => { id: 1, title: '[根]', children: [{ id: 2, title: '[子]' }] }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function mapTree(tree, mapper, options) {
+    if (tree == null) {
+        return tree;
+    }
+    const resolved = resolveTreeTraverseOptions(options);
+    if (Array.isArray(tree)) {
+        return tree
+            .map((node, index) => mapTreeNode(node, null, [], 0, index, mapper, resolved, new Set(), new Set()))
+            .filter((node) => node !== undefined);
+    }
+    return mapTreeNode(tree, null, [], 0, 0, mapper, resolved, new Set(), new Set());
+}

package/dist/esm/tree/pruneTree.js

@@ -0,0 +1,123 @@
+import { resolveTreeTraverseOptions, } from '../_internal/baseTreeTraverse';
+function getChildNodes(node, childrenKey) {
+    if (node == null || typeof node !== 'object') {
+        return [];
+    }
+    const children = node[childrenKey];
+    return Array.isArray(children) ? children : [];
+}
+function shouldDescendTree(resolved, depth) {
+    return resolved.maxDepth === 0 || depth < resolved.maxDepth;
+}
+function isTreeCycle(node, nodeKey, pathKeys, pathObjects) {
+    if (pathKeys.has(nodeKey)) {
+        return true;
+    }
+    if (node != null && typeof node === 'object' && pathObjects.has(node)) {
+        return true;
+    }
+    return false;
+}
+function enterTreePath(node, nodeKey, pathKeys, pathObjects) {
+    pathKeys.add(nodeKey);
+    if (node != null && typeof node === 'object') {
+        pathObjects.add(node);
+    }
+}
+function exitTreePath(node, nodeKey, pathKeys, pathObjects) {
+    pathKeys.delete(nodeKey);
+    if (node != null && typeof node === 'object') {
+        pathObjects.delete(node);
+    }
+}
+function pruneTreeNode(node, parent, parentNodes, depth, index, predicate, resolved, pathKeys, pathObjects) {
+    const { childrenKey, getKey } = resolved;
+    const nodeKey = getKey(node);
+    if (isTreeCycle(node, nodeKey, pathKeys, pathObjects)) {
+        return undefined;
+    }
+    enterTreePath(node, nodeKey, pathKeys, pathObjects);
+    const meta = { parentNodes };
+    if (predicate(node, parent, depth, index, meta)) {
+        exitTreePath(node, nodeKey, pathKeys, pathObjects);
+        return undefined;
+    }
+    const sourceChildren = getChildNodes(node, childrenKey);
+    let outputChildren;
+    if (shouldDescendTree(resolved, depth)) {
+        const prunedChildren = [];
+        for (let childIndex = 0; childIndex < sourceChildren.length; childIndex++) {
+            const prunedChild = pruneTreeNode(sourceChildren[childIndex], node, parentNodes.concat(node), depth + 1, childIndex, predicate, resolved, pathKeys, pathObjects);
+            if (prunedChild !== undefined) {
+                prunedChildren.push(prunedChild);
+            }
+        }
+        if (prunedChildren.length === 0 && sourceChildren.length > 0) {
+            exitTreePath(node, nodeKey, pathKeys, pathObjects);
+            return undefined;
+        }
+        if (prunedChildren.length > 0) {
+            outputChildren = prunedChildren;
+        }
+    }
+    else if (sourceChildren.length > 0) {
+        outputChildren = sourceChildren;
+    }
+    exitTreePath(node, nodeKey, pathKeys, pathObjects);
+    const record = { ...node };
+    if (outputChildren && outputChildren.length > 0) {
+        record[childrenKey] = outputChildren;
+    }
+    else {
+        delete record[childrenKey];
+    }
+    return record;
+}
+/**
+ * 按条件剔除树节点并返回新树；不修改原树。
+ *
+ * - `predicate` 返回真值的节点会被剔除；命中中间节点时，其子树一并移除，子节点不会上提。
+ * - 若某节点原有子节点，剔除后 `children` 为空，则该节点也会被剔除，并向上递归剔除空壳父节点。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 遍历与剔除配置，含 `predicate`、`maxDepth` 及字段映射项
+ * @returns 剔除后的新树；`predicate` 未传或非函数时返回 `null`；根被全部剔除时单根返回 `undefined`、森林返回 `[]`
+ *
+ * @example
+ * ```ts
+ * pruneTree(
+ *   {
+ *     id: 1,
+ *     title: '根',
+ *     children: [
+ *       { id: 2, title: '' },
+ *       { id: 3, title: '保留' },
+ *     ],
+ *   },
+ *   { predicate: (node) => !node.title?.trim() },
+ * );
+ * // => { id: 1, title: '根', children: [{ id: 3, title: '保留' }] }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function pruneTree(tree, options) {
+    if (typeof (options === null || options === void 0 ? void 0 : options.predicate) !== 'function') {
+        return null;
+    }
+    if (tree == null) {
+        return tree;
+    }
+    const { predicate, maxDepth: maxDepthInput, ...traverseOptions } = options;
+    const resolved = resolveTreeTraverseOptions({
+        ...traverseOptions,
+        maxDepth: maxDepthInput,
+    });
+    if (Array.isArray(tree)) {
+        return tree
+            .map((node, index) => pruneTreeNode(node, null, [], 0, index, predicate, resolved, new Set(), new Set()))
+            .filter((node) => node !== undefined);
+    }
+    return pruneTreeNode(tree, null, [], 0, 0, predicate, resolved, new Set(), new Set());
+}

package/dist/esm/tree/toFlatList.js

@@ -0,0 +1,51 @@
+import { resolveTreeTraverseOptions } from '../_internal/baseTreeTraverse';
+import forEachTree from './forEachTree';
+function cloneFlatNode(node, parent, childrenKey, parentIdField, getKey) {
+    if (node == null || typeof node !== 'object') {
+        return node;
+    }
+    const record = { ...node };
+    delete record[childrenKey];
+    if (parent == null) {
+        delete record[parentIdField];
+    }
+    else {
+        record[parentIdField] = getKey(parent);
+    }
+    return record;
+}
+/**
+ * 将嵌套树（或森林）深度优先展开为扁平列表；移除 `childrenKey` 并按层级写入 `parentIdField`。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 与 `forEachTree` 相同的 `TreeTraverseOptions`（含 `maxDepth`）
+ * @returns 扁平节点数组；`null`/`undefined` 时返回 `[]`
+ *
+ * @example
+ * ```ts
+ * toFlatList({
+ *   id: 1,
+ *   title: '根',
+ *   children: [{ id: 2, title: '子' }],
+ * });
+ * // => [
+ * //   { id: 1, title: '根' },
+ * //   { id: 2, title: '子', parentId: 1 },
+ * // ]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function toFlatList(tree, options) {
+    if (tree == null) {
+        return [];
+    }
+    const resolved = resolveTreeTraverseOptions(options);
+    const { childrenKey, parentIdField, getKey } = resolved;
+    const flatList = [];
+    forEachTree(tree, (node, parent) => {
+        flatList.push(cloneFlatNode(node, parent, childrenKey, parentIdField, getKey));
+    }, options);
+    return flatList;
+}

package/dist/esm/tree/toTree.js

@@ -0,0 +1,68 @@
+import { resolveTreeTraverseOptions, } from '../_internal/baseTreeTraverse';
+function cloneNodeWithoutChildren(node, childrenKey) {
+    if (node == null || typeof node !== 'object') {
+        return node;
+    }
+    const clone = { ...node };
+    delete clone[childrenKey];
+    return clone;
+}
+function isFlatListRoot(parentKey, nodeMap) {
+    if (parentKey == null || parentKey === '') {
+        return true;
+    }
+    return !nodeMap.has(parentKey);
+}
+function appendChild(parent, child, childrenKey) {
+    const record = parent;
+    const existing = record[childrenKey];
+    if (Array.isArray(existing)) {
+        existing.push(child);
+        return;
+    }
+    record[childrenKey] = [child];
+}
+/**
+ * 将扁平列表（含节点键与父键）转换为嵌套树；返回根节点数组（森林）。
+ *
+ * @param list - 扁平节点列表
+ * @param options - 字段映射与 `forEachTree` 同名的 `TreeTraverseOptions`（`maxDepth` 不参与构建）
+ * @returns 根节点数组；空列表或 `null`/`undefined` 时返回 `[]`
+ *
+ * @example
+ * ```ts
+ * toTree([
+ *   { id: 1, title: '根' },
+ *   { id: 2, title: '子', parentId: 1 },
+ * ]);
+ * // => [{ id: 1, title: '根', children: [{ id: 2, title: '子', parentId: 1 }] }]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function toTree(list, options) {
+    if (list == null || list.length === 0) {
+        return [];
+    }
+    const resolved = resolveTreeTraverseOptions(options);
+    const { childrenKey, getKey, getParentKey } = resolved;
+    const nodeMap = new Map();
+    for (const item of list) {
+        const key = getKey(item);
+        nodeMap.set(key, cloneNodeWithoutChildren(item, childrenKey));
+    }
+    const roots = [];
+    for (const item of list) {
+        const key = getKey(item);
+        const node = nodeMap.get(key);
+        const parentKey = getParentKey(item, null, undefined);
+        if (isFlatListRoot(parentKey, nodeMap)) {
+            roots.push(node);
+            continue;
+        }
+        const parent = nodeMap.get(parentKey);
+        appendChild(parent, node, childrenKey);
+    }
+    return roots;
+}

package/dist/esm/tree/traverseTree.js

@@ -0,0 +1,23 @@
+import baseTreeTraverse from '../_internal/baseTreeTraverse';
+/**
+ * 深度优先遍历树（前序）；遍历完所有节点，不因 iteratee 返回值中断。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param iteratee - 每次访问节点时调用，接收 `(node, parent, depth, index, meta)`，`meta` 含 `parentNodes`
+ * @param options - 遍历选项，含 `maxDepth`、`childrenKey`、`keyField`、`parentIdField`、`labelField`、`getKey`、`getParentKey`、`getLabel`
+ *
+ * @example
+ * ```ts
+ * traverseTree(
+ *   { id: 1, children: [{ id: 2 }] },
+ *   (node) => console.log(node.id),
+ * );
+ * // 输出 1、2
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function traverseTree(tree, iteratee, options) {
+    baseTreeTraverse(tree, iteratee, options, 'dfs', false);
+}

package/dist/esm/tree/traverseTreeBfs.js

@@ -0,0 +1,23 @@
+import baseTreeTraverse from '../_internal/baseTreeTraverse';
+/**
+ * 广度优先遍历树（按层）；遍历完所有节点，不因 iteratee 返回值中断。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param iteratee - 每次访问节点时调用，接收 `(node, parent, depth, index, meta)`，`meta` 含 `parentNodes`
+ * @param options - 遍历选项，含 `maxDepth`、`childrenKey`、`keyField`、`parentIdField`、`labelField`、`getKey`、`getParentKey`、`getLabel`
+ *
+ * @example
+ * ```ts
+ * traverseTreeBfs(
+ *   { id: 1, children: [{ id: 2, children: [{ id: 3 }] }] },
+ *   (node) => console.log(node.id),
+ * );
+ * // 输出 1、2、3
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function traverseTreeBfs(tree, iteratee, options) {
+    baseTreeTraverse(tree, iteratee, options, 'bfs', false);
+}

package/dist/esm/util/clamp.js

@@ -0,0 +1,53 @@
+function toFinite(value) {
+    const result = Number(value);
+    if (result === Infinity || result === -Infinity) {
+        return result < 0 ? -Number.MAX_VALUE : Number.MAX_VALUE;
+    }
+    return result === result ? result : 0;
+}
+function baseClamp(number, lower, upper) {
+    let result = number;
+    if (result === result) {
+        if (upper !== undefined) {
+            result = result <= upper ? result : upper;
+        }
+        if (lower !== undefined) {
+            result = result >= lower ? result : lower;
+        }
+    }
+    return result;
+}
+/**
+ * 将 number 限制在 [lower, upper] 闭区间内。
+ *
+ * @param number - 待限制的数
+ * @param lower - 下界
+ * @param upper - 上界
+ * @returns 限制后的数
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.clamp(-10, -5, 5);
+ * // => -5
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function clamp(number, lower, upper) {
+    let resolvedLower = lower;
+    let resolvedUpper = upper;
+    if (resolvedUpper === undefined) {
+        resolvedUpper = resolvedLower;
+        resolvedLower = undefined;
+    }
+    if (resolvedUpper !== undefined) {
+        resolvedUpper = toFinite(resolvedUpper);
+        resolvedUpper = resolvedUpper === resolvedUpper ? resolvedUpper : 0;
+    }
+    if (resolvedLower !== undefined) {
+        resolvedLower = toFinite(resolvedLower);
+        resolvedLower = resolvedLower === resolvedLower ? resolvedLower : 0;
+    }
+    return baseClamp(toFinite(number), resolvedLower, resolvedUpper);
+}

package/dist/esm/util/constant.js

@@ -0,0 +1,18 @@
+/**
+ * 返回一个始终返回 value 的函数。
+ *
+ * @param value - 固定返回值
+ * @returns 常量函数
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.constant(5)();
+ * // => 5
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function constant(value) {
+    return () => value;
+}

package/dist/esm/util/defaultTo.js

@@ -0,0 +1,25 @@
+/**
+ * 若 value 为 `null` 或 `undefined`，返回 defaultValue，否则返回 value。
+ *
+ * @param value - 待检查的值
+ * @param defaultValue - 默认值
+ * @returns value 或 defaultValue
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.defaultTo(null, 42);
+ * // => 42
+ *
+ * zhiaiwanUtils.defaultTo(undefined, 42);
+ * // => 42
+ *
+ * zhiaiwanUtils.defaultTo(0, 42);
+ * // => 0
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function defaultTo(value, defaultValue) {
+    return value == null ? defaultValue : value;
+}

package/dist/esm/util/defer.js

@@ -0,0 +1,19 @@
+import delay from './delay';
+/**
+ * 推迟到当前调用栈清空后再调用 func，并传入 args。等效于 `delay(func, 1, ...args)`。
+ *
+ * @param func - 要推迟调用的函数
+ * @param args - 传给 func 的参数
+ * @returns `setTimeout` 返回的定时器 ID
+ *
+ * @example
+ * ```ts
+ * defer((text) => console.log(text), 'deferred');
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function defer(func, ...args) {
+    return delay(func, 1, ...args);
+}

package/dist/esm/util/delay.js

@@ -0,0 +1,22 @@
+/**
+ * 延迟 wait 毫秒后调用 func，并传入 args。wait 会按 Lodash 规则数值化，无效值视为 0。
+ *
+ * @param func - 要延迟调用的函数
+ * @param wait - 延迟毫秒数，默认为 0
+ * @param args - 传给 func 的参数
+ * @returns `setTimeout` 返回的定时器 ID
+ *
+ * @example
+ * ```ts
+ * delay((msg) => console.log(msg), 1000, 'later');
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function delay(func, wait, ...args) {
+    const normalizedWait = Number(wait) || 0;
+    return setTimeout(() => {
+        func(...args);
+    }, normalizedWait);
+}