# Config
[](https://github.com/SlimIO/Config/commit-activity)
[](https://github.com/SlimIO/Config/blob/master/LICENSE)
[](https://snyk.io/test/github/SlimIO/Config?targetFile=package.json)
[](https://travis-ci.com/SlimIO/Config)
SlimIO - Reactive JSON Configuration loader. This package is used in SlimIO core and addons to safely hot reload configuration upon [JSON Schema](https://json-schema.org/).
## Features
- Hot-reloading of configuration
- Reactive with observable key(s)
- Safe with [JSON Schema](https://json-schema.org/) validation
- Support [TOML](https://github.com/toml-lang/toml) as input (enable the parser when the file extension end with **.toml**)
- Read configuration with no extension that start with a dot (like `.nodesecurerc` for example).
## Requirements
[Node.js](https://nodejs.org/en/) version 12 and upper are required to run this project. **We do not provide support** for previous versions.
## Getting Started
This package is available in the Node Package Repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).
```bash
$ npm i @slimio/config
# or
$ yarn add @slimio/config
```
## Usage example
Create a simple json file for your project (As below)
```json
{
"loglevel": 5,
"logsize": 4048,
"login": "administrator"
}
```
Now, create a new Configuration instance and read it
```js
const Config = require("@slimio/config");
async function main() {
const cfg = new Config("./path/to/config.json");
await cfg.read();
console.log(cfg.get("loglevel")); // stdout: 5
// Observe (with an Observable Like) the update made to login property
cfg.observableOf("login").subscribe(console.log);
cfg.set("login", "admin");
// Payload getter will return a deepClone with all configuration properties
console.log(cfg.payload);
await cfg.close();
}
main().catch(console.error);
```
> **Note:** config.json should exist (if not, it will throw an Error). Look at `createOnNoEntry` option for more information !
## Events
Configuration class is extended by a [Node.js EventEmitter](https://nodejs.org/api/events.html). The class can trigger several events:
| event name | description |
| --- | --- |
| configWritten | The configuration payload has been written on the local disk |
| watcherInitialized | The file watcher has been initialized (it will hot reload the configuration on modification) |
| reload | The configuration has been hot reloaded successfully |
| close | Event triggered when the configuration is asked to be closed |
## API
This section describe how works the methods of **Config** class. For a complete definition, take a look at `index.d.ts` !
constructor< T > (configFilePath: string, options?: Config.Options)
Create a new Config Object:
```js
const cfg = new Config("./path/to/file.json", {
createOnNoEntry: true,
autoReload: true
});
```
Available options are:
| name | type | default value | description |
| --- | --- | --- | --- |
| createOnNoEntry | boolean | false | Create the file with default payload value if he doesn't exist on the local disk |
| writeOnSet | boolean | false | Write the file on the disk after each time .set() is called |
| autoReload | boolean | false | Setup hot reload of the configuration file |
| reloadDelay | number | 500ms | The delay to wait before hot reloading the configuration, it's a security to avoid event spamming |
| defaultSchema | plainObject | null | The default JSON Schema for the configuration |
> **Note**: When no schema is provided, it will search for a file prefixed by `.schema` with the same config name.
read (defaultPayload?: T): Promise< this >
Will trigger and read the local configuration (on disk). A default `payload` value can be provided in case the file doesn't exist !
```js
const { strictEqual } = require("assert");
const cfg = new Config("./path/to/file.json");
strictEqual(cfg.configHasBeenRead, false); // true
await cfg.read();
strictEqual(cfg.configHasBeenRead, true); // true
```
Retriggering the method will made an hot-reload of all properties. For a cold reload you will have to close the configuration before.
> **Warning** When the file doesn't exist, the configuration is written at the next loop iteration (with lazyWriteOnDisk).
setupAutoReload (): void
Setup hot reload (with a file watcher). This method is automatically triggered if the Configuration has been created with the option `autoReload` set to true.
We use the package [node-watch](https://www.npmjs.com/package/node-watch) to achieve the hot reload.
get< H > (fieldPath: string, depth?: number): H
Get a value from a key (fieldPath). For example, let take a json payload with a root `foo` field.
```js
const cfg = new Config("./path/to/file.json");
await cfg.read();
const fooValue = cfg.get("foo");
```
> Under the hood the method work with `lodash.get` function.
If the retrieved value is a JavaScript object, you can limit the depth by setting `depth` option.
set< H > (fieldPath: string, fieldValue: H): void
Set a given field in the configuration.
```js
const cfg = new Config("./config.json", {
createOnNoEntry: true
});
await cfg.read({ foo: "bar" });
cfg.set("foo", "hello world!");
await cfg.writeOnDisk();
```
> Under the hood the method work with `lodash.set` function.
observableOf (fieldPath: string, depth?: number): ObservableLike
Observe a given configuration key with an Observable Like object!
```js
const { writeFile } = require("fs").promises;
const cfg = new Config("./config.json", {
autoReload: true,
createOnNoEntry: true
});
await cfg.read({ foo: "bar" });
// Observe initial and next value(s) of foo
cfg.observableOf("foo").subscribe(console.log);
// Re-write local config file
const newPayload = { foo: "world" };
await writeFile("./config.json", JSON.stringify(newPayload, null, 4));
```
writeOnDisk (): Promise< void >
Write the configuration on the disk.
lazyWriteOnDisk (): void
Write the configuration on the disk (only at the next event-loop iteration). Use the event `configWritten` to known when the configuration will be written.
```js
const cfg = new Config("./config.json", {
createOnNoEntry: true
});
await cfg.read();
cfg.once("configWritten", () => {
console.log("Configuration written!");
});
cfg.lazyWriteOnDisk();
```
close (): Promise< void >
Close (and write on disk) the configuration (it will close the watcher and complete/clean all active observers subscribers).
STRINGIFY_SPACE
The `STRINGIFY_SPACE` property allow you to redine the espace used internaly for `JSON.stringify` method. The default value is **4**.
DEFAULTSchema
The `DEFAULTSchema` property allow you to redefine the default schema that should be applied if no schema is provided when constructor is triggered!
The default value is the following Object:
```js
{
title: "CONFIG",
additionalProperties: true
}
```
DEFAULT_EXTENSION
The `DEFAULT_EXTENSION` property allow you to redefine the default extension when there is no extension detected in the constructor filePath. The extension can be either `.json` or `.toml`.