Skip to main content

TreeViewAlpha Interface

TreeView with proposed changes to the schema aware typing to allow use with UnsafeUnknownSchema.

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 TreeViewAlpha<in out TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema> extends Omit<TreeView<ReadSchema<TSchema>>, "root" | "initialize">, TreeBranch

Extends: Omit<TreeView<ReadSchema<TSchema>>, "root" | "initialize">, TreeBranch

Type Parameters​

Parameter Constraint Description
TSchema ImplicitFieldSchema | UnsafeUnknownSchema

Properties​

Property Alerts Modifiers Type Description
events Alpha readonly Listenable<TreeViewEvents & TreeBranchEvents>
root Alpha ReadableField<TSchema>

Methods​

Method Alerts Return Type Description
fork() Alpha ReturnType<TreeBranch["fork"]> & TreeViewAlpha<TSchema>
initialize(content) Alpha void
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​

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

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​
readonly events: Listenable<TreeViewEvents & TreeBranchEvents>;

Type: Listenable<TreeViewEvents & TreeBranchEvents>

root​

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

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​
get root(): ReadableField<TSchema>;
set root(newRoot: InsertableField<TSchema>);

Type: ReadableField<TSchema>

Method Details​

fork​

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

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​
fork(): ReturnType<TreeBranch["fork"]> & TreeViewAlpha<TSchema>;

Returns​

Return type: ReturnType<TreeBranch["fork"]> & TreeViewAlpha<TSchema>

initialize​

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

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​
initialize(content: InsertableField<TSchema>): void;

Parameters​

Parameter Type Description
content InsertableField<TSchema>

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.

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​
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 of 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.

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​
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