Context Interface

The context object available to generated code when editing a tree.

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

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

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

Signature

export interface Context<TSchema extends ImplicitFieldSchema>

Type Parameters

Parameter	Constraint	Description
TSchema	ImplicitFieldSchema

Remarks

This object is provided to JavaScript code executed by the editor as a variable named context. It contains the current state of the tree and utilities for creating and inspecting tree nodes.

Use createContext(tree) to create a context.

Properties

Property	Alerts	Type	Description
create	Alpha	Record<string, (input: FactoryContentObject) => TreeNode>	A collection of builder functions for creating new tree nodes.
is	Alpha	Record<string, <T extends TreeNode>(input: T) => input is T>	A collection of type-checking functions for tree nodes.
root	Alpha	ReadableField<TSchema>	The root of the tree that can be read or modified.

Methods

Method	Alerts	Return Type	Description
isArray(value)	Alpha	boolean	Checks if the given node is an array.
isMap(value)	Alpha	boolean	Checks if the given node is a map.
key(child)	Alpha	string | number	Returns the key or index of the given node within its parent.
parent(child)	Alpha	TreeNode | undefined	Returns the parent node of the given child node.

Property Details

create

A collection of builder functions for creating new tree nodes.

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

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

Signature

create: Record<string, (input: FactoryContentObject) => TreeNode>;

Type: Record<string, (input: FactoryContentObject) => TreeNode>

Remarks

Each property on this object is named after a type in the tree schema. Call the corresponding function to create a new node of that type. Always use these builder functions when creating new nodes rather than plain JavaScript objects.

Example: Create a new Person node with context.create.Person({ name: "Alice", age: 30 })

is

A collection of type-checking functions for tree nodes.

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

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

Signature

is: Record<string, <T extends TreeNode>(input: T) => input is T>;

Type: Record<string, <T extends TreeNode>(input: T) => input is T>

Remarks

Each property on this object is named after a type in the tree schema. Call the corresponding function to check if a node is of that specific type. This is useful when working with nodes that could be one of multiple types.

Example: Check if a node is a Person with if (context.is.Person(node)) { console.log(node.name); }

root

The root of the tree that can be read or modified.

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

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

Signature

root: ReadableField<TSchema>;

Type: ReadableField<TSchema>

Remarks

You can read properties and navigate through the tree starting from this root. You can also assign a new value to this property to replace the entire tree, as long as the new value is one of the types allowed at the root.

Example: Read the current root with const currentRoot = context.root;

Example: Replace the entire root with context.root = context.create.MyRootType({ });

Method Details

isArray

Checks if the given node is an array.

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

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

Signature

isArray(value: unknown): boolean;

Parameters

Parameter	Type	Description
value	unknown

Returns

Return type: boolean

isMap

Checks if the given node is a map.

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

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

Signature

isMap(value: unknown): boolean;

Parameters

Parameter	Type	Description
value	unknown

Returns

Return type: boolean

key

Returns the key or index of the given node within its parent.

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

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

Signature

key(child: TreeNode): string | number;

Remarks

For a node in an object, this might return a string like "firstName". For a node in an array, this might return a number like 0, 1, 2, etc.

Example: const key = context.key(childNode);

Parameters

Parameter	Type	Description
child	TreeNode	The node whose key you want to find.

Returns

A string key if the node is in an object or map, or a numeric index if the node is in an array.

Return type: string | number

parent

Returns the parent node of the given child node.

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

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

Signature

parent(child: TreeNode): TreeNode | undefined;

Remarks

Example: Get the parent with const parent = context.parent(childNode);

Parameters

Parameter	Type	Description
child	TreeNode	The node whose parent you want to find.

Returns

The parent node, or undefined if the node is the root or is not in the tree.

Return type: TreeNode | undefined