@fluidframework/tree Package

Interfaces

Interface	Alerts	Modifiers	Description
CommitMetadata		`sealed`	Information about a commit that has been applied.
FieldProps			Additional information to provide to a FieldSchema.
FieldSchemaMetadata		`sealed`	Metadata associated with a FieldSchema.
FieldSchemaUnsafe			Unenforced version of FieldSchema.
InternalTreeNode		`sealed`	A node type internal to `@fluidframework/tree`.
ITree		`sealed`	Channel for a Fluid Tree DDS.
ITreeConfigurationOptions			Options when constructing a tree view.
ITreeViewConfiguration			Property-bag configuration for TreeViewConfiguration construction.
JsonArrayNodeSchema	`Alpha`	`sealed`	JSON Schema for an array node.
JsonLeafNodeSchema	`Alpha`	`sealed`	JSON Schema for a leaf node.
JsonMapNodeSchema	`Alpha`	`sealed`	JSON Schema for a map node.
JsonNodeSchemaBase	`Alpha`	`sealed`	Base interface for node schemas represented in JSON Schema format.
JsonObjectNodeSchema	`Alpha`	`sealed`	JSON Schema for an object node.
JsonSchemaRef	`Alpha`	`sealed`	Type entry containing a reference to a definition in the schema.
Listenable		`sealed`	An object which allows the registration of listeners so that subscribers can be notified when an event happens.
MakeNominal		`sealed`	Use this as the type of a protected field to cause a type to use nominal typing instead of structural.
NodeChangedData	`Beta`	`sealed`	Data included for nodeChanged.
NodeInDocumentConstraint			A transaction constraint which requires that the given node exists in the tree.
Revertible		`sealed`	Allows reversion of a change made to SharedTree.
RunTransaction		`sealed`	A function which runs a transaction in a SharedTree.
SchemaCompatibilityStatus		`sealed`	Information about a view schema's compatibility with the document's stored schema. See SharedTree's README for more information about choosing a compatibility policy.
TreeArrayNode		`sealed`	A TreeNode which implements 'readonly T[]' and the array mutation APIs.
TreeArrayNodeUnsafe	`System`	`sealed`	Unenforced version of TreeArrayNode.
TreeBranch	`Alpha`	`sealed`	A "version control"-style branch of a SharedTree.
TreeBranchFork	`Alpha`	`sealed`	A branch of a SharedTree that has merged from another branch.
TreeChangeEvents		`sealed`	A collection of events that can be emitted by a TreeNode.
TreeChangeEventsBeta	`Beta`	`sealed`	Extensions to TreeChangeEvents which are not yet stable.
TreeMapNode		`sealed`	A map of string keys to tree objects.
TreeMapNodeUnsafe	`System`	`sealed`	Unenforced version of TreeMapNode.
TreeNodeApi		`sealed`	Provides various functions for analyzing TreeNodes. *
TreeNodeSchemaClass		`sealed`	Tree node schema which is implemented using a class.
TreeNodeSchemaCore		`sealed`	Data common to all tree node schema.
TreeNodeSchemaNonClass	`System`	`sealed`	Schema which is not a class.
TreeView		`sealed`	An editable view of a (version control style) branch of a shared tree based on some schema. This schema--known as the view schema--may or may not align the stored schema of the document. Information about discrepancies between the two schemas is available via compatibility. Application authors are encouraged to read [schema-evolution.md](../../docs/user-facing/schema-evolution.md) and choose a schema compatibility policy that aligns with their application's needs.
TreeViewEvents		`sealed`	Events for TreeView.
ViewableTree	`System`	`sealed`	A tree from which a TreeView can be created.
WithType		`sealed`	Adds a type symbol to a type for stronger typing.

Classes

Class	Modifiers	Description
FieldSchema	`sealed`	All policy for a specific field, including functionality that does not have to be kept consistent across versions or deterministic. This can include policy for how to use this schema for "view" purposes, and well as how to expose editing APIs. Use SchemaFactory to create the FieldSchema instances, for example optional(t, props).
IterableTreeArrayContent	`sealed`	Used to insert iterable content into a TreeArrayNode. Use (TreeArrayNode:variable).spread to create an instance of this type.
SchemaFactory	`sealed`	Creates various types of schema for TreeNodes.
TreeNode	`sealed`	A non-leaf SharedTree node. Includes objects, arrays, and maps.
TreeViewConfiguration	`sealed`	Configuration for viewWith(config).

Enumerations

Enum	Description
CommitKind	The type of a commit. This is used to describe the context in which the commit was created.
FieldKind	Kind of a field on a node.
NodeKind	Kind of tree node.
RevertibleStatus	The status of a Revertible.
TreeStatus	Status of the tree that a particular node belongs to.

Types

TypeAlias	Alerts	Modifiers	Description
AllowedTypes			Types for use in fields.
FixRecursiveArraySchema	`Alpha`		Workaround for fixing errors resulting from an issue with recursive ArrayNode schema exports.
ImplicitAllowedTypes			Types allowed in a field.
ImplicitFieldSchema			Schema for a field of a tree node.
InsertableObjectFromSchemaRecordUnsafe	`System`		Unenforced version of `InsertableObjectFromSchemaRecord`.
InsertableTreeFieldFromImplicitField			Type of content that can be inserted into the tree for a field of the given schema.
InsertableTreeFieldFromImplicitFieldUnsafe	`System`		Unenforced version of InsertableTreeFieldFromImplicitField.
InsertableTreeNodeFromImplicitAllowedTypes			Type of content that can be inserted into the tree for a node of the given schema.
InsertableTreeNodeFromImplicitAllowedTypesUnsafe	`System`		Unenforced version of InsertableTreeNodeFromImplicitAllowedTypes.
InsertableTypedNode			Data which can be used as a node to be inserted. Either an unhydrated node, or content to build a new node.
IsListener			`true` iff the given type is an acceptable shape for a event listener
JsonFieldSchema	`Alpha`	`sealed`	JSON Schema representation of a FieldSchema.
JsonLeafSchemaType	`Alpha`		JSON primitive types.
JsonNodeSchema	`Alpha`		JSON Schema representation of a TreeNodeSchema.
JsonRefPath	`Alpha`		Reference string pointing to a definition in the schema. Should be the fully-qualified identifier.
JsonSchemaId	`Alpha`		The fully-qualified identifier.
JsonSchemaType	`Alpha`		JSON entity type.
JsonTreeSchema	`Alpha`	`sealed`	JSON Schema representation of a tree schema.
LazyItem			An "eager" or "lazy" Item in a `FlexList`. Lazy items are wrapped in a function to allow referring to themselves before they are declared. This makes recursive and co-recursive items possible.
Listeners			Used to specify the kinds of events emitted by a Listenable.
MapNodeInsertableData	`System`		Content which can be used to construct a Map node, explicitly or implicitly.
NodeFromSchema			Takes in `TreeNodeSchema[]` and returns a TypedNode union.
Off			A function that, when called, will deregister an event listener subscription that was previously registered.
RestrictiveReadonlyRecord	`Deprecated`		Alternative to the built in Record type which does not permit unexpected members, and is readonly.
RestrictiveStringRecord	`System`		Alternative to the built-in `Record<string, T>` type which is readonly and does not permit symbols.
RevertibleFactory		`sealed`	Factory for creating a Revertible. Will error if invoked outside the scope of the `commitApplied` event that provides it, or if invoked multiple times.
TransactionConstraint			A requirement for a SharedTree transaction to succeed.
TreeFieldFromImplicitField			Converts ImplicitFieldSchema to the corresponding tree node's field type.
TreeLeafValue			Value that may be stored as a leaf node.
TreeNodeFromImplicitAllowedTypes			Type of tree node for a field of the given schema.
TreeNodeSchema		`sealed`	Schema for a tree node.
TreeObjectNode			A TreeNode which modules a JavaScript object.
TreeObjectNodeUnsafe	`System`		Unenforced version of TreeObjectNode.
Unenforced			A placeholder to use in extends constraints when using the real type breaks compilation of some recursive types due to a design limitation of TypeScript. These extends constraints only serve as documentation: to avoid breaking compilation, this type has to not actually enforce anything, and thus is just `unknown`. Therefore the type safety is the responsibility of the user of the API.
Unhydrated			Type alias to document which values are un-hydrated. Un-hydrated values are nodes produced from schema's create functions that haven't been inserted into a tree yet. Since un-hydrated nodes become hydrated when inserted, strong typing can't be used to distinguish them. This no-op wrapper is used instead.
ValidateRecursiveSchema			Compile time check for validity of a recursive schema.

Functions

Function	Alerts	Return Type	Description
getBranch(tree)	`Alpha`	TreeBranch	Get a TreeBranch from a ITree.
getBranch(view)	`Alpha`	TreeBranch	Get a TreeBranch from a TreeView.
getJsonSchema(schema)	`Alpha`	JsonTreeSchema	Creates a JSON Schema representation of the provided TreeNodeSchema.

Variables

Variable	Alerts	Modifiers	Type	Description
rollback		`readonly`	unique symbol	A special object that signifies when a SharedTree transaction should "roll back".
SharedTree	`Legacy`, `Alpha`	`readonly`	ISharedObjectKind<ITree> & SharedObjectKind<ITree>	SharedTree is a hierarchical data structure for collaboratively editing strongly typed JSON-like trees of objects, arrays, and other data types.
Tree		`readonly`	TreeApi	The `Tree` object holds various functions for interacting with TreeNodes.
TreeArrayNode		`readonly`	{ readonly spread: <T>(content: Iterable<T>) => IterableTreeArrayContent<T>; }	A TreeNode which implements 'readonly T[]' and the array mutation APIs.
TreeBeta	`Beta`	`readonly`, `sealed`	{ readonly on: <K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(node: TNode, eventName: K, listener: NoInfer<TreeChangeEventsBeta<TNode>[K]>) => () => void; }	Extensions to Tree which are not yet stable.
typeSchemaSymbol	`System`	`readonly`	unique symbol	The type of a TreeNode. For more information about the type, use `Tree.schema(theNode)` instead.

Namespaces

Namespace	Description
InternalTypes

Function Details

getBranch

Get a TreeBranch from a ITree .

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

To use, import via @fluidframework/tree/alpha.

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

Signature

export declare function getBranch(tree: ITree): TreeBranch;

Remarks

The branch can be used for “version control”-style coordination of edits on the tree.

Parameters

Parameter	Type	Description
tree	ITree

Returns

Return type: TreeBranch

getBranch

Get a TreeBranch from a TreeView .

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

To use, import via @fluidframework/tree/alpha.

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

Signature

export declare function getBranch(view: TreeView<ImplicitFieldSchema>): TreeBranch;

Remarks

The branch can be used for “version control”-style coordination of edits on the tree. Branches are currently an unstable “alpha” API and are subject to change in the future.

Parameters

Parameter	Type	Description
view	TreeView<ImplicitFieldSchema>

Returns

Return type: TreeBranch

getJsonSchema

Creates a JSON Schema representation of the provided TreeNodeSchema .

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

To use, import via @fluidframework/tree/alpha.

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

Signature

export declare function getJsonSchema(schema: ImplicitFieldSchema): JsonTreeSchema;

Remarks

Useful when communicating the schema to external libraries or services. Caches the result for future calls.

Example

A Shared Tree schema like the following:

class MyObject extends schemaFactory.object("MyObject", {
	foo: schemaFactory.number,
	bar: schemaFactory.optional(schemaFactory.string),
});

Will yield JSON Schema like the following:

{
	"$defs": {
		"com.fluidframework.leaf.string": {
			"type": "string",
		},
		"com.fluidframework.leaf.number": {
			"type": "number",
		},
		"com.myapp.MyObject": {
			"type": "object",
			"properties": {
				"foo": { "$ref": "com.fluidframework.leaf.number" },
				"bar": { "$ref": "com.fluidframework.leaf.string" },
			},
			"required": ["foo"],
		},
	},
	"$ref": "#/$defs/com.myapp.MyObject",
}

Parameters

Parameter	Type	Description
schema	ImplicitFieldSchema

Returns

Return type: JsonTreeSchema

Variable Details

rollback

A special object that signifies when a SharedTree transaction should “roll back”.

Signature

rollback: unique symbol

Type: unique symbol

SharedTree

SharedTree is a hierarchical data structure for collaboratively editing strongly typed JSON-like trees of objects, arrays, and other data types.

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/tree/legacy.

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

Signature

SharedTree: ISharedObjectKind<ITree> & SharedObjectKind<ITree>

Type: ISharedObjectKind <ITree > & SharedObjectKind <ITree >

Tree

The Tree object holds various functions for interacting with TreeNode s.

Signature

treeApi: TreeApi

Type: TreeApi

TreeArrayNode

A TreeNode which implements ‘readonly T[]’ and the array mutation APIs.

Signature

TreeArrayNode: {
    readonly spread: <T>(content: Iterable<T>) => IterableTreeArrayContent<T>;
}

Type: { readonly spread: <T>(content: Iterable<T>) => IterableTreeArrayContent <T>; }

TreeBeta

Extensions to Tree which are not yet stable.

This API is provided as a beta preview and may change without notice.

To use, import via @fluidframework/tree/beta.

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

Signature

/** @sealed */
TreeBeta: {
    readonly on: <K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(node: TNode, eventName: K, listener: NoInfer<TreeChangeEventsBeta<TNode>[K]>) => () => void;
}

Type: { readonly on: <K extends keyof TreeChangeEventsBeta <TNode>, TNode extends TreeNode >(node: TNode, eventName: K, listener: NoInfer<TreeChangeEventsBeta <TNode>[K]>) => () => void; }

typeSchemaSymbol

The type of a TreeNode . For more information about the type, use Tree.schema(theNode) instead.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

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

Signature

typeSchemaSymbol: unique symbol

Type: unique symbol

Remarks

This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking. Tree.is and Tree.schema provide a superset of this information in more friendly ways.

This symbol should not manually be added to objects as doing so allows the object to be invalidly used where specific nodes are expected. Instead construct a real node of the desired type using its constructor.

This symbol should not be used directly for type narrowing. Instead use WithType .