Packages > @fluidframework/tree > TreeApi
TreeApi Interface
Provides various functions for interacting with TreeNode s.
Signature
export interface TreeApi extends TreeNodeApi
Extends: TreeNodeApi
Methods
| Method | Return Type | Description |
|---|---|---|
| contains(node, other) | boolean |
Check if the subtree defined by node contains other.
|
| runTransaction(node, transaction) | void | Apply one or more edits to the tree as a single atomic unit. |
| runTransaction(node, transaction, preconditions) | void | Apply one or more edits to the tree as a single atomic unit. |
| runTransaction(tree, transaction) | void | Apply one or more edits to the tree as a single atomic unit. |
| runTransaction(tree, transaction, preconditions) | void | Apply one or more edits to the tree as a single atomic unit. |
Method Details
contains
Check if the subtree defined by node contains other.
Signature
contains(node: TreeNode, other: TreeNode): boolean;
Remarks
This includes direct and indirect children: as long as node is an ancestor of other (occurs in its parentage chain), this returns true, regardless of the number of levels of the tree between.
node is considered to contain itself, so the case where node === other returns true.
This is handy when checking if moving node into other would create a cycle and thus is invalid.
This check walks the parents of other looking for node, and thus runs in time proportional to the depth of child in the tree.
Parameters
| Parameter | Type | Description |
|---|---|---|
| node | TreeNode | |
| other | TreeNode |
Returns
true if other is an inclusive descendant of node, and false otherwise.
Return type: boolean
runTransaction
Apply one or more edits to the tree as a single atomic unit.
Signature
runTransaction<TNode extends TreeNode>(node: TNode, transaction: (node: TNode) => void | "rollback"): void;
Type Parameters
| Parameter | Constraint | Description |
|---|---|---|
| TNode | TreeNode |
Remarks
All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes. Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not. However, using a transaction has the following additional consequences: - If reverted (e.g. via an “undo” operation), all the changes in the transaction are reverted together. - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
Local change events will be emitted for each change as the transaction is being applied. If the transaction is cancelled and rolled back, a corresponding change event will also be emitted for the rollback.
Parameters
| Parameter | Type | Description |
|---|---|---|
| node | TNode |
The node that will be passed to transaction. This is typically the root node of the subtree that will be modified by the transaction.
|
| transaction | (node: TNode) => void | "rollback" |
The function to run as the body of the transaction. This function is passed the provided node. At any point during the transaction, the function may return the value "rollback" to abort the transaction and discard any changes it made so far.
|
runTransaction
Apply one or more edits to the tree as a single atomic unit.
Signature
runTransaction<TNode extends TreeNode>(node: TNode, transaction: (node: TNode) => void | "rollback", preconditions?: TransactionConstraint[]): void;
Type Parameters
| Parameter | Constraint | Description |
|---|---|---|
| TNode | TreeNode |
Remarks
All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes. Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not. However, using a transaction has the following additional consequences: - If reverted (e.g. via an “undo” operation), all the changes in the transaction are reverted together. - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
Local change events will be emitted for each change as the transaction is being applied. If the transaction is cancelled and rolled back, a corresponding change event will also be emitted for the rollback.
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| node | TNode |
The node that will be passed to transaction. This is typically the root node of the subtree that will be modified by the transaction.
|
|
| transaction | (node: TNode) => void | "rollback" |
The function to run as the body of the transaction. This function is passed the provided node. At any point during the transaction, the function may return the value "rollback" to abort the transaction and discard any changes it made so far.
|
|
| preconditions | optional | TransactionConstraint[] |
An optional list of constraints that are checked just before the transaction begins. If any of the constraints are not met when runTransaction is called, it will throw an error. If any of the constraints are not met when this transaction is sequenced (on this client or other clients), the transaction will not be run.
|
runTransaction
Apply one or more edits to the tree as a single atomic unit.
Signature
runTransaction<TView extends TreeView<ImplicitFieldSchema>>(tree: TView, transaction: (root: TView["root"]) => void | "rollback"): void;
Type Parameters
| Parameter | Constraint | Description |
|---|---|---|
| TView | TreeView<ImplicitFieldSchema> |
Remarks
All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes. Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not. However, using a transaction has the following additional consequences: - If reverted (e.g. via an “undo” operation), all the changes in the transaction are reverted together. - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
Local change events will be emitted for each change as the transaction is being applied. If the transaction is cancelled and rolled back, a corresponding change event will also be emitted for the rollback.
Parameters
| Parameter | Type | Description |
|---|---|---|
| tree | TView | The tree which will be edited by the transaction |
| transaction | (root: TView["root"]) => void | "rollback" |
The function to run as the body of the transaction. This function is passed the root of the tree. At any point during the transaction, the function may return the value "rollback" to abort the transaction and discard any changes it made so far.
|
runTransaction
Apply one or more edits to the tree as a single atomic unit.
Signature
runTransaction<TView extends TreeView<ImplicitFieldSchema>>(tree: TView, transaction: (root: TView["root"]) => void | "rollback", preconditions?: TransactionConstraint[]): void;
Type Parameters
| Parameter | Constraint | Description |
|---|---|---|
| TView | TreeView<ImplicitFieldSchema> |
Remarks
All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes. Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not. However, using a transaction has the following additional consequences: - If reverted (e.g. via an “undo” operation), all the changes in the transaction are reverted together. - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
Local change events will be emitted for each change as the transaction is being applied. If the transaction is cancelled and rolled back, a corresponding change event will also be emitted for the rollback.
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| tree | TView | The tree which will be edited by the transaction | |
| transaction | (root: TView["root"]) => void | "rollback" |
The function to run as the body of the transaction. This function is passed the root of the tree. At any point during the transaction, the function may return the value "rollback" to abort the transaction and discard any changes it made so far.
|
|
| preconditions | optional | TransactionConstraint[] |
An optional list of constraints that are checked just before the transaction begins. If any of the constraints are not met when runTransaction is called, it will throw an error. If any of the constraints are not met when this transaction is sequenced (on this client or other clients), the transaction will not be run.
|