TreeNodeApi Interface
Packages > @fluidframework/tree > TreeNodeApi
Provides various functions for analyzing TreeNode s. *
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