TreeBranchAlpha Interface
TreeBranch with alpha-level APIs.
To use, import via @fluidframework/tree/alpha.
For more information about our API support guarantees, see here.
This type is "sealed," meaning that code outside of the library defining it should not implement or extend it. Future versions of this type may add members or make typing of readonly members more specific.
Signature
/** @sealed */
export interface TreeBranchAlpha extends TreeBranch
Extends: TreeBranch
Remarks
The TreeBranch for a specific TreeNode may be acquired by calling TreeAlpha.branch.
A branch does not necessarily know the schema of its SharedTree - to convert a branch to a view with a schema, use hasRootSchema(). \
Properties
| Property | Alerts | Modifiers | Type | Description |
|---|---|---|---|---|
| events | Alpha | readonly | Listenable<TreeBranchEvents> | Events for the branch |
Methods
| Method | Alerts | Return Type | Description |
|---|---|---|---|
| fork() | Alpha | TreeBranchAlpha | |
| hasRootSchema(schema) | Alpha | this is TreeViewAlpha<TSchema> | Returns true if this branch has the given schema as its root schema. |
| runTransaction(transaction, params) | Alpha | TransactionResultExt<TSuccessValue, TFailureValue> | Run a transaction which applies one or more edits to the tree as a single atomic unit. |
| runTransaction(transaction, params) | Alpha | TransactionResult | Run a transaction which applies one or more edits to the tree as a single atomic unit. |
Property Details
events
Events for the branch
For more information about our API support guarantees, see here.
Signature
readonly events: Listenable<TreeBranchEvents>;
Type: Listenable<TreeBranchEvents>
Method Details
fork
For more information about our API support guarantees, see here.
Signature
fork(): TreeBranchAlpha;
Returns
Return type: TreeBranchAlpha
hasRootSchema
Returns true if this branch has the given schema as its root schema.
For more information about our API support guarantees, see here.
Signature
hasRootSchema<TSchema extends ImplicitFieldSchema>(schema: TSchema): this is TreeViewAlpha<TSchema>;
Type Parameters
| Parameter | Constraint | Description |
|---|---|---|
| TSchema | ImplicitFieldSchema |
Remarks
This is a type guard which allows this branch to become strongly typed as a view of the given schema.
To succeed, the given schema must be invariant to the schema of the view - it must include exactly the same allowed types. For example, a schema of Foo | Bar will not match a view schema of Foo, and likewise a schema of Foo will not match a view schema of Foo | Bar.
Example
if (branch.hasRootSchema(MySchema)) {
const { root } = branch; // `branch` is now a TreeViewAlpha<MySchema>
// ...
}
Parameters
| Parameter | Type | Description |
|---|---|---|
| schema | TSchema |
Returns
Return type: this is TreeViewAlpha<TSchema>
runTransaction
Run a transaction which applies one or more edits to the tree as a single atomic unit.
For more information about our API support guarantees, see here.
Signature
runTransaction<TSuccessValue, TFailureValue>(transaction: () => TransactionCallbackStatus<TSuccessValue, TFailureValue>, params?: RunTransactionParams): TransactionResultExt<TSuccessValue, TFailureValue>;
Type Parameters
| Parameter | Description |
|---|---|
| TSuccessValue | |
| TFailureValue |
Remarks
This API will throw an error if the constraints are not met or something unexpected happens. 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 rolled back, a corresponding change event will also be emitted for the rollback.
Nested transactions: This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:
- If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue. - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated for the outermost transaction which includes all inner transactions. - Undo will undo the outermost transaction and all inner transactions.
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| transaction | () => TransactionCallbackStatus<TSuccessValue, TFailureValue> | The function to run as the body of the transaction. It should return a status object of TransactionCallbackStatus type. It includes a "rollback" property which may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so far. "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run. | |
| params | optional | RunTransactionParams | The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins. |
Returns
A result object of TransactionResultExt type. It includes the following:
- A "success" flag indicating whether the transaction was successful or not. - The success or failure value as returned by the transaction function.
Return type: TransactionResultExt<TSuccessValue, TFailureValue>
runTransaction
Run a transaction which applies one or more edits to the tree as a single atomic unit.
For more information about our API support guarantees, see here.
Signature
runTransaction(transaction: () => VoidTransactionCallbackStatus | void, params?: RunTransactionParams): TransactionResult;
Remarks
This API will throw an error if the constraints are not met or something unexpected happens. 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 rolled back, a corresponding change event will also be emitted for the rollback.
Nested transactions: This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:
- If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue. - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated for the outermost transaction which includes all inner transactions. - Undo will undo the outermost transaction and all inner transactions.
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| transaction | () => VoidTransactionCallbackStatus | void | The function to run as the body of the transaction. It may return the following:
| |
| params | optional | RunTransactionParams | The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins. |
Returns
A result object of TransactionResult type. It includes a "success" flag indicating whether the transaction was successful or not.
Return type: TransactionResult