config-sets/README.md

Easily configure the app in real-time.

<p id="config-sets-logo">
  <img src="logo/logo-256x256.png" alt="config-sets logo" width="200" style="border-radius: 1em;">
</p>

# Config Sets 

Easy app configure in real time.

## 📚 Table of contents
- [✨ Features](#-features)
- [📋 Description](#-description)
- [📦 Installation](#-installation)
- [🚀 Usage](#-usage)
  - [Basic Usage](#basic-usage)
  - [Command-Line Arguments](#command-line-arguments)
  - [Watching for Changes](#watching-for-changes)
- [🧪 Testing](#-testing)
- [🛠️ API Reference](#️-api-reference)
  - [Main Function](#main-function)
  - [Static Properties](#static-properties)
  - [Helper Functions](#helper-functions)
- [📜 License - MIT](#-license)

 <p align="right"><a href="#config-sets-logo">Back to top ↑</a></p>

---

## ✨ Features

- Read and write configuration settings to a `config-sets.json` file.
- Handle command-line arguments for configuration settings.
- Watch for changes to the configuration file and update settings in real time.
- Easy to use and integrate into Node.js applications.
- Part of the ['conextra'](https://www.npmjs.com/package/conextra) framework.
- Uses the ['data-context'](https://www.npmjs.com/package/data-context) module for data management.
- Supports metadata and comments in JSON files.
- Extended JSON parsing for incremental updates.
- MIT License.

<p align="right"><a href="#config-sets-logo">Back to top ↑</a></p>

---

## 📋 Description

This Node.js module manages configuration settings by reading from and writing to a `config-sets.json` file.
It handles command-line arguments and watches for changes to the configuration file.
It allows you to create applications that can be configured in real time.
This module is part of the ['conextra'](https://www.npmjs.com/package/conextra) framework, 
which is a simple and easy-to-use single-page application (SPA) framework.
You have to try it! A different solution than MVC (model–view–controller).

> Please note, this version is not backward compatible with version 2.x<br>
> Please note that JSON string is not 100% compatible.<br>
> It has been extended to allow for incremental updates of JSON files.<br>
> Added the ability to include metadata and comments.<br>
> Parsing of JSON files is enabled.

<p align="right"><a href="#config-sets-logo">Back to top ↑</a></p>

---

## 📦 Installation

To install the module, use npm:
```bash
npm install config-sets
```

<p align="right"><a href="#config-sets-logo">Back to top ↑</a></p>

---

## 🚀 Usage

### Basic Usage

To use the module, require it in your script and call the `configSets` function:

```javascript

const configSets = require('config-sets');

const config = configSets({ 
    '-metadata-key1': ' key1 comment ',
    key1: 'value1', 
    '-metadata-key2': ' key2 comment ',
    key2: 'value2' 
});

const moduleConfig = configSets('moduleName', { key1: 'value1', key2: 'value2' });

console.log(config);

config.on('key1', function (ev) { console.log(ev); return true; });

```

file: `config-sets.json` 
```javascript
/* Configuration settings for application. */
{
  /* Set to true to use production settings, */
  /* false for development settings. Default is true. */
  "isProduction": true,
  /* Settings used in production mode. */
  /* These settings are saved to "config-sets.json" file. */
  "production": {
    /* key1 comment */
    "key1": "value1",
    /* key2 comment */
    "key2": "value2",
    "moduleName": {
        "key1": "value1",
        "key2": "value2"
    }
  },
  /* Settings used in development mode. */
  /* These settings are not saved to file and are created from production settings. */
  /* You can override these settings using command line arguments. */
  /* Set only the settings you want to change. */
  "development": {}
}
```


### Command-Line Arguments

You can pass configuration settings via command-line arguments:

`node index.js --key1=value1 --key2=value2`

`node index.js --help`


### Watching for Changes

The module watches the `config-sets.json` file for changes and updates the configuration settings accordingly.<br>
This uses the ['data-context'](https://www.npmjs.com/package/data-context) module. Read more about how to use it.

```javascript
config.on('key1', function (ev) { console.log(ev); return true; });
```

<p align="right"><a href="#config-sets-logo">Back to top ↑</a></p>

---

## 🧪 Testing

You can test `config-sets` on your system using this command:
```bash
node ./node_modules/config-sets/index.test
```

or in the `config-sets` project directory:
```bash
npm test
```

<p align="right"><a href="#config-sets-logo">Back to top ↑</a></p>

---

## 🛠️ API Reference

### Main Function

#### `configSets(configModuleName, defaultConfigSettings)`

- `configModuleName` (optional): The name of the module to set or update configuration settings for.
- `defaultConfigSettings`: The default configuration settings.

Returns the current configuration settings.

### Static Properties

- **`configSets.isProduction`**: Indicates if the environment is production.
- **`configSets.production`**: Contains production-specific configuration settings.
- **`configSets.development`**: Contains development-specific configuration settings.
- **`configSets.enableFileReadWrite`** (default: true): Determines if changes to the configuration should be saved automatically.

### Helper Functions

#### `assign(target, source, overwriteChanges)`

- `target`: The target object to merge properties into.
- `source`: The source object containing properties to merge.
- `overwriteChanges` (optional): A boolean indicating whether to overwrite existing properties in the target object.

Merges source objects into a target object.

#### `arg_options()`

Parses command-line arguments into an object.

Returns an object containing the parsed command-line arguments.

#### `print_help()`

Prints the help message.

<p align="right"><a href="#config-sets-logo">Back to top ↑</a></p>

---

## 📜 License

This project is licensed under the MIT License.

Copyright &copy; Manuel Lõhmus

<p align="right"><a href="#config-sets-logo">Back to top ↑</a></p>

---