0
# Store Management
1

2
Store management system for adding, removing, and configuring different configuration sources with priority-based hierarchical access. Stores are queried in the order they were added, with the first store having the highest priority.
3

4
## Capabilities
5

6
### Add Store
7

8
Add a configuration store to the hierarchy with automatic initialization and loading.
9

10
```javascript { .api }
11
/**
12
 * Add a configuration store to the hierarchy
13
 * @param {string} name - Store name for identification
14
 * @param {Object} options - Store configuration options
15
 * @param {string} [options.type] - Store type (memory, file, argv, env, literal)
16
 * @param {string} [usage] - Usage information for argv store
17
 * @returns {Provider} Provider instance for chaining
18
 */
19
add(name, options, usage);
20
```
21

22
**Usage Examples:**
23

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

27
// Add memory store
28
nconf.add('memory', { type: 'memory' });
29

30
// Add file store
31
nconf.add('config', {
32
  type: 'file',
33
  file: './config.json'
34
});
35

36
// Add argv store with usage
37
nconf.add('args', { type: 'argv' }, 'Usage: node app.js [options]');
38

39
// Add env store with options
40
nconf.add('environment', {
41
  type: 'env',
42
  separator: '__',
43
  parseValues: true
44
});
45

46
// Add literal store with default values
47
nconf.add('defaults', {
48
  type: 'literal',
49
  store: {
50
    app: { port: 3000, env: 'development' },
51
    database: { host: 'localhost' }
52
  }
53
});
54

55
// Type defaults to name if not specified
56
nconf.add('memory');  // Creates memory store
57
nconf.add('argv');    // Creates argv store
58
```
59

60
### Remove Store
61

62
Remove a store from the configuration hierarchy.
63

64
```javascript { .api }
65
/**
66
 * Remove a store from the hierarchy
67
 * @param {string} name - Store name to remove
68
 * @returns {Provider} Provider instance for chaining
69
 */
70
remove(name);
71
```
72

73
**Usage Examples:**
74

75
```javascript
76
// Remove specific store
77
nconf.remove('temp-config');
78

79
// Remove and re-add with different options
80
nconf
81
  .remove('environment')
82
  .add('environment', {
83
    type: 'env',
84
    whitelist: ['NODE_ENV', 'PORT', 'DATABASE_URL']
85
  });
86

87
// Chain removal operations
88
nconf
89
  .remove('old-config')
90
  .remove('deprecated-store')
91
  .add('new-config', { type: 'file', file: './new-config.json' });
92
```
93

94
### Use Store
95

96
Add or replace a store with idempotent behavior - only creates/updates if the store doesn't exist or has different options.
97

98
```javascript { .api }
99
/**
100
 * Add or replace a store (idempotent operation)
101
 * @param {string} name - Store name
102
 * @param {Object} options - Store configuration options
103
 * @returns {Provider} Provider instance for chaining
104
 */
105
use(name, options);
106
```
107

108
**Usage Examples:**
109

110
```javascript
111
// Idempotent store creation
112
nconf.use('config', {
113
  type: 'file',
114
  file: './config.json'
115
});
116

117
// Won't recreate if same options
118
nconf.use('config', {
119
  type: 'file',
120
  file: './config.json'  // Same options, no change
121
});
122

123
// Will recreate if different options
124
nconf.use('config', {
125
  type: 'file',
126
  file: './production.json'  // Different file, recreates store
127
});
128

129
// Safe initialization pattern
130
nconf
131
  .use('overrides', { type: 'literal', store: overrideConfig })
132
  .use('argv', { type: 'argv' })
133
  .use('env', { type: 'env' })
134
  .use('config', { type: 'file', file: configPath });
135
```
136

137
### Create Store
138

139
Create a store instance without adding it to the hierarchy (used internally).
140

141
```javascript { .api }
142
/**
143
 * Create a store instance of the specified type
144
 * @param {string} type - Store type (memory, file, argv, env, literal)
145
 * @param {Object} options - Store configuration options
146
 * @param {string} [usage] - Usage information for argv store
147
 * @returns {Store} Store instance
148
 */
149
create(type, options, usage);
150
```
151

152
**Usage Examples:**
153

154
```javascript
155
// Create store for custom usage
156
const memoryStore = nconf.create('memory', { 
157
  logicalSeparator: '.',  // Use dots instead of colons
158
  parseValues: true 
159
});
160

161
// Create file store with encryption
162
const secureStore = nconf.create('file', {
163
  file: './secure.json',
164
  secure: {
165
    secret: process.env.CONFIG_SECRET,
166
    alg: 'aes-256-ctr'
167
  }
168
});
169

170
// Create argv store with custom options
171
const argvStore = nconf.create('argv', {
172
  separator: '_',
173
  parseValues: true
174
}, 'Custom usage message');
175
```
176

177
### Initialize Provider
178

179
Initialize the provider with multiple stores and sources at once.
180

181
```javascript { .api }
182
/**
183
 * Initialize provider with stores and sources
184
 * @param {Object} options - Initialization options
185
 * @param {Object} [options.store] - Single store configuration
186
 * @param {Object} [options.stores] - Multiple store configurations  
187
 * @param {Object} [options.source] - Single read-only source
188
 * @param {Object} [options.sources] - Multiple read-only sources
189
 * @param {string} [options.type] - Single store type
190
 * @returns {Provider} Provider instance
191
 */
192
init(options);
193
```
194

195
**Usage Examples:**
196

197
```javascript
198
// Initialize with single store
199
const provider = nconf.init({
200
  type: 'file',
201
  file: './config.json'
202
});
203

204
// Initialize with multiple stores
205
nconf.init({
206
  stores: {
207
    overrides: { type: 'literal', store: { debug: true } },
208
    config: { type: 'file', file: './config.json' },
209
    env: { type: 'env', separator: '__' },
210
    defaults: { type: 'literal', store: defaultConfig }
211
  }
212
});
213

214
// Initialize with read-only sources
215
nconf.init({
216
  sources: {
217
    system: { type: 'file', file: '/etc/myapp/config.json' },
218
    global: { type: 'env', prefix: 'MYAPP_' }
219
  },
220
  stores: {
221
    local: { type: 'file', file: './local.json' }
222
  }
223
});
224
```
225

226
## Store Types and Options
227

228
### Memory Store Options
229

230
```javascript { .api }
231
/**
232
 * Memory store options
233
 */
234
interface MemoryOptions {
235
  loadFrom?: string[];           // Files to load initially
236
  logicalSeparator?: string;     // Key separator (default: ':')
237
  parseValues?: boolean;         // Parse string values (default: false)
238
}
239
```
240

241
### File Store Options
242

243
```javascript { .api }
244
/**
245
 * File store options
246
 */
247
interface FileOptions {
248
  file: string;                  // File path (required)
249
  dir?: string;                  // Directory path (default: process.cwd())
250
  format?: Object;               // Format parser (default: json)
251
  spacing?: number;              // JSON indentation (default: 2)
252
  search?: boolean;              // Search up directory tree
253
  secure?: {                     // Encryption options
254
    secret: string;              // Encryption secret
255
    alg?: string;                // Algorithm (default: 'aes-256-ctr')
256
    secretPath?: string;         // Path to secret file
257
  };
258
}
259
```
260

261
### Argv Store Options
262

263
```javascript { .api }
264
/**
265
 * Argv store options
266
 */
267
interface ArgvOptions {
268
  parseValues?: boolean;         // Parse string values (default: false)
269
  transform?: Function;          // Transform key-value pairs
270
  separator?: string|RegExp;     // Key separator for nested keys
271
}
272
```
273

274
### Env Store Options
275

276
```javascript { .api }
277
/**
278
 * Environment store options
279
 */
280
interface EnvOptions {
281
  separator?: string|RegExp;     // Key separator for nested keys
282
  whitelist?: string[];          // Allowed environment variables
283
  lowerCase?: boolean;           // Convert keys to lowercase
284
  parseValues?: boolean;         // Parse string values
285
  transform?: Function;          // Transform key-value pairs
286
  match?: RegExp;                // Regex to match variable names
287
  prefix?: string;               // Environment variable prefix
288
  readOnly?: boolean;            // Read-only store (default: true)
289
}
290
```
291

292
### Literal Store Options
293

294
```javascript { .api }
295
/**
296
 * Literal store options
297
 */
298
interface LiteralOptions {
299
  store?: Object;                // Static configuration object
300
}
301
```