TreeNodeApi Interface
Provides various functions for analyzing TreeNodes.
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 TreeNodeApi
Remarks
With the exception of status(node), these functions should not be called with nodes that have been deleted. To verify whether or not a node already has been deleted, use the status(node) function.
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
Error Handling
A @fluidframework/telemetry-utils#UsageError if the node has been deleted.
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 |
Remarks
The returned unsubscribe function should be called any time the need for the listener callback ends before the node is deleted (Not just removed). Doing so removes the overhead of tracking and triggering the event, and also avoids leaking any memory retained by the callback.
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
Error Handling
A @fluidframework/telemetry-utils#UsageError if the node has been deleted.
See Also
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 is hydrated and its identifier is a valid UUID that was automatically generated by the SharedTree it is part of (or something else using the same IIdCompressor), 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. Note that automatically generated identifiers that were accessed before the node was hydrated will return the generated UUID, not the process-unique integer.
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 should 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