# Overview & Philosophy

`rok-utils` is a **zero-bloat, modular utility crate** for the Rok ecosystem. It follows the same
design philosophy as Laravel's `Illuminate\Support\Str` and AdonisJS's `@adonisjs/core/helpers`:
utilities are ergonomic, predictable, and composable.

## Design Principles

- **Fluent API first** — chainable builder pattern mirroring Laravel's `Str::of()` / AdonisJS's
  `string.camelCase().truncate()` pipeline
- **No runtime panics** — all functions return `Result<T, RokError>` or `Option<T>`; never `unwrap()`
  in library code
- **Feature-flagged** — heavy dependencies (crypto, chrono, uuid) are opt-in via Cargo features
- **UTF-8 native** — all string operations use `chars()`, never raw bytes, mirroring AdonisJS's
  unicode-safe `escapeHTML` / `encodeSymbols` approach
- **`< 400 lines` per file** — every module is a single focused concern; no "god files"
- **Fully tested** — unit tests + `proptest` for invariant testing + doctests as living documentation

## Comparison Table

| Feature                  | Laravel (`Str::`)           | AdonisJS (`string.`)        | `rok-utils`              |
|--------------------------|-----------------------------|-----------------------------|--------------------------|
| Case conversion          | `snake()`, `camel()`        | `snakeCase()`, `camelCase()`| `to_snake_case()` etc.   |
| Fluent chaining          | `Str::of('x')->slug()`      | N/A                         | `Str::of("x").slug()`    |
| Slug generation          | `Str::slug()`               | `string.slug()`             | `str::slug()`            |
| Pluralize                | `Str::plural()`             | `string.plural()`           | `str::plural()` (feature)|
| Error types              | `HttpException`             | `E_HTTP_EXCEPTION`          | `RokError` enum          |
| Byte/time parsing        | N/A                         | `string.bytes.parse('1MB')` | `parse_bytes()` etc.     |
| Random string            | `Str::random(32)`           | `string.random(32)`         | `str::random(32)`        |