Add schema-derived types for editable tree 2 proxies (#17736)

## Description

This creates adaptations of the editable-tree-2 schema-derived types
which:

1. Produce the "proxy" API objects
2. "Unbox" unconditionally

It also renames "List" to "SharedTreeList".

Author: noencke

experimental/dds/tree2/src/feature-libraries/editable-tree-2/index.ts

@@ -26,7 +26,18 @@ export {
 	TreeStatus,
 } from "./editableTreeTypes";
 
-export { getProxyForField, List } from "./proxies";
+export {
+	getProxyForField,
+	SharedTreeList,
+	ObjectFields,
+	ProxyField,
+	ProxyFieldInner,
+	ProxyNode,
+	ProxyNodeUnion,
+	SharedTreeMap,
+	SharedTreeObject,
+	is,
+} from "./proxies";
 export { createRawStruct, rawStructErrorMessage, nodeContent } from "./rawStruct";
 
 export {

experimental/dds/tree2/src/feature-libraries/editable-tree-2/proxies/index.ts

@@ -3,5 +3,14 @@
  * Licensed under the MIT License.
  */
 
-export { getProxyForField } from "./proxies";
-export { List } from "./types";
+export { getProxyForField, is } from "./proxies";
+export {
+	SharedTreeList,
+	ObjectFields,
+	ProxyField,
+	ProxyFieldInner,
+	ProxyNode,
+	ProxyNodeUnion,
+	SharedTreeMap,
+	SharedTreeObject,
+} from "./types";

experimental/dds/tree2/src/feature-libraries/editable-tree-2/proxies/proxies.ts

@@ -9,6 +9,7 @@ import {
 	FieldNodeSchema,
 	FieldSchema,
 	StructSchema,
+	TreeSchema,
 	schemaIsFieldNode,
 	schemaIsLeaf,
 	schemaIsMap,
@@ -18,7 +19,7 @@ import { FieldKinds } from "../../default-field-kinds";
 import { FieldNode, TreeNode, TypedField, TypedNodeUnion } from "../editableTreeTypes";
 import { LazySequence } from "../lazyField";
 import { FieldKey } from "../../../core";
-import { List } from "./types";
+import { ProxyField, ProxyNode, SharedTreeList, SharedTreeObject } from "./types";
 
 /** Symbol used to store a private/internal reference to the underlying editable tree node. */
 const treeNodeSym = Symbol("TreeNode");
@@ -38,19 +39,32 @@ export function setTreeNode(target: any, treeNode: TreeNode) {
 	});
 }
 
+/**
+ * Checks if the given object is a {@link SharedTreeObject}
+ */
+export function is<TSchema extends StructSchema>(
+	x: unknown,
+	schema: TSchema,
+): x is SharedTreeObject<TSchema> {
+	// TODO: Do this a better way. Perhaps, should `treeNodeSym` be attached to object proxies via `setTreeNode`?
+	return (x as any)[treeNodeSym].schema === schema;
+}
+
 // TODO: Implement lifetime.  The proxy that should be cached on their respective nodes and reused.
 // Object identity is tied to the proxy instance (not the target object)
 
 /** Retrieve the associated proxy for the given field. */
-export function getProxyForField<T extends FieldSchema>(field: TypedField<T>) {
+export function getProxyForField<TSchema extends FieldSchema>(
+	field: TypedField<TSchema>,
+): ProxyField<TSchema> {
 	switch (field.schema.kind) {
 		case FieldKinds.required: {
 			const asValue = field as TypedField<FieldSchema<typeof FieldKinds.required>>;
 
 			// TODO: Ideally, we would return leaves without first boxing them.  However, this is not
 			//       as simple as calling '.content' since this skips the node and returns the FieldNode's
 			//       inner field.
-			return getProxyForNode(asValue.boxedContent);
+			return getProxyForNode(asValue.boxedContent) as ProxyField<TSchema>;
 		}
 		case FieldKinds.optional: {
 			fail(`"not implemented"`);
@@ -63,28 +77,30 @@ export function getProxyForField<T extends FieldSchema>(field: TypedField<T>) {
 	}
 }
 
-export function getProxyForNode(treeNode: TreeNode) {
+export function getProxyForNode<TSchema extends TreeSchema>(
+	treeNode: TreeNode,
+): ProxyNode<TSchema> {
 	const schema = treeNode.schema;
 
 	if (schemaIsMap(schema)) {
 		fail("Map not implemented");
 	}
 	if (schemaIsLeaf(schema)) {
-		return treeNode.value;
+		return treeNode.value as ProxyNode<TSchema>;
 	}
 	if (schemaIsFieldNode(schema)) {
-		return createListProxy(treeNode);
+		return createListProxy(treeNode) as ProxyNode<TSchema>;
 	}
 	if (schemaIsStruct(schema)) {
-		return createObjectProxy(treeNode, schema);
+		return createObjectProxy(treeNode, schema) as ProxyNode<TSchema>;
 	}
 	fail("unrecognized node kind");
 }
 
-export function createObjectProxy<TTypes extends AllowedTypes>(
+export function createObjectProxy<TSchema extends StructSchema, TTypes extends AllowedTypes>(
 	content: TypedNodeUnion<TTypes>,
-	schema: StructSchema,
-) {
+	schema: TSchema,
+): SharedTreeObject<TSchema> {
 	// To satisfy 'deepEquals' level scrutiny, the target of the proxy must be an object with the same
 	// 'null prototype' you would get from on object literal '{}' or 'Object.create(null)'.  This is
 	// because 'deepEquals' uses 'Object.getPrototypeOf' as a way to quickly reject objects with different
@@ -97,7 +113,14 @@ export function createObjectProxy<TTypes extends AllowedTypes>(
 		{
 			get(target, key): unknown {
 				const field = content.tryGetField(key as FieldKey);
-				return field === undefined ? undefined : getProxyForField(field);
+				if (field !== undefined) {
+					return getProxyForField(field);
+				}
+				// TODO: Do this a better way.
+				if (key === treeNodeSym) {
+					return { schema };
+				}
+				return undefined;
 			},
 			set(target, key, value) {
 				// TODO: Implement set
@@ -126,7 +149,7 @@ export function createObjectProxy<TTypes extends AllowedTypes>(
 				return p;
 			},
 		},
-	) as unknown;
+	) as SharedTreeObject<TSchema>;
 }
 
 const getField = <TTypes extends AllowedTypes>(target: object) => {
@@ -257,7 +280,9 @@ function asIndex(key: string | symbol, length: number) {
 	}
 }
 
-export function createListProxy<TTypes extends AllowedTypes>(treeNode: TreeNode): List<TTypes> {
+export function createListProxy<TTypes extends AllowedTypes>(
+	treeNode: TreeNode,
+): SharedTreeList<TTypes> {
 	// Create a 'dispatch' object that this Proxy forwards to instead of the proxy target.
 	// Own properties on the dispatch object are surfaced as own properties of the proxy.
 	// (e.g., 'length', which is defined below).
@@ -279,7 +304,7 @@ export function createListProxy<TTypes extends AllowedTypes>(treeNode: TreeNode)
 	// To satisfy 'deepEquals' level scrutiny, the target of the proxy must be an array literal in order
 	// to pass 'Object.getPrototypeOf'.  It also satisfies 'Array.isArray' and 'Object.prototype.toString'
 	// requirements without use of Array[Symbol.species], which is potentially on a path ot deprecation.
-	return new Proxy<List<TTypes>>([] as any, {
+	return new Proxy<SharedTreeList<TTypes>>([] as any, {
 		get: (target, key) => {
 			const field = getField(dispatch);
 			const maybeIndex = asIndex(key, field.length);

experimental/dds/tree2/src/feature-libraries/editable-tree-2/proxies/types.ts

@@ -3,16 +3,32 @@
  * Licensed under the MIT License.
  */
 
-import { AllowedTypes } from "../../typed-schema";
+import { SchemaAware } from "../..";
+import { RestrictiveReadonlyRecord } from "../../../util";
+import { FieldKinds } from "../../default-field-kinds";
+import { FieldKind } from "../../modular-schema";
+import {
+	AllowedTypes,
+	Any,
+	FieldNodeSchema,
+	FieldSchema,
+	InternalTypedSchemaTypes,
+	LeafSchema,
+	MapSchema,
+	StructSchema,
+	TreeSchema,
+} from "../../typed-schema";
 import {
-	UnboxNodeUnion,
 	CheckTypesOverlap,
 	FlexibleNodeContent,
 	Sequence,
+	NodeKeyField,
+	AssignableFieldKinds,
 } from "../editableTreeTypes";
 
 /** Implements 'readonly T[]' and the list mutation APIs. */
-export interface List<TTypes extends AllowedTypes> extends ReadonlyArray<UnboxNodeUnion<TTypes>> {
+export interface SharedTreeList<TTypes extends AllowedTypes>
+	extends ReadonlyArray<ProxyNodeUnion<TTypes>> {
 	/**
 	 * Inserts new item(s) at a specified location.
 	 * @param index - The index at which to insert `value`.
@@ -131,3 +147,100 @@ export interface List<TTypes extends AllowedTypes> extends ReadonlyArray<UnboxNo
 	// 	source: Sequence<CheckTypesOverlap<TTypesSource, TTypes>>,
 	// ): void;
 }
+
+/**
+ * An object which supports property-based access to fields.
+ * @alpha
+ */
+export type SharedTreeObject<TSchema extends StructSchema> = ObjectFields<
+	TSchema["structFieldsObject"]
+>;
+
+/**
+ * Helper for generating the properties of a {@link SharedTreeObject}.
+ * @alpha
+ */
+export type ObjectFields<TFields extends RestrictiveReadonlyRecord<string, FieldSchema>> = {
+	// Add getter only (make property readonly) when the field is **not** of a kind that has a logical set operation.
+	// If we could map to getters and setters separately, we would preferably do that, but we can't.
+	// See https://github.com/microsoft/TypeScript/issues/43826 for more details on this limitation.
+	readonly [key in keyof TFields as TFields[key]["kind"] extends AssignableFieldKinds
+		? never
+		: key]: ProxyField<TFields[key]>;
+} & {
+	// Add setter (make property writable) when the field is of a kind that has a logical set operation.
+	// If we could map to getters and setters separately, we would preferably do that, but we can't.
+	// See https://github.com/microsoft/TypeScript/issues/43826 for more details on this limitation.
+	-readonly [key in keyof TFields as TFields[key]["kind"] extends AssignableFieldKinds
+		? key
+		: never]: ProxyField<TFields[key]>;
+};
+
+/**
+ * A map of string keys to tree objects.
+ * @alpha
+ */
+export type SharedTreeMap<TSchema extends MapSchema> = Map<string, ProxyNode<TSchema>>;
+
+/**
+ * Given a field's schema, return the corresponding object in the proxy-based API.
+ * @alpha
+ */
+export type ProxyField<
+	TSchema extends FieldSchema,
+	// If "notEmpty", then optional fields will unbox to their content (not their content | undefined)
+	Emptiness extends "maybeEmpty" | "notEmpty" = "maybeEmpty",
+> = ProxyFieldInner<TSchema["kind"], TSchema["allowedTypes"], Emptiness>;
+
+/**
+ * Helper for implementing {@link InternalEditableTreeTypes#ProxyField}.
+ * @alpha
+ */
+export type ProxyFieldInner<
+	Kind extends FieldKind,
+	TTypes extends AllowedTypes,
+	Emptiness extends "maybeEmpty" | "notEmpty",
+> = Kind extends typeof FieldKinds.sequence
+	? SharedTreeList<TTypes>
+	: Kind extends typeof FieldKinds.required
+	? ProxyNodeUnion<TTypes>
+	: Kind extends typeof FieldKinds.optional
+	? ProxyNodeUnion<TTypes> | (Emptiness extends "notEmpty" ? never : undefined)
+	: // Since struct already provides a short-hand accessor for the local field key, and the field provides a nicer general API than the node under it in this case, do not unbox nodeKey fields.
+	Kind extends typeof FieldKinds.nodeKey
+	? NodeKeyField
+	: // TODO: forbidden
+	  unknown;
+
+/**
+ * Given multiple node schema types, return the corresponding object type union in the proxy-based API.
+ * @alpha
+ */
+export type ProxyNodeUnion<TTypes extends AllowedTypes> = TTypes extends readonly [Any]
+	? unknown
+	: {
+			// TODO: Is the the best way to write this type function? Can it be simplified?
+			// This first maps the tuple of AllowedTypes to a tuple of node API types.
+			// Then, it uses [number] to index arbitrarily into that tuple, effectively converting the type tuple into a type union.
+			[Index in keyof TTypes]: TTypes[Index] extends InternalTypedSchemaTypes.LazyItem<
+				infer InnerType
+			>
+				? InnerType extends TreeSchema
+					? ProxyNode<InnerType>
+					: never
+				: never;
+	  }[number];
+
+/**
+ * Given a node's schema, return the corresponding object in the proxy-based API.
+ * @alpha
+ */
+export type ProxyNode<TSchema extends TreeSchema> = TSchema extends LeafSchema
+	? SchemaAware.InternalTypes.TypedValue<TSchema["leafValue"]>
+	: TSchema extends MapSchema
+	? SharedTreeMap<TSchema>
+	: TSchema extends FieldNodeSchema
+	? ProxyField<TSchema["structFieldsObject"][""]>
+	: TSchema extends StructSchema
+	? SharedTreeObject<TSchema>
+	: unknown;

experimental/dds/tree2/src/feature-libraries/index.ts

@@ -254,6 +254,15 @@ export {
 	CheckTypesOverlap,
 	TreeStatus,
 	getProxyForField,
+	ObjectFields,
+	ProxyField,
+	ProxyFieldInner,
+	ProxyNode,
+	ProxyNodeUnion,
+	SharedTreeList,
+	SharedTreeMap,
+	SharedTreeObject,
+	is,
 } from "./editable-tree-2";
 
 // Split into separate import and export for compatibility with API-Extractor.

experimental/dds/tree2/src/test/feature-libraries/editable-tree-2/list.spec.ts

@@ -4,10 +4,8 @@
  */
 
 import { strict as assert } from "assert";
-import { SchemaBuilder } from "../../../feature-libraries";
+import { ProxyField, SchemaBuilder, SharedTreeList } from "../../../feature-libraries";
 import { leaf } from "../../../domains";
-// eslint-disable-next-line import/no-internal-modules
-import { TypedNode, List } from "../../../feature-libraries/editable-tree-2";
 import { createTreeView } from "./utils";
 
 const builder = new SchemaBuilder({ scope: "test", libraries: [leaf.library] });
@@ -23,9 +21,8 @@ const root = builder.struct("root", {
 	numbers: numberList,
 });
 
-type Root = TypedNode<typeof root>;
-
 const schema = builder.toDocumentSchema(root);
+type Root = ProxyField<(typeof schema)["rootFieldSchema"]>;
 
 describe("List", () => {
 	/** Similar to JSON stringify, but preserves 'undefined' and leaves numbers as-is. */
@@ -81,7 +78,7 @@ describe("List", () => {
 
 	// TODO: Combine createList helpers once we unbox unions.
 	/** Helper that creates a new List<number> proxy */
-	function createNumberList(items: readonly number[]): List<[typeof leaf.number]> {
+	function createNumberList(items: readonly number[]): SharedTreeList<[typeof leaf.number]> {
 		const list = createTree().numbers;
 		list.insertAtStart(items);
 		assert.deepEqual(list, items);
@@ -90,7 +87,7 @@ describe("List", () => {
 
 	// TODO: Combine createList helpers once we unbox unions.
 	/** Helper that creates a new List<string> proxy */
-	function createStringList(items: readonly string[]): List<[typeof leaf.string]> {
+	function createStringList(items: readonly string[]): SharedTreeList<[typeof leaf.string]> {
 		const list = createTree().strings;
 		list.insertAtStart(items);
 		assert.deepEqual(list, items);