Programmatic API

/**
 * Analyze npm dependencies and return current state
 * @param options - Configuration options for the analysis
 * @returns Promise resolving to CurrentState object with analysis results
 */
function npmCheck(options?: NpmCheckOptions): Promise<CurrentState>;

const npmCheck = require('npm-check');

// Basic usage - analyze current directory
npmCheck()
  .then(currentState => {
    const packages = currentState.get('packages');
    console.log(`Found ${packages.length} packages`);
  });

// With specific options
npmCheck({
  cwd: './my-project',
  skipUnused: true,
  ignoreDev: false
})
  .then(currentState => {
    const outdated = currentState.get('packages')
      .filter(pkg => pkg.bump && !pkg.notInstalled);
    console.log(`${outdated.length} packages need updates`);
  });

interface NpmCheckOptions {
  /** Check global modules instead of local project */
  global?: boolean;
  /** Enable interactive update mode (not typically used programmatically) */
  update?: boolean;
  /** Update all packages without prompting (not typically used programmatically) */
  updateAll?: boolean;
  /** Skip checking for unused packages */
  skipUnused?: boolean;
  /** Only check devDependencies, ignore dependencies */
  devOnly?: boolean;
  /** Ignore devDependencies, only check dependencies */
  ignoreDev?: boolean;
  /** Working directory to analyze (defaults to process.cwd()) */
  cwd?: string;
  /** Save exact versions instead of semver ranges when updating */
  saveExact?: boolean;
  /** Pre-existing state object to extend (advanced usage) */
  currentState?: Object;
  /** Ignore dependencies matching glob patterns */
  ignore?: string | string[];
  /** List of depcheck specials to include */
  specials?: string;
  /** Enable debug output */
  debug?: boolean;
  /** Enable emoji in output */
  emoji?: boolean;
  /** Enable spinner animations */
  spinner?: boolean;
  /** Package manager to use for updates */
  installer?: 'npm' | 'pnpm' | 'yarn' | 'ied' | 'auto';
}

interface CurrentState {
  /**
   * Get a value from the current state
   * @param key - State key to retrieve
   * @returns Value associated with the key
   */
  get(key: StateKey): any;
  
  /**
   * Set a value in the current state
   * @param key - State key to set
   * @param value - Value to set
   */
  set(key: StateKey, value: any): void;
  
  /**
   * Get all state values as an object
   * @returns Complete state object
   */
  all(): Object;
  
  /**
   * Inspect current state if debug mode is enabled
   */
  inspectIfDebugMode(): void;
}

type StateKey = 
  | 'packages'               // Array of PackageInfo objects
  | 'debug'                 // Debug mode status
  | 'global'                // Global mode status  
  | 'cwd'                   // Current working directory
  | 'cwdPackageJson'        // Parsed package.json object
  | 'emoji'                 // Emoji mode status
  | 'globalPackages'        // Global packages data
  | 'unusedDependencies'    // Unused dependencies array
  | 'missingFromPackageJson' // Missing packages object
  | 'update'                // Update mode status
  | 'updateAll'             // Update all mode status
  | 'skipUnused'            // Skip unused check status
  | 'devOnly'               // Dev only mode status
  | 'ignoreDev'             // Ignore dev dependencies status
  | 'saveExact'             // Save exact versions status
  | 'specials'              // Depcheck specials
  | 'spinner'               // Spinner enabled status
  | 'installer'             // Package installer to use
  | 'ignore';               // Ignore patterns for dependencies

interface PackageInfo {
  /** Name of the npm module */
  moduleName: string;
  /** URL to the package's homepage */
  homepage: string;
  /** Error encountered when communicating with registry (if any) */
  regError: any;
  /** Error encountered when reading package.json (if any) */
  pkgError: any;
  /** Latest version available in registry */
  latest: string;
  /** Currently installed version */
  installed: string;
  /** Whether the package is currently installed */
  isInstalled: boolean;
  /** Whether the package is not installed */
  notInstalled: boolean;
  /** Requested version from package.json */
  packageWanted: string;
  /** Version or range specified in parent package.json */
  packageJson: string;
  /** Whether this is listed as a devDependency */
  devDependency: boolean;
  /** Array of package.json scripts that reference this module */
  usedInScripts: string[] | undefined;
  /** Whether installed version doesn't match package.json range */
  mismatch: boolean;
  /** Valid semver version of installed package */
  semverValid: string;
  /** Whether running 'npm install' would upgrade this package */
  easyUpgrade: boolean;
  /** Type of semver bump needed to reach latest version */
  bump: 'patch' | 'minor' | 'major' | 'prerelease' | 'build' | 'nonSemver' | null;
  /** Whether this package appears to be unused in the codebase */
  unused: boolean;
}

const npmCheck = require('npm-check');

npmCheck({ cwd: './my-project' })
  .then(currentState => {
    const packages = currentState.get('packages');
    
    // Find outdated packages
    const outdated = packages.filter(pkg => 
      pkg.bump && !pkg.notInstalled
    );
    
    // Find unused packages
    const unused = packages.filter(pkg => 
      pkg.unused && pkg.isInstalled
    );
    
    // Find packages with version mismatches  
    const mismatched = packages.filter(pkg => 
      pkg.mismatch
    );
    
    console.log(`Outdated: ${outdated.length}`);
    console.log(`Unused: ${unused.length}`);
    console.log(`Mismatched: ${mismatched.length}`);
  });

const npmCheck = require('npm-check');

npmCheck({ cwd: './invalid-path' })
  .then(currentState => {
    // Analysis completed - check individual packages for errors
    const packages = currentState.get('packages');
    packages.forEach(pkg => {
      if (pkg.regError) {
        console.log(`Registry error for ${pkg.moduleName}:`, pkg.regError);
      }
      if (pkg.pkgError) {
        console.log(`Package error for ${pkg.moduleName}:`, pkg.pkgError);
      }
    });
  })
  .catch(error => {
    // Critical error prevented analysis
    console.error('npm-check failed:', error.message);
  });