@fluidframework/tree Package

Interfaces

Interface	Alerts	Modifiers	Description
BranchableTree	Alpha	sealed	A "version control"-style branch of a SharedTree.
CommitMetadata		sealed	Information about a commit that has been applied.
EncodeOptions	Alpha		Options for how to encode a tree.
FieldProps			Additional information to provide to a FieldSchema.
FieldSchemaMetadata		sealed	Metadata associated with a FieldSchema.
FieldSchemaUnsafe			Unenforced version of FieldSchema.
ForestOptions	Alpha		Configuration options for SharedTree's internal tree storage.
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.
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.
Listenable		sealed	An object which allows the registration of listeners so that subscribers can be notified when an event happens.
MakeNominal		sealed	Use this as the type of a protected field to cause a type to use nominal typing instead of structural.
NodeChangedData	Beta	sealed	Data included for nodeChanged.
NodeInDocumentConstraint			A transaction constraint which requires that the given node exists in the tree.
ParseOptions	Alpha		Options for how to interpret a VerboseTree<TCustom> when schema information is available.
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.
RunTransaction		sealed	A function which runs a transaction in a SharedTree.
SchemaCompatibilityStatus		sealed	Information about a view schema's compatibility with the document's stored schema. See SharedTree's README for more information about choosing a compatibility policy.
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.
TreeArrayNode		sealed	A TreeNode which implements 'readonly T[]' and the array mutation APIs.
TreeArrayNodeUnsafe	System	sealed	Unenforced version of TreeArrayNode.
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.
TreeMapNode		sealed	A map of string keys to tree objects.
TreeMapNodeUnsafe	System	sealed	Unenforced version of TreeMapNode.
TreeNodeApi		sealed	Provides various functions for analyzing TreeNodes. *
TreeNodeSchemaClassUnsafe	System		Unenforced version of TreeNodeSchemaClass.
TreeNodeSchemaCore		sealed	Data common to all tree node schema.
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	Modifiers	Description
FieldSchema	sealed	All policy for a specific field, including functionality that does not have to be kept consistent across versions or deterministic. This can include policy for how to use this schema for "view" purposes, and well as how to expose editing APIs. Use SchemaFactory to create the FieldSchema instances, for example optional(t, props).
IterableTreeArrayContent	sealed	Used to insert iterable content into a TreeArrayNode. Use (TreeArrayNode:variable).spread to create an instance of this type.
SchemaFactory	sealed	Creates various types of schema for TreeNodes.
TreeNode	sealed	A non-leaf SharedTree node. Includes objects, arrays, and maps.
TreeViewConfiguration	sealed	Configuration for viewWith(config).

Enumerations

Enum	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 a node.
FluidClientVersion	Alpha	Versions of Fluid Framework client packages.
ForestType	Alpha	Used to distinguish between different forest types.
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.

Types

TypeAlias	Alerts	Modifiers	Description
AllowedTypes	System		Types for use in fields.
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.
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.
InsertableObjectFromSchemaRecordUnsafe	System		Unenforced version of InsertableObjectFromSchemaRecord.
InsertableTreeFieldFromImplicitField			Type of content that can be inserted into the tree for a field of the given schema.
InsertableTreeFieldFromImplicitFieldUnsafe	System		Unenforced version of InsertableTreeFieldFromImplicitField.
InsertableTreeNodeFromAllowedTypes	System		Type of content that can be inserted into the tree for a node of the given schema.
InsertableTreeNodeFromAllowedTypesUnsafe	System		Unenforced version of InsertableTreeNodeFromAllowedTypes.
InsertableTreeNodeFromImplicitAllowedTypes			Type of content that can be inserted into the tree for a node of the given schema.
InsertableTreeNodeFromImplicitAllowedTypesUnsafe	System		Unenforced version of InsertableTreeNodeFromImplicitAllowedTypes.
InsertableTypedNode			Data which can be used as a node to be inserted. Either an unhydrated node, or content to build a new node.
IsListener			true iff the given type is an acceptable shape for a event listener
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.
Listeners			Used to specify the kinds of events emitted by a Listenable.
MapNodeInsertableData	System		Content which can be used to construct a Map node, explicitly or implicitly.
NodeFromSchema			Takes in TreeNodeSchema[] and returns a TypedNode union.
Off			A function that, when called, will deregister an event listener subscription that was previously registered.
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.
RevertibleFactory		sealed	Factory for creating a Revertible. Will error if invoked outside the scope of the changed event that provides it, or if invoked multiple times.
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.
TransactionConstraint			A requirement for a SharedTree transaction to succeed.
TreeFieldFromImplicitField			Converts an ImplicitFieldSchema to a property type suitable for reading a field with this that schema.
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 modules a JavaScript object.
TreeObjectNodeUnsafe	System		Unenforced version of TreeObjectNode.
Unenforced			A placeholder to use in extends constraints when using the real type breaks compilation of some recursive types due to a design limitation of TypeScript. These extends constraints only serve as documentation: to avoid breaking compilation, this type has to not actually enforce anything, and thus is just unknown. Therefore the type safety is the responsibility of the user of the API.
Unhydrated			Type alias to document which values are un-hydrated. Un-hydrated values are nodes produced from schema's create functions that haven't been inserted into a tree yet. Since un-hydrated nodes become hydrated when inserted, strong typing can't be used to distinguish them. This no-op wrapper is used instead.
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.
VerboseTree	Alpha		Verbose encoding of a TreeNode or TreeLeafValue.

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.
asTreeViewAlpha(view)	Alpha	TreeViewAlpha<TSchema>	Retrieve the alpha API for a TreeView.
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).
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.
extractPersistedSchema(schema)	Alpha	JsonCompatible	Dumps the "persisted" schema subset of the provided schema into a deterministic JSON-compatible, semi-human-readable, but unspecified format.
getBranch(tree)	Deprecated, Alpha	BranchableTree	Get a BranchableTree from a ITree.
getBranch(view)	Deprecated, Alpha	BranchableTree	Get a BranchableTree from a TreeView.
getJsonSchema(schema)	Alpha	JsonTreeSchema	Creates a JSON Schema representation of the provided TreeNodeSchema.
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.
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
noopValidator	Alpha	readonly	JsonValidator	A JsonValidator implementation which performs no validation and accepts all data as valid.
rollback		readonly	unique symbol	A special object that signifies when a SharedTree transaction should "roll back".
SharedTree	Legacy, Alpha	readonly	ISharedObjectKind<ITree> & SharedObjectKind<ITree>	SharedTree is a hierarchical data structure for collaboratively editing strongly typed JSON-like trees of objects, arrays, and other data types.
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<ParseOptions<IFluidHandle>>): Unhydrated<TreeFieldFromImplicitField<TSchema>>; importVerbose<const TSchema extends ImplicitFieldSchema, THandle>(schema: TSchema, data: VerboseTree<THandle> | undefined, options: ParseOptions<THandle>): Unhydrated<TreeFieldFromImplicitField<TSchema>>; exportConcise(node: TreeNode | TreeLeafValue, options?: Partial<EncodeOptions<IFluidHandle>>): ConciseTree; exportConcise<THandle>(node: TreeNode | TreeLeafValue, options: EncodeOptions<THandle>): ConciseTree<THandle>; exportVerbose(node: TreeNode | TreeLeafValue, options?: Partial<EncodeOptions<IFluidHandle>>): VerboseTree; exportVerbose<T>(node: TreeNode | TreeLeafValue, options: EncodeOptions<T>): VerboseTree<T>; 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	Description
InternalTypes

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.

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>

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: JsonCompatible, 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"),
		extractPersistedSchema(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	JsonCompatible	Schema which would be used to view persisted content. Use extractPersistedSchema(schema) to convert the view schema into this format.
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

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.

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

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: ImplicitFieldSchema): JsonTreeSchema;

Remarks

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

Example

A Shared Tree schema like the following:

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

Will yield JSON Schema like the following:

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

Parameters

Parameter	Type	Description
schema	ImplicitFieldSchema

Returns

Return type: JsonTreeSchema

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>

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

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

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>

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<ParseOptions<IFluidHandle>>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
    importVerbose<const TSchema extends ImplicitFieldSchema, THandle>(schema: TSchema, data: VerboseTree<THandle> | undefined, options: ParseOptions<THandle>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
    exportConcise(node: TreeNode | TreeLeafValue, options?: Partial<EncodeOptions<IFluidHandle>>): ConciseTree;
    exportConcise<THandle>(node: TreeNode | TreeLeafValue, options: EncodeOptions<THandle>): ConciseTree<THandle>;
    exportVerbose(node: TreeNode | TreeLeafValue, options?: Partial<EncodeOptions<IFluidHandle>>): VerboseTree;
    exportVerbose<T>(node: TreeNode | TreeLeafValue, options: EncodeOptions<T>): VerboseTree<T>;
    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<ParseOptions<IFluidHandle>>): Unhydrated<TreeFieldFromImplicitField<TSchema>>; importVerbose<const TSchema extends ImplicitFieldSchema, THandle>(schema: TSchema, data: VerboseTree<THandle> | undefined, options: ParseOptions<THandle>): Unhydrated<TreeFieldFromImplicitField<TSchema>>; exportConcise(node: TreeNode | TreeLeafValue, options?: Partial<EncodeOptions<IFluidHandle>>): ConciseTree; exportConcise<THandle>(node: TreeNode | TreeLeafValue, options: EncodeOptions<THandle>): ConciseTree<THandle>; exportVerbose(node: TreeNode | TreeLeafValue, options?: Partial<EncodeOptions<IFluidHandle>>): VerboseTree; exportVerbose<T>(node: TreeNode | TreeLeafValue, options: EncodeOptions<T>): VerboseTree<T>; 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.