0
# Regenerator
1

2
Regenerator is a source transformation tool that enables the use of ECMAScript 2015 generator functions (yield) and async/await syntax in JavaScript environments that don't natively support them. It transforms modern JavaScript code to ES5-compatible code, providing both a programmatic API and command-line interface for transforming generator and async function syntax.
3

4
## Package Information
5

6
- **Package Name**: regenerator
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install -g regenerator`
10

11
## Core Imports
12

13
```javascript
14
// CommonJS - programmatic API
15
const regenerator = require("regenerator");
16

17
// Individual functions
18
const { compile, transform, runtime, types } = require("regenerator");
19
```
20

21
## Basic Usage
22

23
### Command Line Usage
24

25
```bash
26
# Transform a file
27
regenerator es6.js > es5.js
28

29
# Include runtime in output
30
regenerator --include-runtime es6.js > es5.js
31

32
# Transform directory
33
regenerator src lib
34

35
# Disable async transformation
36
regenerator --disable-async input.js > output.js
37
```
38

39
### Programmatic Usage
40

41
```javascript
42
const regenerator = require("regenerator");
43

44
// Compile source code string
45
const result = regenerator.compile(es6Source);
46
console.log(result.code); // Transformed ES5 code
47

48
// Include runtime in output
49
const resultWithRuntime = regenerator.compile(es6Source, {
50
  includeRuntime: true
51
});
52
console.log(resultWithRuntime.code);
53
```
54

55
### AST Transformation
56

57
```javascript
58
const recast = require("recast");
59
const regenerator = require("regenerator");
60

61
// Parse and transform AST
62
const ast = recast.parse(es6Source);
63
const transformedAst = regenerator.transform(ast);
64
const es5Source = recast.print(transformedAst);
65
```
66

67
## Architecture
68

69
Regenerator is built around several core components:
70

71
- **Babel Integration**: Uses Babel core for parsing and code generation
72
- **AST Transformation**: Leverages Recast for AST manipulation and source mapping
73
- **Runtime Injection**: Optionally includes regenerator-runtime for execution
74
- **CLI Interface**: Command-line tool built on Commoner for file processing
75
- **Stream Interface**: Browserify transform support for build pipelines
76

77
## Capabilities
78

79
### Source Code Compilation
80

81
Transforms ES6+ generator and async function source code to ES5-compatible JavaScript.
82

83
```javascript { .api }
84
/**
85
 * Compiles ES6+ source code with generator/async functions to ES5
86
 * @param {string} source - Source code to transform
87
 * @param {Object} options - Compilation options
88
 * @param {boolean} options.includeRuntime - Include regenerator-runtime in output
89
 * @param {boolean} options.disableAsync - Disable async function transformation
90
 * @returns {Object} Result object with transformed code and optional source map
91
 */
92
function compile(source, options);
93
```
94

95
### AST Transformation
96

97
Direct AST manipulation for integration with other build tools and transformers.
98

99
```javascript { .api }
100
/**
101
 * Transforms an AST containing generator/async functions
102
 * @param {Object} node - AST node to transform (File, Program, or other node)
103
 * @param {Object} options - Transformation options
104
 * @param {boolean} options.includeRuntime - Inject runtime directly into AST
105
 * @returns {Object} Transformed AST node
106
 */
107
function transform(node, options);
108
```
109

110
### Runtime Management
111

112
Functions for managing the regenerator runtime dependency.
113

114
```javascript { .api }
115
/**
116
 * Registers regenerator-runtime globally in the current Node.js process
117
 * Sets global regeneratorRuntime variable
118
 * @returns {void}
119
 */
120
function runtime();
121

122
/**
123
 * Absolute file system path to the runtime.js file
124
 * @type {string}
125
 */
126
runtime.path;
127
```
128

129
### Stream Interface
130

131
Browserify transform stream for build pipeline integration.
132

133
```javascript { .api }
134
/**
135
 * Creates a transform stream for use with browserify or other stream-based tools
136
 * @param {string} file - File path being transformed
137
 * @param {Object} options - Stream transformation options
138
 * @returns {Stream} Transform stream that processes JavaScript code
139
 */
140
function module.exports(file, options);
141
```
142

143
### AST Types
144

145
Access to Recast AST types for advanced AST manipulation.
146

147
```javascript { .api }
148
/**
149
 * Recast AST types for building and manipulating syntax trees
150
 * @type {Object} Recast types object with builders and checkers
151
 */
152
const types;
153
```
154

155
## Types
156

157
```javascript { .api }
158
// Compilation result interface
159
interface CompilationResult {
160
  code: string;        // Transformed JavaScript code
161
  map?: Object;        // Source map information (if available)
162
}
163

164
// Compilation options interface
165
interface CompileOptions {
166
  includeRuntime?: boolean;    // Include regenerator-runtime in output
167
  disableAsync?: boolean;      // Disable async function transformation
168
}
169

170
// Transform options interface  
171
interface TransformOptions {
172
  includeRuntime?: boolean;    // Inject runtime into AST
173
}
174
```
175

176
## Usage Examples
177

178
### Basic Generator Transformation
179

180
```javascript
181
const regenerator = require("regenerator");
182

183
const es6Code = `
184
function* fibonacci() {
185
  let [a, b] = [0, 1];
186
  while (true) {
187
    yield a;
188
    [a, b] = [b, a + b];
189
  }
190
}
191
`;
192

193
const result = regenerator.compile(es6Code, { includeRuntime: true });
194
console.log(result.code);
195
// Outputs ES5-compatible code with regenerator runtime
196
```
197

198
### Async Function Transformation
199

200
```javascript
201
const regenerator = require("regenerator");
202

203
const asyncCode = `
204
async function fetchData(url) {
205
  const response = await fetch(url);
206
  return await response.json();
207
}
208
`;
209

210
const result = regenerator.compile(asyncCode);
211
console.log(result.code);
212
// Outputs transformed code using regenerator's async support
213
```
214

215
### AST Transformation Example
216

217
```javascript
218
const recast = require("recast");
219
const regenerator = require("regenerator");
220

221
const sourceCode = `
222
function* range(start, end) {
223
  for (let i = start; i < end; i++) {
224
    yield i;
225
  }
226
}
227
`;
228

229
// Parse to AST
230
const ast = recast.parse(sourceCode);
231

232
// Transform generator functions
233
const transformedAst = regenerator.transform(ast, {
234
  includeRuntime: false
235
});
236

237
// Generate transformed code
238
const transformedCode = recast.print(transformedAst).code;
239
console.log(transformedCode);
240
```
241

242
### Browserify Integration
243

244
```javascript
245
// In your browserify build
246
const browserify = require("browserify");
247
const regenerator = require("regenerator");
248

249
browserify("app.js")
250
  .transform(regenerator)
251
  .bundle()
252
  .pipe(process.stdout);
253
```
254

255
### Runtime Path Access
256

257
```javascript
258
const regenerator = require("regenerator");
259
const fs = require("fs");
260

261
// Access runtime file path
262
console.log("Runtime path:", regenerator.runtime.path);
263

264
// Read runtime source
265
const runtimeSource = fs.readFileSync(regenerator.runtime.path, "utf8");
266
console.log("Runtime size:", runtimeSource.length);
267
```