Skip to main content

@fluidframework/tree Package

Interfaces​

Interface Alerts Modifiers Description
ArrayNodeCustomizableSchema System sealed A schema for customizable TreeArrayNodes.
ArrayNodeCustomizableSchemaUnsafe System sealed Unenforced version of ArrayNodeCustomizableSchemas.
ArrayNodePojoEmulationSchema System sealed A schema for POJO emulation mode TreeArrayNodes.
BranchableTree Alpha sealed A "version control"-style branch of a SharedTree.
CommitMetadata sealed Information about a commit that has been applied.
FieldProps Additional information to provide to a FieldSchema.
FieldSchemaAlphaUnsafe System sealed Unenforced version of FieldSchemaAlpha.
FieldSchemaMetadata sealed Metadata associated with a FieldSchema.
ForestOptions Alpha Configuration options for SharedTree's internal tree storage.
ForestType Alpha sealed Used to distinguish between different forest types.
ICodecOptions Alpha Options relating to handling of persisted data.
InternalTreeNode sealed A node type internal to @fluidframework/tree.
ITree sealed Channel for a Fluid Tree DDS.
ITreeAlpha Alpha sealed ITree extended with some alpha APIs.
ITreeConfigurationOptions Options when constructing a tree view.
ITreeViewConfiguration Property-bag configuration for TreeViewConfiguration construction.
JsonArrayNodeSchema Alpha sealed JSON Schema for an array node.
JsonLeafNodeSchema Alpha sealed JSON Schema for a leaf node.
JsonMapNodeSchema Alpha sealed JSON Schema for a map node.
JsonNodeSchemaBase Alpha sealed Base interface for node schemas represented in JSON Schema format.
JsonObjectNodeSchema Alpha sealed JSON Schema for an object node.
JsonSchemaRef Alpha sealed Type entry containing a reference to a definition in the schema.
JsonValidator Alpha JSON schema validator compliant with draft 6 schema. See https://json-schema.org.
LeafSchema System sealed A TreeNodeSchema for a TreeLeafValue.
MakeNominal sealed Use this as the type of a protected field to cause a type to use nominal typing instead of structural.
MapNodeCustomizableSchema System sealed A schema for customizable TreeMapNodes.
MapNodeCustomizableSchemaUnsafe System sealed Unenforced version of MapNodeCustomizableSchemas.
MapNodePojoEmulationSchema System sealed A schema for POJO emulation mode TreeMapNodes.
NodeChangedData Beta sealed Data included for nodeChanged.
NodeInDocumentConstraint A transaction constraint which requires that the given node exists in the tree.
NodeSchemaMetadata sealed Metadata associated with a Node Schema.
NodeSchemaOptions sealed Additional information to provide to Node Schema creation.
ObjectNodeSchema Alpha sealed A schema for TreeObjectNodes.
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.
Revertible sealed Allows reversion of a change made to SharedTree.
RevertibleAlpha Alpha sealed A Revertible with features that are not yet stable.
RunTransaction sealed A function which runs a transaction in a SharedTree.
RunTransactionParams Alpha The parameters for the RunTransaction API.
SchemaCompatibilityStatus sealed

Information about a view schema's compatibility with the document's stored schema.

See SharedTree's README for more information about choosing a compatibility policy.
SchemaFactoryObjectOptions Alpha Options when declaring an object node's schema
SchemaStatics System sealed Stateless APIs exposed via SchemaFactory as both instance properties and as statics.
SchemaValidationFunction Alpha Validates data complies with some particular schema. Implementations are typically created by a JsonValidator.
SharedTreeFormatOptions Alpha Options for configuring the persisted format SharedTree uses.
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.
SimpleObjectFieldSchema Alpha sealed A SimpleFieldSchema for an SimpleObjectNodeSchema field.
SimpleObjectNodeSchema Alpha sealed A SimpleNodeSchema for an object node.
SimpleTreeSchema Alpha sealed A simplified representation of a schema for a tree.
TransactionResultFailed Alpha The result of the RunTransaction API when it failed.
TransactionResultSuccess Alpha The result of the RunTransaction API when it was successful.
TreeArrayNode sealed A TreeNode which implements 'readonly T[]' and the array mutation APIs.
TreeBranch Alpha sealed A collection of functionality associated with a (version-control-style) branch of a SharedTree.
TreeBranchEvents Alpha sealed Events for TreeBranch.
TreeBranchFork Alpha sealed A branch of a SharedTree that has merged from another branch.
TreeChangeEvents sealed A collection of events that can be emitted by a TreeNode.
TreeChangeEventsBeta Beta sealed Extensions to TreeChangeEvents which are not yet stable.
TreeEncodingOptions Alpha Options for how to interpret or encode a tree when schema information is available.
TreeIndex Alpha A index where values are keyed on TreeIndexKeys.
TreeMapNode sealed A map of string keys to tree objects.
TreeNodeApi sealed Provides various functions for analyzing TreeNodes. *
TreeNodeSchemaCore sealed Data common to all tree node schema.
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.

This schema--known as the view schema--may or may not align the stored schema of the document. Information about discrepancies between the two schemas is available via compatibility.

Application authors are encouraged to read [schema-evolution.md](../../docs/user-facing/schema-evolution.md) and choose a schema compatibility policy that aligns with their application's needs.
TreeViewAlpha Alpha sealed TreeView with proposed changes to the schema aware typing to allow use with UnsafeUnknownSchema.
TreeViewEvents sealed Events for TreeView.
VerboseTreeNode Alpha Verbose encoding of a TreeNode.
ViewableTree System sealed A tree from which a TreeView can be created.
ViewContent Alpha The portion of SharedTree data typically persisted by the container. Usable with independentInitializedView(config, options, content) to create a TreeView without loading a container.
WithType sealed Adds a type symbol to a type for stronger typing.

Classes​

Class Alerts Modifiers Description
FieldSchema sealed

All policy for a specific field, including functionality that does not have to be kept consistent across versions or deterministic.

This can include policy for how to use this schema for "view" purposes, and well as how to expose editing APIs. Use SchemaFactory to create the FieldSchema instances, for example optional.
FieldSchemaAlpha Alpha sealed FieldSchema including alpha APIs (currently SimpleFieldSchema).
IterableTreeArrayContent sealed Used to insert iterable content into a TreeArrayNode. Use (TreeArrayNode:variable).spread to create an instance of this type.
SchemaFactory sealed Creates various types of schema for TreeNodes.
SchemaFactoryAlpha Alpha SchemaFactory with additional alpha APIs.
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.
FluidClientVersion Alpha Versions of Fluid Framework client packages.
NodeKind Kind of tree node.
RevertibleStatus The status of a Revertible.
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 Types for use in fields.
ArrayNodeSchema Alpha A schema for TreeArrayNodes.
ConciseTree Alpha Concise encoding of a TreeNode or TreeLeafValue.
FactoryContent System Content which can be used to build a node.
FactoryContentObject System Record-like object which can be used to build some kinds of nodes.
FixRecursiveArraySchema Alpha Workaround for fixing errors resulting from an issue with recursive ArrayNode schema exports.
HandleConverter Alpha Options for how to transcode handles.
IdentifierIndex Alpha An index that returns tree nodes given their associated identifiers.
ImplicitAllowedTypes Types of TreeNodes or TreeLeafValues allowed at a location in a tree.
ImplicitFieldSchema Schema for a field of a tree node.
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](https://en.wikipedia.org/wiki/Covariance_and_contravariance_(computer_science)) over the schema. (See also, [TypeScript Variance Annotations](https://www.typescriptlang.org/docs/handbook/2/generics.html#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 | B (where A and B are types of schema).

- Reading the field behaves covariantly so NodeFromSchema of <A | B> is the same as NodeFromSchema<A> | NodeFromSchema<B>, indicating that either type of node can be read from the field. - Writing to the field behaves contravariantly. Since it is unknown if the node actually has a schema A or a schema B, the only legal values (known to be in schema regardless of which schema the underlying node has) are values which are legal for both A & B.

Note that this is distinct from the case where the schema is [A, B]. In this case it is known that the field allows both A and B (the field can be set to an A or a B value). When A | B is used, the field might allow A but not B (so assigning a B value would be out of schema), B but not A (so assigning an A value would be out of schema) or both A and B.

This gets more extreme when given completely unspecified schema. For example if a field is just provided ImplicitFieldSchema, nothing is known about the content of the field. This means that reading the field (via TreeFieldFromImplicitField) can give any valid tree field content, but there are no safe values which could be written to the field (since it is unknown what values would be out of schema) so InsertableTreeFieldFromImplicitField gives never.

To implement this variance correctly, the computation of types for input and output have to use separate utilities which take very different approaches when encountering non-exact schema like unions or ImplicitFieldSchema. The utilities which behave contravariantly (as required to handle input correctly) link this documentation to indicate that this is how they behave.

In addition to behaving contravariantly, these input type computation utilities often have further limitations. This is due to TypeScript making it difficult to implement this contravariance exactly. When faced with these implementation limitations these contravariant type computation utilities error on the side of producing overly strict requirements. For example in the above case of A | B, the utilities might compute an allowed insertable type as never even if there happens to be a common value accepted by both A and B. Future versions of the API can relax these requirements as the type computations are made more accurate.

For a more concrete example: if InsertableTreeFieldFromImplicitField produced never for a schema A | OptionalField<A>, a future version could instead return a more flexible but still safe type, like A.

More generally: try to avoid providing non-exact schema, especially for the fields of other schema. While these APIs attempt to handle such cases correctly, there are limitations and known bugs in this handling. Code using non-exact schema is much more likely to have its compilation break due to updates of this package or even TypeScript, and thus compilation breaks due to edge cases of non-exact schema handling, especially with recursive schema, are not considered breaking changes. This may change as the API become more stable.
Insertable Alpha Content which could be inserted into a tree.
InsertableContent System Content which can be inserted into a tree.
InsertableField Alpha Content which could be inserted into a field within a tree.
InsertableTreeFieldFromImplicitField Type of content that can be inserted into the tree for a field of the given schema.
InsertableTreeNodeFromAllowedTypes System Type of content that can be inserted into the tree for a node of the given schema.
InsertableTreeNodeFromImplicitAllowedTypes Type of content that can be inserted into the tree for a node of the given schema.
InsertableTypedNode Data which can be used as a node to be inserted. Either an unhydrated node, or content to build a new node.
IsListener Deprecated true iff the given type is an acceptable shape for a event listener
IsUnion System Returns true if T is a union and false if it is not.
JsonCompatible Alpha Use for Json compatible data.
JsonCompatibleObject Alpha Use for Json object compatible data.
JsonFieldSchema Alpha sealed JSON Schema representation of a FieldSchema.
JsonLeafSchemaType Alpha JSON primitive types.
JsonNodeSchema Alpha JSON Schema representation of a TreeNodeSchema.
JsonRefPath Alpha Reference string pointing to a definition in the schema. Should be the fully-qualified identifier.
JsonSchemaId Alpha The fully-qualified identifier.
JsonSchemaType Alpha JSON entity type.
JsonTreeSchema Alpha sealed JSON Schema representation of a tree schema.
LazyItem An "eager" or "lazy" Item in a FlexList. Lazy items are wrapped in a function to allow referring to themselves before they are declared. This makes recursive and co-recursive items possible.
Listenable Deprecated An object which allows the registration of listeners so that subscribers can be notified when an event happens.
Listeners Deprecated Used to specify the kinds of events emitted by a Listenable.
MapNodeInsertableData System Content which can be used to construct a Map node, explicitly or implicitly.
MapNodeSchema Alpha A schema for TreeMapNodes.
NodeFromSchema Takes in TreeNodeSchema[] and returns a TypedNode union.
ObjectFromSchemaRecord System Generates the properties for an ObjectNode from its field schema object.
Off Deprecated A function that, when called, will deregister an event listener subscription that was previously registered.
PopUnion System Gets the first item of a union type.
ReadableField System Content which could be read from a field within a tree.
ReadSchema System Adapter to remove UnsafeUnknownSchema from a schema type so it can be used with types for generating APIs for reading data.
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.
SharedTreeFormatVersion Alpha

Format versions supported by SharedTree.

Each version documents a required minimum version of the \@fluidframework/tree package.
SharedTreeOptions Alpha Configuration options for SharedTree.
SimpleNodeSchema Alpha A simple, shallow representation of a schema for a node.
SimpleTreeIndex Alpha A TreeIndex that returns tree nodes given their associated keys.
TransactionCallbackStatus Alpha The status of the transaction callback in the RunTransaction API.
TransactionConstraint A requirement for a SharedTree transaction to succeed.
TransactionResult Alpha The result of the RunTransaction API. This is the same as TransactionResultExt but with the value field omitted. This is useful when the transaction callback doesn't need to return a value.
TransactionResultExt Alpha The result of the RunTransaction API.
TreeFieldFromImplicitField Converts an ImplicitFieldSchema to a property type suitable for reading a field with this that schema.
TreeIndexKey Alpha Value that may be used as keys in a TreeIndex.
TreeIndexNodes Alpha an array of nodes that is guaranteed to have at least one element
TreeLeafValue Value that may be stored as a leaf node.
TreeNodeFromImplicitAllowedTypes Type of tree node for a field of the given schema.
TreeNodeSchema sealed Schema for a TreeNode or TreeLeafValue.
TreeNodeSchemaClass sealed Tree node schema which is implemented using a class.
TreeNodeSchemaNonClass System sealed Schema which is not a class.
TreeObjectNode A TreeNode which models a JavaScript object.
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 Alpha 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.
VerboseTree Alpha Verbose encoding of a TreeNode or TreeLeafValue.
VoidTransactionCallbackStatus Alpha The status of a the transaction callback in the RunTransaction API where the transaction doesn't need to return a value. This is the same as TransactionCallbackStatus but with the value field omitted. This

Functions​

Function Alerts Return Type Description
adaptEnum(factory, members) Alpha (<TValue extends TEnum[keyof TEnum]>(value: TValue) => TValue extends unknown ? TreeNode & { readonly value: TValue; } : never) & { readonly [Property in keyof TEnum]: TreeNodeSchemaClass<ScopedSchemaName<TScope, TEnum[Property]>, NodeKind.Object, TreeNode & { readonly value: TEnum[Property]; }, Record<string, never>, true, Record<string, never>, undefined>; } & { readonly schema: UnionToTuple<{ readonly [Property in keyof TEnum]: TreeNodeSchemaClass<ScopedSchemaName<TScope, TEnum[Property]>, NodeKind.Object, TreeNode & { readonly value: TEnum[Property]; }, Record<string, never>, true, Record<string, never>, undefined>; }[keyof TEnum]>; } Converts an enum into a collection of schema which can be used in a union.
allowUnused(t) Alpha void Does nothing with the provided value, but appears to use it to make unused locals warnings and errors go away.
asTreeViewAlpha(view) Alpha TreeViewAlpha<TSchema> Retrieve the alpha API for a TreeView.
cloneWithReplacements(root, rootKey, replacer) Alpha unknown Like JSON.stringify, but returns a clone instead of stringifying the result.
comparePersistedSchema(persisted, view, options, canInitialize) Alpha SchemaCompatibilityStatus Compares two schema extracted using extractPersistedSchema(schema). Reports the same compatibility that compatibility would report if opening a document that used the persisted schema and provided view to viewWith(config).
createIdentifierIndex(view) Alpha IdentifierIndex Creates an IdentifierIndex for a given TreeView.
createSimpleTreeIndex(view, indexer, getValue, isKeyValid) Alpha SimpleTreeIndex<TKey, TValue> Creates a SimpleTreeIndex with a specified indexer.
createSimpleTreeIndex(view, indexer, getValue, isKeyValid, indexableSchema) Alpha SimpleTreeIndex<TKey, TValue> Creates a SimpleTreeIndex with a specified indexer.
createSimpleTreeIndex(view, indexer, getValue, isKeyValid) Alpha SimpleTreeIndex<TKey, TValue> Creates a SimpleTreeIndex with a specified indexer.
createSimpleTreeIndex(view, indexer, getValue, isKeyValid, indexableSchema) Alpha SimpleTreeIndex<TKey, TValue> Creates a SimpleTreeIndex with a specified indexer.
enumFromStrings(factory, members) Alpha (<TValue extends Members[number]>(value: TValue) => TValue extends unknown ? TreeNode & { readonly value: TValue; } : never) & { [Index in Extract<keyof Members, `${number}`> extends `${infer N extends number}` ? N : never as Members[Index]]: TreeNodeSchemaClass<ScopedSchemaName<TScope, Members[Index]>, NodeKind.Object, TreeNode & { readonly value: Members[Index]; }, Record<string, never>, true, Record<string, never>, undefined>; } & { readonly schema: UnionToTuple<Members[number] extends unknown ? { [Index in Extract<keyof Members, `${number}`> extends `${infer N extends number}` ? N : never as Members[Index]]: TreeNodeSchemaClass<ScopedSchemaName<TScope, Members[Index]>, NodeKind.Object, TreeNode & { readonly value: Members[Index]; }, Record<string, never>, true, Record<string, never>, undefined>; }[Members[number]] : never>; } Converts an array of distinct strings into a collection of schema which can be used like an enum style union.
evaluateLazySchema(value) Alpha T Returns the schema referenced by the LazyItem.
extractPersistedSchema(schema) Alpha JsonCompatible Dumps the "persisted" schema subset of the provided schema into a deterministic JSON-compatible, semi-human-readable, but unspecified format.
generateSchemaFromSimpleSchema(simple) Alpha TreeSchema Create FieldSchema from a SimpleTreeSchema.
getBranch(tree) Deprecated, Alpha BranchableTree Get a BranchableTree from a ITree.
getBranch(view) Deprecated, Alpha BranchableTree Get a BranchableTree from a TreeView.
getJsonSchema(schema, options) Alpha JsonTreeSchema Creates a JSON Schema representation of the provided TreeNodeSchema.
getSimpleSchema(schema) Alpha SimpleTreeSchema Copies data from ImplicitFieldSchema to create a SimpleTreeSchema out of new plain JavaScript objects, Sets and Maps.
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.
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) Alpha 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.

Variables​

Variable Alerts Modifiers Type Description
ArrayNodeSchema Alpha readonly { readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is ArrayNodeSchema; }
ForestTypeExpensiveDebug Alpha readonly ForestType Slow implementation of forest intended only for debugging.
ForestTypeOptimized Alpha readonly ForestType Optimized implementation of forest.
ForestTypeReference Alpha readonly ForestType Reference implementation of forest.
MapNodeSchema Alpha readonly { readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is MapNodeSchema; }
noopValidator Alpha readonly JsonValidator A JsonValidator implementation which performs no validation and accepts all data as valid.
ObjectNodeSchema Alpha readonly { readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is ObjectNodeSchema<string, RestrictiveStringRecord<ImplicitFieldSchema>, boolean, unknown>; }
rollback readonly unique symbol A special object that signifies when a SharedTree transaction should "roll back".
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
SharedTreeFormatVersion Alpha readonly { readonly v1: 1; readonly v2: 2; readonly v3: 3; }

Format versions supported by SharedTree.

Each version documents a required minimum version of the \@fluidframework/tree package.
Tree readonly TreeApi The Tree object holds various functions for interacting with TreeNodes.
TreeAlpha Alpha readonly, sealed { branch(node: TreeNode): TreeBranch | undefined; create<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: InsertableField<TSchema>): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>; importConcise<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: ConciseTree | undefined): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>; importVerbose<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: VerboseTree | undefined, options?: Partial<TreeEncodingOptions>): Unhydrated<TreeFieldFromImplicitField<TSchema>>; exportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree; exportConcise(node: TreeNode | TreeLeafValue | undefined, options?: TreeEncodingOptions): ConciseTree | undefined; exportVerbose(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): VerboseTree; exportCompressed(tree: TreeNode | TreeLeafValue, options: { oldestCompatibleClient: FluidClientVersion; idCompressor?: IIdCompressor; }): JsonCompatible<IFluidHandle>; importCompressed<const TSchema extends ImplicitFieldSchema>(schema: TSchema, compressedData: JsonCompatible<IFluidHandle>, options: { idCompressor?: IIdCompressor; } & ICodecOptions): Unhydrated<TreeFieldFromImplicitField<TSchema>>; } 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, sealed { on<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(node: TNode, eventName: K, listener: NoInfer<TreeChangeEventsBeta<TNode>[K]>): () => void; clone<const TSchema extends ImplicitFieldSchema>(node: TreeFieldFromImplicitField<TSchema>): TreeFieldFromImplicitField<TSchema>; } Extensions to Tree which are not yet stable.
typeboxValidator Alpha readonly JsonValidator A JsonValidator implementation which uses TypeBox's JSON schema validator.
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
InternalTypes
JsonAsTree Alpha Utilities for storing JSON data in TreeNodes.
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.

Function Details​

adaptEnum​

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

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 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
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 to avoid the enum members colliding with other schema.

Example​

const schemaFactory = new SchemaFactory("com.myApp");
// An enum for use in the tree. Must have string keys.
enum Mode {
	a = "A",
	b = "B",
}
// Define the schema for each member of the enum using a nested scope to group them together.
const ModeNodes = adaptEnum(new SchemaFactory(`${schemaFactory.scope}.Mode`), Mode);
// Defined the types of the nodes which correspond to this the schema.
type ModeNodes = TreeNodeFromImplicitAllowedTypes<(typeof ModeNodes.schema)>;
// An example schema which has an enum as a child.
class Parent extends schemaFactory.object("Parent", {
	// adaptEnum's return value has a ".schema" property can be use as an `AllowedTypes` array allowing any of the members of the enum.
	mode: ModeNodes.schema,
}) {}
// Example usage of enum based nodes, showing what type to use and that `.value` can be used to read out the enum value.
function getValue(node: ModeNodes): Mode {
	return node.value;
}
// Example constructing a tree containing an enum node from an enum value.
// The syntax `new ModeNodes.a()` is also supported.
function setValue(node: Parent): void {
	node.mode = ModeNodes(Mode.a);
}

Parameters​

Parameter Type Description
factory SchemaFactory<TScope>
members TEnum

Returns​

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

See Also​

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

allowUnused​

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

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

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

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

Signature​

export declare function allowUnused<T>(t?: T): void;
Type Parameters​
Parameter Description
T

Remarks​

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

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

Parameters​

Parameter Modifiers Type Description
t optional T

asTreeViewAlpha​

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

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). 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, canInitialize: boolean): SchemaCompatibilityStatus;

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) 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.
canInitialize boolean Passed through to the return value unchanged and otherwise unused.

Returns​

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

Return type: SchemaCompatibilityStatus

createIdentifierIndex​

Creates an IdentifierIndex for a given TreeView.

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

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

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

Signature​

export declare function createIdentifierIndex<TSchema extends ImplicitFieldSchema>(view: TreeView<TSchema>): IdentifierIndex;
Type Parameters​
Parameter Constraint Description
TSchema ImplicitFieldSchema

Parameters​

Parameter Type Description
view TreeView<TSchema>

Returns​

Return type: IdentifierIndex

createSimpleTreeIndex​

Creates a SimpleTreeIndex with a specified indexer.

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

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

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

Signature​

export declare function createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue>(view: TreeView<TFieldSchema>, indexer: (schema: TreeNodeSchema) => string | undefined, getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey): SimpleTreeIndex<TKey, TValue>;
Type Parameters​
Parameter Constraint Description
TFieldSchema ImplicitFieldSchema
TKey TreeIndexKey
TValue

Parameters​

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

Returns​

Return type: SimpleTreeIndex<TKey, TValue>

createSimpleTreeIndex​

Creates a SimpleTreeIndex with a specified indexer.

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

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

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

Signature​

export declare function createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue, TSchema extends TreeNodeSchema>(view: TreeView<TFieldSchema>, indexer: (schema: TSchema) => string | undefined, getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey, indexableSchema: readonly TSchema[]): SimpleTreeIndex<TKey, TValue>;
Type Parameters​
Parameter Constraint Description
TFieldSchema ImplicitFieldSchema
TKey TreeIndexKey
TValue
TSchema TreeNodeSchema

Parameters​

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

Returns​

Return type: SimpleTreeIndex<TKey, TValue>

createSimpleTreeIndex​

Creates a SimpleTreeIndex with a specified indexer.

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

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

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

Signature​

export declare function createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue>(view: TreeView<TFieldSchema>, indexer: Map<TreeNodeSchema, string>, getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey): SimpleTreeIndex<TKey, TValue>;
Type Parameters​
Parameter Constraint Description
TFieldSchema ImplicitFieldSchema
TKey TreeIndexKey
TValue

Parameters​

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

Returns​

Return type: SimpleTreeIndex<TKey, TValue>

createSimpleTreeIndex​

Creates a SimpleTreeIndex with a specified indexer.

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

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

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

Signature​

export declare function createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue, TSchema extends TreeNodeSchema>(view: TreeView<TFieldSchema>, indexer: Map<TreeNodeSchema, string>, getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey, indexableSchema: readonly TSchema[]): SimpleTreeIndex<TKey, TValue>;
Type Parameters​
Parameter Constraint Description
TFieldSchema ImplicitFieldSchema
TKey TreeIndexKey
TValue
TSchema TreeNodeSchema

Parameters​

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

Returns​

Return type: SimpleTreeIndex<TKey, TValue>

enumFromStrings​

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

This API is provided as 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 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.

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

extractPersistedSchema​

Dumps the "persisted" schema subset of the provided schema into a deterministic JSON-compatible, semi-human-readable, but unspecified 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): 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 may change across major versions of this package: such changes are considered breaking. Beyond that, no compatibility guarantee is provided for this format: it should never be relied upon to load data, it should only be used for comparing outputs from this function.

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, canInitialize).

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), require("./schema.json"));

Parameters​

Parameter Type Description
schema ImplicitFieldSchema

Returns​

Return type: JsonCompatible

generateSchemaFromSimpleSchema​

Create FieldSchema from a SimpleTreeSchema.

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

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

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

Signature​

export declare function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): TreeSchema;

Remarks​

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

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

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

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

Parameters​

Parameter Type Description
simple SimpleTreeSchema

Returns​

Return type: TreeSchema

getBranch​

Get a BranchableTree from a ITree.

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

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

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

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

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

Signature​

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

Remarks​

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

Parameters​

Parameter Type Description
tree ITree

Returns​

Return type: BranchableTree

getBranch​

Get a BranchableTree from a TreeView.

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

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

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

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

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

Signature​

export declare function getBranch<T extends ImplicitFieldSchema | UnsafeUnknownSchema>(view: TreeViewAlpha<T>): BranchableTree;
Type Parameters​
Parameter Constraint Description
T ImplicitFieldSchema | UnsafeUnknownSchema

Remarks​

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

Parameters​

Parameter Type Description
view TreeViewAlpha<T>

Returns​

Return type: BranchableTree

getJsonSchema​

Creates a JSON Schema representation of the provided TreeNodeSchema.

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

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

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

Signature​

export declare function getJsonSchema(schema: ImplicitAllowedTypes, options: Required<TreeSchemaEncodingOptions>): JsonTreeSchema;

Remarks​

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

Example​

A Shared Tree schema like the following:

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

Will yield JSON Schema like the following:

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

Parameters​

Parameter Type Description
schema ImplicitAllowedTypes
options Required<TreeSchemaEncodingOptions>

Returns​

Return type: JsonTreeSchema

getSimpleSchema​

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

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

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

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

Signature​

export declare function getSimpleSchema(schema: ImplicitFieldSchema): SimpleTreeSchema;

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

independentInitializedView​

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

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

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

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

Signature​

export declare function independentInitializedView<const TSchema extends ImplicitFieldSchema>(config: TreeViewConfiguration<TSchema>, options: ForestOptions & ICodecOptions, content: ViewContent): TreeViewAlpha<TSchema>;
Type Parameters​
Parameter Constraint Description
TSchema ImplicitFieldSchema

Remarks​

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

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

Parameters​

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

Returns​

Return type: TreeViewAlpha<TSchema>

independentView​

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

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

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

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

Signature​

export declare function independentView<const TSchema extends ImplicitFieldSchema>(config: TreeViewConfiguration<TSchema>, options: ForestOptions & {
    idCompressor?: IIdCompressor | undefined;
}): TreeViewAlpha<TSchema>;
Type Parameters​
Parameter Constraint Description
TSchema ImplicitFieldSchema

Remarks​

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

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

Parameters​

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

Returns​

Return type: TreeViewAlpha<TSchema>

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 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 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)

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

ForestTypeExpensiveDebug​

Slow implementation of forest intended only for debugging.

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​

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 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​

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 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​

ForestTypeReference: ForestType

Type: ForestType

Remarks​

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

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

noopValidator​

A JsonValidator implementation which performs no validation and accepts all data as valid.

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​

noopValidator: JsonValidator

Type: JsonValidator

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

rollback​

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

Signature​

rollback: unique symbol

Type: unique symbol

SharedTree​

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

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

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

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

Signature​

SharedTree: ISharedObjectKind<ITree> & SharedObjectKind<ITree>

Type: ISharedObjectKind<ITree> & SharedObjectKind<ITree>

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"

SharedTreeFormatVersion​

Format versions supported by SharedTree.

Each version documents a required minimum version of the @fluidframework/tree package.

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​

SharedTreeFormatVersion: {
    readonly v1: 1;
    readonly v2: 2;
    readonly v3: 3;
}

Type: { readonly v1: 1; readonly v2: 2; readonly v3: 3; }

Tree​

The Tree object holds various functions for interacting with TreeNodes.

Signature​

treeApi: TreeApi

Type: TreeApi

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​

/** @sealed */
TreeAlpha: {
    branch(node: TreeNode): TreeBranch | undefined;
    create<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: InsertableField<TSchema>): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>;
    importConcise<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: ConciseTree | undefined): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>;
    importVerbose<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: VerboseTree | undefined, options?: Partial<TreeEncodingOptions>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
    exportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;
    exportConcise(node: TreeNode | TreeLeafValue | undefined, options?: TreeEncodingOptions): ConciseTree | undefined;
    exportVerbose(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): VerboseTree;
    exportCompressed(tree: TreeNode | TreeLeafValue, options: {
        oldestCompatibleClient: FluidClientVersion;
        idCompressor?: IIdCompressor;
    }): JsonCompatible<IFluidHandle>;
    importCompressed<const TSchema extends ImplicitFieldSchema>(schema: TSchema, compressedData: JsonCompatible<IFluidHandle>, options: {
        idCompressor?: IIdCompressor;
    } & ICodecOptions): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
}

Type: { branch(node: TreeNode): TreeBranch | undefined; create<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: InsertableField<TSchema>): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>; importConcise<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: ConciseTree | undefined): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>; importVerbose<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: VerboseTree | undefined, options?: Partial<TreeEncodingOptions>): Unhydrated<TreeFieldFromImplicitField<TSchema>>; exportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree; exportConcise(node: TreeNode | TreeLeafValue | undefined, options?: TreeEncodingOptions): ConciseTree | undefined; exportVerbose(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): VerboseTree; exportCompressed(tree: TreeNode | TreeLeafValue, options: { oldestCompatibleClient: FluidClientVersion; idCompressor?: IIdCompressor; }): JsonCompatible<IFluidHandle>; importCompressed<const TSchema extends ImplicitFieldSchema>(schema: TSchema, compressedData: JsonCompatible<IFluidHandle>, options: { idCompressor?: IIdCompressor; } & ICodecOptions): Unhydrated<TreeFieldFromImplicitField<TSchema>>; }

TreeArrayNode​

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

Signature​

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

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

TreeBeta​

Extensions to Tree which are not yet stable.

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

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

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

Signature​

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

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

typeboxValidator​

A JsonValidator 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​

typeboxValidator: JsonValidator

Type: JsonValidator

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.