Packages > @fluidframework/tree > TreeNodeApi

TreeNodeApi Interface

Provides various functions for analyzing TreeNode s. *

Signature

/** @sealed */
export interface TreeNodeApi

Remarks

This type should only be used via the public Tree export.

Properties

Property Modifiers Type Description
status readonly (node: TreeNode) => TreeStatus Returns the TreeStatus of the given node.

Methods

Method Return Type Description
is(value, schema) value is TreeNodeFromImplicitAllowedTypes<TSchema> Narrow the type of the given value if it satisfies the given schema.
key(node) string | number The key of the given node under its parent.
on(node, eventName, listener) () => void Register an event listener on the given node.
parent(node) TreeNode | undefined Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).
schema(node) TreeNodeSchema<string, NodeKind, unknown, T> The schema information for this node.
shortId(node) number | string | undefined Returns the identifier of the given node in the most compressed form possible.

Property Details

status

Returns the TreeStatus of the given node.

Signature

readonly status: (node: TreeNode) => TreeStatus;

Type: (node: TreeNode ) => TreeStatus

Method Details

is

Narrow the type of the given value if it satisfies the given schema.

Signature

is<TSchema extends ImplicitAllowedTypes>(value: unknown, schema: TSchema): value is TreeNodeFromImplicitAllowedTypes<TSchema>;
Type Parameters
Parameter Constraint Description
TSchema ImplicitAllowedTypes

Example

if (node.is(myNode, Point)) {
    const y = myNode.y; // `myNode` is now known to satisfy the `Point` schema and therefore has a `y` coordinate.
}

Parameters

Parameter Type Description
value unknown
schema TSchema

Returns

Return type: value is TreeNodeFromImplicitAllowedTypes <TSchema>

key

The key of the given node under its parent.

Signature

key(node: TreeNode): string | number;

Remarks

If node is an element in a TreeArrayNode , this returns the index of node in the array node (a number). Otherwise, this returns the key of the field that it is under (a string).

Parameters

Parameter Type Description
node TreeNode

Returns

Return type: string | number

on

Register an event listener on the given node.

Signature

on<K extends keyof TreeChangeEvents>(node: TreeNode, eventName: K, listener: TreeChangeEvents[K]): () => void;
Type Parameters
Parameter Constraint Description
K keyof TreeChangeEvents

Parameters

Parameter Type Description
node TreeNode The node whose events should be subscribed to.
eventName K Which event to subscribe to.
listener TreeChangeEvents[K] The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.

Returns

A callback function which will deregister the event. This callback should be called only once.

Return type: () => void

parent

Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).

Signature

parent(node: TreeNode): TreeNode | undefined;

Parameters

Parameter Type Description
node TreeNode

Returns

Return type: TreeNode | undefined

schema

The schema information for this node.

Signature

schema<T extends TreeNode | TreeLeafValue>(node: T): TreeNodeSchema<string, NodeKind, unknown, T>;
Type Parameters
Parameter Constraint Description
T TreeNode | TreeLeafValue

Parameters

Parameter Type Description
node T

Returns

Return type: TreeNodeSchema <string, NodeKind , unknown, T>

shortId

Returns the identifier of the given node in the most compressed form possible.

Signature

shortId(node: TreeNode): number | string | undefined;

Remarks

If the node’s identifier is a valid UUID that was automatically generated by the SharedTree, then this will return a process-unique integer corresponding to that identifier. This is useful for performance-sensitive scenarios involving many nodes with identifiers that need to be compactly retained in memory or used for efficient lookup.

If the node’s identifier is any other user-provided string, then this will return that string.

If the node has no identifier (that is, it has no identifier field), then this returns undefined.

If the node has more than one identifier, then this will throw an error.

The returned integer must not be serialized or preserved outside of the current process. Its lifetime is that of the current in-memory instance of the FF container for this client, and it is not guaranteed to be unique or stable outside of that context. The same node’s identifier may, for example, be different across multiple sessions for the same client and document, or different across two clients in the same session.

Parameters

Parameter Type Description
node TreeNode

Returns

Return type: number | string | undefined