TreeContextAlpha Interface
Provides additional APIs that may be used to interact with a tree node or a tree node's SharedTree.
To use, import via fluid-framework/alpha.
For more information about our API support guarantees, see here.
Signature
export interface TreeContextAlpha
Methods
| Method | Alerts | Return Type | Description |
|---|---|---|---|
| isBranch() | Alpha | this is TreeBranchAlpha | True if this context is associated with a branch and false if it is associated with an unhydrated node. |
| runTransaction(transaction, params) | Alpha | TransactionResultExt<TValue, TValue> | Run a synchronous transaction which groups sequential edits to the tree into a single atomic edit if possible. |
| runTransaction(transaction, params) | Alpha | TransactionResult | An overload of runTransaction which does not return a value. |
| runTransactionAsync(transaction, params) | Alpha | Promise<TransactionResultExt<TValue, TValue>> | An asynchronous version of runTransaction. |
| runTransactionAsync(transaction, params) | Alpha | Promise<TransactionResult> | An overload of runTransactionAsync which does not return a value. |
Method Details
isBranch
True if this context is associated with a branch and false if it is associated with an unhydrated node.
For more information about our API support guarantees, see here.
Signature
isBranch(): this is TreeBranchAlpha;
Remarks
If this returns true, the context can be safely inferred or cast to TreeBranchAlpha to access additional branch-specific APIs.
Example
const context = tree.context(someNode);
if (context.isBranch()) {
assert(context.hasRootSchema(MySchema)) // `hasRootSchema` is a method on TreeBranchAlpha, so this is only accessible if `context` is a branch context.
context.root.foo = "bar"; // Edit the root of the SharedTree that `someNode` belongs to.
}
Returns
Return type: this is TreeBranchAlpha
runTransaction
Run a synchronous transaction which groups sequential edits to the tree into a single atomic edit if possible.
For more information about our API support guarantees, see here.
Signature
runTransaction<TValue>(transaction: () => WithValue<TValue>, params?: RunTransactionParams): TransactionResultExt<TValue, TValue>;
Type Parameters
| Parameter | Description |
|---|---|
| TValue |
Remarks
All of the changes in the transaction are applied synchronously and therefore no other changes 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.
Change events will be emitted for changed nodes on this client _as each edit happens_, just as they would be if the changes were made outside of a transaction. Any other/future clients or contexts will process the transaction "squashed", i.e. they will apply its changes all at once, emitting only a single event per node (even if that node was edited multiple times in the transaction). Edits to the tree are not permitted within these event callbacks, therefore no other local changes from this client will be interleaved with the changes in this transaction.
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. Only the "outermost" transaction commits a change to the synchronized tree state and therefore only the outermost transaction can be reverted. If a transaction is started and completed while another transaction is already in progress, then the inner transaction will be reverted together with the outer transaction. - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
runTransaction may be invoked on the context of a hydrated or unhydrated node. Use isBranch() to check whether this context is associated with a branch and gain access to more transaction capabilities if so.
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| transaction | () => WithValue<TValue> | A callback run during the transaction to perform user-supplied operations. It may optionally return a value, which will be returned by the runTransaction call. | |
| params | optional | RunTransactionParams | Optional parameters for the transaction. |
Returns
A value indicating whether or not the transaction succeeded, and containing the value returned by transaction.
Return type: TransactionResultExt<TValue, TValue>
runTransaction
An overload of runTransaction which does not return a value.
For more information about our API support guarantees, see here.
Signature
runTransaction(transaction: () => void, params?: RunTransactionParams): TransactionResult;
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| transaction | () => void | ||
| params | optional | RunTransactionParams |
Returns
Return type: TransactionResult
runTransactionAsync
An asynchronous version of runTransaction.
For more information about our API support guarantees, see here.
Signature
runTransactionAsync<TValue>(transaction: () => Promise<WithValue<TValue>>, params?: RunTransactionParams): Promise<TransactionResultExt<TValue, TValue>>;
Type Parameters
| Parameter | Description |
|---|---|
| TValue |
Remarks
As with synchronous transactions, all of the changes in an asynchronous transaction are treated as a unit. Therefore, no other changes (either from this client or from a remote client) can be interleaved with the transaction changes.
Unlike with synchronous transactions, it is possible that other changes (e.g. from a remote client) may be applied to the branch while this transaction is in progress. Those other changes will be not be reflected on the branch until after this transaction completes, at which point the transaction changes will be applied after those other changes.
An asynchronous transaction may not be started while any other transaction is in progress in this context.
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| transaction | () => Promise<WithValue<TValue>> | ||
| params | optional | RunTransactionParams |
Returns
Return type: Promise<TransactionResultExt<TValue, TValue>>
runTransactionAsync
An overload of runTransactionAsync which does not return a value.
For more information about our API support guarantees, see here.
Signature
runTransactionAsync(transaction: () => Promise<void>, params?: RunTransactionParams): Promise<TransactionResult>;
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| transaction | () => Promise<void> | ||
| params | optional | RunTransactionParams |
Returns
Return type: Promise<TransactionResult>