0
# Programmatic API
1

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

4
## Capabilities
5

6
### Main Function
7

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

10
```typescript { .api }
11
/**
12
 * Main entry point for npm-check-updates functionality
13
 * @param runOptions - Configuration options for the upgrade process
14
 * @param options - Additional execution options
15
 * @returns Promise resolving to upgrade results or void for global upgrades
16
 */
17
function run(
18
  runOptions?: RunOptions,
19
  options?: { cli?: boolean }
20
): Promise<PackageFile | Index<VersionSpec> | void>;
21
```
22

23
**Return Types:**
24
- `PackageFile` - Default returns the complete package.json structure with upgraded dependency versions
25
- `Index<VersionSpec>` - When `jsonUpgraded` option is true, returns only the upgraded dependencies as key-value pairs  
26
- `void` - When `global` option is true (global package upgrades), returns void since no package.json is modified
27

28
**Usage Examples:**
29

30
```typescript
31
import ncu from "npm-check-updates";
32

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

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

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

48
// Global package upgrade - returns void
49
await ncu({ 
50
  global: true,
51
  upgrade: true 
52
});
53
// Result: void (global packages are upgraded system-wide, no package.json returned)
54
```
55

56
### Default Export
57

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

60
```typescript { .api }
61
export default run;
62
export { run };
63
```
64

65
**Usage Examples:**
66

67
```typescript
68
// Default import
69
import ncu from "npm-check-updates";
70
const result = await ncu(options);
71

72
// Named import
73
import { run } from "npm-check-updates";
74
const result = await run(options);
75
```
76

77
### Error Handling
78

79
The API includes comprehensive error handling with program termination utilities.
80

81
```typescript { .api }
82
// Unhandled rejection tracking
83
process.on('unhandledRejection', (reason: string | Error) => void);
84

85
// Program error with exit code
86
function programError(options: Options, message: string): never;
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
import ncu from "npm-check-updates";
93

94
try {
95
  const result = await ncu({
96
    upgrade: true,
97
    errorLevel: 2 // Exit with error if dependencies are not up-to-date
98
  });
99
} catch (error) {
100
  console.error('Upgrade failed:', error.message);
101
  process.exit(1);
102
}
103
```
104

105
### Timeout Support
106

107
Global timeout support for long-running operations.
108

109
```typescript { .api }
110
interface RunOptions {
111
  timeout?: string | number; // Timeout in milliseconds
112
}
113
```
114

115
**Usage Examples:**
116

117
```typescript
118
// Set 30 second timeout
119
const result = await ncu({
120
  upgrade: true,
121
  timeout: 30000
122
});
123

124
// String format also supported
125
const result = await ncu({
126
  upgrade: true,
127
  timeout: "30000"
128
});
129
```
130

131
### Installation Integration
132

133
Automatic installation support after upgrading dependencies.
134

135
```typescript { .api }
136
interface RunOptions {
137
  install?: 'always' | 'never' | 'prompt';
138
}
139
```
140

141
**Usage Examples:**
142

143
```typescript
144
// Always install after upgrade
145
await ncu({
146
  upgrade: true,
147
  install: 'always'
148
});
149

150
// Never show install prompt
151
await ncu({
152
  upgrade: true,
153
  install: 'never'
154
});
155

156
// Prompt user in interactive mode
157
await ncu({
158
  upgrade: true,
159
  interactive: true,
160
  install: 'prompt'
161
});
162
```
163

164
### Cache Management
165

166
Version caching for improved performance on repeated runs.
167

168
```typescript { .api }
169
interface RunOptions {
170
  cache?: boolean;
171
  cacheFile?: string;
172
  cacheClear?: boolean;
173
}
174
```
175

176
**Usage Examples:**
177

178
```typescript
179
// Enable caching with default cache file
180
await ncu({
181
  upgrade: true,
182
  cache: true
183
});
184

185
// Custom cache file location
186
await ncu({
187
  upgrade: true,
188
  cache: true,
189
  cacheFile: '/path/to/custom-cache.json'
190
});
191

192
// Clear cache before running
193
await ncu({
194
  upgrade: true,
195
  cacheClear: true
196
});
197
```
198

199
### Working Directory Support
200

201
Specify working directory for npm operations.
202

203
```typescript { .api }
204
interface RunOptions {
205
  cwd?: string;
206
}
207
```
208

209
**Usage Examples:**
210

211
```typescript
212
// Run in specific directory
213
await ncu({
214
  upgrade: true,
215
  cwd: '/path/to/project'
216
});
217

218
// Relative path
219
await ncu({
220
  upgrade: true,
221
  cwd: '../other-project'
222
});
223
```