Skip to main content

TreeNodeApi Interface

Provides various functions for analyzing TreeNodes. *

Signature​

/** @sealed */
export interface TreeNodeApi

Remarks​

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

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 The schema information for this node.
shortId(node) number | string | undefined Returns the identifier of the given node in the most compressed form possible.
status(node) TreeStatus Returns the TreeStatus of the given node.

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(node: TreeNode | TreeLeafValue): TreeNodeSchema;

Parameters​

Parameter Type Description
node TreeNode | TreeLeafValue

Returns​

Return type: TreeNodeSchema

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. Note that the node must already have been inserted into the tree in order to retrieve a generated UUID (or shortId will error). 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

status​

Returns the TreeStatus of the given node.

Signature​

status(node: TreeNode): TreeStatus;

Parameters​

Parameter Type Description
node TreeNode

Returns​

Return type: TreeStatus