@fluidframework/tree Package

Interfaces

Interface	Alerts	Modifiers	Description
AllowedTypeMetadata	Beta		Annotations that apply to an individual allowed type.
AllowedTypesMetadata	Beta		Annotations that apply to a set of allowed types.
AnnotatedAllowedType	Beta	sealed	Stores annotations for an individual allowed type.
AnnotatedAllowedTypes	Beta	sealed	Stores annotations for a set of allowed types.
AnnotatedAllowedTypesUnsafe	System	sealed	Unenforced version of AnnotatedAllowedTypes.
AnnotatedAllowedTypeUnsafe	System	sealed	Unenforced version of AnnotatedAllowedType.
ArrayNodeCustomizableSchema	System	sealed	A schema for customizable TreeArrayNodes.
ArrayNodeCustomizableSchemaUnsafe	System	sealed	Unenforced version of ArrayNodeCustomizableSchemas.
ArrayNodePojoEmulationSchema	System	sealed	A schema for POJO emulation mode TreeArrayNodes.
BranchableTree	Alpha	sealed	A "version control"-style branch of a SharedTree.
CodecWriteOptions	Alpha		Options relating to encoding of persisted data.
CommitMetadata		sealed	Information about a commit that has been applied.
DirtyTreeMap	Alpha		A map-like interface for tracking the status of nodes that have been tracked for changes.
FieldProps			Additional information to provide to a FieldSchema.
FieldPropsAlpha	Alpha		FieldProps extended with additional alpha options.
FieldSchemaAlphaUnsafe	System	sealed	Unenforced version of FieldSchemaAlpha.
FieldSchemaMetadata		sealed	Metadata associated with a FieldSchema.
ForestOptions	Beta		Configuration options for SharedTree's internal tree storage.
ForestType	Beta	sealed	Used to distinguish between different forest types.
FormatValidator	Alpha	sealed	A kind of validator for SharedTree's internal data formats.
ICodecOptions	Alpha		Options relating to handling of persisted data.
InternalTreeNode		sealed	A node type internal to @fluidframework/tree.
ITree		sealed	Channel for a Fluid Tree DDS.
ITreeAlpha	Alpha	sealed	ITree extended with some alpha APIs.
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.
JsonRecordNodeSchema	Alpha	sealed	JSON Schema for a record node.
JsonSchemaRef	Alpha	sealed	Type entry containing a reference to a definition in the schema.
JsonStringKeyPatternProperties	Alpha	sealed	Types allowed in map / record nodes.
LeafSchema	System	sealed	A TreeNodeSchema for a TreeLeafValue.
MakeNominal		sealed	Use this as the type of a protected field to cause a type to use nominal typing instead of structural.
MapNodeCustomizableSchema	System	sealed	A schema for customizable TreeMapNodes.
MapNodeCustomizableSchemaUnsafe	System	sealed	Unenforced version of MapNodeCustomizableSchemas.
MapNodePojoEmulationSchema	System	sealed	A schema for POJO emulation mode TreeMapNodes.
NodeChangedData	Beta	sealed	Data included for nodeChanged.
NodeInDocumentConstraint			A transaction constraint which requires that the given node exists in the tree.
NodeSchemaMetadata		sealed	Metadata associated with a Node Schema.
NodeSchemaOptions			Additional information to provide to Node Schema creation.
NodeSchemaOptionsAlpha	Alpha		Additional information to provide to Node Schema creation. Includes fields for alpha features.
ObjectNodeSchema	Alpha	sealed	A schema for TreeObjectNodes.
ObjectSchemaOptions	Beta		Options when declaring an object node's schema.
ObjectSchemaOptionsAlpha	Alpha		Options when declaring an object node's schema
ObservationResults	Alpha	sealed	Results from an operation with tracked observations.
ReadonlyArrayNode	System	sealed	A covariant base type for TreeArrayNode. This provides the readonly subset of TreeArrayNode functionality, and is used as the source interface for moves since that needs to be covariant.
RecordNodeCustomizableSchema	System	sealed	A schema for customizable TreeMapNodes.
RecordNodePojoEmulationSchema	System	sealed	A schema for POJO emulation mode TreeMapNodes.
Revertible		sealed	Allows reversion of a change made to SharedTree.
RevertibleAlpha	Alpha	sealed	A Revertible with features that are not yet stable.
RunTransaction		sealed	A function which runs a transaction in a SharedTree.
RunTransactionParams	Alpha		The parameters for the RunTransaction API.
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.
SchemaStatics	System	sealed	Stateless APIs exposed via SchemaFactory as both instance properties and as statics.
SchemaStaticsBeta	System	sealed	Stateless APIs exposed via SchemaFactoryBeta as both instance properties and as statics.
SharedTreeFormatOptions	Alpha		Options for configuring the persisted format SharedTree uses.
SharedTreeOptions	Alpha		Configuration options for SharedTree with alpha features.
SimpleAllowedTypeAttributes	Alpha	sealed	Information about allowed types under a field.
SimpleArrayNodeSchema	Alpha	sealed	A SimpleNodeSchema for an array node.
SimpleFieldSchema	Alpha	sealed	A simple, shallow representation of a schema for a field.
SimpleLeafNodeSchema	Alpha	sealed	A SimpleNodeSchema for a leaf node.
SimpleMapNodeSchema	Alpha	sealed	A SimpleNodeSchema for a map node.
SimpleNodeSchemaBase	System	sealed	Base interface for TreeNodeSchema and SimpleNodeSchema types. Once simple schema is stable this doesn't have a reason to be kept @system, but it could be.
SimpleNodeSchemaBaseAlpha	System	sealed	A SimpleNodeSchema containing fields for alpha features.
SimpleObjectFieldSchema	Alpha	sealed	A SimpleFieldSchema for an SimpleObjectNodeSchema field.
SimpleObjectNodeSchema	Alpha	sealed	A SimpleNodeSchema for an object node.
SimpleRecordNodeSchema	Alpha	sealed	A SimpleNodeSchema for a map node.
SimpleTreeSchema	Alpha	sealed	A simplified representation of a schema for a tree.
TransactionResultFailed	Alpha		The result of the RunTransaction API when it failed.
TransactionResultSuccess	Alpha		The result of the RunTransaction API when it was successful.
Tree	System	sealed	Provides various functions for interacting with TreeNodes.
TreeAlpha	System	sealed	Extensions to Tree and TreeBeta which are not yet stable.
TreeArrayNode		sealed	A TreeNode which implements 'readonly T[]' and the array mutation APIs.
TreeBeta	System	sealed	Extensions to Tree which are not yet stable.
TreeBranch	Beta	sealed	A collection of functionality associated with a (version-control-style) branch of a SharedTree.
TreeBranchAlpha	Alpha	sealed	TreeBranch with alpha-level APIs.
TreeBranchEvents	Alpha	sealed	Events for TreeBranch.
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.
TreeEncodingOptions	Beta		Options for how to interpret or encode a tree when schema information is available.
TreeIdentifierUtils	Alpha	sealed	A utility interface for retrieving or converting node identifiers.
TreeIndex	Alpha		A index where values are keyed on TreeIndexKeys.
TreeMapNode		sealed	A map of string keys to tree objects.
TreeNodeApi		sealed	Provides various functions for analyzing TreeNodes.
TreeNodeSchemaCore		sealed	Data common to all tree node schema.
TreeRecordNode	Beta		A TreeNode which models a TypeScript record.
TreeRecordNodeUnsafe	System	sealed	Unenforced version of TreeRecordNode.
TreeSchema	Alpha	sealed	TreeViewConfigurationAlpha
TreeSchemaEncodingOptions	Alpha		Options for how to interpret or encode a tree when schema information is available.
TreeView		sealed	An editable view of a (version control style) branch of a shared tree based on some schema.
TreeViewAlpha	Alpha	sealed	TreeView with proposed changes to the schema aware typing to allow use with UnsafeUnknownSchema.
TreeViewBeta	Beta	sealed	TreeView with additional beta APIs.
TreeViewEvents		sealed	Events for TreeView.
VerboseTreeNode	Alpha		Verbose encoding of a TreeNode.
ViewableTree	System	sealed	A tree from which a TreeView can be created.
ViewContent	Alpha		The portion of SharedTree data typically persisted by the container. Usable with independentInitializedView(config, options, content) to create a TreeView without loading a container.
WithType		sealed	Adds a type symbol to a type for stronger typing.

Classes

Class	Alerts	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.
FieldSchemaAlpha	Alpha	sealed	FieldSchema including alpha APIs (currently SimpleFieldSchema).
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.
SchemaFactoryAlpha	Alpha		SchemaFactory with additional alpha APIs.
SchemaFactoryBeta	Beta		SchemaFactory with additional beta APIs.
SchemaUpgrade	Beta	sealed	Unique token used to upgrade schemas and determine if a particular upgrade has been completed.
TreeNode		sealed	A non-leaf SharedTree node. Includes objects, arrays, and maps.
TreeViewConfiguration		sealed	Configuration for viewWith(config).
TreeViewConfigurationAlpha	Alpha	sealed	TreeViewConfiguration extended with some alpha APIs.

Enumerations

Enum	Alerts	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 an TreeObjectNode.
KeyEncodingOptions	Beta	Options for how to encode keys in a tree.
NodeKind		Kind of tree node.
RevertibleStatus		The status of a Revertible.
SchemaType	Alpha	The type of simple schema being represented.
TreeCompressionStrategy	Alpha	Selects which heuristics to use when encoding tree content. All encoding options here are compatible with the same decoder: the selection here does not impact compatibility.
TreeStatus		Status of the tree that a particular node belongs to.
ValueSchema	Alpha	Schema for what TreeLeafValue is allowed on a Leaf node.

Types

TypeAlias	Alerts	Modifiers	Description
AllowedTypes	System		Schema for types allowed in some location in a tree (like a field, map entry or array).
AllowedTypesFull	Beta	sealed	Stores annotations for a set of allowed types.
AllowedTypesFullEvaluated	Beta	sealed	AllowedTypesFull but with the lazy schema references eagerly evaluated.
AllowedTypesFullFromMixed	System	sealed	Creates an AllowedTypesFull type from a mixed array of annotated and unannotated allowed types.
AllowedTypesFullFromMixedUnsafe	System	sealed	Unenforced version of AllowedTypesFullFromMixed.
AllowedTypesFullUnsafe	System	sealed	Unenforced version of AllowedTypesFull.
AnnotateAllowedTypesList	System		Add annotations to a list of allowed types that may or may not contain annotations.
AnnotateAllowedTypesListUnsafe	System	sealed	Unenforced version of AnnotateAllowedTypesList.
ArrayNodeSchema	Alpha		A schema for TreeArrayNodes.
ChangeMetadata	Alpha	sealed	Information about a commit that has been applied.
ConciseTree	Beta		Concise encoding of a TreeNode or TreeLeafValue.
DirtyTreeStatus	Alpha		The status of a node in a that has been tracked for changes.
FactoryContent	System		Content which can be used to build a node.
FactoryContentObject	System		Record-like object which can be used to build some kinds of nodes.
FixRecursiveArraySchema	Beta		Workaround for fixing errors resulting from an issue with recursive ArrayNode schema exports.
HandleConverter	Alpha		Options for how to transcode handles.
IdentifierIndex	Alpha		An index that returns tree nodes given their associated identifiers.
ImplicitAllowedTypes			Types of TreeNodes or TreeLeafValues allowed at a location in a tree.
ImplicitFieldSchema			Schema for a field of a tree node.
IncrementalEncodingPolicy	Alpha		Policy type to determine whether one of more fields of a node in a schema should be incrementally encoded.
Input	System		This type exists only to be linked from documentation to provide a single linkable place to document some details of "Input" types and how they handle schema. When a schema is used to describe data which is an input into an API, the API is contravariant) over the schema. (See also TypeScript Variance Annotations). Since these schema are expressed using TypeScript types, it is possible for the user of the API to provide non-exact values of these types which has implications that depended on the variance. Consider a field with schema type of A
Insertable	Alpha		Content which could be inserted into a tree.
InsertableContent	System		Content which can be inserted into a tree.
InsertableField	Alpha		Content which could be inserted into a field within a tree.
InsertableTreeFieldFromImplicitField			Type of content that can be inserted into the tree for a field of the given schema.
InsertableTreeNodeFromAllowedTypes	System		Type of content that can be inserted into the tree for a node of the given schema.
InsertableTreeNodeFromImplicitAllowedTypes			Type of content that can be inserted into the tree for a node of the given schema.
InsertableTypedNode			Data which can be used as a node to be inserted. Either an unhydrated node, or content to build a new node.
IsListener	Deprecated		true iff the given type is an acceptable shape for a event listener
IsUnion	System		Returns true if T is a union and false if it is not.
JsonCompatible	Beta		Use for Json compatible data.
JsonCompatibleObject	Beta		Use for Json object compatible data.
JsonCompatibleReadOnly	Alpha		Use for readonly view of Json compatible data.
JsonCompatibleReadOnlyObject	Alpha		Use for readonly view of Json compatible data.
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.
Listenable	Deprecated		An object which allows the registration of listeners so that subscribers can be notified when an event happens.
Listeners	Deprecated		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.
MapNodeSchema	Alpha		A schema for TreeMapNodes.
NodeFromSchema			Takes in TreeNodeSchema[] and returns a TypedNode union.
NumberKeys	System		Extracts the keys of T which are numbers.
ObjectFromSchemaRecord	System		Generates the properties for an ObjectNode from its field schema object.
Off	Deprecated		A function that, when called, will deregister an event listener subscription that was previously registered.
PopUnion	System		Gets the first item of a union type.
ReadableField	System		Content which could be read from a field within a tree.
ReadSchema	System		Adapter to remove UnsafeUnknownSchema from a schema type so it can be used with types for generating APIs for reading data.
RecordNodeInsertableData	System		Content which can be used to construct a Record node, explicitly or implicitly.
RecordNodeSchema	Alpha		A schema for TreeRecordNodes.
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.
RevertibleAlphaFactory	Alpha	sealed	Factory for creating a RevertibleAlpha.
RevertibleFactory		sealed	Factory for creating a Revertible.
SharedTreeOptionsBeta	Beta		Configuration options for SharedTree.
SimpleNodeSchema	Alpha		A simple, shallow representation of a schema for a node.
SimpleTreeIndex	Alpha		A TreeIndex that returns tree nodes given their associated keys.
TransactionCallbackStatus	Alpha		The status of the transaction callback in the RunTransaction API.
TransactionConstraint			A requirement for a SharedTree transaction to succeed.
TransactionResult	Alpha		The result of the RunTransaction API. This is the same as TransactionResultExt but with the value field omitted. This is useful when the transaction callback doesn't need to return a value.
TransactionResultExt	Alpha		The result of the RunTransaction API.
TreeFieldFromImplicitField			Converts an ImplicitFieldSchema to a property type suitable for reading a field with this that schema.
TreeIndexKey	Alpha		Value that may be used as keys in a TreeIndex.
TreeIndexNodes	Alpha		an array of nodes that is guaranteed to have at least one element
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 TreeNode or TreeLeafValue.
TreeNodeSchemaClass		sealed	Tree node schema which is implemented using a class.
TreeNodeSchemaNonClass	System	sealed	Schema which is not a class.
TreeObjectNode			A TreeNode which models a JavaScript object.
TreeParsingOptions	Alpha		Options for how to interpret a tree when schema information is available.
UnannotateAllowedTypesList	System		Removes annotations from a list of allowed types that may contain annotations.
UnannotateAllowedTypesListUnsafe	System	sealed	Unenforced version of UnannotateAllowedTypesList.
UnannotateAllowedTypeUnsafe	System	sealed	Unenforced utility to remove AnnotatedAllowedTypeUnsafe wrappers.
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.
UnionToIntersection	System		Convert a union of types to an intersection of those types. Useful for TransformEvents.
UnionToTuple	System		Converts a union type to a tuple type.
UnsafeUnknownSchema	Alpha		A special type which can be provided to some APIs as the schema type parameter when schema cannot easily be provided at compile time and an unsafe (instead of disabled) editing API is desired.
ValidateRecursiveSchema			Compile time check for validity of a recursive schema. This type also serves as a central location for documenting the requirements and issues related to recursive schema.
ValidateRecursiveSchemaTemplate	System		Validation logic used by ValidateRecursiveSchema.
VerboseTree	Alpha		Verbose encoding of a TreeNode or TreeLeafValue.
VoidTransactionCallbackStatus	Alpha		The status of a the transaction callback in the RunTransaction API where the transaction doesn't need to return a value. This is the same as TransactionCallbackStatus but with the value field omitted. This

Functions

Function	Alerts	Return Type	Description
adaptEnum(factory, members)	Beta	(<TValue extends TEnum[keyof TEnum]>(value: TValue) => TValue extends unknown ? TreeNode & { readonly value: TValue; } : never) & { readonly [Property in keyof TEnum]: TreeNodeSchemaClass<ScopedSchemaName<TScope, TEnum[Property]>, NodeKind.Object, TreeNode & { readonly value: TEnum[Property]; }, Record<string, never>, true, Record<string, never>, undefined>; } & { readonly schema: UnionToTuple<{ readonly [Property in keyof TEnum]: TreeNodeSchemaClass<ScopedSchemaName<TScope, TEnum[Property]>, NodeKind.Object, TreeNode & { readonly value: TEnum[Property]; }, Record<string, never>, true, Record<string, never>, undefined>; }[keyof TEnum]>; }	Converts an enum into a collection of schema which can be used in a union.
allowUnused(t)	Alpha	void	Does nothing with the provided value, but appears to use it to make unused locals warnings and errors go away.
asAlpha(view)	Alpha	TreeViewAlpha<TSchema>	Retrieve the alpha API for a TreeView.
asAlpha(view)	Alpha	TreeViewConfigurationAlpha<TSchema>	Retrieve the alpha API for a TreeViewConfiguration.
asBeta(view)	Beta	TreeViewBeta<TSchema>	Retrieve the beta API for a TreeView.
asTreeViewAlpha(view)	Deprecated, Alpha	TreeViewAlpha<TSchema>	Retrieve the alpha API for a TreeView.
checkCompatibility(viewWhichCreatedStoredSchema, view)	Alpha	Omit<SchemaCompatibilityStatus, "canInitialize">	Compute the compatibility of using view to view a tree who's stored schema could be derived from viewWhichCreatedStoredSchema via either initialize(content) or upgradeSchema().
cloneWithReplacements(root, rootKey, replacer)	Alpha	unknown	Like JSON.stringify, but returns a clone instead of stringifying the result.
comparePersistedSchema(persisted, view, options)	Alpha	Omit<SchemaCompatibilityStatus, "canInitialize">	Compares two schema extracted using extractPersistedSchema(schema, minVersionForCollab, includeStaged). Reports the same compatibility that compatibility would report if opening a document that used the persisted schema and provided view to viewWith(config).
configuredSharedTreeAlpha(options)	Alpha	SharedObjectKind<ITree>	configuredSharedTreeBeta(options) but including the alpha SharedTreeOptions.
configuredSharedTreeBeta(options)	Beta	SharedObjectKind<ITree>	SharedTree but allowing a non-default configuration.
configuredSharedTreeBetaLegacy(options)	Legacy	ISharedObjectKind<ITree> & SharedObjectKind<ITree>	configuredSharedTreeBeta(options) including the legacy ISharedObjectKind type.
createIdentifierIndex(view)	Alpha	IdentifierIndex	Creates an IdentifierIndex for a given TreeView.
createIndependentTreeAlpha(options)	Alpha	ViewableTree & Pick<ITreeAlpha, "exportVerbose" | "exportSimpleSchema">	Alpha extensions to createIndependentTreeBeta(options).
createIndependentTreeBeta(options)	Beta	ViewableTree	Create a ViewableTree that is not tied to any Fluid runtimes or services.
createSimpleTreeIndex(view, indexer, getValue, isKeyValid)	Alpha	SimpleTreeIndex<TKey, TValue>	Creates a SimpleTreeIndex with a specified indexer.
createSimpleTreeIndex(view, indexer, getValue, isKeyValid, indexableSchema)	Alpha	SimpleTreeIndex<TKey, TValue>	Creates a SimpleTreeIndex with a specified indexer.
createSimpleTreeIndex(view, indexer, getValue, isKeyValid)	Alpha	SimpleTreeIndex<TKey, TValue>	Creates a SimpleTreeIndex with a specified indexer.
createSimpleTreeIndex(view, indexer, getValue, isKeyValid, indexableSchema)	Alpha	SimpleTreeIndex<TKey, TValue>	Creates a SimpleTreeIndex with a specified indexer.
decodeSchemaCompatibilitySnapshot(encodedSchema, validator)	Alpha	SimpleTreeSchema	Decodes a JSON-compatible schema into a simple schema.
encodeSchemaCompatibilitySnapshot(simpleSchema)	Alpha	JsonCompatibleReadOnly	Encodes the compatibility impacting subset of simple schema (view or stored) into a serializable format.
enumFromStrings(factory, members)	Beta	(<TValue extends Members[number]>(value: TValue) => TValue extends unknown ? TreeNode & { readonly value: TValue; } : never) & { [Index in Extract<keyof Members, `${number}`> extends `${infer N extends number}` ? N : never as Members[Index]]: TreeNodeSchemaClass<ScopedSchemaName<TScope, Members[Index]>, NodeKind.Object, TreeNode & { readonly value: Members[Index]; }, Record<string, never>, true, Record<string, never>, undefined>; } & { readonly schema: UnionToTuple<Members[number] extends unknown ? { [Index in Extract<keyof Members, `${number}`> extends `${infer N extends number}` ? N : never as Members[Index]]: TreeNodeSchemaClass<ScopedSchemaName<TScope, Members[Index]>, NodeKind.Object, TreeNode & { readonly value: Members[Index]; }, Record<string, never>, true, Record<string, never>, undefined>; }[Members[number]] : never>; }	Converts an array of distinct strings into a collection of schema which can be used like an enum style union.
eraseSchemaDetails()	Alpha	<T extends ExtraSchemaProperties & TreeNodeSchema<string, NodeKind, TNode & TreeNode>>(schema: T) => ExtraSchemaProperties & TreeNodeSchema<T["identifier"], NodeKind, TNode & TreeNode & WithType<T["identifier"]>, never, false>	Type-erase details of a schema.
eraseSchemaDetailsSubclassable()	Alpha	<T extends ExtraSchemaProperties & TreeNodeSchemaClass<string, NodeKind, TNode & TreeNode>>(schema: T) => ExtraSchemaProperties & TreeNodeSchemaClass<T["identifier"], NodeKind, TNode & TreeNode & WithType<T["identifier"]>, never, false>	Like eraseSchemaDetails() but allows the returned schema to be subclassed.
evaluateLazySchema(value)	Alpha	T	Returns the schema referenced by the LazyItem.
exportCompatibilitySchemaSnapshot(config)	Alpha	JsonCompatibleReadOnly	Returns a JSON compatible representation of the tree schema for snapshot compatibility checking. Snapshots can be loaded by the same or newer package versions, but not necessarily older versions.
extractPersistedSchema(schema, minVersionForCollab, includeStaged)	Alpha	JsonCompatible	Dumps the "persisted" schema subset of the provided schema into a deterministic JSON-compatible, semi-human-readable format.
generateSchemaFromSimpleSchema(simple)	Alpha	TreeSchema	Create FieldSchema from a SimpleTreeSchema.
getBranch(tree)	Deprecated, Alpha	BranchableTree	Get a BranchableTree from a ITree.
getBranch(view)	Deprecated, Alpha	BranchableTree	Get a BranchableTree from a TreeView.
getJsonSchema(schema, options)	Alpha	JsonTreeSchema	Creates a JSON Schema representation of the provided TreeNodeSchema.
getSimpleSchema(schema)	Alpha	SimpleTreeSchema<SchemaType.View>	Copies data from ImplicitFieldSchema to create a SimpleTreeSchema out of new plain JavaScript objects, Sets and Maps.
importCompatibilitySchemaSnapshot(config)	Alpha	TreeViewConfiguration	Parse the format exported by exportCompatibilitySchemaSnapshot(config) into a schema. Can load snapshots created by the same or older package versions, but not necessarily newer versions.
incrementalEncodingPolicyForAllowedTypes(rootSchema)	Alpha	IncrementalEncodingPolicy	This helper function incrementalEncodingPolicyForAllowedTypes(rootSchema) can be used to generate a callback function of type IncrementalEncodingPolicy. It determines if each AllowedTypes in a schema should be incrementally summarized. This callback can be passed as the value for shouldEncodeIncrementally parameter when creating the tree.
independentInitializedView(config, options, content)	Alpha	TreeViewAlpha<TSchema>	Create an initialized TreeView that is not tied to any ITree instance.
independentView(config, options)	Alpha	TreeViewAlpha<TSchema>	Create an uninitialized TreeView that is not tied to any ITree instance.
normalizeAllowedTypes(types)	Alpha	AllowedTypesFull	Normalizes an ImplicitAllowedTypes to an AllowedTypesFull.
persistedToSimpleSchema(persisted, options)	Alpha	SimpleTreeSchema	A way to parse schema in the persisted format from extractPersistedSchema(schema, minVersionForCollab, includeStaged).
replaceConciseTreeHandles(tree, replacer)	Alpha	ConciseTree<T>	Clones tree, replacing any handles.
replaceHandles(tree, replacer)	Alpha	unknown	Clones tree, replacing any handles.
replaceVerboseTreeHandles(tree, replacer)	Alpha	VerboseTree<T>	Clones tree, replacing any handles.
singletonSchema(factory, name)	Beta	TreeNodeSchemaClass<ScopedSchemaName<TScope, TName>, NodeKind.Object, TreeNode & { readonly value: TName; }, Record<string, never>, true, Record<string, never>, undefined>	Create a schema for a node with no state.
trackDirtyNodes(view, dirty)	Alpha	() => void	Registers a visitor on the view's forest that tracks which nodes are dirty.

Variables

Variable	Alerts	Modifiers	Type	Description
ArrayNodeSchema	Alpha	readonly	{ readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is ArrayNodeSchema; }
contentSchemaSymbol	Alpha	readonly	unique symbol	The intended type of insertable content that is to become a TreeNode.
FluidClientVersion	Alpha	readonly	{ readonly v2_0: "2.0.0"; readonly v2_43: "2.43.0"; readonly v2_52: "2.52.0"; readonly v2_73: "2.73.0"; readonly v2_74: "2.74.0"; }	Versions of Fluid Framework client packages.
ForestTypeExpensiveDebug	Beta	readonly	ForestType	Slow implementation of forest intended only for debugging.
ForestTypeOptimized	Beta	readonly	ForestType	Optimized implementation of forest.
ForestTypeReference	Beta	readonly	ForestType	Reference implementation of forest.
FormatValidatorBasic	Alpha	readonly	import("../codec/codec.js").FormatValidator	A FormatValidator implementation which uses TypeBox's JSON schema validator.
FormatValidatorNoOp	Alpha	readonly	FormatValidator	A FormatValidator which does no validation.
incrementalSummaryHint	Alpha	readonly	unique symbol	A symbol when present in the metadata's custom property as true, opts in the allowed types to incremental summary optimization. These allowed types will be optimized during summary such that if they don't change across summaries, they will not be encoded and their content will not be included in the summary that is uploaded to the service.
MapNodeSchema	Alpha	readonly	{ readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is MapNodeSchema; }
ObjectNodeSchema	Alpha	readonly	{ readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is ObjectNodeSchema<string, RestrictiveStringRecord<ImplicitFieldSchema>, boolean, unknown>; }
RecordNodeSchema	Alpha	readonly	{ readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is RecordNodeSchema<string, ImplicitAllowedTypes, true, unknown>; }
rollback		readonly	unique symbol	A special object that signifies when a SharedTree transaction should "roll back".
SchemaFactory_base	System	readonly	SchemaStatics & (new () => SchemaStatics)	Base class for SchemaFactory, exposes SchemaStatics as both static properties and member properties.
SharedTree	Legacy	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.
SharedTreeAttributes	Legacy	readonly	IChannelAttributes
SharedTreeFactoryType	Legacy	readonly
Tree		readonly	Tree	The Tree singleton which holds various functions for interacting with TreeNodes.
TreeAlpha	Alpha	readonly	TreeAlpha	Extensions to Tree and TreeBeta which are not yet stable.
TreeArrayNode		readonly	{ readonly spread: <T>(content: Iterable<T>) => IterableTreeArrayContent<T>; }	A TreeNode which implements 'readonly T[]' and the array mutation APIs.
TreeBeta	Beta	readonly	TreeBeta	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.
UnsafeUnknownSchema	Alpha	readonly	unique symbol	A special type which can be provided to some APIs as the schema type parameter when schema cannot easily be provided at compile time and an unsafe (instead of disabled) editing API is desired.

Namespaces

Namespace	Alerts	Description
FluidSerializableAsTree	Beta	Utilities for storing Fluid Serializable data in TreeNodes. Same as JsonAsTree except allows IFluidHandles.
InternalTypes
JsonAsTree	Alpha	Utilities for storing JSON data in TreeNodes.
System_TableSchema	System	Not intended for use outside of this package.
System_Unsafe	System	A collection of Unenforced types that are used in the implementation of recursive schema. These are all @system types, and thus should not be used directly.
TableSchema	Alpha	Contains types and factories for creating schema to represent dynamic tabular data.

Function Details

adaptEnum

Converts an enum into a collection of schema which can be used in a union.

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

export declare function adaptEnum<TScope extends string, const TEnum extends Record<string, string | number>>(factory: SchemaFactory<TScope>, members: TEnum): (<TValue extends TEnum[keyof TEnum]>(value: TValue) => TValue extends unknown ? TreeNode & {
    readonly value: TValue;
} : never) & { readonly [Property in keyof TEnum]: TreeNodeSchemaClass<ScopedSchemaName<TScope, TEnum[Property]>, NodeKind.Object, TreeNode & {
    readonly value: TEnum[Property];
}, Record<string, never>, true, Record<string, never>, undefined>; } & {
    readonly schema: UnionToTuple<{ readonly [Property in keyof TEnum]: TreeNodeSchemaClass<ScopedSchemaName<TScope, TEnum[Property]>, NodeKind.Object, TreeNode & {
        readonly value: TEnum[Property];
    }, Record<string, never>, true, Record<string, never>, undefined>; }[keyof TEnum]>;
};

Type Parameters

Parameter	Constraint	Description
TScope	string	The scope of the provided factory. There is a known issue where if a factory is provided that is typed as a SchemaFactoryAlpha, and its scope contains a "." character, the inferred type for the scope will end up as a union of the scope up to the first "." character and the scope as it should be. This can be mitigated by explicitly providing the TScope type parameter or by typing the provided factory as a SchemaFactory instead of a SchemaFactoryAlpha.
TEnum	Record<string, string | number>

Remarks

The string value of the enum is used as the name of the schema: callers must ensure that it is stable and unique. Numeric enums values have the value implicitly converted into a string. Consider making a dedicated schema factory with a nested scope (for example using scopedFactory(name)) to avoid the enum members colliding with other schema.

Example

const schemaFactory = new SchemaFactory("com.myApp");
// An enum for use in the tree. Must have string keys.
enum Mode {
	a = "A",
	b = "B",
}
// Define the schema for each member of the enum using a nested scope to group them together.
const ModeNodes = adaptEnum(new SchemaFactory(`${schemaFactory.scope}.Mode`), Mode);
// Defined the types of the nodes which correspond to this the schema.
type ModeNodes = TreeNodeFromImplicitAllowedTypes<(typeof ModeNodes.schema)>;
// An example schema which has an enum as a child.
class Parent extends schemaFactory.object("Parent", {
	// adaptEnum's return value has a ".schema" property can be use as an `AllowedTypes` array allowing any of the members of the enum.
	mode: ModeNodes.schema,
}) {}

// Example usage of enum based nodes, showing what type to use and that `.value` can be used to read out the enum value.
function getValue(node: ModeNodes): Mode {
	return node.value;
}

// Example constructing a tree containing an enum node from an enum value.
// The syntax `new ModeNodes.a()` is also supported.
function setValue(node: Parent): void {
	node.mode = ModeNodes(Mode.a);
}

Parameters

Parameter	Type	Description
factory	SchemaFactory<TScope>
members	TEnum

Returns

Return type: (<TValue extends TEnum[keyof TEnum]>(value: TValue) => TValue extends unknown ? TreeNode & { readonly value: TValue; } : never) & { readonly [Property in keyof TEnum]: TreeNodeSchemaClass<ScopedSchemaName<TScope, TEnum[Property]>, NodeKind.Object, TreeNode & { readonly value: TEnum[Property]; }, Record<string, never>, true, Record<string, never>, undefined>; } & { readonly schema: UnionToTuple<{ readonly [Property in keyof TEnum]: TreeNodeSchemaClass<ScopedSchemaName<TScope, TEnum[Property]>, NodeKind.Object, TreeNode & { readonly value: TEnum[Property]; }, Record<string, never>, true, Record<string, never>, undefined>; }[keyof TEnum]>; }

See Also

enumFromStrings(factory, members) for a similar function that works on arrays of strings instead of an enum.

allowUnused

Does nothing with the provided value, but appears to use it to make unused locals warnings and errors go away.

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 allowUnused<T>(t?: T): void;

Type Parameters

Parameter	Description
T

Remarks

When TypeScript is configured with "noUnusedLocals", it will produce an error if a local variable is declared but never used. When you want to have this check enabled, but not follow it for a specific variable, you can pass the type or value to this function.

Instead of using this, consider disabling "noUnusedLocals" in your tsconfig.json file, and enabling a similar check via a linter. This will allow you to still have the check, but have more control over it, for example being able to suppress it, or enable patterns like allowing unused locals with an "_" prefix.

Parameters

Parameter	Modifiers	Type	Description
t	optional	T

asAlpha

Retrieve the alpha API for 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 asAlpha<TSchema extends ImplicitFieldSchema>(view: TreeView<TSchema>): TreeViewAlpha<TSchema>;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Parameters

Parameter	Type	Description
view	TreeView<TSchema>

Returns

Return type: TreeViewAlpha<TSchema>

asAlpha

Retrieve the alpha API for a TreeViewConfiguration.

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 asAlpha<TSchema extends ImplicitFieldSchema>(view: TreeViewConfiguration<TSchema>): TreeViewConfigurationAlpha<TSchema>;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Parameters

Parameter	Type	Description
view	TreeViewConfiguration<TSchema>

Returns

Return type: TreeViewConfigurationAlpha<TSchema>

asBeta

Retrieve the beta API for a TreeView.

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

export declare function asBeta<TSchema extends ImplicitFieldSchema>(view: TreeView<TSchema>): TreeViewBeta<TSchema>;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Parameters

Parameter	Type	Description
view	TreeView<TSchema>

Returns

Return type: TreeViewBeta<TSchema>

asTreeViewAlpha

Retrieve the alpha API for a TreeView.

This API is deprecated and will be removed in a future release.

Use asAlpha(view) instead.

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 asTreeViewAlpha<TSchema extends ImplicitFieldSchema>(view: TreeView<TSchema>): TreeViewAlpha<TSchema>;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Parameters

Parameter	Type	Description
view	TreeView<TSchema>

Returns

Return type: TreeViewAlpha<TSchema>

checkCompatibility

Compute the compatibility of using view to view a tree who's stored schema could be derived from viewWhichCreatedStoredSchema via either initialize(content) or upgradeSchema().

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 checkCompatibility(viewWhichCreatedStoredSchema: TreeViewConfiguration, view: TreeViewConfiguration): Omit<SchemaCompatibilityStatus, "canInitialize">;

Remarks

See SchemaCompatibilityStatus for details on the compatibility results.

Example

This example demonstrates checking the compatibility of a historical schema against a current schema. In this case, the historical schema is a Point2D object with x and y fields, while the current schema is a Point3D object that adds an optional z field.

// This snapshot is assumed to be the same as Point3D, except missing `z`.
const encodedSchema = JSON.parse(fs.readFileSync("PointSchema.json", "utf8"));
const oldViewSchema = importCompatibilitySchemaSnapshot(encodedSchema);

// Build the current view schema
class Point3D extends factory.object("Point", {
	x: factory.number,
	y: factory.number,

	// The current schema has a new optional field that was not present on Point2D
	z: factory.optional(factory.number),
}) {}
const currentViewSchema = new TreeViewConfiguration({ schema: Point3D });

// Check to see if the document created by the historical view schema can be opened with the current view schema
const backwardsCompatibilityStatus = checkCompatibility(oldViewSchema, currentViewSchema);

// z is not present in Point2D, so the schema must be upgraded
assert.equal(backwardsCompatibilityStatus.canView, false);

// The schema can be upgraded to add the new optional field
assert.equal(backwardsCompatibilityStatus.canUpgrade, true);

// Test what the old version of the application would do with a tree using the new schema:
const forwardsCompatibilityStatus = checkCompatibility(currentViewSchema, oldViewSchema);

// If the old schema set allowUnknownOptionalFields, this would be true, but since it did not,
// this assert will fail, detecting the forwards compatibility break:
// this means these two versions of the application cannot collaborate on content using these schema.
assert.equal(forwardsCompatibilityStatus.canView, true);

Parameters

Parameter	Type	Description
viewWhichCreatedStoredSchema	TreeViewConfiguration	From which to derive the stored schema, as if it initialized or upgraded a tree via TreeView.
view	TreeViewConfiguration	The view being tested to see if it could view tree created or initialized using viewWhichCreatedStoredSchema.

Returns

The compatibility status.

Return type: Omit<SchemaCompatibilityStatus, "canInitialize">

cloneWithReplacements

Like JSON.stringify, but returns a clone instead of stringifying the result.

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 cloneWithReplacements(root: unknown, rootKey: string, replacer: (key: string, value: unknown) => {
    clone: boolean;
    value: unknown;
}): unknown;

Remarks

Only considers enumerable own properties with string keys.

Parameters

Parameter	Type	Description
root	unknown	Data to clone.
rootKey	string	The key to pass to replacer for the root.
replacer	(key: string, value: unknown) => { clone: boolean; value: unknown; }	Like JSON.stringify's replacer: called for every value while walking data. Unlike JSON.stringify's replacer, this returns a wrapper around the value with a "clone" flag to indicate if the clone should recurse into that object (true) or use it as is (false).

Returns

A clone of root.

Return type: unknown

comparePersistedSchema

Compares two schema extracted using extractPersistedSchema(schema, minVersionForCollab, includeStaged). Reports the same compatibility that compatibility would report if opening a document that used the persisted schema and provided view to viewWith(config).

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 comparePersistedSchema(persisted: JsonCompatible, view: ImplicitFieldSchema, options: ICodecOptions): Omit<SchemaCompatibilityStatus, "canInitialize">;

Remarks

This uses the persisted formats for schema, meaning it only includes data which impacts compatibility. It also uses the persisted format so that this API can be used in tests to compare against saved schema from previous versions of the application.

Example

An application could use extractPersistedSchema(schema, minVersionForCollab, includeStaged) to generate a schema.json file for various versions of the app, then test that documents using those schema can be upgraded to work with the current schema using a test like:

assert(
	comparePersistedSchema(
		require("./schema.json"),
		MySchema,
		{ jsonValidator: typeboxValidator },
		false,
	).canUpgrade,
);

Parameters

Parameter	Type	Description
persisted	JsonCompatible	Schema persisted for a document. Typically persisted alongside the data and assumed to describe that data.
view	ImplicitFieldSchema	Schema which would be used to view persisted content.
options	ICodecOptions	ICodecOptions used when parsing the provided schema.

Returns

The SchemaCompatibilityStatus a TreeView would report for this combination of schema.

Return type: Omit<SchemaCompatibilityStatus, "canInitialize">

configuredSharedTreeAlpha

configuredSharedTreeBeta(options) but including the alpha SharedTreeOptions.

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 configuredSharedTreeAlpha(options: SharedTreeOptions): SharedObjectKind<ITree>;

Parameters

Parameter	Type	Description
options	SharedTreeOptions

Returns

Return type: SharedObjectKind<ITree>

configuredSharedTreeBeta

SharedTree but allowing a non-default configuration.

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

export declare function configuredSharedTreeBeta(options: SharedTreeOptionsBeta): SharedObjectKind<ITree>;

Remarks

This is useful for debugging and testing. For example it can be used to opt into extra validation or see if opting out of some optimizations fixes an issue.

With great care, and knowledge of the support and stability of the options exposed here, this can also be used to opt into some features early or for performance tuning.

Example

import {
	configuredSharedTreeBeta,
	ForestTypeReference,
} from "fluid-framework/beta";
const SharedTree = configuredSharedTree({
	forest: ForestTypeReference,
});

Parameters

Parameter	Type	Description
options	SharedTreeOptionsBeta

Returns

Return type: SharedObjectKind<ITree>

configuredSharedTreeBetaLegacy

configuredSharedTreeBeta(options) including the legacy ISharedObjectKind type.

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

export declare function configuredSharedTreeBetaLegacy(options: SharedTreeOptionsBeta): ISharedObjectKind<ITree> & SharedObjectKind<ITree>;

Parameters

Parameter	Type	Description
options	SharedTreeOptionsBeta

Returns

Return type: ISharedObjectKind<ITree> & SharedObjectKind<ITree>

createIdentifierIndex

Creates an IdentifierIndex for a given 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 createIdentifierIndex<TSchema extends ImplicitFieldSchema>(view: TreeView<TSchema>): IdentifierIndex;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Parameters

Parameter	Type	Description
view	TreeView<TSchema>

Returns

Return type: IdentifierIndex

createIndependentTreeAlpha

Alpha extensions to createIndependentTreeBeta(options).

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 createIndependentTreeAlpha<const TSchema extends ImplicitFieldSchema>(options?: ForestOptions & (({
    idCompressor?: IIdCompressor | undefined;
} & {
    content?: undefined;
}) | (ICodecOptions & {
    content: ViewContent;
} & {
    idCompressor?: undefined;
}))): ViewableTree & Pick<ITreeAlpha, "exportVerbose" | "exportSimpleSchema">;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Parameters

Parameter	Modifiers	Type	Description
options	optional	ForestOptions & (({ idCompressor?: IIdCompressor | undefined; } & { content?: undefined; }) | (ICodecOptions & { content: ViewContent; } & { idCompressor?: undefined; }))	Configuration options for the independent tree. This can be used to create an uninitialized tree, or content can be provided to create an initialized tree. If content is provided, the idCompressor is a required part of it: otherwise it is optional and provided at the top level.

Returns

Return type: ViewableTree & Pick<ITreeAlpha, "exportVerbose" | "exportSimpleSchema">

createIndependentTreeBeta

Create a ViewableTree that is not tied to any Fluid runtimes or services.

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

export declare function createIndependentTreeBeta<const TSchema extends ImplicitFieldSchema>(options?: ForestOptions): ViewableTree;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Remarks

Such a tree can never experience collaboration or be persisted to to a Fluid Container.

This can be useful for testing, as well as use-cases like working on local files instead of documents stored in some Fluid service.

Example

const tree = createIndependentTreeBeta();

const stagedConfig = new TreeViewConfiguration({
	schema: SchemaFactoryAlpha.types([
		SchemaFactory.number,
		SchemaFactoryAlpha.staged(SchemaFactory.string),
	]),
});
const afterConfig = new TreeViewConfigurationAlpha({
	schema: [SchemaFactory.number, SchemaFactory.string],
});

// Initialize tree
{
	const view = tree.viewWith(stagedConfig);
	view.initialize(1);
	view.dispose();
}

// Do schema upgrade
{
	const view = tree.viewWith(afterConfig);
	view.upgradeSchema();
	view.root = "A";
	view.dispose();
}

// Can still view tree with staged schema
{
	const view = tree.viewWith(stagedConfig);
	assert.equal(view.root, "A");
	view.dispose();
}

Parameters

Parameter	Modifiers	Type	Description
options	optional	ForestOptions

Returns

Return type: ViewableTree

createSimpleTreeIndex

Creates a SimpleTreeIndex with a specified indexer.

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 createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue>(view: TreeView<TFieldSchema>, indexer: (schema: TreeNodeSchema) => string | undefined, getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey): SimpleTreeIndex<TKey, TValue>;

Type Parameters

Parameter	Constraint	Description
TFieldSchema	ImplicitFieldSchema
TKey	TreeIndexKey
TValue

Parameters

Parameter	Type	Description
view	TreeView<TFieldSchema>	the view for the tree being indexed
indexer	(schema: TreeNodeSchema) => string | undefined	a function that takes in a TreeNodeSchema and returns the field name that all nodes of the given schema should be keyed on, must be pure and functional
getValue	(nodes: TreeIndexNodes<TreeNode>) => TValue	given at least one TreeNode, returns an associated value
isKeyValid	(key: TreeIndexKey) => key is TKey	function for verifying the validity of the key retrieved based on the information given by the indexer

Returns

Return type: SimpleTreeIndex<TKey, TValue>

createSimpleTreeIndex

Creates a SimpleTreeIndex with a specified indexer.

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 createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue, TSchema extends TreeNodeSchema>(view: TreeView<TFieldSchema>, indexer: (schema: TSchema) => string | undefined, getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey, indexableSchema: readonly TSchema[]): SimpleTreeIndex<TKey, TValue>;

Type Parameters

Parameter	Constraint	Description
TFieldSchema	ImplicitFieldSchema
TKey	TreeIndexKey
TValue
TSchema	TreeNodeSchema

Parameters

Parameter	Type	Description
view	TreeView<TFieldSchema>	the view for the tree being indexed
indexer	(schema: TSchema) => string | undefined	a function that takes in a TreeNodeSchema and returns the field name that all nodes of the given schema should be keyed on, must be pure and functional
getValue	(nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue	given at least one TreeNode, returns an associated value
isKeyValid	(key: TreeIndexKey) => key is TKey	function for verifying the validity of the key retrieved based on the information given by the indexer
indexableSchema	readonly TSchema[]	a list of all the schema types that can be indexed

Returns

Return type: SimpleTreeIndex<TKey, TValue>

createSimpleTreeIndex

Creates a SimpleTreeIndex with a specified indexer.

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 createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue>(view: TreeView<TFieldSchema>, indexer: Map<TreeNodeSchema, string>, getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey): SimpleTreeIndex<TKey, TValue>;

Type Parameters

Parameter	Constraint	Description
TFieldSchema	ImplicitFieldSchema
TKey	TreeIndexKey
TValue

Parameters

Parameter	Type	Description
view	TreeView<TFieldSchema>	the view for the tree being indexed
indexer	Map<TreeNodeSchema, string>	a map from TreeNodeSchema to the field name that all nodes of the given schema should be keyed on
getValue	(nodes: TreeIndexNodes<TreeNode>) => TValue	given at least one TreeNode, returns an associated value
isKeyValid	(key: TreeIndexKey) => key is TKey	function for verifying the validity of the key retrieved based on the information given by the indexer

Returns

Return type: SimpleTreeIndex<TKey, TValue>

createSimpleTreeIndex

Creates a SimpleTreeIndex with a specified indexer.

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 createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue, TSchema extends TreeNodeSchema>(view: TreeView<TFieldSchema>, indexer: Map<TreeNodeSchema, string>, getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey, indexableSchema: readonly TSchema[]): SimpleTreeIndex<TKey, TValue>;

Type Parameters

Parameter	Constraint	Description
TFieldSchema	ImplicitFieldSchema
TKey	TreeIndexKey
TValue
TSchema	TreeNodeSchema

Parameters

Parameter	Type	Description
view	TreeView<TFieldSchema>	the view for the tree being indexed
indexer	Map<TreeNodeSchema, string>	a map from TreeNodeSchema to the field name that all nodes of the given schema should be keyed on
getValue	(nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue	given at least one TreeNode, returns an associated value
isKeyValid	(key: TreeIndexKey) => key is TKey	function for verifying the validity of the key retrieved based on the information given by the indexer
indexableSchema	readonly TSchema[]	a list of all the schema types that can be indexed

Returns

Return type: SimpleTreeIndex<TKey, TValue>

decodeSchemaCompatibilitySnapshot

Decodes a JSON-compatible schema into a simple schema.

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 decodeSchemaCompatibilitySnapshot(encodedSchema: JsonCompatibleReadOnly, validator?: FormatValidator): SimpleTreeSchema;

Parameters

Parameter	Modifiers	Type	Description
encodedSchema		JsonCompatibleReadOnly	The encoded schema to decode.
validator	optional	FormatValidator	The format validator to use to validate the encoded schema.

Returns

A decoded simple schema.

Return type: SimpleTreeSchema

Error Handling

Will throw a usage error if the encoded schema is not in the expected format.

encodeSchemaCompatibilitySnapshot

Encodes the compatibility impacting subset of simple schema (view or stored) into a serializable format.

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 encodeSchemaCompatibilitySnapshot(simpleSchema: SimpleTreeSchema): JsonCompatibleReadOnly;

Remarks

The JSON-compatible schema returned from this method is only intended for use in snapshots/comparisons of schemas. It is not possible to reconstruct a full schema (including metadata and persistedMetadata) from the encoded format.

Parameters

Parameter	Type	Description
simpleSchema	SimpleTreeSchema

Returns

A serializable representation of the schema.

Return type: JsonCompatibleReadOnly

enumFromStrings

Converts an array of distinct strings into a collection of schema which can be used like an enum style union.

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

export declare function enumFromStrings<TScope extends string, const Members extends readonly string[]>(factory: SchemaFactory<TScope>, members: Members): (<TValue extends Members[number]>(value: TValue) => TValue extends unknown ? TreeNode & {
    readonly value: TValue;
} : never) & { [Index in Extract<keyof Members, `${number}`> extends `${infer N extends number}` ? N : never as Members[Index]]: TreeNodeSchemaClass<ScopedSchemaName<TScope, Members[Index]>, NodeKind.Object, TreeNode & {
    readonly value: Members[Index];
}, Record<string, never>, true, Record<string, never>, undefined>; } & {
    readonly schema: UnionToTuple<Members[number] extends unknown ? { [Index in Extract<keyof Members, `${number}`> extends `${infer N extends number}` ? N : never as Members[Index]]: TreeNodeSchemaClass<ScopedSchemaName<TScope, Members[Index]>, NodeKind.Object, TreeNode & {
        readonly value: Members[Index];
    }, Record<string, never>, true, Record<string, never>, undefined>; }[Members[number]] : never>;
};

Type Parameters

Parameter	Constraint	Description
TScope	string
Members	readonly string[]

Remarks

The returned collection is also a function which can be used to convert strings into Unhydrated nodes in the union. Each node type has a .value getter which returns the associated string.

The produced nodes use the provided strings as their name, and don't store any data beyond that.

Example

const schemaFactory = new SchemaFactory("com.myApp");
const Mode = enumFromStrings(schemaFactory, ["Fun", "Cool"]);
type Mode = TreeNodeFromImplicitAllowedTypes<typeof Mode.schema>;
const nodeFromString: Mode = Mode("Fun");
const nodeFromSchema: Mode = new Mode.Fun();

// Schema nodes have a strongly typed `.value` property.
const nameFromNode: "Fun" | "Cool" = nodeFromSchema.value;

class Parent extends schemaFactory.object("Parent", { mode: Mode.schema }) {}

Parameters

Parameter	Type	Description
factory	SchemaFactory<TScope>
members	Members

Returns

Return type: (<TValue extends Members[number]>(value: TValue) => TValue extends unknown ? TreeNode & { readonly value: TValue; } : never) & { [Index in Extract<keyof Members, `${number}`> extends `${infer N extends number}` ? N : never as Members[Index]]: TreeNodeSchemaClass<ScopedSchemaName<TScope, Members[Index]>, NodeKind.Object, TreeNode & { readonly value: Members[Index]; }, Record<string, never>, true, Record<string, never>, undefined>; } & { readonly schema: UnionToTuple<Members[number] extends unknown ? { [Index in Extract<keyof Members, `${number}`> extends `${infer N extends number}` ? N : never as Members[Index]]: TreeNodeSchemaClass<ScopedSchemaName<TScope, Members[Index]>, NodeKind.Object, TreeNode & { readonly value: Members[Index]; }, Record<string, never>, true, Record<string, never>, undefined>; }[Members[number]] : never>; }

See Also

adaptEnum(factory, members) for a similar function that works on enums instead of arrays of strings.

eraseSchemaDetails

Type-erase details of a schema.

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 eraseSchemaDetails<TNode, ExtraSchemaProperties = unknown>(): <T extends ExtraSchemaProperties & TreeNodeSchema<string, NodeKind, TNode & TreeNode>>(schema: T) => ExtraSchemaProperties & TreeNodeSchema<T["identifier"], NodeKind, TNode & TreeNode & WithType<T["identifier"]>, never, false>;

Type Parameters

Parameter	Default	Description
TNode		The type to narrow the node to. Typically TreeNode intersected with the public interface for the component.
ExtraSchemaProperties	unknown	Properties of the schema (statics on the schema class) to retain in addition to the basic TreeNodeSchema. Typically includes at least one static factory method for creating nodes.

Remarks

This can be used to type erase the details of a schema including the node's type (such as its fields and APIs for modifying those fields). This is intended for use on component boundaries to support encapsulation of implementation details, including the exact schema.

This is best applied to a top level "component node" which wraps the actual component content (in a single required object node field) allowing more cases of schema evolution to be carried out as implementation details of the component.

Since this type-erases the schema details, the remaining API will need to provide ways to construct instances of the node and access its contents. Typically construction is done via static functions on the schema which can be included in ExtraSchemaProperties, and access to contents is done via properties of TNode (usually methods).

Example

const schema = new SchemaFactory("com.example");

interface SquareNode {
	readonly area: number;
}

interface SquareSchema {
	create(sideLength: number): Square;
}

class SquareInternal
	extends schema.object("Demo", { hidden: schema.number })
	implements SquareNode
{
	public get area(): number {
		return this.hidden * this.hidden;
	}

	public static create(sideLength: number): SquareInternal {
		return new SquareInternal({ hidden: sideLength });
	}
}

const Square = eraseSchemaDetails<Square, SquareSchema>()(SquareInternal);
type Square = SquareNode & TreeNode & WithType<"com.example.Demo">;

Returns

Return type: <T extends ExtraSchemaProperties & TreeNodeSchema<string, NodeKind, TNode & TreeNode>>(schema: T) => ExtraSchemaProperties & TreeNodeSchema<T["identifier"], NodeKind, TNode & TreeNode & WithType<T["identifier"]>, never, false>

eraseSchemaDetailsSubclassable

Like eraseSchemaDetails() but allows the returned schema to be subclassed.

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 eraseSchemaDetailsSubclassable<TNode, ExtraSchemaProperties = unknown>(): <T extends ExtraSchemaProperties & TreeNodeSchemaClass<string, NodeKind, TNode & TreeNode>>(schema: T) => ExtraSchemaProperties & TreeNodeSchemaClass<T["identifier"], NodeKind, TNode & TreeNode & WithType<T["identifier"]>, never, false>;

Type Parameters

Parameter	Default	Description
TNode
ExtraSchemaProperties	unknown

Example

const schema = new SchemaFactory("com.example");

interface SquareInterface {
	readonly area: number;
}

class SquareInternal
	extends schema.object("Demo", { size: schema.number })
	implements SquareInterface
{
	public get area(): number {
		return this.size * this.size;
	}
}

class Square extends eraseSchemaDetailsSubclassable<SquareInterface>()(SquareInternal) {
	public static create(sideLength: number): Square {
		return new (this as TreeNodeSchema as typeof SquareInternal)({ size: sideLength });
	}
}

const square = Square.create(10);
assert.equal(square.area, 100);

Returns

Return type: <T extends ExtraSchemaProperties & TreeNodeSchemaClass<string, NodeKind, TNode & TreeNode>>(schema: T) => ExtraSchemaProperties & TreeNodeSchemaClass<T["identifier"], NodeKind, TNode & TreeNode & WithType<T["identifier"]>, never, false>

evaluateLazySchema

Returns the schema referenced by the LazyItem.

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 evaluateLazySchema<T extends TreeNodeSchema>(value: LazyItem<T>): T;

Type Parameters

Parameter	Constraint	Description
T	TreeNodeSchema

Remarks

Caches results to handle LazyItems which compute their resulting schema.

Parameters

Parameter	Type	Description
value	LazyItem<T>

Returns

Return type: T

exportCompatibilitySchemaSnapshot

Returns a JSON compatible representation of the tree schema for snapshot compatibility checking.

Snapshots can be loaded by the same or newer package versions, but not necessarily older versions.

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 exportCompatibilitySchemaSnapshot(config: Pick<TreeViewConfiguration, "schema">): JsonCompatibleReadOnly;

Example

This example creates and persists a snapshot of a Point2D schema.

const schemaFactory = new SchemaFactory("test");
class Point2D extends schemaFactory.object("Point", {
	x: factory.number,
	y: factory.number,
}) {}
const viewSchema = new TreeViewConfiguration({ schema: Point2D });
const encodedSchema = JSON.stringify(exportCompatibilitySchemaSnapshot(viewSchema));
fs.writeFileSync("PointSchema.json", encodedSchema);

Parameters

Parameter	Type	Description
config	Pick<TreeViewConfiguration, "schema">	The schema to snapshot. Only the schema field of the TreeViewConfiguration is used.

Returns

The JSON representation of the schema.

Return type: JsonCompatibleReadOnly

See Also

importCompatibilitySchemaSnapshot(config) which loads these snapshots.

extractPersistedSchema

Dumps the "persisted" schema subset of the provided schema into a deterministic JSON-compatible, semi-human-readable format.

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 extractPersistedSchema(schema: ImplicitFieldSchema, minVersionForCollab: MinimumVersionForCollab, includeStaged: (upgrade: SchemaUpgrade) => boolean): JsonCompatible;

Remarks

This can be used to help inspect schema for debugging, and to save a snapshot of schema to help detect and review changes to an applications schema. This format is also compatible with schema, comparePersistedSchema(persisted, view, options) and persistedToSimpleSchema(persisted, options).

This only includes the "persisted" subset of schema information, which means the portion which gets included in documents. It thus uses "persisted" keys, see key.

If two schema have identical "persisted" schema, then they are considered equivalent.

See also comparePersistedSchema(persisted, view, options).

Example

An application could use this API to generate a schema.json file when it first releases, then test that the schema is sill compatible with documents from that version with a test like :

assert.deepEqual(extractPersistedSchema(MySchema, FluidClientVersion.v2_0), require("./schema.json"));

Parameters

Parameter	Type	Description
schema	ImplicitFieldSchema	The schema to dump.
minVersionForCollab	MinimumVersionForCollab	The oldest client version which can read the schema: impacts the format used.
includeStaged	(upgrade: SchemaUpgrade) => boolean	filter for selecting which staged allowed types to include in the output.

Returns

Return type: JsonCompatible

generateSchemaFromSimpleSchema

Create FieldSchema from a SimpleTreeSchema.

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 generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): TreeSchema;

Remarks

Only use this API if hand written schema (produced using SchemaFactory cannot be provided.

Using generated schema with schema aware APIs (designed to work with strongly typed schema) like TreeViewConfiguration will produce a poor TypeScript typing experience which is subject to change.

Editing through a view produced using this schema can easily violate invariants other users of the document might expect and must be done with great care.

This API bakes in some arbitrary policy choices for how to handle data that is not included in the SimpleTreeSchema API, for example the value of allowUnknownOptionalFields. If any particular choice is required for such cases, this API should not be used.

Parameters

Parameter	Type	Description
simple	SimpleTreeSchema

Returns

Return type: TreeSchema

getBranch

Get a BranchableTree from a ITree.

This API is deprecated and will be removed in a future release.

This API is superseded by TreeBranch, which should be used instead.

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): BranchableTree;

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: BranchableTree

getBranch

Get a BranchableTree from a TreeView.

This API is deprecated and will be removed in a future release.

This API is superseded by TreeBranch, which should be used instead.

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<T extends ImplicitFieldSchema | UnsafeUnknownSchema>(view: TreeViewAlpha<T>): BranchableTree;

Type Parameters

Parameter	Constraint	Description
T	ImplicitFieldSchema | UnsafeUnknownSchema

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	TreeViewAlpha<T>

Returns

Return type: BranchableTree

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: ImplicitAllowedTypes, options: Required<TreeSchemaEncodingOptions>): 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	ImplicitAllowedTypes
options	Required<TreeSchemaEncodingOptions>

Returns

Return type: JsonTreeSchema

getSimpleSchema

Copies data from ImplicitFieldSchema to create a SimpleTreeSchema out of new plain JavaScript objects, Sets and Maps.

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 getSimpleSchema(schema: ImplicitFieldSchema): SimpleTreeSchema<SchemaType.View>;

Remarks

See also TreeViewConfigurationAlpha which implements SimpleTreeSchema as a way to get a SimpleTreeSchema without copying the node and field schema and without losing as much type information.

Parameters

Parameter	Type	Description
schema	ImplicitFieldSchema

Returns

Return type: SimpleTreeSchema<SchemaType.View>

importCompatibilitySchemaSnapshot

Parse the format exported by exportCompatibilitySchemaSnapshot(config) into a schema.

Can load snapshots created by the same or older package versions, but not necessarily newer versions.

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 importCompatibilitySchemaSnapshot(config: JsonCompatibleReadOnly): TreeViewConfiguration;

Example

This example loads and parses a snapshot of a Point2D schema.

const oldViewSchema = importCompatibilitySchemaSnapshot(fs.readFileSync("PointSchema.json", "utf8"));

Parameters

Parameter	Type	Description
config	JsonCompatibleReadOnly	The JSON representation of the schema.

Returns

The schema. Only the schema field of the TreeViewConfiguration is populated.

Return type: TreeViewConfiguration

Error Handling

Will throw a usage error if the encoded schema is not in the expected format.

See Also

exportCompatibilitySchemaSnapshot(config) which creates these snapshots.

incrementalEncodingPolicyForAllowedTypes

This helper function incrementalEncodingPolicyForAllowedTypes(rootSchema) can be used to generate a callback function of type IncrementalEncodingPolicy. It determines if each AllowedTypes in a schema should be incrementally summarized. This callback can be passed as the value for shouldEncodeIncrementally parameter when creating the tree.

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 incrementalEncodingPolicyForAllowedTypes(rootSchema: TreeSchema): IncrementalEncodingPolicy;

Remarks

This only works for forest type ForestTypeOptimized and compression strategy CompressedIncremental.

Parameters

Parameter	Type	Description
rootSchema	TreeSchema	The schema for the root of the tree.

Returns

A callback function of type IncrementalEncodingPolicy which determines if allowed types should be incrementally summarized based on whether they have opted in via the incrementalSummaryHint metadata.

Return type: IncrementalEncodingPolicy

independentInitializedView

Create an initialized TreeView that is not tied to any ITree instance.

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 independentInitializedView<const TSchema extends ImplicitFieldSchema>(config: TreeViewConfiguration<TSchema>, options: ForestOptions & ICodecOptions, content: ViewContent): TreeViewAlpha<TSchema>;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Remarks

Such a view can never experience collaboration or be persisted to to a Fluid Container.

This can be useful for testing, as well as use-cases like working on local files instead of documents stored in some Fluid service.

Parameters

Parameter	Type	Description
config	TreeViewConfiguration<TSchema>
options	ForestOptions & ICodecOptions
content	ViewContent

Returns

Return type: TreeViewAlpha<TSchema>

independentView

Create an uninitialized TreeView that is not tied to any ITree instance.

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 independentView<const TSchema extends ImplicitFieldSchema>(config: TreeViewConfiguration<TSchema>, options?: ForestOptions & {
    idCompressor?: IIdCompressor | undefined;
}): TreeViewAlpha<TSchema>;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Remarks

Such a view can never experience collaboration or be persisted to to a Fluid Container.

This can be useful for testing, as well as use-cases like working on local files instead of documents stored in some Fluid service.

Parameters

Parameter	Modifiers	Type	Description
config		TreeViewConfiguration<TSchema>
options	optional	ForestOptions & { idCompressor?: IIdCompressor | undefined; }

Returns

Return type: TreeViewAlpha<TSchema>

normalizeAllowedTypes

Normalizes an ImplicitAllowedTypes to an AllowedTypesFull.

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 normalizeAllowedTypes(types: ImplicitAllowedTypes): AllowedTypesFull;

Parameters

Parameter	Type	Description
types	ImplicitAllowedTypes

Returns

Return type: AllowedTypesFull

persistedToSimpleSchema

A way to parse schema in the persisted format from extractPersistedSchema(schema, minVersionForCollab, includeStaged).

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 persistedToSimpleSchema(persisted: JsonCompatible, options: ICodecOptions): SimpleTreeSchema;

Remarks

This behaves identically to exportSimpleSchema(), except that it gets the schema from the caller instead of from an existing tree.

This can be useful for inspecting the contents of persisted schema, such as those generated by extractPersistedSchema(schema, minVersionForCollab, includeStaged) for use in testing. Since that data format is otherwise unspecified, this provides a way to inspect its contents with documented semantics.

Parameters

Parameter	Type	Description
persisted	JsonCompatible
options	ICodecOptions

Returns

Return type: SimpleTreeSchema

replaceConciseTreeHandles

Clones tree, replacing any handles.

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 replaceConciseTreeHandles<T>(tree: ConciseTree, replacer: HandleConverter<T>): ConciseTree<T>;

Type Parameters

Parameter	Description
T

Remarks

A strongly typed version of replaceHandles(tree, replacer).

Parameters

Parameter	Type	Description
tree	ConciseTree
replacer	HandleConverter<T>

Returns

Return type: ConciseTree<T>

replaceHandles

Clones tree, replacing any handles.

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 replaceHandles<T>(tree: unknown, replacer: HandleConverter<T>): unknown;

Type Parameters

Parameter	Description
T

Remarks

This can be useful converting data containing handles to JSON compatible formats, or just asserting that data does not contain handles.

Reversing this replacement depends on how the replacer encodes handles, and can often be impossible if the replacer does not have all the necessary context to restore the handles (e.g. if the handles are something insufficiently descriptive, if data referenced by the handle got garbage collected, if the encoded form of the handle can't be differentiated from other data, or the replacer doesn't have access to the correct Fluid container to to restore them from).

Code attempting to reverse this replacement may want to use cloneWithReplacements(root, rootKey, replacer).

Parameters

Parameter	Type	Description
tree	unknown
replacer	HandleConverter<T>

Returns

Return type: unknown

replaceVerboseTreeHandles

Clones tree, replacing any handles.

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 replaceVerboseTreeHandles<T>(tree: VerboseTree, replacer: HandleConverter<T>): VerboseTree<T>;

Type Parameters

Parameter	Description
T

Remarks

A strongly types version of replaceHandles(tree, replacer).

Parameters

Parameter	Type	Description
tree	VerboseTree
replacer	HandleConverter<T>

Returns

Return type: VerboseTree<T>

singletonSchema

Create a schema for a node with no state.

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

export declare function singletonSchema<TScope extends string, TName extends string | number>(factory: SchemaFactory<TScope, TName>, name: TName): TreeNodeSchemaClass<ScopedSchemaName<TScope, TName>, NodeKind.Object, TreeNode & {
    readonly value: TName;
}, Record<string, never>, true, Record<string, never>, undefined>;

Type Parameters

Parameter	Constraint	Description
TScope	string
TName	string | number

Remarks

This is commonly used in unions when the only information needed is which kind of node the value is. Enums are a common example of this pattern.

Parameters

Parameter	Type	Description
factory	SchemaFactory<TScope, TName>
name	TName

Returns

Return type: TreeNodeSchemaClass<ScopedSchemaName<TScope, TName>, NodeKind.Object, TreeNode & { readonly value: TName; }, Record<string, never>, true, Record<string, never>, undefined>

See Also

adaptEnum(factory, members)

trackDirtyNodes

Registers a visitor on the view's forest that tracks which nodes are dirty.

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 trackDirtyNodes(view: TreeViewAlpha<ImplicitFieldSchema>, dirty: DirtyTreeMap): () => void;

Example

const dirty = new Map<TreeNode, DirtyTreeStatus>();
const stopTracking = trackDirtyNodes(view, dirty);
// ... make changes to the view ...
console.log(`The root of the tree is ${dirty.get(view.root) ?? "unchanged"}`);
stopTracking();

Parameters

Parameter	Type	Description
view	TreeViewAlpha<ImplicitFieldSchema>	The view to track dirty nodes on
dirty	DirtyTreeMap	A map that will be updated over time to reflect the status of nodes as they change. Nodes that have not changed will not be inserted/updated in the map.

Returns

a cleanup function that should be called when the tracking is no longer needed.

Return type: () => void

Variable Details

ArrayNodeSchema

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

ArrayNodeSchema: {
    readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is ArrayNodeSchema;
}

Type: { readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is ArrayNodeSchema; }

contentSchemaSymbol

The intended type of insertable content that is to become a TreeNode.

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

contentSchemaSymbol: unique symbol

Type: unique symbol

Remarks

Use the type-safe tagContentSchema(schema, content) function to tag insertable content with this symbol.

If a property with this symbol key is present on an object that is inserted into the tree, the tree will use the schema identifier specified by the value of this property when creating the node. This is particularly useful for specifying the intended schema of untyped content when it would otherwise be ambiguous.

Example

const sf = new SchemaFactory("example");
class Dog extends sf.object("Dog", { name: sf.string() }) {}
class Cat extends sf.object("Cat", { name: sf.string() }) {}
class Root extends sf.object("Root", { pet: [Dog, Cat] }) {}
// ...
view.root.pet = { name: "Max" }; // Error: ambiguous schema - is it a Dog or a Cat?
view.root.pet = { name: "Max", [contentSchemaSymbol]: "example.Dog" }; // No error - it's a Dog.

FluidClientVersion

Versions of Fluid Framework client packages.

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

FluidClientVersion: {
    readonly v2_0: "2.0.0";
    readonly v2_43: "2.43.0";
    readonly v2_52: "2.52.0";
    readonly v2_73: "2.73.0";
    readonly v2_74: "2.74.0";
}

Type: { readonly v2_0: "2.0.0"; readonly v2_43: "2.43.0"; readonly v2_52: "2.52.0"; readonly v2_73: "2.73.0"; readonly v2_74: "2.74.0"; }

Remarks

Used to express compatibility requirements by indicating the oldest version with which compatibility must be maintained.

When no compatibility-impacting change is made in a given version, the value associated with its enum entry may point to the older version which it's fully compatible with. Note that this can change if a future version of the framework introduces an option to use something which is only supported at a particular version. In which case, the values of the enum may shift, but the semantics of keys in this enum will not change.

Do not depend on the value of this enums's entries: only depend on the keys (enum members) themselves.

Some release may also be omitted if there is currently no need to express that specific version. If the need arises, they might be added in the future.

ForestTypeExpensiveDebug

Slow implementation of forest intended only for debugging.

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

ForestTypeExpensiveDebug: ForestType

Type: ForestType

Remarks

Includes validation with scales poorly. May be asymptotically slower than ForestTypeReference, and may perform very badly with larger data sizes.

ForestTypeOptimized

Optimized implementation of forest.

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

ForestTypeOptimized: ForestType

Type: ForestType

Remarks

A complex optimized forest implementation, which has minimal validation and debuggability to optimize for performance. Uses an internal representation optimized for size designed to scale to larger datasets with reduced overhead.

ForestTypeReference

Reference implementation of forest.

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

ForestTypeReference: ForestType

Type: ForestType

Remarks

A simple implementation with minimal complexity and moderate debuggability, validation and performance.

FormatValidatorBasic

A FormatValidator implementation which uses TypeBox's JSON schema validator.

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

FormatValidatorBasic: import("../codec/codec.js").FormatValidator

Type: import("../codec/codec.js").FormatValidator

FormatValidatorNoOp

A FormatValidator which does no validation.

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

FormatValidatorNoOp: FormatValidator

Type: FormatValidator

incrementalSummaryHint

A symbol when present in the metadata's custom property as true, opts in the allowed types to incremental summary optimization. These allowed types will be optimized during summary such that if they don't change across summaries, they will not be encoded and their content will not be included in the summary that is uploaded to the service.

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

incrementalSummaryHint: unique symbol

Type: unique symbol

Remarks

See incrementalEncodingPolicyForAllowedTypes(rootSchema) for more details.

Use types to add this metadata to allowed types in a schema.

Example

const sf = new SchemaFactoryAlpha("IncrementalSummarization");
class Foo extends sf.objectAlpha("foo", {
  bar: sf.types([{ type: sf.string, metadata: {} }], {
    custom: { [incrementalSummaryHint]: true },
  }),
}) {}

MapNodeSchema

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

MapNodeSchema: {
    readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is MapNodeSchema;
}

Type: { readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is MapNodeSchema; }

ObjectNodeSchema

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

ObjectNodeSchema: {
    readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is ObjectNodeSchema<string, RestrictiveStringRecord<ImplicitFieldSchema>, boolean, unknown>;
}

Type: { readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is ObjectNodeSchema<string, RestrictiveStringRecord<ImplicitFieldSchema>, boolean, unknown>; }

RecordNodeSchema

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

RecordNodeSchema: {
    readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is RecordNodeSchema<string, ImplicitAllowedTypes, true, unknown>;
}

Type: { readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is RecordNodeSchema<string, ImplicitAllowedTypes, true, unknown>; }

rollback

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

Signature

rollback: unique symbol

Type: unique symbol

SchemaFactory_base

Base class for SchemaFactory, exposes SchemaStatics as both static properties and member properties.

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

SchemaFactory_base: SchemaStatics & (new () => SchemaStatics)

Type: SchemaStatics & (new () => SchemaStatics)

Remarks

Do not use this directly, use SchemaFactory instead.

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>

SharedTreeAttributes

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

SharedTreeAttributes: IChannelAttributes

Type: IChannelAttributes

SharedTreeFactoryType

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

SharedTreeFactoryType = "https://graph.microsoft.com/types/tree"

Tree

The Tree singleton which holds various functions for interacting with TreeNodes.

Signature

Tree: Tree

Type: Tree

TreeAlpha

Extensions to Tree and TreeBeta which are not yet stable.

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

TreeAlpha: TreeAlpha

Type: TreeAlpha

See Also

TreeAlpha.

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

TreeBeta: TreeBeta

Type: TreeBeta

See Also

TreeBeta.

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.

UnsafeUnknownSchema

A special type which can be provided to some APIs as the schema type parameter when schema cannot easily be provided at compile time and an unsafe (instead of disabled) editing API is desired.

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

UnsafeUnknownSchema: unique symbol

Type: unique symbol

Remarks

When used, this means the TypeScript typing should err on the side of completeness (allow all inputs that could be valid). This introduces the risk that out-of-schema data could be allowed at compile time, and only error at runtime.