TreeMapNodeAlpha Interface

TreeMapNode with FluidReadonlyMap-based iteration.

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

For more information about our API support guarantees, see here.

Sealed

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 TreeMapNodeAlpha<T extends ImplicitAllowedTypes = ImplicitAllowedTypes> extends FluidReadonlyMap<string, TreeNodeFromImplicitAllowedTypes<T>>, TreeNode, Pick<TreeMapNode<T>, "set" | "delete">

Extends: FluidReadonlyMap<string, TreeNodeFromImplicitAllowedTypes<T>>, TreeNode, Pick<TreeMapNode<T>, "set" | "delete">

Type Parameters

Parameter	Constraint	Default	Description
T	ImplicitAllowedTypes	ImplicitAllowedTypes

Remarks

This is the same as TreeMapNode except that it extends FluidReadonlyMap instead of the built-in ReadonlyMap, insulating against breaking changes in TypeScript's standard library iterator types.

Methods

Method	Alerts	Return Type	Description
clear()	Alpha	void	Removes all elements from the map.
getOrInsert(key, fallbackValue)	Alpha	TreeNodeFromImplicitAllowedTypes<T>	Returns the value at key, first inserting fallbackValue if this map has no entry for key.
getOrInsertComputed(key, callback)	Alpha	TreeNodeFromImplicitAllowedTypes<T>	Returns the value at key, first inserting the value produced by callback if this map has no entry for key.

Method Details

clear

Removes all elements from the map.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

clear(): void;

Remarks

The merge semantics of this operation are loosely specified. Either of the following may occur:

• clear may remove all elements that were in the map when the edit was authored, even if some of those elements have since been moved elsewhere in the tree (in which case they are removed from their new location).

• clear may remove all elements that are in the map when the edit is sequenced, even if some of those elements were not yet in the map when the edit was authored.

getOrInsert

Returns the value at key, first inserting fallbackValue if this map has no entry for key.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

getOrInsert(key: string, fallbackValue: InsertableTreeNodeFromImplicitAllowedTypes<T>): TreeNodeFromImplicitAllowedTypes<T>;

Remarks

The check for the presence of an existing entry with the given key is performed at the time the edit is authored. This has implications for the merge semantics of this operation:

• If no entry is present for key at authoring time (thus leading to an insert) while a peer concurrently inserts a value for the same key, then the two inserts will race and the one that is sequenced second will overwrite the value inserted by the one that is sequenced first.

• If an entry is present for key at authoring time (thus leading to no insert) while a peer concurrently deletes the entry for key, then the map will end up with no entry for key no matter how the two edits are sequenced.

• If an entry is present for key at authoring time (thus leading to no insert) while a peer concurrently inserts a new entry for key, then the map will end up with the entry set by the peer no matter how the two edits are sequenced.

These last two points mean that, upon sequencing of an edit made with this API, there is no guarantee that the entry for the given key will be the current one (if any) or the fallback one. If such a guarantee is important, then consider using preconditions to ensure the edit only applies when appropriate.

This API is **not** equivalent to the following alternative:

map.set(key, map.get(key) ?? fallbackValue);

They differ in the following ways:

• This API treats entries containing null values as populated. By contrast, the above alternative's usage of ?? means that a null entry is treated as equivalent to a missing entry.

• This API only inserts/sets the entry for the given key when there is no current one. By contrast, the above alternative always performs an insert. That insert will throw an error for non-leaf types (objects, maps, arrays, and records) in cases where the entry is already populated, because inserting a node that was already inserted is not supported. It will always succeed for leaf types (number, string, boolean, null, and handle) since a new node is created from the value. Note that even in the cases where it does not throw, the set operation has the potential to overwrite entries that are concurrently inserted even when the map had an entry for key, which is not the case with this API.

Avoid using this API to write a default value into the document when the application could instead return that default when reading a missing entry, which is much less costly. A more appropriate use of this API is when the value to be optionally inserted varies with the key.

Parameters

Parameter	Type	Description
key	string	The key of the element to return or insert at.
fallbackValue	InsertableTreeNodeFromImplicitAllowedTypes<T>	The value to insert if key has no entry.

Returns

The value at key, which may be the provided fallbackValue if the map had no previous entry for key.

Return type: TreeNodeFromImplicitAllowedTypes<T>

getOrInsertComputed

Returns the value at key, first inserting the value produced by callback if this map has no entry for key.

This API is provided as an alpha preview and may change without notice.

For more information about our API support guarantees, see here.

Signature

getOrInsertComputed(key: string, callback: (key: string) => InsertableTreeNodeFromImplicitAllowedTypes<T>): TreeNodeFromImplicitAllowedTypes<T>;

Remarks

This API is equivalent to getOrInsert(key, fallbackValue) except that the fallback value is computed lazily: callback is only invoked when the map has no entry for key. Prefer this API over getOrInsert(key, fallbackValue) when producing the fallback value is expensive.

The check for the presence of an existing entry with the given key is performed at the time the edit is authored. See getOrInsert(key, fallbackValue) for the implications this has on the merge semantics of this operation.

If callback throws, no edit is made and the error is propagated to the caller. If callback sets an entry for key in this map, that entry is overwritten with the value callback returned.

Parameters

Parameter	Type	Description
key	string	The key of the element to return or insert at.
callback	(key: string) => InsertableTreeNodeFromImplicitAllowedTypes<T>	Invoked with key to produce the value to insert if key has no entry. Not invoked if an entry is present.

Returns

The value at key, which may be the value produced by callback if the map had no previous entry for key.

Return type: TreeNodeFromImplicitAllowedTypes<T>