0
# Language Features
1

2
Middleware interfaces for all Language Server Protocol features including completion, hover, diagnostics, and code actions.
3

4
## Capabilities
5

6
### Core Middleware Interface
7

8
Central middleware interface combining all LSP feature middleware.
9

10
```typescript { .api }
11
/**
12
 * Main middleware interface combining all LSP feature middlewares
13
 */
14
interface Middleware {
15
  /** Completion feature middleware */
16
  completion?: CompletionMiddleware;
17
  /** Hover feature middleware */
18
  hover?: HoverMiddleware;
19
  /** Signature help feature middleware */
20
  signatureHelp?: SignatureHelpMiddleware;
21
  /** Go to definition feature middleware */
22
  definition?: DefinitionMiddleware;
23
  /** Find references feature middleware */
24
  references?: ReferencesMiddleware;
25
  /** Document highlight feature middleware */
26
  documentHighlight?: DocumentHighlightMiddleware;
27
  /** Document symbol feature middleware */
28
  documentSymbol?: DocumentSymbolMiddleware;
29
  /** Code action feature middleware */
30
  codeAction?: CodeActionMiddleware;
31
  /** Code lens feature middleware */
32
  codeLens?: CodeLensMiddleware;
33
  /** Document formatting feature middleware */
34
  formatting?: FormattingMiddleware;
35
  /** Rename feature middleware */
36
  rename?: RenameMiddleware;
37
  /** Document link feature middleware */
38
  documentLink?: DocumentLinkMiddleware;
39
  /** Execute command feature middleware */
40
  executeCommand?: ExecuteCommandMiddleware;
41
  /** Workspace symbol feature middleware */
42
  workspaceSymbol?: WorkspaceSymbolMiddleware;
43
  /** Text document synchronization middleware */
44
  textDocumentSync?: TextDocumentSynchronizationMiddleware;
45
  /** Configuration feature middleware */
46
  configuration?: ConfigurationMiddleware;
47
  /** Workspace folder feature middleware */
48
  workspaceFolder?: WorkspaceFolderMiddleware;
49
  /** Diagnostic feature middleware */
50
  diagnostic?: DiagnosticProviderMiddleware;
51
  /** Semantic tokens feature middleware */
52
  semanticTokens?: SemanticTokensMiddleware;
53
  /** Call hierarchy feature middleware */
54
  callHierarchy?: CallHierarchyMiddleware;
55
  /** Type hierarchy feature middleware */
56
  typeHierarchy?: TypeHierarchyMiddleware;
57
  /** Inlay hints feature middleware */
58
  inlayHints?: InlayHintsMiddleware;
59
  /** Inline values feature middleware */
60
  inlineValue?: InlineValueMiddleware;
61
  /** Folding range feature middleware */
62
  foldingRange?: FoldingRangeProviderMiddleware;
63
  /** Linked editing range feature middleware */
64
  linkedEditingRange?: LinkedEditingRangeMiddleware;
65
  /** Selection range feature middleware */
66
  selectionRange?: SelectionRangeProviderMiddleware;
67
  /** Document color feature middleware */
68
  colorProvider?: ColorProviderMiddleware;
69
  /** Declaration feature middleware */
70
  declaration?: DeclarationMiddleware;
71
  /** Implementation feature middleware */
72
  implementation?: ImplementationMiddleware;
73
  /** Type definition feature middleware */
74
  typeDefinition?: TypeDefinitionMiddleware;
75
  /** File operations feature middleware */
76
  fileOperations?: FileOperationsMiddleware;
77
  /** Notebook document feature middleware */
78
  notebookDocument?: NotebookDocumentMiddleware;
79
}
80
```
81

82
### Code Intelligence Features
83

84
#### Completion
85

86
Auto-completion and IntelliSense functionality.
87

88
```typescript { .api }
89
/**
90
 * Middleware for completion features
91
 */
92
interface CompletionMiddleware {
93
  /** Customize completion item provision */
94
  provideCompletionItem?: ProvideCompletionItemsSignature;
95
  /** Customize completion item resolution */
96
  resolveCompletionItem?: ResolveCompletionItemSignature;
97
}
98

99
/**
100
 * Signature for providing completion items
101
 */
102
type ProvideCompletionItemsSignature = (
103
  document: TextDocument,
104
  position: Position,
105
  context: CompletionContext,
106
  token: CancellationToken,
107
  next: ProvideCompletionItemsSignature
108
) => ProviderResult<CompletionItem[] | CompletionList>;
109

110
/**
111
 * Signature for resolving completion items
112
 */
113
type ResolveCompletionItemSignature = (
114
  item: CompletionItem,
115
  token: CancellationToken,
116
  next: ResolveCompletionItemSignature
117
) => ProviderResult<CompletionItem>;
118
```
119

120
#### Hover Information
121

122
Hover documentation and type information.
123

124
```typescript { .api }
125
/**
126
 * Middleware for hover features
127
 */
128
interface HoverMiddleware {
129
  /** Customize hover information provision */
130
  provideHover?: ProvideHoverSignature;
131
}
132

133
/**
134
 * Signature for providing hover information
135
 */
136
type ProvideHoverSignature = (
137
  document: TextDocument,
138
  position: Position,
139
  token: CancellationToken,
140
  next: ProvideHoverSignature
141
) => ProviderResult<Hover>;
142
```
143

144
#### Signature Help
145

146
Function signature assistance during typing.
147

148
```typescript { .api }
149
/**
150
 * Middleware for signature help features
151
 */
152
interface SignatureHelpMiddleware {
153
  /** Customize signature help provision */
154
  provideSignatureHelp?: ProvideSignatureHelpSignature;
155
}
156

157
/**
158
 * Signature for providing signature help
159
 */
160
type ProvideSignatureHelpSignature = (
161
  document: TextDocument,
162
  position: Position,
163
  context: SignatureHelpContext,
164
  token: CancellationToken,
165
  next: ProvideSignatureHelpSignature
166
) => ProviderResult<SignatureHelp>;
167
```
168

169
### Navigation Features
170

171
#### Go to Definition
172

173
Navigate to symbol definitions.
174

175
```typescript { .api }
176
/**
177
 * Middleware for definition features
178
 */
179
interface DefinitionMiddleware {
180
  /** Customize definition provision */
181
  provideDefinition?: ProvideDefinitionSignature;
182
}
183

184
/**
185
 * Signature for providing definitions
186
 */
187
type ProvideDefinitionSignature = (
188
  document: TextDocument,
189
  position: Position,
190
  token: CancellationToken,
191
  next: ProvideDefinitionSignature
192
) => ProviderResult<Definition | DefinitionLink[]>;
193
```
194

195
#### Find References
196

197
Find all references to a symbol.
198

199
```typescript { .api }
200
/**
201
 * Middleware for references features
202
 */
203
interface ReferencesMiddleware {
204
  /** Customize references provision */
205
  provideReferences?: ProvideReferencesSignature;
206
}
207

208
/**
209
 * Signature for providing references
210
 */
211
type ProvideReferencesSignature = (
212
  document: TextDocument,
213
  position: Position,
214
  context: ReferenceContext,
215
  token: CancellationToken,
216
  next: ProvideReferencesSignature
217
) => ProviderResult<Location[]>;
218
```
219

220
#### Document Highlights
221

222
Highlight related symbols in a document.
223

224
```typescript { .api }
225
/**
226
 * Middleware for document highlight features
227
 */
228
interface DocumentHighlightMiddleware {
229
  /** Customize document highlights provision */
230
  provideDocumentHighlights?: ProvideDocumentHighlightsSignature;
231
}
232

233
/**
234
 * Signature for providing document highlights
235
 */
236
type ProvideDocumentHighlightsSignature = (
237
  document: TextDocument,
238
  position: Position,
239
  token: CancellationToken,
240
  next: ProvideDocumentHighlightsSignature
241
) => ProviderResult<DocumentHighlight[]>;
242
```
243

244
### Code Actions and Refactoring
245

246
#### Code Actions
247

248
Quick fixes and refactoring actions.
249

250
```typescript { .api }
251
/**
252
 * Middleware for code action features
253
 */
254
interface CodeActionMiddleware {
255
  /** Customize code actions provision */
256
  provideCodeActions?: ProvideCodeActionsSignature;
257
  /** Customize code action resolution */
258
  resolveCodeAction?: ResolveCodeActionSignature;
259
}
260

261
/**
262
 * Signature for providing code actions
263
 */
264
type ProvideCodeActionsSignature = (
265
  document: TextDocument,
266
  range: Range,
267
  context: CodeActionContext,
268
  token: CancellationToken,
269
  next: ProvideCodeActionsSignature
270
) => ProviderResult<(Command | CodeAction)[]>;
271

272
/**
273
 * Signature for resolving code actions
274
 */
275
type ResolveCodeActionSignature = (
276
  item: CodeAction,
277
  token: CancellationToken,
278
  next: ResolveCodeActionSignature
279
) => ProviderResult<CodeAction>;
280
```
281

282
#### Rename
283

284
Symbol renaming with preview.
285

286
```typescript { .api }
287
/**
288
 * Middleware for rename features
289
 */
290
interface RenameMiddleware {
291
  /** Customize rename preparation */
292
  prepareRename?: PrepareRenameSignature;
293
  /** Customize rename edits provision */
294
  provideRenameEdits?: ProvideRenameEditsSignature;
295
}
296

297
/**
298
 * Signature for preparing rename
299
 */
300
type PrepareRenameSignature = (
301
  document: TextDocument,
302
  position: Position,
303
  token: CancellationToken,
304
  next: PrepareRenameSignature
305
) => ProviderResult<Range | { range: Range; placeholder: string }>;
306

307
/**
308
 * Signature for providing rename edits
309
 */
310
type ProvideRenameEditsSignature = (
311
  document: TextDocument,
312
  position: Position,
313
  newName: string,
314
  token: CancellationToken,
315
  next: ProvideRenameEditsSignature
316
) => ProviderResult<WorkspaceEdit>;
317
```
318

319
### Document Features
320

321
#### Document Symbols
322

323
Outline and symbol navigation within documents.
324

325
```typescript { .api }
326
/**
327
 * Middleware for document symbol features
328
 */
329
interface DocumentSymbolMiddleware {
330
  /** Customize document symbols provision */
331
  provideDocumentSymbols?: ProvideDocumentSymbolsSignature;
332
}
333

334
/**
335
 * Signature for providing document symbols
336
 */
337
type ProvideDocumentSymbolsSignature = (
338
  document: TextDocument,
339
  token: CancellationToken,
340
  next: ProvideDocumentSymbolsSignature
341
) => ProviderResult<SymbolInformation[] | DocumentSymbol[]>;
342
```
343

344
#### Formatting
345

346
Code formatting and style correction.
347

348
```typescript { .api }
349
/**
350
 * Middleware for formatting features
351
 */
352
interface FormattingMiddleware {
353
  /** Customize document formatting */
354
  provideDocumentFormattingEdits?: ProvideDocumentFormattingEditsSignature;
355
  /** Customize range formatting */
356
  provideDocumentRangeFormattingEdits?: ProvideDocumentRangeFormattingEditsSignature;
357
  /** Customize on-type formatting */
358
  provideOnTypeFormattingEdits?: ProvideOnTypeFormattingEditsSignature;
359
}
360

361
/**
362
 * Signature for providing document formatting edits
363
 */
364
type ProvideDocumentFormattingEditsSignature = (
365
  document: TextDocument,
366
  options: FormattingOptions,
367
  token: CancellationToken,
368
  next: ProvideDocumentFormattingEditsSignature
369
) => ProviderResult<TextEdit[]>;
370

371
/**
372
 * Signature for providing range formatting edits
373
 */
374
type ProvideDocumentRangeFormattingEditsSignature = (
375
  document: TextDocument,
376
  range: Range,
377
  options: FormattingOptions,
378
  token: CancellationToken,
379
  next: ProvideDocumentRangeFormattingEditsSignature
380
) => ProviderResult<TextEdit[]>;
381

382
/**
383
 * Signature for providing on-type formatting edits
384
 */
385
type ProvideOnTypeFormattingEditsSignature = (
386
  document: TextDocument,
387
  position: Position,
388
  ch: string,
389
  options: FormattingOptions,
390
  token: CancellationToken,
391
  next: ProvideOnTypeFormattingEditsSignature
392
) => ProviderResult<TextEdit[]>;
393
```
394

395
### Advanced Features
396

397
#### Diagnostics
398

399
Error, warning, and information reporting.
400

401
```typescript { .api }
402
/**
403
 * Middleware for diagnostic features
404
 */
405
interface DiagnosticProviderMiddleware {
406
  /** Customize diagnostic provision */
407
  provideDiagnostics?: ProvideDiagnosticSignature;
408
  /** Customize workspace diagnostic provision */
409
  provideWorkspaceDiagnostics?: ProvideWorkspaceDiagnosticSignature;
410
}
411

412
/**
413
 * Signature for providing diagnostics
414
 */
415
type ProvideDiagnosticSignature = (
416
  document: TextDocument | Uri,
417
  previousResultId: string | undefined,
418
  token: CancellationToken,
419
  next: ProvideDiagnosticSignature
420
) => ProviderResult<DocumentDiagnosticReport>;
421

422
/**
423
 * Signature for providing workspace diagnostics
424
 */
425
type ProvideWorkspaceDiagnosticSignature = (
426
  resultIds: PreviousResultId[],
427
  token: CancellationToken,
428
  resultReporter: ResultReporter,
429
  next: ProvideWorkspaceDiagnosticSignature
430
) => ProviderResult<WorkspaceDiagnosticReport>;
431

432
/**
433
 * Diagnostic pull mode configuration
434
 */
435
enum DiagnosticPullMode {
436
  /** Pull diagnostics on open, change, save, and close events */
437
  onType = 'onType',
438
  /** Pull diagnostics only on save events */
439
  onSave = 'onSave'
440
}
441

442
/**
443
 * Options for diagnostic pull configuration
444
 */
445
type DiagnosticPullOptions = {
446
  /** Whether to pull diagnostics on open */
447
  onOpen?: boolean;
448
  /** Whether to pull diagnostics on change */
449
  onChange?: boolean;
450
  /** Whether to pull diagnostics on save */  
451
  onSave?: boolean;
452
  /** Whether to pull diagnostics on close */
453
  onClose?: boolean;
454
  /** Pull mode configuration */
455
  mode?: DiagnosticPullMode;
456
};
457

458
/**
459
 * Provider shape for diagnostic features
460
 */
461
type DiagnosticProviderShape = {
462
  /** Provide document diagnostics */
463
  provideDiagnostics: ProvideDiagnosticSignature;
464
  /** Provide workspace diagnostics */
465
  provideWorkspaceDiagnostics?: ProvideWorkspaceDiagnosticSignature;
466
};
467

468
/**
469
 * Provider shape for code lens features
470
 */
471
type CodeLensProviderShape = {
472
  /** Provide code lenses for a document */
473
  provideCodeLenses: ProvideCodeLensesSignature;
474
  /** Resolve a code lens with additional information */
475
  resolveCodeLens?: ResolveCodeLensSignature;
476
};
477

478
/**
479
 * Provider shape for semantic tokens features
480
 */
481
type SemanticTokensProviderShape = {
482
  /** Provide semantic tokens for entire document */
483
  provideDocumentSemanticTokens: DocumentSemanticsTokensSignature;
484
  /** Provide semantic token edits */
485
  provideDocumentSemanticTokensEdits?: DocumentSemanticsTokensEditsSignature;
486
  /** Provide semantic tokens for document range */
487
  provideDocumentRangeSemanticTokens?: DocumentRangeSemanticTokensSignature;
488
};
489

490
/**
491
 * Provider shape for inlay hints features
492
 */
493
type InlayHintsProviderShape = {
494
  /** Provide inlay hints for a document range */
495
  provideInlayHints: ProvideInlayHintsSignature;
496
  /** Resolve an inlay hint with additional information */
497
  resolveInlayHint?: ResolveInlayHintSignature;
498
};
499

500
/**
501
 * Provider shape for inline values features  
502
 */
503
type InlineValueProviderShape = {
504
  /** Provide inline values for a document range */
505
  provideInlineValues: ProvideInlineValuesSignature;
506
};
507
```
508

509
#### Semantic Tokens
510

511
Semantic highlighting information.
512

513
```typescript { .api }
514
/**
515
 * Middleware for semantic tokens features
516
 */
517
interface SemanticTokensMiddleware {
518
  /** Customize document semantic tokens provision */
519
  provideDocumentSemanticTokens?: DocumentSemanticsTokensSignature;
520
  /** Customize document semantic tokens edits provision */
521
  provideDocumentSemanticTokensEdits?: DocumentSemanticsTokensEditsSignature;
522
  /** Customize range semantic tokens provision */
523
  provideDocumentRangeSemanticTokens?: DocumentRangeSemanticTokensSignature;
524
}
525

526
/**
527
 * Signature for providing document semantic tokens
528
 */
529
type DocumentSemanticsTokensSignature = (
530
  document: TextDocument,
531
  token: CancellationToken,
532
  next: DocumentSemanticsTokensSignature
533
) => ProviderResult<SemanticTokens>;
534

535
/**
536
 * Signature for providing document semantic tokens edits
537
 */
538
type DocumentSemanticsTokensEditsSignature = (
539
  document: TextDocument,
540
  previousResultId: string,
541
  token: CancellationToken,
542
  next: DocumentSemanticsTokensEditsSignature
543
) => ProviderResult<SemanticTokensEdits | SemanticTokens>;
544

545
/**
546
 * Signature for providing range semantic tokens
547
 */
548
type DocumentRangeSemanticTokensSignature = (
549
  document: TextDocument,
550
  range: Range,
551
  token: CancellationToken,
552
  next: DocumentRangeSemanticTokensSignature
553
) => ProviderResult<SemanticTokens>;
554
```
555

556
### Text Document Synchronization
557

558
Document change tracking and synchronization.
559

560
```typescript { .api }
561
/**
562
 * Middleware for text document synchronization
563
 */
564
interface TextDocumentSynchronizationMiddleware {
565
  /** Customize document open handling */
566
  didOpen?: NextSignature<TextDocument, Promise<void>>;
567
  /** Customize document change handling */
568
  didChange?: NextSignature<TextDocumentChangeEvent, Promise<void>>;
569
  /** Customize document will save handling */
570
  willSave?: NextSignature<TextDocumentWillSaveEvent, Promise<void>>;
571
  /** Customize document will save wait until handling */
572
  willSaveWaitUntil?: NextSignature<TextDocumentWillSaveEvent, Thenable<TextEdit[]>>;
573
  /** Customize document save handling */
574
  didSave?: NextSignature<TextDocument, Promise<void>>;
575
  /** Customize document close handling */
576
  didClose?: NextSignature<TextDocument, Promise<void>>;
577
}
578

579
/**
580
 * Generic next signature for middleware chaining
581
 */
582
type NextSignature<P, R> = (data: P, next: (data: P) => R) => R;
583
```
584

585
### Notebook Document Features
586

587
Middleware and types for Jupyter notebook document support.
588

589
```typescript { .api }
590
/**
591
 * Middleware for notebook document features
592
 */
593
interface NotebookDocumentMiddleware {
594
  /** Customize notebook document synchronization */
595
  didOpen?: NextSignature<NotebookDocument, Promise<void>>;
596
  /** Customize notebook document change handling */
597
  didChange?: NextSignature<VNotebookDocumentChangeEvent, Promise<void>>;
598
  /** Customize notebook document save handling */
599
  didSave?: NextSignature<NotebookDocument, Promise<void>>;
600
  /** Customize notebook document close handling */
601
  didClose?: NextSignature<NotebookDocument, Promise<void>>;
602
}
603

604
/**
605
 * Configuration options for notebook document synchronization
606
 */
607
interface NotebookDocumentOptions {
608
  /** Notebook selector to match notebook types */
609
  notebookSelector: NotebookSelector[];
610
  /** Cell selector to match cell types within notebooks */
611
  cellSelector?: DocumentSelector;
612
  /** Whether to save the notebook document */
613
  save?: boolean;
614
}
615

616
/**
617
 * Event representing changes to a notebook document
618
 */
619
type VNotebookDocumentChangeEvent = {
620
  /** The notebook document that changed */
621
  notebook: NotebookDocument;
622
  /** Metadata changes */
623
  metadata?: { old: { [key: string]: any }; new: { [key: string]: any } };
624
  /** Cell changes */
625
  cells?: NotebookDocumentCellChange;
626
};
627

628
/**
629
 * Selector for matching notebook documents
630
 */
631
interface NotebookSelector {
632
  /** Notebook type pattern (e.g., 'jupyter-notebook') */
633
  notebook: string | { pattern: string };
634
  /** Language pattern for cells */
635
  language?: string | { pattern: string };
636
}
637

638
/**
639
 * Changes to notebook cells
640
 */
641
interface NotebookDocumentCellChange {
642
  /** Array of cell changes */
643
  structure?: {
644
    /** Cells that were added */
645
    array: NotebookDocumentCellChangeStructure;
646
    /** Whether cells were added or removed */
647
    didOpen?: NotebookCell[];
648
    didClose?: NotebookCell[];
649
  };
650
  /** Content changes to existing cells */
651
  data?: NotebookCell[];
652
  /** Text changes to cell content */
653
  textContent?: {
654
    document: TextDocument;
655
    changes: TextDocumentContentChangeEvent[];
656
  }[];
657
}
658
```
659

660
**Usage Examples:**
661

662

663
Basic completion middleware:
664

665
```typescript
666
const clientOptions: LanguageClientOptions = {
667
  middleware: {
668
    completion: {
669
      provideCompletionItem: (document, position, context, token, next) => {
670
        // Add custom completion items
671
        const customItems: CompletionItem[] = [
672
          { label: 'custom-snippet', kind: CompletionItemKind.Snippet }
673
        ];
674
        
675
        // Call next to get server completions
676
        const serverItems = next(document, position, context, token);
677
        
678
        // Combine custom and server items
679
        return Promise.resolve(serverItems).then(items => {
680
          if (Array.isArray(items)) {
681
            return [...customItems, ...items];
682
          }
683
          return { isIncomplete: false, items: [...customItems, ...(items?.items || [])] };
684
        });
685
      }
686
    }
687
  }
688
};
689
```
690

691
Error handling with diagnostics:
692

693
```typescript
694
const clientOptions: LanguageClientOptions = {
695
  middleware: {
696
    diagnostic: {
697
      provideDiagnostics: (document, previousResultId, token, next) => {
698
        // Custom diagnostic processing
699
        console.log(`Providing diagnostics for: ${document.uri}`);
700
        return next(document, previousResultId, token);
701
      }
702
    }
703
  }
704
};
705
```
706

707
Notebook document middleware:
708

709
```typescript
710
const clientOptions: LanguageClientOptions = {
711
  middleware: {
712
    notebookDocument: {
713
      didOpen: (notebook, next) => {
714
        console.log(`Notebook opened: ${notebook.uri}`);
715
        return next(notebook);
716
      },
717
      didChange: (changeEvent, next) => {
718
        console.log(`Notebook changed: ${changeEvent.notebook.uri}`);
719
        return next(changeEvent);
720
      }
721
    }
722
  }
723
};
724
```