1
>
/*---------------------------------------------------------------------------------------------
workingCopy.ts
2
>
* Copyright (c) Microsoft Corporation. All rights reserved.
3
>
* Licensed under the MIT License. See License.txt in the project root for license information.
4
>
*--------------------------------------------------------------------------------------------*/
5
>
6
>
import { Event } from '../../../../base/common/event.js';
7
>
import { URI } from '../../../../base/common/uri.js';
8
>
import { ISaveOptions, IRevertOptions, SaveReason, SaveSource } from '../../../common/editor.js';
9
>
import { CancellationToken } from '../../../../base/common/cancellation.js';
10
>
import { VSBufferReadable, VSBufferReadableStream } from '../../../../base/common/buffer.js';
11
>
12
>
export const enum WorkingCopyCapabilities {
13
>
14
>
/**
15
>
* Signals no specific capability for the working copy.
16
>
*/
17
>
None = 0,
18
>
19
>
/**
20
>
* Signals that the working copy requires
21
>
* additional input when saving, e.g. an
22
>
* associated path to save to.
23
>
*/
24
>
Untitled = 1 << 1,
25
>
26
>
/**
27
>
* The working copy will not indicate that
28
>
* it is dirty and unsaved content will be
29
>
* discarded without prompting if closed.
30
>
*/
31
>
Scratchpad = 1 << 2
32
>
}
33
>
34
>
/**
35
>
* Data to be associated with working copy backups. Use
36
>
* `IWorkingCopyBackupService.resolve(workingCopy)` to
37
>
* retrieve the backup when loading the working copy.
38
>
*/
39
>
export interface IWorkingCopyBackup {
40
>
41
>
/**
42
>
* Any serializable metadata to be associated with the backup.
43
>
*/
44
>
meta?: IWorkingCopyBackupMeta;
45
>
46
>
/**
47
>
* The actual snapshot of the contents of the working copy at
48
>
* the time the backup was made.
49
>
*/
50
>
content?: VSBufferReadable | VSBufferReadableStream;
51
>
}
52
>
53
>
/**
54
>
* Working copy backup metadata that can be associated
55
>
* with the backup.
56
>
*
57
>
* Some properties may be reserved as outlined here and
58
>
* cannot be used.
59
>
*/
60
>
export interface IWorkingCopyBackupMeta {
61
>
62
>
/**
63
>
* Any property needs to be serializable through JSON.
64
>
*/
65
>
[key: string]: unknown;
66
>
67
>
/**
68
>
* `typeId` is a reserved property that cannot be used
69
>
* as backup metadata.
70
>
*/
71
>
typeId?: never;
72
>
}
73
>
74
>
/**
75
>
* @deprecated it is important to provide a type identifier
76
>
* for working copies to enable all capabilities.
77
>
*/
78
>
export const NO_TYPE_ID = '';
79
>
80
>
/**
81
>
* Every working copy has in common that it is identified by
82
>
* a resource `URI` and a `typeId`. There can only be one
83
>
* working copy registered with the same `URI` and `typeId`.
84
>
*/
85
>
export interface IWorkingCopyIdentifier {
86
>
87
>
/**
88
>
* The type identifier of the working copy for grouping
89
>
* working copies of the same domain together.
90
>
*
91
>
* There can only be one working copy for a given resource
92
>
* and type identifier.
93
>
*/
94
>
readonly typeId: string;
95
>
96
>
/**
97
>
* The resource of the working copy must be unique for
98
>
* working copies of the same `typeId`.
99
>
*/
100
>
readonly resource: URI;
101
>
}
102
>
103
>
export interface IWorkingCopySaveEvent {
104
>
105
>
/**
106
>
* The reason why the working copy was saved.
107
>
*/
108
>
readonly reason?: SaveReason;
109
>
110
>
/**
111
>
* The source of the working copy save request.
112
>
*/
113
>
readonly source?: SaveSource;
114
>
}
115
>
116
>
/**
117
>
* A working copy is an abstract concept to unify handling of
118
>
* data that can be worked on (e.g. edited) in an editor.
119
>
*
120
>
*
121
>
* A working copy resource may be the backing store of the data
122
>
* (e.g. a file on disk), but that is not a requirement. If
123
>
* your working copy is file based, consider to use the
124
>
* `IFileWorkingCopy` instead that simplifies a lot of things
125
>
* when working with file based working copies.
126
>
*/
127
>
export interface IWorkingCopy extends IWorkingCopyIdentifier {
128
>
129
>
/**
130
>
* Human readable name of the working copy.
131
>
*/
132
>
readonly name: string;
133
>
134
>
/**
135
>
* The capabilities of the working copy.
136
>
*/
137
>
readonly capabilities: WorkingCopyCapabilities;
138
>
139
>
140
>
//#region Events
141
>
142
>
/**
143
>
* Used by the workbench to signal if the working copy
144
>
* is dirty or not. Typically a working copy is dirty
145
>
* once changed until saved or reverted.
146
>
*/
147
>
readonly onDidChangeDirty: Event<void>;
148
>
149
>
/**
150
>
* Used by the workbench e.g. to trigger auto-save
151
>
* (unless this working copy is untitled) and backups.
152
>
*/
153
>
readonly onDidChangeContent: Event<void>;
154
>
155
>
/**
156
>
* Used by the workbench e.g. to track local history
157
>
* (unless this working copy is untitled).
158
>
*/
159
>
readonly onDidSave: Event<IWorkingCopySaveEvent>;
160
>
161
>
//#endregion
162
>
163
>
164
>
//#region Dirty Tracking
165
>
166
>
/**
167
>
* Indicates that the file has unsaved changes
168
>
* and should confirm before closing.
169
>
*/
170
>
isDirty(): boolean;
171
>
172
>
/**
173
>
* Indicates that the file has unsaved changes.
174
>
* Used for backup tracking and accounts for
175
>
* working copies that are never dirty e.g.
176
>
* scratchpads.
177
>
*/
178
>
isModified(): boolean;
179
>
180
>
//#endregion
181
>
182
>
183
>
//#region Save / Backup
184
>
185
>
/**
186
>
* The delay in milliseconds to wait before triggering
187
>
* a backup after the content of the model has changed.
188
>
*
189
>
* If not configured, a sensible default will be taken
190
>
* based on user settings.
191
>
*/
192
>
readonly backupDelay?: number;
193
>
194
>
/**
195
>
* The workbench may call this method often after it receives
196
>
* the `onDidChangeContent` event for the working copy. The motivation
197
>
* is to allow to quit VSCode with dirty working copies present.
198
>
*
199
>
* Providers of working copies should use `IWorkingCopyBackupService.resolve(workingCopy)`
200
>
* to retrieve the backup metadata associated when loading the working copy.
201
>
*
202
>
* @param token support for cancellation
203
>
*/
204
>
backup(token: CancellationToken): Promise<IWorkingCopyBackup>;
205
>
206
>
/**
207
>
* Asks the working copy to save. If the working copy was dirty, it is
208
>
* expected to be non-dirty after this operation has finished.
209
>
*
210
>
* @returns `true` if the operation was successful and `false` otherwise.
211
>
*/
212
>
save(options?: ISaveOptions): Promise<boolean>;
213
>
214
>
/**
215
>
* Asks the working copy to revert. If the working copy was dirty, it is
216
>
* expected to be non-dirty after this operation has finished.
217
>
*/
218
>
revert(options?: IRevertOptions): Promise<void>;
219
>
220
>
//#endregion
221
>
}