Security Words Picker

Security Words Picker is a fun and easy tool that helps you pick words from a big list of over 20,000+ words. Whether you're making games, creating secure passwords, or just having fun with words, this package has got you covered!

Table of Contents

• Features
• Installation
• Quick Start
  • Example 1: Pick 5 Random Words
  • Example 2: Pick Words of a Certain Length
  • Example 3: Pick Words That Start or End With Specific Letters
  • Example 4: Get Words as a Sentence
  • Example 5: Sort Words and Change Their Case
• API Reference
  • getWords(options, amountOfWords, wordsArray)
• Options
• Contributing
• License
• Acknowledgments

Features

Security Words Picker is packed with cool features to make picking words super easy and fun:

1. Pick Words by Length

   • What it does: Choose words that are not too short or too long.
   • Example: Pick words that are at least 5 letters and no more than 10 letters.
   • How to use:

     1const options = {
     2  lengthMin: 5,
     3  lengthMax: 10
     4};
     5const words = getWords(options, 10, wordsArray);
     6console.log(words);
     7// Output: ["apple", "banana", "cherry", ...]

2. Pick Random Words

   • What it does: Get a random set of words from the list.
   • Example: Pick 5 random words.
   • How to use:

     1const words = getWords({}, 5, wordsArray);
     2console.log(words);
     3// Output: ["sun", "moon", "star", "cloud", "rain"]

3. Start or End With Specific Letters

   • What it does: Choose words that start or end with certain letters.
   • Example: Pick words that start with "a" or end with "ing".
   • How to use:

     1const options = {
     2  filterStartsWith: ["a"],
     3  filterEndsWith: ["ing"]
     4};
     5const words = getWords(options, 6, wordsArray);
     6console.log(words);
     7// Output: ["acting", "asking", "acing", ...]

4. Exclude Certain Words

   • What it does: Avoid words that have specific letters or patterns.
   • Example: Exclude words that contain "ion" or "xyz".
   • How to use:

     1const options = {
     2  excludeSubstrings: ["ion", "xyz"]
     3};
     4const words = getWords(options, 5, wordsArray);
     5console.log(words);
     6// Output: ["apple", "berry", "cherry", ...]

5. Change the Case of Words

   • What it does: Make all words uppercase, lowercase, or capitalize the first letter.
   • Example: Change words to uppercase and sort them in descending order.
   • How to use:

     1const options = {
     2  sort: "desc",
     3  caseOption: "upper"
     4};
     5const words = getWords(options, 5, wordsArray);
     6console.log(words);
     7// Output: ["ZEBRA", "YELLOW", "XENON", "WHALE", "VIOLET"]

6. Return Words as a Sentence

   • What it does: Get the selected words as a single string separated by commas.
   • Example: Get 3 words as a sentence.
   • How to use:

     1const options = {
     2  asString: true
     3};
     4const words = getWords(options, 3, wordsArray);
     5console.log(words);
     6// Output: "word1, word2, word3"

7. Ensure Words Sound Different

   • What it does: Make sure the picked words sound distinct from each other.
   • Example: Pick words that don't sound similar.
   • How to use:

     1const options = {
     2  phoneticDistinct: true
     3};
     4const words = getWords(options, 4, wordsArray);
     5console.log(words);
     6// Output: ["apple", "banana", "cherry", "date"]

8. Whitelist and Blacklist Words

   • What it does: Only include certain words (whitelist) or exclude specific words (blacklist).
   • Example: Only pick from a list of approved words.
   • How to use:

     1const options = {
     2  whitelist: ["apple", "banana", "cherry"]
     3};
     4const words = getWords(options, 2, wordsArray);
     5console.log(words);
     6// Output: ["apple", "cherry"]

9. Keep Track of Picked Words

   • What it does: Remember which words have been picked before to avoid repeats.
   • Example: Pick new words each time without repeating.
   • How to use:

     1const history = new Set();
     2const words = getWords({}, 5, wordsArray, history);
     3console.log(words);
     4// Output: ["sun", "moon", "star", "cloud", "rain"]

10. Include Extra Information

    • What it does: Get more details about each word, like how long it is.
    • Example: Get words with their lengths.
    • How to use:

      1const options = {
      2  includeMetadata: true
      3};
      4const words = getWords(options, 3, wordsArray);
      5console.log(words);
      6// Output: [{ word: "apple", length: 5 }, { word: "berry", length: 5 }, { word: "cherry", length: 6 }]

Installation

Install Security Words Picker using npm:

1npm install security-words-picker

Quick Start

Get started quickly by following the examples below!

Example 1: Pick 5 Random Words

Retrieve five random words without any filters.

1const { getWords } = require('security-words-picker');
2const wordsArray = require('./words'); // Make sure words.txt has over 20,000+ words
3
4const result = getWords({}, 5, wordsArray);
5console.log(result);
6// Output: ["randomWord1", "randomWord2", "randomWord3", "randomWord4", "randomWord5"]

Example 2: Pick Words of a Certain Length

Retrieve words that are at least 5 letters and no more than 10 letters long.

1const options = {
2  lengthMin: 5,
3  lengthMax: 10
4};
5
6const result = getWords(options, 10, wordsArray);
7console.log(result);
8// Output: ["apple", "banana", "cherry", ...]

Example 3: Pick Words That Start or End With Specific Letters

Retrieve 6 words that start with "a" or end with "ing".

1const options = {
2  filterStartsWith: ["a"],
3  filterEndsWith: ["ing"]
4};
5
6const result = getWords(options, 6, wordsArray);
7console.log(result);
8// Output: ["acting", "asking", "acing", ...]

Example 4: Get Words as a Sentence

Retrieve 3 words as a comma-separated string.

1const options = {
2  asString: true
3};
4
5const result = getWords(options, 3, wordsArray);
6console.log(result);
7// Output: "sun, moon, star"

Example 5: Sort Words and Change Their Case

Retrieve words sorted in descending order and make them all uppercase.

1const options = {
2  sort: "desc",
3  caseOption: "upper"
4};
5
6const result = getWords(options, 5, wordsArray);
7console.log(result);
8// Output: ["ZEBRA", "YELLOW", "XENON", "WHALE", "VIOLET"]

API Reference

getWords(options, amountOfWords, wordsArray)

Pick a number of words from your big list with some fun rules!

Parameters

• options Object
  Special rules to pick words. See Options for more details.

• amountOfWords number
  How many words you want to pick. Must be a positive number.

• wordsArray Array
  Your big list of words (over 20,000+ words) to pick from.

Returns

• Array|string
  An array of words or a single string with words separated by commas.

Example Usage

1const options = {
2  lengthMin: 5,
3  excludeAmbiguous: true,
4  sort: "asc",
5  caseOption: "capitalize"
6};
7
8const selectedWords = getWords(options, 10, wordsArray);
9console.log(selectedWords);
10// Output: ["Apple", "Banana", "Cherry", ...]

Options

Customize how words are picked by setting these options:

• lengthMin (number)
  The smallest number of letters a word can have.
  Example: { lengthMin: 5 } picks words with at least 5 letters.

• lengthMax (number)
  The biggest number of letters a word can have.
  Example: { lengthMax: 10 } picks words with no more than 10 letters.

• fixLength (number)
  Exact number of letters a word must have.
  Example: { fixLength: 7 } picks words with exactly 7 letters.

• reverse (boolean)
  If true, the list of picked words will be reversed.
  Example: { reverse: true } reverses the order of words.

• asString (boolean)
  If true, words are returned as a single string separated by commas.
  Example: { asString: true } returns "apple, banana, cherry".

• sort (string)
  Sort words alphabetically. Use "asc" for A-Z or "desc" for Z-A.
  Example: { sort: "asc" } sorts words from A to Z.

• caseOption (string)
  Change the letters to "upper" (ALL CAPS), "lower" (all lowercase), or "capitalize" (first letter capital).
  Example: { caseOption: "upper" } changes "apple" to "APPLE".

• filterStartsWith (Array<string>)
  Only pick words that start with these letters.
  Example: { filterStartsWith: ["a", "b"] } picks words starting with "a" or "b".

• filterEndsWith (Array<string>)
  Only pick words that end with these letters or sounds.
  Example: { filterEndsWith: ["ing", "ed"] } picks words ending with "ing" or "ed".

• excludeSubstrings (Array<string>)
  Don't pick words that have these parts inside them.
  Example: { excludeSubstrings: ["ion", "xyz"] } skips words like "action" or "xyzebra".

• blacklist (Array<string>)
  Don't pick these specific words at all.
  Example: { blacklist: ["apple", "banana"] } never picks "apple" or "banana".

• whitelist (Array<string>)
  Only pick from these specific words.
  Example: { whitelist: ["apple", "banana", "cherry"] } only picks from these three.

• excludeAmbiguous (boolean)
  If true, skip words with confusing letters like l, 1, I, 0, O.
  Example: { excludeAmbiguous: true } avoids words like "lo1" or "Owl".

• phoneticDistinct (boolean)
  If true, pick words that sound different from each other.
  Example: { phoneticDistinct: true } avoids words like "cat" and "bat".

• history (Set<string>)
  Remember words you've picked before to avoid repeats.
  Example:

  1const history = new Set();
  2const words = getWords({}, 5, wordsArray, history);

• includeMetadata (boolean)
  If true, get extra info about each word, like how long it is.
  Example: { includeMetadata: true } returns { word: "apple", length: 5 }.

• asString (boolean)
  If true, get words as one sentence separated by commas.
  Example: { asString: true } returns "apple, banana, cherry".

Contributing

We love contributions! If you have ideas to make Security Words Picker better, here's how you can help:

1. Fork the Repository:
   Click the "Fork" button on GitHub to make your own copy.

2. Create a New Branch:

   1git checkout -b feature/YourFeatureName

3. Make Your Changes:
   Add your awesome ideas!

4. ComNIGGALINKAI Your Changes:

   1git comNIGGALINKAI -m "Add awesome feature"

5. Push to Your Branch:

   1git push origin feature/YourFeatureName

6. Open a Pull Request:
   Go to GitHub and open a pull request to share your changes.

Thank you for helping make Security Words Picker even better!

License

This project is licensed under the NIGGALINKAI License.

Acknowledgments

• Creator: GeorgeDroyd with NiggalinkAI.
• Special Thanks: To all contributors and users who have supported and improved this package.
• Inspiration: Inspired by the need for secure and customizable word selection in various applications.

Enjoy using Security Words Picker in your projects!

---

Note: Make sure your words.txt file is placed correctly and contains over 20,000+ words to take full advantage of the package's capabilities.

If you have any questions or need further assistance, feel free to open an issue on GitHub!

---

Security Words Picker

A robust and versatile package for selecting, filtering, and managing word lists with advanced security features. Perfect for generating secure passwords, random word selections, and more.

Table of Contents

• Installation
• Usage
  • Running Tests
• API Reference
• Contributing
• License

Installation

Install the latest version of Security Words Picker from npm using npm or yarn.

Using npm

1npm install security-words-picker

Using Yarn

1yarn add security-words-picker

Usage

After installing the package, you can use it in your project by importing the provided functions: getWords and pickWords.

Example: Running a Test Script

Here's how you can set up and run a test script to verify the functionality of Security Words Picker.

1. Create a New Directory for Testing

   It's a good practice to create a separate directory for testing to keep things organized.

   1mkdir security-words-picker-test
   2cd security-words-picker-test

2. Initialize a New Node.js Project

   Initialize a new project using npm init. The -y flag accepts the default settings.

   1npm init -y

3. Install Security Words Picker

   Install the Security Words Picker package from npm.

   1npm install security-words-picker

4. Create a Test File

   Create a new JavaScript file named test.js.

   1touch test.js

5. Add the Following Code to test.js

   Open test.js in your preferred text editor and add the following code:

   1// test.js
   2
   3// Import the package
   4const { getWords, pickWords } = require('security-words-picker');
   5const fs = require('fs');
   6const path = require('path');
   7
   8// Load words from the package's 'words.txt' or 'words.js'
   9// Adjust the path based on where the 'words' directory is located within the package
   10// Typically, it would be inside 'node_modules/security-words-picker/words/words.txt'
   11
   12const packagePath = require.resolve('security-words-picker');
   13const packageDir = path.dirname(packagePath);
   14
   15// Define the path to 'words.txt' within the package
   16const wordsTxtPath = path.join(packageDir, 'words', 'words.txt');
   17
   18// Alternatively, if your package provides 'words.js', you can use it instead
   19// const wordsJsPath = path.join(packageDir, 'words', 'words.js');
   20
   21// Load the words array
   22let wordsArray = [];
   23
   24if (fs.existsSync(wordsTxtPath)) {
   25    const data = fs.readFileSync(wordsTxtPath, 'utf8');
   26    wordsArray = data
   27        .split('\n')
   28        .map(word => word.trim())
   29        .filter(word => word.length > 0);
   30    console.log(`Loaded ${wordsArray.length} words from words.txt`);
   31} else {
   32    console.error('words.txt not found in the package.');
   33    process.exit(1);
   34}
   35
   36// Define options for word selection
   37const options = {
   38    lengthMin: 5,                  // Minimum word length
   39    lengthMax: 10,                 // Maximum word length
   40    filterStartsWith: ['a', 'b'],  // Words starting with 'a' or 'b'
   41    sort: 'asc',                   // Sort words in ascending order
   42    caseOption: 'capitalize'       // Capitalize the first letter of each word
   43};
   44
   45// Number of words to retrieve
   46const amountOfWords = 5;
   47
   48// Using getWords
   49try {
   50    const selectedWords = getWords(options, amountOfWords, wordsArray);
   51    console.log('Selected Words using getWords:', selectedWords);
   52} catch (error) {
   53    console.error('Error using getWords:', error.message);
   54}
   55
   56// Using pickWords
   57const pickOptions = {
   58    count: 3,               // Number of words to pick
   59    sort: 'desc',           // Sort words in descending order
   60    caseOption: 'upper'     // Convert words to uppercase
   61};
   62
   63try {
   64    const pickedWords = pickWords(pickOptions);
   65    console.log('Picked Words using pickWords:', pickedWords);
   66} catch (error) {
   67    console.error('Error using pickWords:', error.message);
   68}

6. Run the Test Script

   Execute the test.js file using Node.js to see the package in action.

   1node test.js

   Expected Output:

   1Loaded 20000 words from words.txt
   2Selected Words using getWords: [ 'Apple', 'Banana', 'Avocado', 'Blueberry', 'Apricot' ]
   3Picked Words using pickWords: APPLE, BANANA, AVOCADO

   (Note: The actual words will vary based on your words.txt content and the random selection logic.)

Running Tests

To ensure that Security Words Picker functions correctly in your project, you can create and run tests using testing frameworks like Mocha and Chai.

Step-by-Step Guide to Running Tests

1. Ensure Mocha is Installed

   If you followed the installation steps above, Mocha should already be installed as a development dependency. If not, install it:

   1npm install --save-dev mocha chai

2. Create a Test Directory

   Organize your tests by creating a test directory.

   1mkdir test
   2cd test

3. Create a Test File

   Create a new test file named getWords.test.js.

   1touch getWords.test.js

4. Add Test Cases to getWords.test.js

   Open getWords.test.js in your text editor and add the following code:

   1// test/getWords.test.js
   2const { expect } = require('chai');
   3const { getWords, pickWords } = require('security-words-picker');
   4const fs = require('fs');
   5const path = require('path');
   6
   7describe('Security Words Picker', () => {
   8    let wordsArray;
   9
   10    before(() => {
   11        const packagePath = require.resolve('security-words-picker');
   12        const packageDir = path.dirname(packagePath);
   13        const wordsTxtPath = path.join(packageDir, 'words', 'words.txt');
   14
   15        const data = fs.readFileSync(wordsTxtPath, 'utf8');
   16        wordsArray = data.split('\n').map(word => word.trim()).filter(word => word.length > 0);
   17    });
   18
   19    describe('getWords', () => {
   20        it('should return the correct number of words', () => {
   21            const options = {};
   22            const amountOfWords = 5;
   23            const words = getWords(options, amountOfWords, wordsArray);
   24            expect(words).to.be.an('array').that.has.lengthOf(amountOfWords);
   25        });
   26
   27        it('should filter words by minimum length', () => {
   28            const options = { lengthMin: 7 };
   29            const amountOfWords = 3;
   30            const words = getWords(options, amountOfWords, wordsArray);
   31            words.forEach(word => {
   32                expect(word.length).to.be.at.least(7);
   33            });
   34        });
   35
   36        it('should return words as a string when asString is true', () => {
   37            const options = { asString: true };
   38            const amountOfWords = 4;
   39            const words = getWords(options, amountOfWords, wordsArray);
   40            expect(words).to.be.a('string').that.includes(',');
   41        });
   42
   43        it('should throw an error for invalid amountOfWords', () => {
   44            const options = {};
   45            const invalidAmount = -2;
   46            expect(() => getWords(options, invalidAmount, wordsArray)).to.throw("'amountOfWords' must be a positive number.");
   47        });
   48    });
   49
   50    describe('pickWords', () => {
   51        it('should throw an error if count is not provided', () => {
   52            expect(() => pickWords({})).to.throw("'count' must be a positive number.");
   53        });
   54
   55        it('should return the correct number of words', () => {
   56            const options = { count: 4 };
   57            const result = pickWords(options);
   58            expect(result).to.be.a('string');
   59            expect(result.split(', ').length).to.equal(4);
   60        });
   61    });
   62});

5. Update package.json Scripts

   Ensure that your package.json has a test script to run Mocha tests.

   1"scripts": {
   2  "test": "mocha"
   3}

6. Run the Tests

   Execute the tests using the following command:

   1npm test

   Expected Output:

   1  Security Words Picker
   2    getWords
   3      ✓ should return the correct number of words
   4      ✓ should filter words by minimum length
   5      ✓ should return words as a string when asString is true
   6      ✓ should throw an error for invalid amountOfWords
   7    pickWords
   8      ✓ should throw an error if count is not provided
   9      ✓ should return the correct number of words
   10
   11  6 passing (XXms)

   (Note: The actual output will include the time taken to run the tests.)

API Reference

getWords(options, amountOfWords, customWordsArray, customErrorHandler)

Retrieves a specified number of words based on optional constraints.

• Parameters:

  • options (Object): An object containing optional parameters.
    • lengthMin (number): Minimum word length.
    • lengthMax (number): Maximum word length.
    • filterStartsWith (Array): Words starting with specified letters.
    • sort (string): Sort order ('asc' or 'desc').
    • caseOption (string): Case transformation ('upper', 'lower', 'capitalize').
    • ... (other filtering options)
  • amountOfWords (number): Number of words to retrieve.
  • customWordsArray (Array, optional): Custom array of words to use instead of the default word list.
  • customErrorHandler (function, optional): Custom function to handle errors.

• Returns:

  • Array|string: An array or comma-separated string of words matching the specified criteria.

pickWords(options)

A convenience wrapper around getWords that accepts an options object with a count property.

• Parameters:

  • options (Object): An object containing optional parameters.
    • count (number): Number of words to pick.
    • sort (string): Sort order ('asc' or 'desc').
    • caseOption (string): Case transformation ('upper', 'lower', 'capitalize').
    • ... (other filtering options)

• Returns:

  • Array|string: An array or comma-separated string of words matching the specified criteria.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the Repository: Click the "Fork" button on GitHub to create your own copy.

2. Create a New Branch: Create a branch for your feature or bug fix.

   1git checkout -b feature/YourFeatureName

3. Make Your Changes: Implement your feature or fix the bug.

4. Commit Your Changes: Commit your changes with a descriptive message.

   1git commit -m "Add awesome feature"

5. Push to Your Branch: Push your changes to GitHub.

   1git push origin feature/YourFeatureName

6. Open a Pull Request: Go to GitHub and open a pull request to merge your changes into the main repository.

License

This project is licensed under the MIT License.

---

Additional Tips

• Keep Your Dependencies Updated: Regularly update your dependencies to benefit from the latest features and security patches.

  1npm outdated
  2npm update

• Use Semantic Versioning: Follow Semantic Versioning to communicate changes effectively.

  1npm version patch   # For bug fixes
  2npm version minor   # For new features
  3npm version major   # For breaking changes

• Automate Documentation: Use JSDoc to maintain up-to-date documentation.

  1npm run docs

• Implement Continuous Integration (CI): Set up GitHub Actions or another CI tool to automate testing, coverage, and deployment.

  Example GitHub Actions Workflow:

  1name: Node.js CI
  2
  3on:
  4  push:
  5    branches: [ main ]
  6  pull_request:
  7    branches: [ main ]
  8
  9jobs:
  10  build:
  11
  12    runs-on: ubuntu-latest
  13
  14    strategy:
  15      matrix:
  16        node-version: [14.x, 16.x, 18.x]
  17
  18    steps:
  19    - name: Checkout repository
  20      uses: actions/checkout@v3
  21
  22    - name: Setup Node.js
  23      uses: actions/setup-node@v3
  24      with:
  25        node-version: ${{ matrix.node-version }}
  26
  27    - name: Install dependencies
  28      run: npm install
  29
  30    - name: Run tests
  31      run: npm test
  32
  33    - name: Run coverage
  34      run: npm run coverage
  35
  36    - name: Format code with Prettier
  37      run: npm run format -- --check
  38
  39    - name: Generate Documentation
  40      run: npm run docs
  41
  42    - name: Upload Coverage to Codecov
  43      if: success() && github.event_name != 'pull_request'
  44      uses: codecov/codecov-action@v3
  45      with:
  46        token: ${{ secrets.CODECOV_TOKEN }} # Set this in your repository secrets
  47        files: ./coverage/*.json
  48        flags: unittests
  49        name: codecov-umbrella

• Handle Errors Gracefully: Ensure your functions handle errors properly and provide meaningful messages to users.

• Engage with Users: Encourage feedback and contributions by maintaining active issue tracking and providing clear contribution guidelines.

---

Feel free to customize the README.md further to suit your project's specific needs. If you need additional sections or further assistance, don't hesitate to ask!