@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

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

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

code

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

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

override.json

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

code

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

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

override

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

code

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

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

override

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

code

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 to do this (also used by Moleculer JS for param validation).

default.json

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

override

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

validation schema

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

code

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.