# Introduction

CapyKit is a practical toolkit for .NET applications. It collects common helpers and extension methods into one package so application code can stay focused on business behavior instead of re-implementing the same plumbing in every project.

The project began as shared infrastructure for HappyCapy and is now available as a standalone library. It currently targets .NET 8.

## What CapyKit Provides

### Extension Methods

The `CapyKit.Extensions` namespace contains helpers for common language and LINQ tasks:

- `StringExtensions` provides fallback helpers such as `IfNullOrEmpty` and `IfNullOrWhiteSpace`.
- `LINQExtensions` adds pagination, page counts, inverted filtering, and left outer join helpers for enumerable and queryable collections.
- `EnumerationExtensions` makes enum names, numeric values, descriptions, and human-readable names easier to retrieve.
- `ObjectExtensions` copies matching writable properties from one object to another.

### Helper Classes

The `CapyKit.Helpers` namespace contains focused utility classes:

- `SerializationHelper` serializes and deserializes values with `System.Text.Json`.
- `CompressionHelper` compresses serialized values with gzip and can represent compressed data as Base64.
- `SecurityHelper` creates PBKDF2 password hashes, salts, random strings, and random passwords.
- `KeyHelper` creates and validates formatted HMAC-backed keys using a caller-provided master key.
- `CalculationHelper` includes distance calculations, unit conversion, angle conversion, and quick non-cryptographic hash helpers.
- `LanguageHelper` converts camel case identifiers into human-readable text.

### Core Utility Types

The root `CapyKit` namespace includes small types that support the helpers:

- `Password`, `IPasswordAlgorithm`, and `Pbkdf2Algorithm` model password hashing.
- `Pool<T>` and `PoolItem<T>` provide a simple resource pool abstraction.
- `PropertyComparer<T, U>` compares objects by a selected property.
- `CapyEventReporter`, `CapyEventArgs`, and `EventLevel` expose library diagnostics without requiring a specific logging package.
- `NamedColor` provides a large named color enumeration based on the XKCD color survey palette.

## Design Approach

CapyKit favors explicit, discoverable APIs. Most helpers are static methods or extension methods and can be adopted independently. You can use only the namespaces you need, and the library does not impose dependency injection, hosting, logging, or configuration conventions on the consuming application.

Where CapyKit needs to communicate warnings or errors internally, it uses `CapyEventReporter`. Applications can subscribe to these events and map them into their preferred logging, telemetry, or diagnostics system.

## API Reference

The generated API reference is available through the DocFX navigation and starts at [API Reference](api/toc.yml). Use it for exact signatures, overloads, return types, exceptions, and XML comment details.