0
# Module Lookup
1

2
Module and package discovery utilities for finding generators in npm packages and file systems.
3

4
## Capabilities
5

6
### Synchronous Module Lookup
7

8
Search for modules and packages synchronously using patterns and search paths.
9

10
```typescript { .api }
11
/**
12
 * Search for npm packages synchronously using glob patterns
13
 * @param patterns - Glob patterns to search for (string or array)
14
 * @param options - Lookup configuration options
15
 * @returns Single result or array of found package paths
16
 */
17
function moduleLookupSync(patterns: string | string[], options?: {
18
  /** Return package.json instead of main entry point */
19
  packageJson?: boolean;
20
  /** Return single result instead of array */
21
  singleResult?: boolean;
22
  /** Custom lookup paths to search */
23
  lookups?: string[];
24
  /** Specific npm paths to search */
25
  npmPaths?: string | string[];
26
}): string | string[];
27
```
28

29
**Usage Examples:**
30

31
```typescript
32
import { moduleLookupSync } from "yeoman-environment";
33

34
// Find all generator packages
35
const generators = moduleLookupSync("generator-*");
36
console.log("Found generators:", generators);
37

38
// Find specific generator with package.json
39
const webapp = moduleLookupSync("generator-webapp", {
40
  packageJson: true,
41
  singleResult: true
42
});
43

44
// Search in custom paths
45
const custom = moduleLookupSync("generator-*", {
46
  lookups: ["/custom/path/node_modules"],
47
  npmPaths: ["/usr/local/lib/node_modules"]
48
});
49
```
50

51
### Package Discovery
52

53
Find packages in specific search paths with pattern matching.
54

55
```typescript { .api }
56
/**
57
 * Find packages matching patterns in given search paths
58
 * @param patterns - Glob patterns to match against
59
 * @param searchPaths - Array of paths to search in
60
 * @returns Array of found package paths
61
 */
62
function findPackagesIn(
63
  patterns: string | string[],
64
  searchPaths: string[]
65
): string[];
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
import { findPackagesIn } from "yeoman-environment";
72

73
// Find generators in specific directories
74
const paths = [
75
  "/usr/local/lib/node_modules",
76
  "./node_modules",
77
  "~/.npm-global/lib/node_modules"
78
];
79

80
const packages = findPackagesIn("generator-*", paths);
81
console.log("Found packages:", packages);
82

83
// Find multiple patterns
84
const allPackages = findPackagesIn([
85
  "generator-*",
86
  "@*/generator-*",
87
  "yeoman-generator"
88
], paths);
89
```
90

91
### NPM Path Resolution
92

93
Get npm-related lookup directories for package discovery.
94

95
```typescript { .api }
96
/**
97
 * Get npm lookup directories including global and local paths
98
 * @param paths - Additional paths to include (optional)
99
 * @returns Array of npm-related search paths
100
 */
101
function getNpmPaths(paths?: string | string[]): string[];
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
import { getNpmPaths } from "yeoman-environment";
108

109
// Get standard npm paths
110
const npmPaths = getNpmPaths();
111
console.log("NPM search paths:", npmPaths);
112
// Typical output: [
113
//   "/usr/local/lib/node_modules",
114
//   "/home/user/.npm-global/lib/node_modules",
115
//   "./node_modules"
116
// ]
117

118
// Include custom paths
119
const customPaths = getNpmPaths([
120
  "/custom/node_modules",
121
  "/another/path/node_modules"
122
]);
123
```
124

125
## Integration with Environment
126

127
These module lookup functions are used internally by the Environment system for generator discovery, but can also be used directly for custom discovery logic.
128

129
```typescript
130
import { createEnv, moduleLookupSync, findPackagesIn } from "yeoman-environment";
131

132
const env = createEnv();
133

134
// Manual discovery before environment lookup
135
const manualGenerators = moduleLookupSync("generator-*");
136
console.log("Available generators:", manualGenerators);
137

138
// Register discovered generators
139
for (const generatorPath of manualGenerators) {
140
  try {
141
    env.register(generatorPath);
142
  } catch (error) {
143
    console.warn(`Failed to register ${generatorPath}:`, error.message);
144
  }
145
}
146

147
// Now use environment lookup for automatic discovery
148
await env.lookup();
149
```
150

151
## Lookup Options
152

153
```typescript { .api }
154
interface ModuleLookupOptions {
155
  /** Return package.json instead of main entry point */
156
  packageJson?: boolean;
157
  /** Return single result instead of array */
158
  singleResult?: boolean;
159
  /** Custom lookup paths to search */
160
  lookups?: string[];
161
  /** Specific npm paths to search */
162
  npmPaths?: string | string[];
163
  /** File patterns to match */
164
  filePatterns?: string | string[];
165
  /** Package patterns to match */
166
  packagePatterns?: string | string[];
167
}
168
```