Utility Functions

const parseField = require('@npmcli/config/lib/parse-field');

/**
 * Parse configuration field value with type coercion and validation
 * @param field - Field type definition or type constructor
 * @param key - Configuration key name for error reporting
 * @param options - Configuration context and definitions
 * @param listElement - Whether this value is an array element
 * @returns Parsed and coerced value
 */
function parseField(field: any, key: string, options: ParseOptions, listElement?: boolean): any;

interface ParseOptions {
  /** Type definitions for validation */
  types: Record<string, TypeDefinition>;
  /** Configuration type definitions */
  typeDefs: Record<string, TypeDefinition>;
  /** Default values */
  defaults: Record<string, any>;
  /** Current configuration data */
  data: Record<string, any>;
  /** Configuration key for context */
  key: string;
}

const parseField = require('@npmcli/config/lib/parse-field');

// Parse string value
const parsed = parseField(String, 'loglevel', {
  types: { String },
  typeDefs: { String: { type: String } },
  defaults: { loglevel: 'notice' },
  data: {},
  key: 'loglevel'
}, false);

// Parse number with validation
const port = parseField(Number, 'port', {
  types: { Number },
  typeDefs: { Number: { type: Number, description: 'numeric value' } },
  defaults: { port: 8080 },
  data: {},
  key: 'port'
}, false);

// Parse array of strings
const tags = parseField([String], 'tag', options, true);

const envReplace = require('@npmcli/config/lib/env-replace');

/**
 * Replace ${VAR} patterns in strings with environment variable values
 * @param string - String potentially containing ${VAR} patterns
 * @param env - Environment variables object (defaults to process.env)
 * @returns String with environment variables expanded
 */
function envReplace(string: string, env?: Record<string, string>): string;

const envReplace = require('@npmcli/config/lib/env-replace');

// Replace environment variables in configuration values
const registryUrl = envReplace('${NPM_REGISTRY}/api/v1', process.env);
// If NPM_REGISTRY="https://registry.company.com"
// Result: "https://registry.company.com/api/v1"

// Replace multiple variables
const cachePath = envReplace('${HOME}/.npm/${USER}-cache', {
  HOME: '/home/john',
  USER: 'john'
});
// Result: "/home/john/.npm/john-cache"

// Handle missing variables (left unchanged)
const withMissing = envReplace('${MISSING_VAR}/path', {});
// Result: "${MISSING_VAR}/path"

const nerfDart = require('@npmcli/config/lib/nerf-dart');

/**
 * Convert URL to nerf-dart identifier for configuration scoping
 * @param url - URL to convert
 * @returns Nerf-dart identifier string
 */
function nerfDart(url: string): string;

const nerfDart = require('@npmcli/config/lib/nerf-dart');

// Convert registry URLs to configuration keys
const npmKey = nerfDart('https://registry.npmjs.org/');
// Result: "//registry.npmjs.org/"

const privateKey = nerfDart('https://npm.company.com:8443/registry/');
// Result: "//npm.company.com:8443/registry/"

// Use for scoped configuration
const scopedKey = nerfDart('https://registry.company.com/@scope/');
// Result: "//registry.company.com/@scope/"

const setEnvs = require('@npmcli/config/lib/set-envs');

/**
 * Set npm_config_* environment variables for configuration values
 * that differ from defaults, making them available to child processes
 * @param config - Configuration object with flat configuration data
 */
function setEnvs(config: ConfigForEnvs): void;

interface ConfigForEnvs {
  /** Flattened configuration values */
  flat: Record<string, any>;
  /** Default configuration values */
  defaults: Record<string, any>;
  /** Environment variables object to modify */
  env: Record<string, string>;
}

const setEnvs = require('@npmcli/config/lib/set-envs');

// Set environment variables from config
setEnvs({
  flat: {
    registry: 'https://npm.company.com/',
    loglevel: 'verbose',
    'save-dev': true
  },
  defaults: {
    registry: 'https://registry.npmjs.org/',
    loglevel: 'notice',
    'save-dev': false
  },
  env: process.env
});

// Now process.env contains:
// npm_config_registry = "https://npm.company.com/"
// npm_config_loglevel = "verbose"
// npm_config_save_dev = "true"
// (default values are not set as environment variables)

const typeDescription = require('@npmcli/config/lib/type-description');

/**
 * Generate human-readable description array for configuration field type
 * @param type - Type definition or constructor
 * @returns Array of description strings for the type
 */
function typeDescription(type: any): string[];

const typeDescription = require('@npmcli/config/lib/type-description');

// Get description for basic types
const stringDesc = typeDescription(String);
// Result: ["string"]

const numberDesc = typeDescription(Number);
// Result: ["number"]

const booleanDesc = typeDescription(Boolean);
// Result: ["boolean"]

// Get description for array types
const stringArrayDesc = typeDescription([String]);
// Result: ["string", "(can be set multiple times)"]

// Get description for complex types
const urlDesc = typeDescription(require('nopt').typeDefs.url);
// Result: ["url"]

// Use for help text generation
const fieldType = [String, Number];
const desc = typeDescription(fieldType);
// Result: ["string", "number"]
console.log(`Field accepts: ${desc.join(' or ')}`);

const { Umask, parse, validate } = require('@npmcli/config/lib/umask');

/**
 * Umask type class for file permission masks
 */
class Umask {
  constructor(value: string | number);
  toString(): string;
  valueOf(): number;
}

/**
 * Parse umask string or number into Umask instance
 * @param value - Umask value as string or number
 * @returns Umask instance
 */
function parse(value: string | number): Umask;

/**
 * Validate umask value for nopt type system
 * @param data - Configuration data object
 * @param key - Configuration key
 * @param value - Value to validate
 * @returns Boolean indicating if value is valid
 */
function validate(data: any, key: string, value: any): boolean;

const { Umask, parse, validate } = require('@npmcli/config/lib/umask');

// Create umask from octal string
const umask1 = new Umask('0o755');
console.log(umask1.toString()); // "0o755"
console.log(umask1.valueOf());  // 493

// Create umask from number
const umask2 = new Umask(755);
console.log(umask2.toString()); // "0o755"

// Parse umask values
const parsed = parse('644');
console.log(parsed.toString()); // "0o644"

// Validate umask in configuration
const config = {};
const isValid = validate(config, 'umask', '0o644');
console.log(isValid); // true
console.log(config.umask); // Umask instance

const typeDefs = require('@npmcli/config/lib/type-defs');

// Available type definitions
interface TypeDefinitions {
  /** SemVer validation type */
  semver: {
    type: typeof import('semver');
    validate: (data: any, key: string, value: any) => boolean;
    description: string;
  };
  
  /** Umask file permission type */
  Umask: {
    type: typeof Umask;
    validate: (data: any, key: string, value: any) => boolean;
    description: string;
  };
  
  /** URL type with validation */
  url: {
    type: typeof URL;
    validate: (data: any, key: string, value: any) => boolean;
    description: string;
  };
  
  /** File system path type */
  path: {
    type: typeof String;
    validate: (data: any, key: string, value: any) => boolean;
    description: string;
  };
  
  /** Numeric value type */
  Number: {
    type: typeof Number;
    description: string;
  };
  
  /** Boolean value type */
  Boolean: {
    type: typeof Boolean;
    description: string;
  };
  
  /** Date value type */
  Date: {
    type: typeof Date;
    description: string;
  };
  
  /** String value type */
  String: {
    type: typeof String;
    description: string;
  };
  
  /** Array type */
  Array: {
    type: typeof Array;
    description: string;
  };
}

const typeDefs = require('@npmcli/config/lib/type-defs');

// Use type definitions in configuration
const configDefs = {
  version: {
    type: typeDefs.semver.type,
    validate: typeDefs.semver.validate,
    description: 'Package version (valid semver)'
  },
  
  umask: {
    type: typeDefs.Umask.type,
    validate: typeDefs.Umask.validate,
    description: 'File creation mask'
  },
  
  registry: {
    type: typeDefs.url.type,
    validate: typeDefs.url.validate,
    description: 'Package registry URL'
  }
};

// Access type descriptions
console.log(typeDefs.semver.description); // "full valid SemVer string"
console.log(typeDefs.Umask.description);  // "octal number in range 0o000..0o777 (0..511)"

/**
 * Configuration data container for a specific configuration layer
 * Accessible through Config.data Map as individual layer data
 */
class ConfigData {
  /**
   * Create configuration data instance
   * @param parent - Parent ConfigData instance (for inheritance)
   */
  constructor(parent?: ConfigData);
  
  /** Configuration data object (getter) */
  data: Record<string, any>;
  
  /** Validation status (getter) */
  valid: boolean;
  
  /** Configuration source identifier (getter/setter) */
  source: string;
  
  /** Load error if configuration loading failed (getter/setter) */
  loadError: Error | null;
  
  /** Raw configuration data before processing (getter/setter) */
  raw: any;
}

// Access ConfigData instances through Config.data
const config = new Config({ definitions, shorthands, flatten, npmPath });
await config.load();

// Get specific configuration layer data
const userConfigData = config.data.get('user');
console.log(userConfigData.source);    // "user"
console.log(userConfigData.valid);     // true/false
console.log(userConfigData.data);      // { registry: "...", ... }

// Check for load errors
const projectConfigData = config.data.get('project');
if (projectConfigData.loadError) {
  console.error('Failed to load project config:', projectConfigData.loadError);
}

// Access raw configuration data
console.log(projectConfigData.raw); // Original file contents before parsing

// Iterate through all configuration layers
for (const [layerName, configData] of config.data.entries()) {
  console.log(`Layer: ${layerName}`);
  console.log(`Source: ${configData.source}`);
  console.log(`Valid: ${configData.valid}`);
  console.log(`Data:`, configData.data);
}

// Configuration layers are available in priority order:
// - cli: Command line arguments
// - env: Environment variables  
// - project: Project .npmrc file
// - user: User .npmrc file
// - global: Global .npmrc file
// - builtin: Built-in npm configuration
// - default: Default values