@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.
@@ -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 { }