SharedTree Class
A [distributed tree](../Readme.md).
Signature
export declare class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeIdContext
Extends: SharedObject<ISharedTreeEvents
Implements: NodeIdContext
Constructors
| Constructor | Description |
|---|---|
| (constructor)(runtime, id, args) | Create a new SharedTree. |
| (constructor)(runtime, id, args) | Constructs a new instance of the SharedTree class |
Static Methods
| Method | Return Type | Description |
|---|---|---|
| create(runtime, id) | SharedTree | Create a new SharedTree. It will contain the default value (see initialTree). |
| getFactory(args) | SharedTreeFactory | Get a factory for SharedTree to register with the data store. |
| getFactory(args) | SharedTreeFactory |
Properties
| Property | Type | Description |
|---|---|---|
| attributionId | AttributionId | The UUID used for attribution of nodes created by this SharedTree. All shared trees with a write format of 0.1.1 or greater have a unique attribution ID which may be configured in the constructor. All other shared trees (i.e. those with a write format of 0.0.2) use the nil UUID as their attribution ID. |
| currentView | RevisionView | |
| edits | OrderedEditSet<InternalizedChange> | |
| logger | ITelemetryLogger | |
| logViewer | LogViewer | Viewer for trees defined by editLog. This allows access to views of the tree at different revisions (various points in time). |
Methods
| Method | Return Type | Description |
|---|---|---|
| applyEdit(changes) | Edit<InternalizedChange> | Applies a set of changes to this tree. The result will be reflected in SharedTree.currentView. This method does not allow for snapshot isolation, as the changes are always applied to the most recent revision. If it is desireable to read from and apply changes to a fixed view that does not change when remote changes arrive, Checkout should be used instead. |
| applyEdit(changes) | Edit<InternalizedChange> | |
| applyStashedOp(op) | StashedLocalOpMetadata | "Pending local state" refers to ops submitted to the runtime that have not yet been acked. When closing a container, hosts have the option to stash this pending local state somewhere to be reapplied later (to avoid data loss). If a host then loads a container using that stashed state, this function is called for each stashed op, and is expected to: 1. Update this DDS to reflect that state locally. 2. Return any localOpMetadata that would have been associated with this op. |
| attributeNodeId(id) | AttributionId | Returns the attribution ID associated with the SharedTree that generated the given node ID. This is generally only useful for clients with a write format of 0.1.1 or greater since older clients cannot be given an attribution ID and will always use the default attributionId of the tree. |
| convertToNodeId(id) | NodeId | Given a stable ID, return the corresponding NodeId or throws if the supplied stable ID was never generated with this tree, either as a UUID corresponding to a NodeId or as an override passed to generateNodeId. If a stable ID is returned, this does not imply that there is a node with id in the current revision of the tree, only that id was at some point generated by an instance of this SharedTree. |
| convertToStableNodeId(id) | StableNodeId | Given a NodeId, returns the corresponding stable ID or throws if the supplied node ID was not generated with this tree (NodeIds may not be used across SharedTree instances, see generateNodeId for more). The returned value will be a UUID, unless the creation of id used an override string (see generateNodeId for more). The result is safe to persist and re-use across SharedTree instances, unlike NodeId. |
| generateNodeId(override) | NodeId | Generates a node identifier. The returned IDs may be used as the identifier of a node in the SharedTree. NodeIds are *always* unique and stable within the scope of the tree and session that generated them. They are *not* unique within a Fluid container, and *cannot* be compared across instances of a SharedTree. They are *not* stable across sessions/lifetimes of a SharedTree, and *cannot* be persisted (e.g. stored in payloads, uploaded in blobs, etc.). If stable persistence is needed, NodeIdConverter.convertToStableNodeId may be used to return a corresponding UUID that is globally unique and stable. |
| getRuntime() | IFluidDataStoreRuntime | |
| getWriteFormat() | WriteFormat | The write format version currently used by this SharedTree. This is always initialized to the write format passed to the tree's constructor, but it may automatically upgrade over time (e.g. when connected to another SharedTree with a higher write format, or when loading a summary with a higher write format). |
| loadCore(storage) | Promise<void> | |
| mergeEditsFrom(other, edits, stableIdRemapper) | EditId[] | Merges edits from other into this SharedTree. |
| onDisconnect() | void | |
| processCore(message, local) | void | |
| registerCore() | void | |
| reSubmitCore(op, localOpMetadata) | void | |
| revert(editId) | EditId | undefined | Reverts a previous edit by applying a new edit containing the inverse of the original edit's changes. |
| summarizeCore(serializer) | ISummaryTreeWithStats | Gets a form of the object that can be serialized. |
| tryConvertToNodeId(id) | NodeId | undefined | Given a stable ID, return the corresponding NodeId or return undefined if the supplied stable ID was never generated with this tree, either as a UUID corresponding to a NodeId or as an override passed to generateNodeId. If a stable ID is returned, this does not imply that there is a node with id in the current revision of the tree, only that id was at some point generated by an instance of this SharedTree. |
| tryConvertToStableNodeId(id) | StableNodeId | undefined | Given a NodeId, attempt to return the corresponding stable ID. The returned value will be a UUID, unless the creation of id used an override string (see generateNodeId for more). The returned stable ID is undefined if id was never created with this SharedTree. If a stable ID is returned, this does not imply that there is a node with id in the current revision of the tree, only that id was at some point generated by some instance of this tree. |
Constructor Details
(constructor)
Create a new SharedTree.
Signature
constructor(runtime: IFluidDataStoreRuntime, id: string, ...args: SharedTreeArgs<WriteFormat.v0_0_2>);
Parameters
| Parameter | Type | Description |
|---|---|---|
| runtime | IFluidDataStoreRuntime | The runtime the SharedTree will be associated with |
| id | string | Unique ID for the SharedTree |
| args | SharedTreeArgs<WriteFormat.v0_0_2> |
(constructor)
Constructs a new instance of the SharedTree class
Signature
constructor(runtime: IFluidDataStoreRuntime, id: string, ...args: SharedTreeArgs<WriteFormat.v0_1_1>);
Parameters
| Parameter | Type | Description |
|---|---|---|
| runtime | IFluidDataStoreRuntime | |
| id | string | |
| args | SharedTreeArgs<WriteFormat.v0_1_1> |
Property Details
attributionId
The UUID used for attribution of nodes created by this SharedTree. All shared trees with a write format of 0.1.1 or greater have a unique attribution ID which may be configured in the constructor. All other shared trees (i.e. those with a write format of 0.0.2) use the nil UUID as their attribution ID.
Signature
get attributionId(): AttributionId;
Type: AttributionId
currentView
Signature
get currentView(): RevisionView;
Type: RevisionView
edits
Signature
get edits(): OrderedEditSet<InternalizedChange>;
Type: OrderedEditSet<InternalizedChange>
logger
Signature
protected readonly logger: ITelemetryLogger;
Type: ITelemetryLogger
logViewer
Viewer for trees defined by editLog. This allows access to views of the tree at different revisions (various points in time).
Signature
get logViewer(): LogViewer;
Type: LogViewer
Method Details
applyEdit
Applies a set of changes to this tree. The result will be reflected in SharedTree.currentView. This method does not allow for snapshot isolation, as the changes are always applied to the most recent revision. If it is desireable to read from and apply changes to a fixed view that does not change when remote changes arrive, Checkout should be used instead.
Signature
applyEdit(...changes: Change[]): Edit<InternalizedChange>;
Parameters
| Parameter | Type | Description |
|---|---|---|
| changes | Change[] |
Returns
Return type: Edit<InternalizedChange>
applyEdit
Signature
applyEdit(changes: Change[]): Edit<InternalizedChange>;
Parameters
| Parameter | Type | Description |
|---|---|---|
| changes | Change[] |
Returns
Return type: Edit<InternalizedChange>
applyStashedOp
"Pending local state" refers to ops submitted to the runtime that have not yet been acked. When closing a container, hosts have the option to stash this pending local state somewhere to be reapplied later (to avoid data loss). If a host then loads a container using that stashed state, this function is called for each stashed op, and is expected to: 1. Update this DDS to reflect that state locally. 2. Return any localOpMetadata that would have been associated with this op.
Signature
protected applyStashedOp(op: unknown): StashedLocalOpMetadata;
Parameters
| Parameter | Type | Description |
|---|---|---|
| op | unknown |
Returns
Return type: StashedLocalOpMetadata
attributeNodeId
Returns the attribution ID associated with the SharedTree that generated the given node ID. This is generally only useful for clients with a write format of 0.1.1 or greater since older clients cannot be given an attribution ID and will always use the default attributionId of the tree.
Signature
attributeNodeId(id: NodeId): AttributionId;
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | NodeId |
Returns
Return type: AttributionId
convertToNodeId
Given a stable ID, return the corresponding NodeId or throws if the supplied stable ID was never generated with this tree, either as a UUID corresponding to a NodeId or as an override passed to generateNodeId. If a stable ID is returned, this does not imply that there is a node with id in the current revision of the tree, only that id was at some point generated by an instance of this SharedTree.
Signature
convertToNodeId(id: StableNodeId): NodeId;
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | StableNodeId |
Returns
Return type: NodeId
convertToStableNodeId
Given a NodeId, returns the corresponding stable ID or throws if the supplied node ID was not generated with this tree (NodeIds may not be used across SharedTree instances, see generateNodeId for more). The returned value will be a UUID, unless the creation of id used an override string (see generateNodeId for more). The result is safe to persist and re-use across SharedTree instances, unlike NodeId.
Signature
convertToStableNodeId(id: NodeId): StableNodeId;
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | NodeId |
Returns
Return type: StableNodeId
create
Create a new SharedTree. It will contain the default value (see initialTree).
Signature
static create(runtime: IFluidDataStoreRuntime, id?: string): SharedTree;
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| runtime | IFluidDataStoreRuntime | ||
| id | optional | string |
Returns
Return type: SharedTree
generateNodeId
Generates a node identifier. The returned IDs may be used as the identifier of a node in the SharedTree. NodeIds are *always* unique and stable within the scope of the tree and session that generated them. They are *not* unique within a Fluid container, and *cannot* be compared across instances of a SharedTree. They are *not* stable across sessions/lifetimes of a SharedTree, and *cannot* be persisted (e.g. stored in payloads, uploaded in blobs, etc.). If stable persistence is needed, NodeIdConverter.convertToStableNodeId may be used to return a corresponding UUID that is globally unique and stable.
Signature
generateNodeId(override?: string): NodeId;
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| override | optional | string | if supplied, calls to convertToStableNodeId using the returned node ID will return the override instead of the UUID. Calls to generateNodeId with the same override always return the same ID. Performance note: passing an override string incurs a storage cost that is significantly higher that a node ID without one, and should be avoided if possible. |
Returns
Return type: NodeId
getFactory
Get a factory for SharedTree to register with the data store.
Signature
static getFactory(...args: SharedTreeArgs<WriteFormat.v0_0_2>): SharedTreeFactory;
Parameters
| Parameter | Type | Description |
|---|---|---|
| args | SharedTreeArgs<WriteFormat.v0_0_2> |
Returns
A factory that creates SharedTrees and loads them from storage.
Return type: SharedTreeFactory
getFactory
Signature
static getFactory(...args: SharedTreeArgs<WriteFormat.v0_1_1>): SharedTreeFactory;
Parameters
| Parameter | Type | Description |
|---|---|---|
| args | SharedTreeArgs<WriteFormat.v0_1_1> |
Returns
Return type: SharedTreeFactory
getRuntime
Signature
getRuntime(): IFluidDataStoreRuntime;
Returns
Return type: IFluidDataStoreRuntime
getWriteFormat
The write format version currently used by this SharedTree. This is always initialized to the write format passed to the tree's constructor, but it may automatically upgrade over time (e.g. when connected to another SharedTree with a higher write format, or when loading a summary with a higher write format).
Signature
getWriteFormat(): WriteFormat;
Returns
Return type: WriteFormat
loadCore
Signature
protected loadCore(storage: IChannelStorageService): Promise<void>;
Parameters
| Parameter | Type | Description |
|---|---|---|
| storage | IChannelStorageService |
Returns
Return type: Promise<void>
mergeEditsFrom
Merges edits from other into this SharedTree.
Signature
mergeEditsFrom(other: SharedTree, edits: Iterable<Edit<InternalizedChange>>, stableIdRemapper?: (id: StableNodeId) => StableNodeId): EditId[];
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| other | SharedTree | Tree containing the edits that should be applied to this one. | |
| edits | Iterable<Edit<InternalizedChange>> | Iterable of edits from other to apply. |
|
| stableIdRemapper | optional | (id: StableNodeId) => StableNodeId |
Optional remapper to translate stable identities from Payloads on the edits are left intact. |
Returns
a list containing EditIds for all applied edits.
Return type: EditId[]
onDisconnect
Signature
protected onDisconnect(): void;
processCore
Signature
protected processCore(message: unknown, local: boolean): void;
Parameters
| Parameter | Type | Description |
|---|---|---|
| message | unknown | |
| local | boolean |
registerCore
Signature
protected registerCore(): void;
reSubmitCore
Signature
protected reSubmitCore(op: unknown, localOpMetadata?: StashedLocalOpMetadata): void;
Parameters
| Parameter | Modifiers | Type | Description |
|---|---|---|---|
| op | unknown | ||
| localOpMetadata | optional | StashedLocalOpMetadata |
revert
Reverts a previous edit by applying a new edit containing the inverse of the original edit's changes.
Signature
revert(editId: EditId): EditId | undefined;
Parameters
| Parameter | Type | Description |
|---|---|---|
| editId | EditId | the edit to revert |
Returns
the id of the new edit, or undefined if the original edit could not be inverted given the current tree state.
Return type: EditId | undefined
summarizeCore
Gets a form of the object that can be serialized.
Signature
summarizeCore(serializer: IFluidSerializer): ISummaryTreeWithStats;
Parameters
| Parameter | Type | Description |
|---|---|---|
| serializer | IFluidSerializer |
Returns
A tree representing the snapshot of the shared object.
Return type: ISummaryTreeWithStats
tryConvertToNodeId
Given a stable ID, return the corresponding NodeId or return undefined if the supplied stable ID was never generated with this tree, either as a UUID corresponding to a NodeId or as an override passed to generateNodeId. If a stable ID is returned, this does not imply that there is a node with id in the current revision of the tree, only that id was at some point generated by an instance of this SharedTree.
Signature
tryConvertToNodeId(id: StableNodeId): NodeId | undefined;
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | StableNodeId |
Returns
Return type: NodeId | undefined
tryConvertToStableNodeId
Given a NodeId, attempt to return the corresponding stable ID. The returned value will be a UUID, unless the creation of id used an override string (see generateNodeId for more). The returned stable ID is undefined if id was never created with this SharedTree. If a stable ID is returned, this does not imply that there is a node with id in the current revision of the tree, only that id was at some point generated by some instance of this tree.
Signature
tryConvertToStableNodeId(id: NodeId): StableNodeId | undefined;
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | NodeId |
Returns
Return type: StableNodeId | undefined