propertiesmanager

A powerful and flexible Node.js configuration management module with support for multiple environments, command-line overrides, environment variables, multi-file composition, hot reload, and advanced security features.

Features

- 🌍 Multiple environments - production, dev, test with automatic fallback
- 🔧 Command-line overrides - Override any property via CLI arguments
- 🌐 Environment variable support - Override via PM_* environment variables
- 📁 Multi-file configuration - Compose configs from default.json, local.json, secrets.json
- 🔄 Hot reload - Automatically reload configuration when files change
- 🔒 Security hardened - Protection against prototype pollution and property injection
- 📝 JSON5 support - Use comments, trailing commas in your config files
- 📊 Configurable logging - Control verbosity with LOG_LEVEL environment variable
- 📘 TypeScript support - Full TypeScript definitions included

This module helps to easily manage all the configuration properties needed in a system, giving a simple and consistent configuration interface to your application. The properties must have a profile category: production, dev, or test. Configuration files are stored in the config folder in your application home directory (config/default.json).


* Installation
* Property file creation
* Property file population
* Using propertiesmanager
* Loading a running profile
* Override parameters from command line
* Override parameters from environment variables
* Multi-file configuration
* Configuration hot reload
* Debugging and Logging
* TypeScript Support
* Security
* Examples

Installation

To install propertiesmanager, type:

``shell
$ npm install propertiesmanager
`

Property file creation


Configuration files must be created in a folder named config in the home directory of your application.
The filename must be named default.json. Type:
`shell
$ mkdir config
$ vi config/default.json
`

Property file population

The file containing your properties is a JSON file having a mandatory dictionary called "production".
It contains all the configuration parameters of your application running in production or default mode.
Other dictionaries can be used, "dev" for development properties and "test" for testing properties.

An example of empty property file:
`javascript
{
"production":{}
}
`

An example of populated property file:
`javascript
{
"production":{
"properties_One":"One",
"properties_Two":"Two",
"Objectproperties":{
"Obj_One":1,
"Obj_Two":2
}
}
}
`


An example of property file with dev and test dictionaries defined:
`javascript
{
"production":{
"properties_One":"One",
"properties_Two":"Two",
"Objectproperties":{
"Obj_One":1,
"Obj_Two":2
}
},
"test":{
"properties_One":"TestOne",
"Objectproperties":{
"Obj_One":1,
"Obj_Two":2
}
},
"dev":{
"properties_One":"Test Development",
"DevLogs":{
"path":"/logs/log.xml",
"format":"xml"
}
}
}
`

Usage

$3

Just require it like a simple package:

`javascript
var propertiesmanager = require('propertiesmanager').conf;
`

$3


propertiesmanager returns a dictionary containing all the properties from a configuration file.
These properties can be overridden by command line parameters.
`javascript
// Print all the loaded properties
console.log(propertiesmanager);

`

Loading a running profile

The application using this package runs under one profile among three (production, dev, test), set by NODE_ENV environment variable.
If NODE_ENV is not defined the default profile is production

Running your app in default mode. production properties are loaded:
`shell
$ cd "YOUR_APPLICATION_HOME_DIRECTORY"
$ npm start
`

Running your app in production mode. production properties are loaded:
`shell
$ cd "YOUR_APPLICATION_HOME_DIRECTORY"
$ NODE_ENV=production npm start
`

Running your app in dev mode. dev properties are loaded:
`shell
$ cd "YOUR_APPLICATION_HOME_DIRECTORY"
$ NODE_ENV=dev npm start
`

Running your app in test mode. test properties are loaded:
`shell
$ cd "YOUR_APPLICATION_HOME_DIRECTORY"
$ NODE_ENV=test npm start
`

Override loaded parameters from command line


The package propertiesmanager uses minimist for parsing command-line arguments, so your properties stored in default.json can be
overridden by command line parameters.

$3

`shell
$ cd "YOUR_APPLICATION_HOME_DIRECTORY"
$ NODE_ENV=dev npm start -- --properties_One="Override_TestOne"
`

The first -- after npm start means that the following params must be passed to node bin/www,
so if you run your application directly calling node bin/www the first -- must be not used:
`shell
$ cd "YOUR_APPLICATION_HOME_DIRECTORY"
$ NODE_ENV=dev node bin/www --properties_One="Override_TestOne"
`

$3

Since this package uses minimist, the following syntax rules apply:

- --key=value → Sets key to "value" (string)
- --key=123 → Sets key to 123 (number - minimist auto-converts)
- --key=true → Sets key to "true" (string)
- --key=false → Sets key to "false" (string)
- --key → Sets key to true (boolean - flag syntax)
- --key=null → Sets key to null (actual null value, not string)
- --key=undefined → Sets key to undefined (actual undefined value, not string)
- --key= → Rejected (empty string not allowed by design)

$3


To override parameters that are complex objects, use dotted (".") notation:
`javascript
// Example: We want to override Obj_One property
// This is the structure in default.json:
{
"production":{
"properties_One":"One",
"properties_Two":"Two",
"Objectproperties":{
"Obj_One":1,
"Obj_Two":2
}
}
}
`

`shell
// Command to override the Obj_One value
$ cd "YOUR_APPLICATION_HOME_DIRECTORY"
$ NODE_ENV=dev node bin/www --Objectproperties.Obj_One="Override_Obj_One"
`

For further information about minimist syntax, see the minimist documentation.

Override parameters from environment variables

Properties can also be overridden using environment variables with the PM_ prefix. This is especially useful in containerized environments or CI/CD pipelines.

Precedence order (highest to lowest):
1. Environment variables (PM_*)
2. Command-line parameters
3. Configuration files

$3

`shell


Override port via environment variable

$ PM_PORT=8080 node app.js

Override nested properties (use uppercase for nested keys)

$ PM_DATABASE.HOST=localhost PM_DATABASE.PORT=5432 node app.js

Combine with command line (command line has lower priority)

$ PM_PORT=8080 node app.js --database.name=mydb

Set to null or undefined

$ PM_DATABASE.HOST=null node app.js
$ PM_CACHE.ENABLED=undefined node app.js
`

Environment variables are converted the same way as command-line parameters:
- Numbers are kept as strings (use command line for automatic number conversion)
- "null" string becomes null
- "undefined" string becomes undefined
- Empty strings are rejected

Multi-file configuration

The package supports loading and merging multiple configuration files for better organization and security:

- config/default.json - Base configuration (required)
- config/local.json - Local overrides (optional, not committed to git)
- config/secrets.json - Sensitive data like API keys (optional, not committed to git)

Merge precedence (highest to lowest):
1. config/secrets.json
2. config/local.json
3. config/default.json

$3

`javascript
// config/default.json (base configuration)
{"production": {"appName": "MyApp", "port": 3000, "db": {"host": "localhost"}}}

// config/local.json (developer overrides)
{"production": {"port": 8080, "db": {"host": "192.168.1.100"}}}

// config/secrets.json (credentials)
{"production": {"db": {"password": "secret123"}}}

// Result: port=8080, db.host=192.168.1.100, db.password=secret123
`

Best practices:
- Add config/local.json and config/secrets.json to .gitignore
- Use default.json for safe default values
- Use local.json for developer-specific settings
- Use secrets.json for sensitive credentials

Configuration hot reload

The package can watch config/default.json for changes and automatically reload the configuration when the file is modified. Hot reload is disabled by default and must be explicitly enabled.

$3

Enable via environment variable:

`shell
$ ENABLE_CONFIG_WATCH=true node app.js
`

Note: This must be set as an environment variable (not in config file) to avoid circular dependency issues.

$3

`javascript
var propertiesmanager = require('propertiesmanager');

// Listen for configuration reload events
propertiesmanager.configEvents.on('reload', function(newConfig) {
console.log('Configuration reloaded!');
console.log('New config:', newConfig);

// Update your application state with new config
// For example, restart a service, reconnect to database, etc.
});

// Access current configuration
console.log(propertiesmanager.conf);
`

$3

- The file watcher monitors config/default.json for changes
- When a change is detected, the configuration is automatically reloaded
- The reload event is emitted with the new configuration
- Changes are reflected immediately in propertiesmanager.conf (by reference)

Note: Hot reload only watches config/default.json. Changes to local.json or secrets.json require an application restart.

Production use: Hot reload is disabled by default, making it safe for production. Only enable it in development environments where you need automatic configuration updates.

Debugging and Logging

The package uses the LOG_LEVEL environment variable to control logging verbosity. This affects all internal messages from propertiesmanager.

$3

Available levels (from most to least verbose): debug, info, warn, error

Default: info

$3

Set via LOG_LEVEL environment variable:

`shell


Debug mode: show all internal messages (key processing, config loading, watcher status)

$ LOG_LEVEL=debug node app.js

Default: info level (shows config loaded, hot-reload events)

$ LOG_LEVEL=info node app.js

Production: only errors and warnings

$ LOG_LEVEL=warn node app.js

Only critical errors

$ LOG_LEVEL=error node app.js
`

Note: LOG_LEVEL must be set as an environment variable and cannot be configured in the config file.

$3

When LOG_LEVEL=debug is set, you'll see detailed internal messages:

`
propertiesmanager Processing key: appName
propertiesmanager Processing key: server
propertiesmanager Config file watcher disabled (set ENABLE_CONFIG_WATCH=true to enable)
propertiesmanager Configuration loaded successfully for environment: production
`

These messages show the internal workings of the configuration loading process and are useful for troubleshooting.

TypeScript Support

The package includes TypeScript type definitions. TypeScript projects can import and use it with full type support:

`typescript
import { conf } from 'propertiesmanager';

// conf is typed as Record
const port: number = conf.server.port;
const appName: string = conf.appName;
`

For better type safety, you can define your own interface:

`typescript
interface MyConfig {
appName: string;
server: {
host: string;
port: number;
};
database: {
host: string;
name: string;
};
}

import { conf } from 'propertiesmanager';
const config = conf as MyConfig;

// Now fully typed!
const port: number = config.server.port;
`

Security

propertiesmanager implements multiple security protections to prevent common configuration-based attacks:

$3

The package actively blocks attempts to pollute JavaScript prototypes through command-line arguments:

- __proto__ - Automatically filtered and rejected
- constructor - Blocked at all nesting levels
- prototype - Cannot be used as property name

These protections prevent attackers from injecting malicious properties into JavaScript's object prototype chain, which could lead to:
- Remote Code Execution (RCE)
- Denial of Service (DoS)
- Authentication bypass
- Property injection attacks

`shell


These malicious attempts are automatically blocked:


$ node app.js --__proto__.polluted=true # ❌ BLOCKED
$ node app.js --constructor.prototype.admin=true # ❌ BLOCKED
$ node app.js --prototype.isAdmin=true # ❌ BLOCKED
`

$3

The package only allows overriding existing properties defined in default.json:

- ✅ Cannot add new properties via command line
- ✅ Cannot add new nested properties
- ✅ Only pre-defined configuration keys can be modified

`javascript
// If default.json contains:
{
"production": {
"port": 3000,
"debug": false
}
}

// This works (overrides existing property):
$ node app.js --port=8080 // ✅ OK

// This is silently ignored (property doesn't exist):
$ node app.js --malicious=payload // ❌ IGNORED
`

$3


Empty values via --key= syntax are rejected by design to prevent accidental configuration corruption:

`shell
$ node app.js --database.host= # ❌ REJECTED (empty string)
$ node app.js --database.host=null # ✅ OK (explicit null)
`

$3

The package safely handles path-like strings and prevents directory traversal attempts:

`shell
$ node app.js --configPath=../../etc/passwd # ✅ Treated as safe string value
`

$3

SQL injection, XSS, and other injection patterns are safely handled as regular string values without special interpretation.

$3

All security features are validated through 119 automated tests, including specific vulnerability tests in test/security-integrity.test.js and logging configuration tests in test/logging.test.js.

$3

The package provides clear error messages when configuration files are missing or invalid:

`
ERROR: config/default.json not found or invalid.
Please create config/default.json in your application root directory.
See https://github.com/aromanino/propertiesmanager for documentation.
`

This prevents silent failures and helps developers quickly identify configuration issues.

Examples

$3


From your home project directory type:
`shell
$ mkdir config
$ vi config/default.json
`

Write default.json property file:
`javascript
{
"production":{
"properties_One":"One",
"properties_Two":"Two",
"Objectproperties":{
"Obj_One":1,
"Obj_Two":2
}
},
"test":{
"properties_One":"TestOne",
"Objectproperties":{
"Obj_One":1,
"Obj_Two":2
}
},
"dev":{
"properties_One":"Test Development",
"DevLogs":{
"path":"/logs/log.xml",
"format":"xml"
}
}
}
`
Now you can print all your properties:
`javascript
var propertiesmanager = require('propertiesmanager').conf;

// Print the loaded properties to console
console.log("########### Read Properties ###########" );
console.log(propertiesmanager);

`

Running your app in default mode, production properties are loaded:
`shell
$ cd "YOUR_APPLICATION_HOME_DIRECTORY"
$ npm start
########### Read Properties ###########
"production":{
"properties_One":"One",
"properties_Two":"Two",
"Objectproperties":{
"Obj_One":1,
"Obj_Two":2
}
}
`

Running your app in production mode (NODE_ENV=production) is equivalent to run in default mode:
`shell
$ cd "YOUR_APPLICATION_HOME_DIRECTORY"
$ NODE_ENV=production npm start
########### Read Properties ###########
"production":{
"properties_One":"One",
"properties_Two":"Two",
"Objectproperties":{
"Obj_One":1,
"Obj_Two":2
}
}
`

Running your app in dev mode (NODE_ENV=dev), dev properties are loaded:
`shell
$ cd "YOUR_APPLICATION_HOME_DIRECTORY"
$ NODE_ENV=dev npm start
########### Read Properties ###########
"dev":{
"properties_One":"Test Development",
"DevLogs":{
"path":"/logs/log.xml",
"format":"xml"
}
}
`

Running your app in test mode (NODE_ENV=test), test properties are loaded:
`shell
$ cd "YOUR_APPLICATION_HOME_DIRECTORY"
$ NODE_ENV=test npm start
########### Read Properties ###########
"test":{
"properties_One":"TestOne",
"Objectproperties":{
"Obj_One":1,
"Obj_Two":2
}
}
`


Overriding some test mode (NODE_ENV=test) properties:
`shell
$ cd "YOUR_APPLICATION_HOME_DIRECTORY"
$ NODE_ENV=test npm start -- --properties_One="Override_TestOne"
########### Read Properties ###########
"test":{
"properties_One":"Override_TestOne",
"Objectproperties":{
"Obj_One":1,
"Obj_Two":2
}
}
``

License - "MIT License"
-----------------------

MIT License

Copyright (c) 2016 aromanino

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Author
------
CRS4 Microservice Core Team (cmc.smartenv@crs4.it)

Contributors
------
Alessandro Romanino (a.romanino@gmail.com)

Guido Porruvecchio (guido.porruvecchio@gmail.com)