UntypedTreeViewAlpha Interface

An untyped view of a UntypedTreeView 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 UntypedTreeViewAlpha extends UntypedTreeView, TreeContextAlpha

Extends: UntypedTreeView, TreeContextAlpha

Remarks

The untyped view for a specific TreeNode may be acquired by calling TreeAlpha.context and checking isView().

An untyped view does not necessarily know the schema of its SharedTree. To convert it to a view with a schema, use hasRootSchema().

Properties

Property	Alerts	Modifiers	Type	Description
branchHistory	Alpha	readonly	TreeBranchHistory	APIs for querying the history of the branch being viewed.
events	Alpha	readonly	Listenable<TreeBranchEvents>	Events for the view's underlying branch.

Methods

Method	Alerts	Return Type	Description
applyChange(change)	Alpha	void	Apply a serialized change to this branch.
computeNetChangeIfRebasedOnto(view)	Alpha	JsonCompatibleReadOnly | undefined	Computes the net change that would result if this view were rebased onto the given view. Note that this method does not actually perform the rebase and therefore has no effect on this view.
fork()	Alpha	UntypedTreeViewAlpha
hasRootSchema(schema)	Alpha	this is TreeViewAlpha<TSchema>	Returns true if this view has the given schema as its root schema.
isMissingEditsFrom(view)	Alpha	boolean	Determines if there are changes on the given view that are not present on this view.
revertTo(revision, options)	Alpha	void	Applies a new change which reverts all changes made since the given revision. This is a no-op if the given revision is the head commit of the underlying branch being viewed.
rewindTo(revision)	Alpha	void	Switches this view to a new underlying branch with the given commit as the head, updating the view state accordingly.
runTransaction(transaction, params)	Alpha	TransactionValueResult<TSuccessValue, TFailureValue>	Run a transaction on this view of the SharedTree.
runTransaction(transaction, params)	Alpha	TransactionVoidResult	An overload of runTransaction which does not return a value.
runTransactionAsync(transaction, params)	Alpha	Promise<TransactionValueResult<TSuccessValue, TFailureValue>>	An asynchronous version of runTransaction.
runTransactionAsync(transaction, params)	Alpha	Promise<TransactionVoidResult>	An overload of runTransactionAsync which does not return a value.

Property Details

branchHistory

APIs for querying the history of the branch being viewed.

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 branchHistory: TreeBranchHistory;

Type: TreeBranchHistory

events

Events for the view's underlying 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.

computeNetChangeIfRebasedOnto

Computes the net change that would result if this view were rebased onto the given view. Note that this method does not actually perform the rebase and therefore has no effect on this view.

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

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

Signature

computeNetChangeIfRebasedOnto(view: UntypedTreeView): JsonCompatibleReadOnly | undefined;

Parameters

Parameter	Type	Description
view	UntypedTreeView	The view that would be rebased onto.

Returns

The net change that would result if this view were rebased onto the given view, or undefined if rebasing would have no impact.

Return type: JsonCompatibleReadOnly | undefined

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

Returns

Return type: UntypedTreeViewAlpha

hasRootSchema

Returns true if this view 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 view 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 (view.hasRootSchema(MySchema)) {
  const { root } = view; // `view` is now a TreeViewAlpha<MySchema>
  // ...
}

Parameters

Parameter	Type	Description
schema	TSchema

Returns

Return type: this is TreeViewAlpha<TSchema>

isMissingEditsFrom

Determines if there are changes on the given view that are not present on this view.

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

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

Signature

isMissingEditsFrom(view: UntypedTreeView): boolean;

Parameters

Parameter	Type	Description
view	UntypedTreeView	The view to compare to. The new edits, if any, can be applied to this view by rebasing this view onto the given view or by merging the given view into this view.

Returns

Return type: boolean

Error Handling

UsageError if the branches are unrelated.

revertTo

Applies a new change which reverts all changes made since the given revision. This is a no-op if the given revision is the head commit of the underlying branch being viewed.

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

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

Signature

revertTo(revision: CommitRevision, options?: RevertToOptionsAlpha): void;

Remarks

The generated change is subject to the same merge semantics as the reverts of individual commits: Concurrent changes that are sequenced before the revert will not be overwritten by the revert if they affect different parts of the document.

Unlike rewindTo, this does not switch to a new branch.

Parameters

Parameter	Modifiers	Type	Description
revision		CommitRevision	The revision to restore the state of. Can be obtained by navigating the commits on the branch history.
options	optional	RevertToOptionsAlpha	Optional options for the revert.

rewindTo

Switches this view to a new underlying branch with the given commit as the head, updating the view state accordingly.

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

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

Signature

rewindTo(revision: CommitRevision): void;

Remarks

Unlike revertTo, this does not apply a change to the underlying branch. The original underlying branch will be disposed. Consider forking before rewinding. Not valid to invoke on the main branch or a shared branch.

Parameters

Parameter	Type	Description
revision	CommitRevision	The revision to rewind to. Can be obtained by navigating the commits on the branch history.

runTransaction

Run a transaction on this view 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: () => TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue>, params?: RunTransactionParamsAlpha): TransactionValueResult<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		() => TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue>	The function to run as the body of the transaction, which may optionally return a value or rollback signal.
params	optional	RunTransactionParamsAlpha

Returns

Return type: TransactionValueResult<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: () => VoidTransactionCallbackStatusAlpha | void, params?: RunTransactionParamsAlpha): TransactionVoidResult;

Parameters

Parameter	Modifiers	Type	Description
transaction		() => VoidTransactionCallbackStatusAlpha | void
params	optional	RunTransactionParamsAlpha

Returns

Return type: TransactionVoidResult

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<TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue>>, params?: RunTransactionParamsAlpha): Promise<TransactionValueResult<TSuccessValue, TFailureValue>>;

Type Parameters

Parameter	Description
TSuccessValue
TFailureValue

Remarks

See runTransactionAsync for additional information about asynchronous transactions.

Parameters

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

Returns

Return type: Promise<TransactionValueResult<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<VoidTransactionCallbackStatusAlpha | void>, params?: RunTransactionParamsAlpha): Promise<TransactionVoidResult>;

Parameters

Parameter	Modifiers	Type	Description
transaction		() => Promise<VoidTransactionCallbackStatusAlpha | void>
params	optional	RunTransactionParamsAlpha

Returns

Return type: Promise<TransactionVoidResult>