@fluid-experimental/tree 2.0.0-dev-rc.3.0.0.254513 → 2.0.0-dev-rc.3.0.0.254674
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +21 -21
- package/dist/tree-alpha.d.ts +0 -2901
- package/dist/tree-beta.d.ts +0 -348
- package/dist/tree-public.d.ts +0 -348
- package/dist/tree-untrimmed.d.ts +0 -3820
package/dist/tree-alpha.d.ts
DELETED
|
@@ -1,2901 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Fluid DDS storing a tree.
|
|
3
|
-
*
|
|
4
|
-
* @packageDocumentation
|
|
5
|
-
*/
|
|
6
|
-
|
|
7
|
-
import { EventEmitterWithErrorHandling } from '@fluidframework/telemetry-utils/internal';
|
|
8
|
-
import { IChannel } from '@fluidframework/datastore-definitions';
|
|
9
|
-
import { IChannelAttributes } from '@fluidframework/datastore-definitions';
|
|
10
|
-
import { IChannelFactory } from '@fluidframework/datastore-definitions';
|
|
11
|
-
import { IChannelServices } from '@fluidframework/datastore-definitions';
|
|
12
|
-
import { IChannelStorageService } from '@fluidframework/datastore-definitions';
|
|
13
|
-
import { IDisposable } from '@fluidframework/core-interfaces';
|
|
14
|
-
import { IErrorEvent } from '@fluidframework/core-interfaces';
|
|
15
|
-
import { IEvent } from '@fluidframework/core-interfaces';
|
|
16
|
-
import { IExperimentalIncrementalSummaryContext } from '@fluidframework/runtime-definitions';
|
|
17
|
-
import { IFluidDataStoreRuntime } from '@fluidframework/datastore-definitions';
|
|
18
|
-
import { IFluidHandle } from '@fluidframework/core-interfaces';
|
|
19
|
-
import { IFluidLoadable } from '@fluidframework/core-interfaces';
|
|
20
|
-
import { IFluidSerializer } from '@fluidframework/shared-object-base';
|
|
21
|
-
import { IGarbageCollectionData } from '@fluidframework/runtime-definitions';
|
|
22
|
-
import { ISharedObjectEvents } from '@fluidframework/shared-object-base';
|
|
23
|
-
import { ISummaryTreeWithStats } from '@fluidframework/runtime-definitions';
|
|
24
|
-
import { ITelemetryBaseEvent } from '@fluidframework/core-interfaces';
|
|
25
|
-
import { ITelemetryBaseProperties } from '@fluidframework/core-interfaces';
|
|
26
|
-
import { ITelemetryContext } from '@fluidframework/runtime-definitions';
|
|
27
|
-
import { ITelemetryLoggerExt } from '@fluidframework/telemetry-utils';
|
|
28
|
-
import { ITree } from '@fluidframework/tree';
|
|
29
|
-
import { SharedObject } from '@fluidframework/shared-object-base/internal';
|
|
30
|
-
import { TypedEventEmitter } from '@fluid-internal/client-utils';
|
|
31
|
-
|
|
32
|
-
/* Excluded from this release type: areRevisionViewsSemanticallyEqual */
|
|
33
|
-
|
|
34
|
-
/**
|
|
35
|
-
* An identifier associated with a session for the purpose of attributing its created content to some user/entity.
|
|
36
|
-
* @alpha
|
|
37
|
-
*/
|
|
38
|
-
export declare type AttributionId = UuidString;
|
|
39
|
-
|
|
40
|
-
/**
|
|
41
|
-
* The result of validating a bad place.
|
|
42
|
-
* @alpha
|
|
43
|
-
*/
|
|
44
|
-
export declare type BadPlaceValidationResult = Exclude<PlaceValidationResult, PlaceValidationResult.Valid>;
|
|
45
|
-
|
|
46
|
-
/**
|
|
47
|
-
* The result of validating a bad range.
|
|
48
|
-
* @alpha
|
|
49
|
-
*/
|
|
50
|
-
export declare type BadRangeValidationResult = Exclude<RangeValidationResult, RangeValidationResultKind.Valid>;
|
|
51
|
-
|
|
52
|
-
/**
|
|
53
|
-
* Constructs a sequence of nodes, associates it with the supplied ID, and stores it for use in later changes.
|
|
54
|
-
* Does not modify the document.
|
|
55
|
-
*
|
|
56
|
-
* Valid if (transitively) all DetachedSequenceId are used according to their rules (use here counts as a destination),
|
|
57
|
-
* and all Nodes' identifiers are previously unused.
|
|
58
|
-
* @alpha
|
|
59
|
-
*/
|
|
60
|
-
export declare interface Build {
|
|
61
|
-
readonly destination: number;
|
|
62
|
-
readonly source: BuildNode | TreeNodeSequence<BuildNode>;
|
|
63
|
-
readonly type: typeof ChangeType.Build;
|
|
64
|
-
}
|
|
65
|
-
|
|
66
|
-
/**
|
|
67
|
-
* {@inheritdoc Build}
|
|
68
|
-
* @alpha
|
|
69
|
-
*/
|
|
70
|
-
export declare interface BuildInternal extends Omit<BuildInternal_0_0_2, 'source'> {
|
|
71
|
-
readonly source: TreeNodeSequence<BuildNodeInternal>;
|
|
72
|
-
}
|
|
73
|
-
|
|
74
|
-
/**
|
|
75
|
-
* {@inheritdoc Build}
|
|
76
|
-
* @alpha
|
|
77
|
-
*/
|
|
78
|
-
export declare interface BuildInternal_0_0_2 {
|
|
79
|
-
/** {@inheritdoc Build.destination } */
|
|
80
|
-
readonly destination: DetachedSequenceId;
|
|
81
|
-
/** {@inheritdoc Build.source } */
|
|
82
|
-
readonly source: TreeNodeSequence<BuildNodeInternal_0_0_2>;
|
|
83
|
-
/** {@inheritdoc Build."type" } */
|
|
84
|
-
readonly type: typeof ChangeTypeInternal.Build;
|
|
85
|
-
}
|
|
86
|
-
|
|
87
|
-
/**
|
|
88
|
-
* Node or a detached sequence of nodes (referred to by a detached sequence ID) for use in a Build change.
|
|
89
|
-
* See `BuildTreeNode` for more.
|
|
90
|
-
* @alpha
|
|
91
|
-
*/
|
|
92
|
-
export declare type BuildNode = BuildTreeNode | number;
|
|
93
|
-
|
|
94
|
-
/**
|
|
95
|
-
* {@inheritdoc BuildNode}
|
|
96
|
-
* @alpha
|
|
97
|
-
*/
|
|
98
|
-
export declare type BuildNodeInternal = TreeNode<BuildNodeInternal, NodeId> | DetachedSequenceId;
|
|
99
|
-
|
|
100
|
-
/**
|
|
101
|
-
* {@inheritdoc BuildNode}
|
|
102
|
-
* @alpha
|
|
103
|
-
*/
|
|
104
|
-
export declare type BuildNodeInternal_0_0_2 = TreeNode<BuildNodeInternal_0_0_2, StableNodeId> | DetachedSequenceId;
|
|
105
|
-
|
|
106
|
-
/**
|
|
107
|
-
* Node for use in a Build change, which is composed of a definition describing what this nodes type, an identifier identifying this node
|
|
108
|
-
* within the tree, and a payload containing an opaque serializable piece of data.
|
|
109
|
-
* An identifier can be provided explicitly if the node must be referred to before the results of the `Change` containing this
|
|
110
|
-
* BuildTreeNode can be observed. If `identifier` is not supplied, one will be generated for it in an especially efficient manner
|
|
111
|
-
* that allows for compact storage and transmission and thus this property should be omitted if convenient.
|
|
112
|
-
* See the SharedTree readme for more on the tree format.
|
|
113
|
-
* @alpha
|
|
114
|
-
*/
|
|
115
|
-
export declare interface BuildTreeNode extends HasVariadicTraits<BuildNode> {
|
|
116
|
-
definition: string;
|
|
117
|
-
identifier?: NodeId;
|
|
118
|
-
payload?: Payload;
|
|
119
|
-
}
|
|
120
|
-
|
|
121
|
-
/**
|
|
122
|
-
* A change that composes an Edit.
|
|
123
|
-
*
|
|
124
|
-
* @remarks
|
|
125
|
-
*
|
|
126
|
-
* `Change` objects can be conveniently constructed with the helper methods exported on a constant of the same name.
|
|
127
|
-
*
|
|
128
|
-
* @example
|
|
129
|
-
*
|
|
130
|
-
* ```typescript
|
|
131
|
-
* Change.insert(sourceId, destination)
|
|
132
|
-
* ```
|
|
133
|
-
* @alpha
|
|
134
|
-
*/
|
|
135
|
-
export declare type Change = Insert | Detach | Build | SetValue | Constraint;
|
|
136
|
-
|
|
137
|
-
/**
|
|
138
|
-
* @alpha
|
|
139
|
-
*/
|
|
140
|
-
export declare const Change: {
|
|
141
|
-
build: (source: BuildNode | TreeNodeSequence<BuildNode>, destination: number) => Build;
|
|
142
|
-
insert: (source: number, destination: StablePlace) => Insert;
|
|
143
|
-
detach: (source: StableRange, destination?: number) => Detach;
|
|
144
|
-
setPayload: (nodeToModify: NodeId, payload: Payload) => SetValue;
|
|
145
|
-
clearPayload: (nodeToModify: NodeId) => SetValue;
|
|
146
|
-
constraint: (toConstrain: StableRange, effect: ConstraintEffect, identityHash?: UuidString, length?: number, contentHash?: UuidString, parentNode?: NodeId, label?: TraitLabel) => Constraint;
|
|
147
|
-
/** Helpers for making high-level composite operations */
|
|
148
|
-
/**
|
|
149
|
-
* @returns a change that deletes the supplied part of the tree.
|
|
150
|
-
*/
|
|
151
|
-
delete: (stableRange: StableRange) => Change;
|
|
152
|
-
/**
|
|
153
|
-
* @returns changes that insert 'nodes' into the specified location in the tree.
|
|
154
|
-
*/
|
|
155
|
-
insertTree: (nodes: BuildNode | TreeNodeSequence<BuildNode>, destination: StablePlace) => Change[];
|
|
156
|
-
/**
|
|
157
|
-
* @returns changes that moves the specified content to a new location in the tree.
|
|
158
|
-
*/
|
|
159
|
-
move: (source: StableRange, destination: StablePlace) => Change[];
|
|
160
|
-
};
|
|
161
|
-
|
|
162
|
-
/**
|
|
163
|
-
* {@inheritdoc (Change:type)}
|
|
164
|
-
* @alpha
|
|
165
|
-
*/
|
|
166
|
-
export declare type ChangeInternal = InsertInternal | DetachInternal | BuildInternal | SetValueInternal | ConstraintInternal;
|
|
167
|
-
|
|
168
|
-
/**
|
|
169
|
-
* @alpha
|
|
170
|
-
*/
|
|
171
|
-
export declare const ChangeInternal: {
|
|
172
|
-
build: (source: TreeNodeSequence<BuildNodeInternal>, destination: DetachedSequenceId) => BuildInternal;
|
|
173
|
-
insert: (source: DetachedSequenceId, destination: StablePlaceInternal) => InsertInternal;
|
|
174
|
-
detach: (source: StableRangeInternal, destination?: DetachedSequenceId) => DetachInternal;
|
|
175
|
-
setPayload: (nodeToModify: NodeData<NodeId> | NodeId, payload: Payload) => SetValueInternal;
|
|
176
|
-
clearPayload: (nodeToModify: NodeData<NodeId> | NodeId) => SetValueInternal;
|
|
177
|
-
constraint: (toConstrain: StableRangeInternal, effect: ConstraintEffect, identityHash?: UuidString, length?: number, contentHash?: UuidString, parentNode?: NodeId, label?: TraitLabel) => ConstraintInternal;
|
|
178
|
-
/** {@inheritdoc (Change:variable).delete } */
|
|
179
|
-
delete: (stableRange: StableRangeInternal) => ChangeInternal;
|
|
180
|
-
/** {@inheritdoc (Change:variable).insertTree } */
|
|
181
|
-
insertTree: (nodes: TreeNodeSequence<BuildNodeInternal>, destination: StablePlaceInternal) => ChangeInternal[];
|
|
182
|
-
/** {@inheritdoc (Change:variable).move } */
|
|
183
|
-
move: (source: StableRangeInternal, destination: StablePlaceInternal) => ChangeInternal[];
|
|
184
|
-
};
|
|
185
|
-
|
|
186
|
-
/* Excluded from this release type: ChangeNode */
|
|
187
|
-
|
|
188
|
-
/**
|
|
189
|
-
* JSON-compatible Node type. Objects of this type will be persisted in internal change objects (under Edits) in the SharedTree history.
|
|
190
|
-
* @alpha
|
|
191
|
-
*/
|
|
192
|
-
export declare type ChangeNode_0_0_2 = TreeNode<ChangeNode_0_0_2, StableNodeId>;
|
|
193
|
-
|
|
194
|
-
/* Excluded from this release type: ChangeResult */
|
|
195
|
-
|
|
196
|
-
/**
|
|
197
|
-
* The type of a Change
|
|
198
|
-
* @alpha
|
|
199
|
-
*/
|
|
200
|
-
export declare enum ChangeType {
|
|
201
|
-
Insert = 0,
|
|
202
|
-
Detach = 1,
|
|
203
|
-
Build = 2,
|
|
204
|
-
SetValue = 3,
|
|
205
|
-
Constraint = 4
|
|
206
|
-
}
|
|
207
|
-
|
|
208
|
-
/**
|
|
209
|
-
* {@inheritdoc ChangeType}
|
|
210
|
-
* @alpha
|
|
211
|
-
*/
|
|
212
|
-
export declare enum ChangeTypeInternal {
|
|
213
|
-
Insert = 0,
|
|
214
|
-
Detach = 1,
|
|
215
|
-
Build = 2,
|
|
216
|
-
SetValue = 3,
|
|
217
|
-
Constraint = 4,
|
|
218
|
-
CompressedBuild = 5
|
|
219
|
-
}
|
|
220
|
-
|
|
221
|
-
/**
|
|
222
|
-
* A mutable Checkout of a SharedTree, allowing viewing and interactive transactional editing.
|
|
223
|
-
* Provides {@link https://en.wikipedia.org/wiki/Snapshot_isolation | snapshot-isolation} while editing.
|
|
224
|
-
*
|
|
225
|
-
* A Checkout always shows a consistent sequence of versions of the SharedTree, but it may skip intermediate versions, and may fall behind.
|
|
226
|
-
* In this case consistent means the sequence of versions could occur with fully synchronous shared tree access,
|
|
227
|
-
* though the timing of sequenced edits arriving to the Checkout may be later than they actually arrive in the SharedTree.
|
|
228
|
-
* Specifically no sequenced edits will arrive during an ongoing edit (to implement snapshot isolation):
|
|
229
|
-
* they will be applied asynchronously some time after the ongoing edit is ended.
|
|
230
|
-
*
|
|
231
|
-
* Events emitted by `Checkout` are documented in {@link CheckoutEvent}.
|
|
232
|
-
* Exceptions thrown during event handling will be emitted as error events, which are automatically surfaced as error events on the
|
|
233
|
-
* `SharedTree` used at construction time.
|
|
234
|
-
* @alpha
|
|
235
|
-
*/
|
|
236
|
-
export declare abstract class Checkout extends EventEmitterWithErrorHandling<ICheckoutEvents> implements IDisposable {
|
|
237
|
-
/**
|
|
238
|
-
* The view of the latest committed revision.
|
|
239
|
-
* Does not include changes from any open edits.
|
|
240
|
-
*
|
|
241
|
-
* When this changes, emitChange must be called.
|
|
242
|
-
*/
|
|
243
|
-
protected abstract get latestCommittedView(): RevisionView;
|
|
244
|
-
/**
|
|
245
|
-
* The last view for which invalidation was sent.
|
|
246
|
-
* Updated by emitChange.
|
|
247
|
-
*/
|
|
248
|
-
private previousView;
|
|
249
|
-
/**
|
|
250
|
-
* A handler for 'committedEdit' SharedTreeEvent
|
|
251
|
-
*/
|
|
252
|
-
private readonly editCommittedHandler;
|
|
253
|
-
/**
|
|
254
|
-
* The shared tree this checkout views/edits.
|
|
255
|
-
*/
|
|
256
|
-
readonly tree: SharedTree;
|
|
257
|
-
/**
|
|
258
|
-
* `tree`'s log viewer as a CachingLogViewer if it is one, otherwise undefined.
|
|
259
|
-
* Used for optimizations if provided.
|
|
260
|
-
*/
|
|
261
|
-
private readonly cachingLogViewer?;
|
|
262
|
-
/**
|
|
263
|
-
* Holds the state required to manage the currently open edit.
|
|
264
|
-
* Undefined if there is currently not an open edit.
|
|
265
|
-
*
|
|
266
|
-
* Since `currentView` exposes the the intermediate state from this edit,
|
|
267
|
-
* operations that modify `currentEdit.view` must call `emitChange` to handle invalidation.
|
|
268
|
-
*/
|
|
269
|
-
private currentEdit?;
|
|
270
|
-
private readonly logger;
|
|
271
|
-
disposed: boolean;
|
|
272
|
-
protected constructor(tree: SharedTree, currentView: RevisionView, onEditCommitted: EditCommittedHandler);
|
|
273
|
-
/**
|
|
274
|
-
* @returns the current view of the tree, including the result of changes applied so far during an edit.
|
|
275
|
-
* Note that any external edits (from other clients) will not added to view while there is a `currentEdit`.
|
|
276
|
-
*/
|
|
277
|
-
get currentView(): TreeView;
|
|
278
|
-
/**
|
|
279
|
-
* @returns true iff there is an open edit.
|
|
280
|
-
*/
|
|
281
|
-
hasOpenEdit(): boolean;
|
|
282
|
-
/**
|
|
283
|
-
* Opens a new edit operation.
|
|
284
|
-
* Changes accumulate in the edit via calls to `applyChanges()`.
|
|
285
|
-
*/
|
|
286
|
-
openEdit(): void;
|
|
287
|
-
/**
|
|
288
|
-
* Ends the ongoing edit operation and commits it to the history.
|
|
289
|
-
*
|
|
290
|
-
* Malformed edits are considered an error, and will assert:
|
|
291
|
-
* All named detached sequences must have been used or the Edit is malformed.
|
|
292
|
-
*
|
|
293
|
-
* @returns the `id` of the committed edit
|
|
294
|
-
*/
|
|
295
|
-
closeEdit(): EditId;
|
|
296
|
-
private validateChangesApplied;
|
|
297
|
-
/**
|
|
298
|
-
* Inform the Checkout that a particular edit is know to have a specific result when applied to a particular TreeView.
|
|
299
|
-
* This may be used as a caching hint to avoid recomputation.
|
|
300
|
-
*/
|
|
301
|
-
protected hintKnownEditingResult(edit: Edit<ChangeInternal>, result: ValidEditingResult): void;
|
|
302
|
-
/**
|
|
303
|
-
* Take any needed action between when an edit is completed.
|
|
304
|
-
* Usually this will include submitting it to a SharedTree.
|
|
305
|
-
*
|
|
306
|
-
* Override this to customize.
|
|
307
|
-
*/
|
|
308
|
-
protected handleNewEdit(id: EditId, result: ValidEditingResult): void;
|
|
309
|
-
/**
|
|
310
|
-
* Applies the supplied changes to the tree and emits a change event.
|
|
311
|
-
* Must be called during an ongoing edit (see `openEdit()`/`closeEdit()`).
|
|
312
|
-
* `changes` must be well-formed and valid: it is an error if they do not apply cleanly.
|
|
313
|
-
*/
|
|
314
|
-
applyChanges(changes: readonly Change[]): void;
|
|
315
|
-
applyChanges(...changes: readonly Change[]): void;
|
|
316
|
-
/**
|
|
317
|
-
* Applies the supplied changes to the tree and emits a change event.
|
|
318
|
-
* Must be called during an ongoing edit (see `openEdit()`/`closeEdit()`).
|
|
319
|
-
* `changes` must be well-formed and valid: it is an error if they do not apply cleanly.
|
|
320
|
-
*/
|
|
321
|
-
protected tryApplyChangesInternal(changes: readonly ChangeInternal[]): EditStatus;
|
|
322
|
-
protected tryApplyChangesInternal(...changes: readonly ChangeInternal[]): EditStatus;
|
|
323
|
-
/**
|
|
324
|
-
* Convenience helper for applying an edit containing the given changes.
|
|
325
|
-
* Opens an edit, applies the given changes, and closes the edit. See (`openEdit()`/`applyChanges()`/`closeEdit()`).
|
|
326
|
-
*/
|
|
327
|
-
applyEdit(changes: readonly Change[]): EditId;
|
|
328
|
-
applyEdit(...changes: readonly Change[]): EditId;
|
|
329
|
-
/**
|
|
330
|
-
* Apply an edit, if valid, otherwise does nothing (the edit is not added to the history).
|
|
331
|
-
* If the edit applied, its changes will be immediately visible on this checkout, though it still may end up invalid once sequenced due to concurrent edits.
|
|
332
|
-
* @returns The EditId if the edit was valid and thus applied, and undefined if it was invalid and thus not applied.
|
|
333
|
-
*/
|
|
334
|
-
tryApplyEdit(changes: readonly Change[]): EditId | undefined;
|
|
335
|
-
tryApplyEdit(...changes: readonly Change[]): EditId | undefined;
|
|
336
|
-
/**
|
|
337
|
-
* Rebases the ongoing edit to the latest revision loaded by this 'Checkout'.
|
|
338
|
-
*
|
|
339
|
-
* If the rebase succeeds (none of the changes in the ongoing edit became invalid), the ongoing edit will remain open and the current
|
|
340
|
-
* view will reflect those changes.
|
|
341
|
-
*
|
|
342
|
-
* If the rebase fails (changes become invalid), the ongoing edit will be aborted and
|
|
343
|
-
* currentView will return to showing the newest committed revision as it always does when there is no ongoing edit.
|
|
344
|
-
*
|
|
345
|
-
* Must only be called during an open edit.
|
|
346
|
-
*
|
|
347
|
-
* @returns The result of the rebase.
|
|
348
|
-
*/
|
|
349
|
-
rebaseCurrentEdit(): EditValidationResult.Valid | EditValidationResult.Invalid;
|
|
350
|
-
/**
|
|
351
|
-
* Ends the ongoing edit operation without committing it to the history.
|
|
352
|
-
* Can only be called if an edit is open.
|
|
353
|
-
*/
|
|
354
|
-
abortEdit(): void;
|
|
355
|
-
/**
|
|
356
|
-
* @returns the {@link EditStatus} of the current edit.
|
|
357
|
-
* Has no side effects.
|
|
358
|
-
* Can only be called if an edit is open.
|
|
359
|
-
*/
|
|
360
|
-
getEditStatus(): EditStatus;
|
|
361
|
-
/**
|
|
362
|
-
* Reverts a collection of edits.
|
|
363
|
-
* @param editIds - the edits to revert
|
|
364
|
-
*/
|
|
365
|
-
revert(editId: EditId): void;
|
|
366
|
-
/**
|
|
367
|
-
* Send invalidation message for all changes since last call to emitChange.
|
|
368
|
-
* This must be called every time `currentView` could have changed.
|
|
369
|
-
* It is ok to make excessive calls to this: change notifications will be cheaply de-duplicated.
|
|
370
|
-
*/
|
|
371
|
-
protected emitChange(): void;
|
|
372
|
-
/**
|
|
373
|
-
* @returns a Promise which completes after all currently known edits are available in this checkout.
|
|
374
|
-
*/
|
|
375
|
-
abstract waitForPendingUpdates(): Promise<void>;
|
|
376
|
-
/**
|
|
377
|
-
* @returns a Promise which completes after edits that were closed on this checkout (before calling this) have been
|
|
378
|
-
* submitted to Fluid. This does NOT wait for the Fluid service to ack them
|
|
379
|
-
*/
|
|
380
|
-
abstract waitForEditsToSubmit(): Promise<void>;
|
|
381
|
-
/**
|
|
382
|
-
* release all unmanaged resources
|
|
383
|
-
* e.g. unregister event listeners
|
|
384
|
-
*/
|
|
385
|
-
dispose(error?: Error): void;
|
|
386
|
-
}
|
|
387
|
-
|
|
388
|
-
/**
|
|
389
|
-
* An event emitted by a `Checkout` to indicate a state change. See {@link ICheckoutEvents} for event argument information.
|
|
390
|
-
* @alpha
|
|
391
|
-
*/
|
|
392
|
-
export declare enum CheckoutEvent {
|
|
393
|
-
/**
|
|
394
|
-
* `currentView` has changed.
|
|
395
|
-
* Passed a before and after TreeView.
|
|
396
|
-
*/
|
|
397
|
-
ViewChange = "viewChange"
|
|
398
|
-
}
|
|
399
|
-
|
|
400
|
-
/**
|
|
401
|
-
* @returns true if two `Payloads` are identical.
|
|
402
|
-
* May return false for equivalent payloads encoded differently.
|
|
403
|
-
*
|
|
404
|
-
* Object field order and object identity are not considered significant, and are ignored by this function.
|
|
405
|
-
* (This is because they may not be preserved through roundtrip).
|
|
406
|
-
*
|
|
407
|
-
* For other information which Fluid would lose on serialization round trip,
|
|
408
|
-
* behavior is unspecified other than this this function is reflective (all payloads are equal to themselves)
|
|
409
|
-
* and commutative (argument order does not matter).
|
|
410
|
-
*
|
|
411
|
-
* This means that any Payload is equal to itself and a deep clone of itself.
|
|
412
|
-
*
|
|
413
|
-
* Payloads might not be equal to a version of themselves that has been serialized then deserialized.
|
|
414
|
-
* If they are serialized then deserialized again, the two deserialized objects will compare equal,
|
|
415
|
-
* however the serialized strings may be unequal (due to field order for objects being unspecified).
|
|
416
|
-
*
|
|
417
|
-
* Fluid will cause lossy operations due to use of JSON.stringify().
|
|
418
|
-
* This includes:
|
|
419
|
-
* - Loss of object identity
|
|
420
|
-
* - Loss of field order (may be ordered arbitrarily)
|
|
421
|
-
* - -0 becomes +0
|
|
422
|
-
* - NaN, Infinity, -Infinity all become null
|
|
423
|
-
* - custom toJSON functions may cause arbitrary behavior
|
|
424
|
-
* - functions become undefined or null
|
|
425
|
-
* - non enumerable properties (including prototype) are lost
|
|
426
|
-
* - more (this is not a complete list)
|
|
427
|
-
*
|
|
428
|
-
* Inputs must not contain cyclic references other than fields set to their immediate parent (for the JavaScript feature detection pattern).
|
|
429
|
-
*
|
|
430
|
-
* IFluidHandle instances (detected via JavaScript feature detection pattern) are only compared by absolutePath.
|
|
431
|
-
*
|
|
432
|
-
* TODO:#54095: Is there a better way to do this comparison?
|
|
433
|
-
* @alpha
|
|
434
|
-
*/
|
|
435
|
-
export declare function comparePayloads(a: Payload, b: Payload): boolean;
|
|
436
|
-
|
|
437
|
-
/**
|
|
438
|
-
* An identifier (UUID) that has been shortened by a distributed compression algorithm.
|
|
439
|
-
* @alpha
|
|
440
|
-
*/
|
|
441
|
-
export declare type CompressedId = FinalCompressedId | LocalCompressedId;
|
|
442
|
-
|
|
443
|
-
/**
|
|
444
|
-
* A set of constraints on the validity of an Edit.
|
|
445
|
-
* A Constraint is used to detect when an Edit, due to other concurrent edits, may have unintended effects or merge in
|
|
446
|
-
* non-semantic ways. It is processed in order like any other Change in an Edit. It can cause an edit to fail if the
|
|
447
|
-
* various constraints are not met at the time of evaluation (ex: the parentNode has changed due to concurrent editing).
|
|
448
|
-
* Does not modify the document.
|
|
449
|
-
* @alpha
|
|
450
|
-
*/
|
|
451
|
-
export declare interface Constraint {
|
|
452
|
-
/**
|
|
453
|
-
* Selects a sequence of nodes which will be checked against the constraints specified by the optional fields.
|
|
454
|
-
* If `toConstrain` is invalid, it will be treated like a constraint being unmet.
|
|
455
|
-
* Depending on `effect` this may or may not make the Edit invalid.
|
|
456
|
-
*
|
|
457
|
-
* When a constraint is not met, the effects is specified by `effect`.
|
|
458
|
-
*/
|
|
459
|
-
readonly toConstrain: StableRange;
|
|
460
|
-
/**
|
|
461
|
-
* Require that the identities of all the nodes in toConstrain hash to this value.
|
|
462
|
-
* Hash is order dependent.
|
|
463
|
-
* TODO: implement and specify exact hash function.
|
|
464
|
-
*
|
|
465
|
-
* This is an efficient (O(1) space) way to constrain a sequence of nodes to have specific identities.
|
|
466
|
-
*/
|
|
467
|
-
readonly identityHash?: UuidString;
|
|
468
|
-
/**
|
|
469
|
-
* Require that the number of nodes in toConstrain is this value.
|
|
470
|
-
*/
|
|
471
|
-
readonly length?: number;
|
|
472
|
-
/**
|
|
473
|
-
* Require that the contents of all of the nodes in toConstrain hash to this value.
|
|
474
|
-
* Hash is an order dependant deep hash, which includes all subtree content recursively.
|
|
475
|
-
* TODO: implement and specify exact hash function.
|
|
476
|
-
*
|
|
477
|
-
* This is an efficient (O(1) space) way to constrain a sequence of nodes have exact values (transitively).
|
|
478
|
-
*/
|
|
479
|
-
readonly contentHash?: UuidString;
|
|
480
|
-
/**
|
|
481
|
-
* Require that parent under which toConstrain is located has this identifier.
|
|
482
|
-
*/
|
|
483
|
-
readonly parentNode?: NodeId;
|
|
484
|
-
/**
|
|
485
|
-
* Require that the trait under which toConstrain is located has this label.
|
|
486
|
-
*/
|
|
487
|
-
readonly label?: TraitLabel;
|
|
488
|
-
/**
|
|
489
|
-
* What to do if a constraint is not met.
|
|
490
|
-
*/
|
|
491
|
-
readonly effect: ConstraintEffect;
|
|
492
|
-
/**
|
|
493
|
-
* Marker for which kind of Change this is.
|
|
494
|
-
*/
|
|
495
|
-
readonly type: typeof ChangeType.Constraint;
|
|
496
|
-
}
|
|
497
|
-
|
|
498
|
-
/**
|
|
499
|
-
* What to do when a Constraint is violated.
|
|
500
|
-
* @alpha
|
|
501
|
-
*/
|
|
502
|
-
export declare enum ConstraintEffect {
|
|
503
|
-
/**
|
|
504
|
-
* Discard Edit.
|
|
505
|
-
*/
|
|
506
|
-
InvalidAndDiscard = 0,
|
|
507
|
-
/**
|
|
508
|
-
* Discard Edit, but record metadata that application may want to try and recover this change by recreating it.
|
|
509
|
-
* Should this be the default policy for when another (non Constraint) change is invalid?
|
|
510
|
-
*/
|
|
511
|
-
InvalidRetry = 1,
|
|
512
|
-
/**
|
|
513
|
-
* Apply the change, but flag it for possible reconsideration by the app
|
|
514
|
-
* (applying it is better than not, but perhaps the high level logic could produce something better).
|
|
515
|
-
*/
|
|
516
|
-
ValidRetry = 2
|
|
517
|
-
}
|
|
518
|
-
|
|
519
|
-
/**
|
|
520
|
-
* {@inheritdoc Constraint}
|
|
521
|
-
* @alpha
|
|
522
|
-
*/
|
|
523
|
-
export declare interface ConstraintInternal extends Omit<ConstraintInternal_0_0_2, 'toConstrain' | 'parentNode'> {
|
|
524
|
-
/** {@inheritdoc Constraint.toConstrain } */
|
|
525
|
-
readonly toConstrain: StableRangeInternal;
|
|
526
|
-
/** {@inheritdoc Constraint.parentNode } */
|
|
527
|
-
readonly parentNode?: NodeId;
|
|
528
|
-
}
|
|
529
|
-
|
|
530
|
-
/**
|
|
531
|
-
* {@inheritdoc Constraint}
|
|
532
|
-
* @alpha
|
|
533
|
-
*/
|
|
534
|
-
export declare interface ConstraintInternal_0_0_2 {
|
|
535
|
-
/** {@inheritdoc Constraint.toConstrain } */
|
|
536
|
-
readonly toConstrain: StableRangeInternal_0_0_2;
|
|
537
|
-
/** {@inheritdoc Constraint.identityHash } */
|
|
538
|
-
readonly identityHash?: UuidString;
|
|
539
|
-
/** {@inheritdoc Constraint.length } */
|
|
540
|
-
readonly length?: number;
|
|
541
|
-
/** {@inheritdoc Constraint.contentHash } */
|
|
542
|
-
readonly contentHash?: UuidString;
|
|
543
|
-
/** {@inheritdoc Constraint.parentNode } */
|
|
544
|
-
readonly parentNode?: StableNodeId;
|
|
545
|
-
/** {@inheritdoc Constraint.label } */
|
|
546
|
-
readonly label?: TraitLabel;
|
|
547
|
-
/** {@inheritdoc Constraint.effect } */
|
|
548
|
-
readonly effect: ConstraintEffect;
|
|
549
|
-
/** {@inheritdoc Constraint."type" } */
|
|
550
|
-
readonly type: typeof ChangeTypeInternal.Constraint;
|
|
551
|
-
}
|
|
552
|
-
|
|
553
|
-
/**
|
|
554
|
-
* Definition.
|
|
555
|
-
* A full (Uuid) persistable definition.
|
|
556
|
-
* @alpha
|
|
557
|
-
*/
|
|
558
|
-
export declare type Definition = UuidString & {
|
|
559
|
-
readonly Definition: 'c0ef9488-2a78-482d-aeed-37fba996354c';
|
|
560
|
-
};
|
|
561
|
-
|
|
562
|
-
/**
|
|
563
|
-
* Differences from one forest to another.
|
|
564
|
-
* @alpha
|
|
565
|
-
*/
|
|
566
|
-
export declare interface Delta<NodeId> {
|
|
567
|
-
/**
|
|
568
|
-
* Nodes whose content changed.
|
|
569
|
-
*/
|
|
570
|
-
readonly changed: readonly NodeId[];
|
|
571
|
-
/**
|
|
572
|
-
* Nodes that were added.
|
|
573
|
-
*/
|
|
574
|
-
readonly added: readonly NodeId[];
|
|
575
|
-
/**
|
|
576
|
-
* Nodes that were removed.
|
|
577
|
-
*/
|
|
578
|
-
readonly removed: readonly NodeId[];
|
|
579
|
-
}
|
|
580
|
-
|
|
581
|
-
/**
|
|
582
|
-
* Removes a sequence of nodes from the tree.
|
|
583
|
-
* If a destination is specified, the detached sequence is associated with that ID and held for possible reuse
|
|
584
|
-
* by later changes in this same Edit (such as by an Insert).
|
|
585
|
-
* A Detach without a destination is a deletion of the specified sequence, as is a Detach with a destination that is not used later.
|
|
586
|
-
* @alpha
|
|
587
|
-
*/
|
|
588
|
-
export declare interface Detach {
|
|
589
|
-
readonly destination?: number;
|
|
590
|
-
readonly source: StableRange;
|
|
591
|
-
readonly type: typeof ChangeType.Detach;
|
|
592
|
-
}
|
|
593
|
-
|
|
594
|
-
/**
|
|
595
|
-
* Scoped to a single edit: identifies a sequences of nodes that can be moved into a trait.
|
|
596
|
-
*
|
|
597
|
-
* Within a given Edit, any DetachedSequenceId must be a source at most once, and a destination at most once.
|
|
598
|
-
* If used as a source, it must be after it is used as a destination.
|
|
599
|
-
* If this is violated, the Edit is considered malformed.
|
|
600
|
-
* @alpha
|
|
601
|
-
*/
|
|
602
|
-
export declare type DetachedSequenceId = number & {
|
|
603
|
-
readonly DetachedSequenceId: 'f7d7903a-194e-45e7-8e82-c9ef4333577d';
|
|
604
|
-
};
|
|
605
|
-
|
|
606
|
-
/**
|
|
607
|
-
* {@inheritdoc Detach}
|
|
608
|
-
* @alpha
|
|
609
|
-
*/
|
|
610
|
-
export declare interface DetachInternal extends Omit<DetachInternal_0_0_2, 'source'> {
|
|
611
|
-
/** {@inheritdoc Detach.source } */
|
|
612
|
-
readonly source: StableRangeInternal;
|
|
613
|
-
}
|
|
614
|
-
|
|
615
|
-
/**
|
|
616
|
-
* {@inheritdoc Detach}
|
|
617
|
-
* @alpha
|
|
618
|
-
*/
|
|
619
|
-
export declare interface DetachInternal_0_0_2 {
|
|
620
|
-
/** {@inheritdoc Detach.destination } */
|
|
621
|
-
readonly destination?: DetachedSequenceId;
|
|
622
|
-
/** {@inheritdoc Detach.source } */
|
|
623
|
-
readonly source: StableRangeInternal_0_0_2;
|
|
624
|
-
/** {@inheritdoc Detach."type" } */
|
|
625
|
-
readonly type: typeof ChangeTypeInternal.Detach;
|
|
626
|
-
}
|
|
627
|
-
|
|
628
|
-
/**
|
|
629
|
-
* Checkout that always stays up to date with the SharedTree.
|
|
630
|
-
* This means that {@link EagerCheckout.waitForPendingUpdates} is always a no-op since EagerCheckout is always up to date.
|
|
631
|
-
* @sealed
|
|
632
|
-
* @alpha
|
|
633
|
-
*/
|
|
634
|
-
export declare class EagerCheckout extends Checkout {
|
|
635
|
-
/**
|
|
636
|
-
* @param tree - the tree
|
|
637
|
-
*/
|
|
638
|
-
constructor(tree: SharedTree);
|
|
639
|
-
protected get latestCommittedView(): RevisionView;
|
|
640
|
-
waitForPendingUpdates(): Promise<void>;
|
|
641
|
-
waitForEditsToSubmit(): Promise<void>;
|
|
642
|
-
}
|
|
643
|
-
|
|
644
|
-
/**
|
|
645
|
-
* A collection of changes to the tree that are applied atomically along with a unique identifier for the edit.
|
|
646
|
-
* If any individual change fails to apply, the entire Edit will fail to apply.
|
|
647
|
-
* @alpha
|
|
648
|
-
*/
|
|
649
|
-
export declare interface Edit<TChange> extends EditBase<TChange> {
|
|
650
|
-
/**
|
|
651
|
-
* Unique identifier for this edit. Must never be reused.
|
|
652
|
-
* Used for referencing and de-duplicating edits.
|
|
653
|
-
*/
|
|
654
|
-
readonly id: EditId;
|
|
655
|
-
}
|
|
656
|
-
|
|
657
|
-
/**
|
|
658
|
-
* The outcome of an edit.
|
|
659
|
-
* @alpha
|
|
660
|
-
*/
|
|
661
|
-
export declare type EditApplicationOutcome = {
|
|
662
|
-
/**
|
|
663
|
-
* The revision view resulting from the edit.
|
|
664
|
-
*/
|
|
665
|
-
readonly view: RevisionView;
|
|
666
|
-
/**
|
|
667
|
-
* The status code for the edit that produced the revision.
|
|
668
|
-
*/
|
|
669
|
-
readonly status: EditStatus.Applied;
|
|
670
|
-
} | {
|
|
671
|
-
/**
|
|
672
|
-
* The revision view resulting from the edit.
|
|
673
|
-
*/
|
|
674
|
-
readonly failure: TransactionInternal.Failure;
|
|
675
|
-
/**
|
|
676
|
-
* The status code for the edit that produced the revision.
|
|
677
|
-
*/
|
|
678
|
-
readonly status: EditStatus.Invalid | EditStatus.Malformed;
|
|
679
|
-
};
|
|
680
|
-
|
|
681
|
-
/**
|
|
682
|
-
* The information included in an edit.
|
|
683
|
-
* @alpha
|
|
684
|
-
*/
|
|
685
|
-
export declare interface EditBase<TChange> {
|
|
686
|
-
/**
|
|
687
|
-
* Actual changes to apply.
|
|
688
|
-
* Applied in order as part of a single transaction.
|
|
689
|
-
*/
|
|
690
|
-
readonly changes: readonly TChange[];
|
|
691
|
-
/**
|
|
692
|
-
* For edits which are being re-issued due to a conflict, the number of times this edit has already been attempted.
|
|
693
|
-
* Undefined means 0.
|
|
694
|
-
*/
|
|
695
|
-
readonly pastAttemptCount?: number;
|
|
696
|
-
}
|
|
697
|
-
|
|
698
|
-
/**
|
|
699
|
-
* The arguments included when the EditCommitted SharedTreeEvent is emitted.
|
|
700
|
-
* @alpha
|
|
701
|
-
*/
|
|
702
|
-
export declare interface EditCommittedEventArguments {
|
|
703
|
-
/** The ID of the edit committed. */
|
|
704
|
-
readonly editId: EditId;
|
|
705
|
-
/** Whether or not this is a local edit. */
|
|
706
|
-
readonly local: boolean;
|
|
707
|
-
/** The tree the edit was committed on. Required for local edit events handled by SharedTreeUndoRedoHandler. */
|
|
708
|
-
readonly tree: SharedTree;
|
|
709
|
-
}
|
|
710
|
-
|
|
711
|
-
/**
|
|
712
|
-
* Expected type for a handler of the `EditCommitted` event.
|
|
713
|
-
* @alpha
|
|
714
|
-
*/
|
|
715
|
-
export declare type EditCommittedHandler = (args: EditCommittedEventArguments) => void;
|
|
716
|
-
|
|
717
|
-
/* Excluded from this release type: EditHandle */
|
|
718
|
-
|
|
719
|
-
/**
|
|
720
|
-
* Edit identifier
|
|
721
|
-
* @alpha
|
|
722
|
-
*/
|
|
723
|
-
export declare type EditId = UuidString & {
|
|
724
|
-
readonly EditId: '56897beb-53e4-4e66-85da-4bf5cd5d0d49';
|
|
725
|
-
};
|
|
726
|
-
|
|
727
|
-
/* Excluded from this release type: EditingResult */
|
|
728
|
-
|
|
729
|
-
/**
|
|
730
|
-
* Basic result of applying a transaction.
|
|
731
|
-
* @alpha
|
|
732
|
-
*/
|
|
733
|
-
export declare interface EditingResultBase {
|
|
734
|
-
/**
|
|
735
|
-
* The final status of the transaction.
|
|
736
|
-
*/
|
|
737
|
-
readonly status: EditStatus;
|
|
738
|
-
/**
|
|
739
|
-
* The valid changes applied as part of the transaction.
|
|
740
|
-
*/
|
|
741
|
-
readonly changes: readonly ChangeInternal[];
|
|
742
|
-
/**
|
|
743
|
-
* The editing steps applied as part of the transaction.
|
|
744
|
-
*/
|
|
745
|
-
readonly steps: readonly ReconciliationChange[];
|
|
746
|
-
/**
|
|
747
|
-
* The revision preceding the transaction.
|
|
748
|
-
*/
|
|
749
|
-
readonly before: RevisionView;
|
|
750
|
-
}
|
|
751
|
-
|
|
752
|
-
/* Excluded from this release type: EditLogSummary */
|
|
753
|
-
|
|
754
|
-
/**
|
|
755
|
-
* The status code of an attempt to apply the changes in an Edit.
|
|
756
|
-
* @alpha
|
|
757
|
-
*/
|
|
758
|
-
export declare enum EditStatus {
|
|
759
|
-
/**
|
|
760
|
-
* The edit contained one or more malformed changes (e.g. was missing required fields such as `id`),
|
|
761
|
-
* or contained a sequence of changes that could not possibly be applied sequentially without error
|
|
762
|
-
* (e.g. an edit which tries to insert the same detached node twice).
|
|
763
|
-
*/
|
|
764
|
-
Malformed = 0,
|
|
765
|
-
/**
|
|
766
|
-
* The edit contained a well-formed sequence of changes that couldn't be applied to the current view,
|
|
767
|
-
* generally because concurrent changes caused one or more merge conflicts.
|
|
768
|
-
*/
|
|
769
|
-
Invalid = 1,
|
|
770
|
-
/**
|
|
771
|
-
* The edit was applied to the current view successfully.
|
|
772
|
-
*/
|
|
773
|
-
Applied = 2
|
|
774
|
-
}
|
|
775
|
-
|
|
776
|
-
/**
|
|
777
|
-
* The result of validation of an Edit.
|
|
778
|
-
* @alpha
|
|
779
|
-
*/
|
|
780
|
-
export declare enum EditValidationResult {
|
|
781
|
-
/**
|
|
782
|
-
* The edit contained one or more malformed changes (e.g. was missing required fields such as `id`),
|
|
783
|
-
* or contained a sequence of changes that could not possibly be applied sequentially without error
|
|
784
|
-
* (e.g. an edit which tries to insert the same detached node twice).
|
|
785
|
-
*/
|
|
786
|
-
Malformed = 0,
|
|
787
|
-
/**
|
|
788
|
-
* The edit is well-formed but cannot be applied to the current view, generally because concurrent changes
|
|
789
|
-
* caused one or more merge conflicts.
|
|
790
|
-
* For example, the edit refers to the `StablePlace` after node `C`, but `C` has since been deleted.
|
|
791
|
-
*/
|
|
792
|
-
Invalid = 1,
|
|
793
|
-
/**
|
|
794
|
-
* The edit is well-formed and can be applied to the current view.
|
|
795
|
-
*/
|
|
796
|
-
Valid = 2
|
|
797
|
-
}
|
|
798
|
-
|
|
799
|
-
/* Excluded from this release type: EditWithoutId */
|
|
800
|
-
|
|
801
|
-
/* Excluded from this release type: FailedEditingResult */
|
|
802
|
-
|
|
803
|
-
/* Excluded from this release type: FailingTransactionState */
|
|
804
|
-
|
|
805
|
-
/**
|
|
806
|
-
* A compressed ID that is local to a document. Stable across all revisions of a document starting from the one in which it was created.
|
|
807
|
-
* It should not be persisted outside of the history as it can only be decompressed in the context of the originating document.
|
|
808
|
-
* If external persistence is needed (e.g. by a client), a StableId should be used instead.
|
|
809
|
-
* @alpha
|
|
810
|
-
*/
|
|
811
|
-
export declare type FinalCompressedId = number & {
|
|
812
|
-
readonly FinalCompressedId: '5d83d1e2-98b7-4e4e-a889-54c855cfa73d';
|
|
813
|
-
readonly OpNormalized: '9209432d-a959-4df7-b2ad-767ead4dbcae';
|
|
814
|
-
};
|
|
815
|
-
|
|
816
|
-
/* Excluded from this release type: FluidEditHandle */
|
|
817
|
-
|
|
818
|
-
/**
|
|
819
|
-
* An immutable forest of ForestNode.
|
|
820
|
-
* Enforces single parenting, and allows querying the parent.
|
|
821
|
-
* @alpha
|
|
822
|
-
*/
|
|
823
|
-
export declare class Forest {
|
|
824
|
-
/**
|
|
825
|
-
* Contains the nodes in the forest.
|
|
826
|
-
* Used as an immutable data-structure: must not be modified.
|
|
827
|
-
*/
|
|
828
|
-
private readonly nodes;
|
|
829
|
-
/**
|
|
830
|
-
* If true, consistency checks will be applied after forest operations.
|
|
831
|
-
*/
|
|
832
|
-
private readonly expensiveValidation;
|
|
833
|
-
/**
|
|
834
|
-
* Caller must ensure provided BTrees are not modified.
|
|
835
|
-
* Will not modify the BTrees.
|
|
836
|
-
*/
|
|
837
|
-
private constructor();
|
|
838
|
-
/**
|
|
839
|
-
* Construct a new forest without reusing nodes from a previous one.
|
|
840
|
-
*/
|
|
841
|
-
private constructor();
|
|
842
|
-
/**
|
|
843
|
-
* Creates a new Forest.
|
|
844
|
-
*/
|
|
845
|
-
static create(expensiveValidation?: boolean): Forest;
|
|
846
|
-
/**
|
|
847
|
-
* Returns the number of nodes in the forest.
|
|
848
|
-
*/
|
|
849
|
-
get size(): number;
|
|
850
|
-
/**
|
|
851
|
-
* Adds the supplied nodes to the forest. The nodes' IDs must be unique in the forest.
|
|
852
|
-
* @param nodes - the sequence of nodes to add to the forest. If any of them have children which exist in the forest already, those
|
|
853
|
-
* children will be parented. Any trait arrays present in a node must be non-empty. The nodes may be provided in any order.
|
|
854
|
-
*/
|
|
855
|
-
add(nodes: Iterable<ForestNode>): Forest;
|
|
856
|
-
/**
|
|
857
|
-
* Parents a set of nodes already in the forest at a specified location within a trait.
|
|
858
|
-
* @param parentId - the id of the parent under which to insert the new nodes
|
|
859
|
-
* @param label - the label of the trait under which to insert the new nodes
|
|
860
|
-
* @param index - the index in the trait after which to insert the new nodes
|
|
861
|
-
* @param childIds - the ids of the nodes to insert
|
|
862
|
-
*/
|
|
863
|
-
attachRangeOfChildren(parentId: NodeId, label: TraitLabel, index: number, childIds: readonly NodeId[]): Forest;
|
|
864
|
-
/**
|
|
865
|
-
* Detaches a range of nodes from their parent. The detached nodes remain in the `Forest`.
|
|
866
|
-
* @param parentId - the id of the parent from which to detach the nodes
|
|
867
|
-
* @param label - the label of the trait from which to detach the nodes
|
|
868
|
-
* @param startIndex - the index of the first node in the range to detach
|
|
869
|
-
* @param endIndex - the index after the last node in the range to detach
|
|
870
|
-
* @returns a new `Forest` with the nodes detached, and a list of the ids of the nodes that were detached
|
|
871
|
-
*/
|
|
872
|
-
detachRangeOfChildren(parentId: NodeId, label: TraitLabel, startIndex: number, endIndex: number): {
|
|
873
|
-
forest: Forest;
|
|
874
|
-
detached: readonly NodeId[];
|
|
875
|
-
};
|
|
876
|
-
/**
|
|
877
|
-
* Replaces a node's value. The node must exist in this `Forest`.
|
|
878
|
-
* @param nodeId - the id of the node
|
|
879
|
-
* @param value - the new value
|
|
880
|
-
*/
|
|
881
|
-
setValue(nodeId: NodeId, value: Payload | null): Forest;
|
|
882
|
-
/**
|
|
883
|
-
* @returns true if the node associated with `id` exists in this forest, otherwise false
|
|
884
|
-
*/
|
|
885
|
-
has(id: NodeId): boolean;
|
|
886
|
-
/**
|
|
887
|
-
* @returns the node associated with `id`. Should not be used if there is no node with the provided id.
|
|
888
|
-
*/
|
|
889
|
-
get(id: NodeId): ForestNode;
|
|
890
|
-
/**
|
|
891
|
-
* @returns the node associated with `id`, or undefined if there is none
|
|
892
|
-
*/
|
|
893
|
-
tryGet(id: NodeId): ForestNode | undefined;
|
|
894
|
-
/**
|
|
895
|
-
* Deletes every node in ids (each of which must be unparented)
|
|
896
|
-
* @param ids - The IDs of the nodes to delete.
|
|
897
|
-
* @param deleteChildren - If true, recursively deletes descendants. Otherwise, leaves children unparented.
|
|
898
|
-
*/
|
|
899
|
-
delete(ids: Iterable<NodeId>, deleteChildren: boolean): Forest;
|
|
900
|
-
private deleteRecursive;
|
|
901
|
-
/**
|
|
902
|
-
* Checks that the metadata is correct, and the items form a forest.
|
|
903
|
-
* This is an expensive O(map size) operation.
|
|
904
|
-
*/
|
|
905
|
-
assertConsistent(): void;
|
|
906
|
-
/**
|
|
907
|
-
* @returns the parent of `id`. Should not be used if there is no node with id or if id refers to the root node.
|
|
908
|
-
*/
|
|
909
|
-
getParent(id: NodeId): ParentData;
|
|
910
|
-
/**
|
|
911
|
-
* @returns undefined iff root, otherwise the parent of `id`.
|
|
912
|
-
*/
|
|
913
|
-
tryGetParent(id: NodeId): ParentData | undefined;
|
|
914
|
-
/**
|
|
915
|
-
* Compares two forests for equality.
|
|
916
|
-
* @param forest - the other forest to compare to this one
|
|
917
|
-
* @param comparator - a function which returns true if two objects of type ForestNode are equivalent, false otherwise
|
|
918
|
-
* @returns true iff the forests are equal.
|
|
919
|
-
*/
|
|
920
|
-
equals(forest: Forest): boolean;
|
|
921
|
-
/**
|
|
922
|
-
* Calculate the difference between two forests.
|
|
923
|
-
* @param forest - the other forest to compare to this one
|
|
924
|
-
* @param comparator - a function which returns true if two objects of type ForestNode are equivalent, false otherwise
|
|
925
|
-
* @returns A {@link Delta} listing which nodes must be changed, added, and removed to get from `this` to `forest`.
|
|
926
|
-
*/
|
|
927
|
-
delta(forest: Forest): Delta<NodeId>;
|
|
928
|
-
}
|
|
929
|
-
|
|
930
|
-
/**
|
|
931
|
-
* A node that can be contained within a Forest
|
|
932
|
-
* @alpha
|
|
933
|
-
*/
|
|
934
|
-
export declare interface ForestNode extends NodeData<NodeId> {
|
|
935
|
-
readonly traits: ReadonlyMap<TraitLabel, readonly NodeId[]>;
|
|
936
|
-
}
|
|
937
|
-
|
|
938
|
-
/* Excluded from this release type: GenericTransaction */
|
|
939
|
-
|
|
940
|
-
/* Excluded from this release type: GenericTransactionPolicy */
|
|
941
|
-
|
|
942
|
-
/* Excluded from this release type: getSerializedUploadedEditChunkContents */
|
|
943
|
-
|
|
944
|
-
/* Excluded from this release type: getTraitLocationOfRange */
|
|
945
|
-
|
|
946
|
-
/**
|
|
947
|
-
* An object which may have traits with children of the given type underneath it
|
|
948
|
-
* @alpha
|
|
949
|
-
*/
|
|
950
|
-
export declare interface HasTraits<TChild> {
|
|
951
|
-
readonly traits: TraitMap<TChild>;
|
|
952
|
-
}
|
|
953
|
-
|
|
954
|
-
/**
|
|
955
|
-
* An object which may have traits with children of the given type underneath it
|
|
956
|
-
* @alpha
|
|
957
|
-
*/
|
|
958
|
-
export declare interface HasVariadicTraits<TChild> {
|
|
959
|
-
readonly traits?: {
|
|
960
|
-
readonly [key: string]: TChild | TreeNodeSequence<TChild> | undefined;
|
|
961
|
-
};
|
|
962
|
-
}
|
|
963
|
-
|
|
964
|
-
/**
|
|
965
|
-
* Events which may be emitted by `Checkout`. See {@link CheckoutEvent} for documentation of event semantics.
|
|
966
|
-
* @alpha
|
|
967
|
-
*/
|
|
968
|
-
export declare interface ICheckoutEvents extends IErrorEvent {
|
|
969
|
-
(event: 'viewChange', listener: (before: TreeView, after: TreeView) => void): any;
|
|
970
|
-
}
|
|
971
|
-
|
|
972
|
-
/* Excluded from this release type: IMigrationEvent */
|
|
973
|
-
|
|
974
|
-
/**
|
|
975
|
-
* The initial tree.
|
|
976
|
-
* @alpha
|
|
977
|
-
*/
|
|
978
|
-
export declare const initialTree: ChangeNode_0_0_2;
|
|
979
|
-
|
|
980
|
-
/**
|
|
981
|
-
* Inserts a sequence of nodes at the specified destination.
|
|
982
|
-
* The source can be constructed either by a Build (used to insert new nodes) or a Detach (amounts to a "move" operation).
|
|
983
|
-
* @alpha
|
|
984
|
-
*/
|
|
985
|
-
export declare interface Insert {
|
|
986
|
-
readonly destination: StablePlace;
|
|
987
|
-
readonly source: number;
|
|
988
|
-
readonly type: typeof ChangeType.Insert;
|
|
989
|
-
}
|
|
990
|
-
|
|
991
|
-
/**
|
|
992
|
-
* {@inheritdoc (Insert:interface)}
|
|
993
|
-
* @alpha
|
|
994
|
-
*/
|
|
995
|
-
export declare interface InsertInternal extends Omit<InsertInternal_0_0_2, 'destination'> {
|
|
996
|
-
/** {@inheritdoc (Insert:interface).destination } */
|
|
997
|
-
readonly destination: StablePlaceInternal;
|
|
998
|
-
}
|
|
999
|
-
|
|
1000
|
-
/**
|
|
1001
|
-
* {@inheritdoc (Insert:interface)}
|
|
1002
|
-
* @alpha
|
|
1003
|
-
*/
|
|
1004
|
-
export declare interface InsertInternal_0_0_2 {
|
|
1005
|
-
/** {@inheritdoc (Insert:interface).destination } */
|
|
1006
|
-
readonly destination: StablePlaceInternal_0_0_2;
|
|
1007
|
-
/** {@inheritdoc (Insert:interface).source } */
|
|
1008
|
-
readonly source: DetachedSequenceId;
|
|
1009
|
-
/** {@inheritdoc (Insert:interface)."type" } */
|
|
1010
|
-
readonly type: typeof ChangeTypeInternal.Insert;
|
|
1011
|
-
}
|
|
1012
|
-
|
|
1013
|
-
/**
|
|
1014
|
-
* This type should be used as an opaque handle in the public API for `ChangeInternal` objects.
|
|
1015
|
-
* This is useful for supporting public APIs which involve working with a tree's edit history,
|
|
1016
|
-
* which will involve changes that have already been internalized.
|
|
1017
|
-
* @alpha
|
|
1018
|
-
*/
|
|
1019
|
-
export declare interface InternalizedChange {
|
|
1020
|
-
InternalChangeBrand: '2cae1045-61cf-4ef7-a6a3-8ad920cb7ab3';
|
|
1021
|
-
}
|
|
1022
|
-
|
|
1023
|
-
/* Excluded from this release type: InternedStringId */
|
|
1024
|
-
|
|
1025
|
-
/* Excluded from this release type: isDetachedSequenceId */
|
|
1026
|
-
|
|
1027
|
-
/**
|
|
1028
|
-
* Events which may be emitted by `SharedTree`. See {@link SharedTreeEvent} for documentation of event semantics.
|
|
1029
|
-
* @alpha
|
|
1030
|
-
*/
|
|
1031
|
-
export declare interface ISharedTreeEvents extends ISharedObjectEvents {
|
|
1032
|
-
(event: 'committedEdit', listener: EditCommittedHandler): any;
|
|
1033
|
-
(event: 'appliedSequencedEdit', listener: SequencedEditAppliedHandler): any;
|
|
1034
|
-
}
|
|
1035
|
-
|
|
1036
|
-
/* Excluded from this release type: IShim */
|
|
1037
|
-
|
|
1038
|
-
/* Excluded from this release type: isSharedTreeEvent */
|
|
1039
|
-
|
|
1040
|
-
/* Excluded from this release type: LazyCheckout */
|
|
1041
|
-
|
|
1042
|
-
/**
|
|
1043
|
-
* A compressed ID that is local to a session (can only be decompressed when paired with a SessionId).
|
|
1044
|
-
* It should not be persisted outside of the history as it can only be decompressed in the context of the originating session.
|
|
1045
|
-
* If external persistence is needed (e.g. by a client), a StableId should be used instead.
|
|
1046
|
-
* @alpha
|
|
1047
|
-
*/
|
|
1048
|
-
export declare type LocalCompressedId = number & {
|
|
1049
|
-
readonly LocalCompressedId: '6fccb42f-e2a4-4243-bd29-f13d12b9c6d1';
|
|
1050
|
-
} & SessionUnique;
|
|
1051
|
-
|
|
1052
|
-
/**
|
|
1053
|
-
* Creates `RevisionView`s for the revisions in an `EditLog`
|
|
1054
|
-
* @alpha
|
|
1055
|
-
*/
|
|
1056
|
-
export declare interface LogViewer {
|
|
1057
|
-
/**
|
|
1058
|
-
* Returns the `TreeView` output associated with the largest revision in `editLog` less than (but not equal to) the supplied revision.
|
|
1059
|
-
*
|
|
1060
|
-
* For example:
|
|
1061
|
-
*
|
|
1062
|
-
* - revision 0 returns the initialRevision.
|
|
1063
|
-
*
|
|
1064
|
-
* - revision 1 returns the output of editLog[0] (or initialRevision if there is no edit 0).
|
|
1065
|
-
*
|
|
1066
|
-
* - revision Number.POSITIVE_INFINITY returns the newest revision.
|
|
1067
|
-
*
|
|
1068
|
-
* @deprecated Edit virtualization is no longer supported, use {@link LogViewer.getRevisionViewInMemory}
|
|
1069
|
-
*/
|
|
1070
|
-
getRevisionView(revision: Revision): Promise<RevisionView>;
|
|
1071
|
-
/**
|
|
1072
|
-
* Returns the `TreeView` output associated with the largest revision in `editLog` less than (but not equal to) the supplied revision.
|
|
1073
|
-
* Can only be used to retrieve revisions added during the current sessions.
|
|
1074
|
-
*
|
|
1075
|
-
* For example:
|
|
1076
|
-
*
|
|
1077
|
-
* - revision 0 returns the initialRevision.
|
|
1078
|
-
*
|
|
1079
|
-
* - revision 1 returns the output of editLog[0] (or initialRevision if there is no edit 0).
|
|
1080
|
-
*
|
|
1081
|
-
* - revision Number.POSITIVE_INFINITY returns the newest revision.
|
|
1082
|
-
*
|
|
1083
|
-
* @deprecated Edit virtualization is no longer supported so the 'inSession' APIs will be removed, use {@link LogViewer.getRevisionViewInMemory}
|
|
1084
|
-
*/
|
|
1085
|
-
getRevisionViewInSession(revision: Revision): RevisionView;
|
|
1086
|
-
/**
|
|
1087
|
-
* Returns the `TreeView` output associated with the largest revision in `editLog` less than (but not equal to) the supplied revision.
|
|
1088
|
-
* Can only be used to retrieve revisions added during the current session that have not been evicted from `editLog`.
|
|
1089
|
-
*
|
|
1090
|
-
* For example:
|
|
1091
|
-
*
|
|
1092
|
-
* - revision 0 returns the oldest edit in the log (which might be initialRevision).
|
|
1093
|
-
*
|
|
1094
|
-
* - revision 1 returns the output of editLog[0] (or initialRevision if there is no edit 0).
|
|
1095
|
-
*
|
|
1096
|
-
* - revision Number.POSITIVE_INFINITY returns the newest revision.
|
|
1097
|
-
*/
|
|
1098
|
-
getRevisionViewInMemory(revision: Revision): RevisionView;
|
|
1099
|
-
}
|
|
1100
|
-
|
|
1101
|
-
/* Excluded from this release type: MergeHealthStats */
|
|
1102
|
-
|
|
1103
|
-
/* Excluded from this release type: MigrationShim */
|
|
1104
|
-
|
|
1105
|
-
/* Excluded from this release type: MigrationShimFactory */
|
|
1106
|
-
|
|
1107
|
-
/**
|
|
1108
|
-
* The fields required by a node in a tree
|
|
1109
|
-
* @alpha
|
|
1110
|
-
*/
|
|
1111
|
-
export declare interface NodeData<TId> {
|
|
1112
|
-
/**
|
|
1113
|
-
* A payload of arbitrary serializable data
|
|
1114
|
-
*/
|
|
1115
|
-
readonly payload?: Payload;
|
|
1116
|
-
/**
|
|
1117
|
-
* The meaning of this node.
|
|
1118
|
-
* Provides contexts/semantics for this node and its content.
|
|
1119
|
-
* Typically use to associate a node with metadata (including a schema) and source code (types, behaviors, etc).
|
|
1120
|
-
*/
|
|
1121
|
-
readonly definition: Definition;
|
|
1122
|
-
/**
|
|
1123
|
-
* Identifier which can be used to refer to this Node.
|
|
1124
|
-
*/
|
|
1125
|
-
readonly identifier: TId;
|
|
1126
|
-
}
|
|
1127
|
-
|
|
1128
|
-
/**
|
|
1129
|
-
* Node identifier.
|
|
1130
|
-
* Identifies a node within a document.
|
|
1131
|
-
* @alpha
|
|
1132
|
-
*/
|
|
1133
|
-
export declare type NodeId = number & SessionSpaceCompressedId & NodeIdBrand;
|
|
1134
|
-
|
|
1135
|
-
/**
|
|
1136
|
-
* @alpha
|
|
1137
|
-
*/
|
|
1138
|
-
export declare interface NodeIdBrand {
|
|
1139
|
-
readonly NodeId: 'e53e7d6b-c8b9-431a-8805-4843fc639342';
|
|
1140
|
-
}
|
|
1141
|
-
|
|
1142
|
-
/**
|
|
1143
|
-
* An object which can generate node IDs and convert node IDs between compressed and stable variants
|
|
1144
|
-
* @alpha
|
|
1145
|
-
*/
|
|
1146
|
-
export declare interface NodeIdContext extends NodeIdGenerator, NodeIdConverter {
|
|
1147
|
-
}
|
|
1148
|
-
|
|
1149
|
-
/**
|
|
1150
|
-
* An object which can convert node IDs between compressed and stable variants
|
|
1151
|
-
* @alpha
|
|
1152
|
-
*/
|
|
1153
|
-
export declare interface NodeIdConverter {
|
|
1154
|
-
/**
|
|
1155
|
-
* Given a NodeId, returns the corresponding stable ID or throws if the supplied node ID was not generated with this tree (`NodeId`s
|
|
1156
|
-
* may not be used across SharedTree instances, see `generateNodeId` for more).
|
|
1157
|
-
* The returned value will be a UUID, unless the creation of `id` used an override string (see `generateNodeId` for more).
|
|
1158
|
-
* The result is safe to persist and re-use across `SharedTree` instances, unlike `NodeId`.
|
|
1159
|
-
*/
|
|
1160
|
-
convertToStableNodeId(id: NodeId): StableNodeId;
|
|
1161
|
-
/**
|
|
1162
|
-
* Given a NodeId, attempt to return the corresponding stable ID.
|
|
1163
|
-
* The returned value will be a UUID, unless the creation of `id` used an override string (see `generateNodeId` for more).
|
|
1164
|
-
* The returned stable ID is undefined if `id` was never created with this SharedTree. If a stable ID is returned, this does not imply
|
|
1165
|
-
* that there is a node with `id` in the current revision of the tree, only that `id` was at some point generated by some instance of
|
|
1166
|
-
* this tree.
|
|
1167
|
-
*/
|
|
1168
|
-
tryConvertToStableNodeId(id: NodeId): StableNodeId | undefined;
|
|
1169
|
-
/**
|
|
1170
|
-
* Given a stable ID, return the corresponding NodeId or throws if the supplied stable ID was never generated with this tree, either
|
|
1171
|
-
* as a UUID corresponding to a `NodeId` or as an override passed to `generateNodeId`.
|
|
1172
|
-
* If a stable ID is returned, this does not imply that there is a node with `id` in the current revision of the tree, only that
|
|
1173
|
-
* `id` was at some point generated by an instance of this SharedTree.
|
|
1174
|
-
*/
|
|
1175
|
-
convertToNodeId(id: StableNodeId): NodeId;
|
|
1176
|
-
/**
|
|
1177
|
-
* Given a stable ID, return the corresponding NodeId or return undefined if the supplied stable ID was never generated with this tree,
|
|
1178
|
-
* either as a UUID corresponding to a `NodeId` or as an override passed to `generateNodeId`.
|
|
1179
|
-
* If a stable ID is returned, this does not imply that there is a node with `id` in the current revision of the tree, only that
|
|
1180
|
-
* `id` was at some point generated by an instance of this SharedTree.
|
|
1181
|
-
*/
|
|
1182
|
-
tryConvertToNodeId(id: StableNodeId): NodeId | undefined;
|
|
1183
|
-
}
|
|
1184
|
-
|
|
1185
|
-
/**
|
|
1186
|
-
* An object which can generate node IDs
|
|
1187
|
-
* @alpha
|
|
1188
|
-
*/
|
|
1189
|
-
export declare interface NodeIdGenerator {
|
|
1190
|
-
/**
|
|
1191
|
-
* Generates a node identifier.
|
|
1192
|
-
* The returned IDs may be used as the identifier of a node in the SharedTree.
|
|
1193
|
-
* `NodeId`s are *always* unique and stable within the scope of the tree and session that generated them. They are *not* unique within
|
|
1194
|
-
* a Fluid container, and *cannot* be compared across instances of a SharedTree. They are *not* stable across sessions/lifetimes of a
|
|
1195
|
-
* SharedTree, and *cannot* be persisted (e.g. stored in payloads, uploaded in blobs, etc.). If stable persistence is needed,
|
|
1196
|
-
* NodeIdConverter.convertToStableNodeId may be used to return a corresponding UUID that is globally unique and stable.
|
|
1197
|
-
* @param override - if supplied, calls to `convertToStableNodeId` using the returned node ID will return the override instead of
|
|
1198
|
-
* the UUID. Calls to `generateNodeId` with the same override always return the same ID. Performance note: passing an override string
|
|
1199
|
-
* incurs a storage cost that is significantly higher that a node ID without one, and should be avoided if possible.
|
|
1200
|
-
*/
|
|
1201
|
-
generateNodeId(override?: string): NodeId;
|
|
1202
|
-
}
|
|
1203
|
-
|
|
1204
|
-
/* Excluded from this release type: NodeInTrait */
|
|
1205
|
-
|
|
1206
|
-
/**
|
|
1207
|
-
* An ordered set of Edits associated with a SharedTree.
|
|
1208
|
-
* Supports fast lookup of edits by ID and enforces idempotence.
|
|
1209
|
-
* @sealed
|
|
1210
|
-
* @alpha
|
|
1211
|
-
*/
|
|
1212
|
-
export declare interface OrderedEditSet<TChange = unknown> {
|
|
1213
|
-
/**
|
|
1214
|
-
* The length of this `OrderedEditSet`.
|
|
1215
|
-
*/
|
|
1216
|
-
readonly length: number;
|
|
1217
|
-
/**
|
|
1218
|
-
* The edit IDs of all edits in the log.
|
|
1219
|
-
*/
|
|
1220
|
-
readonly editIds: readonly EditId[];
|
|
1221
|
-
/**
|
|
1222
|
-
* @returns the index of the edit with the given editId within this `OrderedEditSet`.
|
|
1223
|
-
*/
|
|
1224
|
-
getIndexOfId(editId: EditId): number;
|
|
1225
|
-
/**
|
|
1226
|
-
* @returns the id of the edit at the given index within this 'OrderedEditSet'.
|
|
1227
|
-
*/
|
|
1228
|
-
getIdAtIndex(index: number): EditId;
|
|
1229
|
-
/**
|
|
1230
|
-
* @returns the index of the edit with the given editId within this `OrderedEditSet`, or `undefined` if no such edit exists.
|
|
1231
|
-
*/
|
|
1232
|
-
tryGetIndexOfId(editId: EditId): number | undefined;
|
|
1233
|
-
/**
|
|
1234
|
-
* @returns the edit at the given index within this `OrderedEditSet`.
|
|
1235
|
-
*/
|
|
1236
|
-
tryGetEditAtIndex(index: number): Edit<TChange> | undefined;
|
|
1237
|
-
/**
|
|
1238
|
-
* @returns the edit with the given identifier within this `OrderedEditSet`.
|
|
1239
|
-
*/
|
|
1240
|
-
tryGetEditFromId(editId: EditId): Edit<TChange> | undefined;
|
|
1241
|
-
/**
|
|
1242
|
-
* @returns the Edit associated with the EditId or undefined if there is no such edit in the set.
|
|
1243
|
-
* @deprecated Edit virtualization is no longer supported. Don't use the asynchronous APIs. Instead, use {@link OrderedEditSet.tryGetEditFromId}.
|
|
1244
|
-
*/
|
|
1245
|
-
tryGetEdit(editId: EditId): Promise<Edit<TChange> | undefined>;
|
|
1246
|
-
/**
|
|
1247
|
-
* @returns the edit at the given index within this `OrderedEditSet`.
|
|
1248
|
-
* @deprecated Edit virtualization is no longer supported. Don't use the asynchronous APIs.
|
|
1249
|
-
*/
|
|
1250
|
-
getEditAtIndex(index: number): Promise<Edit<TChange>>;
|
|
1251
|
-
/**
|
|
1252
|
-
* @returns the edit at the given index. Must have been added to the log during the current session.
|
|
1253
|
-
* @deprecated this will be removed in favor of {@link OrderedEditSet.tryGetEditAtIndex}
|
|
1254
|
-
*/
|
|
1255
|
-
getEditInSessionAtIndex(index: number): Edit<TChange>;
|
|
1256
|
-
}
|
|
1257
|
-
|
|
1258
|
-
/**
|
|
1259
|
-
* Information about a ForestNode's parent
|
|
1260
|
-
* @alpha
|
|
1261
|
-
*/
|
|
1262
|
-
export declare interface ParentData {
|
|
1263
|
-
readonly parentId: NodeId;
|
|
1264
|
-
readonly traitParent: TraitLabel;
|
|
1265
|
-
}
|
|
1266
|
-
|
|
1267
|
-
/**
|
|
1268
|
-
* Json compatible representation of a payload storing arbitrary Serializable data.
|
|
1269
|
-
*
|
|
1270
|
-
* Keys starting with "IFluid" are reserved for special use such as the JavaScript feature detection pattern and should not be used.
|
|
1271
|
-
*
|
|
1272
|
-
* See {@link comparePayloads} for equality semantics and related details (like what is allowed to be lost when serializing)
|
|
1273
|
-
*
|
|
1274
|
-
* TODO:#51984: Allow opting into heuristic blobbing in snapshots with a special IFluid key.
|
|
1275
|
-
* @alpha
|
|
1276
|
-
*/
|
|
1277
|
-
export declare type Payload = any;
|
|
1278
|
-
|
|
1279
|
-
/* Excluded from this release type: placeFromStablePlace */
|
|
1280
|
-
|
|
1281
|
-
/* Excluded from this release type: PlaceholderTree */
|
|
1282
|
-
|
|
1283
|
-
/**
|
|
1284
|
-
* Index of a place within a trait.
|
|
1285
|
-
* 0 = before all nodes,
|
|
1286
|
-
* 1 = after first node,
|
|
1287
|
-
* etc.
|
|
1288
|
-
* @alpha
|
|
1289
|
-
*/
|
|
1290
|
-
export declare type PlaceIndex = number & {
|
|
1291
|
-
readonly PlaceIndex: unique symbol;
|
|
1292
|
-
};
|
|
1293
|
-
|
|
1294
|
-
/**
|
|
1295
|
-
* The result of validating a place.
|
|
1296
|
-
* @alpha
|
|
1297
|
-
*/
|
|
1298
|
-
export declare enum PlaceValidationResult {
|
|
1299
|
-
Valid = "Valid",
|
|
1300
|
-
Malformed = "Malformed",
|
|
1301
|
-
SiblingIsRootOrDetached = "SiblingIsRootOrDetached",
|
|
1302
|
-
MissingSibling = "MissingSibling",
|
|
1303
|
-
MissingParent = "MissingParent"
|
|
1304
|
-
}
|
|
1305
|
-
|
|
1306
|
-
/* Excluded from this release type: rangeFromStableRange */
|
|
1307
|
-
|
|
1308
|
-
/**
|
|
1309
|
-
* The result of validating a range.
|
|
1310
|
-
* @alpha
|
|
1311
|
-
*/
|
|
1312
|
-
export declare type RangeValidationResult = RangeValidationResultKind.Valid | RangeValidationResultKind.PlacesInDifferentTraits | RangeValidationResultKind.Inverted | {
|
|
1313
|
-
kind: RangeValidationResultKind.BadPlace;
|
|
1314
|
-
place: StablePlaceInternal;
|
|
1315
|
-
placeFailure: BadPlaceValidationResult;
|
|
1316
|
-
};
|
|
1317
|
-
|
|
1318
|
-
/**
|
|
1319
|
-
* The kinds of result of validating a range.
|
|
1320
|
-
* @alpha
|
|
1321
|
-
*/
|
|
1322
|
-
export declare enum RangeValidationResultKind {
|
|
1323
|
-
Valid = "Valid",
|
|
1324
|
-
BadPlace = "BadPlace",
|
|
1325
|
-
PlacesInDifferentTraits = "PlacesInDifferentTraits",
|
|
1326
|
-
Inverted = "Inverted"
|
|
1327
|
-
}
|
|
1328
|
-
|
|
1329
|
-
/**
|
|
1330
|
-
* A change in the `ReconciliationPath`.
|
|
1331
|
-
* @alpha
|
|
1332
|
-
*/
|
|
1333
|
-
export declare interface ReconciliationChange {
|
|
1334
|
-
/**
|
|
1335
|
-
* The resolved change that was applied during the edit.
|
|
1336
|
-
* Resolved changes are guaranteed to be expressed with valid tree locations instead of anchors that need resolution.
|
|
1337
|
-
*/
|
|
1338
|
-
readonly resolvedChange: ChangeInternal;
|
|
1339
|
-
/**
|
|
1340
|
-
* The resulting view from applying the resolved change.
|
|
1341
|
-
*/
|
|
1342
|
-
readonly after: TransactionView;
|
|
1343
|
-
}
|
|
1344
|
-
|
|
1345
|
-
/**
|
|
1346
|
-
* An edit in the `ReconciliationPath`.
|
|
1347
|
-
* @alpha
|
|
1348
|
-
*/
|
|
1349
|
-
export declare interface ReconciliationEdit {
|
|
1350
|
-
/**
|
|
1351
|
-
* The state before the edit was applied.
|
|
1352
|
-
*/
|
|
1353
|
-
readonly before: TreeView;
|
|
1354
|
-
/**
|
|
1355
|
-
* The state after the edit was applied.
|
|
1356
|
-
*/
|
|
1357
|
-
readonly after: TreeView;
|
|
1358
|
-
/**
|
|
1359
|
-
* The number of changes in the edit.
|
|
1360
|
-
*/
|
|
1361
|
-
readonly length: number;
|
|
1362
|
-
/**
|
|
1363
|
-
* Allows access to change information.
|
|
1364
|
-
* @returns Reconciliation information for the change at the given `index`.
|
|
1365
|
-
*/
|
|
1366
|
-
readonly [index: number]: ReconciliationChange;
|
|
1367
|
-
}
|
|
1368
|
-
|
|
1369
|
-
/**
|
|
1370
|
-
* The path of edits from the revision view where a change was meant to have been applied to the view where the edit that contains the
|
|
1371
|
-
* change is actually applied.
|
|
1372
|
-
* The path only contains edits that were successfully applied.
|
|
1373
|
-
* This path is always empty for a change that has no concurrent edits.
|
|
1374
|
-
* @alpha
|
|
1375
|
-
*/
|
|
1376
|
-
export declare interface ReconciliationPath {
|
|
1377
|
-
/**
|
|
1378
|
-
* The number of edits in the path.
|
|
1379
|
-
*/
|
|
1380
|
-
readonly length: number;
|
|
1381
|
-
/**
|
|
1382
|
-
* Allows access to edit information.
|
|
1383
|
-
* @returns Reconciliation information for the edit at the given `index`.
|
|
1384
|
-
*/
|
|
1385
|
-
readonly [index: number]: ReconciliationEdit;
|
|
1386
|
-
}
|
|
1387
|
-
|
|
1388
|
-
/* Excluded from this release type: Result */
|
|
1389
|
-
|
|
1390
|
-
/**
|
|
1391
|
-
* A revision corresponds to an index in an `EditLog`.
|
|
1392
|
-
*
|
|
1393
|
-
* It is associated with the output `RevisionView` of applying the edit at the index to the previous revision.
|
|
1394
|
-
* For example:
|
|
1395
|
-
*
|
|
1396
|
-
* - revision 0 corresponds to the initialRevision.
|
|
1397
|
-
*
|
|
1398
|
-
* - revision 1 corresponds to the output of editLog[0] applied to the initialRevision.
|
|
1399
|
-
* @alpha
|
|
1400
|
-
*/
|
|
1401
|
-
export declare type Revision = number;
|
|
1402
|
-
|
|
1403
|
-
/**
|
|
1404
|
-
* An immutable view of a distributed tree.
|
|
1405
|
-
* @alpha
|
|
1406
|
-
*/
|
|
1407
|
-
export declare class RevisionView extends TreeView {
|
|
1408
|
-
/**
|
|
1409
|
-
* Constructs a {@link RevisionView} using the supplied tree.
|
|
1410
|
-
* @param root - the root of the tree to use as the contents of the {@link RevisionView}
|
|
1411
|
-
* @param expensiveValidation - whether or not to perform additional validation, e.g. to catch errors when testing
|
|
1412
|
-
*/
|
|
1413
|
-
static fromTree<T extends TreeNode<T, NodeId>>(root: T, expensiveValidation?: boolean): RevisionView;
|
|
1414
|
-
/**
|
|
1415
|
-
* Constructs a {@link RevisionView} using the supplied tree.
|
|
1416
|
-
* @param root - the root of the tree to use as the contents of the `RevisionView`
|
|
1417
|
-
* @param idConverter - the {@link NodeIdConverter} that will recompress the IDs the in the tree
|
|
1418
|
-
* @param expensiveValidation - whether or not to perform additional validation, e.g. to catch errors when testing
|
|
1419
|
-
*/
|
|
1420
|
-
static fromTree<T extends TreeNode<T, StableNodeId>>(root: T, idConverter: NodeIdConverter, expensiveValidation?: boolean): RevisionView;
|
|
1421
|
-
/** Begin a transaction by generating a mutable `TransactionView` from this view */
|
|
1422
|
-
openForTransaction(): TransactionView;
|
|
1423
|
-
equals(view: TreeView): boolean;
|
|
1424
|
-
}
|
|
1425
|
-
|
|
1426
|
-
/**
|
|
1427
|
-
* The arguments included when the {@link SharedTreeEvent.SequencedEditApplied} SharedTreeEvent is emitted.
|
|
1428
|
-
* @alpha
|
|
1429
|
-
*/
|
|
1430
|
-
export declare interface SequencedEditAppliedEventArguments {
|
|
1431
|
-
/** The ID of the edit committed. */
|
|
1432
|
-
readonly edit: Edit<ChangeInternal>;
|
|
1433
|
-
/** Whether or not this was a local edit. */
|
|
1434
|
-
readonly wasLocal: boolean;
|
|
1435
|
-
/** The tree the edit was applied to. */
|
|
1436
|
-
readonly tree: SharedTree;
|
|
1437
|
-
/** The telemetry logger associated with sequenced edit application. */
|
|
1438
|
-
readonly logger: ITelemetryLoggerExt;
|
|
1439
|
-
/** The reconciliation path for the edit. See {@link ReconciliationPath} for details. */
|
|
1440
|
-
readonly reconciliationPath: ReconciliationPath;
|
|
1441
|
-
/** The outcome of the sequenced edit being applied. */
|
|
1442
|
-
readonly outcome: EditApplicationOutcome;
|
|
1443
|
-
}
|
|
1444
|
-
|
|
1445
|
-
/**
|
|
1446
|
-
* Expected type for a handler of the {@link SharedTreeEvent.SequencedEditApplied} event.
|
|
1447
|
-
* @alpha
|
|
1448
|
-
*/
|
|
1449
|
-
export declare type SequencedEditAppliedHandler = (args: SequencedEditAppliedEventArguments) => void;
|
|
1450
|
-
|
|
1451
|
-
/**
|
|
1452
|
-
* A compressed ID that has been normalized into "session space" (see `IdCompressor` for more).
|
|
1453
|
-
* Consumer-facing APIs and data structures should use session-space IDs as their lifetime and equality is stable and tied to the
|
|
1454
|
-
* compressor that produced them.
|
|
1455
|
-
* @alpha
|
|
1456
|
-
*/
|
|
1457
|
-
export declare type SessionSpaceCompressedId = CompressedId & SessionUnique;
|
|
1458
|
-
|
|
1459
|
-
/**
|
|
1460
|
-
* A brand for identity types that are unique within a particular session (SharedTree instance).
|
|
1461
|
-
* @alpha
|
|
1462
|
-
*/
|
|
1463
|
-
export declare interface SessionUnique {
|
|
1464
|
-
readonly SessionUnique: 'cea55054-6b82-4cbf-ad19-1fa645ea3b3e';
|
|
1465
|
-
}
|
|
1466
|
-
|
|
1467
|
-
/* Excluded from this release type: setTrait */
|
|
1468
|
-
|
|
1469
|
-
/**
|
|
1470
|
-
* Modifies the payload of a node.
|
|
1471
|
-
* @alpha
|
|
1472
|
-
*/
|
|
1473
|
-
export declare interface SetValue {
|
|
1474
|
-
readonly nodeToModify: NodeId;
|
|
1475
|
-
/**
|
|
1476
|
-
* Sets or clears the payload.
|
|
1477
|
-
* To improve ease of forwards compatibility, an explicit `null` value is used to represent the clearing of a payload.
|
|
1478
|
-
* SetValue may use `undefined` in future API versions to mean "don't change the payload" (which is useful if e.g. other
|
|
1479
|
-
* fields are added to SetValue that can be changed without altering the payload)
|
|
1480
|
-
*/
|
|
1481
|
-
readonly payload: Payload | null;
|
|
1482
|
-
readonly type: typeof ChangeType.SetValue;
|
|
1483
|
-
}
|
|
1484
|
-
|
|
1485
|
-
/**
|
|
1486
|
-
* {@inheritdoc SetValue}
|
|
1487
|
-
* @alpha
|
|
1488
|
-
*/
|
|
1489
|
-
export declare interface SetValueInternal extends Omit<SetValueInternal_0_0_2, 'nodeToModify'> {
|
|
1490
|
-
/** {@inheritdoc SetValue.nodeToModify } */
|
|
1491
|
-
readonly nodeToModify: NodeId;
|
|
1492
|
-
}
|
|
1493
|
-
|
|
1494
|
-
/**
|
|
1495
|
-
* {@inheritdoc SetValue}
|
|
1496
|
-
* @alpha
|
|
1497
|
-
*/
|
|
1498
|
-
export declare interface SetValueInternal_0_0_2 {
|
|
1499
|
-
/** {@inheritdoc SetValue.nodeToModify } */
|
|
1500
|
-
readonly nodeToModify: StableNodeId;
|
|
1501
|
-
/** {@inheritdoc SetValue.payload } */
|
|
1502
|
-
readonly payload: Payload | null;
|
|
1503
|
-
/** {@inheritdoc SetValue."type" } */
|
|
1504
|
-
readonly type: typeof ChangeTypeInternal.SetValue;
|
|
1505
|
-
}
|
|
1506
|
-
|
|
1507
|
-
/**
|
|
1508
|
-
* A [distributed tree](../Readme.md).
|
|
1509
|
-
* @alpha
|
|
1510
|
-
*/
|
|
1511
|
-
export declare class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeIdContext {
|
|
1512
|
-
private writeFormat;
|
|
1513
|
-
/**
|
|
1514
|
-
* Create a new SharedTree. It will contain the default value (see initialTree).
|
|
1515
|
-
*/
|
|
1516
|
-
static create(runtime: IFluidDataStoreRuntime, id?: string): SharedTree;
|
|
1517
|
-
/**
|
|
1518
|
-
* Get a factory for SharedTree to register with the data store.
|
|
1519
|
-
* @param writeFormat - Determines the format version the SharedTree will write ops and summaries in.
|
|
1520
|
-
* This format may be updated to a newer (supported) version at runtime if a collaborating shared-tree
|
|
1521
|
-
* that was initialized with a newer write version connects to the session. Care must be taken when changing this value,
|
|
1522
|
-
* as a staged rollout must of occurred such that all collaborating clients must have the code to read at least the version
|
|
1523
|
-
* written.
|
|
1524
|
-
* See [the write format documentation](../docs/Write-Format.md) for more information.
|
|
1525
|
-
* @param options - Configuration options for this tree
|
|
1526
|
-
* @returns A factory that creates `SharedTree`s and loads them from storage.
|
|
1527
|
-
*/
|
|
1528
|
-
static getFactory(...args: SharedTreeArgs<WriteFormat.v0_0_2>): SharedTreeFactory;
|
|
1529
|
-
static getFactory(...args: SharedTreeArgs<WriteFormat.v0_1_1>): SharedTreeFactory;
|
|
1530
|
-
/**
|
|
1531
|
-
* Get a factory for SharedTree to register with the data store, using the latest write version and default options.
|
|
1532
|
-
*/
|
|
1533
|
-
static getFactory(): SharedTreeFactory;
|
|
1534
|
-
/**
|
|
1535
|
-
* The UUID used for attribution of nodes created by this SharedTree. All shared trees with a write format of 0.1.1 or
|
|
1536
|
-
* greater have a unique attribution ID which may be configured in the constructor. All other shared trees (i.e. those
|
|
1537
|
-
* with a write format of 0.0.2) use the nil UUID as their attribution ID.
|
|
1538
|
-
*/
|
|
1539
|
-
get attributionId(): AttributionId;
|
|
1540
|
-
/**
|
|
1541
|
-
* This is SharedTree's internal IdCompressor that predates the one in the runtime. If access
|
|
1542
|
-
* to the IdCompressor is needed, this is the one that should be used.
|
|
1543
|
-
*/
|
|
1544
|
-
private idCompressor;
|
|
1545
|
-
private readonly idNormalizer;
|
|
1546
|
-
/** Temporarily created to apply stashed ops from a previous session */
|
|
1547
|
-
private stashedIdCompressor?;
|
|
1548
|
-
private interner;
|
|
1549
|
-
/**
|
|
1550
|
-
* The log of completed edits for this SharedTree.
|
|
1551
|
-
*/
|
|
1552
|
-
private editLog;
|
|
1553
|
-
private readonly editLogSize?;
|
|
1554
|
-
private readonly editEvictionFrequency?;
|
|
1555
|
-
/**
|
|
1556
|
-
* As an implementation detail, SharedTree uses a log viewer that caches views of different revisions.
|
|
1557
|
-
* It is not exposed to avoid accidental correctness issues, but `logViewer` is exposed in order to give clients a way
|
|
1558
|
-
* to access the revision history.
|
|
1559
|
-
*/
|
|
1560
|
-
private cachingLogViewer;
|
|
1561
|
-
/**
|
|
1562
|
-
* Viewer for trees defined by editLog. This allows access to views of the tree at different revisions (various points in time).
|
|
1563
|
-
*/
|
|
1564
|
-
get logViewer(): LogViewer;
|
|
1565
|
-
/**
|
|
1566
|
-
* logger for SharedTree events.
|
|
1567
|
-
*/
|
|
1568
|
-
readonly logger: ITelemetryLoggerExt;
|
|
1569
|
-
private readonly sequencedEditAppliedLogger;
|
|
1570
|
-
private readonly encoder_0_0_2;
|
|
1571
|
-
private encoder_0_1_1;
|
|
1572
|
-
private readonly processEditResult;
|
|
1573
|
-
private readonly processSequencedEditResult;
|
|
1574
|
-
private summarizeHistory;
|
|
1575
|
-
private getHistoryPolicy;
|
|
1576
|
-
/**
|
|
1577
|
-
* Create a new SharedTree.
|
|
1578
|
-
* @param runtime - The runtime the SharedTree will be associated with
|
|
1579
|
-
* @param id - Unique ID for the SharedTree
|
|
1580
|
-
* @param writeFormat - Determines the format version the SharedTree will write ops and summaries in. See [the write format
|
|
1581
|
-
* documentation](../docs/Write-Format.md) for more information.
|
|
1582
|
-
* @param options - Configuration options for this tree
|
|
1583
|
-
*/
|
|
1584
|
-
constructor(runtime: IFluidDataStoreRuntime, id: string, ...args: SharedTreeArgs<WriteFormat.v0_0_2>);
|
|
1585
|
-
constructor(runtime: IFluidDataStoreRuntime, id: string, ...args: SharedTreeArgs<WriteFormat.v0_1_1>);
|
|
1586
|
-
/**
|
|
1587
|
-
* The write format version currently used by this `SharedTree`. This is always initialized to the write format
|
|
1588
|
-
* passed to the tree's constructor, but it may automatically upgrade over time (e.g. when connected to another
|
|
1589
|
-
* SharedTree with a higher write format, or when loading a summary with a higher write format).
|
|
1590
|
-
*/
|
|
1591
|
-
getWriteFormat(): WriteFormat;
|
|
1592
|
-
/**
|
|
1593
|
-
* Computes the oldest client in the quorum, true by default if the container is detached and false by default if the client isn't connected.
|
|
1594
|
-
* TODO:#55900: Get rid of copy-pasted OldestClientObserver code
|
|
1595
|
-
*/
|
|
1596
|
-
private computeIsOldest;
|
|
1597
|
-
/**
|
|
1598
|
-
* @returns the current view of the tree.
|
|
1599
|
-
*/
|
|
1600
|
-
get currentView(): RevisionView;
|
|
1601
|
-
/**
|
|
1602
|
-
* Generates a node identifier.
|
|
1603
|
-
* The returned IDs may be used as the identifier of a node in the SharedTree.
|
|
1604
|
-
* `NodeId`s are *always* unique and stable within the scope of the tree and session that generated them. They are *not* unique within
|
|
1605
|
-
* a Fluid container, and *cannot* be compared across instances of a SharedTree. They are *not* stable across sessions/lifetimes of a
|
|
1606
|
-
* SharedTree, and *cannot* be persisted (e.g. stored in payloads, uploaded in blobs, etc.). If stable persistence is needed,
|
|
1607
|
-
* NodeIdConverter.convertToStableNodeId may be used to return a corresponding UUID that is globally unique and stable.
|
|
1608
|
-
* @param override - if supplied, calls to `convertToStableNodeId` using the returned node ID will return the override instead of
|
|
1609
|
-
* the UUID. Calls to `generateNodeId` with the same override always return the same ID. Performance note: passing an override string
|
|
1610
|
-
* incurs a storage cost that is significantly higher that a node ID without one, and should be avoided if possible.
|
|
1611
|
-
*/
|
|
1612
|
-
generateNodeId(override?: string): NodeId;
|
|
1613
|
-
/**
|
|
1614
|
-
* Given a NodeId, returns the corresponding stable ID or throws if the supplied node ID was not generated with this tree (`NodeId`s
|
|
1615
|
-
* may not be used across SharedTree instances, see `generateNodeId` for more).
|
|
1616
|
-
* The returned value will be a UUID, unless the creation of `id` used an override string (see `generateNodeId` for more).
|
|
1617
|
-
* The result is safe to persist and re-use across `SharedTree` instances, unlike `NodeId`.
|
|
1618
|
-
*/
|
|
1619
|
-
convertToStableNodeId(id: NodeId): StableNodeId;
|
|
1620
|
-
/**
|
|
1621
|
-
* Given a NodeId, attempt to return the corresponding stable ID.
|
|
1622
|
-
* The returned value will be a UUID, unless the creation of `id` used an override string (see `generateNodeId` for more).
|
|
1623
|
-
* The returned stable ID is undefined if `id` was never created with this SharedTree. If a stable ID is returned, this does not imply
|
|
1624
|
-
* that there is a node with `id` in the current revision of the tree, only that `id` was at some point generated by some instance of
|
|
1625
|
-
* this tree.
|
|
1626
|
-
*/
|
|
1627
|
-
tryConvertToStableNodeId(id: NodeId): StableNodeId | undefined;
|
|
1628
|
-
/**
|
|
1629
|
-
* Given a stable ID, return the corresponding NodeId or throws if the supplied stable ID was never generated with this tree, either
|
|
1630
|
-
* as a UUID corresponding to a `NodeId` or as an override passed to `generateNodeId`.
|
|
1631
|
-
* If a stable ID is returned, this does not imply that there is a node with `id` in the current revision of the tree, only that
|
|
1632
|
-
* `id` was at some point generated by an instance of this SharedTree.
|
|
1633
|
-
*/
|
|
1634
|
-
convertToNodeId(id: StableNodeId): NodeId;
|
|
1635
|
-
/**
|
|
1636
|
-
* Given a stable ID, return the corresponding NodeId or return undefined if the supplied stable ID was never generated with this tree,
|
|
1637
|
-
* either as a UUID corresponding to a `NodeId` or as an override passed to `generateNodeId`.
|
|
1638
|
-
* If a stable ID is returned, this does not imply that there is a node with `id` in the current revision of the tree, only that
|
|
1639
|
-
* `id` was at some point generated by an instance of this SharedTree.
|
|
1640
|
-
*/
|
|
1641
|
-
tryConvertToNodeId(id: StableNodeId): NodeId | undefined;
|
|
1642
|
-
/**
|
|
1643
|
-
* Returns the attribution ID associated with the SharedTree that generated the given node ID. This is generally only useful for clients
|
|
1644
|
-
* with a write format of 0.1.1 or greater since older clients cannot be given an attribution ID and will always use the default
|
|
1645
|
-
* `attributionId` of the tree.
|
|
1646
|
-
*/
|
|
1647
|
-
attributeNodeId(id: NodeId): AttributionId;
|
|
1648
|
-
/**
|
|
1649
|
-
* @returns the edit history of the tree.
|
|
1650
|
-
*/
|
|
1651
|
-
get edits(): OrderedEditSet<InternalizedChange>;
|
|
1652
|
-
/**
|
|
1653
|
-
* {@inheritDoc @fluidframework/shared-object-base#SharedObject.summarizeCore}
|
|
1654
|
-
*/
|
|
1655
|
-
summarizeCore(serializer: IFluidSerializer): ISummaryTreeWithStats;
|
|
1656
|
-
/**
|
|
1657
|
-
* {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).getAttachSummary}
|
|
1658
|
-
*/
|
|
1659
|
-
getAttachSummary(fullTree?: boolean | undefined, trackState?: boolean | undefined, telemetryContext?: ITelemetryContext | undefined): ISummaryTreeWithStats;
|
|
1660
|
-
/**
|
|
1661
|
-
* Saves this SharedTree into a serialized summary. This is used for testing.
|
|
1662
|
-
*
|
|
1663
|
-
* @param summarizer - Optional summarizer to use. If not passed in, SharedTree's summarizer is used.
|
|
1664
|
-
*/
|
|
1665
|
-
saveSerializedSummary(options?: {
|
|
1666
|
-
serializer?: IFluidSerializer;
|
|
1667
|
-
}): string;
|
|
1668
|
-
/**
|
|
1669
|
-
* Initialize shared tree with a serialized summary. This is used for testing.
|
|
1670
|
-
* @returns Statistics about the loaded summary.
|
|
1671
|
-
*/
|
|
1672
|
-
loadSerializedSummary(blobData: string): ITelemetryBaseProperties;
|
|
1673
|
-
/**
|
|
1674
|
-
* Saves this SharedTree into a deserialized summary.
|
|
1675
|
-
*/
|
|
1676
|
-
saveSummary(): SharedTreeSummaryBase;
|
|
1677
|
-
/**
|
|
1678
|
-
* Generates a SharedTree summary for the current state of the tree.
|
|
1679
|
-
* Will never be called when local edits are present.
|
|
1680
|
-
*/
|
|
1681
|
-
private generateSummary;
|
|
1682
|
-
/**
|
|
1683
|
-
* Initialize shared tree with a deserialized summary.
|
|
1684
|
-
*/
|
|
1685
|
-
loadSummary(summary: SharedTreeSummaryBase): void;
|
|
1686
|
-
private static eventFromEditResult;
|
|
1687
|
-
/**
|
|
1688
|
-
* Initializes a new `EditLog` and `CachingLogViewer` on this `SharedTree`, replacing and disposing of any previously existing ones.
|
|
1689
|
-
* @returns the initialized values (this is mostly to keep the constructor happy)
|
|
1690
|
-
*/
|
|
1691
|
-
private initializeNewEditLogFromSummary;
|
|
1692
|
-
/**
|
|
1693
|
-
* Compares this shared tree to another for equality. Should only be used for internal correctness testing.
|
|
1694
|
-
*
|
|
1695
|
-
* Equality means that the histories as captured by the EditLogs are equivalent.
|
|
1696
|
-
*
|
|
1697
|
-
* Equality does not include:
|
|
1698
|
-
*
|
|
1699
|
-
* - if an edit is open
|
|
1700
|
-
*
|
|
1701
|
-
* - the shared tree's id
|
|
1702
|
-
*
|
|
1703
|
-
* - local vs sequenced status of edits
|
|
1704
|
-
*
|
|
1705
|
-
* - registered event listeners
|
|
1706
|
-
*
|
|
1707
|
-
* - state of caches
|
|
1708
|
-
*/
|
|
1709
|
-
equals(sharedTree: SharedTree): boolean;
|
|
1710
|
-
/**
|
|
1711
|
-
* {@inheritDoc @fluidframework/shared-object-base#SharedObject.loadCore}
|
|
1712
|
-
*/
|
|
1713
|
-
protected loadCore(storage: IChannelStorageService): Promise<void>;
|
|
1714
|
-
/**
|
|
1715
|
-
* {@inheritDoc @fluidframework/shared-object-base#SharedObject.processCore}
|
|
1716
|
-
*/
|
|
1717
|
-
protected processCore(message: unknown, local: boolean): void;
|
|
1718
|
-
/**
|
|
1719
|
-
* {@inheritDoc @fluidframework/shared-object-base#SharedObject.registerCore}
|
|
1720
|
-
*/
|
|
1721
|
-
protected registerCore(): void;
|
|
1722
|
-
/**
|
|
1723
|
-
* {@inheritDoc @fluidframework/shared-object-base#SharedObject.onDisconnect}
|
|
1724
|
-
*/
|
|
1725
|
-
protected onDisconnect(): void;
|
|
1726
|
-
/**
|
|
1727
|
-
* Parses a sequenced edit. This is only invoked for ops with version matching the current `writeFormat`.
|
|
1728
|
-
*/
|
|
1729
|
-
private parseSequencedEdit;
|
|
1730
|
-
private processSequencedEdit;
|
|
1731
|
-
/**
|
|
1732
|
-
* Updates SharedTree to the provided version if the version is a valid write version newer than the current version.
|
|
1733
|
-
* @param version - The version to update to.
|
|
1734
|
-
*/
|
|
1735
|
-
private processVersionUpdate;
|
|
1736
|
-
private upgradeFrom_0_0_2_to_0_1_1;
|
|
1737
|
-
/**
|
|
1738
|
-
* Applies a set of changes to this tree. The result will be reflected in `SharedTree.currentView`.
|
|
1739
|
-
* This method does not allow for snapshot isolation, as the changes are always applied to the most recent revision.
|
|
1740
|
-
* If it is desireable to read from and apply changes to a fixed view that does not change when remote changes arrive, `Checkout`
|
|
1741
|
-
* should be used instead.
|
|
1742
|
-
*/
|
|
1743
|
-
applyEdit(...changes: readonly Change[]): Edit<InternalizedChange>;
|
|
1744
|
-
applyEdit(changes: readonly Change[]): Edit<InternalizedChange>;
|
|
1745
|
-
/**
|
|
1746
|
-
* Merges `edits` from `other` into this SharedTree.
|
|
1747
|
-
* @param other - Tree containing the edits that should be applied to this one.
|
|
1748
|
-
* @param edits - Iterable of edits from `other` to apply.
|
|
1749
|
-
* @param stableIdRemapper - Optional remapper to translate stable identities from `other` into stable identities on this tree.
|
|
1750
|
-
* Any references that `other` contains to a stable id `foo` will be replaced with references to the id `stableIdRemapper(foo)`.
|
|
1751
|
-
*
|
|
1752
|
-
* Payloads on the edits are left intact.
|
|
1753
|
-
* @returns a list containing `EditId`s for all applied edits.
|
|
1754
|
-
*/
|
|
1755
|
-
mergeEditsFrom(other: SharedTree, edits: Iterable<Edit<InternalizedChange>>, stableIdRemapper?: (id: StableNodeId) => StableNodeId): EditId[];
|
|
1756
|
-
/**
|
|
1757
|
-
* Applies a set of internal changes to this tree. The result will be reflected in `SharedTree.currentView`.
|
|
1758
|
-
* External users should use one of the more specialized functions, like `applyEdit` which handles constructing the actual `Edit`
|
|
1759
|
-
* and uses public Change types.
|
|
1760
|
-
* This is exposed for internal use only.
|
|
1761
|
-
*/
|
|
1762
|
-
applyEditInternal(editOrChanges: Edit<ChangeInternal> | readonly ChangeInternal[]): Edit<ChangeInternal>;
|
|
1763
|
-
/**
|
|
1764
|
-
* Converts a public Change type to an internal representation.
|
|
1765
|
-
* This is exposed for internal use only.
|
|
1766
|
-
*/
|
|
1767
|
-
internalizeChange(change: Change): ChangeInternal;
|
|
1768
|
-
private applyEditLocally;
|
|
1769
|
-
/**
|
|
1770
|
-
* Reverts a previous edit by applying a new edit containing the inverse of the original edit's changes.
|
|
1771
|
-
* @param editId - the edit to revert
|
|
1772
|
-
* @returns the id of the new edit, or undefined if the original edit could not be inverted given the current tree state.
|
|
1773
|
-
*/
|
|
1774
|
-
revert(editId: EditId): EditId | undefined;
|
|
1775
|
-
/**
|
|
1776
|
-
* Revert the given changes
|
|
1777
|
-
* @param changes - the changes to revert
|
|
1778
|
-
* @param before - the revision view before the changes were originally applied
|
|
1779
|
-
* @returns the inverse of `changes` or undefined if the changes could not be inverted for the given tree state.
|
|
1780
|
-
*/
|
|
1781
|
-
revertChanges(changes: readonly InternalizedChange[], before: RevisionView): ChangeInternal[] | undefined;
|
|
1782
|
-
/**
|
|
1783
|
-
* Submits an edit by the local client to the runtime.
|
|
1784
|
-
*/
|
|
1785
|
-
private submitEditOp;
|
|
1786
|
-
/** A type-safe `submitLocalMessage` wrapper to enforce op format */
|
|
1787
|
-
private submitOp;
|
|
1788
|
-
getRuntime(): IFluidDataStoreRuntime;
|
|
1789
|
-
/**
|
|
1790
|
-
* "Pending local state" refers to ops submitted to the runtime that have not yet been acked.
|
|
1791
|
-
* When closing a container, hosts have the option to stash this pending local state somewhere to be reapplied
|
|
1792
|
-
* later (to avoid data loss).
|
|
1793
|
-
* If a host then loads a container using that stashed state, this function is called for each stashed op, and is expected to:
|
|
1794
|
-
* Update this DDS to reflect that state locally, and submit the op to do that.
|
|
1795
|
-
*
|
|
1796
|
-
* @param content - op to apply locally.
|
|
1797
|
-
*/
|
|
1798
|
-
protected applyStashedOp(op: unknown): void;
|
|
1799
|
-
protected reSubmitCore(op: unknown, localOpMetadata?: StashedLocalOpMetadata): void;
|
|
1800
|
-
private changeWriteFormat;
|
|
1801
|
-
/**
|
|
1802
|
-
* Interns all Definitions and TraitLabel_s referenced by the provided edit.
|
|
1803
|
-
*
|
|
1804
|
-
* Clients must have consensus on the interned values to guarantee the interned ID is valid.
|
|
1805
|
-
*/
|
|
1806
|
-
private internStringsFromEdit;
|
|
1807
|
-
}
|
|
1808
|
-
|
|
1809
|
-
/**
|
|
1810
|
-
* The write format and associated options used to construct a `SharedTree`
|
|
1811
|
-
* @alpha
|
|
1812
|
-
*/
|
|
1813
|
-
export declare type SharedTreeArgs<WF extends WriteFormat = WriteFormat> = [writeFormat: WF, options?: SharedTreeOptions<WF>];
|
|
1814
|
-
|
|
1815
|
-
/* Excluded from this release type: sharedTreeAssertionErrorType */
|
|
1816
|
-
|
|
1817
|
-
/**
|
|
1818
|
-
* Configuration options for SharedTree that are independent of write format versions.
|
|
1819
|
-
* @alpha
|
|
1820
|
-
*/
|
|
1821
|
-
export declare interface SharedTreeBaseOptions {
|
|
1822
|
-
/**
|
|
1823
|
-
* The target number of sequenced edits that the tree will try to store in memory.
|
|
1824
|
-
* Depending on eviction frequency and the collaboration window, there can be more edits in memory at a given time.
|
|
1825
|
-
* Edits in the collaboration window are not evicted.
|
|
1826
|
-
*
|
|
1827
|
-
* The size is set to infinity by default, meaning that all edits in session are kept within memory.
|
|
1828
|
-
*/
|
|
1829
|
-
inMemoryHistorySize?: number;
|
|
1830
|
-
/**
|
|
1831
|
-
* The rate at which edits are evicted from memory. This is a factor of the inMemoryHistorySize.
|
|
1832
|
-
* For example, with the default frequency of inMemoryHistorySize * 2 and a size of 10, the log will evict once it reaches 20 sequenced edits
|
|
1833
|
-
* down to 10 edits, also keeping any that are still in the collaboration window.
|
|
1834
|
-
*/
|
|
1835
|
-
editEvictionFrequency?: number;
|
|
1836
|
-
}
|
|
1837
|
-
|
|
1838
|
-
/* Excluded from this release type: SharedTreeDiagnosticEvent */
|
|
1839
|
-
|
|
1840
|
-
/**
|
|
1841
|
-
* An event emitted by a `SharedTree` to indicate a state change. See {@link ISharedTreeEvents} for event
|
|
1842
|
-
* argument information.
|
|
1843
|
-
* @alpha
|
|
1844
|
-
*/
|
|
1845
|
-
export declare enum SharedTreeEvent {
|
|
1846
|
-
/**
|
|
1847
|
-
* Note: It is _strongly_ recommended that you avoid this API and instead use the `viewChange` event
|
|
1848
|
-
* on a {@link Checkout}. See "Use a Checkout" in the README for an example of how to create a
|
|
1849
|
-
* checkout of a tree. The Checkout API is generally more user friendly and also avoids a class
|
|
1850
|
-
* of bugs involving the interleaving of remote and local edits that can arise when querying the
|
|
1851
|
-
* tree's {@link LogViewer} directly.
|
|
1852
|
-
*
|
|
1853
|
-
* An edit has been committed to the log.
|
|
1854
|
-
* This happens when either:
|
|
1855
|
-
*
|
|
1856
|
-
* 1. A locally generated edit is added to the log.
|
|
1857
|
-
*
|
|
1858
|
-
* 2. A remotely generated edit is added to the log.
|
|
1859
|
-
*
|
|
1860
|
-
* Note that, for locally generated edits, this event will not be emitted again when that edit is sequenced.
|
|
1861
|
-
* Passed the EditId of the committed edit, i.e. supports callbacks of type {@link EditCommittedHandler}.
|
|
1862
|
-
*/
|
|
1863
|
-
EditCommitted = "committedEdit",
|
|
1864
|
-
/**
|
|
1865
|
-
* Note: It is _strongly_ recommended that you avoid this API and instead use the `viewChange` event
|
|
1866
|
-
* on a {@link Checkout}. See "Use a Checkout" in the README for an example of how to create a
|
|
1867
|
-
* checkout of a tree. The Checkout API is generally more user friendly and also avoids a class
|
|
1868
|
-
* of bugs involving the interleaving of remote and local edits that can arise when querying the
|
|
1869
|
-
* tree's {@link LogViewer} directly.
|
|
1870
|
-
*
|
|
1871
|
-
* A sequenced edit has been applied.
|
|
1872
|
-
* This includes local edits though the callback is only invoked once the sequenced version is received.
|
|
1873
|
-
* For edits that were local (see {@link SequencedEditAppliedEventArguments.wasLocal}, this callback will only
|
|
1874
|
-
* be called once.
|
|
1875
|
-
* For non-local edits, it may be called multiple times: the number of calls and when they occur depends on caching
|
|
1876
|
-
* and is an implementation detail.
|
|
1877
|
-
* Supports callbacks of type {@link SequencedEditAppliedHandler}.
|
|
1878
|
-
*/
|
|
1879
|
-
SequencedEditApplied = "sequencedEditApplied"
|
|
1880
|
-
}
|
|
1881
|
-
|
|
1882
|
-
/**
|
|
1883
|
-
* Factory for SharedTree.
|
|
1884
|
-
* Includes history in the summary.
|
|
1885
|
-
* @alpha
|
|
1886
|
-
*/
|
|
1887
|
-
export declare class SharedTreeFactory implements IChannelFactory {
|
|
1888
|
-
/**
|
|
1889
|
-
* {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory."type"}
|
|
1890
|
-
*/
|
|
1891
|
-
static Type: string;
|
|
1892
|
-
/**
|
|
1893
|
-
* {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory.attributes}
|
|
1894
|
-
*/
|
|
1895
|
-
static Attributes: IChannelAttributes;
|
|
1896
|
-
private readonly args;
|
|
1897
|
-
/**
|
|
1898
|
-
* Get a factory for SharedTree to register with the data store.
|
|
1899
|
-
* @param writeFormat - Determines the format version the SharedTree will write ops and summaries in. See [the write format
|
|
1900
|
-
* documentation](../docs/Write-Format.md) for more information.
|
|
1901
|
-
* @param options - Configuration options for this tree
|
|
1902
|
-
* @returns A factory that creates `SharedTree`s and loads them from storage.
|
|
1903
|
-
*/
|
|
1904
|
-
constructor(...args: SharedTreeArgs);
|
|
1905
|
-
/**
|
|
1906
|
-
* {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory."type"}
|
|
1907
|
-
*/
|
|
1908
|
-
get type(): string;
|
|
1909
|
-
/**
|
|
1910
|
-
* {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory.attributes}
|
|
1911
|
-
*/
|
|
1912
|
-
get attributes(): IChannelAttributes;
|
|
1913
|
-
/**
|
|
1914
|
-
* {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory.load}
|
|
1915
|
-
*/
|
|
1916
|
-
load(runtime: IFluidDataStoreRuntime, id: string, services: IChannelServices, _channelAttributes: Readonly<IChannelAttributes>): Promise<SharedTree>;
|
|
1917
|
-
/**
|
|
1918
|
-
* Create a new SharedTree.
|
|
1919
|
-
* @param runtime - data store runtime that owns the new SharedTree
|
|
1920
|
-
* @param id - optional name for the SharedTree
|
|
1921
|
-
*/
|
|
1922
|
-
create(runtime: IFluidDataStoreRuntime, id: string): SharedTree;
|
|
1923
|
-
private createSharedTree;
|
|
1924
|
-
}
|
|
1925
|
-
|
|
1926
|
-
/* Excluded from this release type: SharedTreeMergeHealthTelemetryHeartbeat */
|
|
1927
|
-
|
|
1928
|
-
/**
|
|
1929
|
-
* The type of shared tree options for a given write format
|
|
1930
|
-
* @alpha
|
|
1931
|
-
*/
|
|
1932
|
-
export declare type SharedTreeOptions<WF extends WriteFormat, HistoryCompatibility extends 'Forwards' | 'None' = 'Forwards'> = SharedTreeBaseOptions & Omit<WF extends WriteFormat.v0_0_2 ? SharedTreeOptions_0_0_2 : WF extends WriteFormat.v0_1_1 ? SharedTreeOptions_0_1_1 : never, HistoryCompatibility extends 'Forwards' ? 'summarizeHistory' : never>;
|
|
1933
|
-
|
|
1934
|
-
/**
|
|
1935
|
-
* Configuration options for a SharedTree with write format 0.0.2
|
|
1936
|
-
* @alpha
|
|
1937
|
-
*/
|
|
1938
|
-
export declare interface SharedTreeOptions_0_0_2 {
|
|
1939
|
-
/**
|
|
1940
|
-
* Determines if the history is included in summaries.
|
|
1941
|
-
*
|
|
1942
|
-
* Warning: enabling history summarization incurs a permanent cost in the document. It is not possible to disable history summarization
|
|
1943
|
-
* later once it has been enabled, and thus the history cannot be safely deleted.
|
|
1944
|
-
*
|
|
1945
|
-
* On 0.1.1 documents, due to current code limitations, this parameter is only impactful for newly created documents.
|
|
1946
|
-
* `SharedTree`s which load existing documents will summarize history if and only if the loaded summary included history.
|
|
1947
|
-
*
|
|
1948
|
-
* The technical limitations here relate to clients with mixed versions collaborating.
|
|
1949
|
-
* In the future we may allow modification of whether or not a particular document saves history, but only via a consensus mechanism.
|
|
1950
|
-
* See the skipped test in SharedTreeFuzzTests.ts for more details on this issue.
|
|
1951
|
-
* See docs/Breaking-Change-Migration for more details on the consensus scheme.
|
|
1952
|
-
*/
|
|
1953
|
-
summarizeHistory?: boolean;
|
|
1954
|
-
}
|
|
1955
|
-
|
|
1956
|
-
/**
|
|
1957
|
-
* Configuration options for a SharedTree with write format 0.1.1
|
|
1958
|
-
* @alpha
|
|
1959
|
-
*/
|
|
1960
|
-
export declare interface SharedTreeOptions_0_1_1 {
|
|
1961
|
-
/**
|
|
1962
|
-
* Determines if the history is included in summaries and if edit chunks are uploaded when they are full.
|
|
1963
|
-
*
|
|
1964
|
-
* Warning: enabling history summarization incurs a permanent cost in the document. It is not possible to disable history summarization
|
|
1965
|
-
* later once it has been enabled, and thus the history cannot be safely deleted.
|
|
1966
|
-
*
|
|
1967
|
-
* On 0.1.1 documents, due to current code limitations, this parameter is only impactful for newly created documents.
|
|
1968
|
-
* `SharedTree`s which load existing documents will summarize history if and only if the loaded summary included history.
|
|
1969
|
-
*
|
|
1970
|
-
* The technical limitations here relate to clients with mixed versions collaborating.
|
|
1971
|
-
* In the future we may allow modification of whether or not a particular document saves history, but only via a consensus mechanism.
|
|
1972
|
-
* See the skipped test in SharedTreeFuzzTests.ts for more details on this issue.
|
|
1973
|
-
* See docs/Breaking-Change-Migration for more details on the consensus scheme.
|
|
1974
|
-
*/
|
|
1975
|
-
summarizeHistory?: false | {
|
|
1976
|
-
uploadEditChunks: boolean;
|
|
1977
|
-
};
|
|
1978
|
-
/** a UUID that identifies the user of this tree; all node IDs generated by this tree will be associated with this UUID */
|
|
1979
|
-
attributionId?: AttributionId;
|
|
1980
|
-
}
|
|
1981
|
-
|
|
1982
|
-
/* Excluded from this release type: SharedTreeShim */
|
|
1983
|
-
|
|
1984
|
-
/* Excluded from this release type: SharedTreeShimFactory */
|
|
1985
|
-
|
|
1986
|
-
/**
|
|
1987
|
-
* The minimal information on a SharedTree summary. Contains the summary format version.
|
|
1988
|
-
* @alpha
|
|
1989
|
-
*/
|
|
1990
|
-
export declare interface SharedTreeSummaryBase {
|
|
1991
|
-
/**
|
|
1992
|
-
* Field on summary under which version is stored.
|
|
1993
|
-
*/
|
|
1994
|
-
readonly version: WriteFormat;
|
|
1995
|
-
}
|
|
1996
|
-
|
|
1997
|
-
/**
|
|
1998
|
-
* Defines a place relative to sibling.
|
|
1999
|
-
* The "outside" of a trait is the `undefined` sibling,
|
|
2000
|
-
* so After `undefined` is the beginning of the trait, and before `undefined` is the end.
|
|
2001
|
-
*
|
|
2002
|
-
* For this purpose, traits look like:
|
|
2003
|
-
*
|
|
2004
|
-
* `{undefined} - {Node 0} - {Node 1} - ... - {Node N} - {undefined}`
|
|
2005
|
-
*
|
|
2006
|
-
* Each `{value}` in the diagram is a possible sibling, which is either a Node or undefined.
|
|
2007
|
-
* Each `-` in the above diagram is a `Place`, and can be describe as being `After` a particular `{sibling}` or `Before` it.
|
|
2008
|
-
* This means that `After` `{undefined}` means the same `Place` as before the first node
|
|
2009
|
-
* and `Before` `{undefined}` means the `Place` after the last Node.
|
|
2010
|
-
*
|
|
2011
|
-
* Each place can be specified, (aka 'anchored') in two ways (relative to the sibling before or after):
|
|
2012
|
-
* the choice of which way to anchor a place only matters when the kept across an edit, and thus evaluated in multiple contexts where the
|
|
2013
|
-
* two place description may no longer evaluate to the same place.
|
|
2014
|
-
* @alpha
|
|
2015
|
-
*/
|
|
2016
|
-
export declare enum Side {
|
|
2017
|
-
Before = 0,
|
|
2018
|
-
After = 1
|
|
2019
|
-
}
|
|
2020
|
-
|
|
2021
|
-
/**
|
|
2022
|
-
* Globally unique node identifier.
|
|
2023
|
-
* Uniquely identifies a node within and across documents. Can be used across SharedTree instances.
|
|
2024
|
-
* @alpha
|
|
2025
|
-
*/
|
|
2026
|
-
export declare type StableNodeId = string & {
|
|
2027
|
-
readonly StableNodeId: 'a0843b38-699d-4bb2-aa7a-16c502a71151';
|
|
2028
|
-
};
|
|
2029
|
-
|
|
2030
|
-
/**
|
|
2031
|
-
* A location in a trait.
|
|
2032
|
-
* This is NOT the location of a node, but a location where a node could be inserted:
|
|
2033
|
-
* it is next to a sibling or at one end of the trait.
|
|
2034
|
-
*
|
|
2035
|
-
* To be well formed, either `sibling` or `trait` must be defined, but not both.
|
|
2036
|
-
*
|
|
2037
|
-
* Any given insertion location can be described by two `StablePlace` objects, one with `Side.After` and one with `Side.Before`.
|
|
2038
|
-
* For example, in a trait containing two strings "foo" and "bar", there are 6 different `StablePlace`s corresponding to 3 locations in the
|
|
2039
|
-
* trait a new node could be inserted: at the start, before "foo", after "foo", before "bar", after "bar", and at the end.
|
|
2040
|
-
* Neither of the two ways to specify the same location are considered to be after each other.
|
|
2041
|
-
*
|
|
2042
|
-
* The anchor (`referenceSibling` or `referenceTrait`) used for a particular `StablePlace` can have an impact in collaborative scenarios.
|
|
2043
|
-
*
|
|
2044
|
-
* `StablePlace` objects can be conveniently constructed with the helper methods exported on a constant of the same name.
|
|
2045
|
-
*
|
|
2046
|
-
* @example
|
|
2047
|
-
*
|
|
2048
|
-
* ```typescript
|
|
2049
|
-
* StablePlace.before(node)
|
|
2050
|
-
* StablePlace.atStartOf(trait)
|
|
2051
|
-
* ```
|
|
2052
|
-
* @alpha
|
|
2053
|
-
*/
|
|
2054
|
-
export declare interface StablePlace {
|
|
2055
|
-
/**
|
|
2056
|
-
* Where this StablePlace is relative to the sibling (if specified), or an end of the trait (if no sibling specified).
|
|
2057
|
-
* If 'After' and there is no sibling, this StablePlace is after the front of the trait.
|
|
2058
|
-
* If 'Before' and there is no sibling, this StablePlace is before the back of the trait.
|
|
2059
|
-
*/
|
|
2060
|
-
readonly side: Side;
|
|
2061
|
-
/**
|
|
2062
|
-
* The sibling to which this 'StablePlace' is anchored (by 'side').
|
|
2063
|
-
* If specified, referenceTrait must be unspecified.
|
|
2064
|
-
*/
|
|
2065
|
-
readonly referenceSibling?: NodeId;
|
|
2066
|
-
/**
|
|
2067
|
-
* The trait to which this 'StablePlace' is anchored (by 'side').
|
|
2068
|
-
* If specified, referenceSibling must be unspecified.
|
|
2069
|
-
*/
|
|
2070
|
-
readonly referenceTrait?: TraitLocation;
|
|
2071
|
-
}
|
|
2072
|
-
|
|
2073
|
-
/**
|
|
2074
|
-
* @alpha
|
|
2075
|
-
*/
|
|
2076
|
-
export declare const StablePlace: {
|
|
2077
|
-
/**
|
|
2078
|
-
* @returns The location directly before `node`.
|
|
2079
|
-
*/
|
|
2080
|
-
before: (node: NodeData<NodeId> | NodeId) => StablePlace;
|
|
2081
|
-
/**
|
|
2082
|
-
* @returns The location directly after `node`.
|
|
2083
|
-
*/
|
|
2084
|
-
after: (node: NodeData<NodeId> | NodeId) => StablePlace;
|
|
2085
|
-
/**
|
|
2086
|
-
* @returns The location at the start of `trait`.
|
|
2087
|
-
*/
|
|
2088
|
-
atStartOf: (trait: TraitLocation) => StablePlace;
|
|
2089
|
-
/**
|
|
2090
|
-
* @returns The location at the end of `trait`.
|
|
2091
|
-
*/
|
|
2092
|
-
atEndOf: (trait: TraitLocation) => StablePlace;
|
|
2093
|
-
};
|
|
2094
|
-
|
|
2095
|
-
/**
|
|
2096
|
-
* {@inheritdoc (StablePlace:interface) }
|
|
2097
|
-
* @alpha
|
|
2098
|
-
*/
|
|
2099
|
-
export declare interface StablePlaceInternal extends Omit<StablePlaceInternal_0_0_2, 'referenceSibling' | 'referenceTrait'> {
|
|
2100
|
-
/**
|
|
2101
|
-
* {@inheritdoc (StablePlace:interface).referenceSibling }
|
|
2102
|
-
*/
|
|
2103
|
-
readonly referenceSibling?: NodeId;
|
|
2104
|
-
/**
|
|
2105
|
-
* {@inheritdoc (StablePlace:interface).referenceTrait }
|
|
2106
|
-
*/
|
|
2107
|
-
readonly referenceTrait?: TraitLocationInternal;
|
|
2108
|
-
}
|
|
2109
|
-
|
|
2110
|
-
/**
|
|
2111
|
-
* @alpha
|
|
2112
|
-
*/
|
|
2113
|
-
export declare const StablePlaceInternal: {
|
|
2114
|
-
/**
|
|
2115
|
-
* @returns The location directly before `node`.
|
|
2116
|
-
*/
|
|
2117
|
-
before: (node: NodeData<NodeId> | NodeId) => StablePlaceInternal;
|
|
2118
|
-
/**
|
|
2119
|
-
* @returns The location directly after `node`.
|
|
2120
|
-
*/
|
|
2121
|
-
after: (node: NodeData<NodeId> | NodeId) => StablePlaceInternal;
|
|
2122
|
-
/**
|
|
2123
|
-
* @returns The location at the start of `trait`.
|
|
2124
|
-
*/
|
|
2125
|
-
atStartOf: (trait: TraitLocationInternal) => StablePlaceInternal;
|
|
2126
|
-
/**
|
|
2127
|
-
* @returns The location at the end of `trait`.
|
|
2128
|
-
*/
|
|
2129
|
-
atEndOf: (trait: TraitLocationInternal) => StablePlaceInternal;
|
|
2130
|
-
};
|
|
2131
|
-
|
|
2132
|
-
/**
|
|
2133
|
-
* {@inheritdoc (StablePlace:interface) }
|
|
2134
|
-
* @alpha
|
|
2135
|
-
*/
|
|
2136
|
-
export declare interface StablePlaceInternal_0_0_2 {
|
|
2137
|
-
/**
|
|
2138
|
-
* {@inheritdoc (StablePlace:interface).side }
|
|
2139
|
-
*/
|
|
2140
|
-
readonly side: Side;
|
|
2141
|
-
/**
|
|
2142
|
-
* {@inheritdoc (StablePlace:interface).referenceSibling }
|
|
2143
|
-
*/
|
|
2144
|
-
readonly referenceSibling?: StableNodeId;
|
|
2145
|
-
/**
|
|
2146
|
-
* {@inheritdoc (StablePlace:interface).referenceTrait }
|
|
2147
|
-
*/
|
|
2148
|
-
readonly referenceTrait?: TraitLocationInternal_0_0_2;
|
|
2149
|
-
}
|
|
2150
|
-
|
|
2151
|
-
/**
|
|
2152
|
-
* Specifies the range of nodes from `start` to `end` within a trait.
|
|
2153
|
-
* Valid iff start and end are valid and are within the same trait and the start does not occur after the end in the trait.
|
|
2154
|
-
*
|
|
2155
|
-
* See {@link (StablePlace:interface)} for what it means for a place to be "after" another place.
|
|
2156
|
-
*
|
|
2157
|
-
* @remarks
|
|
2158
|
-
*
|
|
2159
|
-
* `StableRange` objects can be conveniently constructed with the helper methods exported on a constant of the same name.
|
|
2160
|
-
*
|
|
2161
|
-
* @example
|
|
2162
|
-
*
|
|
2163
|
-
* ```typescript
|
|
2164
|
-
* StableRange.from(StablePlace.before(startNode)).to(StablePlace.after(endNode))
|
|
2165
|
-
* ```
|
|
2166
|
-
* @alpha
|
|
2167
|
-
*/
|
|
2168
|
-
export declare interface StableRange {
|
|
2169
|
-
readonly start: StablePlace;
|
|
2170
|
-
readonly end: StablePlace;
|
|
2171
|
-
}
|
|
2172
|
-
|
|
2173
|
-
/**
|
|
2174
|
-
* @alpha
|
|
2175
|
-
*/
|
|
2176
|
-
export declare const StableRange: {
|
|
2177
|
-
/**
|
|
2178
|
-
* Factory for producing a `StableRange` from a start `StablePlace` to an end `StablePlace`.
|
|
2179
|
-
*
|
|
2180
|
-
* @example
|
|
2181
|
-
*
|
|
2182
|
-
* ```typescript
|
|
2183
|
-
* StableRange.from(StablePlace.before(startNode)).to(StablePlace.after(endNode))
|
|
2184
|
-
* ```
|
|
2185
|
-
*/
|
|
2186
|
-
from: (start: StablePlace) => {
|
|
2187
|
-
to: (end: StablePlace) => StableRange;
|
|
2188
|
-
};
|
|
2189
|
-
/**
|
|
2190
|
-
* @returns a `StableRange` which contains only the provided `node`.
|
|
2191
|
-
* Both the start and end `StablePlace` objects used to anchor this `StableRange` are in terms of the passed in node.
|
|
2192
|
-
*/
|
|
2193
|
-
only: (node: NodeData<NodeId> | NodeId) => StableRange;
|
|
2194
|
-
/**
|
|
2195
|
-
* @returns a `StableRange` which contains everything in the trait.
|
|
2196
|
-
* This is anchored using the provided `trait`, and is independent of the actual contents of the trait:
|
|
2197
|
-
* it does not use sibling anchoring.
|
|
2198
|
-
*/
|
|
2199
|
-
all: (trait: TraitLocation) => StableRange;
|
|
2200
|
-
};
|
|
2201
|
-
|
|
2202
|
-
/**
|
|
2203
|
-
* {@inheritdoc (StableRange:interface) }
|
|
2204
|
-
* @alpha
|
|
2205
|
-
*/
|
|
2206
|
-
export declare interface StableRangeInternal {
|
|
2207
|
-
/** {@inheritdoc (StableRange:interface).start } */
|
|
2208
|
-
readonly start: StablePlaceInternal;
|
|
2209
|
-
/** {@inheritdoc (StableRange:interface).end } */
|
|
2210
|
-
readonly end: StablePlaceInternal;
|
|
2211
|
-
}
|
|
2212
|
-
|
|
2213
|
-
/**
|
|
2214
|
-
* @alpha
|
|
2215
|
-
*/
|
|
2216
|
-
export declare const StableRangeInternal: {
|
|
2217
|
-
/**
|
|
2218
|
-
* Factory for producing a `StableRange` from a start `StablePlace` to an end `StablePlace`.
|
|
2219
|
-
*
|
|
2220
|
-
* @example
|
|
2221
|
-
*
|
|
2222
|
-
* ```typescript
|
|
2223
|
-
* StableRange.from(StablePlace.before(startNode)).to(StablePlace.after(endNode))
|
|
2224
|
-
* ```
|
|
2225
|
-
*/
|
|
2226
|
-
from: (start: StablePlaceInternal) => {
|
|
2227
|
-
to: (end: StablePlaceInternal) => StableRangeInternal;
|
|
2228
|
-
};
|
|
2229
|
-
/**
|
|
2230
|
-
* @returns a `StableRange` which contains only the provided `node`.
|
|
2231
|
-
* Both the start and end `StablePlace` objects used to anchor this `StableRange` are in terms of the passed in node.
|
|
2232
|
-
*/
|
|
2233
|
-
only: (node: NodeData<NodeId> | NodeId) => StableRangeInternal;
|
|
2234
|
-
/**
|
|
2235
|
-
* @returns a `StableRange` which contains everything in the trait.
|
|
2236
|
-
* This is anchored using the provided `trait`, and is independent of the actual contents of the trait:
|
|
2237
|
-
* it does not use sibling anchoring.
|
|
2238
|
-
*/
|
|
2239
|
-
all: (trait: TraitLocationInternal) => StableRangeInternal;
|
|
2240
|
-
};
|
|
2241
|
-
|
|
2242
|
-
/**
|
|
2243
|
-
* {@inheritdoc (StableRange:interface) }
|
|
2244
|
-
* @alpha
|
|
2245
|
-
*/
|
|
2246
|
-
export declare interface StableRangeInternal_0_0_2 {
|
|
2247
|
-
/** {@inheritdoc (StableRange:interface).start } */
|
|
2248
|
-
readonly start: StablePlaceInternal_0_0_2;
|
|
2249
|
-
/** {@inheritdoc (StableRange:interface).end } */
|
|
2250
|
-
readonly end: StablePlaceInternal_0_0_2;
|
|
2251
|
-
}
|
|
2252
|
-
|
|
2253
|
-
/**
|
|
2254
|
-
* Contains information resulting from processing stashed shared tree ops
|
|
2255
|
-
* @alpha
|
|
2256
|
-
*/
|
|
2257
|
-
export declare interface StashedLocalOpMetadata {
|
|
2258
|
-
/** A modified version of the edit in an edit op that should be resubmitted rather than the original edit */
|
|
2259
|
-
transformedEdit?: Edit<ChangeInternal>;
|
|
2260
|
-
}
|
|
2261
|
-
|
|
2262
|
-
/* Excluded from this release type: StringInterner */
|
|
2263
|
-
|
|
2264
|
-
/**
|
|
2265
|
-
* The state of a transaction that has not encountered an error.
|
|
2266
|
-
* @alpha
|
|
2267
|
-
*/
|
|
2268
|
-
export declare interface SucceedingTransactionState {
|
|
2269
|
-
/**
|
|
2270
|
-
* The current status of the transaction.
|
|
2271
|
-
*/
|
|
2272
|
-
readonly status: EditStatus.Applied;
|
|
2273
|
-
/**
|
|
2274
|
-
* The view reflecting the latest applied change.
|
|
2275
|
-
*/
|
|
2276
|
-
readonly view: TransactionView;
|
|
2277
|
-
/**
|
|
2278
|
-
* The applied changes so far.
|
|
2279
|
-
*/
|
|
2280
|
-
readonly changes: readonly ChangeInternal[];
|
|
2281
|
-
/**
|
|
2282
|
-
* The editing steps applied so far.
|
|
2283
|
-
*/
|
|
2284
|
-
readonly steps: readonly ReconciliationChange[];
|
|
2285
|
-
}
|
|
2286
|
-
|
|
2287
|
-
/**
|
|
2288
|
-
* Definition.
|
|
2289
|
-
* A full (Uuid) persistable label for a trait.
|
|
2290
|
-
* @alpha
|
|
2291
|
-
*/
|
|
2292
|
-
export declare type TraitLabel = UuidString & {
|
|
2293
|
-
readonly TraitLabel: '613826ed-49cc-4df3-b2b8-bfc6866af8e3';
|
|
2294
|
-
};
|
|
2295
|
-
|
|
2296
|
-
/**
|
|
2297
|
-
* Specifies the location of a trait (a labeled sequence of nodes) within the tree.
|
|
2298
|
-
* @alpha
|
|
2299
|
-
*/
|
|
2300
|
-
export declare interface TraitLocation {
|
|
2301
|
-
readonly parent: NodeId;
|
|
2302
|
-
readonly label: TraitLabel;
|
|
2303
|
-
}
|
|
2304
|
-
|
|
2305
|
-
/**
|
|
2306
|
-
* Specifies the location of a trait (a labeled sequence of nodes) within the tree.
|
|
2307
|
-
* @alpha
|
|
2308
|
-
*/
|
|
2309
|
-
export declare interface TraitLocationInternal extends Omit<TraitLocationInternal_0_0_2, 'parent'> {
|
|
2310
|
-
readonly parent: NodeId;
|
|
2311
|
-
}
|
|
2312
|
-
|
|
2313
|
-
/**
|
|
2314
|
-
* Specifies the location of a trait (a labeled sequence of nodes) within the tree.
|
|
2315
|
-
* @alpha
|
|
2316
|
-
*/
|
|
2317
|
-
export declare interface TraitLocationInternal_0_0_2 {
|
|
2318
|
-
readonly parent: StableNodeId;
|
|
2319
|
-
readonly label: TraitLabel;
|
|
2320
|
-
}
|
|
2321
|
-
|
|
2322
|
-
/**
|
|
2323
|
-
* Json compatible map as object.
|
|
2324
|
-
* Keys are TraitLabels,
|
|
2325
|
-
* Values are the content of the trait specified by the key.
|
|
2326
|
-
* @alpha
|
|
2327
|
-
*/
|
|
2328
|
-
export declare interface TraitMap<TChild> {
|
|
2329
|
-
readonly [key: string]: TreeNodeSequence<TChild>;
|
|
2330
|
-
}
|
|
2331
|
-
|
|
2332
|
-
/**
|
|
2333
|
-
* Index of a node within a trait.
|
|
2334
|
-
* 0 = first node,
|
|
2335
|
-
* 1 = second node,
|
|
2336
|
-
* etc.
|
|
2337
|
-
* @alpha
|
|
2338
|
-
*/
|
|
2339
|
-
export declare type TraitNodeIndex = number & {
|
|
2340
|
-
readonly TraitNodeIndex: unique symbol;
|
|
2341
|
-
};
|
|
2342
|
-
|
|
2343
|
-
/**
|
|
2344
|
-
* Buffers changes to be applied to an isolated view of a `SharedTree` over time before applying them directly to the tree itself as a
|
|
2345
|
-
* single edit
|
|
2346
|
-
* @alpha
|
|
2347
|
-
*/
|
|
2348
|
-
export declare class Transaction extends TypedEventEmitter<TransactionEvents> {
|
|
2349
|
-
readonly tree: SharedTree;
|
|
2350
|
-
/** The view of the tree when this transaction was created */
|
|
2351
|
-
readonly startingView: TreeView;
|
|
2352
|
-
private readonly transaction;
|
|
2353
|
-
/**
|
|
2354
|
-
* Create a new transaction over the given tree. The tree's `currentView` at this time will become the `startingView` for this
|
|
2355
|
-
* transaction.
|
|
2356
|
-
* @param tree - the `SharedTree` that this transaction applies changes to
|
|
2357
|
-
*/
|
|
2358
|
-
constructor(tree: SharedTree);
|
|
2359
|
-
/**
|
|
2360
|
-
* True if this transaction is open, false if it is closed. A transaction may be closed manually via `closeAndApplyEdit()`, or may
|
|
2361
|
-
* be automatically closed by a change in this transaction failing to apply (see `applyChange()`).
|
|
2362
|
-
*/
|
|
2363
|
-
get isOpen(): boolean;
|
|
2364
|
-
/**
|
|
2365
|
-
* The status of the most recently applied change in this transaction
|
|
2366
|
-
*/
|
|
2367
|
-
get status(): EditStatus;
|
|
2368
|
-
/**
|
|
2369
|
-
* The state of the tree following the most change that was successfully applied. If no changes have been applied, this is the same as
|
|
2370
|
-
* `startingView`.
|
|
2371
|
-
*/
|
|
2372
|
-
get currentView(): TreeView;
|
|
2373
|
-
/**
|
|
2374
|
-
* Attempt to apply a sequence of changes in this transaction. The `currentView` will be updated to reflect the new tree state after all
|
|
2375
|
-
* applied changes. If any change fails to apply, the remaining changes will be ignored and this transaction will be automatically
|
|
2376
|
-
* closed (see `isOpen`). If this transaction is already closed, this method has no effect. This method will emit a
|
|
2377
|
-
* `TransactionEvent.ViewChange` event at most once per call.
|
|
2378
|
-
* @param changes - the changes to apply
|
|
2379
|
-
* @returns either the `EditStatus` of the given changes or the `EditStatus` of the last change before the transaction was closed
|
|
2380
|
-
*/
|
|
2381
|
-
apply(...changes: readonly Change[]): EditStatus;
|
|
2382
|
-
apply(changes: readonly Change[]): EditStatus;
|
|
2383
|
-
/**
|
|
2384
|
-
* Close this transaction and apply its changes to the `SharedTree`. If this transaction is already closed, this method has no effect.
|
|
2385
|
-
*/
|
|
2386
|
-
closeAndCommit(): void;
|
|
2387
|
-
}
|
|
2388
|
-
|
|
2389
|
-
/**
|
|
2390
|
-
* An event emitted by a `Transaction` to indicate a state change. See {@link TransactionEvents} for event argument information.
|
|
2391
|
-
* @alpha
|
|
2392
|
-
*/
|
|
2393
|
-
export declare enum TransactionEvent {
|
|
2394
|
-
/**
|
|
2395
|
-
* `currentView` has changed from `before` to `after`
|
|
2396
|
-
*/
|
|
2397
|
-
ViewChange = "viewChange"
|
|
2398
|
-
}
|
|
2399
|
-
|
|
2400
|
-
/**
|
|
2401
|
-
* Events which may be emitted by `Transaction`
|
|
2402
|
-
* @alpha
|
|
2403
|
-
*/
|
|
2404
|
-
export declare interface TransactionEvents extends IErrorEvent {
|
|
2405
|
-
(event: TransactionEvent.ViewChange, listener: (before: TreeView, after: TreeView) => void): any;
|
|
2406
|
-
}
|
|
2407
|
-
|
|
2408
|
-
/* Excluded from this release type: TransactionFailure */
|
|
2409
|
-
|
|
2410
|
-
/**
|
|
2411
|
-
* A mutable transaction for applying sequences of changes to a TreeView.
|
|
2412
|
-
* Allows viewing the intermediate states.
|
|
2413
|
-
*
|
|
2414
|
-
* Contains necessary state to apply changes within an edit to a TreeView.
|
|
2415
|
-
*
|
|
2416
|
-
* May have any number of changes applied to make up the edit.
|
|
2417
|
-
* Use `close` to complete the transaction, returning the array of changes and an EditingResult showing the
|
|
2418
|
-
* results of applying the changes as an Edit to the initial TreeView (passed to the constructor).
|
|
2419
|
-
*
|
|
2420
|
-
* No data outside the Transaction is modified by Transaction:
|
|
2421
|
-
* the results from `close` must be used to actually submit an `Edit`.
|
|
2422
|
-
* @alpha
|
|
2423
|
-
*/
|
|
2424
|
-
export declare namespace TransactionInternal {
|
|
2425
|
-
/* Excluded from this release type: factory */
|
|
2426
|
-
export type ValidState = SucceedingTransactionState;
|
|
2427
|
-
/* Excluded from this release type: Policy */
|
|
2428
|
-
/**
|
|
2429
|
-
* The kinds of failures that a transaction might encounter.
|
|
2430
|
-
* @alpha
|
|
2431
|
-
*/
|
|
2432
|
-
export enum FailureKind {
|
|
2433
|
-
/**
|
|
2434
|
-
* Transaction has an unused DetachedSequenceId
|
|
2435
|
-
*/
|
|
2436
|
-
UnusedDetachedSequence = "UnusedDetachedSequence",
|
|
2437
|
-
/**
|
|
2438
|
-
* Transaction has a build operation using an already in use DetachedSequenceID.
|
|
2439
|
-
*/
|
|
2440
|
-
DetachedSequenceIdAlreadyInUse = "DetachedSequenceIdAlreadyInUse",
|
|
2441
|
-
/**
|
|
2442
|
-
* Transaction tries to operate on an unknown DetachedSequenceID
|
|
2443
|
-
*/
|
|
2444
|
-
DetachedSequenceNotFound = "DetachedSequenceNotFound",
|
|
2445
|
-
/**
|
|
2446
|
-
* Transaction has a build which uses a duplicated NodeId
|
|
2447
|
-
*/
|
|
2448
|
-
DuplicateIdInBuild = "DuplicateIdInBuild",
|
|
2449
|
-
/**
|
|
2450
|
-
* Transaction tries to build a node using an ID which is already used in the current state
|
|
2451
|
-
*/
|
|
2452
|
-
IdAlreadyInUse = "IdAlreadyInUse",
|
|
2453
|
-
/**
|
|
2454
|
-
* Transaction tries to set value of an unknown node
|
|
2455
|
-
*/
|
|
2456
|
-
UnknownId = "UnknownId",
|
|
2457
|
-
/**
|
|
2458
|
-
* Transaction tries to insert in an invalid Place
|
|
2459
|
-
*/
|
|
2460
|
-
BadPlace = "BadPlace",
|
|
2461
|
-
/**
|
|
2462
|
-
* Transaction tries to detach an invalid Range
|
|
2463
|
-
*/
|
|
2464
|
-
BadRange = "BadRange",
|
|
2465
|
-
/**
|
|
2466
|
-
* Transaction has an invalid constraint
|
|
2467
|
-
*/
|
|
2468
|
-
ConstraintViolation = "ConstraintViolation"
|
|
2469
|
-
}
|
|
2470
|
-
/**
|
|
2471
|
-
* A failure encountered by a transaction.
|
|
2472
|
-
* @alpha
|
|
2473
|
-
*/
|
|
2474
|
-
export type Failure = UnusedDetachedSequenceFailure | DetachedSequenceIdAlreadyInUseFailure | DetachedSequenceNotFoundFailure | DuplicateIdInBuildFailure | IdAlreadyInUseFailure | UnknownIdFailure | BadPlaceFailure | BadRangeFailure | ConstraintViolationFailure;
|
|
2475
|
-
/**
|
|
2476
|
-
* Error returned when a transaction is closed while there is an unused detached sequence.
|
|
2477
|
-
* @alpha
|
|
2478
|
-
*/
|
|
2479
|
-
export interface UnusedDetachedSequenceFailure {
|
|
2480
|
-
/**
|
|
2481
|
-
* Failure kind (will always be FailureKind.UnusedDetachedSequence)
|
|
2482
|
-
*/
|
|
2483
|
-
readonly kind: FailureKind.UnusedDetachedSequence;
|
|
2484
|
-
/**
|
|
2485
|
-
* The unused DetachedSequenceId
|
|
2486
|
-
*/
|
|
2487
|
-
readonly sequenceId: DetachedSequenceId;
|
|
2488
|
-
}
|
|
2489
|
-
/**
|
|
2490
|
-
* Error thrown when a transaction encounters a build operation using an already in use DetachedSequenceID.
|
|
2491
|
-
* @alpha
|
|
2492
|
-
*/
|
|
2493
|
-
export interface DetachedSequenceIdAlreadyInUseFailure {
|
|
2494
|
-
/**
|
|
2495
|
-
* Failure kind (will always be FailureKind.DetachedSequenceIdAlreadyInUse)
|
|
2496
|
-
*/
|
|
2497
|
-
readonly kind: FailureKind.DetachedSequenceIdAlreadyInUse;
|
|
2498
|
-
/**
|
|
2499
|
-
* Faulting Change
|
|
2500
|
-
*/
|
|
2501
|
-
readonly change: ChangeInternal;
|
|
2502
|
-
/**
|
|
2503
|
-
* The DetachedSequenceId that is already in use
|
|
2504
|
-
*/
|
|
2505
|
-
readonly sequenceId: DetachedSequenceId;
|
|
2506
|
-
}
|
|
2507
|
-
/**
|
|
2508
|
-
* Error thrown when a transaction tries to operate on an unknown DetachedSequenceID
|
|
2509
|
-
* @alpha
|
|
2510
|
-
*/
|
|
2511
|
-
export interface DetachedSequenceNotFoundFailure {
|
|
2512
|
-
/**
|
|
2513
|
-
* Failure kind (will always be FailureKind.DetachedSequenceNotFound)
|
|
2514
|
-
*/
|
|
2515
|
-
readonly kind: FailureKind.DetachedSequenceNotFound;
|
|
2516
|
-
/**
|
|
2517
|
-
* Faulting Change
|
|
2518
|
-
*/
|
|
2519
|
-
readonly change: ChangeInternal;
|
|
2520
|
-
/**
|
|
2521
|
-
* The DetachedSequenceId that wasn't found
|
|
2522
|
-
*/
|
|
2523
|
-
readonly sequenceId: DetachedSequenceId;
|
|
2524
|
-
}
|
|
2525
|
-
/**
|
|
2526
|
-
* Error thrown when a build uses a duplicated NodeId
|
|
2527
|
-
* @alpha
|
|
2528
|
-
*/
|
|
2529
|
-
export interface DuplicateIdInBuildFailure {
|
|
2530
|
-
/**
|
|
2531
|
-
* Failure kind (will always be FailureKind.DuplicateIdInBuild)
|
|
2532
|
-
*/
|
|
2533
|
-
readonly kind: FailureKind.DuplicateIdInBuild;
|
|
2534
|
-
/**
|
|
2535
|
-
* Faulting Change
|
|
2536
|
-
*/
|
|
2537
|
-
readonly change: ChangeInternal;
|
|
2538
|
-
/**
|
|
2539
|
-
* ID of duplicated node
|
|
2540
|
-
*/
|
|
2541
|
-
readonly id: NodeId;
|
|
2542
|
-
}
|
|
2543
|
-
/**
|
|
2544
|
-
* Error thrown when a build node ID is already used in the current state
|
|
2545
|
-
* @alpha
|
|
2546
|
-
*/
|
|
2547
|
-
export interface IdAlreadyInUseFailure {
|
|
2548
|
-
/**
|
|
2549
|
-
* Failure kind (will always be FailureKind.IdAlreadyInUse)
|
|
2550
|
-
*/
|
|
2551
|
-
readonly kind: FailureKind.IdAlreadyInUse;
|
|
2552
|
-
/**
|
|
2553
|
-
* Faulting Change
|
|
2554
|
-
*/
|
|
2555
|
-
readonly change: ChangeInternal;
|
|
2556
|
-
/**
|
|
2557
|
-
* ID of already in use node
|
|
2558
|
-
*/
|
|
2559
|
-
readonly id: NodeId;
|
|
2560
|
-
}
|
|
2561
|
-
/**
|
|
2562
|
-
* Error thrown when a change is attempted on an unknown NodeId
|
|
2563
|
-
* @alpha
|
|
2564
|
-
*/
|
|
2565
|
-
export interface UnknownIdFailure {
|
|
2566
|
-
/**
|
|
2567
|
-
* Failure kind (will always be FailureKind.UnknownId)
|
|
2568
|
-
*/
|
|
2569
|
-
readonly kind: FailureKind.UnknownId;
|
|
2570
|
-
/**
|
|
2571
|
-
* Faulting Change
|
|
2572
|
-
*/
|
|
2573
|
-
readonly change: ChangeInternal;
|
|
2574
|
-
/**
|
|
2575
|
-
* The unknown ID
|
|
2576
|
-
*/
|
|
2577
|
-
readonly id: NodeId;
|
|
2578
|
-
}
|
|
2579
|
-
/**
|
|
2580
|
-
* Error thrown when an insert change uses an invalid Place
|
|
2581
|
-
* @alpha
|
|
2582
|
-
*/
|
|
2583
|
-
export interface BadPlaceFailure {
|
|
2584
|
-
/**
|
|
2585
|
-
* Failure kind (will always be FailureKind.BadPlace)
|
|
2586
|
-
*/
|
|
2587
|
-
readonly kind: FailureKind.BadPlace;
|
|
2588
|
-
/**
|
|
2589
|
-
* Faulting Change
|
|
2590
|
-
*/
|
|
2591
|
-
readonly change: ChangeInternal;
|
|
2592
|
-
/**
|
|
2593
|
-
* The faulting place
|
|
2594
|
-
*/
|
|
2595
|
-
readonly place: StablePlaceInternal;
|
|
2596
|
-
/**
|
|
2597
|
-
* The reason for the failure
|
|
2598
|
-
*/
|
|
2599
|
-
readonly placeFailure: BadPlaceValidationResult;
|
|
2600
|
-
}
|
|
2601
|
-
/**
|
|
2602
|
-
* Error thrown when a detach operation is given an invalid or malformed Range
|
|
2603
|
-
* @alpha
|
|
2604
|
-
*/
|
|
2605
|
-
export interface BadRangeFailure {
|
|
2606
|
-
/**
|
|
2607
|
-
* Failure kind (will always be FailureKind.BadRange)
|
|
2608
|
-
*/
|
|
2609
|
-
readonly kind: FailureKind.BadRange;
|
|
2610
|
-
/**
|
|
2611
|
-
* Faulting Change
|
|
2612
|
-
*/
|
|
2613
|
-
readonly change: ChangeInternal;
|
|
2614
|
-
/**
|
|
2615
|
-
* Faulting range
|
|
2616
|
-
*/
|
|
2617
|
-
readonly range: StableRangeInternal;
|
|
2618
|
-
/**
|
|
2619
|
-
* The reason for the failure
|
|
2620
|
-
*/
|
|
2621
|
-
readonly rangeFailure: BadRangeValidationResult;
|
|
2622
|
-
}
|
|
2623
|
-
/**
|
|
2624
|
-
* Error thrown when a constraint fails to apply
|
|
2625
|
-
* @alpha
|
|
2626
|
-
*/
|
|
2627
|
-
export interface ConstraintViolationFailure {
|
|
2628
|
-
/**
|
|
2629
|
-
* Failure kind (will always be FailureKind.ConstraintViolation)
|
|
2630
|
-
*/
|
|
2631
|
-
readonly kind: FailureKind.ConstraintViolation;
|
|
2632
|
-
/**
|
|
2633
|
-
* Faulting Change
|
|
2634
|
-
*/
|
|
2635
|
-
readonly constraint: ConstraintInternal;
|
|
2636
|
-
/**
|
|
2637
|
-
* The first violation the constraint encounters (there may be others).
|
|
2638
|
-
*/
|
|
2639
|
-
readonly violation: ConstraintViolationResult;
|
|
2640
|
-
}
|
|
2641
|
-
/**
|
|
2642
|
-
* The details of what kind of constraint was violated and caused a ConstraintViolationFailure error to occur
|
|
2643
|
-
* @alpha
|
|
2644
|
-
*/
|
|
2645
|
-
export type ConstraintViolationResult = {
|
|
2646
|
-
readonly kind: ConstraintViolationKind.BadRange;
|
|
2647
|
-
readonly rangeFailure: BadRangeValidationResult;
|
|
2648
|
-
} | {
|
|
2649
|
-
readonly kind: ConstraintViolationKind.BadLength;
|
|
2650
|
-
readonly actual: number;
|
|
2651
|
-
} | {
|
|
2652
|
-
readonly kind: ConstraintViolationKind.BadParent;
|
|
2653
|
-
readonly actual: NodeId;
|
|
2654
|
-
} | {
|
|
2655
|
-
readonly kind: ConstraintViolationKind.BadLabel;
|
|
2656
|
-
readonly actual: TraitLabel;
|
|
2657
|
-
};
|
|
2658
|
-
/**
|
|
2659
|
-
* Enum of possible kinds of constraint violations that can be encountered
|
|
2660
|
-
* @alpha
|
|
2661
|
-
*/
|
|
2662
|
-
export enum ConstraintViolationKind {
|
|
2663
|
-
/**
|
|
2664
|
-
* The constraint failed because it applies to an invalid range
|
|
2665
|
-
*/
|
|
2666
|
-
BadRange = "BadRange",
|
|
2667
|
-
/**
|
|
2668
|
-
* The constraint failed because the length prescribed by the constraint does not match the length of range being constrained
|
|
2669
|
-
*/
|
|
2670
|
-
BadLength = "BadLength",
|
|
2671
|
-
/**
|
|
2672
|
-
* The constraint failed because the parent prescribed by the constraint does not match the actual parent of the range being constrained
|
|
2673
|
-
*/
|
|
2674
|
-
BadParent = "BadParent",
|
|
2675
|
-
/**
|
|
2676
|
-
* The constraint failed because the trait label prescribed by the constraint does not match the actual trait label of the range being constrained
|
|
2677
|
-
*/
|
|
2678
|
-
BadLabel = "BadLabel"
|
|
2679
|
-
}
|
|
2680
|
-
{};
|
|
2681
|
-
}
|
|
2682
|
-
|
|
2683
|
-
/* Excluded from this release type: TransactionState */
|
|
2684
|
-
|
|
2685
|
-
/**
|
|
2686
|
-
* An view of a distributed tree that is part of an ongoing transaction between `RevisionView`s.
|
|
2687
|
-
* @alpha
|
|
2688
|
-
*/
|
|
2689
|
-
export declare class TransactionView extends TreeView {
|
|
2690
|
-
/** Conclude a transaction by generating an immutable `RevisionView` from this view */
|
|
2691
|
-
close(): RevisionView;
|
|
2692
|
-
/** Inserts all nodes in a NodeSequence into the view */
|
|
2693
|
-
addNodes(sequence: Iterable<TreeViewNode>): TransactionView;
|
|
2694
|
-
/** Remove all nodes with the given ids from the view */
|
|
2695
|
-
deleteNodes(nodes: Iterable<NodeId>): TransactionView;
|
|
2696
|
-
/**
|
|
2697
|
-
* Parents a set of detached nodes at a specified place.
|
|
2698
|
-
* @param nodesToAttach - the nodes to parent in the specified place. The nodes must already be present in the view.
|
|
2699
|
-
* @param place - the location to insert the nodes.
|
|
2700
|
-
*/
|
|
2701
|
-
attachRange(nodesToAttach: readonly NodeId[], place: TreeViewPlace): TransactionView;
|
|
2702
|
-
/**
|
|
2703
|
-
* Detaches a range of nodes from their parent. The detached nodes remain in the view.
|
|
2704
|
-
* @param rangeToDetach - the range of nodes to detach
|
|
2705
|
-
*/
|
|
2706
|
-
detachRange(rangeToDetach: TreeViewRange): {
|
|
2707
|
-
view: TransactionView;
|
|
2708
|
-
detached: readonly NodeId[];
|
|
2709
|
-
};
|
|
2710
|
-
/**
|
|
2711
|
-
* Sets or overwrites a node's value. The node must exist in this view.
|
|
2712
|
-
* @param nodeId - the id of the node
|
|
2713
|
-
* @param value - the new value
|
|
2714
|
-
*/
|
|
2715
|
-
setNodeValue(nodeId: NodeId, value: Payload): TransactionView;
|
|
2716
|
-
equals(view: TreeView): boolean;
|
|
2717
|
-
}
|
|
2718
|
-
|
|
2719
|
-
/**
|
|
2720
|
-
* Satisfies `NodeData` and may contain children under traits (which may or may not be `TreeNodes`)
|
|
2721
|
-
* @alpha
|
|
2722
|
-
*/
|
|
2723
|
-
export declare interface TreeNode<TChild, TId> extends NodeData<TId>, HasTraits<TChild> {
|
|
2724
|
-
}
|
|
2725
|
-
|
|
2726
|
-
/* Excluded from this release type: TreeNodeHandle */
|
|
2727
|
-
|
|
2728
|
-
/**
|
|
2729
|
-
* A sequence of Nodes that make up a trait under a Node
|
|
2730
|
-
* @alpha
|
|
2731
|
-
*/
|
|
2732
|
-
export declare type TreeNodeSequence<TChild> = readonly TChild[];
|
|
2733
|
-
|
|
2734
|
-
/**
|
|
2735
|
-
* A view of a distributed tree.
|
|
2736
|
-
* @alpha
|
|
2737
|
-
*/
|
|
2738
|
-
export declare abstract class TreeView {
|
|
2739
|
-
readonly root: NodeId;
|
|
2740
|
-
protected readonly forest: Forest;
|
|
2741
|
-
private readonly rootNode;
|
|
2742
|
-
/**
|
|
2743
|
-
* A cache of node's index within their parent trait.
|
|
2744
|
-
* Used to avoid redundant linear scans of traits.
|
|
2745
|
-
* Not shared across views; initialized to empty each time a TreeView is created.
|
|
2746
|
-
*/
|
|
2747
|
-
private traitIndicesCache?;
|
|
2748
|
-
protected constructor(root: NodeId, forest: Forest);
|
|
2749
|
-
/** @returns the number of nodes in this view */
|
|
2750
|
-
get size(): number;
|
|
2751
|
-
/** @returns true iff a node with the given id exists in this view */
|
|
2752
|
-
hasNode(id: NodeId): boolean;
|
|
2753
|
-
/**
|
|
2754
|
-
* @returns the index just after place (which specifies a location between items).
|
|
2755
|
-
* Performance note: this is O(siblings in trait).
|
|
2756
|
-
*/
|
|
2757
|
-
findIndexWithinTrait(place: TreeViewPlace): PlaceIndex;
|
|
2758
|
-
/** @returns the node associated with the given id in this view. Fails if the node does not exist in this view. */
|
|
2759
|
-
getViewNode(id: NodeId): TreeViewNode;
|
|
2760
|
-
/** @returns the node associated with the given id in this view, or undefined if the node does not exist in this view */
|
|
2761
|
-
tryGetViewNode(id: NodeId): TreeViewNode | undefined;
|
|
2762
|
-
/**
|
|
2763
|
-
* @returns the label of the trait under which a node with the given id resides. Fails if the node does not exist in this view or if
|
|
2764
|
-
* it is the root node.
|
|
2765
|
-
*/
|
|
2766
|
-
getTraitLabel(id: NodeId): TraitLabel;
|
|
2767
|
-
/**
|
|
2768
|
-
* @returns the label of the trait under which a node with the given id resides, or undefined if the node is not present in this
|
|
2769
|
-
* view or if it is the root node
|
|
2770
|
-
*/
|
|
2771
|
-
tryGetTraitLabel(id: NodeId): TraitLabel | undefined;
|
|
2772
|
-
/**
|
|
2773
|
-
* @returns the parent of the node with the given id. Fails if the node does not exist in this view or if it is the root node.
|
|
2774
|
-
*/
|
|
2775
|
-
getParentViewNode(id: NodeId): TreeViewNode;
|
|
2776
|
-
/**
|
|
2777
|
-
* @returns the parent of the node with the given id. Returns undefined if the node does not exist in this view or if it is the root
|
|
2778
|
-
* node.
|
|
2779
|
-
*/
|
|
2780
|
-
tryGetParentViewNode(id: NodeId): TreeViewNode | undefined;
|
|
2781
|
-
/**
|
|
2782
|
-
* @returns the trait location of the node with the given id. Fails if the node does not exist in this view or of it is the root
|
|
2783
|
-
* node
|
|
2784
|
-
*/
|
|
2785
|
-
getTraitLocation(id: NodeId): TraitLocation;
|
|
2786
|
-
/**
|
|
2787
|
-
* @returns the trait location of the node with the given id, or undefined if the node does not exist in this view or if it is the root
|
|
2788
|
-
* node
|
|
2789
|
-
*/
|
|
2790
|
-
tryGetTraitLocation(id: NodeId): TraitLocation | undefined;
|
|
2791
|
-
/**
|
|
2792
|
-
* @returns the index within the trait under which the node with the given id resides. The node must exist in this view and must have a
|
|
2793
|
-
* parent.
|
|
2794
|
-
* Performance note: this is O(siblings in trait).
|
|
2795
|
-
*/
|
|
2796
|
-
getIndexInTrait(id: NodeId): TraitNodeIndex;
|
|
2797
|
-
/**
|
|
2798
|
-
* @returns the index within the trait under which the node with the given id resides, or undefined if the node does not exist in this
|
|
2799
|
-
* view or does not have a parent.
|
|
2800
|
-
* Performance note: this is O(siblings in trait).
|
|
2801
|
-
*/
|
|
2802
|
-
tryGetIndexInTrait(id: NodeId): TraitNodeIndex | undefined;
|
|
2803
|
-
/**
|
|
2804
|
-
* @returns the trait at the given location. If no such trait exists, returns an empty trait.
|
|
2805
|
-
*/
|
|
2806
|
-
getTrait(traitLocation: TraitLocation): readonly NodeId[];
|
|
2807
|
-
/** Asserts that the view's internal state is consistent. Useful for testing/validation. */
|
|
2808
|
-
assertConsistent(): void;
|
|
2809
|
-
[Symbol.iterator](): IterableIterator<TreeViewNode>;
|
|
2810
|
-
/** @returns true iff the given view is equal to this view */
|
|
2811
|
-
abstract equals(view: TreeView): boolean;
|
|
2812
|
-
/**
|
|
2813
|
-
* @returns true iff the given view's forest of nodes is equivalent to this view's forest of nodes
|
|
2814
|
-
* @param strict - if true, the views' forests must be the same object, otherwise they must merely be equivalent
|
|
2815
|
-
*/
|
|
2816
|
-
hasEqualForest(view: TreeView, strict?: boolean): boolean;
|
|
2817
|
-
private iterateNodeDescendants;
|
|
2818
|
-
private getIndexOfSide;
|
|
2819
|
-
/**
|
|
2820
|
-
* Calculate the difference between two `TreeView`s
|
|
2821
|
-
* @param view - the other view to compare to this one
|
|
2822
|
-
* @returns A {@link Delta} which nodes must be changed, added, and removed to get from `this` to `view`.
|
|
2823
|
-
* The views must share a root.
|
|
2824
|
-
*/
|
|
2825
|
-
delta(view: TreeView): Delta<NodeId>;
|
|
2826
|
-
}
|
|
2827
|
-
|
|
2828
|
-
/**
|
|
2829
|
-
* An immutable view of a distributed tree node.
|
|
2830
|
-
* @alpha
|
|
2831
|
-
*/
|
|
2832
|
-
export declare interface TreeViewNode extends NodeData<NodeId> {
|
|
2833
|
-
/** The IDs of the children under this node */
|
|
2834
|
-
readonly traits: ReadonlyMap<TraitLabel, readonly NodeId[]>;
|
|
2835
|
-
/** The parent and trait under which this node resides. Undefined iff this is the root node of the tree (i.e. {@link initialTree}). */
|
|
2836
|
-
readonly parentage?: TraitLocation;
|
|
2837
|
-
}
|
|
2838
|
-
|
|
2839
|
-
/**
|
|
2840
|
-
* A place within a particular `TreeView` that is anchored relative to a specific node in the tree, or relative to the outside of the trait.
|
|
2841
|
-
* Valid iff 'trait' is valid and, if provided, sibling is in the Location specified by 'trait'.
|
|
2842
|
-
* @alpha
|
|
2843
|
-
*/
|
|
2844
|
-
export declare interface TreeViewPlace {
|
|
2845
|
-
readonly sibling?: NodeId;
|
|
2846
|
-
readonly side: Side;
|
|
2847
|
-
readonly trait: TraitLocation;
|
|
2848
|
-
}
|
|
2849
|
-
|
|
2850
|
-
/**
|
|
2851
|
-
* Specifies the range of nodes from `start` to `end` within a trait within a particular `TreeView`.
|
|
2852
|
-
* Valid iff start and end are valid and are within the same trait.
|
|
2853
|
-
* @alpha
|
|
2854
|
-
*/
|
|
2855
|
-
export declare interface TreeViewRange {
|
|
2856
|
-
readonly start: TreeViewPlace;
|
|
2857
|
-
readonly end: TreeViewPlace;
|
|
2858
|
-
}
|
|
2859
|
-
|
|
2860
|
-
/* Excluded from this release type: useFailedSequencedEditTelemetry */
|
|
2861
|
-
|
|
2862
|
-
/**
|
|
2863
|
-
* Type-safe identifiers for specific use cases.
|
|
2864
|
-
*/
|
|
2865
|
-
/**
|
|
2866
|
-
* A 128-bit Universally Unique IDentifier. Represented here
|
|
2867
|
-
* with a string of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,
|
|
2868
|
-
* where x is a lowercase hex digit.
|
|
2869
|
-
* @alpha
|
|
2870
|
-
*/
|
|
2871
|
-
export declare type UuidString = string & {
|
|
2872
|
-
readonly UuidString: '9d40d0ae-90d9-44b1-9482-9f55d59d5465';
|
|
2873
|
-
};
|
|
2874
|
-
|
|
2875
|
-
/**
|
|
2876
|
-
* Result of applying a valid transaction.
|
|
2877
|
-
* @alpha
|
|
2878
|
-
*/
|
|
2879
|
-
export declare interface ValidEditingResult extends EditingResultBase {
|
|
2880
|
-
/**
|
|
2881
|
-
* {@inheritDoc EditingResultBase.status}
|
|
2882
|
-
*/
|
|
2883
|
-
readonly status: EditStatus.Applied;
|
|
2884
|
-
/**
|
|
2885
|
-
* The new revision produced by the transaction.
|
|
2886
|
-
*/
|
|
2887
|
-
readonly after: RevisionView;
|
|
2888
|
-
}
|
|
2889
|
-
|
|
2890
|
-
/**
|
|
2891
|
-
* Format versions that SharedTree supports writing. Changes to op or summary formats necessitate updates.
|
|
2892
|
-
* @alpha
|
|
2893
|
-
*/
|
|
2894
|
-
export declare enum WriteFormat {
|
|
2895
|
-
/** Stores all edits in their raw format. */
|
|
2896
|
-
v0_0_2 = "0.0.2",
|
|
2897
|
-
/** Supports history virtualization, tree compression, string interning, and makes currentView optional. */
|
|
2898
|
-
v0_1_1 = "0.1.1"
|
|
2899
|
-
}
|
|
2900
|
-
|
|
2901
|
-
export { }
|