Skip to main content

TreeBranch Interface

A collection of functionality associated with a (version-control-style) branch of a SharedTree.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/tree/alpha.

For more information about our API support guarantees, see here.

Sealed

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 TreeBranch extends IDisposable

Extends: IDisposable

Remarks​

A TreeBranch allows for the creation of branches and for those branches to later be merged.

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().

The branch associated directly with the SharedTree is the "main" branch, and all other branches fork (directly or transitively) from that main branch. \

Properties​

Property Alerts Modifiers Type Description
events Alpha readonly Listenable<TreeBranchEvents> Events for the branch

Methods​

Method Alerts Return Type Description
dispose(error) Alpha void Dispose of this branch, cleaning up any resources associated with it.
fork() Alpha TreeBranch Fork a new branch off of this branch which is based off of this branch's current state.
hasRootSchema(schema) Alpha this is TreeViewAlpha<TSchema> Returns true if this branch has the given schema as its root schema.
merge(branch, disposeMerged) Alpha void Apply all the new changes on the given branch to this branch.
rebaseOnto(branch) Alpha void Advance this branch forward such that all new changes on the target branch become part of this branch.
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

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature​
readonly events: Listenable<TreeBranchEvents>;

Type: Listenable<TreeBranchEvents>

Method Details​

dispose​

Dispose of this branch, cleaning up any resources associated with it.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature​
dispose(error?: Error): void;
Remarks​

Branches can also be automatically disposed when they are merged into another branch.

Disposing branches is important to avoid consuming memory unnecessarily. In particular, the SharedTree retains all sequenced changes made to the tree since the "most-behind" branch was created or last rebased.

The main branch cannot be disposed - attempting to do so will have no effect.

Parameters​

Parameter Modifiers Type Description
error optional Error Optional error indicating the reason for the disposal, if the object was disposed as the result of an error.

fork​

Fork a new branch off of this branch which is based off of this branch's current state.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature​
fork(): TreeBranch;
Remarks​

Any changes to the tree on the new branch will not apply to this branch until the new branch is e.g. merged back into this branch. The branch should be disposed when no longer needed, either explicitly or implicitly when merging into another branch.

Returns​

Return type: TreeBranch

hasRootSchema​

Returns true if this branch has the given schema as its root schema.

This API is provided as an alpha preview and may change without notice.

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>

merge​

Apply all the new changes on the given branch to this branch.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature​
merge(branch: TreeBranch, disposeMerged?: boolean): void;
Remarks​

All ongoing transactions (if any) in branch will be committed before the merge.

Parameters​

Parameter Modifiers Type Description
branch TreeBranch a branch which was created by a call to branch().
disposeMerged optional boolean whether or not to dispose branch after the merge completes. Defaults to true. The main branch cannot be disposed - attempting to do so will have no effect.

rebaseOnto​

Advance this branch forward such that all new changes on the target branch become part of this branch.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature​
rebaseOnto(branch: TreeBranch): void;
Remarks​

After rebasing, this branch will be "ahead" of the target branch, that is, its unique changes will have been recreated as if they happened after all changes on the target branch. This method may only be called on branches produced via branch - attempting to rebase the main branch will throw.

Rebasing long-lived branches is important to avoid consuming memory unnecessarily. In particular, the SharedTree retains all sequenced changes made to the tree since the "most-behind" branch was created or last rebased.

The main branch cannot be rebased onto another branch - attempting to do so will throw an error.

Parameters​

Parameter Type Description
branch TreeBranch The branch to rebase onto.

runTransaction​

Run a transaction which applies one or more edits to the tree as a single atomic unit.

This API is provided as an alpha preview and may change without notice.

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.

This API is provided as an alpha preview and may change without notice.

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:

  • Nothing to indicate that the body of the transaction has successfully run. - A status object of VoidTransactionCallbackStatus 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 TransactionResult type. It includes a "success" flag indicating whether the transaction was successful or not.

Return type: TransactionResult