Configuration Management

/**
 * Load configuration with environment resolution
 * @param opts - Options object with path, env, config properties
 * @returns Loaded configuration queries
 */
browserslist.loadConfig(opts: ConfigLoadOptions): string[] | object | undefined;

interface ConfigLoadOptions {
  /** Starting directory path for config search */
  path?: string;
  /** Environment name for config selection */
  env?: string;
  /** Path to specific config file */
  config?: string;
}

const browserslist = require("browserslist");

// Load config from current directory
const config = browserslist.loadConfig({ path: '.' });
console.log(config);
// => ['> 1%', 'last 2 versions', 'not dead']

// Load config for specific environment
const devConfig = browserslist.loadConfig({
  path: '/path/to/project',
  env: 'development'
});

// Load specific config file
const customConfig = browserslist.loadConfig({
  config: '/path/to/browserslist.config'
});

/**
 * Find browserslist configuration in directory tree
 * @param from - Starting directory path
 * @returns Found configuration object or undefined
 */
browserslist.findConfig(from: string): object | undefined;

// Find config starting from specific directory
const config = browserslist.findConfig('/path/to/project');
if (config) {
  console.log('Configuration found:', config);
} else {
  console.log('No configuration found');
}

// Find config from current working directory
const cwd = process.cwd();
const config = browserslist.findConfig(cwd);

/**
 * Parse browserslist configuration string
 * @param string - Configuration string to parse
 * @returns Parsed configuration with environment sections
 */
browserslist.parseConfig(string: string): object;

/**
 * Read and parse configuration file
 * @param file - Path to configuration file
 * @returns Parsed configuration object
 */
browserslist.readConfig(file: string): object;

// Parse configuration string
const configString = `
# Default environment
> 1%
last 2 versions
not dead

[development]
last 1 chrome version
last 1 firefox version

[production]
> 0.5%
last 3 versions
not dead
`;

const parsed = browserslist.parseConfig(configString);
console.log(parsed);
// => {
//   defaults: ['> 1%', 'last 2 versions', 'not dead'],
//   development: ['last 1 chrome version', 'last 1 firefox version'],
//   production: ['> 0.5%', 'last 3 versions', 'not dead']
// }

// Read and parse config file
const fileConfig = browserslist.readConfig('./.browserslistrc');

/**
 * Clear internal caches for files and configuration
 */
browserslist.clearCaches(): void;

// Clear all caches (useful in build tools and testing)
browserslist.clearCaches();

// After clearing cache, next config load will re-read files
const config = browserslist.loadConfig({ path: '.' });

{
  "name": "my-project",
  "browserslist": [
    "> 1%",
    "last 2 versions",
    "not dead"
  ]
}

{
  "browserslist": {
    "production": [
      "> 0.5%",
      "last 3 versions",
      "not dead"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version"
    ]
  }
}

# Browsers that we support

> 1%
last 2 versions
not dead

[development]
last 1 chrome version
last 1 firefox version

[production]
> 0.5%
last 3 versions
not dead

# Production environment (default)
> 1%
last 2 versions
not dead

[development]
last 1 chrome version
last 1 firefox version

// Explicit environment
const config = browserslist.loadConfig({ env: 'development' });

// Via environment variable
process.env.BROWSERSLIST_ENV = 'testing';
const config = browserslist.loadConfig({});

// Via NODE_ENV
process.env.NODE_ENV = 'production';
const config = browserslist.loadConfig({});

// Environment variables that affect configuration loading:
process.env.BROWSERSLIST          // Override queries directly
process.env.BROWSERSLIST_CONFIG   // Override config file path
process.env.BROWSERSLIST_ENV      // Override environment name
process.env.BROWSERSLIST_STATS    // Override stats file path
process.env.BROWSERSLIST_DISABLE_CACHE // Disable caching

// Override queries via environment
process.env.BROWSERSLIST = 'last 1 version';
const browsers = browserslist(); // Uses 'last 1 version'

// Override config file
process.env.BROWSERSLIST_CONFIG = '/custom/browserslist.config';
const config = browserslist.loadConfig({});

// Disable caching
process.env.BROWSERSLIST_DISABLE_CACHE = '1';
browserslist.loadConfig({}); // Always re-reads files

// Invalid configuration format (must be string or array of strings)
const invalidConfig = { invalid: true };
browserslist.parseConfig(invalidConfig); // throws BrowserslistError

// Conflicting configuration files
// Project with both .browserslistrc AND package.json browserslist field
browserslist.findConfig('./conflicting-project'); // throws BrowserslistError

// Missing configuration file
browserslist.readConfig('./nonexistent.config'); // throws BrowserslistError

// Invalid package.json (browserlist vs browserslist)
// package.json with "browserlist" field instead of "browserslist"
// throws BrowserslistError with helpful message

extends @company/browserslist-config

/**
 * Load queries from shareable config package
 * @param context - Context with dangerousExtend option
 * @param name - Config package name
 * @returns Array of queries from the package
 */
// Internal function, used by extends query
loadQueries(context: object, name: string): string[];

/**
 * Get custom usage statistics
 * @param opts - Options with stats and path properties
 * @returns Statistics object or undefined
 */
getStat(opts: StatsOptions): object | undefined;

interface StatsOptions {
  /** Custom statistics (string path or object) */
  stats?: string | object;
  /** Path for finding browserslist-stats.json */
  path?: string;
}

// Load stats from file path
const stats = browserslist.getStat({ 
  stats: '/path/to/browserslist-stats.json' 
});

// Load stats from project directory
const stats = browserslist.getStat({ 
  path: '/path/to/project' 
});
// Looks for /path/to/project/browserslist-stats.json

// Use with coverage calculation
const coverage = browserslist.coverage(browsers, stats);