0
# Core Service Management
1

2
Core functionality for creating and registering TypeScript compilation services. This is the primary API for programmatic usage of ts-node.
3

4
## Capabilities
5

6
### Register Function
7

8
Creates and registers a TypeScript compiler instance globally on the Node.js runtime.
9

10
```typescript { .api }
11
/**
12
 * Create a new TypeScript compiler instance and register it onto node.js
13
 * @param opts - Configuration options for the service
14
 * @returns Service instance for compilation and management
15
 */
16
function register(opts?: RegisterOptions): Service;
17

18
/**
19
 * Register an existing TypeScript compiler service onto node.js
20
 * @param service - Pre-existing Service instance to register
21
 * @returns The same Service instance
22
 */
23
function register(service: Service): Service;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { register } from "ts-node";
30

31
// Basic registration with default options
32
const service = register();
33

34
// Registration with custom options
35
const service = register({
36
  transpileOnly: true,
37
  compilerOptions: {
38
    target: "es2020",
39
    module: "commonjs",
40
  },
41
  ignore: [/node_modules/],
42
});
43

44
// Register an existing service
45
const existingService = create({ transpileOnly: true });
46
register(existingService);
47
```
48

49
### Create Function
50

51
Creates a TypeScript compiler instance without registering it globally.
52

53
```typescript { .api }
54
/**
55
 * Create TypeScript compiler instance without global registration
56
 * @param rawOptions - Configuration options for the service
57
 * @returns Service instance for compilation
58
 */
59
function create(rawOptions?: CreateOptions): Service;
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
import { create } from "ts-node";
66

67
// Create service for manual compilation
68
const service = create({
69
  transpileOnly: true,
70
  compilerOptions: {
71
    target: "es2018",
72
    strict: true,
73
  },
74
});
75

76
// Compile TypeScript code manually
77
const result = service.compile('const x: number = 42;', 'test.ts');
78
console.log(result); // Compiled JavaScript
79
```
80

81
### Service Interface
82

83
The primary interface for TypeScript compilation and management operations.
84

85
```typescript { .api }
86
interface Service {
87
  /** TypeScript compiler instance */
88
  ts: TSCommon;
89
  /** Parsed TypeScript configuration */
90
  config: _ts.ParsedCommandLine;
91
  /** Service configuration options */
92
  options: RegisterOptions;
93
  
94
  /**
95
   * Enable or disable the service
96
   * @param enabled - Whether to enable the service
97
   * @returns Current enabled state
98
   */
99
  enabled(enabled?: boolean): boolean;
100
  
101
  /**
102
   * Check if a filename should be ignored by ts-node
103
   * @param fileName - File path to check
104
   * @returns True if file should be ignored
105
   */
106
  ignored(fileName: string): boolean;
107
  
108
  /**
109
   * Compile TypeScript code to JavaScript
110
   * @param code - TypeScript source code
111
   * @param fileName - Source file name for error reporting
112
   * @param lineOffset - Line number offset for error reporting
113
   * @returns Compiled JavaScript code
114
   */
115
  compile(code: string, fileName: string, lineOffset?: number): string;
116
  
117
  /**
118
   * Get type information at a specific position in TypeScript code
119
   * @param code - TypeScript source code
120
   * @param fileName - Source file name
121
   * @param position - Character position in code
122
   * @returns Type information object
123
   */
124
  getTypeInfo(code: string, fileName: string, position: number): TypeInfo;
125
  
126
  // Internal properties and methods
127
  /** @internal Service brand for type checking */
128
  [TS_NODE_SERVICE_BRAND]: true;
129
  /** @internal TypeScript compiler path */
130
  compilerPath: string;
131
  /** @internal TypeScript config file path */
132
  configFilePath: string | undefined;
133
  /** @internal Module type classifier */
134
  moduleTypeClassifier: ModuleTypeClassifier;
135
  /** @internal Whether REPL await is supported */
136
  readonly shouldReplAwait: boolean;
137
  /** @internal Whether transpile-only mode is enabled */
138
  transpileOnly: boolean;
139
  /** @internal Project-local resolve helper */
140
  projectLocalResolveHelper: ProjectLocalResolveHelper;
141
  /** @internal File extensions configuration */
142
  extensions: Extensions;
143
  
144
  /** @internal Add diagnostic filter */
145
  addDiagnosticFilter(filter: DiagnosticFilter): void;
146
  /** @internal Install source map support */
147
  installSourceMapSupport(): void;
148
  /** @internal Enable experimental ESM loader interop */
149
  enableExperimentalEsmLoaderInterop(): void;
150
  /** @internal Get Node.js ESM resolver */
151
  getNodeEsmResolver(): any;
152
  /** @internal Get Node.js ESM format detector */
153
  getNodeEsmGetFormat(): any;
154
  /** @internal Get Node.js CJS loader */
155
  getNodeCjsLoader(): any;
156
}
157

158
interface TypeInfo {
159
  /** Type name */
160
  name: string;
161
  /** Documentation comment */
162
  comment: string;
163
}
164
```
165

166
**Usage Examples:**
167

168
```typescript
169
import { create } from "ts-node";
170

171
const service = create({ transpileOnly: true });
172

173
// Check if service is enabled
174
console.log(service.enabled()); // true
175

176
// Check if a file should be ignored
177
console.log(service.ignored('node_modules/some-package/index.ts')); // true
178
console.log(service.ignored('src/app.ts')); // false
179

180
// Compile TypeScript code
181
const jsCode = service.compile(
182
  'const message: string = "Hello, World!";',
183
  'example.ts'
184
);
185

186
// Get type information
187
const typeInfo = service.getTypeInfo(
188
  'const num: number = 42;',
189
  'example.ts',
190
  6 // Position of 'num'
191
);
192
console.log(typeInfo.name); // "number"
193
```
194

195
### Global Registry
196

197
Access to the globally registered ts-node instance.
198

199
```typescript { .api }
200
/** Symbol for accessing registered instance on process object */
201
const REGISTER_INSTANCE: symbol;
202

203
// Global process interface extension
204
declare global {
205
  namespace NodeJS {
206
    interface Process {
207
      [REGISTER_INSTANCE]?: Service;
208
    }
209
  }
210
}
211
```
212

213
**Usage Examples:**
214

215
```typescript
216
import { register, REGISTER_INSTANCE } from "ts-node";
217

218
// Register a service
219
register({ transpileOnly: true });
220

221
// Access the global service
222
const globalService = process[REGISTER_INSTANCE];
223
if (globalService) {
224
  console.log('ts-node is registered globally');
225
  const result = globalService.compile('const x = 1;', 'test.ts');
226
}
227
```
228

229
### Error Handling
230

231
TypeScript compilation errors and diagnostics.
232

233
```typescript { .api }
234
class TSError extends Error {
235
  name: 'TSError';
236
  /** Formatted diagnostic text */
237
  diagnosticText: string;
238
  /** Raw TypeScript diagnostics */
239
  diagnostics: ReadonlyArray<Diagnostic>;
240
  /** Diagnostic error codes */
241
  diagnosticCodes: number[];
242
  
243
  constructor(
244
    diagnosticText: string,
245
    diagnosticCodes: number[],
246
    diagnostics?: ReadonlyArray<Diagnostic>
247
  );
248
}
249
```
250

251
**Usage Examples:**
252

253
```typescript
254
import { create, TSError } from "ts-node";
255

256
const service = create({ typeCheck: true });
257

258
try {
259
  // This will throw TSError due to type mismatch
260
  service.compile('const x: string = 42;', 'error.ts');
261
} catch (error) {
262
  if (error instanceof TSError) {
263
    console.log('TypeScript Error:', error.diagnosticText);
264
    console.log('Error Codes:', error.diagnosticCodes);
265
    console.log('Raw Diagnostics:', error.diagnostics);
266
  }
267
}
268
```