npm package: @gearbox-built/bolts
Description: Bolts is a versatile TS & JS utility library designed to streamline your Next.js / Sanity / Rack & Pinion development workflow.
Author: Gearbox Built
Latest version: 1.0.0

# ⚡️ Bolts

Bolts is a versatile TS & JS utility library designed to streamline your [Next.js](https://github.com/vercel/next.js/) / [Sanity](https://github.com/sanity-io/sanity) / [Rack & Pinion](https://github.com/gearbox-built/rack-pinion) development workflow. Inspired by the flexibility of tools like [lodash](https://github.com/lodash/lodash) and [react-use](https://github.com/streamich/react-use), Bolts provides a curated set of reusable functions and hooks we often reach for at [Gearbox](https://github.com/gearbox-built/).

## Installation

```sh
# npm
npm install @gearbox-built/bolts

# yarn
yarn add @gearbox-built/bolts
```

## Usage

```tsx
// All the Bolt⚡️
import { generateSlug, batchCommit } from '@gearbox-built/bolts'

// Only Sanity ⚡️
import { batchCommit } from '@gearbox-built/bolts/sanity'

// Sans Sanity ⚡️
import { generateSlug } from '@gearbox-built/bolts/utils'

// Node.js / CommonJS
import { generateSlug } from '@gearbox-built/bolts/cjs/utils'
```

<br>

# Utilities

- **Sanity**

  - [`batchCommit`](./docs/batchCommit.md) — batch mutation operations for Sanity datasets
    - [`buildPatches`](./docs/batchCommit.md#buildpatches) – patch mutations from a list of documents
    - [`mergePatches`](./docs/batchCommit.md#mergepatches) — merges patches with the same id into a single patch
    - [`buildMutations`](./docs/batchCommit.md#buildmutations) - mutations from a list of documents
    - [`generateMutationItems`](./docs/batchCommit.md#generatemutationitems) – mutations for each type of operation
      <br>

- **General**

  - [`generateSlug`](./docs/generateSlug.md) — generates a URL-friendly slug using Gearbox defaults.
  - [`findPaths`](./docs/findPaths.md) — traverse an array of objects with a condition function and return the paths of matches.
  - [`splitArrayInHalf`](./docs/splitArrayInHalf.md) — splits an array into two halves.
  - [`getPlatformNameByUrl`](./docs/getPlatformNameByUrl.md) — extracts the platform name from a URL by parsing its hostname.
    <br>

- **Typing**

  - [`Truthy`](./docs/truthy.md) — type guard function to filter out falsy values.
    <br>
    <br>
    <br>

## Contibuting

To maintain the quality and reliability of Bolts utilities, all contributions must follow these guidelines:

1. **Write Tests:** All new features and bug fixes must include basic [Jest](https://jestjs.io/) unit tests to ensure correctness and prevent regressions.

   - Write tests that cover the core functionality of your utility.
   - If adding or modifying functionality, ensure existing tests still pass.
   - Use descriptive test cases to document expected behavior.

2. **Code Style:** Follow the existing code style and conventions using [eslint](https://eslint.org/) and [prettier](https://prettier.io/) to keep the codebase clean and consistent.

3. **Documentation:** Update the relevant documentation (e.g., JSDoc comments, usage examples, `/docs`) to reflect your changes.

### Pull Request Checklist:

- Ensure all tests pass by running `npm test` or `yarn test`.
- Confirm your changes do not break the build.
- Include a clear and concise description of your changes in the pull request.

Thank you for helping improve Bolts! Contributions with well-tested code make the library robust and reliable for everyone. 🎉

## License

[MIT](LICENSE) © Gearbox Development Inc.