0
# Package Information
1

2
Retrieve comprehensive metadata and information about installed packages, including version details, file system paths, and complete package.json contents. Available in both asynchronous and synchronous variants.
3

4
## Capabilities
5

6
### Get Package Information (Async)
7

8
Retrieve detailed information about a package asynchronously.
9

10
```typescript { .api }
11
/**
12
 * Get comprehensive information about a package (async)
13
 * @param name - Package name to get information for
14
 * @param options - Optional resolution configuration
15
 * @returns Promise resolving to PackageInfo or undefined if package not found
16
 */
17
function getPackageInfo(name: string, options?: PackageResolvingOptions): Promise<PackageInfo | undefined>;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { getPackageInfo } from "local-pkg";
24

25
// Get basic package information
26
const info = await getPackageInfo("express");
27
if (info) {
28
  console.log(info.name);           // "express"
29
  console.log(info.version);        // "4.18.2"
30
  console.log(info.rootPath);       // "/path/to/node_modules/express"
31
  console.log(info.packageJsonPath); // "/path/to/node_modules/express/package.json"
32
  console.log(info.packageJson);    // Full package.json object
33
}
34

35
// Handle non-existent packages
36
const missing = await getPackageInfo("nonexistent-package");
37
console.log(missing); // undefined
38

39
// Use custom search paths
40
const customInfo = await getPackageInfo("my-package", {
41
  paths: ["/custom/node_modules"]
42
});
43
```
44

45
### Get Package Information (Sync)
46

47
Retrieve detailed information about a package synchronously.
48

49
```typescript { .api }
50
/**
51
 * Get comprehensive information about a package (sync)
52
 * @param name - Package name to get information for
53
 * @param options - Optional resolution configuration
54
 * @returns PackageInfo or undefined if package not found
55
 */
56
function getPackageInfoSync(name: string, options?: PackageResolvingOptions): PackageInfo | undefined;
57
```
58

59
**Usage Examples:**
60

61
```typescript
62
import { getPackageInfoSync } from "local-pkg";
63

64
// Synchronous package information retrieval
65
const info = getPackageInfoSync("lodash");
66
if (info) {
67
  console.log(`${info.name}@${info.version}`);
68
  
69
  // Access full package.json data
70
  console.log(info.packageJson.description);
71
  console.log(info.packageJson.dependencies);
72
  console.log(info.packageJson.main);
73
}
74
```
75

76
## Package Information Structure
77

78
```typescript { .api }
79
interface PackageInfo {
80
  /** Package name as specified in package.json */
81
  name: string;
82
  /** Root directory path of the package */
83
  rootPath: string;
84
  /** Full path to the package.json file */
85
  packageJsonPath: string;
86
  /** Package version string */
87
  version: string;
88
  /** Complete parsed package.json object */
89
  packageJson: PackageJson;
90
}
91
```
92

93
The `PackageInfo` interface provides comprehensive access to package metadata:
94

95
- **name**: The package name exactly as specified in its package.json
96
- **rootPath**: The file system path to the package's root directory
97
- **packageJsonPath**: Full path to the package.json file itself
98
- **version**: Current version string of the installed package
99
- **packageJson**: The complete, parsed package.json object containing all metadata including dependencies, scripts, configuration, etc.
100

101
## Error Handling
102

103
Both functions return `undefined` when a package cannot be found or accessed, rather than throwing errors. This allows for graceful handling of missing packages:
104

105
```typescript
106
import { getPackageInfo } from "local-pkg";
107

108
const info = await getPackageInfo("might-not-exist");
109
if (!info) {
110
  console.log("Package not found or not accessible");
111
} else {
112
  console.log(`Found ${info.name}@${info.version}`);
113
}
114
```