npm package: @synanetics/settings-resolver
Description: Settings mixin for MoleculerJS
Author: David Tolman
Latest version: 2.0.0

# `@synanetics/settings-resolver`

A utility function to resolve settings from a structured default settings JSON file. It can optionally accept overrides using a path to a JSON file, JSON string or object with a matching structure. It can also optionally apply a schema for validation of the resulting object.

## Usage

```javascript
const settingsResolver = require('@synanetics/settings-resolver');
// or
import settingsResolver from '@synanetics/settings-resolver';
```

### Setting Validation

It should be noted that both default and override settings are validated against a common schema:

- key is required and must be a string
- value is required and must be a boolean, number or string
- description is optional but must be a string if present
  - this property is for humans only and is ignored when building the output object

### Loading Defaults Only

At a minimum it requires the full path to a valid default JSON file.

default.json

```json
[
    {
        "key": "example",
        "value": "example value",
        "description": "Optional"
    }
]
```

code

```javascript
const settings = settingsResolver(path.resolve('./default.json'));

/* settings would be
 * { example: 'example value' }
 */
```

### Applying Overrides

Overrides can be in the form of a file, a string or an object.

Any override **could** extend the default structure but it would be more descriptive to maintain it as a default.

#### By File

Override file paths must be prefixed with `file://`

default.json

```json
[
    {
        "key": "example",
        "value": "example value"
    }
]
```

override.json

```json
[
    {
        "key": "example",
        "value": "overriding value"
    }
]
```

code

```javascript
const settings = settingsResolver(
    path.resolve('./default.json'),
    `file://${path.resolve('./override.json')}`,
);

/* settings would be
 * { example: 'overriding value' }
 */
```

#### By String

A string must be valid JSON

default.json

```json
[
    {
        "key": "example",
        "value": "example value"
    }
]
```

override

```javascript
process.env.OVERRIDE = "[{\"key\":\"example\",\"value\":\"overriding value\"}]"
```

code

```javascript
const settings = settingsResolver(
    path.resolve('./default.json'),
    process.env.OVERRIDE,
);

/* settings would be
 * { example: 'overriding value' }
 */
```

#### By Object

Simply provide a valid object

default.json

```json
[
    {
        "key": "example",
        "value": "example value"
    }
]
```

override

```javascript
const override = [
    {
        key: 'example',
        value: 'overriding value',
    }
];
```

code

```javascript
const settings = settingsResolver(
    path.resolve('./default.json'),
    override,
);

/* settings would be
 * { example: 'overriding value' }
 */
```

### Validating the Resulting Object

You can optionally supply a schema object by which the resulting object should be validated against. It uses the [fastest-validator](https://www.npmjs.com/package/fastest-validator) to do this (also used by Moleculer JS for param validation).

default.json

```json
[
    {
        "key": "example",
        "value": 1
    }
]
```

override

```javascript
const override = [
    {
        key: 'example',
        value: 'not a number',
    }
];
```

validation schema

```javascript
const validationSchema = {
    example: { type: 'number', optional: false, empty: false }
};
```

code

```javascript
const settings = settingsResolver(
    path.resolve('./default.json'),
    override,
    validationSchema,
);

// above would throw SettingsValidationError as override sets an expected number value to a string
```

### Errors Handling

`settingsResolver` does nothing to prevent errors being raised by underlying operations (think a filesystem read error or invalid JSON syntax being provided).

When it fails to validate values (input settings, or validating output against a provided schema) it will raise a `SettingsValidationError` which is also exported by this package to assist in error handling.

`SettingsValidationError` has a `data` property which contains the array of validation errors encountered.