sh-tools

概述

SH-Tools 提供了一个强大的表达式求值器模块，支持复杂的数学运算、逻辑判断、函数调用和模板字符串解析。特别适合动态计算、规则引擎和配置化计算场景。

安装

npm install sh-tools

引入方式

import { utils, expr } from 'sh-tools'

核心 API

| 函数名 | 参数 | 返回值 | 描述 | 示例 |
|--------|------|--------|------|------|
| utils.calculate(expression, data?) | expression: string - 表达式字符串
data?: object - 数据上下文 | any - 计算结果 | 计算表达式并返回结果，支持 {} 模板 | utils.calculate("1+2*3") → 7
utils.calculate("用户{name}", {name:"张三"}) → "用户张三" |
| utils.calculateLog(expression, data?) | expression: string
data?: object | {result, log, treeLog} - 结果和日志 | 计算表达式并返回详细执行日志 | utils.calculateLog("sum([1,2,3])") → {result: 6, log: [...], treeLog: [...]} |
| expr.registerFunction(name, fn, override?) | name: string\|object - 函数名或对象
fn: Function - 函数实现
override?: boolean - 是否覆盖 | void | 注册自定义函数 | expr.registerFunction('double', x=>x2)
expr.registerFunction({square: x=>xx}) |
| expr.extendOperator(symbol, config, override?) | symbol: string - 运算符
config: object - 配置
override?: boolean - 是否覆盖 | void | 扩展自定义运算符 | expr.extendOperator('//', {precedence:11, fn:(a,b)=>Math.floor(a/b)}) |

内置函数

数学函数

| 函数名 | 参数 | 返回值 | 描述 | 示例 |
|--------|------|--------|------|------|
| abs | x: number | number | 绝对值 | abs(-10) → 10 |
| ceil | x: number | number | 向上取整 | ceil(3.14) → 4 |
| floor | x: number | number | 向下取整 | floor(3.14) → 3 |
| round | x: number | number | 四舍五入 | round(3.14) → 3 |
| pow | base: number, exponent: number | number | 幂运算 | pow(2, 3) → 8 |
| sqrt | x: number | number | 平方根 | sqrt(9) → 3 |
| sin | x: number | number | 正弦 | sin(0) → 0 |
| cos | x: number | number | 余弦 | cos(0) → 1 |
| tan | x: number | number | 正切 | tan(0) → 0 |
| log | x: number | number | 自然对数 | log(10) → 2.302... |
| exp | x: number | number | e的幂次 | exp(1) → 2.718... |
| random | min?: number, max?: number | number | 随机数 | random() → 0.123
random(1,10) → 5 |
| min | ...args: number[] 或 arr: number[] | number | 最小值 | min(5,2,8,1) → 1
min([5,2,8,1]) → 1 |
| max | ...args: number[] 或 arr: number[] | number | 最大值 | max(5,2,8,1) → 8
max([5,2,8,1]) → 8 |
| add | a: number, b: number | number | 加法（精确） | add(0.1, 0.2) → 0.3 |
| subtract | a: number, b: number | number | 减法（精确） | subtract(0.3, 0.1) → 0.2 |
| multiply | a: number, b: number | number | 乘法（精确） | multiply(0.1, 0.2) → 0.02 |
| divide | a: number, b: number | number | 除法（精确） | divide(0.3, 0.1) → 3 |
| toFixed | value: number, digits: number | string | 保留小数位 | toFixed(3.14159, 2) → "3.14" |
| toInteger | value: any | number | 转整数 | toInteger("123") → 123
toInteger(3.14) → 3 |
| toNumber | value: any | number | 转数字 | toNumber("3.14") → 3.14
toNumber("123") → 123 |
| truncate | value: number, digits: number | number | 截断小数位 | truncate(3.14159, 2) → 3.14 |

数组函数

| 函数名 | 参数 | 返回值 | 描述 | 示例 |
|--------|------|--------|------|------|
| sum | arr: number[] | number | 求和 | sum([1,2,3]) → 6 |
| mean | arr: number[] | number | 平均值 | mean([1,2,3,4]) → 2.5 |
| min | arr: number[] | number | 最小值 | min([5,2,8,1]) → 1 |
| max | arr: number[] | number | 最大值 | max([5,2,8,1]) → 8 |
| flatten | arr: any[] | any[] | 扁平化数组 | flatten([[1,2],[3,4]]) → [1,2,3,4] |
| uniq | arr: any[] | any[] | 数组去重 | uniq([1,2,2,3,3,3]) → [1,2,3] |
| includes | arr: any[], value: any | boolean | 包含判断 | includes([1,2,3], 2) → true |
| first | arr: any[] | any | 第一个元素 | first([1,2,3]) → 1 |
| last | arr: any[] | any | 最后一个元素 | last([1,2,3]) → 3 |
| length | arr: any[] | number | 数组长度 | length([1,2,3,4,5]) → 5 |
| slice | arr: any[], start: number, end?: number | any[] | 切片 | slice([1,2,3,4,5], 1, 3) → [2,3] |
| indexOf | arr: any[], value: any, fromIndex?: number | number | 查找索引 | indexOf([1,2,3,2], 2) → 1 |
| union | ...arrays: any[][] | any[] | 数组合并并去重 | union([1,2], [2,3], [3,4]) → [1,2,3,4] |
| pluck | arr: object[], property: string | any[] | 提取属性值 | pluck([{id:1},{id:2},{id:3}], 'id') → [1,2,3] |
| orderBy | arr: any[], field: string, order?: 'asc'\|'desc' | any[] | 排序 | orderBy([{age:30},{age:25}], 'age', 'asc') → [{age:25},{age:30}] |
| groupBy | arr: any[], field: string | object | 分组 | groupBy([{type:'A'},{type:'B'},{type:'A'}], 'type') → {A:[...], B:[...]} |
| countBy | arr: any[], field: string | object | 统计计数 | countBy([{type:'A'},{type:'B'},{type:'A'}], 'type') → {A:2, B:1} |
| toArrayTree | arr: any[], options?: object | any[] | 转树形结构 | toArrayTree([{id:1,pid:0},{id:2,pid:1}]) → [{id:1,children:[{id:2}]}] |
| toTreeArray | tree: any[], options?: object | any[] | 树形转数组 | toTreeArray([{id:1,children:[{id:2}]}]) → [{id:1,pid:0},{id:2,pid:1}] |
| invoke | arr: any[], methodName: string, ...args: any[] | any[] | 调用方法 | invoke([[1,2],[3,4]], 'join', ',') → ['1,2','3,4'] |
| unzip | arr: any[][] | any[][] | 解压数组 | unzip([[1,'a'],[2,'b'],[3,'c']]) → [[1,2,3],['a','b','c']] |
| includeArrays | arr1: any[], arr2: any[] | boolean | 数组包含 | includeArrays([1,2,3,4], [2,3]) → true |

字符串函数

| 函数名 | 参数 | 返回值 | 描述 | 示例 |
|--------|------|--------|------|------|
| trim | str: string | string | 去除两端空格 | trim(' hello ') → 'hello' |
| trimLeft | str: string | string | 去除左侧空格 | trimLeft(' hello') → 'hello' |
| trimRight | str: string | string | 去除右侧空格 | trimRight('hello ') → 'hello' |
| camelCase | str: string | string | 转驼峰命名 | camelCase('hello_world') → 'helloWorld'
camelCase('hello-world') → 'helloWorld' |
| kebabCase | str: string | string | 转烤串命名 | kebabCase('helloWorld') → 'hello-world'
kebabCase('HelloWorld') → 'hello-world' |
| startsWith | str: string, search: string | boolean | 是否以指定字符串开头 | startsWith('hello', 'he') → true
startsWith('hello', 'lo') → false |
| endsWith | str: string, search: string | boolean | 是否以指定字符串结尾 | endsWith('hello', 'lo') → true
endsWith('hello', 'he') → false |
| toValueString | value: any | string | 转值字符串 | toValueString(123) → '123'
toValueString(null) → '' |
| toNumberString | value: any, digits?: number | string | 转数字字符串 | toNumberString(3.14159, 2) → '3.14' |

日期函数

| 函数名 | 参数 | 返回值 | 描述 | 示例 |
|--------|------|--------|------|------|
| now | 无 | number | 当前时间戳 | now() → 1640995200000 |
| timestamp | 无 | number | 当前时间戳 | timestamp() → 1640995200000 |
| toDateString | date: any, format?: string | string | 日期格式化 | toDateString(1640995200000, 'YYYY-MM-DD') → '2022-01-01' |
| getYearDiff | date1: string\|number, date2: string\|number | number | 年份差 | getYearDiff('2020-01-01', '2024-01-01') → 4 |
| getMonthDiff | date1: string\|number, date2: string\|number | number | 月份差 | getMonthDiff('2024-01-01', '2024-06-01') → 5 |
| getDayDiff | date1: string\|number, date2: string\|number | number | 天数差 | getDayDiff('2024-01-01', '2024-01-10') → 9 |
| getHourDiff | time1: string\|number, time2: string\|number | number | 小时差 | getHourDiff('2024-01-01 10:00', '2024-01-01 15:30') → 5.5 |
| getMinuteDiff | time1: string\|number, time2: string\|number | number | 分钟差 | getMinuteDiff('10:30', '11:45') → 75 |
| getSecondDiff | time1: string\|number, time2: string\|number | number | 秒数差 | getSecondDiff('12:00:00', '12:01:30') → 90 |
| getDayOfMonth | date: string\|number | number | 当月第几天 | getDayOfMonth('2024-01-15') → 15 |

对象函数

| 函数名 | 参数 | 返回值 | 描述 | 示例 |
|--------|------|--------|------|------|
| has | obj: object, key: string | boolean | 检查属性是否存在 | has({name:'John'}, 'name') → true |
| get | obj: object, path: string, defaultValue?: any | any | 深度获取属性值 | get({user:{name:'John'}}, 'user.name') → 'John'
get({}, 'user.name', '默认值') → '默认值' |
| assign | target: object, ...sources: object[] | object | 对象属性分配 | assign({}, {a:1}, {b:2}) → {a:1,b:2} |
| merge | ...objects: object[] | object | 深度合并对象 | merge({a:{x:1}}, {a:{y:2}, b:3}) → {a:{x:1,y:2},b:3} |
| pick | obj: object, keys: string[] | object | 选取指定属性 | pick({name:'John',age:30,city:'NY'}, ['name','age']) → {name:'John',age:30} |
| omit | obj: object, keys: string[] | object | 排除指定属性 | omit({x:1,y:2,z:3}, ['z']) → {x:1,y:2} |

类型判断函数

| 函数名 | 参数 | 返回值 | 描述 | 示例 |
|--------|------|--------|------|------|
| isNaN | value: any | boolean | 是否是NaN | isNaN(NaN) → true
isNaN(123) → false |
| isArray | value: any | boolean | 是否是数组 | isArray([1,2,3]) → true
isArray({}) → false |
| isFloat | value: any | boolean | 是否是浮点数 | isFloat(3.14) → true
isFloat(3) → false |
| isInteger | value: any | boolean | 是否是整数 | isInteger(3) → true
isInteger(3.14) → false |
| isBoolean | value: any | boolean | 是否是布尔值 | isBoolean(true) → true
isBoolean('true') → false |
| isString | value: any | boolean | 是否是字符串 | isString('hello') → true
isString(123) → false |
| isNumber | value: any | boolean | 是否是数字 | isNumber(123) → true
isNumber('123') → false |
| isPlainObject | value: any | boolean | 是否是纯对象 | isPlainObject({}) → true
isPlainObject([]) → false |
| isDate | value: any | boolean | 是否是日期对象 | isDate(new Date()) → true
isDate('2024-01-01') → false |
| isEmpty | value: any | boolean | 是否为空 | isEmpty([]) → true
isEmpty({}) → true
isEmpty('') → true
isEmpty([1]) → false |
| isNull | value: any | boolean | 是否是null | isNull(null) → true
isNull(undefined) → false |
| isMatch | obj: object, source: object | boolean | 是否部分匹配 | isMatch({a:1,b:2,c:3}, {a:1,b:2}) → true |
| isEqual | value1: any, value2: any | boolean | 深度相等比较 | isEqual({a:[1,2]}, {a:[1,2]}) → true
isEqual({a:1}, {a:1,b:2}) → false |
| getSize | value: any | number | 获取大小 | getSize([1,2,3]) → 3
getSize({a:1,b:2}) → 2
getSize('hello') → 5 |

工具函数

| 函数名 | 参数 | 返回值 | 描述 | 示例 |
|--------|------|--------|------|------|
| first | arr: any[] 或 ...args: any[] | any | 第一个元素 | first([1,2,3]) → 1
first(1,2,3) → 1 |
| last | arr: any[] 或 ...args: any[] | any | 最后一个元素 | last([1,2,3]) → 3
last(1,2,3) → 3 |

注意事项

1. 参数类型：所有函数参数都经过类型转换，字符串会自动转为数字等
2. 空值处理：大部分函数对空值有安全的处理机制
3. 错误处理：函数调用出错时会抛出清晰的错误信息
4. 性能优化：常用函数做了性能优化，适合高频调用

使用示例

``javascript
import { utils } from 'sh-tools'

// 数学计算
utils.calculate("abs(-10) + pow(2, 3)") // 18

// 数组操作
utils.calculate("sum([1,2,3,4,5]) / length([1,2,3,4,5])") // 3

// 字符串处理
utils.calculate("trim(' hello ') + ' ' + camelCase('world_test')") // "hello worldTest"

// 日期计算
utils.calculate("getDayDiff('2024-01-01', '2024-01-10') + getHourDiff('10:00', '12:30')") // 12.5

// 对象操作
utils.calculate("merge({a:1}, {b:2}, {c:3})") // {a:1, b:2, c:3}
``