# configurator-js

> Configuration management.

Latest version **0.0.5** (published 2015-07-19) · Apache 2.0 license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install configurator-js
pnpm add configurator-js
yarn add configurator-js
bun add configurator-js
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.0.5 |
| Published | 2015-07-19 |
| First published | 2015-07-19 |
| Weekly downloads | 0 |
| License | Apache 2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Douglas Vasconcelos |
| Maintainers | douglascvas |
| Keywords | configuration |

## Links

- npm: https://www.npmjs.com/package/configurator-js
- Repository: https://github.com/douglascvas/configurator
- Homepage: https://github.com/douglascvas/configurator#readme
- Issues: https://github.com/douglascvas/configurator/issues
- npm.io page: https://npm.io/package/configurator-js

## Dependencies (2)

- [yamljs](https://npm.io/package/yamljs.md) 0.2.2
- [json-path-utils](https://npm.io/package/json-path-utils.md) 0.0.1

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 0.0.5 (latest) — 2015-07-19

## README

# configurator-js
Configuration management.

As a new instance of Configurator is created, it loads a configuration file and resolve its expressions, if any.
A configuration file can be a JSON file or a YAML file.

## Modules and versions

A configuration file can hold configurations for multiple modules, so each one can access its own configs.
Also each module can evolve and increase its versions. Sometimes though there is the need to keep the configuration for old modules. 

Imagine a situation in that a machine has a module that offers APIs. The API module is then modified to use some other configurations, although you don't want to shut down the old version, but keep both running in parallel. 
In this case they will need to access different configurations, that is made possible using versions.

A version must be specified with curl braces, like *{0.0.1}*.

Example: 
```JSON
{
  "module1": {
    "{1.0.0}": {
      "hostname": "localhost",
      "port": 8000  
    },
    "{1.1.0}": {
      "hostname": "localhost",
      "port": 8001  
    }
  },
  "module2": {
  	...
  }
}
```

A configuration can also be **generic**, so to be used by multiple modules, as amqp configuration, for example.

Example: 
```JSON
{
  "module2": {
    "{0.0.1}":
  	  ...
  },
  "amqp": {
  	"host": "localhost",
    "port": "5672"
  }
}
```

## Expressions


Expressions are special strings that points to other configurations. Example:

```
"config1": "@{config2.value2}"
"config2": {
  "value1": "foo",
  "value2": "bar"
}
```

The expression under `config1` will resolve to the config under `config2.value2`, resulting in the value `bar`.

There are three types of expression:

#### Environment expressions
Environment expressions are those with format `[[...]]` and resolve to environment variables. It can be also specified inside of other types of expression.

#### Strict expressions
Strict expressions are the ones with format `@{...}` and will resolve to *generic* configurations (those whose not belongs to modules configuration).

#### Module expressions
Strict expressions are the ones with format `${...}` and will resolve to configurations related to a module. A module expression must contain `${<module>.<version>.<config_path>}`, where:

* `module`: which module to get the config from. The word `$this` can be used to use the current module (the one that instantiated the configuration library).
* `version`: which module version to get the config from. The word `$this` can be used to use the current version. An sterisk (`*`) can also be used to use the last version. A version in an expression must be surrounded by `[]`, `()` or `{}`. Example: `[1.0.0]`.
* `config_path`: path to the desired configuration value.

Example:
```JSON
{
  "apis": {
  	"{1.2.1}": {
  	  "amqp": "@{rabbitMQ}",
      "mainDir": "/opt/apis"
    }
  },
  "rabbitMQ": {
  	"host": "localhost",
    "port": "[[RABBITMQ_PORT]]",
    "logPath": "${$this.$this.mainDir}"
  }
}
```

In this example, the `amqp` configuration from the module `apis` points to the generic configuration `rabbitMQ`. 

The `logPath` config from the `rabbitMQ` configuration points to the `mainDir` config of the current module. If the *apis* module has loaded the configuration in this case, it will resolve to `/opt/apis`.

The `port` attribute from the `rabbitMQ` module will resolve to the value specified in the environment variable `RABBITMQ_PORT`.

## How to use

In the package.json of your module declare under the dependencies:

npm install --save configurator

The Configurator class can be imported as:
```javascript
var Configurator = require('configurator');
```

The constructor receives three parameters (parameters with `[]` are **optional**):
 * `configPath` {String} Path to the configuration file that will be used.
 * `[module]` {String} Name of the module to which the configuration belongs.
 * `[version]` {String} Version of the module to which the configuration belongs.

If the `module` and `version` parameters are given, then when getting configurations, the configurator will get the config from the given `module` and `version`. Both parameters are required if some expression with `$this` is used in the config file.

Example:

```javascript
var configurator = new Configurator("/config", "apis", "0.1.0");
```

A in a more real scenario, the module name and version would be gotten from the package.json file. Example:
```javascript
var Configurator = require('configurator');
var moduleInfo = require('./package.json');
var configurator = new Configurator(null, moduleInfo.name,
moduleInfo.version);
```

#### Getting a config value

A value can be retrieved from the configuration using the `get` method. It expects three parameters:

* `key` {String} Path to the configuration value to be retrieved.
* `[module]` {String} Name of the module to which the configuration belongs. If specified, overrides the module given in the constructor.
* `[version]` {String} Version of the module to which the configuration belongs. If specified, overrides the version given in the constructor.

The `module` and `version` parameters are optional, and can be used when trying to get a configuration from another module. If `null` is passed (**null**, not *undefined*) in the `module` parameter, a generic configuration is selected.

Example:

Suppose the **apis** module is trying to get a configuration from the **database** module. 
Having the configuration file as:
```JSON
{
  "apis": {
  	"{1.2.1}": {
  	  "amqp": "@{rabbitMQ}",
      "mainDir": "/opt/apis"
    }
  },
  "database": {
  	"{0.1.1}": {
    	"url": "mysql://localhost:3306"
    }
  },
  "rabbitMQ": {
  	"host": "localhost",
    "port": "5672",
    "logPath": "${$this.$this.mainDir}"
  }
}
```

The **apis** module could do:
```javascript
var amqpConfig = configurator.get("amqp");
var databaseUrl = configurator.get("url", "database", "0.1.1")
```

In this example, `amqpConfig` would receive the value under the `amqp` config of the module **apis**. The `databaseUrl` will receive the value under the `url` config of the module `database` configuration, whose version is `0.1.1`. The version could be just ommited so to use the last version from the `database` module:

```javascript
var databaseUrl = configurator.get("url", "database");
```

---
_Source: https://npm.io/package/configurator-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._