TreeBranchAlpha Interface

TreeBranch with alpha-level APIs.

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

To use, import via fluid-framework/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 TreeBranchAlpha extends TreeBranch, TreeContextAlpha

Extends: TreeBranch, TreeContextAlpha

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
applyChange(change)	Alpha	void	Apply a serialized change to this branch.
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 on a branch of the SharedTree.
runTransaction(transaction, params)	Alpha	TransactionResult	An overload of runTransaction which does not return a value.
runTransactionAsync(transaction, params)	Alpha	Promise<TransactionResultExt<TSuccessValue, TFailureValue>>	An asynchronous version of runTransaction.
runTransactionAsync(transaction, params)	Alpha	Promise<TransactionResult>	An overload of runTransactionAsync which does not return a value.

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

applyChange

Apply a serialized change 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

applyChange(change: JsonCompatibleReadOnly): void;

Remarks

Changes may only be applied to a SharedTree with the same IdCompressor instance and branch state from which they were generated. They may be created by one branch and applied to another, but only if both branches share the same history at the time of creation and application.

Parameters

Parameter	Type	Description
change	JsonCompatibleReadOnly	the change to apply. Changes are acquired via getChange in a branch's "changed" event.

fork

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(): TreeBranchAlpha;

Returns

Return type: TreeBranchAlpha

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>

runTransaction

Run a transaction on a branch of the SharedTree.

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

If the transaction is rolled back, a corresponding `changed` event will also be emitted for the rollback.

Parameters

Parameter	Modifiers	Type	Description
transaction		() => TransactionCallbackStatus<TSuccessValue, TFailureValue>	The function to run as the body of the transaction, which may optionally return a value or rollback signal.
params	optional	RunTransactionParams

Returns

Return type: TransactionResultExt<TSuccessValue, TFailureValue>

runTransaction

An overload of runTransaction which does not return a value.

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;

Parameters

Parameter	Modifiers	Type	Description
transaction		() => VoidTransactionCallbackStatus | void
params	optional	RunTransactionParams

Returns

Return type: TransactionResult

runTransactionAsync

An asynchronous version of runTransaction.

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

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

Signature

runTransactionAsync<TSuccessValue, TFailureValue>(transaction: () => Promise<TransactionCallbackStatus<TSuccessValue, TFailureValue>>, params?: RunTransactionParams): Promise<TransactionResultExt<TSuccessValue, TFailureValue>>;

Type Parameters

Parameter	Description
TSuccessValue
TFailureValue

Remarks

See runTransactionAsync for additional information about asynchronous transactions.

Parameters

Parameter	Modifiers	Type	Description
transaction		() => Promise<TransactionCallbackStatus<TSuccessValue, TFailureValue>>
params	optional	RunTransactionParams

Returns

Return type: Promise<TransactionResultExt<TSuccessValue, TFailureValue>>

runTransactionAsync

An overload of runTransactionAsync which does not return a value.

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

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

Signature

runTransactionAsync(transaction: () => Promise<VoidTransactionCallbackStatus | void>, params?: RunTransactionParams): Promise<TransactionResult>;

Parameters

Parameter	Modifiers	Type	Description
transaction		() => Promise<VoidTransactionCallbackStatus | void>
params	optional	RunTransactionParams

Returns

Return type: Promise<TransactionResult>