# rok-utils

A Laravel/AdonisJS-inspired utility crate for Rust.

> **Version:** 0.1.0  
> **Edition:** Rust 2021

## Overview

`rok-utils` provides zero-bloat, ergonomic utility functions inspired by Laravel's `Illuminate\Support\Str` and AdonisJS's `@adonisjs/core/helpers`. Designed for the Rok ecosystem.

## Features

- **String utilities** — case conversion, truncation, pluralization, fluent builder
- **Array utilities** — map, filter, reduce, chunk, unique, group_by
- **Path helpers** — normalize, stem_ext, with_extension
- **Data utilities** — numbers, dates (feature: dates), hashing (feature: crypto), ids (feature: ids)
- **Fluent builder** — `Str::of()` chainable API
- **Error handling** — AdonisJS-style error codes
- **Functional patterns** — pipe, compose, tap, retry
- **Type guards** — JSON type guards (feature: json)

## Installation

```toml
[dependencies]
rok-utils = "0.1.0"
```

## Usage

```rust
use rok_utils::{to_snake_case, to_camel_case, truncate, Str};

let snake = to_snake_case("HelloWorld");
assert_eq!(snake, "hello_world");

let camel = to_camel_case("hello_world");
assert_eq!(camel, "helloWorld");

let truncated = truncate("hello world", 5);
assert_eq!(truncated, "he...");

// Fluent API
use rok_utils::str::Str;

let result = Str::of("  Hello World  ")
    .trim()
    .to_snake_case()
    .truncate(20)
    .value();
assert_eq!(result, "hello_world");
```

## Module Structure

```
src/
├── lib.rs          # Public API
├── string.rs       # to_snake_case, to_camel_case, truncate, pluralize
├── str.rs          # Fluent builder Str
├── arr.rs          # map, filter, reduce, unique, group_by
├── path.rs         # normalize, stem_ext, with_extension
├── fs.rs           # file system utilities
├── data/
│   ├── numbers.rs # format_number, round, clamp, lerp
│   ├── dates.rs   # date helpers (feature: dates)
│   ├── ids.rs    # UUID, ULID (feature: ids)
│   └── hashing   # SHA-256, tokens (feature: crypto)
├── errors/         # RokError enum
├── fp/             # pipe, compose, tap
└── types/         # JSON type guards
```

## Quality Gates

```bash
cargo fmt --check
cargo clippy -- -D warnings
cargo test --all-features
cargo test --doc
```

## Roadmap

See [plan/12-roadmap.md](plan/12-roadmap.md) for milestones.

## License

MIT