node-configuration-manager v1.1.0

node-configuration-manager

Helps your nodejs project to manage configuration files with just a few lines of code.

Installation

npm install node-configuration-manager

Usage - Config.Manager

Note:

• Configuration manager will not create a new file until a config key was set.
• Configuration data defaults to {} if the configuration file does not exist.

Import

// ES Module import
import Config from "node-configuration-manager" ;
//or
import { Manager as ConfigManager } from "node-configuration-manager" ;
//or
var Config = await import ( "node-configuration-manager" ) ;

// CommonJS import
var Config = require ( "node-configuration-manager" ) ;
//or 
var { Manager : ConfigManager } = require ( "node-configuration-manager" ) ;
//or
var ConfigManager = require ( "node-configuration-manager" ) . Manager ;

Instantiating configuration manager

@param Directory: Fs.PathLike | undefined

• The directory where the configuration files will be stored.
  • Defaults to `${process.cwd()}/Config`.

@param Context: Fs.PathLike | undefined

• The configuration file inside the specified direrctory.
  • Defaults to index.

@param Prefix: string | undefined

• The prefix to configuration keys for better categorization.
  • Defaults to `` (empty string).

@param Options: Config.ConfigOptions | undefined

• Configuration options. (Details below).

Example:

var ConfMan = new Config . Manager ( './Config' , 'thisconfig' , 'thisprefix' ) ;

Config Options Options: Config.ConfigOptions

ConfigOptions.CaseInsensitiveKey: boolean | undefined

• Enable case insensitive key resolving.

  • Example:

    ConfMan . Set ( 'haha' , true ) ;
    
    console . log ( ConfMan . Get ( 'haha' ) ) ; // -> true
    console . log ( ConfMan . Get ( 'haHA' ) ) ; // -> true
    console . log ( ConfMan . Get ( 'HAHA' ) ) ; // -> true

  • Defaults to true

ConfigOptions.Format: 'json' | 'yaml' | undefined

• Configuration file format.
  • Example (JSON):
    • File structure

      |-Config
          |-thisconfig.json

    • File contents

      {"configKey":"configValue"}

  • Example (YAML):
    • File structure

      |-Config
          |-thisconfig.yaml

    • File contents

      configKey: configValue

  • Defaults to json

Using Get(), Set(), Defaults(), SetMultiple(), DefaultsMultiple(), IsSet(), and Unset() methods in Config.Manager

@method Set

• Sets a key in the configuration.
  • @param Key: string
    • Specify a key where the value will be set.
  • @param Value: any
    • The value to set.
  • @returns any
    • Returns the same as the specified value.
• Example:

  ConfMan . Set ( 'ha' , true ) ;

@method Get

• Gets a value of the key in the configuration.
  • @param Key: string
    • Specify a key to get value from.
  • @returns any
    • Returns a value or undefined if it's not already set.
• Example:

  console . log ( ConfMan . Get ( 'ha' ) ) ; // -> true

@method Defaults

• Sets a key only if it's not already set. If the specified key is already set, the function will return the current value of the key. Otherwise, It will set the key with the specified value and return it.
  • @param Key: string
    • Specify a key to get/set value from.
  • @param Value: any
    • Specify a value to set.
  • @returns any
    • Returns either the key value or the specified value.

• Example:

  ConfMan . Set ( 'ha' , 123 ) ;
  console . log ( ConfMan . Get ( 'ha' ) ) ; // -> 123
  
  console . log ( ConfMan . Defaults ( 'ha' , 456 ) ) ; // -> 123
  ConfMan . Unset ( 'ha' ) ;
  console . log ( ConfMan . Defaults ( 'ha' , 456 ) ) ; // -> 456

@method SetMultiple

• Iterative process for Set() method.
  • @param Data: Config.ConfigData
    • Configuration data to apply to the configuration.
  • @returns Config.Data
    • Returns the same as the specified configuration data.

• Example:

  ConfMan . SetMultiple ( {
      ha1 : 123 ,
      ha2 : 456
  } ) ;
  
  console . log ( ConfMan . Get ( 'ha1' ) ) ; // -> 123
  console . log ( ConfMan . Get ( 'ha2' ) ) ; // -> 456

@method DefaultsMultple

• Iterative process for Defaults() method.
  • @param Data: Config.ConfigData
    • Configuration data to apply to the configuration.
  • @return Config.Data
    • Returns the values.

• Example:

  ConfMan . SetMultiple ( {
      ha1 : 123 ,
      ha2 : 456
  } ) ;
  
  console . log ( ConfMan . DefaultsMultiple ( 'ha1' , 456 ) ) ; // -> 123
  console . log ( ConfMan . DefaultsMultiple ( 'ha2' , 123 ) ) ; // -> 456
  
  ConfMan . Unset ( 'ha1' ) ;
  ConfMan . Unset ( 'ha2' ) ;
  
  console . log ( ConfMan . DefaultsMultiple ( 'ha1' , 456 ) ) ; // -> 456
  console . log ( ConfMan . DefaultsMultiple ( 'ha2' , 123 ) ) ; // -> 123

@method IsSet

• Checks whether the key is set or not.
  • @param Key: string
    • Specify a key to check.
  • @returns boolean
    • Returns whether the key is set or not.
• Example:

  console . log ( ConfMan . IsSet ( 'ha' ) ) ; // -> false
  ConfMan . Set ( 'ha' , 123 ) ;
  console . log ( ConfMan . IsSet ( 'ha' ) ) ; // -> true

@method Unset

• Unsets a key from the configuration.
  • @param Key: string
    • Specify a key to unset.
  • @returns void
• Example:

  ConfMan . Set ( 'ha' , 123 ) ;
  console . log ( ConfMan . Get ( 'ha' ) ) ; // -> 123
  ConfMan . Unset ( 'ha' ) ;
  console . log ( ConfMan . Get ( 'ha' ) ) ; // -> undefined

  Alternatively, you can use Set() method to unset a key.

  ConfMan . Set ( 'ha' , 456 ) ;
  console . log ( ConfMan . Get ( 'ha' ) ) ; // -> 456
  ConfMan . Set ( 'ha' , undefined ) ;
  console . log ( ConfMan . Get ( 'ha' ) ) ; // -> undefined

Using Config.Manager.Data property to modify values.

Example:

ConfMan . Set ( 'HAHAHA1' , 'value1' ) ;
ConfMan . Set ( 'HAHAHA2' , 'value2' ) ;

console . log ( ConfMan . Data ) ; // -> { "HAHAHA1": "value1", "HAHAHA2": "value2" }

ConfMan . Data = {} ;

console . log ( ConfMan . Data ) ; // -> {}
console . log ( ConfMan . Get ( 'HAHAHA1' ) ) ; // -> undefined
console . log ( ConfMan . Get ( 'HAHAHA2' ) ) ; // -> undefined

This code will work...

var ConfData = ConfMan . Data ;
ConfData . HAHAHA1 = 'value1' ;
ConfMan . Data = ConfData ;

console . log ( ConfMan . Data ) ; // -> { "HAHAHA1": "value1" } ;

This code will NOT work...

ConfMan . Data . HAHAHA1 = 'value1' ;

console . log ( ConfMan . Data ) ; // -> {} ;

If you prefer the style of the last code shown above, please use Config.Manager.Proxy property instead as shown below.

Using Config.Manager.Proxy property to modify configuration values.

Example:

//Setting and getting values
ConfMan . Proxy . HAHAHA = true ;
console . log ( ConfMan . Proxy . HAHAHA ) ; // -> true

//Checking and unsetting values
console . log ( ConfMan . IsSet ( "HAHAHA" ) ) ; // true
console . log ( typeof ( ConfMan . Proxy . HAHAHA ) ) ; // -> boolean

ConfMan . Proxy . HAHAHA = undefined ;
//or
delete ConfMan . Proxy . HAHAHA ;

console . log ( typeof ( ConfMan . Proxy . HAHAHA ) ) ; // -> undefined

Using Config.Manager.Summon() method to instantiate a new configuration manager.

@param Directory: Fs.PathLike | null | undefined

• The directory where the configuration files will be stored.
  • Defaults to the current path of the parent class or `${process.cwd()}/Config`.

@param Context: Fs.PathLike | null | undefined

• The configuration file inside the specified direrctory.
  • If set to null, it defaults to the current context of the parent class.
  • If set to undefined, it defaults to index.

@param Prefix: string | null | undefined

• The prefix to configuration keys for better categorization.
  • If set to null, it defaults to the current prefix of the parent class.
  • If set to undefined, it defaults to (empty string).

@param Options: Config.ConfigOptions | undefined

• Configuration options.
  • Defaults to the current options of the parent class.

Example:

var NewConfMan = ConfMan . Summon ( null , 'thisnewconfig' , null ) ;

Usage - Config.ManagerAsync

Note:

• Config.ManagerAsync uses asynchronous fs functions.
• Some methods and properties of Config.Manager are not available in Config.ManagerAsync such as Proxy, GetData(), and SetData().
• All public methods except Summon() return promises. Those methods use async/await operations.

Example:

import { ManagerAsync } from "node-configuration-manager" ;

( async () => {
    const AsyncConfig = new ManagerAsync ( './Config' , 'ConfigContext' , 'ConfigPrefix' ) ;

    await AsyncConfig . Set ( "HA" , 123 ) ;

    console . log ( await AsyncConfig . IsSet ( "HA" ) ) ; // -> true

    console . log ( await AsyncConfig . Get ( "HA" ) ) ; // -> 123

    await AsyncConfig . Unset ( "HA" ) ;

    console . log ( await AsyncConfig . IsSet ( "HA" ) ) ; // -> false
} ) () . catch ( console . error ) ;