@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.
ArrayNodeCustomizableSchemaAlpha	System	sealed	A Schema for customizable TreeArrayNodes with additional alpha APIs.
ArrayNodeCustomizableSchemaUnsafe	System	sealed	Unenforced version of ArrayNodeCustomizableSchemas.
ArrayNodeInsertOp	Alpha	sealed	An "insert" op in an ArrayNodeDeltaOp sequence. Represents elements added to the array. Read the new element values from the current tree at the positions described by this op.
ArrayNodePojoEmulationSchema	System	sealed	A schema for POJO emulation mode TreeArrayNodes.
ArrayNodeRemoveOp	Alpha	sealed	A "remove" op in an ArrayNodeDeltaOp sequence. Represents elements removed from the array.
ArrayNodeRetainOp	Alpha	sealed	A "retain" op in an ArrayNodeDeltaOp sequence. Represents elements that were neither inserted into nor removed from the array.
ArrayNodeTreeChangedRetainOp	Alpha	sealed	A "retain" op in an ArrayNodeTreeChangedDeltaOp sequence, used in NodeChangedDataTreeDelta payloads delivered to treeChanged on array nodes. Extends ArrayNodeRetainOp with a subtreeChanged flag that indicates whether any descendant of the retained element changed.
ArrayPlaceAnchor	Alpha	sealed	A location in a TreeArrayNode.
CodecWriteOptions	Alpha		Options relating to encoding of persisted data.
CodecWriteOptionsBeta	Beta		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.
IndependentViewOptions	Alpha		independentView(config, options) options.
IndependentViewTelemetryOptions	Alpha		Options for supplying a telemetry logger to an independent tree view.
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.
ITreeViewConfigurationAlpha	Alpha		Property-bag configuration for TreeViewConfigurationAlpha 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.
LabelTree	Alpha	sealed	A tree representing the nesting structure of transaction labels.
LeafSchema	System	sealed	A TreeNodeSchema for a TreeLeafValue.
LocalChangeMetadata	Alpha	sealed	Information about a change that has been applied by the local client.
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 TreeMapNodeAlphas.
MapNodeCustomizableSchemaUnsafe	System	sealed	Unenforced version of MapNodeCustomizableSchemas.
MapNodePojoEmulationSchema	System	sealed	A schema for POJO emulation mode TreeMapNodeAlphas.
NoChangeConstraint	Alpha		A constraint which requires that, for this transaction to apply, the document must be in the same state immediately before the transaction is applied as it was before the transaction was authored. When used as a revert precondition it requires that, for the revert to apply, the document must be in the same state immediately before the revert is applied as it was after the transaction was applied.
NodeChangedData	Beta	sealed	Data included for nodeChanged.
NodeChangedDataDelta	Alpha	sealed	Data carried by the nodeChanged event for array nodes.
NodeChangedDataProperties	Alpha	sealed	Data included for nodeChanged when the node is an object, map, or record node.
NodeChangedDataTreeDelta	Alpha	sealed	Data carried by the treeChanged event for array nodes.
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.
RemoteChangeMetadata	Alpha	sealed	Information about a change that has been applied by a remote client.
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.
RunTransactionParamsAlpha	Alpha		The parameters for the RunTransaction API, extended with alpha-only constraint options.
RunTransactionParamsBeta	Beta		The parameters for the RunTransaction API.
SchemaCompatibilityStatus		sealed	Information about a view schema's compatibility with the document's stored schema.
SchemaStatics	System	sealed	Stateless APIs exposed via SchemaFactory as both instance properties and as statics.
SchemaStaticsAlpha	System	sealed	Stateless APIs exposed via SchemaFactoryBeta 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.
SharedTreeOptionsBeta	Beta		Configuration options for SharedTree.
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.
SnapshotFileSystem	Beta		The file system methods required by snapshotSchemaCompatibility(options).
SnapshotSchemaCompatibilityOptions	Beta		The options for snapshotSchemaCompatibility(options).
StagedSchemaUpgradePolicy	Alpha		Policy controlling which staged schema upgrades are included when generating stored schema from a view schema.
StagedSchemaUpgradePolicyFactory	Alpha	sealed	Provides factory methods for creating StagedSchemaUpgradePolicy instances.
TransactionPostProcessor	System	sealed	A type-erased function that post-processes the change produced when a transaction is committed.
TransactionResultFailed	Beta	sealed	The result of a transaction that was rolled back.
TransactionResultSuccess	Beta	sealed	The result of a transaction that completed successfully.
Tree		sealed	Provides various functions for interacting with TreeNodes.
TreeAlpha	Alpha	sealed	Extensions to Tree and TreeBeta which are not yet stable.
TreeArrayNode		sealed	A TreeNode which implements 'readonly T[]' and the array mutation APIs.
TreeArrayNodeAlpha	Alpha	sealed	TreeArrayNode with additional alpha APIs.
TreeBeta	Beta	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.
TreeChangeEvents		sealed	A collection of events that can be emitted by a TreeNode.
TreeChangeEventsAlpha	Alpha	sealed	Extension of TreeChangeEvents with a richer nodeChanged event and a delta-carrying treeChanged event for array nodes.
TreeChangeEventsBeta	Beta	sealed	Extensions to TreeChangeEvents which are not yet stable.
TreeContextAlpha	Alpha		Provides additional APIs that may be used to interact with a tree node or a tree node's SharedTree.
TreeEncodingOptions	Beta		Options for how to interpret or encode a tree when schema information is available.
TreeIdentifierUtils	Alpha	sealed	A utility interface for manipulating node identifiers.
TreeIndex	Beta	sealed	An index allows lookup content from a tree using keys.
TreeMapNode		sealed	A map of string keys to tree objects.
TreeMapNodeAlpha	Alpha	sealed	TreeMapNode with FluidReadonlyMap-based iteration.
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.
WithValue	Beta		Contains a value returned from a transaction.

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.
ArrayNodeDeltaOp	Alpha	sealed	A single operation in an array node change delta. Used to efficiently sync an external representation of an array (e.g. a text editor or virtual list) with tree changes without needing to snapshot the old state or diff the entire array. Each op describes a contiguous run of positions in the array before the change. For inserts, read the new element values from the current tree at those positions.
ArrayNodeSchema	Alpha		A schema for TreeArrayNodes.
ArrayNodeTreeChangedDeltaOp	Alpha		A single operation in an array-node delta delivered by treeChanged. Extends ArrayNodeDeltaOp: retain ops carry a subtreeChanged flag indicating whether any descendant of the retained element changed.
ChangeMetadata	Alpha	sealed	Information about a local or remote change that has been applied.
CodecName	Alpha		A unique name given to this codec family.
ConciseTree	Beta		Concise encoding of a TreeNode or TreeLeafValue.
CreateIndependentTreeAlphaOptions	Alpha		createIndependentTreeAlpha(options) options.
DirtyTreeStatus	Alpha		The status of a node in a that has been tracked for changes.
ErasedNode	Alpha		The type of an erased schema's node.
ErasedSchema	Alpha		The type of an erased schema.
ErasedSchemaSubclassable	Alpha		The type of a subclassable erased schema.
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.
FieldHasDefaultAlpha	System		Type utility for determining if an implicit field schema is known to have a default value. Supports alpha field schemas with explicit default providers.
FieldHasDefaultAlphaUnsafe	System	sealed	Unenforced version of FieldHasDefaultAlpha.
FixRecursiveArraySchema	Beta		Workaround for fixing errors resulting from an issue with recursive ArrayNode schema exports.
FormatVersion	Alpha		A version stamp for encoded data.
HandleConverter	Alpha		Options for how to transcode handles.
IdentifierIndex	Beta		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.
InsertableObjectFromSchemaRecordAlpha	System		Alpha version of InsertableObjectFromSchemaRecord that supports field defaults.
InsertableObjectFromSchemaRecordAlphaUnsafe	System		Unenforced version of InsertableObjectFromSchemaRecordAlpha.
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 TreeMapNodeAlphas.
NodeChangedDataAlpha	Alpha		The data passed to nodeChanged and, for array nodes, to treeChanged.
NodeFromSchema			Takes in TreeNodeSchema[] and returns a TypedNode union.
NodeProvider	Alpha	sealed	A provider for values in tree nodes.
NumberKeys	System		Extracts the keys of T which are numbers.
ObjectFromSchemaRecord	System		Generates the properties for an ObjectNode from its field schema object.
ObjectNodeSchemaWorkaround	Alpha	sealed	ObjectNodeSchema with a workaround to avoid a specific known TypeScript issue which causes it to not be assignable to itself in some cases.
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.
SimpleNodeSchema	Alpha		A simple, shallow representation of a schema for a node.
TransactionCallbackStatusAlpha	Alpha		TransactionCallbackStatusBeta extended with alpha-only constraint options.
TransactionCallbackStatusBeta	Beta		Contains a value and status returned from a user-supplied transaction callback.
TransactionConstraint			A requirement for a SharedTree transaction to succeed.
TransactionConstraintAlpha	Alpha	sealed	Type for alpha version constraints
TransactionLabels	Alpha	sealed	A set of transaction labels with an optional structural tree.
TransactionValueResult	Beta	sealed	The result of the RunTransaction API.
TransactionVoidResult	Beta	sealed	The result of the RunTransaction API. This is the same as TransactionValueResult but with the value field omitted. This is useful when the transaction callback doesn't need to return a value.
TreeFieldFromImplicitField			Converts an ImplicitFieldSchema to a property type suitable for reading a field with this that schema.
TreeIndexKey	Beta		Value that may be used as keys in a TreeIndex.
TreeIndexNodes	Beta		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.
VoidTransactionCallbackStatusAlpha	Alpha		The result of a transaction that doesn't return a value.
VoidTransactionCallbackStatusBeta	Beta		The result of a transaction that doesn't return a value.

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 schemas 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.
asAlpha(node)	Alpha	TreeArrayNodeAlpha<TAllowedTypes>	Retrieve the alpha API for a TreeArrayNode.
asAlpha(node)	Alpha	TreeMapNodeAlpha<TAllowedTypes>	Retrieve the alpha API for a TreeMapNode.
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.
createArrayInsertionAnchor(node, currentIndex)	Alpha	ArrayPlaceAnchor	Create an ArrayPlaceAnchor tracking an insertion point in the array which is currently at the provided index.
createIdentifierIndex(view)	Beta	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.
createTreeIndex(view, indexer, getValue, isKeyValid)	Beta	TreeIndex<TKey, TValue>	Creates a TreeIndex with a specified indexer.
createTreeIndex(view, indexer, getValue, isKeyValid, indexableSchema)	Beta	TreeIndex<TKey, TValue>	Creates a TreeIndex with a specified indexer.
createTreeIndex(view, indexer, getValue, isKeyValid)	Beta	TreeIndex<TKey, TValue>	Creates a TreeIndex with a specified indexer.
createTreeIndex(view, indexer, getValue, isKeyValid, indexableSchema)	Beta	TreeIndex<TKey, TValue>	Creates a TreeIndex 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 schemas 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.
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.
snapshotSchemaCompatibility(options)	Beta	void	Check currentViewSchema for compatibility with a collection of historical schema snapshots stored in snapshotDirectory.
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"; readonly v2_80: "2.80.0"; }	Versions of Fluid Framework client packages, usable as a MinimumVersionForCollab.
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; }
minimize	Deprecated, Alpha	readonly	TransactionPostProcessor	A post-processor that "minimizes" the change produced when a transaction is committed, so that the resulting squashed change contains no extraneous information.
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
StagedSchemaUpgradePolicy	Alpha	readonly	StagedSchemaUpgradePolicyFactory	Provides factory methods for creating StagedSchemaUpgradePolicy instances.
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
Component	Alpha	Utilities for composing application "components" which contribute to a shared configuration.
ExtensibleUnionNode	Beta	Utilities for creating extensible unions using a node.
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	Beta	Contains types and factories for creating schema to represent dynamic tabular data.
TextAsTree	Alpha	A collection of text related types, schema and utilities for working with text beyond the basic string.

Function Details

adaptEnum

Converts an enum into a collection of schemas 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 schemas.

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>

asAlpha

Retrieve the alpha API for a TreeArrayNode.

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<TAllowedTypes extends ImplicitAllowedTypes>(node: TreeArrayNode<TAllowedTypes>): TreeArrayNodeAlpha<TAllowedTypes>;

Type Parameters

Parameter	Constraint	Description
TAllowedTypes	ImplicitAllowedTypes

Parameters

Parameter	Type	Description
node	TreeArrayNode<TAllowedTypes>

Returns

Return type: TreeArrayNodeAlpha<TAllowedTypes>

asAlpha

Retrieve the alpha API for a TreeMapNode.

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<TAllowedTypes extends ImplicitAllowedTypes>(node: TreeMapNode<TAllowedTypes>): TreeMapNodeAlpha<TAllowedTypes>;

Type Parameters

Parameter	Constraint	Description
TAllowedTypes	ImplicitAllowedTypes

Parameters

Parameter	Type	Description
node	TreeMapNode<TAllowedTypes>

Returns

Return type: TreeMapNodeAlpha<TAllowedTypes>

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>

createArrayInsertionAnchor

Create an ArrayPlaceAnchor tracking an insertion point in the array which is currently at the provided index.

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 createArrayInsertionAnchor(node: TreeArrayNode, currentIndex: number): ArrayPlaceAnchor;

Remarks

This anchor will track the logical position in the array across changes. As long as the subsection of the array surrounding the anchor point is not edited, this anchor will move with them, keeping its relative position to those children fixed. How exactly it behaves when the adjacent portion of the array is modified is subject to change, but this will always report a valid index to insert content at (which can be the index after the last item in the array).

This is intended to track a location that might be used for an insertion point (for example in a text editor): future changes to its details should make it behave better for such uses.

The current implementation is known to behave particularly poorly if the child which was at the original anchor point's index is removed (jumps to the end of the array): this behavior is subject to change.

Parameters

Parameter	Type	Description
node	TreeArrayNode	The array node to anchor into.
currentIndex	number	The current index of the place to track.

Returns

Return type: ArrayPlaceAnchor

createIdentifierIndex

Creates an IdentifierIndex for a given 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 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?: CreateIndependentTreeAlphaOptions): ViewableTree & Pick<ITreeAlpha, "exportVerbose" | "exportSimpleSchema">;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Parameters

Parameter	Modifiers	Type	Description
options	optional	CreateIndependentTreeAlphaOptions	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

createTreeIndex

Creates a TreeIndex with a specified indexer.

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 createTreeIndex<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): TreeIndex<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: TreeIndex<TKey, TValue>

createTreeIndex

Creates a TreeIndex with a specified indexer.

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 createTreeIndex<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[]): TreeIndex<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: TreeIndex<TKey, TValue>

createTreeIndex

Creates a TreeIndex with a specified indexer.

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 createTreeIndex<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): TreeIndex<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: TreeIndex<TKey, TValue>

createTreeIndex

Creates a TreeIndex with a specified indexer.

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 createTreeIndex<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[]): TreeIndex<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: TreeIndex<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 schemas 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

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 & IndependentViewTelemetryOptions, 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 & IndependentViewTelemetryOptions
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?: IndependentViewOptions): 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	IndependentViewOptions

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)

snapshotSchemaCompatibility

Check currentViewSchema for compatibility with a collection of historical schema snapshots stored in snapshotDirectory.

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 snapshotSchemaCompatibility(options: SnapshotSchemaCompatibilityOptions): void;

Remarks

This is intended for use in snapshot-based schema compatibility tests. Every SharedTree-based component or application with a schema is recommended to use this to verify schema compatibility across versions.

Schema snapshots should be added to snapshotDirectory using this function in "update" mode whenever the schema changes in a compatibility impacting way (or when snapshotUnchangedVersions is true and a new version about to be released is getting prepared for release (and thus version changed)).

This will throw an exception if any snapshotted schema would result in documents that cannot be viewed (after using upgradeSchema()), or if any schema with a version greater than or equal to minVersionForCollaboration cannot view documents created with the currentViewSchema. See compatibility for more information.

Proper use of this utility should do a good job at detecting schema compatibility issues, however it currently does not do a good job of explaining exactly what change to the schema is causing the compatibility issues. This is a known limitation that will be improved in future releases. These improvements, as well as other changes, may change the exact messages produced by this function in the error cases: no stability of these messages should be assumed.

Unlike some other snapshot based testing tools, this stores more than just the current snapshot: historical snapshots are retained as well. Retention of these additional historical snapshots, whose content can't be regenerated from the current schema, is necessary to properly test compatibility across versions. Since there is content in the snapshots which cannot be regenerated, tools which assume all snapshotted content can be regenerated cannot be used here. This means that tools like Jest's built in snapshot testing are not suitable for this purpose. These snapshots behave partly like test data, and partly like snapshots. Typically the easiest way to manage this is to place snapshotDirectory inside a directory appropriate for test data, and use node to provide the filesystem access via fileSystem.

For now, locating what change broke compatibility is likely best discovered by making small schema changes one at a time and updating the snapshot and reviewing the diffs. Details for what kinds of changes are breaking and in which ways can be found in the documentation for compatibility and schema-evolution.

This utility does not enforce anything with respect to API compatibility, or special semantics for major, minor, or patch versions. Libraries which export schema for use by others will need to take special care to ensure the stability contract they offer their users aligns which what is validated by this utility.

This utility only tests compatibility of the historical snapshots against the current schema; it does not test them against each-other. Generally any historical schemas should have been tested against the ones before them at the time they were current. If for some reason a version of a schema made it into production that was not compatible with a previous version, that can still be represented here (but may require manually generating a snapshot for that version) and this will still allow testing that all historical version can be upgraded to the current one. If a sufficiently incompatible historical schemas were used in production, it may be impossible to make a single schema which can accommodate all of them: this utility can be used to confirm that is the case, as well as to avoid the problem in the first place by testing schema before each one is deployed.

Usage

Example 1

Mocha test which validates the current config can collaborate with all historical version back to 2.0.0, and load and update any versions older than that.

it("schema compatibility", () => {
	snapshotSchemaCompatibility({
		version: pkgVersion,
		schema: config,
		fileSystem: { ...fs, ...path },
		minVersionForCollaboration: "2.0.0",
		mode: process.argv.includes("--snapshot") ? "update" : "test",
		snapshotDirectory,
	});
});

Example 2

Complete Mocha test file

import fs from "node:fs";
import path from "node:path";

import { snapshotSchemaCompatibility } from "@fluidframework/tree/beta";

// The TreeViewConfiguration the application uses, which contains the application's schema.
import { treeViewConfiguration } from "./schema.js";
// The next version of the application which will be released.
import { packageVersion } from "./version.js";

// Provide some way to run the check in "update" mode when updating snapshots is intended.
const regenerateSnapshots = process.argv.includes("--snapshot");

// Setup the actual test. In this case using Mocha syntax.
describe("schema", () => {
	it("schema compatibility", () => {
		// Select a path to save the snapshots in.
		// This will depend on how your application organizes its test data.
		const snapshotDirectory = path.join(
			import.meta.dirname,
			"../../../src/test/schema-snapshots",
		);
		snapshotSchemaCompatibility({
			schema: config,
			fileSystem: { ...fs, ...path },
			version: pkgVersion,
			minVersionForCollaboration: "2.0.0",
			mode: process.argv.includes("--snapshot") ? "update" : "assert",
			snapshotDirectory,
		});
	});
});

Parameters

Parameter	Type	Description
options	SnapshotSchemaCompatibilityOptions

Error Handling

Throws errors if the input version strings (including those in snapshot file names) are not valid semver versions when using default semver version comparison.

Throws errors if the input version strings (including those in snapshot file names) are not ordered as expected (current being the highest, and minVersionForCollaboration corresponding to the current version or a lower snapshotted version).

In test mode, throws an error if there is not an up to date snapshot for the current version.

Throws an error if any snapshotted schema cannot be upgraded to the current schema.

Throws an error if any snapshotted schema with a version greater than or equal to minVersionForCollaboration cannot view documents created with the current schema.

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, usable as a MinimumVersionForCollab.

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";
    readonly v2_80: "2.80.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"; readonly v2_80: "2.80.0"; }

Remarks

Versions with no notable impact may be omitted, and added later if needed.

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; }

minimize

A post-processor that "minimizes" the change produced when a transaction is committed, so that the resulting squashed change contains no extraneous information.

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

Note: minimization is not yet implemented. For now this is a no-op that leaves the squashed change unchanged, so supplying it currently has no observable effect beyond reserving the behavior. A real implementation will be provided in a future change.

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

minimize: TransactionPostProcessor

Type: TransactionPostProcessor

Remarks

Supply this via postProcessor when running a transaction. "Extraneous information" includes, for example, data for nodes that were both created and removed within the transaction, or changes whose effects cancel out to nothing. Minimizing the change reduces the size of the edit that is submitted to (and stored by) the service without altering the observable effect of the transaction.

The current implementation is limited and is unable to guarantee that the resulting change is fully minimized if multiple distinct edit groups are present in the transaction. Transaction edit groups are divided by schema changes, so this limitation is only relevant for transactions that contain one or more schema changes and content edits on both sides. In such cases, the implementation will throw a usage error: "At most one edit group can be minimized..."

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"

StagedSchemaUpgradePolicy

Provides factory methods for creating StagedSchemaUpgradePolicy instances.

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

StagedSchemaUpgradePolicy: StagedSchemaUpgradePolicyFactory

Type: StagedSchemaUpgradePolicyFactory

Remarks

Use the properties and methods on this object to obtain staged-schema generation options for different scenarios:

• restrictive — no staged upgrades (default)

• permissive — all staged upgrades enabled

• enabledStagedUpgrades(upgrades) — only specific upgrades enabled

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.