npm package: @neabyte/wordler
Description: Word scrambler based on anagram and permutation.
Author: NeaByteLab
Latest version: 0.1.0

# Wordler [![Module type: Deno/ESM](https://img.shields.io/badge/module%20type-deno%2Fesm-brightgreen)](https://github.com/NeaByteLab/Wordler) [![npm version](https://img.shields.io/npm/v/@neabyte/wordler.svg)](https://www.npmjs.org/package/@neabyte/wordler) [![JSR](https://jsr.io/badges/@neabyte/wordler)](https://jsr.io/@neabyte/wordler) [![CI](https://github.com/NeaByteLab/Wordler/actions/workflows/ci.yaml/badge.svg)](https://github.com/NeaByteLab/Wordler/actions/workflows/ci.yaml) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Word scrambler engine based on anagram and permutation.

## Installation

**Deno (JSR):**

```bash
deno add jsr:@neabyte/wordler
```

**npm:**

```bash
npm install @neabyte/wordler
```

## Usage

The Wordler engine provides several modes of operation to find the exact permutations you need.

### 1. Basic Scrambling (Anagrams)

By default, the engine works as an anagram generator. It will find all possible permutations using **all** characters provided in the input string.

```typescript
import Wordler from '@neabyte/wordler'

const results = Wordler.scramble('dog')
// Results: 'dog', 'dgo', 'odg', 'ogd', 'gdo', 'god'
```

### 2. Wildcards for Discovery

Use the `*` character to represent any letter from `a` to `z`. This is useful for discovering words when you only have partial information.

```typescript
// Find 3-letter words starting with 'a' and 'b'
const results = Wordler.scramble('ab*', { limit: 5 })
// Results: 'aba', 'abb', 'abc', 'abd', 'abe'
```

### 3. Character Sets (Fixed Position)

Brackets `[abc]` allow you to specify a set of allowed characters for a single position. The engine will pick exactly one character from the set.

```typescript
// Starts with a vowel, followed by 'lc'
const results = Wordler.scramble('[aeiou]lc', { mode: 'template' })
// Results: 'alc', 'elc', 'ilc', 'olc', 'ulc'
```

### 4. Template Mode vs Scramble Mode

- **Scramble Mode** (Default): Permutes all character slots. It treats your input as a "bag of slots" and tries every possible order.
- **Template Mode**: Keeps each character/slot in its specific index. Ideal for fixed-layout pattern discovery.

```typescript
// Template mode keeps 'fixed' at the end
const results = Wordler.scramble('***fixed', { mode: 'template' })
```

### 5. Automatic Deduplication

The engine internally uses a `Set` to ensure all returned permutations are unique, even if your input contains duplicate characters.

```typescript
const results = Wordler.scramble('banana')
// No duplicate 'banana' entries in the result set
```

## API Reference

### `Wordler.scramble(letters, options?)`

Generates unique letter permutations from input.

**Parameters:**

- `letters: string` - Input letters. Supports special syntax:
  - `*`: Wildcard (a-z)
  - `[abc]`: Character set (one from the list)
- `options: WordlerOptions` - Optional configuration:
  - `min: number`: Minimum word length (Scramble mode only)
  - `max: number`: Maximum word length (Scramble mode only)
  - `limit: number`: Maximum number of results
  - `mode: 'scramble' | 'template'`: Execution strategy

**Returns:** `WordlerResult[]` - Array of generated permutations.

**Types:**

```typescript
interface WordlerOptions {
  readonly min?: number // Minimum word length
  readonly max?: number // Maximum word length
  readonly limit?: number // Results count limit
  readonly mode?: 'scramble' | 'template'
}

interface WordlerResult {
  readonly word: string // Generated permutation
  readonly length: number // Word length
}
```

## Safety Features

For inputs exceeding 12 characters, a `limit` of 1,000,000 or less is required to prevent memory exhaustion.

## License

This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.