Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/xyfir/rword
🎲 A cryptographically secure random generator for real English words. Contains 350,000+ English words.
https://github.com/xyfir/rword
nodejs random random-generation random-word-generator words
Last synced: 3 months ago
JSON representation
🎲 A cryptographically secure random generator for real English words. Contains 350,000+ English words.
- Host: GitHub
- URL: https://github.com/xyfir/rword
- Owner: xyfir
- License: mit
- Created: 2017-01-06T20:18:08.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2022-02-11T20:02:52.000Z (almost 3 years ago)
- Last Synced: 2024-07-21T07:33:13.365Z (4 months ago)
- Topics: nodejs, random, random-generation, random-word-generator, words
- Language: TypeScript
- Homepage: https://npmjs.com/package/rword
- Size: 2.64 MB
- Stars: 156
- Watchers: 7
- Forks: 20
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
A cryptographically secure Node.js random generator for real English words. Contains over 350,000 English words.
**Note:** rword stores its words array in memory, and limited testing shows this to add about ~20-60 MB to Node's heap depending on which word list you choose. rword is built to be fast and self-contained without the need for a database and this price is paid at the expense of your RAM.
# Examples
```ts
import { rword } from 'rword';
rword.generate();
// 'bioplasm'
rword.generate(5);
// ['verniers', 'recognizes', 'shockstall', 'aerofoils', 'sooling']
rword.generate(5, { length: 5 });
// ['crags', 'allyl', 'vower', 'berob', 'divan']
rword.generate(3, { length: '3-4' });
// ['limo', 'fado', 'calf']
rword.generate(5, { contains: '.*ed' });
// ['outvied', 'lappeted', 'roared', 'needfully', 'catechized']
rword.generate(5, { contains: 'af' });
// ['falafels', 'handstaff', 'bushcrafts', 'cafila', 'cybercafe']
rword.generate(5, { contains: /.*ing$/ });
// ['depicting', 'upstanding', 'scending', 'forking', 'numbing']
rword.generate(3, { capitalize: 'all' });
// ['THEORIZED', 'RETIRE', 'HOLDBACK']
rword.generate(3, { capitalize: 'first' });
// ['Grew', 'Waxberries', 'Neesing']
rword.generateFromPool(5);
// [ 'intimae', 'shandygaff', 'likable', 'unrebated', 'broken' ]
```
# Words
rword comes with two word lists: `small`, with a "tiny" ~123k words, and `big`, with ~350k. By default, rword uses `small`.
All of the words contain _only_ `a-z` characters. There are no numbers, symbols, spaces, or diacritics.
`small` contains only words 3-10 characters in length, while `big` has no length requirements.
`small` is likely to decrease in size in the future, while `big` may increase.
# API
## `rword.generate(count, options)`
Generates words from the global words array.
- `count: number` - Optional (default `1`) - How many words to return. If `1` or not present, a string is returned. If greater than `1` an array of strings is returned.
- `options: object` - Optional - Allows you to modify the output and words that could be randomly chosen.
- `options.length: number|string` - Optional (default `'3-10'`) - Allows you to set an exact length or range of lengths for words to return.
- `options.contains: string|RegExp` - Optional (default `/.*/`) - Words that don't match the regexp will not be returned.
- `options.capitalize: string` - Optional (default `'none'`) - Changes the capitalization of the words returned. Possible values: `'none' | 'all' | 'first'`.
It should be obvious, but be warned that there's no guarantee you'll receive as many words as requested if you use any of the filtering options. In addition, adding filters to is slow, and should be avoided if possible. Use `rword.generateFromPool()` if possible as it can be much faster, especially for generating a single word.
## `rword.generateFromPool(count)`
Generates words from the global pool array. The pool is automatically filled using `rword.generate(500)` and then words are taken out of that array as needed. Can be faster than `rword.generate()` for generating small amounts of words.
- `count: number` - Optional (default `1`) - How many words to return. If `1` or not present, a string is returned. If greater than `1` an array of strings is returned.
**Limitations:**
- No options object is accepted.
- You cannot request more than 10 words through this method.
## `rword.load(list)`
Loads and shuffles word list. This is a blocking function that does a lot of processing, so don't call it often.
- `list: "big" | "small"` - The list you'll load into rword. `"small"` is automatically loaded upon first importing rword.
## `rword.shuffle()`
Shuffles both the global and pool words arrays. This method can most likely be ignored as it is automatically called on first run.
## `rword.words`
The full (shuffled) words array that is used internally by rword. Likely there's no need for this but if you'd like to bypass the rword API and just utilize its words then this is what you'll need.