Type Definitions

/**
 * Options that can be given on the CLI or passed to the ncu module to control all behavior.
 */
interface RunOptions {
  /** Cache versions to a local cache file. */
  cache?: boolean;
  /** Clear the default cache, or the cache file specified by `--cacheFile`. */
  cacheClear?: boolean;
  /** Cache expiration in minutes. Only works with `--cache`. */
  cacheExpiration?: number;
  /** Filepath for the cache file. Only works with `--cache`. */
  cacheFile?: string;
  /** Force color in terminal. */
  color?: boolean;
  /** Max number of concurrent HTTP requests to registry. */
  concurrency?: number;
  /** Config file name. (default: .ncurc.{json,yml,js,cjs}) */
  configFileName?: string;
  /** Directory of .ncurc config file. (default: directory of `packageFile`) */
  configFilePath?: string;
  /** Working directory in which npm will be executed. */
  cwd?: string;
  /** Run recursively in current working directory. */
  deep?: boolean;
  /** Check one or more sections of dependencies only: dev, optional, peer, prod, or packageManager. */
  dep?: string | readonly string[];
  /** Include deprecated packages. Use `--no-deprecated` to exclude deprecated packages. */
  deprecated?: boolean;
  /** Iteratively installs upgrades and runs tests to identify breaking upgrades. */
  doctor?: boolean;
  /** Specifies the install script to use in doctor mode. */
  doctorInstall?: string;
  /** Specifies the test script to use in doctor mode. */
  doctorTest?: string;
  /** Include only packages that satisfy engines.node as specified in the package file. */
  enginesNode?: boolean;
  /** Set the error level. 1: exits with error code 0 if no errors occur. 2: exits with error code 0 if no packages need updating. */
  errorLevel?: number;
  /** Include only package names matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function. */
  filter?: string | RegExp | readonly (string | RegExp)[] | FilterFunction;
  /** Filters results based on a user provided predicate function after fetching new versions. */
  filterResults?: FilterResultsFunction;
  /** Filter on package version using comma-or-space-delimited list, /regex/, or predicate function. */
  filterVersion?: string | RegExp | readonly (string | RegExp)[] | FilterFunction;
  /** Modify the output formatting or show additional information. */
  format?: readonly string[];
  /** Check global packages instead of in the current project. */
  global?: boolean;
  /** Customize how packages are divided into groups when using `--format group`. */
  groupFunction?: GroupFunction;
  /** Control the auto-install behavior: always, never, prompt. */
  install?: 'always' | 'never' | 'prompt';
  /** Enable interactive prompts for each dependency; implies `-u` unless one of the json options are set. */
  interactive?: boolean;
  /** Output new package file instead of human-readable message. */
  jsonAll?: boolean;
  /** Like `jsonAll` but only lists `dependencies`, `devDependencies`, `optionalDependencies`, etc of the new package data. */
  jsonDeps?: boolean;
  /** Output upgraded dependencies in json. */
  jsonUpgraded?: boolean;
  /** Amount to log: silent, error, minimal, warn, info, verbose, silly. */
  loglevel?: string;
  /** Merges nested configs with the root config file for `--deep` or `--packageFile` options. */
  mergeConfig?: boolean;
  /** Do not upgrade newer versions that are already satisfied by the version range according to semver. */
  minimal?: boolean;
  /** Package file data (you can also use stdin). */
  packageData?: string | PackageFile;
  /** Package file(s) location. (default: ./package.json) */
  packageFile?: string;
  /** npm, yarn, pnpm, deno, bun, staticRegistry (default: npm). */
  packageManager?: 'npm' | 'yarn' | 'pnpm' | 'deno' | 'bun' | 'staticRegistry';
  /** Check peer dependencies of installed packages and filter updates to compatible versions. */
  peer?: boolean;
  /** Include prerelease versions, e.g. -alpha.0, -beta.5, -rc.2. */
  pre?: boolean;
  /** Current working directory of npm. */
  prefix?: string;
  /** Specify the registry to use when looking up package versions. */
  registry?: string;
  /** Specify whether --registry refers to a full npm registry or a simple JSON file or url: npm, json. */
  registryType?: 'npm' | 'json';
  /** Exclude packages matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function. */
  reject?: string | RegExp | readonly (string | RegExp)[] | FilterFunction;
  /** Exclude package.json versions using comma-or-space-delimited list, /regex/, or predicate function. */
  rejectVersion?: string | RegExp | readonly (string | RegExp)[] | FilterFunction;
  /** Remove version ranges from the final package version. */
  removeRange?: boolean;
  /** Number of times to retry failed requests for package info. */
  retry?: number;
  /** Runs updates on the root project in addition to specified workspaces. */
  root?: boolean;
  /** Don't output anything. Alias for `--loglevel` silent. */
  silent?: boolean;
  /** Read package.json from stdin. */
  stdin?: string;
  /** Determines the version to upgrade to: latest, newest, greatest, minor, patch, semver, `@[tag]`, or [function]. */
  target?: 'latest' | 'newest' | 'greatest' | 'minor' | 'patch' | 'semver' | `@${string}` | TargetFunction;
  /** Global timeout in milliseconds. */
  timeout?: number;
  /** Overwrite package file with upgraded versions instead of just outputting to console. */
  upgrade?: boolean;
  /** Log additional information for debugging. */
  verbose?: boolean;
  /** Run on one or more specified workspaces. */
  workspace?: readonly string[];
  /** Run on all workspaces. */
  workspaces?: boolean;
}

import ncu, { RunOptions } from "npm-check-updates";

// Basic configuration
const options: RunOptions = {
  upgrade: true,
  target: "minor",
  interactive: false
};

// Advanced configuration
const advancedOptions: RunOptions = {
  packageFile: "./package.json",
  upgrade: true,
  target: "latest",
  filter: /^@myorg\//,
  reject: /^@types\//,
  cache: true,
  cacheExpiration: 60,
  concurrency: 4,
  timeout: 30000,
  install: "prompt",
  format: ["group", "repo"],
  loglevel: "verbose"
};

const result = await ncu(advancedOptions);

/**
 * A version specification or range supported as a value in package.json dependencies
 */
type VersionSpec = string;

/**
 * Generic object type for key-value mappings
 */
type Index<T> = Record<string, T>;

/**
 * The relevant bits of a parsed package.json file
 */
interface PackageFile {
  dependencies?: Index<VersionSpec>;
  devDependencies?: Index<VersionSpec>;
  imports?: Index<VersionSpec>;
  engines?: Index<VersionSpec>;
  name?: string;
  packageManager?: string;
  optionalDependencies?: Index<VersionSpec>;
  overrides?: NestedVersionSpecs;
  peerDependencies?: Index<VersionSpec>;
  repository?: string | PackageFileRepository;
  scripts?: Index<string>;
  workspaces?: string[] | { packages: string[] };
  version?: string;
}

/**
 * Nested version specifications for overrides
 */
type NestedVersionSpecs = {
  [name: string]: VersionSpec | NestedVersionSpecs;
};

/**
 * Repository configuration structure
 */
interface PackageFileRepository {
  type: string;
  url: string;
}

// Version specifications
const version: VersionSpec = "^1.2.3";
const exactVersion: VersionSpec = "1.2.3";
const rangeVersion: VersionSpec = ">=1.0.0 <2.0.0";

// Index types for dependencies
const dependencies: Index<VersionSpec> = {
  "react": "^18.0.0",
  "lodash": "~4.17.21"
};

// Package file structure (used in RunOptions.packageData)
const pkg: PackageFile = {
  name: "my-project",
  version: "1.0.0",
  dependencies: {
    "react": "^18.0.0",
    "express": "^4.18.0"
  },
  devDependencies: {
    "typescript": "^5.0.0",
    "@types/node": "^20.0.0"
  },
  engines: {
    "node": ">=18.0.0"
  }
};

/**
 * SemVer object from semver-utils package
 */
interface SemVer {
  major: number;
  minor: number;
  patch: number;
  release: string[];
  build: string[];
}

/**
 * Function signature for custom package filtering
 */
type FilterFunction = (
  packageName: string, 
  versionRange: SemVer[]
) => boolean;

/**
 * Function for filtering results based on version metadata
 */
type FilterResultsFunction = (
  packageName: string, 
  versioningMetadata: {
    currentVersion: VersionSpec;
    currentVersionSemver: SemVer[];
    upgradedVersion: string;
    upgradedVersionSemver: SemVer;
  }
) => boolean;

/**
 * Custom function for determining target versions
 */
type TargetFunction = (
  packageName: string, 
  versionRange: SemVer[]
) => string;

/**
 * Custom function for grouping packages in formatted output
 */
type GroupFunction = (
  packageName: string,
  defaultGroup: string,
  currentVersionSpec: SemVer[],
  upgradedVersionSpec: SemVer[],
  upgradedVersion: SemVer | null
) => string;

// Custom filter function
const orgFilter: FilterFunction = (packageName, versionRange) => {
  return packageName.startsWith('@myorg/');
};

// Custom target function
const conservativeTarget: TargetFunction = (packageName, versions) => {
  // Only allow patch updates
  return versions.find(v => v.patch > 0)?.toString() || versions[0].toString();
};

// Custom group function
const customGrouping: GroupFunction = (packageName, defaultGroup, current, upgraded, version) => {
  if (packageName.startsWith('@types/')) return 'TypeScript Types';
  return defaultGroup;
};

// Using custom functions in RunOptions
const options: RunOptions = {
  upgrade: true,
  filter: orgFilter,
  target: conservativeTarget,
  groupFunction: customGrouping,
  format: ['group']
};