# utils

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`utils.ts` provides small, pure mathematical utilities used throughout `@suaveplan/colours`. Every function is deterministic and side-effect-free, making the module safe to import in any JavaScript runtime. These helpers enforce the numeric invariants that keep colour channels, percentages, and alpha values within their valid ranges.

## Features

- `clamp` — restricts a number to a closed interval
- `isFiniteNumber` — type guard rejecting `NaN` and `Infinity`
- `roundChannel` — clamps and rounds to `[0, 255]`
- `roundPercent` — clamps and rounds to `[0, 100]`
- `roundAlpha` — clamps and rounds to three decimal places in `[0, 1]`

## Usage: Basic Example

```ts
import { clamp, roundChannel } from "@suaveplan/colours/utils";

const value = clamp(300, 0, 255);
console.log(value); // 255

const channel = roundChannel(128.6);
console.log(channel); // 129
```

## Usage: Advanced Example

```ts
import { isFiniteNumber, roundAlpha } from "@suaveplan/colours/utils";

function safeAlpha(input: unknown): number {
    if (!isFiniteNumber(input)) return 1;
    return roundAlpha(input);
}
```

## API Reference

- `clamp(val, min, max): number`
- `isFiniteNumber(v): v is number`
- `roundChannel(v): number`
- `roundPercent(v): number`
- `roundAlpha(v): number`

## Implementation Notes

`roundAlpha` uses `Math.round(v * 1000) / 1000` to cap precision at three decimal places. This matches the CSS `opacity` resolution and prevents floating-point drift in serialised output.

All utilities are implemented as standalone functions with no shared state. They can be imported individually for tree-shaking or used together as a consistent numeric toolkit. Because every helper is pure, they are safe to call inside hot loops such as pixel shaders or animation frames without risk of side effects.

The clamp function uses simple comparison operators rather than Math.min and Math.max for slightly better performance in tight loops. The isFiniteNumber guard explicitly rejects NaN and Infinity, which is stricter than a plain typeof check and prevents invalid values from propagating through conversion chains.