@cloudcome/utils-core 0.0.0 → 1.1.1

package/src/tree.ts

@@ -0,0 +1,394 @@
+import { arrayEach } from './array';
+import { isArray, isNullish, isUndefined } from './type';
+import type { AnyObject } from './types';
+
+/**
+ * 表示深度遍历中的节点对象，包含子节点列表。
+ */
+export type TTreeItem = AnyObject & {
+  /**
+   * 子节点列表。
+   */
+  children?: TTreeItem[];
+};
+
+/**
+ * 表示深度遍历中的节点列表。
+ *
+ * @template I - 节点对象的类型，必须继承自 `TreeItem`。
+ */
+export type TTreeList<I extends TTreeItem> = I[];
+
+/**
+ * 表示深度遍历中的遍历器状态。
+ *
+ * @template I - 节点对象的类型，必须继承自 `TreeItem`。
+ */
+export type TTreeWalker<I extends TTreeItem> = {
+  /**
+   * 当前层级的节点列表。
+   */
+  list: TTreeList<I>;
+
+  /**
+   * 当前节点的父节点，如果为根节点则为 `null`。
+   */
+  parent: I | null;
+
+  /**
+   * 当前节点的层级，从 1 开始计数。
+   */
+  level: number;
+
+  /**
+   * 从根节点到当前节点的路径。
+   */
+  path: TTreeList<I>;
+};
+
+/**
+ * 表示深度遍历中的节点信息。
+ *
+ * @template I - 节点对象的类型，必须继承自 `TreeItem`。
+ */
+export type TTreeInfo<I extends TTreeItem> = TTreeWalker<I> & {
+  /**
+   * 当前节点。
+   */
+  item: I;
+
+  /**
+   * 当前节点在 `list` 中的索引。
+   */
+  index: number;
+};
+
+/**
+ * 深度遍历的同步迭代器函数类型。
+ *
+ * @template I - 节点对象的类型，必须继承自 `TreeItem`。
+ * @param info - 当前节点的信息。
+ * @returns 如果返回 `false`，则提前终止遍历。
+ */
+export type TreeEachIterator<I extends TTreeItem> = (info: TTreeInfo<I>) => false | unknown;
+
+/**
+ * 深度遍历的异步迭代器函数类型。
+ *
+ * @template I - 节点对象的类型，必须继承自 `TreeItem`。
+ * @param info - 当前节点的信息。
+ * @returns 如果返回 `false`，则提前终止遍历。
+ */
+export type TreeEachIteratorAsync<I extends TTreeItem> = (info: TTreeInfo<I>) => Promise<boolean | unknown>;
+
+/**
+ * 深度遍历的同步遍历器函数类型。
+ *
+ * @template I - 节点对象的类型，必须继承自 `TreeItem`。
+ * @param walker - 遍历器状态。
+ * @returns 遍历结果。
+ */
+export type TreeWalk<I extends TTreeItem> = (walker: TTreeWalker<I>) => unknown;
+
+/**
+ * 深度遍历的异步遍历器函数类型。
+ *
+ * @template I - 节点对象的类型，必须继承自 `TreeItem`。
+ * @param walker - 遍历器状态。
+ * @returns 异步遍历结果。
+ */
+export type TreeWalkAsync<I extends TTreeItem> = (walker: TTreeWalker<I>) => Promise<unknown>;
+
+/**
+ * 深度遍历数组中的每个元素，并对每个元素执行提供的回调函数。
+ *
+ * @param treeList - 要遍历的深度数组。
+ * @param iterator - 对每个元素执行的回调函数。如果回调函数返回 `false`，则提前终止遍历。
+ * @param breadthFist - 是否使用广度优先遍历，默认为 `false`（深度优先）。
+ * @returns 无返回值。
+ *
+ * @example
+ * ```typescript
+ * const treeList = [
+ *   { value: 1, children: [{ value: 2 }, { value: 3 }] },
+ *   { value: 4 }
+ * ];
+ *
+ * treeEach(treeList, (item) => {
+ *   console.log(item.value);
+ *   if (item.value === 2) return false; // 提前终止遍历
+ * });
+ * ```
+ */
+export function treeEach<I extends TTreeItem = TTreeItem>(
+  treeList: TTreeList<I>,
+  iterator: TreeEachIterator<I>,
+  breadthFist = false,
+): void {
+  const treeInfoList: TTreeInfo<I>[] = [];
+  let returnFalse = false;
+
+  const iterate = (info: TTreeInfo<I>) => {
+    if (iterator(info) === false) {
+      returnFalse = true;
+      return false;
+    }
+  };
+
+  const next = (info: TTreeInfo<I>, walk: TreeWalk<I>) => {
+    const { item, level, parent, path } = info;
+    const { children } = item;
+
+    if (isArray(children)) {
+      returnFalse =
+        walk({
+          ...info,
+          parent: item,
+          list: children as TTreeList<I>,
+          level: level + 1,
+        }) === false;
+    }
+  };
+
+  const walk: TreeWalk<I> = (walker) => {
+    const { list, level, parent, path } = walker;
+
+    const path2 = [...path];
+    while (parent !== null && path2.length > 0 && path2[path2.length - 1] !== parent) {
+      path2.pop();
+    }
+
+    arrayEach(list, (item, index) => {
+      if (returnFalse) return false;
+
+      const info: TTreeInfo<I> = {
+        ...walker,
+        item,
+        index,
+        path: [...path2, item],
+      };
+
+      // 广度优先
+      if (breadthFist) {
+        treeInfoList.push(info);
+      }
+      // 深度优先
+      else {
+        iterate(info);
+        if (returnFalse) return false;
+        next(info, walk);
+      }
+    });
+
+    if (breadthFist) {
+      while (!returnFalse) {
+        const info = treeInfoList.shift();
+        if (!info) break;
+
+        iterate(info);
+        if (returnFalse) break;
+
+        // 内部也会进入 walk
+        next(info, walk);
+      }
+    }
+
+    return !returnFalse;
+  };
+
+  walk({
+    list: treeList,
+    level: 1,
+    parent: null,
+    path: [],
+  });
+}
+
+/**
+ * 在深度数组中查找满足条件的第一个节点信息。
+ *
+ * @param treeList - 要查找的深度数组。
+ * @param predicate - 判断节点是否满足条件的回调函数。
+ * @param breadthFist - 是否使用广度优先查找，默认为 `false`（深度优先）。
+ * @returns 如果找到满足条件的节点，则返回该节点的信息；否则返回 `undefined`。
+ *
+ * @example
+ * ```typescript
+ * const treeList = [
+ *   { value: 1, children: [{ value: 2 }, { value: 3 }] },
+ *   { value: 4 }
+ * ];
+ *
+ * const found = treeFind(treeList, (info) => info.item.value === 3);
+ * console.log(found);
+ * // {
+ * //    item: { value: 3 },
+ * //    index: 1,
+ * //    list: [{ value: 2 }, { value: 3 }],
+ * //    parent: { value: 1, children: [{ value: 2 }, { value: 3 }] },
+ * //    level: 2,
+ * //    path: [{ value: 1, children: [{ value: 2 }, { value: 3 }] }, { value: 3 }]
+ * // }
+ * ```
+ */
+export function treeFind<I extends TTreeItem>(
+  treeList: TTreeList<I>,
+  predicate: (info: TTreeInfo<I>) => boolean,
+  breadthFist = false,
+): TTreeInfo<I> | undefined {
+  let found: TTreeInfo<I> | undefined;
+
+  treeEach(
+    treeList,
+    (info) => {
+      if (predicate(info)) {
+        found = info;
+        return false;
+      }
+    },
+    breadthFist,
+  );
+
+  return found;
+}
+
+/**
+ * 将深度嵌套的树形结构扁平化为一维数组，并对每个节点执行指定的转换函数。
+ *
+ * @template I - 树节点的类型，必须继承自 `TreeItem`。
+ * @template T - 转换后的数据类型。
+ * @param {TTreeList<I>} deepList - 要扁平化的深度嵌套树形结构。
+ * @param {(info: TTreeInfo<I>) => T} flatten - 对每个节点执行的转换函数，返回转换后的数据。
+ * @param {boolean} [breadthFist=false] - 是否使用广度优先遍历，默认为 `false`（深度优先）。
+ * @returns {T[]} - 转换后的一维数组。
+ * @example
+ * ```typescript
+ * const treeList = [
+ *   { value: 1, children: [{ value: 2 }, { value: 3 }] },
+ *   { value: 4 }
+ * ];
+ *
+ * const flattened = deepFlat(treeList, (info) => info.item.value);
+ * console.log(flattened); // [1, 2, 3, 4]
+ * ```
+ */
+export function deepFlat<I extends TTreeItem, T>(
+  deepList: TTreeList<I>,
+  flatten: (info: TTreeInfo<I>) => T,
+  breadthFist = false,
+): T[] {
+  const list2: T[] = [];
+
+  treeEach(
+    deepList,
+    (info) => {
+      list2.push(flatten(info));
+    },
+    breadthFist,
+  );
+
+  return list2;
+}
+
+type FromItemInfo<I> = {
+  selfKey: unknown;
+  parentKey: unknown;
+  item: I;
+  index: number;
+};
+
+export type TTreeFromOptions<I extends TTreeItem> = {
+  getSelfKey: (item: I, index: number) => unknown;
+  getParentKey: (item: I, index: number) => unknown;
+  appendChild: (parentInfo: FromItemInfo<I>, info: FromItemInfo<I>) => unknown;
+};
+
+/**
+ * 从扁平列表构建树形结构。
+ *
+ * @template I - 节点对象的类型，必须继承自 `AnyObject`。
+ * @param {I[]} list - 扁平化的节点列表。
+ * @param {TTreeFromOptions<I>} options - 构建树形结构的配置选项。
+ * @param {function} options.getSelfKey - 获取节点自身唯一标识的函数。
+ * @param {function} options.getParentKey - 获取节点父节点唯一标识的函数。
+ * @param {function} options.appendChild - 将子节点添加到父节点的函数。
+ * @returns {I | undefined} - 构建的树形结构的根节点，如果未找到根节点则返回 `undefined`。
+ *
+ * @example
+ * ```typescript
+ * const list = [
+ *   { id: 1, parentId: null, name: 'Root' },
+ *   { id: 2, parentId: 1, name: 'Child 1' },
+ *   { id: 3, parentId: 1, name: 'Child 2' }
+ * ];
+ *
+ * const tree = treeFrom(list, {
+ *   getSelfKey: (item) => item.id,
+ *   getParentKey: (item) => item.parentId,
+ *   appendChild: (parent, info) => {
+ *     if (!parent.children) parent.children = [];
+ *     parent.children.push(info.item);
+ *   }
+ * });
+ *
+ * console.log(tree);
+ * // {
+ * //   id: 1,
+ * //   parentId: null,
+ * //   name: 'Root',
+ * //   children: [
+ * //     { id: 2, parentId: 1, name: 'Child 1' },
+ * //     { id: 3, parentId: 1, name: 'Child 2' }
+ * //   ]
+ * // }
+ * ```
+ */
+export function treeFrom<I extends TTreeItem>(list: I[], options: TTreeFromOptions<I>): TTreeList<I> | undefined {
+  const keyMap = new Map<unknown, FromItemInfo<I>>();
+  const freeSet = new Set<FromItemInfo<I>>();
+  const roots: TTreeList<I> = [];
+
+  // 分配节点
+  const assign = (info: FromItemInfo<I>, isFirst = false) => {
+    const { selfKey, parentKey, item, index } = info;
+
+    // 父级指向为空
+    if (isNullish(parentKey)) {
+      roots.push(item);
+    }
+    // 父级指向不为空
+    else {
+      const parent = keyMap.get(parentKey);
+
+      // 未找到父级节点
+      if (isUndefined(parent)) {
+        // 游离节点
+        if (isFirst) freeSet.add(info);
+      }
+      // 已找到父级节点
+      else {
+        options.appendChild(parent, info);
+      }
+    }
+  };
+
+  // 构建 map
+  arrayEach(list, (item, index) => {
+    const selfKey = options.getSelfKey(item, index);
+    const parentKey = options.getParentKey(item, index);
+
+    if (isNullish(selfKey)) return;
+
+    const info = { selfKey, parentKey, item, index };
+    keyMap.set(selfKey, info);
+
+    assign(info, true);
+  });
+
+  // 处理游离节点
+  for (const info of freeSet.values()) {
+    assign(info);
+  }
+
+  return roots;
+}

package/src/type.ts

@@ -0,0 +1,197 @@
+import type { AnyArray, AnyAsyncFunction, AnyFunction, AnyObject } from './types';
+
+/**
+ * 获取未知类型的类型名称
+ * @param unknown - 未知类型的值
+ * @returns 类型名称字符串
+ */
+export function typeIs(
+  unknown: unknown,
+):
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'function'
+  | 'null'
+  | 'undefined'
+  | 'symbol'
+  | 'bigint'
+  | 'error'
+  | 'promise'
+  | string {
+  return Object.prototype.toString.call(unknown).slice(8, -1).toLowerCase();
+}
+
+/**
+ * 检查值是否为字符串
+ * @param unknown - 未知类型的值
+ * @returns 如果值为字符串则返回 true，否则返回 false
+ */
+export function isString(unknown: unknown): unknown is string {
+  return typeof unknown === 'string';
+}
+
+/**
+ * 检查值是否为布尔值
+ * @param unknown - 未知类型的值
+ * @returns 如果值为布尔值则返回 true，否则返回 false
+ */
+export function isBoolean(unknown: unknown): unknown is boolean {
+  return typeof unknown === 'boolean';
+}
+
+/**
+ * 检查值是否为符号
+ * @param unknown - 未知类型的值
+ * @returns 如果值为符号则返回 true，否则返回 false
+ */
+export function isSymbol(unknown: unknown): unknown is symbol {
+  return typeof unknown === 'symbol';
+}
+
+/**
+ * 检查值是否为大整数
+ * @param unknown - 未知类型的值
+ * @returns 如果值为大整数则返回 true，否则返回 false
+ */
+export function isBigInt(unknown: unknown): unknown is bigint {
+  return typeof unknown === 'bigint';
+}
+
+/**
+ * 检查值是否为数字
+ * @param unknown - 未知类型的值
+ * @returns 如果值为数字且不是 NaN 则返回 true，否则返回 false
+ */
+export function isNumber(unknown: unknown): unknown is number {
+  return typeof unknown === 'number' && !Number.isNaN(unknown);
+}
+
+/**
+ * 检查值是否为 undefined
+ * @param unknown - 未知类型的值
+ * @returns 如果值为 undefined 则返回 true，否则返回 false
+ */
+export function isUndefined(unknown: unknown): unknown is undefined {
+  return typeof unknown === 'undefined';
+}
+
+/**
+ * 检查值是否为 void
+ * @param unknown - 未知类型的值
+ * @returns 如果值为 undefined 则返回 true，否则返回 false
+ */
+// biome-ignore lint/suspicious/noConfusingVoidType: <explanation>
+export function isVoid(unknown: unknown): unknown is void {
+  return isUndefined(unknown);
+}
+
+/**
+ * 永不执行，用于 switch-case/if-else 类型断言
+ * @param unknown - 永远不会执行的值
+ */
+export function isNever(unknown: never) {
+  //
+}
+
+/**
+ * 检查值是否为 null
+ * @param unknown - 未知类型的值
+ * @returns 如果值为 null 则返回 true，否则返回 false
+ */
+export function isNull(unknown: unknown): unknown is null {
+  return unknown === null;
+}
+
+/**
+ * 检查值是否为 nullish（null 或 undefined 或 void）
+ * @param unknown - 未知类型的值
+ * @returns 如果值为 null 或 undefined 或 void 则返回 true，否则返回 false
+ */
+// biome-ignore lint/suspicious/noConfusingVoidType: <explanation>
+export function isNullish(unknown: unknown): unknown is null | undefined | void {
+  return isNull(unknown) || isUndefined(unknown) || isVoid(unknown);
+}
+
+/**
+ * 检查值是否为原始类型（null 或 非对象）
+ * @param unknown - 未知类型的值
+ * @returns 如果值为原始类型则返回 true，否则返回 false
+ */
+export function isPrimitive(
+  unknown: unknown,
+): unknown is string | number | boolean | symbol | bigint | null | undefined {
+  return isNull(unknown) || !(typeof unknown === 'object' || typeof unknown === 'function');
+}
+
+/**
+ * 检查值是否为对象，但要注意，此时的对象类型是包含了数组和函数
+ * @param unknown - 未知类型的值
+ * @returns 如果值为对象则返回 true，否则返回 false
+ */
+export function isObject(unknown: unknown): unknown is AnyObject {
+  return typeIs(unknown) === 'object';
+}
+
+/**
+ * 检查值是否为数组
+ * @param unknown - 未知类型的值
+ * @returns 如果值为数组则返回 true，否则返回 false
+ */
+export function isArray(unknown: unknown): unknown is AnyArray {
+  return Array.isArray(unknown);
+}
+
+/**
+ * 检查值是否为函数
+ * @param unknown - 未知类型的值
+ * @returns 如果值为函数则返回 true，否则返回 false
+ */
+export function isFunction(unknown: unknown): unknown is AnyFunction {
+  return typeof unknown === 'function';
+}
+
+/**
+ * 检查值是否为异步函数
+ * @param unknown - 需要检查的值
+ * @returns 如果值为异步函数则返回 true，否则返回 false
+ * @example
+ * ```typescript
+ * async function example() {}
+ *
+ * isAsyncFunction(example); // true
+ * isAsyncFunction(() => {}); // false
+ * ```
+ */
+export function isAsyncFunction(unknown: unknown): unknown is AnyAsyncFunction {
+  return isFunction(unknown) && unknown.constructor.name === 'AsyncFunction';
+}
+
+/**
+ * 检查值是否为 Error 类型
+ * @param unknown - 未知类型的值
+ * @returns 如果值为 Error 类型则返回 true，否则返回 false
+ */
+export function isError(unknown: unknown): unknown is Error {
+  return unknown instanceof Error;
+}
+
+/**
+ * 检查值是否为 Promise 类型
+ * @param unknown - 未知类型的值
+ * @returns 如果值为 Promise 类型则返回 true，否则返回 false
+ */
+export function isPromise<T>(unknown: unknown): unknown is Promise<T> {
+  return typeIs(unknown) === 'promise';
+}
+
+/**
+ * 检查值是否为 Date 类型
+ * @param unknown - 未知类型的值
+ * @returns 如果值为 Date 类型则返回 true，否则返回 false
+ */
+export function isDate(unknown: unknown): unknown is Date {
+  return unknown instanceof Date;
+}

package/src/types.ts

@@ -0,0 +1,78 @@
+/**
+ * 任意对象
+ */
+export type AnyObject = Record<PropertyKey, unknown>;
+
+/**
+ * 返回对象的所有键名，并且键名都是字符串类型
+ * @example
+ * ```typescript
+ * type Keys = KeysOf<{ a: 1, 2: 2, [Symbol()]: 3 }>
+ * // 'a' | '2'
+ * ```
+ */
+export type KeysOf<T> = { [P in keyof T]: P extends string ? P : P extends number ? `${P}` : never }[keyof T];
+
+/**
+ * 任意数组
+ */
+export type AnyArray = Array<unknown>;
+
+/**
+ * 任意函数
+ */
+// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+export type AnyFunction = (...args: any[]) => any;
+
+/**
+ * 任意异步函数
+ */
+// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+export type AnyAsyncFunction = (...args: any[]) => Promise<any>;
+
+/**
+ * 可能是 Promise 的类型
+ */
+export type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * 可能是可执行的类型
+ */
+export type MaybeCallable<T> = T | (() => T);
+
+/**
+ * 深度部分类型
+ */
+export type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T;
+
+// https://juejin.cn/post/6994102811218673700#heading-24
+
+// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+export type UnionToIntersection<T> = (T extends any ? (arg: T) => void : never) extends (arg: infer U) => void
+  ? U
+  : never;
+// type T0 = UnionToIntersection<{ key1: string } | { key2: number }>;
+
+/**
+ * 从联合类型中提取最后一个类型
+ * @template U - 联合类型
+ */
+type _UnionLast<U> = UnionToIntersection<U extends U ? (x: U) => 0 : never> extends (x: infer L) => 0 ? L : never;
+
+/**
+ * 将联合类型转换为元组类型
+ * @template U - 联合类型
+ * @template Last - 联合类型中的最后一个类型
+ */
+export type UnionToTuple<U, Last = _UnionLast<U>> = [U] extends [never]
+  ? []
+  : [...UnionToTuple<Exclude<U, Last>>, Last];
+
+// type T2 = LastInUnion<'a' | 'b' | 'c' | 'd'>;
+// type T3 = UnionToTuple<'a' | 'b' | 'c' | 'd'>;
+// ['a', 'b', 'c', 'd']
+
+// https://juejin.cn/post/7187963986875252795#heading-4
+// type Merged = MergeIntersection<{ a: string } & { b: number }>;
+// { a: string; b: number }
+export type MergeIntersection<A> = A extends infer T ? { [Key in keyof T]: T[Key] } : never;