0
# Package Detection
1

2
Core functionality for checking if packages exist and resolving their locations in the local environment, with support for different search paths and platform-specific behavior.
3

4
## Capabilities
5

6
### Package Existence Check
7

8
Check if a package exists in the local environment.
9

10
```typescript { .api }
11
/**
12
 * Check if a package exists in the local environment
13
 * @param name - Package name to check
14
 * @param options - Optional resolution configuration
15
 * @returns true if package exists, false otherwise
16
 */
17
function isPackageExists(name: string, options?: PackageResolvingOptions): boolean;
18
```
19

20
**Usage Examples:**
21

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

25
// Check if package exists
26
console.log(isPackageExists("express")); // true
27
console.log(isPackageExists("nonexistent-package")); // false
28

29
// Check with custom search paths
30
const exists = isPackageExists("my-package", {
31
  paths: ["/custom/node_modules"]
32
});
33

34
// Platform-specific resolution
35
const existsWin32 = isPackageExists("some-package", {
36
  platform: "win32"
37
});
38
```
39

40
### Module Resolution
41

42
Resolve the file path to a module, similar to require.resolve but works in both CJS and ESM environments.
43

44
```typescript { .api }
45
/**
46
 * Resolve module path similar to require.resolve
47
 * @param name - Module name to resolve
48
 * @param options - Optional resolution configuration
49
 * @returns Resolved module path or undefined if not found
50
 */
51
function resolveModule(name: string, options?: PackageResolvingOptions): string | undefined;
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
import { resolveModule } from "local-pkg";
58

59
// Basic module resolution
60
const expressPath = resolveModule("express");
61
console.log(expressPath); // "/path/to/node_modules/express/index.js"
62

63
// Resolve specific file within package
64
const middlewarePath = resolveModule("express/lib/middleware/query");
65

66
// Custom search paths
67
const customPath = resolveModule("my-package", {
68
  paths: ["/custom/node_modules", "/another/path"]
69
});
70

71
// Platform-specific paths
72
const winPath = resolveModule("some-package", {
73
  platform: "win32"  // Forces Windows-style path normalization
74
});
75
```
76

77
## Configuration Options
78

79
```typescript { .api }
80
interface PackageResolvingOptions {
81
  /** Custom search paths for package resolution */
82
  paths?: string[];
83
  /** 
84
   * Platform for path resolution
85
   * @default 'auto' - automatically detects platform
86
   */
87
  platform?: 'posix' | 'win32' | 'auto';
88
}
89
```
90

91
The `paths` option allows you to specify custom directories to search for packages, useful when working with non-standard package locations or custom mono-repo setups.
92

93
The `platform` option controls path normalization:
94
- `'auto'` (default): Automatically detects the current platform
95
- `'posix'`: Forces POSIX-style paths (forward slashes)
96
- `'win32'`: Forces Windows-style paths with proper normalization