feat: support more utils

docs/.vitepress/config.ts

@@ -1,5 +1,5 @@
 import { defineConfig } from 'vitepress'
-import { generalItems, numberItems, stringItems, arrayItems, functionItems, collectionItems } from './items'
+import { generalItems, numberItems, stringItems, arrayItems, functionItems, collectionItems, mathItems } from './items'
 
 function withI18n(items: { link: string; text: string }[], locale: 'zh') {
   return items.map((item) => {
@@ -43,6 +43,10 @@ export default defineConfig({
             text: '字符串',
             items: withI18n(stringItems, 'zh'),
           },
+          {
+            text: '数学',
+            items: withI18n(mathItems, 'zh'),
+          },
           {
             text: '数组',
             items: withI18n(arrayItems, 'zh'),
@@ -54,7 +58,7 @@ export default defineConfig({
           {
             text: '函数',
             items: withI18n(functionItems, 'zh'),
-          }
+          },
         ],
 
         docFooter: {
@@ -93,6 +97,10 @@ export default defineConfig({
         text: 'String',
         items: stringItems,
       },
+      {
+        text: 'Math',
+        items: mathItems,
+      },
       {
         text: 'Array',
         items: arrayItems,

docs/.vitepress/items/array.ts

@@ -1,7 +1,5 @@
 export const arrayItems = [
   { text: 'at', link: '/array/at' },
-  { text: 'sum', link: '/array/sum' },
-  { text: 'sumBy', link: '/array/sum-by' },
   { text: 'uniq', link: '/array/uniq' },
   { text: 'uniqBy', link: '/array/uniq-by' },
   { text: 'find', link: '/array/find' },

docs/.vitepress/items/collection.ts

@@ -1 +1,4 @@
-export const collectionItems = [{ text: 'mergeWith', link: '/collection/merge-with' }]
+export const collectionItems = [
+  { text: 'merge', link: '/collection/merge' },
+  { text: 'mergeWith', link: '/collection/merge-with' },
+]

docs/.vitepress/items/function.ts

@@ -1,5 +1,6 @@
 export const functionItems = [
   { text: 'NOOP', link: '/function/noop' },
-  { text: 'debounce', link: '/function/debounce' },
   { text: 'call', link: '/function/call' },
+  { text: 'debounce', link: '/function/debounce' },
+  { text: 'throttle', link: '/function/throttle' },
 ]

docs/.vitepress/items/index.ts

@@ -4,3 +4,4 @@ export * from './number'
 export * from './array'
 export * from './collection'
 export * from './function'
+export * from './math'

docs/.vitepress/items/math.ts

@@ -0,0 +1,9 @@
+export const mathItems = [
+  { text: 'sum', link: '/math/sum' },
+  { text: 'sumBy', link: '/math/sum-by' },
+  { text: 'minBy', link: '/math/min-by' },
+  { text: 'maxBy', link: '/math/max-by' },
+  { text: 'mean', link: '/math/mean' },
+  { text: 'meanBy', link: '/math/mean-by' },
+  { text: 'sample', link: '/math/sample' },
+]

docs/.vitepress/items/number.ts

@@ -4,4 +4,6 @@ export const numberItems = [
   { text: 'randomNumber', link: '/number/random-number' },
   { text: 'clamp', link: '/number/clamp' },
   { text: 'clampArrayRange', link: '/number/clamp-array-range' },
+  { text: 'times', link: '/number/times' },
+  { text: 'delay', link: '/number/delay' },
 ]

docs/collection/merge-with.md

@@ -7,17 +7,11 @@ Merge two objects recursively, allowing for custom merge logic through a callbac
 ```ts
 import { mergeWith } from 'rattail'
 
-const object = { a: 1, b: { c: 2 } }
-const source = { b: { d: 3 }, e: 4 }
-const result = mergeWith(object, source)
-// result: { a: 1, b: { c: 2, d: 3 }, e: 4 }
-```
-
-```ts
-const object = { a: [1, 2] }
-const source = { a: [3, 4] }
-const result = mergeWith(object, source, (objValue, srcValue) => [...objValue, ...srcValue])
-// result: { a: [ 1, 2, 3, 4 ] }
+mergeWith(
+  { a: [1, 2] }, { a: [3, 4] }, 
+  (objValue, srcValue) => [...objValue, ...srcValue]
+)
+// return: { a: [ 1, 2, 3, 4 ] }
 ```
 
 ### Arguments
@@ -26,7 +20,7 @@ const result = mergeWith(object, source, (objValue, srcValue) => [...objValue, .
 | ---------- | ----------------------------------------------------------------------------------------- | -------- |
 | `object`   | `object`                                                                                  |          |
 | `source`   | `object`                                                                                  |          |
-| `callback` | `(objValue: any, srcValue: any, key: any, object: object, source: object) => any \| void` |          |
+| `callback` | `(objValue: any, srcValue: any, key: any, object: object, source: object) => any` |          |
 
 ### Return
 

docs/collection/merge.md

@@ -0,0 +1,25 @@
+# merge
+
+Merge two objects recursively.
+
+### Usage
+
+```ts
+import { merge } from 'rattail'
+
+merge({ a: 1, b: { c: 2 } }, { b: { d: 3 }, e: 4 })
+// return { a: 1, b: { c: 2, d: 3 }, e: 4 }
+```
+
+### Arguments
+
+| Arg      | Type     | Defaults |
+| -------- | -------- | -------- |
+| `object` | `object` |          |
+| `source` | `object` |          |
+
+### Return
+
+| Type     |
+| -------- |
+| `object` |

docs/function/call.md

@@ -7,18 +7,21 @@ Call a single function or multiple functions (passed as an array) and pass argum
 ```ts
 import { call } from 'rattail'
 
-const fns = [(a, b) => a + b, (a, b) => a * b]
-
-call(fns[0], 1, 2) // return 3
-call(fns, 1, 2) // return [3, 2]
-call(null) // return undefined
+call((a, b) => a + b, 1, 2)
+// return 3
+call([(a, b) => a + b, (a, b) => a + b], 1, 2)
+// return [3, 3]
 ```
 
-### Type Declarations
+### Arguments
 
-```ts
-export function call<P extends any[], R>(
-  fn?: ((...arg: P) => R) | ((...arg: P) => R)[] | null,
-  ...args: P
-): R | R[] | undefined
-```
+| Arg       |           Type           | Defaults |
+| --------- | :----------------------: | -------: |
+| `fn`      | `Function \| Function[]` |          |
+| `...args` |         `any[]`          |          |
+
+### Return
+
+|    Type    |
+| :--------: |
+| `Function` |

docs/function/debounce.md

@@ -16,13 +16,13 @@ window.addEventListener('resize', debouncedFn)
 
 ### Arguments
 
-| Arg     |           Type            | Defaults |
-| ------- | :-----------------------: | -------: |
-| `fn`    | `(...args: any[]) => any` |          |
-| `delay` |         `number`          |        0 |
+| Arg     |    Type    | Defaults |
+| ------- | :--------: | -------: |
+| `fn`    | `Function` |          |
+| `delay` |  `number`  |        0 |
 
 ### Return
 
-|               Type                |
-| :-------------------------------: |
-| `(Parameters<typeof fn>) => void` |
+|    Type    |
+| :--------: |
+| `Function` |

docs/function/throttle.md

@@ -16,13 +16,13 @@ window.addEventListener('resize', throttledFn)
 
 ### Arguments
 
-| Arg     |           Type            | Defaults |
-| ------- | :-----------------------: | -------: |
-| `fn`    | `(...args: any[]) => any` |          |
-| `delay` |         `number`          |      200 |
+| Arg     |    Type    | Defaults |
+| ------- | :--------: | -------: |
+| `fn`    | `Function` |          |
+| `delay` |  `number`  |    `200` |
 
 ### Return
 
-|               Type                |
-| :-------------------------------: |
-| `(Parameters<typeof fn>) => void` |
+|    Type    |
+| :--------: |
+| `Function` |

docs/math/max-by.md

@@ -0,0 +1,25 @@
+# maxBy
+
+Find the maximum value in an array based on the result of applying a function to each element. If the array is empty, `undefined` is returned.
+
+### Usage
+
+```ts
+import { maxBy } from 'rattail'
+
+maxBy([{ n: 5 }, { n: 10 }, { n: 8 }], ({ n }) => n)
+// return { n: 10 }
+```
+
+### Arguments
+
+| Arg   |         Type         | Defaults |
+| ----- | :------------------: | -------: |
+| `arr` |        `T[]`         |          |
+| `fn`  | `(val: T) => number` |          |
+
+### Return
+
+|       Type        |
+| :---------------: |
+| `T  \| undefined` |

docs/math/mean-by.md

@@ -0,0 +1,27 @@
+# meanBy
+
+Calculate the mean (average) of an `array` by applying a function to each element to derive a numeric value.
+
+### Usage
+
+```ts
+import { meanBy } from 'rattail'
+
+meanBy([{ n: 4 }, { n: 6 }, { n: 8 }], ({ n }) => n)
+// return 6
+meanBy([10, 20, 30], (n) => n / 2)
+// return 10
+```
+
+### Arguments
+
+| Arg   |         Type         | Defaults |
+| ----- | :------------------: | -------: |
+| `arr` |        `T[]`         |          |
+| `fn`  | `(val: T) => number` |          |
+
+### Return
+
+|   Type   |
+| :------: |
+| `number` |

docs/math/mean.md

@@ -0,0 +1,24 @@
+# mean
+
+Calculate the `mean` (average) of an `array` of `numbers`.
+
+### Usage
+
+```ts
+import { mean } from 'rattail'
+
+mean([1, 2, 3, 4, 5]) // return 3
+mean([10, 20, 30]) // return 20
+```
+
+### Arguments
+
+| Arg   |    Type    | Defaults |
+| ----- | :--------: | -------: |
+| `arr` | `number[]` |          |
+
+### Return
+
+|   Type   |
+| :------: |
+| `number` |

docs/math/min-by.md

@@ -0,0 +1,25 @@
+# minBy
+
+Find the `minimum` value in an `array` based on the result of applying a function to each element. If the array is empty, `undefined` is returned.
+
+### Usage
+
+```ts
+import { minBy } from 'rattail'
+
+minBy([{ n: 5 }, { n: 2 }, { n: 8 }], ({ n }) => n)
+// return { n: 2 }
+```
+
+### Arguments
+
+| Arg   |         Type         | Defaults |
+| ----- | :------------------: | -------: |
+| `arr` |        `T[]`         |          |
+| `fn`  | `(val: T) => number` |          |
+
+### Return
+
+|       Type        |
+| :---------------: |
+| `T  \| undefined` |

docs/math/sample.md

@@ -0,0 +1,24 @@
+# sample
+
+Return a random element from an `array`. If the array is empty, `undefined` is returned.
+
+### Usage
+
+```ts
+import { sample } from 'rattail'
+
+sample([1, 2, 3, 4, 5]) // returns a random element, e.g., 3
+sample([]) // returns undefined
+```
+
+### Arguments
+
+| Arg   | Type  | Defaults |
+| ----- | :---: | -------: |
+| `arr` | `T[]` |          |
+
+### Return
+
+|       Type        |
+| :---------------: |
+| `T  \| undefined` |

docs/array/sum-by.md → docs/math/sum-by.md

@@ -7,7 +7,7 @@ Calculates the sum of values in an `array` based on a provided function.
 ```ts
 import { sumBy } from 'rattail'
 
-sumBy([{ n: 1 }, { n: 2 }, { n: 3 }], (item) => item.n) // return 6
+sumBy([{ n: 1 }, { n: 2 }, { n: 3 }], ({ n }) => n) // return 6
 ```
 
 ### Arguments

docs/number/delay.md

@@ -0,0 +1,25 @@
+# delay
+
+Create a promise that resolves after a specified time in milliseconds.
+
+### Usage
+
+```ts
+import { delay } from 'rattail'
+
+console.log('Start')
+await delay(1000)
+console.log('End after 1 second')
+```
+
+### Arguments
+
+| Arg                   |   Type   | Defaults |
+| --------------------- | :------: | -------: |
+| `time (ms)` | `number` |          |
+
+### Return
+
+|      Type       |
+| :-------------: |
+| `Promise<void>` |