docs: add array docs (#13)

* docs: add array docs

* chore: ignore vitepress cache files

.gitignore

@@ -4,4 +4,5 @@ lib
 coverage
 .DS_Store
 docs/.vitepress/cache
-docs/.vitepress/dist
+docs/.vitepress/dist
+.vitepress/cache

docs/.vitepress/config.ts

@@ -1,5 +1,5 @@
 import { defineConfig } from 'vitepress'
-import { generalItems, numberItems, stringItems } from './items'
+import { generalItems, numberItems, stringItems, arrayItems } 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(arrayItems, 'zh'),
+          },
         ],
 
         docFooter: {
@@ -81,6 +85,10 @@ export default defineConfig({
         text: 'String',
         items: stringItems,
       },
+      {
+        text: 'Array',
+        items: arrayItems,
+      },
     ],
 
     socialLinks: [{ icon: 'github', link: 'https://github.com/varletjs/rattail' }],

docs/.vitepress/items/array.ts

@@ -0,0 +1,14 @@
+export const arrayItems = [
+  { text: 'uniq', link: '/array/uniq' },
+  { text: 'uniqBy', link: '/array/uniqBy' },
+  { text: 'normalizeToArray', link: '/array/normalizeToArray' },
+  { text: 'removeItem', link: '/array/removeItem' },
+  { text: 'toggleItem', link: '/array/toggleItem' },
+  { text: 'removeArrayBlank', link: '/array/removeArrayBlank' },
+  { text: 'removeArrayEmpty', link: '/array/removeArrayEmpty' },
+  { text: 'find', link: '/array/find' },
+  { text: 'at', link: '/array/at' },
+  { text: 'shuffle', link: '/array/shuffle' },
+  { text: 'sum', link: '/array/sum' },
+  { text: 'sumBy', link: '/array/sumBy' },
+]

docs/.vitepress/items/index.ts

@@ -1,3 +1,4 @@
 export * from './general'
 export * from './string'
 export * from './number'
+export * from './array'

docs/array/at.md

@@ -0,0 +1,24 @@
+# at
+
+Retrieves the element at a specified index in an array, supporting negative indices.
+
+### Usage
+
+```ts
+import { at } from 'rattail'
+
+at([1, 2, 3], -1) // returns 3
+```
+
+### Arguments
+
+| Arg     | Type     | Defaults |
+| ------- | -------- | -------- |
+| `arr`   | `Array`  |          |
+| `index` | `number` |          |
+
+### Return
+
+| Type  |
+| ----- |
+| `any` |

docs/array/find.md

@@ -0,0 +1,25 @@
+# find
+
+Finds the first or last element in an array that meets a specified condition, returning the element and its index.
+
+### Usage
+
+```ts
+import { find } from 'rattail'
+
+find([1, 2, 3], (item) => item > 1) // returns [2, 1]
+```
+
+### Arguments
+
+| Arg    | Type                                              | Defaults  |
+| ------ | ------------------------------------------------- | --------- |
+| `arr`  | `Array`                                           |           |
+| `fn`   | `(item: any, index: number, array: Array) => any` |           |
+| `from` | `'start' \| 'end'`                                | `'start'` |
+
+### Return
+
+| Type                          |
+| ----------------------------- |
+| `[any, number] \| [null, -1]` |

docs/array/normalizeToArray.md

@@ -0,0 +1,24 @@
+# normalizeToArray
+
+Converts a value to an array if it is not already an array. If the input is an array, it returns the input as-is.
+
+### Usage
+
+```ts
+import { normalizeToArray } from 'rattail'
+
+normalizeToArray(5) // returns [5]
+normalizeToArray([1, 2, 3]) // returns [1, 2, 3]
+```
+
+### Arguments
+
+| Arg     | Type  | Defaults |
+| ------- | ----- | -------- |
+| `value` | `any` |          |
+
+### Return
+
+| Type    |
+| ------- |
+| `Array` |

docs/array/removeArrayBlank.md

@@ -0,0 +1,23 @@
+# removeArrayBlank
+
+Removes `null` or `undefined` values from an array.
+
+### Usage
+
+```ts
+import { removeArrayBlank } from 'rattail'
+
+removeArrayBlank([1, null, 2, undefined, 3]) // returns [1, 2, 3]
+```
+
+### Arguments
+
+| Arg | Type  | Defaults |
+| --- | ----- | -------- | --- |
+|     | `arr` | `Array`  |     |
+
+### Return
+
+| Type    |
+| ------- |
+| `Array` |

docs/array/removeArrayEmpty.md

@@ -0,0 +1,23 @@
+# removeArrayEmpty
+
+Removes `null`, `undefined`, or empty string (`''`) values from an array.
+
+### Usage
+
+```ts
+import { removeArrayEmpty } from 'rattail'
+
+removeArrayEmpty([1, null, '', 3]) // returns [1, 3]
+```
+
+### Arguments
+
+| Arg   | Type    | Defaults |
+| ----- | ------- | -------- |
+| `arr` | `Array` |          |
+
+### Return
+
+| Type    |
+| ------- |
+| `Array` |

docs/array/removeItem.md

@@ -0,0 +1,25 @@
+# removeItem
+
+Removes the first occurrence of a specific item from an array and returns the removed item.
+
+### Usage
+
+```ts
+import { removeItem } from 'rattail'
+
+const arr = [1, 2, 3]
+removeItem(arr, 2) // arr becomes [1, 3]
+```
+
+### Arguments
+
+| Arg    | Type    | Defaults |
+| ------ | ------- | -------- |
+| `arr`  | `Array` |          |
+| `item` | `any`   |          |
+
+### Return
+
+| Type  |
+| ----- |
+| `any` |

docs/array/shuffle.md

@@ -0,0 +1,23 @@
+# shuffle
+
+Randomly shuffles elements within an array.
+
+### Usage
+
+```ts
+import { shuffle } from 'rattail'
+
+shuffle([1, 2, 3]) // returns [2, 1, 3] (output may vary)
+```
+
+### Arguments
+
+| Arg   | Type    | Defaults |
+| ----- | ------- | -------- |
+| `arr` | `Array` |          |
+
+### Return
+
+| Type    |
+| ------- |
+| `Array` |

docs/array/sum.md

@@ -0,0 +1,23 @@
+# sum
+
+Calculates the sum of values in an array of numbers.
+
+### Usage
+
+```ts
+import { sum } from 'rattail'
+
+sum([1, 2, 3]) // returns 6
+```
+
+### Arguments
+
+| Arg   | Type       | Defaults |
+| ----- | ---------- | -------- |
+| `arr` | `number[]` |          |
+
+### Return
+
+| Type     |
+| -------- |
+| `number` |

docs/array/sumBy.md

@@ -0,0 +1,24 @@
+# sumBy
+
+Calculates the sum of values in an array based on a provided function.
+
+### Usage
+
+```ts
+import { sumBy } from 'rattail'
+
+sumBy([{ n: 1 }, { n: 2 }, { n: 3 }], (item) => item.n) // returns 6
+```
+
+### Arguments
+
+| Arg   | Type                   | Defaults |
+| ----- | ---------------------- | -------- |
+| `arr` | `Array`                |          |
+| `fn`  | `(val: any) => number` |          |
+
+### Return
+
+| Type     |
+| -------- |
+| `number` |

docs/array/toggleItem.md

@@ -0,0 +1,26 @@
+# toggleItem
+
+Adds or removes an item from an array, based on its existence in the array.
+
+### Usage
+
+```ts
+import { toggleItem } from 'rattail'
+
+const arr = [1, 2]
+toggleItem(arr, 2) // arr becomes [1]
+toggleItem(arr, 3) // arr becomes [1, 3]
+```
+
+### Arguments
+
+| Arg    | Type    | Defaults |
+| ------ | ------- | -------- |
+| `arr`  | `Array` |          |
+| `item` | `any`   |          |
+
+### Return
+
+| Type    |
+| ------- |
+| `Array` |

docs/array/uniq.md

@@ -0,0 +1,24 @@
+# uniq
+
+Creates a duplicate-free version of an array, using the values' equality.
+
+### Usage
+
+```ts
+import { uniq } from 'rattail'
+
+uniq([1, 2, 2, 3]) // returns [1, 2, 3]
+uniq(['a', 'a', 'b', 'c']) // returns ['a', 'b', 'c']
+```
+
+### Arguments
+
+| Arg   | Type    | Defaults |
+| ----- | ------- | -------- |
+| `arr` | `Array` |          |
+
+### Return
+
+| Type    |
+| ------- |
+| `Array` |

docs/array/uniqBy.md

@@ -0,0 +1,24 @@
+# uniqBy
+
+Creates a duplicate-free version of an array, using a custom comparison function to determine uniqueness.
+
+### Usage
+
+```ts
+import { uniqBy } from 'rattail'
+
+uniqBy([{ id: 1 }, { id: 2 }, { id: 1 }], (a, b) => a.id === b.id) // returns [{ id: 1 }, { id: 2 }]
+```
+
+### Arguments
+
+| Arg   | Type                          | Defaults |
+| ----- | ----------------------------- | -------- |
+| `arr` | `Array`                       |          |
+| `fn`  | `(a: any, b: any) => boolean` |          |
+
+### Return
+
+| Type    |
+| ------- |
+| `Array` |

docs/zh/array/at.md

@@ -0,0 +1,24 @@
+# at
+
+获取数组中指定索引的元素，支持负索引。
+
+### 使用
+
+```ts
+import { at } from 'rattail'
+
+at([1, 2, 3], -1) // return 3
+```
+
+### 参数
+
+| 参数    | 类型     | 默认值 |
+| ------- | -------- | ------ |
+| `arr`   | `Array`  |        |
+| `index` | `number` |        |
+
+### 返回值
+
+| 类型  |
+| ----- |
+| `any` |