@allkit/shared 0.0.1 → 0.0.3

package/skills/references/lodash.md

@@ -0,0 +1,472 @@
+# lodash
+
+Lodash 常用工具函数 / Common Lodash utilities
+
+## Overview / 概述
+
+提供常用的对象操作、函数防抖节流等工具函数。Provide common object manipulation, debounce, throttle utilities.
+
+## Functions
+
+### deepClone
+
+深拷贝 / Deep clone
+
+```ts
+function deepClone<T>(obj: T): T
+```
+
+**Parameters / 参数**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `obj` | `T` | 要拷贝的对象 |
+
+**Returns / 返回值**
+
+- `T`: 深拷贝后的对象
+
+**Features / 支持类型**
+
+- 基本类型（string, number, boolean, null, undefined, symbol, bigint）
+- 数组 / Array
+- 对象 / Object
+- Date
+- RegExp
+- Map
+- Set
+- 嵌套对象/数组 / Nested objects/arrays
+
+**Example / 示例**
+
+```ts
+// 简单对象
+const original = { name: 'a', person: { age: 18 } }
+const cloned = deepClone(original)
+cloned.person.age = 20
+console.log(original.person.age) // 18
+
+// 数组
+const arr = [1, 2, { a: 1 }]
+const arrClone = deepClone(arr)
+
+// Date
+const date = new Date()
+const dateClone = deepClone(date)
+
+// RegExp
+const reg = /test/g
+const regClone = deepClone(reg)
+
+// Map
+const map = new Map([['key', 'value']])
+const mapClone = deepClone(map)
+
+// Set
+const set = new Set([1, 2, 3])
+const setClone = deepClone(set)
+```
+
+---
+
+### omit
+
+删除对象中的某些键值对 / Omit fields from object
+
+```ts
+function omit<T, K extends keyof T>(obj: T, fields: K[], ignoreEmpty?: boolean): Omit<T, K>
+```
+
+**Parameters / 参数**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `obj` | `T` | 源对象 |
+| `fields` | `K[]` | 要删除的键名数组 |
+| `ignoreEmpty` | `boolean` | 是否忽略空值 |
+
+**Example / 示例**
+
+```ts
+const obj = { a: 1, b: 2, c: 3 }
+omit(obj, ['a'])           // { b: 2, c: 3 }
+omit(obj, ['a', 'b'])      // { c: 3 }
+
+// 忽略空值
+omit({ a: 1, b: undefined }, ['b'], true) // { a: 1 }
+```
+
+---
+
+### pick
+
+从对象中取出指定的键值对 / Pick fields from object
+
+```ts
+function pick<T, K extends keyof T>(obj: T, keys: K[], ignoreEmpty?: boolean): Pick<T, K>
+```
+
+**Parameters / 参数**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `obj` | `T` | 源对象 |
+| `keys` | `K[]` | 要保留的键名数组 |
+| `ignoreEmpty` | `boolean` | 是否忽略空值 |
+
+**Example / 示例**
+
+```ts
+const obj = { a: 1, b: 2, c: 3 }
+pick(obj, ['a', 'b'])      // { a: 1, b: 2 }
+pick(obj, ['a', 'd'])      // { a: 1 } (d 不存在)
+```
+
+---
+
+### pickBy
+
+根据断言函数取出键值对 / Pick fields by predicate
+
+```ts
+function pickBy<T>(obj: T, predicate: (value: any, key: keyof T) => boolean): Partial<T>
+```
+
+**Example / 示例**
+
+```ts
+const obj = { a: 1, b: 2, c: 3, d: 4 }
+pickBy(obj, (value) => value > 2)  // { c: 3, d: 4 }
+pickBy(obj, (_, key) => key !== 'a') // { b: 2, c: 3, d: 4 }
+```
+
+---
+
+### omitBy
+
+根据断言函数删除键值对 / Omit fields by predicate
+
+```ts
+function omitBy<T>(obj: T, predicate: (value: any, key: keyof T) => boolean): Partial<T>
+```
+
+**Example / 示例**
+
+```ts
+const obj = { a: 1, b: 2, c: 3, d: 4 }
+omitBy(obj, (value) => value > 2)   // { a: 1, b: 2 }
+omitBy(obj, (_, key) => key === 'a') // { b: 2, c: 3, d: 4 }
+```
+
+---
+
+### debounce
+
+防抖函数 / Debounce function
+
+```ts
+function debounce<T extends (...args: any[]) => any>(fn: T, delay: number): T & { cancel: () => void }
+```
+
+**Parameters / 参数**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `fn` | `T` | 要防抖的函数 |
+| `delay` | `number` | 延迟时间（毫秒） |
+
+**Returns / 返回值**
+
+- `T & { cancel: () => void }`: 防抖后的函数，包含 cancel 方法
+
+**Example / 示例**
+
+```ts
+// 搜索防抖
+const debounceSearch = debounce((keyword: string) => {
+  console.log('搜索:', keyword)
+  // 执行搜索 API
+}, 300)
+
+// 模拟输入
+input.oninput = (e) => {
+  debounceSearch(e.target.value)
+}
+
+// 取消
+debounceSearch.cancel()
+```
+
+**场景说明 / Scenario**
+
+- 搜索框输入防抖：用户输入停止 300ms 后才触发搜索
+- 窗口 resize 防抖：窗口调整大小停止后执行
+- 表单验证：输入停止后验证
+
+---
+
+### throttle
+
+节流函数 / Throttle function
+
+```ts
+function throttle<T extends (...args: any[]) => any>(fn: T, delay: number): T & { cancel: () => void }
+```
+
+**Parameters / 参数**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `fn` | `T` | 要节流的函数 |
+| `delay` | `number` | 间隔时间（毫秒） |
+
+**Returns / 返回值**
+
+- `T & { cancel: () => void }`: 节流后的函数，包含 cancel 方法
+
+**Example / 示例**
+
+```ts
+// 滚动节流
+const throttleScroll = throttle(() => {
+  console.log('滚动位置:', window.scrollY)
+}, 100)
+
+window.addEventListener('scroll', throttleScroll)
+
+// 点击节流（防止重复提交）
+const throttleSubmit = throttle(() => {
+  console.log('提交表单')
+  // 执行提交
+}, 2000)
+
+button.onclick = () => throttleSubmit()
+```
+
+**场景说明 / Scenario**
+
+- 滚动事件：限制触发频率
+- 按钮点击：防止重复提交
+- 拖拽事件：减少计算次数
+
+---
+
+### merge
+
+合并对象 / Merge objects
+
+```ts
+function merge<T>(target: T, source: any): T & any
+```
+
+**Example / 示例**
+
+```ts
+const target = { a: 1, b: 2 }
+const source = { b: 3, c: 4 }
+merge(target, source) // { a: 1, b: 3, c: 4 }
+
+// 数组会被替换而非合并
+merge({ arr: [1] }, { arr: [2] }) // { arr: [2] }
+```
+
+---
+
+### uniqueId
+
+生成浏览器唯一 ID / Generate unique ID
+
+```ts
+function uniqueId(length?: number): string
+```
+
+**Parameters / 参数**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `length` | `number` | `16` | ID 长度 |
+
+**Example / 示例**
+
+```ts
+uniqueId()    // 16 位: 'a1b2c3d4e5f6g7h8'
+uniqueId(8)   // 8 位: 'a1b2c3d4'
+uniqueId(32)  // 32 位
+```
+
+**Use Cases / 使用场景**
+
+- 生成组件唯一 ID
+- 生成缓存 key
+- 生成临时文件名
+
+---
+
+### get
+
+从对象中获取指定路径的值 / Get value by path
+
+```ts
+function get(obj: any, path: string | string[], defaultValue?: any): any
+```
+
+**Parameters / 参数**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `obj` | `any` | 源对象 |
+| `path` | `string \| string[]` | 属性路径，支持点号或数组 |
+| `defaultValue` | `any` | 默认值 |
+
+**Example / 示例**
+
+```ts
+const obj = { a: { b: { c: 1 } } }
+
+// 点号路径
+get(obj, 'a.b.c')           // 1
+get(obj, 'a.b.d', 0)        // 0 (默认值)
+
+// 数组路径
+get(obj, ['a', 'b', 'c'])   // 1
+
+// 不存在的路径
+get(obj, 'a.b.c.d', 'N/A')  // 'N/A'
+```
+
+---
+
+### objToQString
+
+对象转 URL 字符串 / Object to query string
+
+```ts
+function objToQString(obj: object): string
+```
+
+**Example / 示例**
+
+```ts
+objToQString({ a: 1, b: 2 })     // 'a=1&b=2'
+objToQString({ name: '张三', age: 18 }) // 'name=%E5%BC%A0%E4%B8%89&age=18'
+objToQString({ ids: [1, 2, 3] }) // 'ids=1&ids=2&ids=3'
+```
+
+---
+
+### qStringToObj
+
+URL 字符串转对象 / Query string to object
+
+```ts
+function qStringToObj(queryString: string): object
+```
+
+**Example / 示例**
+
+```ts
+qStringToObj('a=1&b=2')              // { a: '1', b: '2' }
+qStringToObj('name=%E5%BC%A0%E4%B8%89') // { name: '张三' }
+qStringToObj('ids=1&ids=2&ids=3')     // { ids: ['1', '2', '3'] }
+```
+
+---
+
+### blobToBase64
+
+Blob 转 Base64 / Blob to Base64
+
+```ts
+function blobToBase64(blob: Blob, ignorePrefix?: boolean): string
+```
+
+**Parameters / 参数**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `blob` | `Blob` | - | Blob 对象 |
+| `ignorePrefix` | `boolean` | `false` | 是否忽略 data URL 前缀 |
+
+**Example / 示例**
+
+```ts
+// 完整 Base64 (包含前缀)
+blobToBase64(blob)
+// 'data:image/png;base64,iVBORw0KGgo...'
+
+// 纯 Base64 (无前缀)
+blobToBase64(blob, true)
+// 'iVBORw0KGgo...'
+```
+
+---
+
+## Use Cases / 使用场景
+
+### 表单数据处理 / Form Data Processing
+
+```ts
+// 只提交表单中的部分字段
+const formData = { name: '', email: '', password: '', remember: true }
+const submitData = pick(formData, ['name', 'email', 'password'])
+// { name: '', email: '', password: '' }
+
+// 排除敏感字段
+const userData = { id: 1, name: '张三', password: 'xxx', token: 'xxx' }
+const publicData = omit(userData, ['password', 'token'])
+// { id: 1, name: '张三' }
+```
+
+### 防抖搜索 / Debounced Search
+
+```ts
+const handleSearch = debounce(async (keyword: string) => {
+  const results = await searchAPI(keyword)
+  setResults(results)
+}, 300)
+
+input.addEventListener('input', (e) => {
+  handleSearch(e.target.value)
+})
+```
+
+### 安全获取嵌套属性 / Safe Nested Property Access
+
+```ts
+// 传统方式
+const value = obj && obj.a && obj.a.b && obj.a.b.c
+
+// 使用 get
+const value = get(obj, 'a.b.c', 'default')
+```
+
+### 处理 URL 参数 / Handle URL Parameters
+
+```ts
+// 解析 URL 参数
+const params = qStringToObj(window.location.search.slice(1))
+
+// 构建 URL 参数
+const query = objToQString({ page: 1, size: 10, keyword: 'test' })
+// 'page=1&size=10&keyword=test'
+```
+
+### 图片上传预览 / Image Upload Preview
+
+```ts
+fileInput.addEventListener('change', async (e) => {
+  const file = e.target.files[0]
+  const base64 = await fileToBase64(file)
+  img.src = base64
+})
+
+function fileToBase64(file: File): Promise<string> {
+  return new Promise((resolve) => {
+    const reader = new FileReader()
+    reader.onload = () => {
+      resolve(reader.result as string)
+    }
+    reader.readAsDataURL(file)
+  })
+}
+```

package/skills/references/number.md

@@ -0,0 +1,248 @@
+# number
+
+数字处理工具函数 / Number utilities
+
+基于 big.js / Based on big.js
+
+## Overview / 概述
+
+提供一系列数字处理函数，包括精度计算、数字格式化、金钱格式化等。基于 [big.js](https://github.com/MikeMcl/big.js/) 库，解决 JavaScript 浮点数精度问题。
+
+Provide a series of number handling functions including precision calculation, number formatting, money formatting, etc. Based on [big.js](https://github.com/MikeMcl/big.js/) to solve JavaScript floating point precision problems.
+
+## Functions
+
+### useNumber
+
+返回实例化的 Big 对象 / Get Big instance
+
+```ts
+function useNumber(n: BigSource): Big
+```
+
+**Parameters / 参数**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `n` | `BigSource` | 数字或字符串 |
+
+**Returns / 返回值**
+
+- `Big`: Big.js 实例
+
+**Example / 示例**
+
+```ts
+// 加法
+useNumber('1').add('2').toNumber()      // 3
+
+// 减法
+useNumber('2').sub('1').toNumber()      // 1
+
+// 乘法
+useNumber(1).times(2).toNumber()        // 2
+
+// 除法
+useNumber(2).div(1).toNumber()          // 2
+
+// 四舍五入
+useNumber('1.5').round(0, 1).toNumber() // 2
+
+// 精度计算
+useNumber('0.1').add('0.2').toNumber()   // 0.3 (不会有精度问题)
+```
+
+---
+
+### formatMoney
+
+格式化金钱（万、亿）/ Format money (万/亿)
+
+```ts
+function formatMoney(num: number): string
+```
+
+**Parameters / 参数**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `num` | `number` | 要格式化的数字 |
+
+**Returns / 返回值**
+
+- `string`: 格式化后的金钱字符串
+
+**Example / 示例**
+
+```ts
+// 小于等于4位
+formatMoney(1234)     // '1234'
+
+// 5-8位 (万)
+formatMoney(12345)    // '1万2345'
+formatMoney(10000)    // '1万'
+formatMoney(1234567)  // '123万4567'
+
+// 9-12位 (亿)
+formatMoney(123456789)     // '1亿2345万6789'
+formatMoney(100000000)     // '1亿'
+formatMoney(100000001)     // '1亿1'
+
+// 大于12位
+formatMoney(9007199254740992)  // '90071992亿5474万992'
+formatMoney(12345678901234)    // '1234亿5678万9012'
+```
+
+---
+
+### formatNumber
+
+格式化数字（千位分隔符）/ Format number with separator
+
+```ts
+function formatNumber(val: number | string, options?: FormatOptions): string
+```
+
+**Parameters / 参数**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `val` | `number \| string` | - | 要格式化的数字 |
+| `options.precision` | `number` | `0` | 保留小数位数 |
+| `options.thousandSeparator` | `string` | `,` | 千位分隔符 |
+| `options.bit` | `number` | `3` | 分隔位数 |
+| `options.roundMode` | `RoundingMode` | `1` | 舍入模式 |
+
+**RoundingMode / 舍入模式**
+
+| Mode | Description |
+|------|-------------|
+| 0 | 向下取整 |
+| 1 | 四舍五入 |
+| 2 | roundHalfEven |
+| 3 | 向上取整 |
+
+**Example / 示例**
+
+```ts
+// 千位分隔
+formatNumber(1000)                       // '1,000'
+formatNumber(1234567)                    // '1,234,567'
+
+// 保留小数
+formatNumber(1234.5678, { precision: 2 }) // '1,234.57'
+
+// 自定义分隔符
+formatNumber(1234567, { thousandSeparator: '-' }) // '1-234-567'
+
+// 不同分隔位数
+formatNumber(1234567, { bit: 4 }) // '123,4567'
+```
+
+---
+
+### round
+
+四舍五入（精度兼容）/ Round with precision
+
+```ts
+function round(m: BigSource, dp: number, rm?: RoundingMode): number
+```
+
+**Parameters / 参数**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `m` | `BigSource` | - | 数字 |
+| `dp` | `number` | - | 保留位数 |
+| `rm` | `RoundingMode` | `1` | 舍入模式 |
+
+**Example / 示例**
+
+```ts
+// 四舍五入
+round(5.23, 1)  // 5.2
+
+// 向上取整
+round(5.23, 1, 3)  // 5.3
+
+// 向下取整
+round(5.23, 1, 0)  // 5.2
+
+// 精度计算
+round(0.1 + 0.2, 1)  // 0.3
+```
+
+---
+
+## Use Cases / 使用场景
+
+### 价格显示 / Price Display
+
+```ts
+// 商品价格
+formatMoney(product.price)
+
+// 订单金额
+formatMoney(order.totalAmount)
+
+// 用户余额
+formatMoney(user.balance)
+```
+
+### 数字格式化 / Number Formatting
+
+```ts
+// 统计数据
+formatNumber(userCount)  // '1,234'
+
+// 精确小数
+formatNumber(price, { precision: 2 })  // '1,234.56'
+
+// 银行卡号
+formatNumber(cardNumber, { bit: 4, thousandSeparator: ' ' }) // '1234 5678 9012 3456'
+```
+
+### 精度计算 / Precision Calculation
+
+```ts
+// 金额计算
+const total = useNumber(price)
+  .times(quantity)
+  .plus(shippingFee)
+  .minus(discount)
+  .toNumber()
+
+// 比例计算
+const percent = useNumber(value)
+  .div(total)
+  .times(100)
+  .round(2)
+  .toNumber()
+```
+
+### 计数器动画 / Counter Animation
+
+```ts
+function animateCounter(target: number, duration: number = 1000) {
+  const start = 0
+  const startTime = Date.now()
+
+  const animate = () => {
+    const elapsed = Date.now() - startTime
+    const progress = Math.min(elapsed / duration, 1)
+
+    // 使用 easeOut 函数
+    const easeOut = 1 - Math.pow(1 - progress, 3)
+    const current = useNumber(target).times(easeOut).toNumber()
+
+    element.textContent = formatNumber(Math.round(current))
+
+    if (progress < 1) {
+      requestAnimationFrame(animate)
+    }
+  }
+
+  requestAnimationFrame(animate)
+}
+```