# @suaveplan/utils - Universal utility library: debug, object, platform, number, random, string, email, sound, validate

## Summary

Zero-external-dependency utility library for Suaveplan. Covers debug helpers, deep object manipulation, platform detection, IEEE 754 float packing, pseudo-random selection, email normalization, audio sprite management, string generation, hex validation, and byte-size enforcement.

<!-- begin:auto-docs -->
## Documentation tree

- [debug](./src/debug/debug.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [debug](./src/debug/debug.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [email](./src/email/email.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [email](./src/email/email.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [errors](./src/errors/utils-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [utils-error](./src/errors/utils-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [number](./src/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [number](./src/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [object](./src/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [object](./src/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [platform](./src/platform/platform.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [platform](./src/platform/platform.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [random](./src/random/pseudo.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [pseudo](./src/random/pseudo.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [sound](./src/sound/sound.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [sound](./src/sound/sound.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [string](./src/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [string](./src/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [validate](./src/validate/validate.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [validate](./src/validate/validate.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [validation](./src/validation/size.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [size](./src/validation/size.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
<!-- end:auto-docs -->  - [debug](./src/debug/debug.md) — <!-- begin:auto-docs --> _(no submodules)_- [email](./src/email/email.md) — <!-- begin:auto-docs --> _(no submodules)_- [email](./src/email/email.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/utils-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [utils-error](./src/errors/utils-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [number](./src/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_- [number](./src/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_- [object](./src/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_- [object](./src/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_- [platform](./src/platform/platform.md) — <!-- begin:auto-docs --> _(no submodules)_- [platform](./src/platform/platform.md) — <!-- begin:auto-docs --> _(no submodules)_- [random](./src/random/pseudo.md) — <!-- begin:auto-docs --> _(no submodules)_- [pseudo](./src/random/pseudo.md) — <!-- begin:auto-docs --> _(no submodules)_- [sound](./src/sound/sound.md) — <!-- begin:auto-docs --> _(no submodules)_- [sound](./src/sound/sound.md) — <!-- begin:auto-docs --> _(no submodules)_- [string](./src/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_- [string](./src/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [validate](./src/validate/validate.md) — <!-- begin:auto-docs --> _(no submodules)_- [validate](./src/validate/validate.md) — <!-- begin:auto-docs --> _(no submodules)_- [validation](./src/validation/size.md) — <!-- begin:auto-docs --> _(no submodules)_- [size](./src/validation/size.md) — <!-- begin:auto-docs --> _(no submodules)_- [debug](./src/debug/debug.md) — <!-- begin:auto-docs --> _(no submodules)_- [email](./src/email/email.md) — <!-- begin:auto-docs --> _(no submodules)_- [email](./src/email/email.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/utils-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [utils-error](./src/errors/utils-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [number](./src/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_- [number](./src/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_- [object](./src/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_- [object](./src/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_- [platform](./src/platform/platform.md) — <!-- begin:auto-docs --> _(no submodules)_- [platform](./src/platform/platform.md) — <!-- begin:auto-docs --> _(no submodules)_- [random](./src/random/pseudo.md) — <!-- begin:auto-docs --> _(no submodules)_- [pseudo](./src/random/pseudo.md) — <!-- begin:auto-docs --> _(no submodules)_- [sound](./src/sound/sound.md) — <!-- begin:auto-docs --> _(no submodules)_- [sound](./src/sound/sound.md) — <!-- begin:auto-docs --> _(no submodules)_- [string](./src/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_- [string](./src/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [validate](./src/validate/validate.md) — <!-- begin:auto-docs --> _(no submodules)_- [validate](./src/validate/validate.md) — <!-- begin:auto-docs --> _(no submodules)_- [validation](./src/validation/size.md) — <!-- begin:auto-docs --> _(no submodules)_- [size](./src/validation/size.md) — <!-- begin:auto-docs --> _(no submodules)_- [debug](./src/debug/debug.md) — <!-- begin:auto-docs --> _(no submodules)_- [email](./src/email/email.md) — <!-- begin:auto-docs --> _(no submodules)_- [email](./src/email/email.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/utils-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [utils-error](./src/errors/utils-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [number](./src/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_- [number](./src/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_- [object](./src/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_- [object](./src/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_- [platform](./src/platform/platform.md) — <!-- begin:auto-docs --> _(no submodules)_- [platform](./src/platform/platform.md) — <!-- begin:auto-docs --> _(no submodules)_- [random](./src/random/pseudo.md) — <!-- begin:auto-docs --> _(no submodules)_- [pseudo](./src/random/pseudo.md) — <!-- begin:auto-docs --> _(no submodules)_- [sound](./src/sound/sound.md) — <!-- begin:auto-docs --> _(no submodules)_- [sound](./src/sound/sound.md) — <!-- begin:auto-docs --> _(no submodules)_- [string](./src/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_- [string](./src/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [validate](./src/validate/validate.md) — <!-- begin:auto-docs --> _(no submodules)_- [validate](./src/validate/validate.md) — <!-- begin:auto-docs --> _(no submodules)_- [validation](./src/validation/size.md) — <!-- begin:auto-docs --> _(no submodules)_- [size](./src/validation/size.md) — <!-- begin:auto-docs --> _(no submodules)_- [debug](./src/debug/debug.md) — <!-- begin:auto-docs --> _(no submodules)_- [email](./src/email/email.md) — <!-- begin:auto-docs --> _(no submodules)_  - [email](./src/email/email.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/utils-error.md) — <!-- begin:auto-docs --> _(no submodules)_  - [utils-error](./src/errors/utils-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [number](./src/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_  - [number](./src/number/number.md) — <!-- begin:auto-docs --> _(no submodules)_- [object](./src/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_  - [object](./src/object/object.md) — <!-- begin:auto-docs --> _(no submodules)_- [platform](./src/platform/platform.md) — <!-- begin:auto-docs --> _(no submodules)_  - [platform](./src/platform/platform.md) — <!-- begin:auto-docs --> _(no submodules)_- [random](./src/random/pseudo.md) — <!-- begin:auto-docs --> _(no submodules)_  - [pseudo](./src/random/pseudo.md) — <!-- begin:auto-docs --> _(no submodules)_- [sound](./src/sound/sound.md) — <!-- begin:auto-docs --> _(no submodules)_  - [sound](./src/sound/sound.md) — <!-- begin:auto-docs --> _(no submodules)_- [string](./src/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_  - [string](./src/string/string.md) — <!-- begin:auto-docs --> _(no submodules)_- [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_  - [types](./src/types/types.md) — <!-- begin:auto-docs --> _(no submodules)_- [validate](./src/validate/validate.md) — <!-- begin:auto-docs --> _(no submodules)_  - [validate](./src/validate/validate.md) — <!-- begin:auto-docs --> _(no submodules)_- [validation](./src/validation/size.md) — <!-- begin:auto-docs --> _(no submodules)_  - [size](./src/validation/size.md) — <!-- begin:auto-docs --> _(no submodules)_
## Install

```bash
bun add @suaveplan/utils
```

## Quick Start

```typescript
// Object utilities
import { deepMerge, pick, omit } from "@suaveplan/utils/object";
const merged = deepMerge({ a: 1, b: { x: 1 } }, { b: { y: 2 } });
// { a: 1, b: { x: 1, y: 2 } }

// Email normalization
import { normalizeEmail } from "@suaveplan/utils/email";
normalizeEmail("Jane.Doe+promo@gmail.com"); // "janedoe@gmail.com"

// Sound sprites
import { parseSoundVariations, getSoundKey } from "@suaveplan/utils/sound";
const variations = parseSoundVariations({ step_1: [0,100], step_2: [100,100] });
const key = getSoundKey("step", variations); // "step_1" or "step_2"

// String generation
import { generateId, parseTextWithLinks } from "@suaveplan/utils/string";
const id = generateId({ length: 12 }); // 12-char hex string
const links = parseTextWithLinks("See https://example.com for details");

// Hex validation
import { isHex } from "@suaveplan/utils/validate";
isHex("deadbeef"); // true
isHex("gg");       // false

// Size validation
import { validateSize, formatSize, parseSize, SIZE_LIMITS } from "@suaveplan/utils/validation";
validateSize(payload, SIZE_LIMITS.MEDIUM); // throws if > 100KB
formatSize(1536);   // "1.50 KB"
parseSize("2MB");   // 2097152
```

## Modules

| Module | Description | Docs |
|--------|-------------|------|
| `@suaveplan/utils/debug` | Debug utilities: `assertDefined`, `invariant`, `unreachable`, `assert` | [debug.md](src/debug/debug.md) |
| `@suaveplan/utils/object` | Deep object manipulation: merge, clone, pick, omit, flatten, nested get/set | [object.md](src/object/object.md) |
| `@suaveplan/utils/platform` | Runtime environment detection: browser/Node/Bun/Edge/SSR flags | [platform.md](src/platform/platform.md) |
| `@suaveplan/utils/number` | IEEE 754 float packing/unpacking: Float16/32/64, range checks | [number.md](src/number/number.md) |
| `@suaveplan/utils/random` | Pseudo-random selection with seed: `pseudoRandom` | [pseudo.md](src/random/pseudo.md) |
| `@suaveplan/utils/email` | Provider-aware email normalization: Gmail/Yahoo/Microsoft/generic | [email.md](src/email/email.md) |
| `@suaveplan/utils/sound` | Howler.js sprite variation management: parse, select, convert | [sound.md](src/sound/sound.md) |
| `@suaveplan/utils/string` | String utilities: `generateId`, `parseTextWithLinks` | [string.md](src/string/string.md) |
| `@suaveplan/utils/validate` | Type-guard validators: `isHex` | [validate.md](src/validate/validate.md) |
| `@suaveplan/utils/validation` | Byte-size enforcement: `validateSize`, `formatSize`, `parseSize`, `truncateToSize` | [size.md](src/validation/size.md) |
| `@suaveplan/utils/errors` | Error class and code registry: `UtilsError`, `UTILS_CODES` | [utils-error.md](src/errors/utils-error.md) |

## Benchmarks

Measured on Intel Xeon E5-2696 v4 @ 2.20GHz, Bun 1.3.13.

### Object

| Benchmark | avg |
|-----------|-----|
| deepMerge small | 3.61 µs/iter |
| deepMerge medium | 705 ns/iter |
| deepClone small | 897 ns/iter |
| deepClone medium | 5.16 µs/iter |

### Number (float packing)

| Benchmark | avg |
|-----------|-----|
| packFloat16 | 88 ns/iter |
| packFloat32 | 1.29 µs/iter |
| packFloat64 | 589 ns/iter |

Run benchmarks locally:

```bash
bun benchmarks/object.bench.ts
bun benchmarks/number.bench.ts
```