0
# nconf
1

2
nconf is a hierarchical node.js configuration library that provides unified access to configuration data from multiple sources including files, environment variables, command-line arguments, and static values. It uses a priority-based hierarchy system where configuration sources can be arranged in order of precedence, enabling flexible configuration management for Node.js applications.
3

4
## Package Information
5

6
- **Package Name**: nconf
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install nconf`
10

11
## Core Imports
12

13
```javascript
14
const nconf = require('nconf');
15
```
16

17
For ES modules:
18

19
```javascript
20
import nconf from 'nconf';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const nconf = require('nconf');
27

28
// Setup configuration hierarchy (order matters - first has highest priority)
29
nconf
30
  .argv()        // 1. Command-line arguments
31
  .env()         // 2. Environment variables  
32
  .file({ file: './config.json' });  // 3. Configuration file
33

34
// Set configuration values
35
nconf.set('database:host', 'localhost');
36
nconf.set('database:port', 5432);
37

38
// Get configuration values
39
const dbHost = nconf.get('database:host');
40
const dbPort = nconf.get('database:port');
41
const dbConfig = nconf.get('database');  // Gets entire object
42

43
// Save configuration to file
44
nconf.save((err) => {
45
  if (err) console.error('Error saving config:', err);
46
});
47
```
48

49
## Architecture
50

51
nconf is built around several key components:
52

53
- **Provider**: Main configuration manager that orchestrates multiple stores
54
- **Store System**: Pluggable storage backends (Memory, File, Argv, Env, Literal)
55
- **Hierarchical Access**: Priority-ordered configuration sources with fallback behavior
56
- **Key Namespacing**: Colon-delimited nested key support (`'database:host'`)
57
- **Atomic Operations**: Consistent read/write operations across all stores
58
- **Format Support**: JSON and INI file formats with extensible parsing
59

60
## Capabilities
61

62
### Configuration Management
63

64
Core configuration operations for getting, setting, and managing hierarchical configuration data with support for nested keys and multiple data sources.
65

66
```javascript { .api }
67
/**
68
 * Retrieve configuration value for the specified key
69
 * @param {string} key - Configuration key (supports nested keys with ':' delimiter)
70
 * @param {function} [callback] - Optional callback for async operation
71
 * @returns {*} Configuration value or undefined if not found
72
 */
73
get(key, callback);
74

75
/**
76
 * Set configuration value for the specified key
77
 * @param {string} key - Configuration key (supports nested keys with ':' delimiter) 
78
 * @param {*} value - Value to set
79
 * @param {function} [callback] - Optional callback for async operation
80
 * @returns {Provider} Provider instance for chaining
81
 */
82
set(key, value, callback);
83

84
/**
85
 * Remove configuration key and its value
86
 * @param {string} key - Configuration key to remove
87
 * @param {function} [callback] - Optional callback for async operation
88
 * @returns {Provider} Provider instance for chaining
89
 */
90
clear(key, callback);
91

92
/**
93
 * Merge object into existing configuration at key
94
 * @param {string} [key] - Target key, or merge into root if not provided
95
 * @param {Object} value - Object to merge
96
 * @param {function} [callback] - Optional callback for async operation
97
 * @returns {Provider} Provider instance for chaining
98
 */
99
merge(key, value, callback);
100
```
101

102
[Configuration Management](./configuration.md)
103

104
### Store Management
105

106
Store management system for adding, removing, and configuring different configuration sources with priority-based hierarchical access.
107

108
```javascript { .api }
109
/**
110
 * Add a configuration store to the hierarchy
111
 * @param {string} name - Store name
112
 * @param {Object} options - Store configuration options
113
 * @param {string} [usage] - Usage information for argv store
114
 * @returns {Provider} Provider instance for chaining
115
 */
116
add(name, options, usage);
117

118
/**
119
 * Remove a store from the hierarchy
120
 * @param {string} name - Store name to remove
121
 * @returns {Provider} Provider instance for chaining
122
 */
123
remove(name);
124

125
/**
126
 * Add or replace a store (idempotent operation)
127
 * @param {string} name - Store name
128
 * @param {Object} options - Store configuration options
129
 * @returns {Provider} Provider instance for chaining
130
 */
131
use(name, options);
132
```
133

134
[Store Management](./stores.md)
135

136
### File Operations
137

138
File-based configuration with support for JSON and INI formats, encrypted storage, and automatic file discovery with search functionality.
139

140
```javascript { .api }
141
/**
142
 * Add file store to configuration hierarchy
143
 * @param {string|Object} key - Store name or file path, or options object
144
 * @param {string|Object} [options] - File path or options object
145
 * @returns {Provider} Provider instance for chaining
146
 */
147
file(key, options);
148

149
/**
150
 * Load configuration from all stores
151
 * @param {function} [callback] - Optional callback for async operation
152
 * @returns {Object|Promise} Configuration object
153
 */
154
load(callback);
155

156
/**
157
 * Save configuration to all stores
158
 * @param {*} [value] - Optional value to save
159
 * @param {function} [callback] - Optional callback for async operation
160
 * @returns {Object|Promise} Saved configuration data
161
 */
162
save(value, callback);
163
```
164

165
[File Operations](./files.md)
166

167
### Command Line and Environment
168

169
Integration with command-line arguments via yargs and environment variables with filtering, transformation, and parsing capabilities.
170

171
```javascript { .api }
172
/**
173
 * Add command-line arguments store to hierarchy
174
 * @param {Object} [options] - yargs options or yargs instance
175
 * @returns {Provider} Provider instance for chaining
176
 */
177
argv(options);
178

179
/**
180
 * Add environment variables store to hierarchy  
181
 * @param {Object|Array|string} [options] - Environment variable options, whitelist array, or separator
182
 * @returns {Provider} Provider instance for chaining
183
 */
184
env(options);
185
```
186

187
[Command Line and Environment](./argv-env.md)
188

189
### Utilities and Validation
190

191
Utility functions for key manipulation, file loading, object merging, and configuration validation with required key checking.
192

193
```javascript { .api }
194
/**
195
 * Validate that required configuration keys are present
196
 * @param {string[]} keys - Array of required key names
197
 * @throws {Error} If any required keys are missing
198
 * @returns {boolean} True if all keys are present
199
 */
200
required(keys);
201

202
/**
203
 * Get first truthy value from a list of keys
204
 * @param {string[]|...string} keys - Array of keys or variable arguments
205
 * @param {function} [callback] - Optional callback for async operation
206
 * @returns {*} First truthy value found
207
 */
208
any(keys, callback);
209

210
/**
211
 * Clear all configuration data
212
 * @param {function} [callback] - Optional callback for async operation
213
 * @returns {Provider} Provider instance for chaining
214
 */
215
reset(callback);
216
```
217

218
[Utilities and Validation](./utilities.md)
219

220
## Static Properties and Methods
221

222
```javascript { .api }
223
/**
224
 * Package version string
225
 */
226
nconf.version: string;
227

228
/**
229
 * Provider constructor for creating multiple instances
230
 */
231
nconf.Provider: Function;
232

233
/**
234
 * Store constructor classes
235
 */
236
nconf.Argv: Function;
237
nconf.Env: Function;
238
nconf.File: Function;
239
nconf.Literal: Function;
240
nconf.Memory: Function;
241

242
/**
243
 * Utility functions available on main nconf object
244
 */
245
nconf.key(...args): string;
246
nconf.path(key, separator): string[];
247
nconf.keyed(separator, ...args): string;
248
nconf.loadFiles(files, callback): void;
249
nconf.loadFilesSync(files): Object;
250
nconf.parseValues(value): any;
251
nconf.transform(map, fn): Object;
252
nconf.formats: Object;
253
```
254

255
## Types
256

257
```javascript { .api }
258
/**
259
 * Main configuration provider class
260
 */
261
class Provider {
262
  constructor(options);
263
  stores: Object;    // Active configuration stores
264
  sources: Array;    // Read-only configuration sources
265
}
266

267
/**
268
 * Provider constructor options
269
 */
270
interface ProviderOptions {
271
  type?: string;           // Single store type to initialize
272
  store?: StoreOptions;    // Single store configuration
273
  stores?: Object;         // Multiple store configurations
274
  source?: SourceOptions;  // Single read-only source
275
  sources?: Object;        // Multiple read-only sources
276
}
277

278
/**
279
 * Available store types
280
 */
281
const StoreTypes = {
282
  Memory: 'memory',    // In-memory configuration store
283
  File: 'file',       // File-based configuration store
284
  Argv: 'argv',       // Command-line arguments store
285
  Env: 'env',         // Environment variables store  
286
  Literal: 'literal'  // Static object store
287
};
288

289
/**
290
 * Configuration formats
291
 */
292
const Formats = {
293
  json: {
294
    parse: Function,     // JSON.parse
295
    stringify: Function  // JSON.stringify with formatting
296
  },
297
  ini: {
298
    parse: Function,     // INI format parser
299
    stringify: Function  // INI format stringifier
300
  }
301
};
302
```