@fluid-experimental/tree Package

Fluid DDS storing a tree.

Interfaces

Interface	Modifiers	Description
Build		Constructs a sequence of nodes, associates it with the supplied ID, and stores it for use in later changes. Does not modify the document. Valid if (transitively) all DetachedSequenceId are used according to their rules (use here counts as a destination), and all Nodes' identifiers are previously unused.
BuildInternal_0_0_2		Constructs a sequence of nodes, associates it with the supplied ID, and stores it for use in later changes. Does not modify the document. Valid if (transitively) all DetachedSequenceId are used according to their rules (use here counts as a destination), and all Nodes' identifiers are previously unused.
BuildInternal		Constructs a sequence of nodes, associates it with the supplied ID, and stores it for use in later changes. Does not modify the document. Valid if (transitively) all DetachedSequenceId are used according to their rules (use here counts as a destination), and all Nodes' identifiers are previously unused.
BuildTreeNode		Node for use in a Build change, which is composed of a definition describing what this nodes type, an identifier identifying this node within the tree, and a payload containing an opaque serializable piece of data. An identifier can be provided explicitly if the node must be referred to before the results of the Change containing this BuildTreeNode can be observed. If identifier is not supplied, one will be generated for it in an especially efficient manner that allows for compact storage and transmission and thus this property should be omitted if convenient. See the SharedTree readme for more on the tree format.
Constraint		A set of constraints on the validity of an Edit. A Constraint is used to detect when an Edit, due to other concurrent edits, may have unintended effects or merge in non-semantic ways. It is processed in order like any other Change in an Edit. It can cause an edit to fail if the various constraints are not met at the time of evaluation (ex: the parentNode has changed due to concurrent editing). Does not modify the document.
ConstraintInternal_0_0_2		A set of constraints on the validity of an Edit. A Constraint is used to detect when an Edit, due to other concurrent edits, may have unintended effects or merge in non-semantic ways. It is processed in order like any other Change in an Edit. It can cause an edit to fail if the various constraints are not met at the time of evaluation (ex: the parentNode has changed due to concurrent editing). Does not modify the document.
ConstraintInternal		A set of constraints on the validity of an Edit. A Constraint is used to detect when an Edit, due to other concurrent edits, may have unintended effects or merge in non-semantic ways. It is processed in order like any other Change in an Edit. It can cause an edit to fail if the various constraints are not met at the time of evaluation (ex: the parentNode has changed due to concurrent editing). Does not modify the document.
Delta		Differences from one forest to another.
Detach		Removes a sequence of nodes from the tree. If a destination is specified, the detached sequence is associated with that ID and held for possible reuse by later changes in this same Edit (such as by an Insert). A Detach without a destination is a deletion of the specified sequence, as is a Detach with a destination that is not used later.
DetachInternal_0_0_2		Removes a sequence of nodes from the tree. If a destination is specified, the detached sequence is associated with that ID and held for possible reuse by later changes in this same Edit (such as by an Insert). A Detach without a destination is a deletion of the specified sequence, as is a Detach with a destination that is not used later.
DetachInternal		Removes a sequence of nodes from the tree. If a destination is specified, the detached sequence is associated with that ID and held for possible reuse by later changes in this same Edit (such as by an Insert). A Detach without a destination is a deletion of the specified sequence, as is a Detach with a destination that is not used later.
Edit		A collection of changes to the tree that are applied atomically along with a unique identifier for the edit. If any individual change fails to apply, the entire Edit will fail to apply.
EditBase		The information included in an edit.
EditCommittedEventArguments		The arguments included when the EditCommitted SharedTreeEvent is emitted.
EditHandle		EditHandles are used to load edit chunks stored outside of the EditLog. This is typically implemented by a wrapper around an IFluidHandle.
EditingResultBase		Basic result of applying a transaction.
EditLogSummary		Information used to populate an edit log. In 0.1.1, this is a persisted type only for EditLogSummary<CompressedChangeInternal, FluidEditHandle>, where calling FluidEditHandle.get returns an array buffer of compressed editChunk contents. The type is parameterized to avoid nearly identical type definitions for uncompressed forms of the edit log, and abstracting away the fact that handle fetching needs to invoke decompression.
EditWithoutId		A collection of changes to the tree that are applied atomically. If any individual change fails to apply, the entire Edit will fail to apply.
FailedEditingResult		Result of applying an invalid or malformed transaction.
FailingTransactionState		The state of a transaction that has encountered an error.
FluidEditHandle		FluidEditHandles are used to load edit chunks stored outside of the EditLog. Can be satisfied by IFluidHandle. Note that though this is in PersistedTypes, it isn't directly serializable (e.g. get is a function). Its serialization relies on being encoded via an IFluidSerializer.
ForestNode		A node that can be contained within a Forest
GenericTransactionPolicy		An object that encapsulates the rules and state pertaining to a specific subclass of GenericTransaction. The characteristics that define such a subclass (and an implementation of this interface) are: - The type of change that can be applied - How those changes impact the state of the tree - How those changes are resolved in the face of concurrent changes - What makes a transaction valid - The kind of situations that might lead to a transaction failure Instances of this type are passed to the GenericTransaction constructor.
HasTraits		An object which may have traits with children of the given type underneath it
HasVariadicTraits		An object which may have traits with children of the given type underneath it
ICheckoutEvents		Events which may be emitted by Checkout. See CheckoutEvent for documentation of event semantics.
Insert		Inserts a sequence of nodes at the specified destination. The source can be constructed either by a Build (used to insert new nodes) or a Detach (amounts to a "move" operation).
InsertInternal_0_0_2		Inserts a sequence of nodes at the specified destination. The source can be constructed either by a Build (used to insert new nodes) or a Detach (amounts to a "move" operation).
InsertInternal		Inserts a sequence of nodes at the specified destination. The source can be constructed either by a Build (used to insert new nodes) or a Detach (amounts to a "move" operation).
InternalizedChange		This type should be used as an opaque handle in the public API for ChangeInternal objects. This is useful for supporting public APIs which involve working with a tree's edit history, which will involve changes that have already been internalized.
ISharedTreeEvents		Events which may be emitted by SharedTree. See SharedTreeEvent for documentation of event semantics.
LogViewer		Creates RevisionViews for the revisions in an EditLog
MergeHealthStats		Statistics about the health of collaborative edit merging when using SharedTree. All of those numbers constitute a tally since the last heartbeat was logged or cleared.
NodeData		The fields required by a node in a tree
NodeIdBrand
NodeIdContext		An object which can generate node IDs and convert node IDs between compressed and stable variants
NodeIdConverter		An object which can convert node IDs between compressed and stable variants
NodeIdGenerator		An object which can generate node IDs
NodeInTrait		Contains some redundant information. Use only in computations between edits. Do not store.
OrderedEditSet	sealed	An ordered set of Edits associated with a SharedTree. Supports fast lookup of edits by ID and enforces idempotence. Edits are virtualized, however, edits added during the current session are guaranteed to be available synchronously.
ParentData		Information about a ForestNode's parent
ReconciliationChange		A change in the ReconciliationPath.
ReconciliationEdit		An edit in the ReconciliationPath.
ReconciliationPath		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 change is actually applied. The path only contains edits that were successfully applied. This path is always empty for a change that has no concurrent edits.
SequencedEditAppliedEventArguments		The arguments included when the SequencedEditApplied SharedTreeEvent is emitted.
SessionUnique		A brand for identity types that are unique within a particular session (SharedTree instance).
SetValue		Modifies the payload of a node.
SetValueInternal_0_0_2		Modifies the payload of a node.
SetValueInternal		Modifies the payload of a node.
SharedTreeOptions_0_0_2		Configuration options for a SharedTree with write format 0.0.2
SharedTreeOptions_0_1_1		Configuration options for a SharedTree with write format 0.1.1
SharedTreeSummaryBase		The minimal information on a SharedTree summary. Contains the summary format version.
StablePlace		A location in a trait. This is NOT the location of a node, but a location where a node could be inserted: it is next to a sibling or at one end of the trait. To be well formed, either sibling or trait must be defined, but not both. Any given insertion location can be described by two StablePlace objects, one with Side.After and one with Side.Before. For example, in a trait containing two strings "foo" and "bar", there are 6 different StablePlaces corresponding to 3 locations in the trait a new node could be inserted: at the start, before "foo", after "foo", before "bar", after "bar", and at the end. Neither of the two ways to specify the same location are considered to be after each other. The anchor (referenceSibling or referenceTrait) used for a particular StablePlace can have an impact in collaborative scenarios. StablePlace objects can be conveniently constructed with the helper methods exported on a constant of the same name.
StablePlaceInternal_0_0_2		A location in a trait. This is NOT the location of a node, but a location where a node could be inserted: it is next to a sibling or at one end of the trait. To be well formed, either sibling or trait must be defined, but not both. Any given insertion location can be described by two StablePlace objects, one with Side.After and one with Side.Before. For example, in a trait containing two strings "foo" and "bar", there are 6 different StablePlaces corresponding to 3 locations in the trait a new node could be inserted: at the start, before "foo", after "foo", before "bar", after "bar", and at the end. Neither of the two ways to specify the same location are considered to be after each other. The anchor (referenceSibling or referenceTrait) used for a particular StablePlace can have an impact in collaborative scenarios. StablePlace objects can be conveniently constructed with the helper methods exported on a constant of the same name.
StablePlaceInternal		A location in a trait. This is NOT the location of a node, but a location where a node could be inserted: it is next to a sibling or at one end of the trait. To be well formed, either sibling or trait must be defined, but not both. Any given insertion location can be described by two StablePlace objects, one with Side.After and one with Side.Before. For example, in a trait containing two strings "foo" and "bar", there are 6 different StablePlaces corresponding to 3 locations in the trait a new node could be inserted: at the start, before "foo", after "foo", before "bar", after "bar", and at the end. Neither of the two ways to specify the same location are considered to be after each other. The anchor (referenceSibling or referenceTrait) used for a particular StablePlace can have an impact in collaborative scenarios. StablePlace objects can be conveniently constructed with the helper methods exported on a constant of the same name.
StableRange		Specifies the range of nodes from start to end within a trait. 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. See StablePlace for what it means for a place to be "after" another place. StableRange objects can be conveniently constructed with the helper methods exported on a constant of the same name.
StableRangeInternal_0_0_2		Specifies the range of nodes from start to end within a trait. 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. See StablePlace for what it means for a place to be "after" another place. StableRange objects can be conveniently constructed with the helper methods exported on a constant of the same name.
StableRangeInternal		Specifies the range of nodes from start to end within a trait. 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. See StablePlace for what it means for a place to be "after" another place. StableRange objects can be conveniently constructed with the helper methods exported on a constant of the same name.
StashedLocalOpMetadata		Contains information resulting from processing stashed shared tree ops
StringInterner		Interns strings as integers.
SucceedingTransactionState		The state of a transaction that has not encountered an error.
TraitLocation		Specifies the location of a trait (a labeled sequence of nodes) within the tree.
TraitLocationInternal_0_0_2		Specifies the location of a trait (a labeled sequence of nodes) within the tree.
TraitLocationInternal		Specifies the location of a trait (a labeled sequence of nodes) within the tree.
TraitMap		Json compatible map as object. Keys are TraitLabels, Values are the content of the trait specified by the key.
TransactionEvents		Events which may be emitted by Transaction
TransactionFailure		The failure state of a transaction.
TreeNode		Satisfies NodeData and may contain children under traits (which may or may not be TreeNodes)
TreeViewNode		An immutable view of a distributed tree node.
TreeViewPlace		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. Valid iff 'trait' is valid and, if provided, sibling is in the Location specified by 'trait'.
TreeViewRange		Specifies the range of nodes from start to end within a trait within a particular TreeView. Valid iff start and end are valid and are within the same trait.
ValidEditingResult		Result of applying a valid transaction.

Classes

Class	Modifiers	Description
Checkout		A mutable Checkout of a SharedTree, allowing viewing and interactive transactional editing. Provides snapshot-isolation while editing. A Checkout always shows a consistent sequence of versions of the SharedTree, but it may skip intermediate versions, and may fall behind. In this case consistent means the sequence of versions could occur with fully synchronous shared tree access, though the timing of sequenced edits arriving to the Checkout may be later than they actually arrive in the SharedTree. Specifically no sequenced edits will arrive during an ongoing edit (to implement snapshot isolation): they will be applied asynchronously some time after the ongoing edit is ended. Events emitted by Checkout are documented in CheckoutEvent. Exceptions thrown during event handling will be emitted as error events, which are automatically surfaced as error events on the SharedTree used at construction time.
EagerCheckout	sealed	Checkout that always stays up to date with the SharedTree. This means that waitForPendingUpdates() is always a no-op since EagerCheckout is always up to date.
Forest		An immutable forest of ForestNode. Enforces single parenting, and allows querying the parent.
GenericTransaction		A mutable transaction for applying sequences of changes to a TreeView. Allows viewing the intermediate states. Contains necessary state to apply changes within an edit to a TreeView. May have any number of changes applied to make up the edit. Use close to complete the transaction, returning the array of changes and an EditingResult showing the results of applying the changes as an Edit to the initial TreeView (passed to the constructor). No data outside the Transaction is modified by Transaction: the results from close must be used to actually submit an Edit.
LazyCheckout	sealed	Checkout that only updates its view of the tree when explicitly requested. This means that the currentView field will never change unless waitForPendingUpdates() is called.
RevisionView		An immutable view of a distributed tree.
SharedTree		A [distributed tree](../Readme.md).
SharedTreeFactory		Factory for SharedTree. Includes history in the summary.
SharedTreeMergeHealthTelemetryHeartbeat		Aggregates and logs telemetry about the success of concurrent edits.
Transaction		Buffers changes to be applied to an isolated view of a SharedTree over time before applying them directly to the tree itself as a single edit
TransactionView		An view of a distributed tree that is part of an ongoing transaction between RevisionViews.
TreeNodeHandle		A handle to a TreeNode that exists within a specific TreeView. This type provides a convenient API for traversing trees of nodes in a TreeView and is not designed to provide maximum runtime performance; if performance is a concern, consider using the TreeView and TreeViewNode APIs directly.
TreeView		A view of a distributed tree.

Enumerations

Enum	Description
ChangeType	The type of a Change
ChangeTypeInternal	The type of a Change
CheckoutEvent	An event emitted by a Checkout to indicate a state change. See ICheckoutEvents for event argument information.
ConstraintEffect	What to do when a Constraint is violated.
EditStatus	The status code of an attempt to apply the changes in an Edit.
EditValidationResult	The result of validation of an Edit.
PlaceValidationResult	The result of validating a place.
RangeValidationResultKind	The kinds of result of validating a range.
SharedTreeDiagnosticEvent	An event emitted by a SharedTree for diagnostic purposes. See ISharedTreeEvents for event argument information.
SharedTreeEvent	An event emitted by a SharedTree to indicate a state change. See ISharedTreeEvents for event argument information.
Side	Defines a place relative to sibling. The "outside" of a trait is the undefined sibling, so After undefined is the beginning of the trait, and before undefined is the end. For this purpose, traits look like: {undefined} - {Node 0} - {Node 1} - ... - {Node N} - {undefined} Each {value} in the diagram is a possible sibling, which is either a Node or undefined. Each - in the above diagram is a Place, and can be describe as being After a particular {sibling} or Before it. This means that After {undefined} means the same Place as before the first node and Before {undefined} means the Place after the last Node. Each place can be specified, (aka 'anchored') in two ways (relative to the sibling before or after): 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 two place description may no longer evaluate to the same place.
TransactionEvent	An event emitted by a Transaction to indicate a state change. See TransactionEvents for event argument information.
WriteFormat	Format versions that SharedTree supports writing. Changes to op or summary formats necessitate updates.

Types

TypeAlias	Description
AttributionId	An identifier associated with a session for the purpose of attributing its created content to some user/entity.
BadPlaceValidationResult	The result of validating a bad place.
BadRangeValidationResult	The result of validating a bad range.
BuildNode	Node or a detached sequence of nodes (referred to by a detached sequence ID) for use in a Build change. See BuildTreeNode for more.
BuildNodeInternal_0_0_2	Node or a detached sequence of nodes (referred to by a detached sequence ID) for use in a Build change. See BuildTreeNode for more.
BuildNodeInternal	Node or a detached sequence of nodes (referred to by a detached sequence ID) for use in a Build change. See BuildTreeNode for more.
Change	A change that composes an Edit. Change objects can be conveniently constructed with the helper methods exported on a constant of the same name.
ChangeInternal	A change that composes an Edit. Change objects can be conveniently constructed with the helper methods exported on a constant of the same name.
ChangeNode_0_0_2	JSON-compatible Node type. Objects of this type will be persisted in internal change objects (under Edits) in the SharedTree history.
ChangeNode	JSON-compatible Node type. Objects of this type will be persisted in internal change objects (under Edits) in the SharedTree history.
ChangeResult	The result of applying a change within a transaction.
CompressedId	An identifier (UUID) that has been shortened by a distributed compression algorithm.
Definition	Definition. A full (Uuid) persistable definition.
DetachedSequenceId	Scoped to a single edit: identifies a sequences of nodes that can be moved into a trait. Within a given Edit, any DetachedSequenceId must be a source at most once, and a destination at most once. If used as a source, it must be after it is used as a destination. If this is violated, the Edit is considered malformed.
EditApplicationOutcome	The outcome of an edit.
EditCommittedHandler	Expected type for a handler of the EditCommitted event.
EditId	Edit identifier
EditingResult	Result of applying a transaction.
FinalCompressedId	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. It should not be persisted outside of the history as it can only be decompressed in the context of the originating document. If external persistence is needed (e.g. by a client), a StableId should be used instead.
InternedStringId	The ID of the string that has been interned, which can be used by a StringInterner to retrieve the original string.
LocalCompressedId	A compressed ID that is local to a session (can only be decompressed when paired with a SessionId). It should not be persisted outside of the history as it can only be decompressed in the context of the originating session. If external persistence is needed (e.g. by a client), a StableId should be used instead.
NodeId	Node identifier. Identifies a node within a document.
Payload	Json compatible representation of a payload storing arbitrary Serializable data. Keys starting with "IFluid" are reserved for special use such as the JavaScript feature detection pattern and should not be used. See comparePayloads(a, b) for equality semantics and related details (like what is allowed to be lost when serializing) TODO:#51984: Allow opting into heuristic blobbing in snapshots with a special IFluid key.
PlaceholderTree	A tree whose nodes are either TreeNodes or a placeholder
PlaceIndex	Index of a place within a trait. 0 = before all nodes, 1 = after first node, etc.
RangeValidationResult	The result of validating a range.
Result	Discriminated union instance that wraps either a result of type TOk or an error of type TError.
Revision	A revision corresponds to an index in an EditLog. It is associated with the output RevisionView of applying the edit at the index to the previous revision. For example: - revision 0 corresponds to the initialRevision. - revision 1 corresponds to the output of editLog[0] applied to the initialRevision.
SequencedEditAppliedHandler	Expected type for a handler of the SequencedEditApplied event.
SessionSpaceCompressedId	A compressed ID that has been normalized into "session space" (see IdCompressor for more). Consumer-facing APIs and data structures should use session-space IDs as their lifetime and equality is stable and tied to the compressor that produced them.
SharedTreeArgs	The write format and associated options used to construct a SharedTree
SharedTreeOptions	The type of shared tree options for a given write format
StableNodeId	Globally unique node identifier. Uniquely identifies a node within and across documents. Can be used across SharedTree instances.
TraitLabel	Definition. A full (Uuid) persistable label for a trait.
TraitNodeIndex	Index of a node within a trait. 0 = first node, 1 = second node, etc.
TransactionState	The ongoing state of a transaction.
TreeNodeSequence	A sequence of Nodes that make up a trait under a Node
UuidString	A 128-bit Universally Unique IDentifier. Represented here with a string of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where x is a lowercase hex digit.

Functions

Function	Return Type	Description
areRevisionViewsSemanticallyEqual(treeViewA, idConverterA, treeViewB, idConverterB)	boolean	Compare two views such that semantically equivalent node IDs are considered equal.
comparePayloads(a, b)	boolean
getSerializedUploadedEditChunkContents(sharedTree)	Promise<string>	Returns a serialized description of blob paths and their associated contents for all uploaded edit chunks in the given edit log.
getTraitLocationOfRange(view, range)	TraitLocation	Return the trait under which the given range resides
isSharedTreeEvent(event)	boolean	Returns if the supplied event is a SharedTree telemetry event.
placeFromStablePlace(view, stablePlace)	TreeViewPlace	Express the given StablePlace as a TreeViewPlace
rangeFromStableRange(view, range)	TreeViewRange	Express the given StableRange as a TreeViewRange
setTrait(trait, nodes)	Change[]	Create a sequence of changes that resets the contents of trait.
useFailedSequencedEditTelemetry(tree)	{ disable: () => void; }	Logs generic telemetry for failed sequenced edits. Only failing edits that were originally made locally are logged.

Variables

Variable	Type	Description
Change	{ build: (source: BuildNode | TreeNodeSequence<BuildNode>, destination: number) => Build; insert: (source: number, destination: StablePlace) => Insert; detach: (source: StableRange, destination?: number | undefined) => Detach; setPayload: (nodeToModify: NodeId, payload: Payload) => SetValue; clearPayload: (nodeToModify: NodeId) => SetValue; constraint: (toConstrain: StableRange, effect: ConstraintEffect, identityHash?: UuidString | undefined, length?: number | undefined, contentHash?: UuidString | undefined, parentNode?: NodeId | undefined, label?: TraitLabel | undefined) => Constraint; delete: (stableRange: StableRange) => Change; insertTree: (nodes: BuildNode | TreeNodeSequence<BuildNode>, destination: StablePlace) => Change[]; move: (source: StableRange, destination: StablePlace) => Change[]; }
ChangeInternal	{ build: (source: TreeNodeSequence<BuildNodeInternal>, destination: DetachedSequenceId) => BuildInternal; insert: (source: DetachedSequenceId, destination: StablePlaceInternal) => InsertInternal; detach: (source: StableRangeInternal, destination?: DetachedSequenceId | undefined) => DetachInternal; setPayload: (nodeToModify: NodeData<NodeId> | NodeId, payload: Payload) => SetValueInternal; clearPayload: (nodeToModify: NodeData<NodeId> | NodeId) => SetValueInternal; constraint: (toConstrain: StableRangeInternal, effect: ConstraintEffect, identityHash?: UuidString | undefined, length?: number | undefined, contentHash?: UuidString | undefined, parentNode?: NodeId | undefined, label?: TraitLabel | undefined) => ConstraintInternal; delete: (stableRange: StableRangeInternal) => ChangeInternal; insertTree: (nodes: TreeNodeSequence<BuildNodeInternal>, destination: StablePlaceInternal) => ChangeInternal[]; move: (source: StableRangeInternal, destination: StablePlaceInternal) => ChangeInternal[]; }
initialTree	ChangeNode_0_0_2	The initial tree.
sharedTreeAssertionErrorType		Assertion failures in SharedTree will throw an exception containing this value as an errorType. The Fluid runtime propagates this field in its handlings of errors thrown by containers. See https://github.com/microsoft/FluidFramework/blob/main/packages/loader/container-utils/src/error.ts Exporting this enables users to safely filter telemetry handling of errors based on their type.
StablePlace	{ before: (node: NodeData<NodeId> | NodeId) => StablePlace; after: (node: NodeData<NodeId> | NodeId) => StablePlace; atStartOf: (trait: TraitLocation) => StablePlace; atEndOf: (trait: TraitLocation) => StablePlace; }
StablePlaceInternal	{ before: (node: NodeData<NodeId> | NodeId) => StablePlaceInternal; after: (node: NodeData<NodeId> | NodeId) => StablePlaceInternal; atStartOf: (trait: TraitLocationInternal) => StablePlaceInternal; atEndOf: (trait: TraitLocationInternal) => StablePlaceInternal; }
StableRange	{ from: (start: StablePlace) => { to: (end: StablePlace) => StableRange; }; only: (node: NodeData<NodeId> | NodeId) => StableRange; all: (trait: TraitLocation) => StableRange; }
StableRangeInternal	{ from: (start: StablePlaceInternal) => { to: (end: StablePlaceInternal) => StableRangeInternal; }; only: (node: NodeData<NodeId> | NodeId) => StableRangeInternal; all: (trait: TraitLocationInternal) => StableRangeInternal; }

Namespaces

Namespace	Description
Result
TransactionInternal	A mutable transaction for applying sequences of changes to a TreeView. Allows viewing the intermediate states. Contains necessary state to apply changes within an edit to a TreeView. May have any number of changes applied to make up the edit. Use close to complete the transaction, returning the array of changes and an EditingResult showing the results of applying the changes as an Edit to the initial TreeView (passed to the constructor). No data outside the Transaction is modified by Transaction: the results from close must be used to actually submit an Edit.

Function Details

areRevisionViewsSemanticallyEqual

Compare two views such that semantically equivalent node IDs are considered equal.

Signature

export declare function areRevisionViewsSemanticallyEqual(treeViewA: TreeView, idConverterA: NodeIdConverter, treeViewB: TreeView, idConverterB: NodeIdConverter): boolean;

Parameters

Parameter	Type	Description
treeViewA	TreeView
idConverterA	NodeIdConverter
treeViewB	TreeView
idConverterB	NodeIdConverter

Returns

Return type: boolean

comparePayloads

Signature

export declare function comparePayloads(a: Payload, b: Payload): boolean;

Parameters

Parameter	Type	Description
a	Payload
b	Payload

Returns

true if two Payloads are identical. May return false for equivalent payloads encoded differently.

Object field order and object identity are not considered significant, and are ignored by this function. (This is because they may not be preserved through roundtrip).

For other information which Fluid would lose on serialization round trip, behavior is unspecified other than this this function is reflective (all payloads are equal to themselves) and commutative (argument order does not matter).

This means that any Payload is equal to itself and a deep clone of itself.

Payloads might not be equal to a version of themselves that has been serialized then deserialized. If they are serialized then deserialized again, the two deserialized objects will compare equal, however the serialized strings may be unequal (due to field order for objects being unspecified).

Fluid will cause lossy operations due to use of JSON.stringify(). This includes: - Loss of object identity - Loss of field order (may be ordered arbitrarily) - -0 becomes +0 - NaN, Infinity, -Infinity all become null - custom toJSON functions may cause arbitrary behavior - functions become undefined or null - non enumerable properties (including prototype) are lost - more (this is not a complete list)

Inputs must not contain cyclic references other than fields set to their immediate parent (for the JavaScript feature detection pattern).

IFluidHandle instances (detected via JavaScript feature detection pattern) are only compared by absolutePath.

TODO:#54095: Is there a better way to do this comparison?

Return type: boolean

getSerializedUploadedEditChunkContents

Returns a serialized description of blob paths and their associated contents for all uploaded edit chunks in the given edit log.

Signature

export declare function getSerializedUploadedEditChunkContents(sharedTree: SharedTree): Promise<string>;

Parameters

Parameter	Type	Description
sharedTree	SharedTree

Returns

Return type: Promise<string>

getTraitLocationOfRange

Return the trait under which the given range resides

Signature

export declare function getTraitLocationOfRange(view: TreeView, range: StableRange): TraitLocation;

Parameters

Parameter	Type	Description
view	TreeView	the TreeView within which to retrieve the trait location
range	StableRange	must be well formed and valid

Returns

Return type: TraitLocation

isSharedTreeEvent

Returns if the supplied event is a SharedTree telemetry event.

Signature

export declare function isSharedTreeEvent(event: ITelemetryBaseEvent): boolean;

Parameters

Parameter	Type	Description
event	ITelemetryBaseEvent

Returns

Return type: boolean

placeFromStablePlace

Express the given StablePlace as a TreeViewPlace

Signature

export declare function placeFromStablePlace(view: TreeView, stablePlace: StablePlace): TreeViewPlace;

Parameters

Parameter	Type	Description
view	TreeView
stablePlace	StablePlace

Returns

Return type: TreeViewPlace

rangeFromStableRange

Express the given StableRange as a TreeViewRange

Signature

export declare function rangeFromStableRange(view: TreeView, range: StableRange): TreeViewRange;

Parameters

Parameter	Type	Description
view	TreeView
range	StableRange

Returns

Return type: TreeViewRange

setTrait

Create a sequence of changes that resets the contents of trait.

Signature

export declare function setTrait(trait: TraitLocation, nodes: BuildNode | TreeNodeSequence<BuildNode>): Change[];

Parameters

Parameter	Type	Description
trait	TraitLocation
nodes	BuildNode | TreeNodeSequence<BuildNode>

Returns

Return type: Change[]

useFailedSequencedEditTelemetry

Logs generic telemetry for failed sequenced edits. Only failing edits that were originally made locally are logged.

Signature

export declare function useFailedSequencedEditTelemetry(tree: SharedTree): {
    disable: () => void;
};

Parameters

Parameter	Type	Description
tree	SharedTree	The tree for which to log the telemetry.

Returns

Return type: { disable: () => void; }

Variable Details

Change

Signature

Change: {
    build: (source: BuildNode | TreeNodeSequence<BuildNode>, destination: number) => Build;
    insert: (source: number, destination: StablePlace) => Insert;
    detach: (source: StableRange, destination?: number | undefined) => Detach;
    setPayload: (nodeToModify: NodeId, payload: Payload) => SetValue;
    clearPayload: (nodeToModify: NodeId) => SetValue;
    constraint: (toConstrain: StableRange, effect: ConstraintEffect, identityHash?: UuidString | undefined, length?: number | undefined, contentHash?: UuidString | undefined, parentNode?: NodeId | undefined, label?: TraitLabel | undefined) => Constraint;
    delete: (stableRange: StableRange) => Change;
    insertTree: (nodes: BuildNode | TreeNodeSequence<BuildNode>, destination: StablePlace) => Change[];
    move: (source: StableRange, destination: StablePlace) => Change[];
}

Type: { build: (source: BuildNode | TreeNodeSequence<BuildNode>, destination: number) => Build; insert: (source: number, destination: StablePlace) => Insert; detach: (source: StableRange, destination?: number | undefined) => Detach; setPayload: (nodeToModify: NodeId, payload: Payload) => SetValue; clearPayload: (nodeToModify: NodeId) => SetValue; constraint: (toConstrain: StableRange, effect: ConstraintEffect, identityHash?: UuidString | undefined, length?: number | undefined, contentHash?: UuidString | undefined, parentNode?: NodeId | undefined, label?: TraitLabel | undefined) => Constraint; delete: (stableRange: StableRange) => Change; insertTree: (nodes: BuildNode | TreeNodeSequence<BuildNode>, destination: StablePlace) => Change[]; move: (source: StableRange, destination: StablePlace) => Change[]; }

ChangeInternal

Signature

ChangeInternal: {
    build: (source: TreeNodeSequence<BuildNodeInternal>, destination: DetachedSequenceId) => BuildInternal;
    insert: (source: DetachedSequenceId, destination: StablePlaceInternal) => InsertInternal;
    detach: (source: StableRangeInternal, destination?: DetachedSequenceId | undefined) => DetachInternal;
    setPayload: (nodeToModify: NodeData<NodeId> | NodeId, payload: Payload) => SetValueInternal;
    clearPayload: (nodeToModify: NodeData<NodeId> | NodeId) => SetValueInternal;
    constraint: (toConstrain: StableRangeInternal, effect: ConstraintEffect, identityHash?: UuidString | undefined, length?: number | undefined, contentHash?: UuidString | undefined, parentNode?: NodeId | undefined, label?: TraitLabel | undefined) => ConstraintInternal;
    delete: (stableRange: StableRangeInternal) => ChangeInternal;
    insertTree: (nodes: TreeNodeSequence<BuildNodeInternal>, destination: StablePlaceInternal) => ChangeInternal[];
    move: (source: StableRangeInternal, destination: StablePlaceInternal) => ChangeInternal[];
}

Type: { build: (source: TreeNodeSequence<BuildNodeInternal>, destination: DetachedSequenceId) => BuildInternal; insert: (source: DetachedSequenceId, destination: StablePlaceInternal) => InsertInternal; detach: (source: StableRangeInternal, destination?: DetachedSequenceId | undefined) => DetachInternal; setPayload: (nodeToModify: NodeData<NodeId> | NodeId, payload: Payload) => SetValueInternal; clearPayload: (nodeToModify: NodeData<NodeId> | NodeId) => SetValueInternal; constraint: (toConstrain: StableRangeInternal, effect: ConstraintEffect, identityHash?: UuidString | undefined, length?: number | undefined, contentHash?: UuidString | undefined, parentNode?: NodeId | undefined, label?: TraitLabel | undefined) => ConstraintInternal; delete: (stableRange: StableRangeInternal) => ChangeInternal; insertTree: (nodes: TreeNodeSequence<BuildNodeInternal>, destination: StablePlaceInternal) => ChangeInternal[]; move: (source: StableRangeInternal, destination: StablePlaceInternal) => ChangeInternal[]; }

initialTree

The initial tree.

Signature

initialTree: ChangeNode_0_0_2

Type: ChangeNode_0_0_2

sharedTreeAssertionErrorType

Assertion failures in SharedTree will throw an exception containing this value as an errorType. The Fluid runtime propagates this field in its handlings of errors thrown by containers. See https://github.com/microsoft/FluidFramework/blob/main/packages/loader/container-utils/src/error.ts

Exporting this enables users to safely filter telemetry handling of errors based on their type.

Signature

sharedTreeAssertionErrorType = "SharedTreeAssertion"

StablePlace

Signature

StablePlace: {
    before: (node: NodeData<NodeId> | NodeId) => StablePlace;
    after: (node: NodeData<NodeId> | NodeId) => StablePlace;
    atStartOf: (trait: TraitLocation) => StablePlace;
    atEndOf: (trait: TraitLocation) => StablePlace;
}

Type: { before: (node: NodeData<NodeId> | NodeId) => StablePlace; after: (node: NodeData<NodeId> | NodeId) => StablePlace; atStartOf: (trait: TraitLocation) => StablePlace; atEndOf: (trait: TraitLocation) => StablePlace; }

StablePlaceInternal

Signature

StablePlaceInternal: {
    before: (node: NodeData<NodeId> | NodeId) => StablePlaceInternal;
    after: (node: NodeData<NodeId> | NodeId) => StablePlaceInternal;
    atStartOf: (trait: TraitLocationInternal) => StablePlaceInternal;
    atEndOf: (trait: TraitLocationInternal) => StablePlaceInternal;
}

Type: { before: (node: NodeData<NodeId> | NodeId) => StablePlaceInternal; after: (node: NodeData<NodeId> | NodeId) => StablePlaceInternal; atStartOf: (trait: TraitLocationInternal) => StablePlaceInternal; atEndOf: (trait: TraitLocationInternal) => StablePlaceInternal; }

StableRange

Signature

StableRange: {
    from: (start: StablePlace) => {
        to: (end: StablePlace) => StableRange;
    };
    only: (node: NodeData<NodeId> | NodeId) => StableRange;
    all: (trait: TraitLocation) => StableRange;
}

Type: { from: (start: StablePlace) => { to: (end: StablePlace) => StableRange; }; only: (node: NodeData<NodeId> | NodeId) => StableRange; all: (trait: TraitLocation) => StableRange; }

StableRangeInternal

Signature

StableRangeInternal: {
    from: (start: StablePlaceInternal) => {
        to: (end: StablePlaceInternal) => StableRangeInternal;
    };
    only: (node: NodeData<NodeId> | NodeId) => StableRangeInternal;
    all: (trait: TraitLocationInternal) => StableRangeInternal;
}

Type: { from: (start: StablePlaceInternal) => { to: (end: StablePlaceInternal) => StableRangeInternal; }; only: (node: NodeData<NodeId> | NodeId) => StableRangeInternal; all: (trait: TraitLocationInternal) => StableRangeInternal; }