Store Management

/**
 * Add a configuration store to the hierarchy
 * @param {string} name - Store name for identification
 * @param {Object} options - Store configuration options
 * @param {string} [options.type] - Store type (memory, file, argv, env, literal)
 * @param {string} [usage] - Usage information for argv store
 * @returns {Provider} Provider instance for chaining
 */
add(name, options, usage);

const nconf = require('nconf');

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

// Add file store
nconf.add('config', {
  type: 'file',
  file: './config.json'
});

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

// Add env store with options
nconf.add('environment', {
  type: 'env',
  separator: '__',
  parseValues: true
});

// Add literal store with default values
nconf.add('defaults', {
  type: 'literal',
  store: {
    app: { port: 3000, env: 'development' },
    database: { host: 'localhost' }
  }
});

// Type defaults to name if not specified
nconf.add('memory');  // Creates memory store
nconf.add('argv');    // Creates argv store

/**
 * Remove a store from the hierarchy
 * @param {string} name - Store name to remove
 * @returns {Provider} Provider instance for chaining
 */
remove(name);

// Remove specific store
nconf.remove('temp-config');

// Remove and re-add with different options
nconf
  .remove('environment')
  .add('environment', {
    type: 'env',
    whitelist: ['NODE_ENV', 'PORT', 'DATABASE_URL']
  });

// Chain removal operations
nconf
  .remove('old-config')
  .remove('deprecated-store')
  .add('new-config', { type: 'file', file: './new-config.json' });

/**
 * Add or replace a store (idempotent operation)
 * @param {string} name - Store name
 * @param {Object} options - Store configuration options
 * @returns {Provider} Provider instance for chaining
 */
use(name, options);

// Idempotent store creation
nconf.use('config', {
  type: 'file',
  file: './config.json'
});

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

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

// Safe initialization pattern
nconf
  .use('overrides', { type: 'literal', store: overrideConfig })
  .use('argv', { type: 'argv' })
  .use('env', { type: 'env' })
  .use('config', { type: 'file', file: configPath });

/**
 * Create a store instance of the specified type
 * @param {string} type - Store type (memory, file, argv, env, literal)
 * @param {Object} options - Store configuration options
 * @param {string} [usage] - Usage information for argv store
 * @returns {Store} Store instance
 */
create(type, options, usage);

// Create store for custom usage
const memoryStore = nconf.create('memory', { 
  logicalSeparator: '.',  // Use dots instead of colons
  parseValues: true 
});

// Create file store with encryption
const secureStore = nconf.create('file', {
  file: './secure.json',
  secure: {
    secret: process.env.CONFIG_SECRET,
    alg: 'aes-256-ctr'
  }
});

// Create argv store with custom options
const argvStore = nconf.create('argv', {
  separator: '_',
  parseValues: true
}, 'Custom usage message');

/**
 * Initialize provider with stores and sources
 * @param {Object} options - Initialization options
 * @param {Object} [options.store] - Single store configuration
 * @param {Object} [options.stores] - Multiple store configurations  
 * @param {Object} [options.source] - Single read-only source
 * @param {Object} [options.sources] - Multiple read-only sources
 * @param {string} [options.type] - Single store type
 * @returns {Provider} Provider instance
 */
init(options);

// Initialize with single store
const provider = nconf.init({
  type: 'file',
  file: './config.json'
});

// Initialize with multiple stores
nconf.init({
  stores: {
    overrides: { type: 'literal', store: { debug: true } },
    config: { type: 'file', file: './config.json' },
    env: { type: 'env', separator: '__' },
    defaults: { type: 'literal', store: defaultConfig }
  }
});

// Initialize with read-only sources
nconf.init({
  sources: {
    system: { type: 'file', file: '/etc/myapp/config.json' },
    global: { type: 'env', prefix: 'MYAPP_' }
  },
  stores: {
    local: { type: 'file', file: './local.json' }
  }
});

/**
 * Memory store options
 */
interface MemoryOptions {
  loadFrom?: string[];           // Files to load initially
  logicalSeparator?: string;     // Key separator (default: ':')
  parseValues?: boolean;         // Parse string values (default: false)
}

/**
 * File store options
 */
interface FileOptions {
  file: string;                  // File path (required)
  dir?: string;                  // Directory path (default: process.cwd())
  format?: Object;               // Format parser (default: json)
  spacing?: number;              // JSON indentation (default: 2)
  search?: boolean;              // Search up directory tree
  secure?: {                     // Encryption options
    secret: string;              // Encryption secret
    alg?: string;                // Algorithm (default: 'aes-256-ctr')
    secretPath?: string;         // Path to secret file
  };
}

/**
 * Argv store options
 */
interface ArgvOptions {
  parseValues?: boolean;         // Parse string values (default: false)
  transform?: Function;          // Transform key-value pairs
  separator?: string|RegExp;     // Key separator for nested keys
}

/**
 * Environment store options
 */
interface EnvOptions {
  separator?: string|RegExp;     // Key separator for nested keys
  whitelist?: string[];          // Allowed environment variables
  lowerCase?: boolean;           // Convert keys to lowercase
  parseValues?: boolean;         // Parse string values
  transform?: Function;          // Transform key-value pairs
  match?: RegExp;                // Regex to match variable names
  prefix?: string;               // Environment variable prefix
  readOnly?: boolean;            // Read-only store (default: true)
}

/**
 * Literal store options
 */
interface LiteralOptions {
  store?: Object;                // Static configuration object
}