0
# Environment Management
1

2
Core environment functionality for managing generator lifecycles, registration, and execution in Yeoman environments.
3

4
## Capabilities
5

6
### Environment Factory
7

8
Creates new Environment instances with configuration options.
9

10
```typescript { .api }
11
/**
12
 * Factory function to create Environment instances
13
 * @param options - Configuration options for the environment
14
 * @returns Environment instance
15
 */
16
function createEnv(options?: EnvironmentOptions): Environment;
17
```
18

19
**Usage Example:**
20

21
```typescript
22
import { createEnv } from "yeoman-environment";
23

24
// Create with default settings
25
const env = createEnv();
26

27
// Create with custom options
28
const customEnv = createEnv({
29
  adapter: myAdapter,
30
  skipInstall: true,
31
  logCwd: "/project/logs"
32
});
33
```
34

35
### Environment Class
36

37
Main Environment class extending EnvironmentBase with full generator lifecycle management.
38

39
```typescript { .api }
40
/**
41
 * Main Environment class with full generator lifecycle management
42
 */
43
class Environment extends EnvironmentBase {
44
  constructor(options?: EnvironmentOptions);
45

46
  /**
47
   * Generate help text for available generators
48
   * @param name - Generator name for specific help
49
   * @returns Help text string
50
   */
51
  help(name?: string): string;
52

53
  /**
54
   * Get all registered generator namespaces
55
   * @returns Array of namespace strings
56
   */
57
  namespaces(): string[];
58

59
  /**
60
   * Get metadata for all registered generators
61
   * @returns Object mapping namespaces to generator metadata
62
   */
63
  getGeneratorsMeta(): Record<string, GeneratorMeta>;
64

65
  /**
66
   * Get names of all registered generators
67
   * @returns Array of generator names
68
   */
69
  getGeneratorNames(): string[];
70

71
  /**
72
   * Get package path for a namespace
73
   * @param namespace - Generator namespace to look up
74
   * @returns Package path or undefined if not found
75
   */
76
  getPackagePath(namespace: string): string | undefined;
77

78
  /**
79
   * Get all package paths for a namespace
80
   * @param namespace - Generator namespace to look up
81
   * @returns Array of package paths
82
   */
83
  getPackagePaths(namespace: string): string[];
84

85
  /**
86
   * Execute a generator by namespace with arguments
87
   * @param generatorNamespace - Namespace of generator to run
88
   * @param args - Arguments to pass to generator
89
   */
90
  execute(generatorNamespace: string, args?: string[]): Promise<void>;
91

92
  /**
93
   * Require and return a generator constructor
94
   * @param namespace - Generator namespace to require
95
   * @returns Generator constructor or undefined
96
   */
97
  requireGenerator(namespace: string): Promise<BaseGeneratorConstructor | undefined>;
98

99
  /**
100
   * Install local generator packages
101
   * @param packages - Map of package names to versions
102
   * @returns True if installation succeeded
103
   */
104
  installLocalGenerators(packages: Record<string, string | undefined>): Promise<boolean>;
105

106
  /**
107
   * Lookup and register local packages
108
   * @param packagesToLookup - Optional array of specific packages to lookup
109
   */
110
  lookupLocalPackages(packagesToLookup?: string[]): Promise<void>;
111

112
  /**
113
   * Main run method for executing generators
114
   * @param args - Arguments for the generator
115
   * @param options - Options for execution
116
   */
117
  run(args?: string[], options?: any): Promise<void>;
118

119
  /**
120
   * Load environment-specific options
121
   * @param options - Options to load
122
   * @returns Loaded environment options
123
   */
124
  loadEnvironmentOptions(options: EnvironmentOptions): any;
125

126
  /**
127
   * Load options shared with generators
128
   * @param options - Options to share
129
   * @returns Loaded shared options
130
   */
131
  loadSharedOptions(options: EnvironmentOptions): any;
132
}
133
```
134

135
### EnvironmentBase Class
136

137
Base environment class with core functionality for generator management.
138

139
```typescript { .api }
140
/**
141
 * Base environment class with core functionality
142
 */
143
class EnvironmentBase {
144
  constructor(options?: EnvironmentOptions);
145

146
  /**
147
   * Find generator metadata by namespace or path
148
   * @param namespaceOrPath - Generator namespace or path
149
   * @returns Generator metadata or undefined
150
   */
151
  findMeta(namespaceOrPath: string | YeomanNamespace): Promise<GeneratorMeta | undefined>;
152

153
  /**
154
   * Get generator instance by namespace or path
155
   * @param namespaceOrPath - Generator namespace or path
156
   * @returns Generator instance or undefined
157
   */
158
  get<C>(namespaceOrPath: string | YeomanNamespace): Promise<C | undefined>;
159

160
  /**
161
   * Create generator instance with arguments
162
   * @param namespaceOrPath - Generator namespace, path, or constructor
163
   * @param args - Arguments to pass to generator
164
   * @returns Generator instance
165
   */
166
  create<G>(namespaceOrPath: string | GetGeneratorConstructor<G>, ...args: any[]): Promise<G>;
167

168
  /**
169
   * Instantiate generator from constructor
170
   * @param generator - Generator constructor
171
   * @param args - Arguments to pass to constructor
172
   * @returns Generator instance
173
   */
174
  instantiate<G>(generator: GetGeneratorConstructor<G>, ...args: any[]): Promise<G>;
175

176
  /**
177
   * Compose with another generator
178
   * @param generator - Generator to compose with
179
   * @param args - Arguments for the generator
180
   * @returns Composed generator instance
181
   */
182
  composeWith<G>(generator: string | GetGeneratorConstructor<G>, ...args: any[]): Promise<G>;
183

184
  /**
185
   * Convert filepath to namespace
186
   * @param filepath - File path to convert
187
   * @param lookups - Optional lookup paths
188
   * @returns Generator namespace
189
   */
190
  namespace(filepath: string, lookups?: string[]): string;
191

192
  /**
193
   * Get version information for a package
194
   * @param packageName - Package name (defaults to yeoman-environment)
195
   * @returns Version string or undefined
196
   */
197
  getVersion(packageName?: string): string | undefined;
198

199
  /**
200
   * Queue generator for execution
201
   * @param generator - Generator to queue
202
   * @param queueOptions - Queue options
203
   * @returns Queued generator
204
   */
205
  queueGenerator<G>(generator: G, queueOptions?: { schedule?: boolean }): Promise<G>;
206

207
  /**
208
   * Get root generator instance
209
   * @returns Root generator
210
   */
211
  rootGenerator<G>(): G;
212

213
  /**
214
   * Run a generator instance
215
   * @param generator - Generator to run
216
   */
217
  runGenerator(generator: BaseGenerator): Promise<void>;
218

219
  /**
220
   * Register a generator by path or constructor
221
   * @param pathOrStub - Generator path or constructor
222
   * @param meta - Optional metadata
223
   * @returns Generator metadata
224
   */
225
  register(pathOrStub: unknown, meta?: Partial<BaseGeneratorMeta>): GeneratorMeta;
226

227
  /**
228
   * Queue a task for execution at specified priority
229
   * @param priority - Task priority/queue name
230
   * @param task - Task function to execute
231
   * @param options - Task options
232
   */
233
  queueTask(priority: string, task: () => void | Promise<void>, options?: any): void;
234

235
  /**
236
   * Add custom priority to execution queue
237
   * @param priority - Priority name
238
   * @param before - Priority to insert before
239
   */
240
  addPriority(priority: string, before?: string): void;
241

242
  /**
243
   * Search for generators
244
   * @param options - Lookup options
245
   * @returns Array of found generator metadata
246
   */
247
  lookup(options?: EnvironmentLookupOptions): Promise<LookupGeneratorMeta[]>;
248

249
  /**
250
   * Check if package is registered
251
   * @param packageNamespace - Package namespace to check
252
   * @returns True if registered
253
   */
254
  isPackageRegistered(packageNamespace: string): boolean;
255

256
  /**
257
   * Get all registered package namespaces
258
   * @returns Array of registered package namespaces
259
   */
260
  getRegisteredPackages(): string[];
261

262
  /**
263
   * Get generator metadata by namespace
264
   * @param namespace - Generator namespace
265
   * @returns Generator metadata or undefined
266
   */
267
  getGeneratorMeta(namespace: string): GeneratorMeta | undefined;
268

269
  /**
270
   * Set or get namespace aliases
271
   * @param match - String or regex to match
272
   * @param value - Replacement value (optional for getter)
273
   * @returns Alias value or this for setter
274
   */
275
  alias(match: string | RegExp, value?: string): string | this;
276

277
  /**
278
   * Watch for package manager install operations
279
   * @param options - Watch options
280
   */
281
  watchForPackageManagerInstall(options?: any): void;
282

283
  /**
284
   * Find generators with specific features
285
   * @param featureName - Feature name to search for
286
   * @returns Array of generators with the feature
287
   */
288
  findFeature(featureName: string): Array<{ generatorId: string; feature: any }>;
289

290
  /**
291
   * Apply transforms to filesystem
292
   * @param transformStreams - Transform streams to apply
293
   * @param options - Transform options
294
   */
295
  applyTransforms(transformStreams: any[], options?: any): Promise<void>;
296
}
297
```
298

299
## Configuration Types
300

301
```typescript { .api }
302
interface EnvironmentOptions extends BaseEnvironmentOptions {
303
  /** Custom I/O adapter for input/output operations */
304
  adapter?: InputOutputAdapter;
305
  /** Path for logging purposes */
306
  logCwd?: string;
307
  /** Command instance for CLI integration */
308
  command?: YeomanCommand;
309
  /** Yeoman repository URL */
310
  yeomanRepository?: string;
311
  /** Arborist registry URL for npm operations */
312
  arboristRegistry?: string;
313
  /** Preferred package manager (npm, yarn, pnpm) */
314
  nodePackageManager?: string;
315
  /** Skip dependency installation */
316
  skipInstall?: boolean;
317
  /** Force dependency installation */
318
  forceInstall?: boolean;
319
  /** Skip prompt answer caching */
320
  skipCache?: boolean;
321
  /** Skip local answer caching */
322
  skipLocalCache?: boolean;
323
  /** Skip options parsing */
324
  skipParseOptions?: boolean;
325
  /** Generate config only locally */
326
  localConfigOnly?: boolean;
327
  /** Show prompts for already answered questions */
328
  askAnswered?: boolean;
329
}
330

331
interface EnvironmentLookupOptions extends LookupOptions {
332
  /** Add scope to namespace if missing */
333
  registerToScope?: string;
334
  /** Customize namespace during registration */
335
  customizeNamespace?: (ns?: string) => string | undefined;
336
}
337
```