0
# Document Management
1

2
Text document lifecycle management and synchronization between client and server. The document management system handles document open, change, save, and close events with automatic synchronization.
3

4
## Capabilities
5

6
### Text Documents Manager
7

8
A manager for simple text documents that automatically synchronizes document state between client and server.
9

10
```typescript { .api }
11
/**
12
 * A manager for simple text documents. Requires at minimum that the server
13
 * registered for document open/close and change events.
14
 */
15
class TextDocuments<T extends { uri: DocumentUri }> {
16
    /**
17
     * Create a new text document manager
18
     * @param configuration Configuration for creating and updating documents
19
     */
20
    constructor(configuration: TextDocumentsConfiguration<T>);
21
    
22
    /** Event fired when a text document managed by this manager has been opened */
23
    readonly onDidOpen: Event<TextDocumentChangeEvent<T>>;
24
    
25
    /** Event fired when a text document managed by this manager has been closed */
26
    readonly onDidClose: Event<TextDocumentChangeEvent<T>>;
27
    
28
    /** Event fired when a text document managed by this manager has changed */
29
    readonly onDidChangeContent: Event<TextDocumentChangeEvent<T>>;
30
    
31
    /** Event fired when a text document managed by this manager has been saved */
32
    readonly onDidSave: Event<TextDocumentChangeEvent<T>>;
33
    
34
    /** Event fired when a text document managed by this manager will be saved */
35
    readonly onWillSave: Event<TextDocumentWillSaveEvent<T>>;
36
    
37
    /**
38
     * Returns the document for the given URI. Returns undefined if the document
39
     * is not managed by this instance.
40
     */
41
    get(uri: DocumentUri): T | undefined;
42
    
43
    /** Returns all documents managed by this instance */
44
    all(): T[];
45
    
46
    /** Returns the URIs of all documents managed by this instance */
47
    keys(): DocumentUri[];
48
    
49
    /**
50
     * Listens for low level notification on the given connection to update
51
     * the text documents managed by this instance.
52
     */
53
    listen(connection: TextDocumentConnection): void;
54
}
55
```
56

57
**Usage Examples:**
58

59
```typescript
60
import { TextDocuments, createConnection } from "vscode-languageserver";
61
import { TextDocument } from "vscode-languageserver-textdocument";
62

63
// Create connection and documents manager
64
const connection = createConnection();
65
const documents = new TextDocuments(TextDocument);
66

67
// Listen for document events
68
documents.onDidOpen(event => {
69
    console.log(`Document opened: ${event.document.uri}`);
70
    validateDocument(event.document);
71
});
72

73
documents.onDidChangeContent(change => {
74
    console.log(`Document changed: ${change.document.uri}`);
75
    validateDocument(change.document);
76
});
77

78
documents.onDidSave(event => {
79
    console.log(`Document saved: ${event.document.uri}`);
80
});
81

82
documents.onDidClose(event => {
83
    console.log(`Document closed: ${event.document.uri}`);
84
});
85

86
// Connect documents to the connection
87
documents.listen(connection);
88

89
// Access documents
90
const document = documents.get("file:///path/to/file.txt");
91
const allDocuments = documents.all();
92
```
93

94
### Text Documents Configuration
95

96
Configuration interface for creating and updating text documents.
97

98
```typescript { .api }
99
/**
100
 * Configuration interface for text document creation and updates
101
 */
102
interface TextDocumentsConfiguration<T extends { uri: DocumentUri }> {
103
    /**
104
     * Creates a new text document
105
     * @param uri The document's URI
106
     * @param languageId The document's language id
107
     * @param version The document's version
108
     * @param content The document's content
109
     */
110
    create(uri: DocumentUri, languageId: string, version: number, content: string): T;
111
    
112
    /**
113
     * Updates an existing text document
114
     * @param document The document to update
115
     * @param changes The changes to apply
116
     * @param version The new version number
117
     */
118
    update(document: T, changes: TextDocumentContentChangeEvent[], version: number): T;
119
}
120
```
121

122
### Document Events
123

124
Event interfaces for document lifecycle notifications.
125

126
```typescript { .api }
127
/**
128
 * Event to signal changes to a text document
129
 */
130
interface TextDocumentChangeEvent<T> {
131
    /** The document that has changed */
132
    document: T;
133
}
134

135
/**
136
 * Event to signal that a document will be saved
137
 */
138
interface TextDocumentWillSaveEvent<T> {
139
    /** The document that will be saved */
140
    document: T;
141
    /** The reason why save was triggered */
142
    reason: TextDocumentSaveReason;
143
}
144

145
/**
146
 * Represents reasons why a text document is saved
147
 */
148
enum TextDocumentSaveReason {
149
    /** Manually triggered, e.g. by the user pressing save, by starting debugging, or by an API call */
150
    Manual = 1,
151
    /** Automatic after a delay */
152
    AfterDelay = 2,
153
    /** When the editor lost focus */
154
    FocusOut = 3
155
}
156
```
157

158
### Text Document Connection Interface
159

160
Interface for connecting to text document notifications.
161

162
```typescript { .api }
163
/**
164
 * Interface for receiving text document notifications
165
 */
166
interface TextDocumentConnection {
167
    /** Register handler for document open notifications */
168
    onDidOpenTextDocument(handler: NotificationHandler<DidOpenTextDocumentParams>): Disposable;
169
    
170
    /** Register handler for document change notifications */
171
    onDidChangeTextDocument(handler: NotificationHandler<DidChangeTextDocumentParams>): Disposable;
172
    
173
    /** Register handler for document close notifications */
174
    onDidCloseTextDocument(handler: NotificationHandler<DidCloseTextDocumentParams>): Disposable;
175
    
176
    /** Register handler for document will save notifications */
177
    onWillSaveTextDocument(handler: NotificationHandler<WillSaveTextDocumentParams>): Disposable;
178
    
179
    /** Register handler for document will save wait until requests */
180
    onWillSaveTextDocumentWaitUntil(
181
        handler: RequestHandler<WillSaveTextDocumentParams, TextEdit[] | undefined | null, void>
182
    ): Disposable;
183
    
184
    /** Register handler for document save notifications */
185
    onDidSaveTextDocument(handler: NotificationHandler<DidSaveTextDocumentParams>): Disposable;
186
}
187
```
188

189
### Document Change Events
190

191
Detailed change information for document updates.
192

193
```typescript { .api }
194
/**
195
 * Event for text document content changes
196
 */
197
interface TextDocumentContentChangeEvent {
198
    /** The range of the document that changed */
199
    range?: Range;
200
    /** The optional length of the range that got replaced */
201
    rangeLength?: number;
202
    /** The new text for the provided range or the whole document */
203
    text: string;
204
}
205

206
/**
207
 * Parameters for document open notifications
208
 */
209
interface DidOpenTextDocumentParams {
210
    /** The document that was opened */
211
    textDocument: TextDocumentItem;
212
}
213

214
/**
215
 * Parameters for document change notifications
216
 */
217
interface DidChangeTextDocumentParams {
218
    /** The document that did change */
219
    textDocument: VersionedTextDocumentIdentifier;
220
    /** The actual content changes */
221
    contentChanges: TextDocumentContentChangeEvent[];
222
}
223

224
/**
225
 * Parameters for document close notifications
226
 */
227
interface DidCloseTextDocumentParams {
228
    /** The document that was closed */
229
    textDocument: TextDocumentIdentifier;
230
}
231

232
/**
233
 * Parameters for document save notifications
234
 */
235
interface DidSaveTextDocumentParams {
236
    /** The document that was saved */
237
    textDocument: TextDocumentIdentifier;
238
    /** Optional the content when saved. Depends on the includeText value when save registration was requested */
239
    text?: string;
240
}
241

242
/**
243
 * Parameters for document will save notifications
244
 */
245
interface WillSaveTextDocumentParams {
246
    /** The document that will be saved */
247
    textDocument: TextDocumentIdentifier;
248
    /** The reason why save was triggered */
249
    reason: TextDocumentSaveReason;
250
}
251
```
252

253
### Integration with Connection
254

255
Direct document synchronization through the connection interface.
256

257
```typescript { .api }
258
// Via connection.languages interface
259
interface Languages {
260
    /** Handle document open notifications */
261
    onDidOpenTextDocument(handler: NotificationHandler<DidOpenTextDocumentParams>): Disposable;
262
    
263
    /** Handle document change notifications */
264
    onDidChangeTextDocument(handler: NotificationHandler<DidChangeTextDocumentParams>): Disposable;
265
    
266
    /** Handle document close notifications */
267
    onDidCloseTextDocument(handler: NotificationHandler<DidCloseTextDocumentParams>): Disposable;
268
    
269
    /** Handle document will save notifications */
270
    onWillSaveTextDocument(handler: NotificationHandler<WillSaveTextDocumentParams>): Disposable;
271
    
272
    /** Handle document will save wait until requests */
273
    onWillSaveTextDocumentWaitUntil(
274
        handler: RequestHandler<WillSaveTextDocumentParams, TextEdit[] | undefined | null, void>
275
    ): Disposable;
276
    
277
    /** Handle document save notifications */
278
    onDidSaveTextDocument(handler: NotificationHandler<DidSaveTextDocumentParams>): Disposable;
279
}
280
```
281

282
**Direct Usage Example:**
283

284
```typescript
285
import { createConnection } from "vscode-languageserver";
286

287
const connection = createConnection();
288

289
// Handle document events directly through connection
290
connection.onDidOpenTextDocument(params => {
291
    console.log(`Document opened: ${params.textDocument.uri}`);
292
});
293

294
connection.onDidChangeTextDocument(params => {
295
    console.log(`Document changed: ${params.textDocument.uri}`);
296
    console.log(`Changes: ${params.contentChanges.length}`);
297
});
298

299
connection.onWillSaveTextDocumentWaitUntil(params => {
300
    // Return text edits to apply before saving
301
    return [
302
        {
303
            range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
304
            newText: "// Auto-generated header\n"
305
        }
306
    ];
307
});
308
```
309

310
## Core Types
311

312
```typescript { .api }
313
type DocumentUri = string;
314

315
interface TextDocumentItem {
316
    /** The text document's URI */
317
    uri: DocumentUri;
318
    /** The text document's language identifier */
319
    languageId: string;
320
    /** The version number of this document */
321
    version: number;
322
    /** The content of the opened text document */
323
    text: string;
324
}
325

326
interface TextDocumentIdentifier {
327
    /** The text document's URI */
328
    uri: DocumentUri;
329
}
330

331
interface VersionedTextDocumentIdentifier extends TextDocumentIdentifier {
332
    /** The version number of this document */
333
    version: number;
334
}
335

336
interface Position {
337
    /** Line position in a document (zero-based) */
338
    line: number;
339
    /** Character offset on a line in a document (zero-based) */
340
    character: number;
341
}
342

343
interface Range {
344
    /** The range's start position */
345
    start: Position;
346
    /** The range's end position */
347
    end: Position;
348
}
349

350
interface TextEdit {
351
    /** The range of the text document to be manipulated */
352
    range: Range;
353
    /** The string to be inserted. For delete operations use an empty string */
354
    newText: string;
355
}
356

357
type Event<T> = (listener: (e: T) => any, thisArg?: any) => Disposable;
358

359
type NotificationHandler<P> = (params: P) => void;
360

361
type RequestHandler<P, R, E> = (
362
    params: P,
363
    token: CancellationToken,
364
    workDoneProgress: WorkDoneProgressReporter,
365
    partialResultProgress: ResultProgressReporter<Partial<R>>
366
) => HandlerResult<R, E>;
367
```