foswig/README.md

A library that can generate legible pseudo random words based off an input dictionary using markov chains

# Foswig.js

[![Build Status](https://travis-ci.org/mrsharpoblunto/foswig.js.svg?branch=master)](https://travis-ci.org/mrsharpoblunto/foswig.js)
[![npm version](https://badge.fury.io/js/foswig.svg)](https://badge.fury.io/js/foswig)

A JavaScript library which allows you to easily create [Markov chains](http://en.wikipedia.org/wiki/Markov_chain) based on arbitrary dictionaries in order to create readable pseudo-random words (Yes, the name was generated by the library). See a demo of this library in action [here](http://mrsharpoblunto.github.io/foswig.js/).

## Usage

```javascript
// If you're using the following
// - A bundler like Rollup or Webpack
// - node>=12 and have set "type": "module" in your package.json
// - node>=12 and the parent file has a .mjs extension
import Foswig from 'foswig';
// otherwise require using commonjs
const Foswig = require('foswig').default;

// Create the Markov chain and specify the order of the chain & input dictionary
// The order (an integer that is greater than 0) indicates how many previous 
// letters are taken into account when selecting the next one. A smaller order 
// will result in a more randomized, less recognizeable output. Also, a higher 
// order will result in words which resemble more closely to those in the original 
//dictionary.
const chain = new Foswig(3, [
  "hello",
  "foswig",
]);


// Generate a random word with a minimum of 5 characters, a maximum of 10 letters, 
// and that cannot be a match to any of the input dictionaries words.
const constraints = { 
  minLength: 2, 
  maxLength: 10, 
  allowDuplicates: true
};
const word = chain.generate(constraints);
```

  
## Constraints

- *minLength* (optional, default: 0): Minimum length of the word (optional, default: 0) 
- *maxLength* (optional, default: 0): Maximum length of the word, 0 indicates no max length)
- *allowDuplicates* (optional, default: true): Can the output be an exact match of a dictionary input word or not
- *maxAttempts* (optional, default: 25): The maximum number of attempts to generate a word matching the constraints above before throwing an error, use 0 to allow infinite attempts, but this may result in hangs if the constraints cannot be satisfied.
- *random* (optional, default: Math.random): A function that returns a random floating point number between 0-1.

## License

Foswig.js is licensed under the [MIT license](https://github.com/mrsharpoblunto/foswig.js/blob/master/LICENSE).