TreeBeta Interface

Extensions to Tree which are not yet stable.

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.

Sealed

This type is "sealed," meaning that code outside of the library defining it should not implement or extend it. Future versions of this type may add members or make typing of readonly members more specific.

Signature

/** @sealed */
export interface TreeBeta

Remarks

Use via the TreeBeta singleton.

Methods

Method	Alerts	Return Type	Description
clone(node)	Beta	TreeFieldFromImplicitField<TSchema>	Clones the persisted data associated with a node.
create(schema, data)	Beta	Unhydrated<TreeFieldFromImplicitField<TSchema>>	Construct tree content that is compatible with the field defined by the provided schema.
exportConcise(node, options)	Beta	ConciseTree	Copy a snapshot of the current version of a TreeNode into a ConciseTree.
exportConcise(node, options)	Beta	ConciseTree | undefined	Copy a snapshot of the current version of a TreeNode into a ConciseTree, allowing undefined.
importConcise(schema, data)	Beta	Unhydrated<TreeFieldFromImplicitField<TSchema>>	A less type-safe version of create(schema, data), suitable for importing data.
on(node, eventName, listener)	Beta	() => void	Register an event listener on the given node.

Method Details

clone

Clones the persisted data associated with a node.

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

clone<const TSchema extends ImplicitFieldSchema>(node: TreeFieldFromImplicitField<TSchema>): TreeFieldFromImplicitField<TSchema>;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Remarks

Some key things to note:

• Local state, such as properties added to customized schema classes, will not be cloned. However, they will be initialized to their default state just as if the node had been created via its constructor.

• Value node types (i.e., numbers, strings, booleans, nulls and Fluid handles) will be returned as is.

• The identifiers in the node's subtree will be preserved, i.e., they are not replaced with new values.

• If the node (or any node in its subtree) contains unknown optional fields, those fields will be cloned just like the known fields.

Parameters

Parameter	Type	Description
node	TreeFieldFromImplicitField<TSchema>	The node to clone.

Returns

A new unhydrated node with the same persisted data as the original node.

Return type: TreeFieldFromImplicitField<TSchema>

create

Construct tree content that is compatible with the field defined by the provided schema.

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

create<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: InsertableTreeFieldFromImplicitField<TSchema>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Remarks

When providing a TreeNodeSchemaClass, this is the same as invoking its constructor except that an unhydrated node can also be provided. This function exists as a generalization that can be used in other cases as well, such as when undefined might be allowed (for an optional field), or when the type should be inferred from the data when more than one type is possible.

Parameters

Parameter	Type	Description
schema	TSchema	The schema for what to construct. As this is an ImplicitFieldSchema, a FieldSchema, TreeNodeSchema or AllowedTypes array can be provided.
data	InsertableTreeFieldFromImplicitField<TSchema>	The data used to construct the field content.

Returns

Return type: Unhydrated<TreeFieldFromImplicitField<TSchema>>

exportConcise

Copy a snapshot of the current version of a TreeNode into a ConciseTree.

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

exportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;

Parameters

Parameter	Modifiers	Type	Description
node		TreeNode | TreeLeafValue
options	optional	TreeEncodingOptions

Returns

Return type: ConciseTree

exportConcise

Copy a snapshot of the current version of a TreeNode into a ConciseTree, allowing undefined.

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

exportConcise(node: TreeNode | TreeLeafValue | undefined, options?: TreeEncodingOptions): ConciseTree | undefined;

Parameters

Parameter	Modifiers	Type	Description
node		TreeNode | TreeLeafValue | undefined
options	optional	TreeEncodingOptions

Returns

Return type: ConciseTree | undefined

importConcise

A less type-safe version of create(schema, data), suitable for importing data.

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

importConcise<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: ConciseTree | undefined): Unhydrated<TreeFieldFromImplicitField<TSchema>>;

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Remarks

Due to ConciseTree relying on type inference from the data, its use is somewhat limited. This does not support ConciseTrees with customized handle encodings or using persisted keys. Use "compressed" or "verbose" formats for more flexibility.

When using this function, it is recommend to ensure your schema is unambiguous with preventAmbiguity. If the schema is ambiguous, consider using create(schema, data) and Unhydrated nodes where needed, or using importVerbose(schema, data, options) and specify all types.

Documented (and thus recoverable) error handling/reporting for this is not yet implemented, but for now most invalid inputs will throw a recoverable error.

Parameters

Parameter	Type	Description
schema	TSchema
data	ConciseTree | undefined

Returns

Return type: Unhydrated<TreeFieldFromImplicitField<TSchema>>

on

Register an event listener on the given node.

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

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

Type Parameters

Parameter	Constraint	Description
K	keyof TreeChangeEventsBeta<TNode>
TNode	TreeNode

Parameters

Parameter	Type	Description
node	TNode	The node whose events should be subscribed to.
eventName	K	Which event to subscribe to.
listener	NoInfer<TreeChangeEventsBeta<TNode>[K]>	The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.

Returns

A callback function which will deregister the event. This callback should be called only once.

Return type: () => void