TreeIdentifierUtils Interface
A utility interface for retrieving or converting node identifiers.
To use, import via fluid-framework/alpha.
For more information about our API support guarantees, see here.
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 TreeIdentifierUtils
Remarks
This provides methods to:
-
Retrieve long or short identifiers from nodes
-
Convert between long identifiers and short identifiers
-
Generates long identifiers
Methods
| Method | Alerts | Return Type | Description |
|---|---|---|---|
| create(branch) | Alpha |
string | Creates and returns a long identifier. The long identifier is a compressible, stable identifier generated by the tree's ID compressor. |
| getShort(node) | Alpha |
number | undefined | Returns the identifier of the given node in the most compressed form possible. |
| lengthen(branch, nodeIdentifier) | Alpha |
string |
Returns the stable id as a string if the identifier is decompressible and known by the id compressor. Otherwise, it will throw an error. This method is the inverse of shorten(branch, nodeIdentifier). If you lengthen an identifier and then immediately pass it to shorten(branch, nodeIdentifier), you will get the original short identifier back. |
| shorten(branch, nodeIdentifier) | Alpha |
number | undefined |
Returns the shortened identifier as a number given long identifier known by the id compressor on the branch if possible. Otherwise, it will return the original string identifier provided. If the id does not exist, or is unknown by the id compressor, it returns undefined. This method is the inverse of lengthen(branch, nodeIdentifier). If you shorten an identifier and then immediately pass it to lengthen(branch, nodeIdentifier), you will get the original string back. |
Call Signatures
| CallSignature | Alerts | Description |
|---|---|---|
| (node: TreeNode): string | undefined | Alpha |
Returns the contents of a node's identifier field as a stable identifier. If the identifier field does not exist, returns undefined. |
Method Details
create
Creates and returns a long identifier. The long identifier is a compressible, stable identifier generated by the tree's ID compressor.
For more information about our API support guarantees, see here.
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
create(branch: TreeBranch): string;
Parameters
| Parameter | Type | Description |
|---|---|---|
| branch | TreeBranch | TreeBranch from where you want to get the id compressor to generate the identifier from. |
Returns
Return type: string
getShort
Returns the identifier of the given node in the most compressed form possible.
For more information about our API support guarantees, see here.
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
getShort(node: TreeNode): number | 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 undefined.
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 | undefined
lengthen
Returns the stable id as a string if the identifier is decompressible and known by the id compressor. Otherwise, it will throw an error.
This method is the inverse of shorten(branch, nodeIdentifier). If you lengthen an identifier and then immediately pass it to shorten(branch, nodeIdentifier), you will get the original short identifier back.
For more information about our API support guarantees, see here.
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
lengthen(branch: TreeBranch, nodeIdentifier: number): string;
Parameters
| Parameter | Type | Description |
|---|---|---|
| branch | TreeBranch | TreeBranch from where you want to get the id compressor to do the decompression. |
| nodeIdentifier | number | The local identifier that needs to be expanded. |
Returns
Return type: string
shorten
Returns the shortened identifier as a number given long identifier known by the id compressor on the branch if possible. Otherwise, it will return the original string identifier provided. If the id does not exist, or is unknown by the id compressor, it returns undefined.
This method is the inverse of lengthen(branch, nodeIdentifier). If you shorten an identifier and then immediately pass it to lengthen(branch, nodeIdentifier), you will get the original string back.
For more information about our API support guarantees, see here.
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
shorten(branch: TreeBranch, nodeIdentifier: string): number | undefined;
Parameters
| Parameter | Type | Description |
|---|---|---|
| branch | TreeBranch | TreeBranch from where you get the idCompressor to do the decompression. |
| nodeIdentifier | string | the stable identifier that needs to be shortened. |
Returns
Return type: number | undefined
Call Signature Details
(node: TreeNode): string | undefined
Returns the contents of a node's identifier field as a stable identifier. If the identifier field does not exist, returns undefined.
For more information about our API support guarantees, see here.
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
(node: TreeNode): string | undefined;