0
# REPL Environment
1

2
Interactive TypeScript REPL with evaluation context management and experimental top-level await support for development and debugging workflows.
3

4
## Capabilities
5

6
### Create REPL Service
7

8
Creates an interactive TypeScript REPL instance with custom evaluation capabilities.
9

10
```typescript { .api }
11
/**
12
 * Create a ts-node REPL instance
13
 * @param options - Configuration options for the REPL
14
 * @returns ReplService instance for interactive TypeScript evaluation
15
 */
16
function createRepl(options?: CreateReplOptions): ReplService;
17

18
interface CreateReplOptions {
19
  /** Service instance to use for compilation */
20
  service?: Service;
21
  /** REPL state management */
22
  state?: EvalState;
23
  /** Compile function override */
24
  compile?: (code: string, fileName: string, lineOffset?: number) => string;
25
  /** Evaluation function override */
26
  evalFile?: (code: string, fileName: string) => any;
27
  /** Node.js eval function override */
28
  nodeEval?: (code: string, filename: string) => any;
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { createRepl } from "ts-node";
36

37
// Create basic REPL
38
const repl = createRepl();
39
repl.start();
40

41
// Create REPL with custom service
42
import { create } from "ts-node";
43
const service = create({ transpileOnly: true });
44
const customRepl = createRepl({ service });
45
customRepl.start();
46
```
47

48
### REPL Service Interface
49

50
Main interface for interactive TypeScript evaluation and REPL management.
51

52
```typescript { .api }
53
interface ReplService {
54
  /**
55
   * Evaluate TypeScript code in REPL context
56
   * @param code - TypeScript code to evaluate
57
   * @param context - Evaluation context object
58
   * @returns Evaluation result
59
   */
60
  evalCode(code: string, context: object): any;
61
  
62
  /**
63
   * Start the interactive REPL session
64
   */
65
  start(): void;
66
  
67
  /**
68
   * Node.js eval compatibility function
69
   * @param code - Code to evaluate
70
   * @param context - Evaluation context
71
   * @param filename - Source filename for error reporting
72
   * @param callback - Result callback function
73
   */
74
  nodeEval(code: string, context: object, filename: string, callback: Function): void;
75
  
76
  /**
77
   * Set the REPL evaluation context
78
   * @param context - Object containing variables available in REPL
79
   */
80
  setContext(context: object): void;
81
  
82
  /**
83
   * Reset the REPL state and clear evaluation history
84
   */
85
  resetState(): void;
86
}
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
import { createRepl } from "ts-node";
93

94
const repl = createRepl();
95

96
// Set context variables
97
repl.setContext({
98
  myVariable: 42,
99
  myFunction: (x: number) => x * 2
100
});
101

102
// Evaluate TypeScript code
103
const result = repl.evalCode('myFunction(myVariable)', {});
104
console.log(result); // 84
105

106
// Start interactive session
107
repl.start();
108
```
109

110
### REPL State Management
111

112
State management for virtual files and evaluation context in the REPL environment.
113

114
```typescript { .api }
115
class EvalState {
116
  /** Current evaluation input */
117
  input: string = '';
118
  /** Compiled output */
119
  output: string = '';
120
  /** Current evaluation version */
121
  version: number = 0;
122
  /** File system state tracking */
123
  files: Map<string, string> = new Map();
124
  
125
  constructor();
126
  
127
  /**
128
   * Reset state to initial conditions
129
   */
130
  reset(): void;
131
  
132
  /**
133
   * Update input and increment version
134
   * @param input - New input code
135
   */
136
  updateInput(input: string): void;
137
}
138

139
/**
140
 * Create evaluation-aware file system host
141
 * @param state - EvalState instance to track virtual files
142
 * @param composeWith - Optional host to compose with
143
 * @returns Host functions aware of virtual files
144
 */
145
function createEvalAwarePartialHost(
146
  state: EvalState, 
147
  composeWith?: EvalAwarePartialHost
148
): EvalAwarePartialHost;
149

150
interface EvalAwarePartialHost {
151
  fileExists(fileName: string): boolean;
152
  readFile(fileName: string): string | undefined;
153
  getDirectories?(path: string): string[];
154
}
155
```
156

157
**Usage Examples:**
158

159
```typescript
160
import { createRepl, EvalState, createEvalAwarePartialHost } from "ts-node";
161

162
// Create custom REPL with state management
163
const state = new EvalState();
164
const host = createEvalAwarePartialHost(state);
165

166
const repl = createRepl({
167
  state,
168
  evalFile: (code, fileName) => {
169
    // Custom evaluation logic
170
    state.updateInput(code);
171
    return eval(code);
172
  }
173
});
174

175
// Track evaluation history
176
console.log(`Evaluation version: ${state.version}`);
177
console.log(`Current input: ${state.input}`);
178
```
179

180
### REPL Constants
181

182
Predefined constants for REPL filename handling and context management.
183

184
```typescript { .api }
185
/** Virtual filename for REPL evaluations */
186
const REPL_FILENAME: "[eval].ts";
187

188
/** Virtual name for REPL context */  
189
const REPL_NAME: "[eval]";
190

191
/** Virtual filename for stdin input */
192
const STDIN_FILENAME: "[stdin].ts";
193

194
/** Virtual name for stdin context */
195
const STDIN_NAME: "[stdin]";
196

197
/** Virtual filename for eval context */
198
const EVAL_FILENAME: "[eval].ts";
199

200
/** Virtual name for eval context */
201
const EVAL_NAME: "[eval]";
202
```
203

204
### Context Setup
205

206
Utility functions for setting up REPL evaluation contexts.
207

208
```typescript { .api }
209
/**
210
 * Setup context for REPL evaluation
211
 * @param context - Context object to populate
212
 * @param module - Module instance for require/import context
213
 * @param filenameAndDirname - Type of filename context to create
214
 */
215
function setupContext(
216
  context: any, 
217
  module: NodeJS.Module, 
218
  filenameAndDirname: 'eval' | 'stdin' | null
219
): void;
220
```
221

222
**Usage Examples:**
223

224
```typescript
225
import { createRepl, setupContext, REPL_FILENAME } from "ts-node";
226
import { Module } from "module";
227

228
const repl = createRepl();
229

230
// Setup custom context
231
const context = {};
232
const module = new Module(REPL_FILENAME);
233
setupContext(context, module, 'eval');
234

235
// Now context has __filename, __dirname, require, etc.
236
console.log(context.__filename); // "[eval].ts"
237
```
238

239
## Advanced REPL Usage
240

241
### Top-level Await Support
242

243
```typescript
244
import { createRepl } from "ts-node";
245

246
// Create REPL with experimental await support
247
const repl = createRepl({
248
  service: create({
249
    experimentalReplAwait: true,
250
    compilerOptions: {
251
      target: "es2018", // Required for top-level await
252
    }
253
  })
254
});
255

256
// Now you can use await in REPL
257
// > const data = await fetch('https://api.example.com');
258
// > console.log(data);
259
```
260

261
### Custom Evaluation Logic
262

263
```typescript
264
import { createRepl, EvalState } from "ts-node";
265

266
const state = new EvalState();
267

268
const repl = createRepl({
269
  state,
270
  evalFile: (code: string, fileName: string) => {
271
    console.log(`Evaluating: ${code}`);
272
    
273
    // Add custom globals
274
    const globals = {
275
      console,
276
      process,
277
      Buffer,
278
      // Add your custom utilities
279
      helper: (x: any) => JSON.stringify(x, null, 2)
280
    };
281
    
282
    // Create evaluation context
283
    const context = { ...globals };
284
    return eval(`(function() { ${code} }).call(this)`);
285
  }
286
});
287

288
repl.start();
289
```
290

291
### Integration with Testing
292

293
```typescript
294
import { createRepl } from "ts-node";
295
import { create } from "ts-node";
296

297
// Create REPL for testing TypeScript code
298
const testService = create({
299
  transpileOnly: true,
300
  compilerOptions: {
301
    target: "es2020",
302
    types: ["node", "jest"] // Include test type definitions
303
  }
304
});
305

306
const testRepl = createRepl({ service: testService });
307

308
// Set testing context
309
testRepl.setContext({
310
  describe: global.describe,
311
  it: global.it,
312
  expect: global.expect,
313
  beforeEach: global.beforeEach,
314
  afterEach: global.afterEach
315
});
316

317
testRepl.start();
318
```