0
# Process Management
1

2
Advanced generator process management for scenarios requiring direct control over subprocess communication, such as integrating with existing generator executables or implementing custom process lifecycle management.
3

4
## Capabilities
5

6
### GeneratorProcess Class
7

8
Manages generator subprocess communication via JSON-RPC over stdin/stderr. Use this when you need fine-grained control over process lifecycle or are integrating with existing generator binaries.
9

10
```typescript { .api }
11
/**
12
 * Manages generator subprocess communication
13
 * @param pathOrCommand - Path to generator executable or command
14
 * @param options - Configuration options for the process
15
 */
16
class GeneratorProcess {
17
  constructor(pathOrCommand: string, options?: GeneratorProcessOptions);
18
  
19
  /** Initialize the generator process */
20
  init(): Promise<void>;
21
  /** Get generator manifest information */
22
  getManifest(config: GeneratorConfig): Promise<GeneratorManifest | null>;
23
  /** Execute code generation */
24
  generate(options: GeneratorOptions): Promise<void>;
25
  /** Stop the generator process gracefully */
26
  stop(): void;
27
}
28

29
interface GeneratorProcessOptions {
30
  /** Whether the generator is a Node.js process (affects spawn behavior) */
31
  isNode?: boolean;
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import { GeneratorProcess } from "@prisma/generator-helper";
39

40
// Managing a Node.js generator
41
const nodeGenerator = new GeneratorProcess("./my-generator.js", { 
42
  isNode: true 
43
});
44

45
await nodeGenerator.init();
46

47
// Get generator information
48
const manifest = await nodeGenerator.getManifest({
49
  name: "my-generator",
50
  provider: { value: "./my-generator.js", fromEnvVar: null },
51
  output: { value: "./generated", fromEnvVar: null },
52
  config: {},
53
  binaryTargets: [],
54
  previewFeatures: [],
55
  sourceFilePath: "schema.prisma"
56
});
57

58
// Execute generation
59
await nodeGenerator.generate(generatorOptions);
60

61
// Clean shutdown
62
nodeGenerator.stop();
63
```
64

65
```typescript
66
// Managing a binary generator
67
const binaryGenerator = new GeneratorProcess("./my-generator-binary");
68

69
try {
70
  await binaryGenerator.init();
71
  await binaryGenerator.generate(options);
72
} catch (error) {
73
  if (error instanceof GeneratorError) {
74
    console.error(`Generator failed: ${error.message}`);
75
    if (error.code) console.error(`Error code: ${error.code}`);
76
    if (error.data) console.error(`Additional data:`, error.data);
77
  }
78
} finally {
79
  binaryGenerator.stop();
80
}
81
```
82

83
### Process Initialization
84

85
Initialize the generator subprocess and establish communication channels.
86

87
```typescript { .api }
88
/**
89
 * Initialize the generator process and establish communication
90
 * @throws GeneratorError if process fails to start or lacks permissions
91
 */
92
init(): Promise<void>;
93
```
94

95
The `init()` method handles:
96
- Spawning the generator process with appropriate stdio configuration
97
- Setting up JSON-RPC communication over stdin/stderr
98
- Configuring environment variables (`PRISMA_GENERATOR_INVOCATION: 'true'`)
99
- Error handling for common issues like permission problems (`EACCES`)
100

101
### Manifest Retrieval
102

103
Get generator metadata and capabilities from the subprocess.
104

105
```typescript { .api }
106
/**
107
 * Get generator manifest information
108
 * @param config - Generator configuration from Prisma schema
109
 * @returns Generator manifest or null if not supported
110
 * @throws GeneratorError if communication fails
111
 */
112
getManifest(config: GeneratorConfig): Promise<GeneratorManifest | null>;
113
```
114

115
### Code Generation
116

117
Execute the code generation process with full Prisma schema information.
118

119
```typescript { .api }
120
/**
121
 * Execute code generation with provided options
122
 * @param options - Complete generator options including DMMF, datasources, etc.
123
 * @throws GeneratorError if generation fails
124
 */
125
generate(options: GeneratorOptions): Promise<void>;
126
```
127

128
### Process Termination
129

130
Gracefully terminate the generator subprocess with proper signal handling.
131

132
```typescript { .api }
133
/**
134
 * Stop the generator process gracefully
135
 * Sends SIGTERM first, then SIGKILL after 2 seconds if process doesn't exit
136
 */
137
stop(): void;
138
```
139

140
The `stop()` method implements a two-phase shutdown:
141
1. Sends `SIGTERM` signal for graceful shutdown
142
2. Waits up to 2 seconds for process to exit
143
3. Sends `SIGKILL` if process is still running
144

145
## Error Handling
146

147
### GeneratorError Class
148

149
Specialized error class for generator process failures with additional context.
150

151
```typescript { .api }
152
/**
153
 * Custom error class for generator failures
154
 * @param message - Error description
155
 * @param code - Optional error code from JSON-RPC response
156
 * @param data - Optional additional error data (may include stack trace)
157
 */
158
class GeneratorError extends Error {
159
  name: "GeneratorError";
160
  
161
  constructor(
162
    message: string,
163
    code?: number,
164
    data?: any
165
  );
166
  
167
  /** JSON-RPC error code if available */
168
  code?: number;
169
  /** Additional error data (stack traces, context) */
170
  data?: any;
171
}
172
```
173

174
Common error scenarios:
175
- **Permission errors**: When generator executable lacks execute permissions
176
- **Communication errors**: When JSON-RPC communication fails  
177
- **Generation errors**: When the generator process encounters internal errors
178
- **Process termination**: When generator process exits unexpectedly
179

180
### Error Handling Patterns
181

182
```typescript
183
import { GeneratorProcess, GeneratorError } from "@prisma/generator-helper";
184

185
const generator = new GeneratorProcess("./my-generator");
186

187
try {
188
  await generator.init();
189
  await generator.generate(options);
190
} catch (error) {
191
  if (error instanceof GeneratorError) {
192
    // Handle generator-specific errors
193
    console.error(`Generator error: ${error.message}`);
194
    
195
    if (error.code === -32000) {
196
      console.error("Internal generator error");
197
    }
198
    
199
    if (error.data?.stack) {
200
      console.error("Generator stack trace:", error.data.stack);
201
    }
202
  } else if (error.code === 'EACCES') {
203
    // Handle permission errors
204
    console.error(`Generator executable needs execute permissions: chmod +x ./my-generator`);
205
  } else {
206
    // Handle other errors
207
    console.error("Unexpected error:", error);
208
  }
209
} finally {
210
  generator.stop();
211
}
212
```