feat(tree): Add schema-agnostic tree traversal APIs

.changeset/seven-toes-smell.md

@@ -0,0 +1,62 @@
+---
+"@fluidframework/tree": minor
+"fluid-framework": minor
+"__section": tree
+---
+Add TreeAlpha.child and TreeAlpha.children APIs for generic tree traversal
+
+#### TreeAlpha.child
+
+Access a child node or value of a `TreeNode` by its property key.
+
+```typescript
+class MyObject extends schemaFactory.object("MyObject", {
+	foo: schemaFactory.string;
+	bar: schemaFactory.optional(schemaFactory.string);
+}) {}
+
+const myObject = new MyObject({
+	foo: "Hello world!"
+});
+
+const foo = TreeAlpha.child(myObject, "foo"); // "Hello world!"
+const bar = TreeAlpha.child(myObject, "bar"); // undefined
+const baz = TreeAlpha.child(myObject, "baz"); // undefined
+```
+
+```typescript
+class MyArray extends schemaFactory.array("MyArray", schemaFactory.string) {}
+
+const myArray = new MyArray("Hello", "World");
+
+const child0 = TreeAlpha.child(myArray, 0); // "Hello"
+const child1 = TreeAlpha.child(myArray, 1); // "World
+const child2 = TreeAlpha.child(myArray, 2); // undefined
+```
+
+#### TreeAlpha.children
+
+Get all child nodes / values of a `TreeNode`, keyed by their property keys.
+
+```typescript
+class MyObject extends schemaFactory.object("MyObject", {
+	foo: schemaFactory.string;
+	bar: schemaFactory.optional(schemaFactory.string);
+	baz: schemaFactory.optional(schemaFactory.number);
+}) {}
+
+const myObject = new MyObject({
+	foo: "Hello world!",
+	baz: 42,
+});
+
+const children = TreeAlpha.children(myObject); // [["foo", "Hello world!"], ["baz", 42]]
+```
+
+```typescript
+class MyArray extends schemaFactory.array("MyArray", schemaFactory.string) {}
+
+const myArray = new MyArray("Hello", "World");
+
+const children = TreeAlpha.children(myObject); // [[0, "Hello"], [1, "World"]]
+```

packages/dds/tree/api-report/tree.alpha.api.md

@@ -1216,6 +1216,8 @@ export const Tree: Tree;
 // @alpha @sealed @system
 export interface TreeAlpha {
     branch(node: TreeNode): TreeBranch | undefined;
+    child(node: TreeNode, key: string | number): TreeNode | TreeLeafValue | undefined;
+    children(node: TreeNode): Iterable<[propertyKey: string | number, child: TreeNode | TreeLeafValue]>;
     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>;
     exportCompressed(tree: TreeNode | TreeLeafValue, options: {
         idCompressor?: IIdCompressor;

packages/dds/tree/src/feature-libraries/flex-tree/flexTreeTypes.ts

@@ -169,7 +169,7 @@ export interface FlexTreeNode extends FlexTreeEntity, MapTreeNodeViewGeneric<Fle
 	 * @remarks
 	 * All fields implicitly exist, so `getBoxed` can be called with any key and will always return a field.
 	 * Even if the field is empty, it will still be returned, and can be edited to insert content if allowed by the field kind.
-	 * See {@link FlexTreeNode.tryGetField} for a variant that does not allocate afield in the empty case.
+	 * See {@link FlexTreeNode.tryGetField} for a variant that does not allocate a field in the empty case.
 	 */
 	getBoxed(key: FieldKey): FlexTreeField;
 

packages/dds/tree/src/shared-tree/schematizingTreeView.ts

@@ -27,7 +27,7 @@ import {
 	type SchemaCompatibilityStatus,
 	type TreeView,
 	type TreeViewEvents,
-	getTreeNodeForField,
+	tryGetTreeNodeForField,
 	setField,
 	normalizeFieldSchema,
 	SchemaCompatibilityTester,
@@ -428,7 +428,7 @@ export class SchematizingSimpleTreeView<
 			);
 		}
 		const view = this.getView();
-		return getTreeNodeForField(view.flexTree) as ReadableField<TRootSchema>;
+		return tryGetTreeNodeForField(view.flexTree) as ReadableField<TRootSchema>;
 	}
 
 	public set root(newRoot: InsertableField<TRootSchema>) {

packages/dds/tree/src/shared-tree/treeAlpha.ts

@@ -3,13 +3,19 @@
  * Licensed under the MIT License.
  */
 
-import { assert, fail } from "@fluidframework/core-utils/internal";
+import {
+	assert,
+	debugAssert,
+	fail,
+	unreachableCase,
+} from "@fluidframework/core-utils/internal";
 import { createIdCompressor } from "@fluidframework/id-compressor/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 import {
+	asIndex,
 	getKernel,
 	type TreeNode,
 	type Unhydrated,
@@ -40,15 +46,20 @@ import {
 	getIdentifierFromNode,
 	unhydratedFlexTreeFromInsertable,
 	getOrCreateNodeFromInnerNode,
+	getOrCreateNodeFromInnerUnboxedNode,
+	getOrCreateInnerNode,
+	NodeKind,
+	tryGetTreeNodeForField,
+	isObjectNodeSchema,
 } from "../simple-tree/index.js";
-import { extractFromOpaque, type JsonCompatible } from "../util/index.js";
+import { brand, extractFromOpaque, type JsonCompatible } from "../util/index.js";
 import {
 	FluidClientVersion,
 	noopValidator,
 	type ICodecOptions,
 	type CodecWriteOptions,
 } from "../codec/index.js";
-import type { ITreeCursorSynchronous } from "../core/index.js";
+import { EmptyKey, type ITreeCursorSynchronous } from "../core/index.js";
 import {
 	cursorForMapTreeField,
 	defaultSchemaPolicy,
@@ -60,6 +71,7 @@ import {
 	type FieldBatchEncodingContext,
 	fluidVersionToFieldBatchCodecWriteVersion,
 	type LocalNodeIdentifier,
+	type FlexTreeSequenceField,
 } from "../feature-libraries/index.js";
 import { independentInitializedView, type ViewContent } from "./independentView.js";
 import { SchematizingSimpleTreeView, ViewSlot } from "./schematizingTreeView.js";
@@ -343,6 +355,48 @@ export interface TreeAlpha {
 	 * Otherwise, this returns the key of the field that it is under (a `string`).
 	 */
 	key2(node: TreeNode): string | number | undefined;
+
+	/**
+	 * Gets the child of the given node with the given property key if a child exists under that key.
+	 *
+	 * @remarks {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields | Unknown optional fields} of Object nodes will not be returned by this method.
+	 *
+	 * @param node - The parent node whose child is being requested.
+	 * @param key - The property key under the node under which the child is being requested.
+	 * For Object nodes, this is the developer-facing "property key", not the "{@link SimpleObjectFieldSchema.storedKey | stored keys}".
+	 *
+	 * @returns The child node or leaf value under the given key, or `undefined` if no such child exists.
+	 *
+	 * @see {@link (TreeAlpha:interface).key2}
+	 * @see {@link (TreeNodeApi:interface).parent}
+	 */
+	child(node: TreeNode, key: string | number): TreeNode | TreeLeafValue | undefined;
+
+	/**
+	 * Gets the children of the provided node, paired with their property keys under the node.
+	 *
+	 * @remarks
+	 * No guarantees are made regarding the order of the children in the returned array.
+	 *
+	 * Optional properties of Object nodes with no value are not included in the result.
+	 *
+	 * {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields | Unknown optional fields} of Object nodes are not included in the result.
+	 *
+	 * @param node - The node whose children are being requested.
+	 *
+	 * @returns
+	 * An array of pairs of the form `[propertyKey, child]`.
+	 *
+	 * For Array nodes, the `propertyKey` is the index of the child in the array.
+	 *
+	 * For Object nodes, the returned `propertyKey`s are the developer-facing "property keys", not the "{@link SimpleObjectFieldSchema.storedKey | stored keys}".
+	 *
+	 * @see {@link (TreeAlpha:interface).key2}
+	 * @see {@link (TreeNodeApi:interface).parent}
+	 */
+	children(
+		node: TreeNode,
+	): Iterable<[propertyKey: string | number, child: TreeNode | TreeLeafValue]>;
 }
 
 /**
@@ -492,6 +546,134 @@ export const TreeAlpha: TreeAlpha = {
 		const parentSchema = treeNodeApi.schema(parent);
 		return getPropertyKeyFromStoredKey(parentSchema, storedKey);
 	},
+
+	child: (
+		node: TreeNode,
+		propertyKey: string | number,
+	): TreeNode | TreeLeafValue | undefined => {
+		const flexNode = getOrCreateInnerNode(node);
+		debugAssert(
+			() => !flexNode.context.isDisposed() || "The provided tree node has been disposed.",
+		);
+
+		const schema = treeNodeApi.schema(node);
+
+		switch (schema.kind) {
+			case NodeKind.Array: {
+				const sequence = flexNode.tryGetField(EmptyKey) as FlexTreeSequenceField | undefined;
+
+				// Empty sequence - cannot have children.
+				if (sequence === undefined) {
+					return undefined;
+				}
+
+				const index =
+					typeof propertyKey === "number"
+						? propertyKey
+						: asIndex(propertyKey, Number.POSITIVE_INFINITY);
+
+				// If the key is not a valid index, then there is no corresponding child.
+				if (index === undefined) {
+					return undefined;
+				}
+
+				const childFlexTree = sequence.at(index);
+
+				// No child at the given index.
+				if (childFlexTree === undefined) {
+					return undefined;
+				}
+
+				return getOrCreateNodeFromInnerUnboxedNode(childFlexTree);
+			}
+			case NodeKind.Map:
+				if (typeof propertyKey !== "string") {
+					// Map nodes only support string keys.
+					return undefined;
+				}
+			// Fall through
+			case NodeKind.Object: {
+				let storedKey: string | number = propertyKey;
+				if (isObjectNodeSchema(schema)) {
+					const fieldSchema = schema.fields.get(String(propertyKey));
+					if (fieldSchema === undefined) {
+						return undefined;
+					}
+
+					storedKey = fieldSchema.storedKey;
+				}
+
+				const field = flexNode.tryGetField(brand(String(storedKey)));
+				if (field !== undefined) {
+					return tryGetTreeNodeForField(field);
+				}
+
+				return undefined;
+			}
+			case NodeKind.Leaf: {
+				fail("Leaf schema associated with non-leaf tree node.");
+			}
+			default: {
+				unreachableCase(schema.kind);
+			}
+		}
+	},
+
+	children(node: TreeNode): [propertyKey: string | number, child: TreeNode | TreeLeafValue][] {
+		const flexNode = getOrCreateInnerNode(node);
+		debugAssert(
+			() => !flexNode.context.isDisposed() || "The provided tree node has been disposed.",
+		);
+
+		const schema = treeNodeApi.schema(node);
+
+		const result: [string | number, TreeNode | TreeLeafValue][] = [];
+		switch (schema.kind) {
+			case NodeKind.Array: {
+				const sequence = flexNode.tryGetField(EmptyKey) as FlexTreeSequenceField | undefined;
+				if (sequence === undefined) {
+					break;
+				}
+
+				for (let index = 0; index < sequence.length; index++) {
+					const childFlexTree = sequence.at(index);
+					assert(childFlexTree !== undefined, "Sequence child was undefined.");
+					const childTree = getOrCreateNodeFromInnerUnboxedNode(childFlexTree);
+					result.push([index, childTree]);
+				}
+				break;
+			}
+			case NodeKind.Map: {
+				for (const [key, flexField] of flexNode.fields) {
+					const childTreeNode = tryGetTreeNodeForField(flexField);
+					if (childTreeNode !== undefined) {
+						result.push([key, childTreeNode]);
+					}
+				}
+				break;
+			}
+			case NodeKind.Object: {
+				assert(isObjectNodeSchema(schema), "Expected object schema.");
+				for (const [propertyKey, fieldSchema] of schema.fields) {
+					const storedKey = fieldSchema.storedKey;
+					const flexField = flexNode.tryGetField(brand(String(storedKey)));
+					if (flexField !== undefined) {
+						const childTreeNode = tryGetTreeNodeForField(flexField);
+						assert(childTreeNode !== undefined, "Expected child tree node for field.");
+						result.push([propertyKey, childTreeNode]);
+					}
+				}
+				break;
+			}
+			case NodeKind.Leaf: {
+				fail("Leaf schema associated with non-leaf tree node.");
+			}
+			default: {
+				unreachableCase(schema.kind);
+			}
+		}
+		return result;
+	},
 };
 
 function exportConcise(

packages/dds/tree/src/simple-tree/api/index.ts

@@ -45,12 +45,12 @@ export {
 	singletonSchema,
 } from "./schemaCreationUtilities.js";
 export {
+	getIdentifierFromNode,
+	getPropertyKeyFromStoredKey,
+	getStoredKey,
 	treeNodeApi,
 	type TreeNodeApi,
 	tryGetSchema,
-	getStoredKey,
-	getPropertyKeyFromStoredKey,
-	getIdentifierFromNode,
 } from "./treeNodeApi.js";
 export { createFromCursor } from "./create.js";
 export {

packages/dds/tree/src/simple-tree/api/treeNodeApi.ts

@@ -39,7 +39,7 @@ import {
 } from "../core/index.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
 import { isObjectNodeSchema } from "../node-kinds/index.js";
-import { getTreeNodeForField } from "../getTreeNodeForField.js";
+import { tryGetTreeNodeForField } from "../getTreeNodeForField.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
@@ -83,6 +83,9 @@ export interface TreeNodeApi {
 	 * Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).
 	 *
 	 * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the node has been {@link TreeStatus.Deleted | deleted}.
+	 *
+	 * @see {@link (TreeAlpha:interface).child}
+	 * @see {@link (TreeAlpha:interface).children}
 	 */
 	parent(node: TreeNode): TreeNode | undefined;
 
@@ -316,7 +319,7 @@ export function getIdentifierFromNode(
 			const key = identifierFieldKeys[0] ?? oob();
 			const identifierField = flexNode.tryGetField(key);
 			assert(identifierField !== undefined, 0xbb5 /* missing identifier field */);
-			const identifierValue = getTreeNodeForField(identifierField);
+			const identifierValue = tryGetTreeNodeForField(identifierField);
 			assert(typeof identifierValue === "string", 0xbb6 /* identifier not a string */);
 
 			const context = flexNode.context;