sculp-js 1.7.1 → 1.8.0

package/lib/index.d.ts

@@ -24,11 +24,15 @@ declare function objectHas<T extends AnyObject>(obj: T, key: keyof T): boolean;
  */
 declare function arrayLike(any: unknown): boolean;
 /**
- * 判断任意值的数据类型
+ * 判断任意值的数据类型，检查非对象时不如typeof、instanceof的性能高
+ *
+ * 当检查类对象时是不可靠的，对象可以通过定义 Symbol.toStringTag 属性来更改检查结果
+ *
+ * 详见：https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Object/toString
  * @param {unknown} any
- * @returns {string}
+ * @returns
  */
-declare const typeIs: (any: unknown) => string;
+declare function typeIs(any: unknown): 'Null' | 'Undefined' | 'Symbol' | 'Boolean' | 'Number' | 'String' | 'Function' | 'Date' | 'RegExp' | 'Map' | 'Set' | 'ArrayBuffer' | 'Object' | 'Array' | 'Error' | 'BigInt' | 'Promise' | 'AsyncFunction' | string;
 declare const isString: (any: unknown) => any is string;
 declare const isBoolean: (any: unknown) => any is boolean;
 declare const isSymbol: (any: unknown) => any is symbol;
@@ -38,6 +42,7 @@ declare const isUndefined: (any: unknown) => any is undefined;
 declare const isNull: (any: unknown) => any is null;
 declare const isPrimitive: (any: unknown) => boolean;
 declare function isNullOrUnDef(val: unknown): val is null | undefined;
+
 declare const isObject: (any: unknown) => any is Record<string, unknown>;
 declare const isArray: (any: unknown) => any is unknown[];
 /**
@@ -268,9 +273,6 @@ interface SmoothScrollOptions {
     easing: EasingName;
 }
 declare function smoothScroll(options?: Partial<SmoothScrollOptions>): Promise<void>;
-type ReadyCallback = () => void;
-declare function isDomReady(): boolean;
-declare function onDomReady(callback: ReadyCallback): void;
 /**
  * 获取元素样式属性的计算值
  * @param {HTMLElement} el
@@ -380,7 +382,7 @@ declare function objectMap<O extends AnyObject, T>(obj: O, iterator: (val: O[key
  */
 declare function objectPick<O extends AnyObject, K extends Extract<keyof O, string>[]>(obj: O, keys: K): Pick<O, ArrayElements<K>>;
 /**
- * 对象祛除
+ * 对象去除
  * @param {O} obj
  * @param {K} keys
  * @returns {Pick<O, ArrayElements<K>>}
@@ -403,6 +405,13 @@ declare function objectAssign<R = AnyObject | AnyArray>(source: ObjectAssignItem
  * @returns {R}
  */
 declare function objectFill<R extends AnyObject = AnyObject>(source: Partial<R>, target: Partial<R>, fillable?: (s: typeof source, t: typeof target, key: keyof R) => boolean): R;
+/**
+ * 获取对象指定层级下的属性值（现在可用ES6+的可选链?.来替代）
+ * @param {AnyObject} obj
+ * @param {string} path
+ * @param {boolean} strict
+ * @returns
+ */
 declare function objectGet(obj: AnyObject, path: string, strict?: boolean): {
     p: any | undefined;
     k: string | undefined;
@@ -410,11 +419,23 @@ declare function objectGet(obj: AnyObject, path: string, strict?: boolean): {
 };
 /**
  * 深拷贝堪称完全体 即：任何类型的数据都会被深拷贝
+ *
+ * 包含对null、原始值、对象循环引用的处理
+ *
+ * 对Map、Set、ArrayBuffer、Date、RegExp、Array、Object及原型链属性方法执行深拷贝
  * @param {T} source
  * @param {WeakMap} map
  * @returns {T}
  */
 declare function cloneDeep<T>(source: T, map?: WeakMap<any, any>): T;
+type Comparable = null | undefined | boolean | number | string | Date | RegExp | Map<any, any> | Set<any> | ArrayBuffer | object | Array<any>;
+/**
+ * 比较两值是否相等，适用所有数据类型
+ * @param {Comparable} a
+ * @param {Comparable} b
+ * @returns {boolean}
+ */
+declare function isEqual(a: Comparable, b: Comparable): boolean;
 
 /**
  * 标准化路径
@@ -762,7 +783,12 @@ interface IFieldOptions {
 interface ISearchTreeOpts {
     childField: string;
     nameField: string;
-    ignoreEmptyChild: boolean;
+    removeEmptyChild: boolean;
+    ignoreCase: boolean;
+}
+interface IFilterCondition<V> {
+    keyword?: string;
+    filter?: (args: V) => boolean;
 }
 /**
  * 深度优先遍历函数(支持continue和break操作), 可用于insert tree item 和 remove tree item
@@ -774,14 +800,18 @@ interface ISearchTreeOpts {
  */
 declare function forEachDeep<V>(tree: ArrayLike<V>, iterator: (val: V, i: number, currentArr: ArrayLike<V>, tree: ArrayLike<V>, parent: V | null, level: number) => boolean | void, children?: string, isReverse?: boolean): void;
 /**
- * 深度优先遍历的Map函数(支持continue和break操作), 可用于insert tree item 和 remove tree item
+ * 创建一个新数组, 深度优先遍历的Map函数(支持continue和break操作), 可用于insert tree item 和 remove tree item
+ *
+ * 可遍历任何带有 length 属性和数字键的类数组对象
  * @param {ArrayLike<V>} tree  树形数据
  * @param {Function} iterator  迭代函数, 返回值为true时continue, 返回值为false时break
  * @param {string} children 定制子元素的key
  * @param {boolean} isReverse  是否反向遍历
  * @returns {any[]} 新的一棵树
  */
-declare function mapDeep<V>(tree: ArrayLike<V>, iterator: (val: V, i: number, currentArr: ArrayLike<V>, tree: ArrayLike<V>, parent: V | null, level: number) => boolean | any, children?: string, isReverse?: boolean): any[];
+declare function mapDeep<T>(tree: T[], iterator: (val: T, i: number, currentArr: T[], tree: T[], parent: T | null, level: number) => {
+    [k: string | number]: any;
+} | boolean, children?: string, isReverse?: boolean): any[];
 type IdLike = number | string;
 interface ITreeConf {
     id: string | number;
@@ -796,45 +826,6 @@ interface ITreeConf {
  * @returns {[IdLike[], ITreeItem<V>[]]} - 由parentId...childId, parentObject-childObject组成的二维数组
  */
 declare function searchTreeById<V>(tree: ArrayLike<V>, nodeId: IdLike, config?: ITreeConf): [IdLike[], ArrayLike<V>[]];
-type WithChildren<T> = T & {
-    children?: WithChildren<T>[];
-};
-/**
- * 根据 idProp 与 parentIdProp 从对象数组中构建对应的树
- * 当 A[parentIdProp] === B[idProp] 时，对象A会被移动到对象B的children。
- * 当一个对象的 parentIdProp 不与其他对象的 idProp 字段相等时，该对象被作为树的顶层节点
- * @param {string} idProp 元素ID
- * @param {string} parentIdProp 父元素ID
- * @param {object[]} items 一维数组
- * @returns {WithChildren<T>[]} 树
- * @example
- * const array = [
- *   { id: 'node-1', parent: 'root' },
- *   { id: 'node-2', parent: 'root' },
- *   { id: 'node-3', parent: 'node-2' },
- *   { id: 'node-4', parent: 'node-2' },
- *   { id: 'node-5', parent: 'node-4' },
- * ]
- * const tree = buildTree('id', 'parent', array)
- * expect(tree).toEqual([
- *   { id: 'node-1', parent: 'root' },
- *   {
- *     id: 'node-2',
- *     parent: 'root',
- *     children: [
- *       { id: 'node-3', parent: 'node-2' },
- *       {
- *         id: 'node-4',
- *         parent: 'node-2',
- *         children: [{ id: 'node-5', parent: 'node-4' }],
- *       },
- *     ],
- *   },
- * ])
- */
-declare function buildTree<ID extends string, PID extends string, T extends {
-    [key in ID | PID]: string;
-}>(idProp: ID, parentIdProp: PID, items: T[]): WithChildren<T>[];
 /**
  * 扁平化数组转换成树(效率高于buildTree)
  * @param {any[]} list
@@ -851,12 +842,19 @@ declare function formatTree(list: any[], options?: IFieldOptions): any[];
 declare function flatTree(treeList: any[], options?: IFieldOptions): any[];
 /**
  * 模糊搜索函数，返回包含搜索字符的节点及其祖先节点, 适用于树型组件的字符过滤功能
- * @param {any[]} nodes
- * @param {string} query
+ * 以下搜索条件二选一，按先后优先级处理：
+ * 1. 过滤函数filter, 返回true/false
+ * 2. 匹配关键词，支持是否启用忽略大小写来判断
+ *
+ * 有以下特性：
+ * 1. 可配置removeEmptyChild字段，来决定是否移除搜索结果中的空children字段
+ * 2. 若无任何过滤条件或keyword模式匹配且keyword为空串，返回原对象；其他情况返回新数组
+ * @param {V[]} nodes
+ * @param {IFilterCondition} filterCondition
  * @param {ISearchTreeOpts} options
- * @returns {any[]}
+ * @returns {V[]}
  */
-declare function fuzzySearchTree(nodes: any[], query: string, options?: ISearchTreeOpts): any[];
+declare function fuzzySearchTree<V>(nodes: V[], filterCondition: IFilterCondition<V>, options?: ISearchTreeOpts): V[];
 
 /**
  * 数值安全乘法
@@ -1057,4 +1055,4 @@ declare function replaceVarFromString(sourceStr: string, targetObj: Record<strin
  */
 declare function executeInScope(code: string, scope?: Record<string, any>): any;
 
-export { type AnyArray, type AnyFunc, type AnyObject, type ArrayElements, type DateObj, type DateValue, type DebounceFunc, EMAIL_REGEX, type FileType, HEX_POOL, HTTP_URL_REGEX, type ICanvasWM, type ICompressOptions, type IFieldOptions, IPV4_REGEX, IPV6_REGEX, type ISearchTreeOpts, type ITreeConf, type IdLike, type LooseParamValue, type LooseParams, type ObjectAssignItem, type OnceFunc, PHONE_REGEX, type Params, type PartialDeep, type RandomString, type ReadyCallback, type Replacer, STRING_ARABIC_NUMERALS, STRING_LOWERCASE_ALPHA, STRING_POOL, STRING_UPPERCASE_ALPHA, type SetStyle, type SmoothScrollOptions, type Style, type ThrottleFunc, UNIQUE_NUMBER_SAFE_LENGTH, URL_REGEX, type UniqueString, type Url, type WithChildren, add, addClass, arrayEach, arrayEachAsync, arrayInsertBefore, arrayLike, arrayRemove, asyncMap, buildTree, calculateDate, calculateDateTime, chooseLocalFile, cloneDeep, compressImg, cookieDel, cookieGet, cookieSet, copyText, crossOriginDownload, dateParse, dateToEnd, dateToStart, debounce, decodeFromBase64, divide, downloadBlob, downloadData, downloadHref, downloadURL, encodeToBase64, escapeRegExp, executeInScope, flatTree, forEachDeep, formatDate, formatNumber, formatTree, fuzzySearchTree, genCanvasWM, getComputedCssVal, getGlobal, getStrWidthPx, getStyle, hasClass, isArray, isBigInt, isBoolean, isDate, isDigit, isDomReady, isEmail, isEmpty, isError, isFloat, isFunction, isIdNo, isInteger, isIpV4, isIpV6, isJsonString, isNaN, isNull, isNullOrUnDef, isNumber, isNumerical, isObject, isPhone, isPlainObject, isPrimitive, isRegExp, isString, isSymbol, isUndefined, isUrl, isValidDate, mapDeep, multiply, numberAbbr, numberToHex, objectAssign, objectEach, objectEachAsync, objectFill, objectGet, objectHas, objectMap, objectAssign as objectMerge, objectOmit, objectPick, onDomReady, once, parseQueryParams, parseVarFromString, pathJoin, pathNormalize, qsParse, qsStringify, randomNumber, randomString, randomUuid, removeClass, replaceVarFromString, searchTreeById, setGlobal, setStyle, smoothScroll, stringAssign, stringCamelCase, stringEscapeHtml, stringFill, stringFormat, stringKebabCase, strip, subtract, supportCanvas, throttle, tooltipEvent, typeIs, uniqueNumber, uniqueString, uniqueSymbol, urlDelParams, urlParse, urlSetParams, urlStringify, wait, weAtob, weBtoa };
+export { type AnyArray, type AnyFunc, type AnyObject, type ArrayElements, type Comparable, type DateObj, type DateValue, type DebounceFunc, EMAIL_REGEX, type FileType, HEX_POOL, HTTP_URL_REGEX, type ICanvasWM, type ICompressOptions, type IFieldOptions, type IFilterCondition, IPV4_REGEX, IPV6_REGEX, type ISearchTreeOpts, type ITreeConf, type IdLike, type LooseParamValue, type LooseParams, type ObjectAssignItem, type OnceFunc, PHONE_REGEX, type Params, type PartialDeep, type RandomString, type Replacer, STRING_ARABIC_NUMERALS, STRING_LOWERCASE_ALPHA, STRING_POOL, STRING_UPPERCASE_ALPHA, type SetStyle, type SmoothScrollOptions, type Style, type ThrottleFunc, UNIQUE_NUMBER_SAFE_LENGTH, URL_REGEX, type UniqueString, type Url, add, addClass, arrayEach, arrayEachAsync, arrayInsertBefore, arrayLike, arrayRemove, asyncMap, calculateDate, calculateDateTime, chooseLocalFile, cloneDeep, compressImg, cookieDel, cookieGet, cookieSet, copyText, crossOriginDownload, dateParse, dateToEnd, dateToStart, debounce, decodeFromBase64, divide, downloadBlob, downloadData, downloadHref, downloadURL, encodeToBase64, escapeRegExp, executeInScope, flatTree, forEachDeep, formatDate, formatNumber, formatTree, fuzzySearchTree, genCanvasWM, getComputedCssVal, getGlobal, getStrWidthPx, getStyle, hasClass, isArray, isBigInt, isBoolean, isDate, isDigit, isEmail, isEmpty, isEqual, isError, isFloat, isFunction, isIdNo, isInteger, isIpV4, isIpV6, isJsonString, isNaN, isNull, isNullOrUnDef, isNullOrUnDef as isNullish, isNumber, isNumerical, isObject, isPhone, isPlainObject, isPrimitive, isRegExp, isString, isSymbol, isUndefined, isUrl, isValidDate, mapDeep, multiply, numberAbbr, numberToHex, objectAssign, objectEach, objectEachAsync, objectFill, objectGet, objectHas, objectMap, objectAssign as objectMerge, objectOmit, objectPick, once, parseQueryParams, parseVarFromString, pathJoin, pathNormalize, qsParse, qsStringify, randomNumber, randomString, randomUuid, removeClass, replaceVarFromString, searchTreeById, setGlobal, setStyle, smoothScroll, stringAssign, stringCamelCase, stringEscapeHtml, stringFill, stringFormat, stringKebabCase, strip, subtract, supportCanvas, throttle, tooltipEvent, typeIs, uniqueNumber, uniqueString, uniqueSymbol, urlDelParams, urlParse, urlSetParams, urlStringify, wait, weAtob, weBtoa };