rword
    TypeScript icon, indicating that this package has built-in type declarations

    3.2.1 • Public • Published

    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

    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.

    Install

    npm i rword

    DownloadsWeekly Downloads

    1,841

    Version

    3.2.1

    License

    MIT

    Unpacked Size

    5.84 MB

    Total Files

    23

    Last publish

    Collaborators

    • xyfir