tessl/npm-npm-check-updates

Find newer versions of dependencies than what your package.json allows

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Programmatic API

Name: tessl/npm-npm-check-updates
Author: tessl

Core programmatic interface for integrating npm-check-updates into Node.js applications. Provides the main run() function for all upgrade operations.

Capabilities

Main Function

The primary entry point for all npm-check-updates functionality.

/**
 * Main entry point for npm-check-updates functionality
 * @param runOptions - Configuration options for the upgrade process
 * @param options - Additional execution options
 * @returns Promise resolving to upgrade results or void for global upgrades
 */
function run(
  runOptions?: RunOptions,
  options?: { cli?: boolean }
): Promise<PackageFile | Index<VersionSpec> | void>;

Return Types:

PackageFile - Default returns the complete package.json structure with upgraded dependency versions
Index<VersionSpec> - When jsonUpgraded option is true, returns only the upgraded dependencies as key-value pairs
void - When global option is true (global package upgrades), returns void since no package.json is modified

Usage Examples:

import ncu from "npm-check-updates";

// Basic upgrade - returns upgraded package.json structure
const upgrades = await ncu({ upgrade: true });
// Result: { name: "my-app", dependencies: { "react": "^18.2.0", "lodash": "^4.17.21" }, ... }

// Check only without upgrading - returns upgrade preview showing available updates
const preview = await ncu({ upgrade: false });
// Result: { "react": "^18.2.0", "lodash": "^4.17.21" } (only packages with available updates)

// Get only upgraded dependencies as key-value pairs
const upgraded = await ncu({ 
  upgrade: true,
  jsonUpgraded: true 
});
// Result: { "react": "^18.2.0", "lodash": "^4.17.21" } (only the dependencies that were actually upgraded)

// Global package upgrade - returns void
await ncu({ 
  global: true,
  upgrade: true 
});
// Result: void (global packages are upgraded system-wide, no package.json returned)

Default Export

The run function is exported as both named and default export.

export default run;
export { run };

Usage Examples:

// Default import
import ncu from "npm-check-updates";
const result = await ncu(options);

// Named import
import { run } from "npm-check-updates";
const result = await run(options);

Error Handling

The API includes comprehensive error handling with program termination utilities.

// Unhandled rejection tracking
process.on('unhandledRejection', (reason: string | Error) => void);

// Program error with exit code
function programError(options: Options, message: string): never;

Usage Examples:

import ncu from "npm-check-updates";

try {
  const result = await ncu({
    upgrade: true,
    errorLevel: 2 // Exit with error if dependencies are not up-to-date
  });
} catch (error) {
  console.error('Upgrade failed:', error.message);
  process.exit(1);
}

Timeout Support

Global timeout support for long-running operations.

interface RunOptions {
  timeout?: string | number; // Timeout in milliseconds
}

Usage Examples:

// Set 30 second timeout
const result = await ncu({
  upgrade: true,
  timeout: 30000
});

// String format also supported
const result = await ncu({
  upgrade: true,
  timeout: "30000"
});

Installation Integration

Automatic installation support after upgrading dependencies.

interface RunOptions {
  install?: 'always' | 'never' | 'prompt';
}

Usage Examples:

// Always install after upgrade
await ncu({
  upgrade: true,
  install: 'always'
});

// Never show install prompt
await ncu({
  upgrade: true,
  install: 'never'
});

// Prompt user in interactive mode
await ncu({
  upgrade: true,
  interactive: true,
  install: 'prompt'
});

Cache Management

Version caching for improved performance on repeated runs.

interface RunOptions {
  cache?: boolean;
  cacheFile?: string;
  cacheClear?: boolean;
}

Usage Examples:

// Enable caching with default cache file
await ncu({
  upgrade: true,
  cache: true
});

// Custom cache file location
await ncu({
  upgrade: true,
  cache: true,
  cacheFile: '/path/to/custom-cache.json'
});

// Clear cache before running
await ncu({
  upgrade: true,
  cacheClear: true
});

Working Directory Support

Specify working directory for npm operations.

interface RunOptions {
  cwd?: string;
}

Usage Examples:

// Run in specific directory
await ncu({
  upgrade: true,
  cwd: '/path/to/project'
});

// Relative path
await ncu({
  upgrade: true,
  cwd: '../other-project'
});

Install with Tessl CLI