TreeIdentifierUtils Interface
A utility interface for manipulating node identifiers.
To use, import via @fluidframework/tree/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 identifiers from nodes - Generate identifiers - Convert between short numeric identifiers and long string identifiers
Methods
| Method | Alerts | Return Type | Description |
|---|---|---|---|
| create(branch) | Alpha | string | Creates a new identifier. |
| getShort(node) | Alpha | number | undefined | Returns the shortened form of the identifier identifier for the given node. |
| lengthen(branch, nodeIdentifier) | Alpha | string | Returns the stable id as a string if the identifier is decompressible and known by the id compressor. |
| shorten(branch, nodeIdentifier) | Alpha | number | undefined | Returns the shortened identifier as a number given a UUID known by the id compressor on the branch. |
Call Signatures
| Call Signature | Alerts | Return Type | Description |
|---|---|---|---|
| (node: TreeNode): string | undefined | Alpha | string | undefined | Returns the identifier of a node. |
Method Details
create
Creates a new identifier.
For more information about our API support guarantees, see here.
Signature
create(branch: TreeBranch): string;
Remarks
The returned UUID string can be shortened for high-performance scenarios.
Parameters
| Parameter | Type | Description |
|---|---|---|
| branch | TreeBranch | The branch (and/or view) of the SharedTree that will generate and manage the identifier. |
Returns
Return type: string
getShort
Returns the shortened form of the identifier identifier for the given node.
For more information about our API support guarantees, see here.
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 not yield a short identifier until after hydration.
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. In that case, retrieve the identifiers individually via their fields instead.
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.
For more information about our API support guarantees, see here.
Signature
lengthen(branch: TreeBranch, nodeIdentifier: number): string;
Remarks
If the given number does not correspond to a valid identifier generated by the SharedTree, this will return undefined.
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.
Parameters
| Parameter | Type | Description |
|---|---|---|
| branch | TreeBranch | The branch (and/or view) of the SharedTree that will perform the decompression. |
| nodeIdentifier | number | The local identifier to be lengthened. |
Returns
Return type: string
shorten
Returns the shortened identifier as a number given a UUID known by the id compressor on the branch.
For more information about our API support guarantees, see here.
Signature
shorten(branch: TreeBranch, nodeIdentifier: string): number | undefined;
Remarks
If the given string is not a valid identifier and/or was not generated by the SharedTree, this will return undefined.
See getShort(node) for additional details about shortened identifiers.
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.
Parameters
| Parameter | Type | Description |
|---|---|---|
| branch | TreeBranch | The branch (and/or view) of the SharedTree that will perform the compression. |
| nodeIdentifier | string | the stable identifier to be shortened. |
Returns
Return type: number | undefined
Call Signature Details
(node: TreeNode): string | undefined
Returns the identifier of a node.
For more information about our API support guarantees, see here.
Signature
(node: TreeNode): string | undefined;
Remarks
This returns the node's UUID if and only if it has exactly one identifier field. If it has no identifier field, this returns undefined. If it has more than one identifier field, this throws an error. In that case, query the identifier fields directly instead.