Merge pull request #6 from giraugh/chore/docs

Documentation

.changeset/gold-dots-raise.md

@@ -0,0 +1,5 @@
+---
+"@giraugh/tools": major
+---
+
+Added documentation and stable version bump

.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: Docs
+
+on:
+  push:
+    branches: ['main']
+    paths:
+      - '**/package.json'
+      - 'lib/**'
+      - '.github/workflows/docs.yml'
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-node@v3
+      with:
+        node-version: 18
+        cache: 'yarn'
+    - run: yarn install --immutable
+    - run: yarn docs
+    - uses: stefanzweifel/git-auto-commit-action@v4
+      with:
+        commit_message: 'ci: generate docs'

README.md

@@ -33,6 +33,12 @@ import { pluralize } from '@giraugh/tools'
 pluralize('cake', 2) === 'cakes'
 ```
 
+## Documentation
+
+**[📄 Visit documentation](/docs/modules.md)**
+
+Docs are auto generated based on TSDoc comments. See the full API docs above for a list of tools and constants you can use.
+
 ## Development
 
 If you find an issue or want to request a feature, please [create an issue](https://github.com/giraugh/tools/issues/new/choose).

docs/.nojekyll

@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.

docs/README.md

@@ -0,0 +1,50 @@
+# 🦒 Giraugh Tools
+
+[![npm version](https://img.shields.io/npm/v/@giraugh/tools)](https://www.npmjs.com/package/@giraugh/tools)
+[![minzip size](https://img.shields.io/bundlephobia/minzip/@giraugh/tools)](https://bundlephobia.com/package/@giraugh/tools)
+
+Generic typescript utilities built with simplicity in mind.
+
+## Installation
+
+**Yarn**
+
+```bash
+yarn add @giraugh/tools
+```
+
+**PNPM**
+
+```bash
+pnpm add @giraugh/tools
+```
+
+**NPM**
+
+```bash
+npm install @giraugh/tools
+```
+
+## Usage
+
+```ts
+import { pluralize } from "@giraugh/tools";
+
+pluralize("cake", 2) === "cakes";
+```
+
+## Documentation
+
+**[📄 Visit documentation](/docs/modules.md)**
+
+Docs are auto generated based on TSDoc comments. See the full API docs above for a list of tools and constants you can use.
+
+## Development
+
+If you find an issue or want to request a feature, please [create an issue](https://github.com/giraugh/tools/issues/new/choose).
+
+Refer to the [Contributing Guide](./CONTRIBUTING.md) for details on local development and contributing to this project.
+
+## License
+
+`@giraugh/tools` is licensed under MIT

docs/arrays/arrays.md

@@ -0,0 +1,20 @@
+[@giraugh/tools](../modules.md) / arrays
+
+# arrays
+
+## Index
+
+### Type Aliases
+
+- [Zipped](types/type-alias.Zipped.md)
+- [ZippedLongest](types/type-alias.ZippedLongest.md)
+
+### Functions
+
+- [chunkArray](functions/function.chunkArray.md)
+- [dedupArrayBy](functions/function.dedupArrayBy.md)
+- [groupArrayBy](functions/function.groupArrayBy.md)
+- [partitionArray](functions/function.partitionArray.md)
+- [range](functions/function.range.md)
+- [zipArrays](functions/function.zipArrays.md)
+- [zipArraysLongest](functions/function.zipArraysLongest.md)

docs/arrays/functions/function.chunkArray.md

@@ -0,0 +1,50 @@
+[@giraugh/tools](../../modules.md) / [arrays](../arrays.md) / chunkArray
+
+# Function: chunkArray()
+
+Chunk array into an array of chunks of given size
+
+## Note
+
+this can return partial chunks
+
+## Example
+
+```ts
+chunkArray([1, 2, 3, 4, 5, 6], 3) ===
+  [
+    [1, 2, 3],
+    [4, 5, 6],
+  ];
+```
+
+## Example
+
+```ts
+chunkArray([1, 2, 3, 4, 5, 6, 7], 3) === [[1, 2, 3], [4, 5, 6], [7]];
+```
+
+> **chunkArray**\<T\>(array: `T`[], chunkSize: `number`): `T`[][]
+
+## Type parameters
+
+| Parameter |
+| :-------- |
+| T         |
+
+## Parameters
+
+| Parameter | Type     | Description                   |
+| :-------- | :------- | :---------------------------- |
+| array     | `T`[]    | array to chunk                |
+| chunkSize | `number` | number of items in each chunk |
+
+## Returns
+
+`T`[][]
+
+array of chunks
+
+## Defined in
+
+[arrays/chunkArray.ts:11](https://github.com/giraugh/tools/blob/a6c3d4a/lib/arrays/chunkArray.ts#L11)

docs/arrays/functions/function.dedupArrayBy.md

@@ -0,0 +1,44 @@
+[@giraugh/tools](../../modules.md) / [arrays](../arrays.md) / dedupArrayBy
+
+# Function: dedupArrayBy()
+
+Deduplicate the values in an array using a specified key function.
+Preserves order.
+
+## Example
+
+```ts
+const animals = [
+  { id: 1, animal: "whale" },
+  { id: 1, animal: "gorilla" },
+  { id: 2, animal: "ant" },
+];
+dedupArrayBy(animals, (animal) => animal.id) ===
+  [
+    { id: 1, animal: "whale" },
+    { id: 2, animal: "ant" },
+  ];
+```
+
+> **dedupArrayBy**\<T\>(array: `T`[], keyFn: `Function`): `T`[]
+
+## Type parameters
+
+| Parameter             |
+| :-------------------- |
+| T _extends_ `unknown` |
+
+## Parameters
+
+| Parameter | Type                        | Description                              |
+| :-------- | :-------------------------- | :--------------------------------------- |
+| array     | `T`[]                       | the array to deduplicate                 |
+| keyFn     | (`t`: `T`) => `PropertyKey` | a function to generate a key to dedup by |
+
+## Returns
+
+`T`[]
+
+## Defined in
+
+[arrays/dedupArrayBy.ts:18](https://github.com/giraugh/tools/blob/a6c3d4a/lib/arrays/dedupArrayBy.ts#L18)

docs/arrays/functions/function.groupArrayBy.md

@@ -0,0 +1,61 @@
+[@giraugh/tools](../../modules.md) / [arrays](../arrays.md) / groupArrayBy
+
+# Function: groupArrayBy()
+
+Group an array using a grouping function
+
+## Example
+
+```ts
+groupArrayBy([1, 2, 3, 4], (x) => x % 2) ===
+  [
+    [1, 3],
+    [2, 4],
+  ];
+```
+
+## Example
+
+```ts
+const peopleByAge = groupArrayBy(
+  [
+    { name: "John", age: 20 },
+    { name: "Claire", age: 20 },
+    { name: "Ben", age: 23 },
+  ],
+  (person) => person.age
+);
+peopleByAge ===
+  [
+    [
+      { name: "John", age: 20 },
+      { name: "Claire", age: 20 },
+    ],
+    [{ name: "Ben", age: 23 }],
+  ];
+```
+
+> **groupArrayBy**\<T\>(array: `T`[], groupFn: `Function`): `T`[][]
+
+## Type parameters
+
+| Parameter |
+| :-------- |
+| T         |
+
+## Parameters
+
+| Parameter | Type                              | Description                                                                                                     |
+| :-------- | :-------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
+| array     | `T`[]                             | the array to create groups from                                                                                 |
+| groupFn   | (`element`: `T`) => `PropertyKey` | the keys to group by. Elements which return the same key when passed to this function will be in the same group |
+
+## Returns
+
+`T`[][]
+
+groups built from the array
+
+## Defined in
+
+[arrays/groupArrayBy.ts:22](https://github.com/giraugh/tools/blob/a6c3d4a/lib/arrays/groupArrayBy.ts#L22)

docs/arrays/functions/function.partitionArray.md

@@ -0,0 +1,38 @@
+[@giraugh/tools](../../modules.md) / [arrays](../arrays.md) / partitionArray
+
+# Function: partitionArray()
+
+Split an array into two subarrays using a predicate function
+
+## Example
+
+```ts
+const [even, odd] = partitionArray([1, 2, 3, 4], (x) => x % 2 === 0);
+even === [2, 4];
+odd === [1, 3];
+```
+
+> **partitionArray**\<T\>(array: `T`[], predicateFn: `Function`): [`T`[], `T`[]]
+
+## Type parameters
+
+| Parameter |
+| :-------- |
+| T         |
+
+## Parameters
+
+| Parameter   | Type                    | Description                          |
+| :---------- | :---------------------- | :----------------------------------- |
+| array       | `T`[]                   | the array to partition               |
+| predicateFn | (`t`: `T`) => `boolean` | the boolean predicate to split along |
+
+## Returns
+
+[`T`[], `T`[]]
+
+the two partitions
+
+## Defined in
+
+[arrays/partitionArray.ts:12](https://github.com/giraugh/tools/blob/a6c3d4a/lib/arrays/partitionArray.ts#L12)

docs/arrays/functions/function.range.md

@@ -0,0 +1,46 @@
+[@giraugh/tools](../../modules.md) / [arrays](../arrays.md) / range
+
+# Function: range()
+
+Create an array of integers in the specified range
+
+## Example
+
+```ts
+range(1, 3) === [1, 2, 3];
+```
+
+## Example
+
+```ts
+range(3, 8) === [3, 4, 5, 6, 7, 8];
+```
+
+## Example
+
+```ts
+range(5, 1, -1) === [5, 4, 3, 2, 1];
+```
+
+> **range**(
+> start: `number`,
+> end: `number`,
+> interval: `number` = `1`): `number`[]
+
+## Parameters
+
+| Parameter | Type     | Default value | Description                                          |
+| :-------- | :------- | :------------ | :--------------------------------------------------- |
+| start     | `number` | undefined     | start of range (inclusive)                           |
+| end       | `number` | undefined     | end of range (inclusive)                             |
+| interval  | `number` | 1             | the jump between successive elements (defaults to 1) |
+
+## Returns
+
+`number`[]
+
+the range as an array of numbers
+
+## Defined in
+
+[arrays/range.ts:11](https://github.com/giraugh/tools/blob/a6c3d4a/lib/arrays/range.ts#L11)