TreeBranch Interface
A collection of functionality associated with a (version-control-style) branch of a SharedTree.
To use, import via @fluidframework/tree/alpha.
For more information about our API support guarantees, see here.
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. |
Property Details
events
Events for the branch
To use, import via @fluidframework/tree/alpha.
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.
To use, import via @fluidframework/tree/alpha.
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.
To use, import via @fluidframework/tree/alpha.
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.
To use, import via @fluidframework/tree/alpha.
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.
To use, import via @fluidframework/tree/alpha.
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.
To use, import via @fluidframework/tree/alpha.
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. |