npm package: @idsync/generator
Description: NodeJS password generator
Latest version: 0.0.2

# idsync Password Generator 

A password generator that's used in [idsync](https://github.com/idsync).

## Usage
You can generate a generic password by simply running the following:

```javascript
const { generatePassword, getConfig } = require("@idsync/generator");

const config = getConfig(); // Generic config
generatePassword(config).then(password => {
    // password is a string
});
```

You can change what types of passwords are generated by manipulating the `config` object.

### Generation errors
Errors may occur for a variety of reasons, primarily due to user options being too restrictive (or just by random chance). Each predictable error should have a code (`thrownError.code`) associated with it:

 * `BAD_MODE`: An invalid generation mode was selected.
 * `NO_CHARSETS`: No character sets were enabled - so no password could be generated.
 * `MAX_RETRIES`: An attempt at generating a password was made, but due to the selected character sets, restrictive repeat rules (`config.randomCharacters.allowRepeatingCharacters` and `config.randomCharacters.allowRepeatingSets`) and random chance, no password could be generated within the allowed number of retries.

### Configuration
After getting a configuration object by running `getConfig()`, you can set `config.mode` to one of the two following behaviours:

 * **characters**: Generate a password made up of random characters. Character sets are used to customise the output. This is the default mode.
 * **words**: Generate a password made up of random words.

#### Random character configuration
You can set the length of the password by changing `config.randomCharacters.length`. You can change the repetition behaviour of the password by changing the two following values:

 * `config.randomCharacters.allowRepeatingCharacters`: Whether or not to allow repeating characters in the generated password. The default is `false`.
 * `config.randomCharacters.allowRepeatingSets`: Whether or not to allow repeating character sets. The default is `true`.

You can set what character sets are used to generate the random-character passwords. The available character sets are available on the object `config.randomCharacters.characterSets`. The _enabled_ character sets are set on `config.randomCharacters.enabledCharacterSets`, which is an array of the names of enabled character sets.

For example, the following allows for generation of passwords that are 20 characters long with only letters and numbers:

```javascript
const config = getConfig();
config.randomCharacters.length = 20;
config.randomCharacters.enabledCharacterSets = ["UPPERCASE", "LOWERCASE", "DIGITS"];
generatePassword(config).then(password => {
    // do something with the password
});
```

Similarly, you could enable the use of all character sets by using:

```javascript
config.randomCharacters.enabledCharacterSets = Object.keys(config.randomCharacters.characterSets);
```

**Important note**: Limiting the character sets, as well as enforcing strict non-repeat rules, may cause the password generator to throw. You should gracefully handle thrown errors in any interface this component is used.

#### Random word configuration
After setting `config.mode` to "words", you can use the `config.randomWords` object to configure the generation. Set the number of generated words by using `config.randomWords.length` to the desired count. The words are joined by the string `config.randomWords.separator`.

### Setup for platforms other than NodeJS
An asynchronous random number generator is used so that other platforms may easily be supported. Random number generation doesn't work well in the browser (in a broad sense), and doesn't really work at all in React-Native (crypto PRNG).

You should override the random number generation on platforms where better solutions are available (when compared to this library's built in generator). The override function should take an array of objects that resemble `{ min, max }`, where `min` and `max` are bounds for random number generation. For each item in the array, a random number should be generated between the provided range (bounds inclusive). For example:

```javascript
const { setRNG } = require("@idsync/generator");

// Overriden method must return a Promise with an array of the
// generated numbers
setRNG(items => {
    return Promise.all(items.map(item => {
        return someRandomNumberGenerator(item.min, item.max);
    }));
});
```

## Installation
Install the library by running:

```shell
npm install @idsync/generator --save
```