joyful 0.1.0

Generate delightful, random word combinations - Rust port of the joyful TypeScript library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# joyful-rs

Generate delightful, random word combinations for your Rust app — perfect for project names, usernames, or unique identifiers.

> **Note:** This is a Rust port of the original [joyful](https://github.com/fvitale/joyful) TypeScript library.

## Installation

```toml
[dependencies]
joyful = "0.1.0"
```

## Usage

```rust
use joyful::{joyful, Options};

// Default: 2 segments with "-" separator
joyful(Options::default()).unwrap(); // "amber-fox"

// Custom segments
joyful(Options {
    segments: 3,
    ..Default::default()
}).unwrap(); // "golden-marble-cathedral"

// Custom separator
joyful(Options {
    segments: 3,
    separator: '_',
    ..Default::default()
}).unwrap(); // "swift_northern_lights"

// With max length constraint
joyful(Options {
    max_length: Some(20),
    ..Default::default()
}).unwrap(); // "tan-elk"
```

## API

### `joyful(options: Options) -> Result<String, ValidationError>`

Returns a randomly generated string or an error if constraints cannot be satisfied.

### `Options`

| Field        | Type             | Default | Description                           |
| ------------ | ---------------- | ------- | ------------------------------------- |
| `segments`   | `usize`          | `2`     | Number of words to generate           |
| `separator`  | `char`           | `'-'`   | Character between words               |
| `max_length` | `Option<usize>`  | `None`  | Maximum length of the returned string |

When `max_length` is set, words are intelligently selected to fit within the constraint. Returns `ValidationError::LengthConstraintImpossible` if the limit is too short to produce a valid result.

## Word Categories

The first word is always a prefix (adjective or color). Subsequent words are drawn from:

animals, architecture, art, emotions, fashion, food, history, literature, music, mythology, nature, professions, science, space, sports, transportation

## Permutations

| Segments | Combinations           |
| -------- | ---------------------- |
| 2        | 700,295                |
| 3        | 2,160,410,075          |
| 4        | 6,664,865,081,375      |
| 5        | 20,561,108,776,041,876 |

## Credits

- Rust port by Federico Vitale
- Original TypeScript library: [joyful](https://github.com/fvitale/joyful) by Federico Vitale
- Based on [friendly-words](https://github.com/glitchdotcom/friendly-words) by Glitch, with curated word lists and additional categories

## License

ISC