Requirements

• Node.js v20 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @openally/config
# or
$ yarn add @openally/config

Features

• Hot-reloading of configuration
• Reactive with observable key(s)
• Safe with JSON Schema validation
• Support 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).

Usage example

Create a simple json file for your project

{
  "loglevel": 5,
  "logsize": 4048,
  "login": "administrator"
}

Now, create a new Configuration instance and read it

import { AsynchronousConfig } from "@openally/config";

const config = new AsynchronousConfig("./path/to/config.json");
await config.read();
console.log(cfg.get("loglevel")); // stdout: 5

// Observe (with an Observable Like) the update made to login property
config.observableOf("login").subscribe(console.log);
config.set("login", "admin");

// Payload getter will return a deepClone with all configuration properties
console.log(config.payload);

config.close();

[!IMPORTANT] config.json should exists otherwise it will throw an Error. Look at createOnNoEntry option for more information !

Events

Configuration class is extended by a Node.js EventEmitter. 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

AsynchronousConfig

const config = new AsynchronousConfig(path: string, options?: ConfigOptions);

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 | | jsonSchema | object | null | The default JSON Schema for the configuration | | fs | FileSystem | fs | The file system to use for reading and writing the configuration |

[!NOTE] When no schema is provided, it will search for a file prefixed by .schema with the same config name.

AsynchronousConfig.read(defaultPayload?: object): Promise<AsynchronousConfig>

Will read the local configuration on disk. A default payload value can be provided in case the file doesn't exist !

[!CAUTION] When the file doesn't exist, the configuration is written at the next loop iteration

AsynchronousConfig.setupHotReload(): void

Setup the hot reload of the configuration file. It will watch the file for modification and reload the configuration when it happens.

This method is automatically triggered if the Configuration has been created with the option autoReload set to true.

AsynchronousConfig.get<T>(fieldPath: string, depth?: number): T

Get a value from a key (fieldPath). For example, let take a json payload with a root foo field.

const config = new AsynchronousConfig("./path/to/file.json");
await config.read();
const fooValue = config.get("foo");

If the retrieved value is a JavaScript object, you can limit the depth with depth option.

AsynchronousConfig.set(fieldPath: string, fieldValue: string)

Set or udpate a given field in the configuration. The file will be written on the disk if the option writeOnSet is set to true.

const config = new AsynchronousConfig("./config.json", {
  createOnNoEntry: true
});

await config.read();
config.set("foo", "hello world!");

AsynchronousConfig.observableOf(fieldPath: string): Observable<T>

Return an Observable that will emit the value of the given fieldPath when it changes.

const config = new AsynchronousConfig("./config.json");
await config.read({ foo: "bar" });

// Observe initial and next value(s) of foo
config.observableOf("foo").subscribe(console.log);
config.set("foo", "baz");

AsynchronousConfig.close(): Promise<void>

Close the configuration. It will stop the file watcher, remove subscribers and emit the close event.

AsynchronousConfig.payload: object

Return a deep clone of the configuration payload.

AsynchronousConfig.writeOnDisk(): Promise<void>

Write the configuration payload on the local disk.

License

MIT