0
# Core Arborist Operations
1

2
The main Arborist class provides high-level dependency tree management operations. It manages three types of trees: actual (what's on disk), virtual (from lockfiles), and ideal (desired state).
3

4
## Capabilities
5

6
### Constructor
7

8
Creates a new Arborist instance with configuration options.
9

10
```javascript { .api }
11
/**
12
 * Create a new Arborist instance
13
 * @param options - Configuration options
14
 */
15
constructor(options?: ArboristOptions): Arborist;
16

17
interface ArboristOptions {
18
  /** Project root path, defaults to current directory */
19
  path?: string;
20
  /** Cache directory path, defaults to ~/.npm/_cacache */
21
  cache?: string;
22
  /** Registry URL, defaults to npm registry */
23
  registry?: string;
24
  /** Node.js version, defaults to process.version */
25
  nodeVersion?: string;
26
  /** Enable binary links, default true */
27
  binLinks?: boolean;
28
  /** Dry run mode, default false */
29
  dryRun?: boolean;
30
  /** Format package-lock.json, default true */
31
  formatPackageLock?: boolean;
32
  /** Force operations, default false */
33
  force?: boolean;
34
  /** Global package mode, default false */
35
  global?: boolean;
36
  /** Skip lifecycle scripts, default false */
37
  ignoreScripts?: boolean;
38
  /** Installation strategy: 'hoisted' or 'shallow', default 'hoisted' */
39
  installStrategy?: 'hoisted' | 'shallow';
40
  /** Lockfile version (1, 2, 3, or null for auto) */
41
  lockfileVersion?: 1 | 2 | 3 | null;
42
  /** Only use package-lock.json, default false */
43
  packageLockOnly?: boolean;
44
  /** Custom packument cache instance */
45
  packumentCache?: any;
46
  /** Rebuild bundled packages, default true */
47
  rebuildBundle?: boolean;
48
  /** Registry host replacement */
49
  replaceRegistryHost?: string;
50
  /** Save prefix for versions, default '^' */
51
  savePrefix?: string;
52
  /** Shell for running scripts */
53
  scriptShell?: string;
54
  /** Workspace names filter */
55
  workspaces?: string[];
56
  /** Enable workspaces support, default true */
57
  workspacesEnabled?: boolean;
58
}
59
```
60

61
**Usage Example:**
62

63
```javascript
64
const Arborist = require('@npmcli/arborist');
65

66
const arb = new Arborist({
67
  path: '/path/to/project',
68
  registry: 'https://registry.npmjs.org',
69
  dryRun: false,
70
  force: false
71
});
72
```
73

74
### Load Actual Tree
75

76
Loads the actual dependency tree from disk by reading node_modules directories.
77

78
```javascript { .api }
79
/**
80
 * Load actual dependency tree from disk
81
 * @param options - Loading options
82
 * @returns Promise resolving to the root node of the actual tree
83
 */
84
loadActual(options?: LoadOptions): Promise<Node>;
85

86
interface LoadOptions {
87
  /** Filter function to control which nodes are loaded */
88
  filter?: (node: Node, kidName: string) => boolean;
89
  /** Force loading from actual filesystem, ignore cache */
90
  forceActual?: boolean;
91
}
92
```
93

94
**Usage Example:**
95

96
```javascript
97
// Load complete actual tree
98
const actualTree = await arb.loadActual();
99

100
// Load with filtering
101
const filteredTree = await arb.loadActual({
102
  filter: (node, kidName) => !kidName.startsWith('.')
103
});
104
```
105

106
### Load Virtual Tree
107

108
Loads the virtual dependency tree from package.json and lockfiles without reading node_modules.
109

110
```javascript { .api }
111
/**
112
 * Load virtual tree from package.json and lockfiles
113
 * @param options - Loading options
114
 * @returns Promise resolving to the root node of the virtual tree
115
 */
116
loadVirtual(options?: LoadOptions): Promise<Node>;
117
```
118

119
**Usage Example:**
120

121
```javascript
122
// Load virtual tree from lockfile
123
const virtualTree = await arb.loadVirtual();
124

125
// Access the loaded tree
126
console.log(`Virtual tree root: ${virtualTree.name}@${virtualTree.version}`);
127
```
128

129
### Build Ideal Tree
130

131
Builds the ideal dependency tree based on package.json, lockfiles, and requested changes.
132

133
```javascript { .api }
134
/**
135
 * Build ideal dependency tree incorporating requested changes
136
 * @param options - Build options including packages to add/remove
137
 * @returns Promise that resolves when ideal tree is built
138
 */
139
buildIdealTree(options?: BuildOptions): Promise<void>;
140

141
interface BuildOptions {
142
  /** Array of package specifiers to add */
143
  add?: string[];
144
  /** Array of package names to remove */
145
  rm?: string[];
146
  /** Update configuration */
147
  update?: boolean | { all?: boolean; names?: string[] };
148
  /** Where to save added packages */
149
  saveType?: 'prod' | 'dev' | 'optional' | 'peer' | 'peerOptional';
150
  /** Add to bundleDependencies list */
151
  saveBundle?: boolean;
152
  /** Prune extraneous packages, default true */
153
  prune?: boolean;
154
  /** Prefer to deduplicate rather than update */
155
  preferDedupe?: boolean;
156
  /** Use npm v2 style nesting */
157
  legacyBundling?: boolean;
158
}
159
```
160

161
**Usage Examples:**
162

163
```javascript
164
// Add production dependencies
165
await arb.buildIdealTree({
166
  add: ['express@^4.18.0', 'lodash@latest'],
167
  saveType: 'prod'
168
});
169

170
// Remove packages
171
await arb.buildIdealTree({
172
  rm: ['old-package', 'unused-dep']
173
});
174

175
// Update all packages
176
await arb.buildIdealTree({
177
  update: { all: true }
178
});
179

180
// Update specific packages
181
await arb.buildIdealTree({
182
  update: { names: ['express', 'lodash'] }
183
});
184
```
185

186
### Reify Changes
187

188
Applies the ideal tree to disk, making the actual tree match the ideal tree.
189

190
```javascript { .api }
191
/**
192
 * Apply ideal tree changes to disk
193
 * @param options - Reification options
194
 * @returns Promise that resolves when reification is complete
195
 */
196
reify(options?: ReifyOptions): Promise<void>;
197

198
interface ReifyOptions {
199
  /** Write lockfile back to disk, default true */
200
  save?: boolean;
201
  /** Dry run mode - don't make actual changes */
202
  dryRun?: boolean;
203
  /** Dependency types to omit during install */
204
  omit?: string[];
205
  /** Dependency types to include during install */
206
  include?: string[];
207
}
208
```
209

210
**Usage Examples:**
211

212
```javascript
213
// Standard reification
214
await arb.reify();
215

216
// Dry run to see what would change
217
await arb.reify({ dryRun: true });
218

219
// Omit dev dependencies
220
await arb.reify({ omit: ['dev'] });
221
```
222

223
### Audit Dependencies
224

225
Runs security audit on the dependency tree.
226

227
```javascript { .api }
228
/**
229
 * Run security audit on dependencies
230
 * @param options - Audit options
231
 * @returns Promise resolving to audit report or reification result if fix=true
232
 */
233
audit(options?: AuditOptions): Promise<any>;
234

235
interface AuditOptions {
236
  /** Automatically fix vulnerabilities */
237
  fix?: boolean;
238
  /** Use package-lock.json instead of building ideal tree */
239
  packageLock?: boolean;
240
  /** Set of nodes to include in audit */
241
  filterSet?: Set<Node>;
242
}
243
```
244

245
**Usage Examples:**
246

247
```javascript
248
// Run audit without fixing
249
const auditReport = await arb.audit();
250

251
// Run audit and automatically fix issues
252
await arb.audit({ fix: true });
253
```
254

255
### Deduplicate Dependencies
256

257
Removes duplicate dependencies by consolidating identical packages.
258

259
```javascript { .api }
260
/**
261
 * Remove duplicate dependencies
262
 * @param options - Deduplication options
263
 * @returns Promise that resolves when deduplication is complete
264
 */
265
dedupe(options?: DedupeOptions): Promise<void>;
266

267
interface DedupeOptions {
268
  /** Dry run mode */
269
  dryRun?: boolean;
270
  /** Save changes to lockfile */
271
  save?: boolean;
272
}
273
```
274

275
**Usage Example:**
276

277
```javascript
278
// Deduplicate all possible packages
279
await arb.dedupe();
280
```
281

282
### Workspace Management
283

284
Methods for working with npm workspaces in monorepos.
285

286
```javascript { .api }
287
/**
288
 * Get nodes corresponding to specified workspaces
289
 * @param tree - Root tree node
290
 * @param workspaces - Array of workspace names
291
 * @returns Array of workspace nodes
292
 */
293
workspaceNodes(tree: Node, workspaces: string[]): Node[];
294

295
/**
296
 * Get dependency set for workspaces including all their dependencies
297
 * @param tree - Root tree node
298
 * @param workspaces - Array of workspace names
299
 * @param includeWorkspaceRoot - Include root workspace dependencies
300
 * @returns Set of nodes in workspace dependency tree
301
 */
302
workspaceDependencySet(
303
  tree: Node, 
304
  workspaces: string[], 
305
  includeWorkspaceRoot?: boolean
306
): Set<Node>;
307

308
/**
309
 * Get dependencies excluding workspace-only dependencies
310
 * @param tree - Root tree node
311
 * @returns Set of non-workspace dependencies
312
 */
313
excludeWorkspacesDependencySet(tree: Node): Set<Node>;
314
```
315

316
**Usage Example:**
317

318
```javascript
319
// Load tree and get workspace nodes
320
const tree = await arb.loadActual();
321
const wsNodes = arb.workspaceNodes(tree, ['workspace-a', 'workspace-b']);
322

323
// Get all dependencies for specific workspaces
324
const wsDepSet = arb.workspaceDependencySet(tree, ['workspace-a']);
325
```
326

327
## Properties
328

329
```javascript { .api }
330
interface ArboristInstance {
331
  /** Configuration options */
332
  options: ArboristOptions;
333
  /** Resolved cache directory path */
334
  cache: string;
335
  /** Resolved project path */
336
  path: string;
337
  /** Last tree diff result */
338
  diff: any | null;
339
  /** Last audit report */
340
  auditReport: any | null;
341
  /** Registry host replacement setting */
342
  replaceRegistryHost: string;
343
}
344
```