0
# Scope Types
1

2
The scope type system provides comprehensive coverage of all JavaScript and TypeScript language constructs with specialized behavior for each scope type.
3

4
## Capabilities
5

6
### Scope Union Type
7

8
The main Scope type that represents all possible scope types in the system.
9

10
```typescript { .api }
11
type Scope = 
12
  | BlockScope
13
  | CatchScope  
14
  | ClassScope
15
  | ClassFieldInitializerScope
16
  | ClassStaticBlockScope
17
  | ConditionalTypeScope
18
  | ForScope
19
  | FunctionScope
20
  | FunctionExpressionNameScope
21
  | FunctionTypeScope
22
  | GlobalScope
23
  | MappedTypeScope
24
  | ModuleScope
25
  | SwitchScope
26
  | TSEnumScope
27
  | TSModuleScope
28
  | TypeScope
29
  | WithScope;
30
```
31

32
### Scope Type Enumeration
33

34
Enumeration of all scope type identifiers used throughout the system.
35

36
```typescript { .api }
37
enum ScopeType {
38
  block = "block",
39
  catch = "catch",
40
  class = "class", 
41
  classFieldInitializer = "class-field-initializer",
42
  classStaticBlock = "class-static-block",
43
  conditionalType = "conditionalType",
44
  for = "for",
45
  function = "function",
46
  functionExpressionName = "function-expression-name",
47
  functionType = "functionType",
48
  global = "global",
49
  mappedType = "mappedType",
50
  module = "module",
51
  switch = "switch",
52
  tsEnum = "tsEnum",
53
  tsModule = "tsModule",
54
  type = "type",
55
  with = "with"
56
}
57
```
58

59
### Base Scope Interface
60

61
All scopes extend from a common base that provides essential scope functionality.
62

63
```typescript { .api }
64
interface ScopeBase {
65
  /** Unique identifier for this scope instance */
66
  readonly $id: number;
67
  
68
  /** The AST node that created this scope */
69
  readonly block: TSESTree.Node;
70
  
71
  /** Child scopes contained within this scope */
72
  readonly childScopes: Scope[];
73
  
74
  /** Whether this scope is associated with a function expression name */
75
  functionExpressionScope: boolean;
76
  
77
  /** Whether this scope is in strict mode */
78
  isStrict: boolean;
79
  
80
  /** References to identifiers that cross scope boundaries */
81
  readonly references: Reference[];
82
  
83
  /** Set of variables defined directly in this scope */
84
  readonly set: Map<string, Variable>;
85
  
86
  /** References that could not be resolved in this scope */
87
  readonly through: Reference[];
88
  
89
  /** The type of this scope */
90
  readonly type: ScopeType;
91
  
92
  /** The parent scope containing this scope */
93
  readonly upper: Scope | null;
94
  
95
  /** All variables accessible in this scope */
96
  readonly variables: Variable[];
97
  
98
  /** The scope where var declarations are hoisted to */
99
  readonly variableScope: Scope;
100
}
101
```
102

103
## JavaScript Scope Types
104

105
### BlockScope
106

107
Scope created by block statements, including if/else blocks, try/catch blocks, and standalone block statements.
108

109
```typescript { .api }
110
class BlockScope extends ScopeBase {
111
  readonly type: ScopeType.block;
112
  readonly block: TSESTree.BlockStatement;
113
}
114
```
115

116
**Usage Examples:**
117

118
```typescript
119
// Block scopes are created for:
120
{
121
  let x = 1; // BlockScope variables
122
  const y = 2;
123
}
124

125
if (condition) {
126
  let z = 3; // Another BlockScope
127
}
128

129
try {
130
  let a = 4; // BlockScope within try
131
} catch (e) {
132
  // CatchScope (separate type)
133
}
134
```
135

136
### CatchScope
137

138
Scope created by catch clauses in try-catch statements.
139

140
```typescript { .api }
141
class CatchScope extends ScopeBase {
142
  readonly type: ScopeType.catch;
143
  readonly block: TSESTree.CatchClause;
144
}
145
```
146

147
### ForScope
148

149
Scope created by for loop initialization sections.
150

151
```typescript { .api }
152
class ForScope extends ScopeBase {
153
  readonly type: ScopeType.for;
154
  readonly block: TSESTree.ForStatement | TSESTree.ForInStatement | TSESTree.ForOfStatement;
155
}
156
```
157

158
**Usage Examples:**
159

160
```typescript
161
// ForScope created for loop variable declarations
162
for (let i = 0; i < 10; i++) {
163
  // 'i' is in ForScope
164
  // Loop body creates BlockScope
165
}
166

167
for (const item of items) {
168
  // 'item' is in ForScope  
169
}
170
```
171

172
### FunctionScope
173

174
Scope created by function declarations and expressions.
175

176
```typescript { .api }
177
class FunctionScope extends ScopeBase {
178
  readonly type: ScopeType.function;
179
  readonly block: TSESTree.Function;
180
  readonly isMethodDefinition: boolean;
181
}
182
```
183

184
### FunctionExpressionNameScope
185

186
Special scope for named function expressions.
187

188
```typescript { .api }
189
class FunctionExpressionNameScope extends ScopeBase {
190
  readonly type: ScopeType.functionExpressionName;
191
  readonly block: TSESTree.FunctionExpression;
192
}
193
```
194

195
**Usage Examples:**
196

197
```typescript
198
// FunctionExpressionNameScope for the name 'factorial'
199
const f = function factorial(n) {
200
  return n <= 1 ? 1 : n * factorial(n - 1); // 'factorial' accessible here
201
};
202
// 'factorial' not accessible here
203
```
204

205
### GlobalScope
206

207
The root scope containing global variables and functions.
208

209
```typescript { .api }
210
class GlobalScope extends ScopeBase {
211
  readonly type: ScopeType.global;
212
  readonly block: TSESTree.Program;
213
  
214
  /** Define an implicit global variable */
215
  defineImplicitVariable(name: string, options: ImplicitGlobalVariableOptions): void;
216
}
217
```
218

219
### ModuleScope
220

221
Scope created by ES modules (when sourceType is 'module').
222

223
```typescript { .api }
224
class ModuleScope extends ScopeBase {
225
  readonly type: ScopeType.module;
226
  readonly block: TSESTree.Program;
227
}
228
```
229

230
### SwitchScope
231

232
Scope created by switch statements.
233

234
```typescript { .api }
235
class SwitchScope extends ScopeBase {
236
  readonly type: ScopeType.switch;
237
  readonly block: TSESTree.SwitchStatement;
238
}
239
```
240

241
### WithScope
242

243
Scope created by with statements (deprecated feature).
244

245
```typescript { .api }
246
class WithScope extends ScopeBase {
247
  readonly type: ScopeType.with;
248
  readonly block: TSESTree.WithStatement;
249
}
250
```
251

252
## Class-Related Scope Types
253

254
### ClassScope
255

256
Scope created by class declarations and expressions.
257

258
```typescript { .api }
259
class ClassScope extends ScopeBase {
260
  readonly type: ScopeType.class;
261
  readonly block: TSESTree.ClassDeclaration | TSESTree.ClassExpression;
262
}
263
```
264

265
### ClassFieldInitializerScope
266

267
Scope created by class field initializers.
268

269
```typescript { .api }
270
class ClassFieldInitializerScope extends ScopeBase {
271
  readonly type: ScopeType.classFieldInitializer;
272
  readonly block: TSESTree.PropertyDefinition;
273
}
274
```
275

276
### ClassStaticBlockScope
277

278
Scope created by class static blocks.
279

280
```typescript { .api }
281
class ClassStaticBlockScope extends ScopeBase {
282
  readonly type: ScopeType.classStaticBlock;
283
  readonly block: TSESTree.StaticBlock;
284
}
285
```
286

287
**Usage Examples:**
288

289
```typescript
290
class MyClass {
291
  // ClassFieldInitializerScope
292
  field = this.getValue();
293
  
294
  static {
295
    // ClassStaticBlockScope
296
    console.log('Static block');
297
  }
298
  
299
  getValue() {
300
    // FunctionScope (method)
301
    return 42;
302
  }
303
}
304
```
305

306
## TypeScript-Specific Scope Types
307

308
### TypeScope
309

310
General scope for TypeScript type constructs.
311

312
```typescript { .api }
313
class TypeScope extends ScopeBase {
314
  readonly type: ScopeType.type;
315
  readonly block: TSESTree.TSTypeAnnotation | TSESTree.TSTypeParameter;
316
}
317
```
318

319
### FunctionTypeScope
320

321
Scope created by function type annotations.
322

323
```typescript { .api }
324
class FunctionTypeScope extends ScopeBase {
325
  readonly type: ScopeType.functionType;
326
  readonly block: TSESTree.TSFunctionType | TSESTree.TSConstructorType;
327
}
328
```
329

330
### ConditionalTypeScope
331

332
Scope created by conditional type expressions.
333

334
```typescript { .api }
335
class ConditionalTypeScope extends ScopeBase {
336
  readonly type: ScopeType.conditionalType;
337
  readonly block: TSESTree.TSConditionalType;
338
}
339
```
340

341
### MappedTypeScope
342

343
Scope created by mapped type expressions.
344

345
```typescript { .api }
346
class MappedTypeScope extends ScopeBase {
347
  readonly type: ScopeType.mappedType;
348
  readonly block: TSESTree.TSMappedType;
349
}
350
```
351

352
### TSEnumScope
353

354
Scope created by TypeScript enum declarations.
355

356
```typescript { .api }
357
class TSEnumScope extends ScopeBase {
358
  readonly type: ScopeType.tsEnum;
359
  readonly block: TSESTree.TSEnumDeclaration;
360
}
361
```
362

363
### TSModuleScope
364

365
Scope created by TypeScript module (namespace) declarations.
366

367
```typescript { .api }
368
class TSModuleScope extends ScopeBase {
369
  readonly type: ScopeType.tsModule;
370
  readonly block: TSESTree.TSModuleDeclaration;
371
}
372
```
373

374
**Usage Examples:**
375

376
```typescript
377
// TSEnumScope
378
enum Color {
379
  Red,   // Each member creates definitions
380
  Green,
381
  Blue
382
}
383

384
// TSModuleScope  
385
namespace Utilities {
386
  export function helper() {
387
    // FunctionScope within TSModuleScope
388
  }
389
}
390

391
// Conditional and mapped types
392
type IsString<T> = T extends string ? true : false; // ConditionalTypeScope
393
type Readonly<T> = { readonly [K in keyof T]: T[K] }; // MappedTypeScope
394

395
// Function type scope
396
type Handler = (event: Event) => void; // FunctionTypeScope
397
```
398

399
### Scope Navigation Patterns
400

401
```typescript
402
// Common patterns for working with scopes
403
function analyzeScope(scope: Scope) {
404
  console.log(`Scope type: ${scope.type}`);
405
  
406
  // Type-specific handling
407
  switch (scope.type) {
408
    case ScopeType.function:
409
      const funcScope = scope as FunctionScope;
410
      console.log(`Method definition: ${funcScope.isMethodDefinition}`);
411
      break;
412
      
413
    case ScopeType.class:
414
      const classScope = scope as ClassScope;
415
      console.log(`Class scope with ${classScope.variables.length} variables`);
416
      break;
417
      
418
    case ScopeType.tsEnum:
419
      const enumScope = scope as TSEnumScope;
420
      console.log(`Enum scope: ${enumScope.block.id?.name}`);
421
      break;
422
  }
423
  
424
  // Navigate hierarchy
425
  if (scope.upper) {
426
    console.log(`Parent: ${scope.upper.type}`);
427
  }
428
  
429
  scope.childScopes.forEach(child => {
430
    console.log(`Child: ${child.type}`);
431
  });
432
}
433
```