Wordler

Word scrambler engine based on anagram and permutation.

Installation

Deno (JSR):

deno add jsr:@neabyte/wordler

npm:

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.

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.

// 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.

// 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.

// 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.

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:

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 file for more info.