0
# API Usage
1

2
Core programmatic API functions for dependency management and package analysis. The API provides complete control over dependency checking, resolution, and updating workflows.
3

4
## Core API Functions
5

6
### CheckPackages
7

8
Main function for checking and updating package dependencies with full lifecycle event support.
9

10
```typescript { .api }
11
/**
12
 * Check packages for dependency updates with optional callbacks
13
 * @param options - Configuration options for the check operation
14
 * @param callbacks - Optional event callbacks for lifecycle hooks
15
 * @returns Promise resolving to results with package metadata
16
 */
17
function CheckPackages(
18
  options: CheckOptions,
19
  callbacks?: CheckEventCallbacks
20
): Promise<{ packages: PackageMeta[] }>;
21

22
interface CheckEventCallbacks {
23
  /** Called after all packages are loaded but before processing */
24
  afterPackagesLoaded?: (pkgs: PackageMeta[]) => void;
25
  /** Called before processing each individual package */
26
  beforePackageStart?: (pkg: PackageMeta) => void;
27
  /** Called after processing each individual package */
28
  afterPackageEnd?: (pkg: PackageMeta) => void;
29
  /** Called before writing changes to a package (return false to skip) */
30
  beforePackageWrite?: (pkg: PackageMeta) => boolean | Promise<boolean>;
31
  /** Called after all packages are processed */
32
  afterPackagesEnd?: (pkgs: PackageMeta[]) => void;
33
  /** Called after writing changes to a package */
34
  afterPackageWrite?: (pkg: PackageMeta) => void;
35
  /** Called during dependency resolution for progress tracking */
36
  onDependencyResolved?: (packageName: string | null, depName: string, progress: number, total: number) => void;
37
}
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
import { CheckPackages } from "taze";
44

45
// Basic usage
46
const result = await CheckPackages({
47
  cwd: process.cwd(),
48
  mode: "minor"
49
});
50

51
// With callbacks for progress tracking
52
const result = await CheckPackages({
53
  mode: "patch",
54
  write: true
55
}, {
56
  afterPackagesLoaded: (packages) => {
57
    console.log(`Processing ${packages.length} packages`);
58
  },
59
  onDependencyResolved: (pkg, dep, progress, total) => {
60
    console.log(`Resolved ${dep} (${progress}/${total})`);
61
  },
62
  beforePackageWrite: (pkg) => {
63
    console.log(`Writing updates to ${pkg.filepath}`);
64
    return true; // Allow write
65
  }
66
});
67
```
68

69
### Package Loading Functions
70

71
Functions for loading and managing package metadata from the filesystem.
72

73
```typescript { .api }
74
/**
75
 * Load all packages from the current directory structure
76
 * @param options - Common options for package discovery
77
 * @returns Promise resolving to array of package metadata
78
 */
79
function loadPackages(options: CommonOptions): Promise<PackageMeta[]>;
80

81
/**
82
 * Load a single package file (package.json or pnpm-workspace.yaml)
83
 * @param relative - Relative path to the package file
84
 * @param options - Common options for loading
85
 * @param shouldUpdate - Function to determine if a dependency should be updated
86
 * @returns Promise resolving to array of package metadata
87
 */
88
function loadPackage(
89
  relative: string,
90
  options: CommonOptions,
91
  shouldUpdate: (name: string) => boolean
92
): Promise<PackageMeta[]>;
93

94
/**
95
 * Write updated package data back to disk
96
 * @param pkg - Package metadata with resolved changes
97
 * @param options - Common options for writing
98
 * @returns Promise that resolves when write is complete
99
 */
100
function writePackage(pkg: PackageMeta, options: CommonOptions): Promise<void>;
101
```
102

103
### Dependency Resolution Functions
104

105
Functions for resolving dependency versions and analyzing update requirements.
106

107
```typescript { .api }
108
/**
109
 * Resolve dependencies for a single package
110
 * @param pkg - Package metadata to resolve dependencies for
111
 * @param options - Check options for resolution configuration
112
 * @param filter - Optional filter function for dependency inclusion
113
 * @param onProgress - Optional progress callback
114
 * @returns Promise that resolves when resolution is complete
115
 */
116
function resolvePackage(
117
  pkg: PackageMeta,
118
  options: CheckOptions,
119
  filter?: DependencyFilter,
120
  onProgress?: DependencyResolvedCallback
121
): Promise<void>;
122

123
/**
124
 * Resolve a single dependency to its target version
125
 * @param dep - Raw dependency to resolve
126
 * @param options - Check options for resolution configuration
127
 * @param filter - Optional filter function for dependency inclusion
128
 * @returns Promise resolving to resolved dependency change
129
 */
130
function resolveDependency(
131
  dep: RawDep,
132
  options: CheckOptions,
133
  filter?: DependencyFilter
134
): Promise<ResolvedDepChange>;
135

136
/**
137
 * Resolve dependencies for multiple packages
138
 * @param deps - Array of raw dependencies to resolve
139
 * @param options - Check options for resolution configuration
140
 * @param filter - Optional filter function for dependency inclusion
141
 * @param progressCallback - Optional progress callback
142
 * @returns Promise that resolves when all resolutions are complete
143
 */
144
function resolveDependencies(
145
  deps: RawDep[],
146
  options: CheckOptions,
147
  filter?: DependencyFilter,
148
  progressCallback?: (name: string, counter: number, total: number) => void
149
): Promise<void>;
150
```
151

152
### Dependency Processing Functions
153

154
Functions for parsing and formatting dependency data.
155

156
```typescript { .api }
157
/**
158
 * Parse dependencies from package.json structure into RawDep format
159
 * @param pkg - Package.json object or similar structure
160
 * @param type - Type of dependencies to parse
161
 * @param shouldUpdate - Function to determine if dependency should be updated
162
 * @returns Array of raw dependency objects
163
 */
164
function parseDependencies(
165
  pkg: any,
166
  type: DepType,
167
  shouldUpdate: (name: string) => boolean
168
): RawDep[];
169

170
/**
171
 * Convert resolved dependency changes back to package.json format
172
 * @param deps - Array of resolved dependency changes
173
 * @param type - Type of dependencies to dump
174
 * @returns Object with dependency names and versions
175
 */
176
function dumpDependencies(deps: ResolvedDepChange[], type: DepType): Record<string, any>;
177
```
178

179
### Configuration Helper
180

181
```typescript { .api }
182
/**
183
 * Helper for defining configuration with full type safety
184
 * @param config - Partial configuration object
185
 * @returns The same configuration object with type information
186
 */
187
function defineConfig(config: Partial<CheckOptions>): Partial<CheckOptions>;
188
```
189

190
**Usage Example:**
191

192
```typescript
193
import { defineConfig, CheckPackages } from "taze";
194

195
const config = defineConfig({
196
  mode: "minor",
197
  include: ["react", "vue"],
198
  exclude: ["legacy-*"],
199
  write: false,
200
  interactive: true
201
});
202

203
const result = await CheckPackages(config);
204
```
205

206
## Type Definitions
207

208
### Core Package Types
209

210
```typescript { .api }
211
interface PackageMeta {
212
  /** Package name */
213
  name: string;
214
  /** Is private package */
215
  private: boolean;
216
  /** Package version */
217
  version: string;
218
  /** Absolute filepath */
219
  filepath: string;
220
  /** Relative filepath to the root project */
221
  relative: string;
222
  /** Dependencies */
223
  deps: RawDep[];
224
  /** Resolved dependencies */
225
  resolved: ResolvedDepChange[];
226
}
227

228
interface RawDep {
229
  /** Dependency name */
230
  name: string;
231
  /** Current version specification */
232
  currentVersion: string;
233
  /** Source field in package.json */
234
  source: DepType;
235
  /** Whether this dependency should be updated */
236
  update: boolean;
237
  /** Parent path for nested dependencies */
238
  parents?: string[];
239
  /** Protocol (npm, jsr) */
240
  protocol?: Protocol;
241
}
242

243
interface ResolvedDepChange extends RawDep {
244
  /** Latest version available */
245
  latestVersionAvailable?: string;
246
  /** Target version to update to */
247
  targetVersion: string;
248
  /** Timestamp of target version */
249
  targetVersionTime?: string;
250
  /** Timestamp of current version */
251
  currentVersionTime?: string;
252
  /** Target version provenance status */
253
  targetProvenance?: boolean | 'trustedPublisher';
254
  /** Current version provenance status */
255
  currentProvenance?: boolean | 'trustedPublisher';
256
  /** Whether provenance was downgraded */
257
  provenanceDowngraded: boolean;
258
  /** Type of version difference */
259
  diff: DiffType;
260
  /** Package metadata from registry */
261
  pkgData: PackageData;
262
  /** Error during resolution if any */
263
  resolveError?: Error | string | null;
264
  /** Alias name for aliased dependencies */
265
  aliasName?: string;
266
  /** Node.js compatibility information */
267
  nodeCompatibleVersion?: { semver: string; compatible: boolean };
268
}
269
```
270

271
### Filter and Callback Types
272

273
```typescript { .api }
274
type DependencyFilter = (dep: RawDep) => boolean | Promise<boolean>;
275

276
type DependencyResolvedCallback = (
277
  packageName: string | null,
278
  depName: string,
279
  progress: number,
280
  total: number
281
) => void;
282
```
283

284
### Dependency Types
285

286
```typescript { .api }
287
type DepType =
288
  | "dependencies"
289
  | "devDependencies"
290
  | "peerDependencies"
291
  | "optionalDependencies"
292
  | "packageManager"
293
  | "pnpm.overrides"
294
  | "resolutions"
295
  | "overrides"
296
  | "pnpm-workspace";
297

298
type Protocol = "npm" | "jsr";
299

300
type DiffType = "major" | "minor" | "patch" | "error" | null;
301
```
302

303
## Advanced Usage Patterns
304

305
### Custom Package Processing
306

307
```typescript
308
import { CheckPackages, PackageMeta } from "taze";
309

310
await CheckPackages({
311
  mode: "minor",
312
  recursive: true
313
}, {
314
  beforePackageStart: (pkg: PackageMeta) => {
315
    console.log(`Processing ${pkg.name} at ${pkg.relative}`);
316
  },
317
  beforePackageWrite: (pkg: PackageMeta) => {
318
    // Custom validation before writing
319
    const hasBreakingChanges = pkg.resolved.some(dep => dep.diff === "major");
320
    if (hasBreakingChanges) {
321
      console.warn(`Skipping ${pkg.name} due to breaking changes`);
322
      return false; // Skip writing
323
    }
324
    return true;
325
  }
326
});
327
```
328

329
### Selective Dependency Updates
330

331
```typescript
332
import { CheckPackages, defineConfig } from "taze";
333

334
const config = defineConfig({
335
  mode: "patch", // Only patch updates
336
  include: ["@types/*"], // Only type packages
337
  exclude: ["react"], // Exclude React updates
338
  depFields: {
339
    dependencies: true,
340
    devDependencies: true,
341
    peerDependencies: false // Skip peer deps
342
  }
343
});
344

345
const result = await CheckPackages(config);
346
```