@fluidframework/tree-agent 2.80.0 → 2.81.0

package/src/propertyBinding.ts

@@ -9,6 +9,8 @@ import type { ZodType, ZodTypeAny, ZodTypeDef, infer as ZodInfer } from "zod";
 
 import type { BindableSchema, Ctor } from "./methodBinding.js";
 import { instanceOf } from "./renderZodTypeScript.js";
+import type { TypeFactoryType } from "./treeAgentTypes.js";
+import { isTypeFactoryType } from "./treeAgentTypes.js";
 
 /**
  * A symbol used to expose properties to the LLM.
@@ -73,9 +75,21 @@ export type TypeMatchOrError<Expected, Received> = [Received] extends [Expected]
  */
 export class PropertyDef {
 	public constructor(
+		/**
+		 * The name of the property.
+		 */
 		public readonly name: string,
+		/**
+		 * Optional description of the property.
+		 */
 		public readonly description: string | undefined,
-		public readonly schema: ZodTypeAny,
+		/**
+		 * The schema defining the property's type (either Zod or TypeFactory).
+		 */
+		public readonly schema: ZodTypeAny | TypeFactoryType,
+		/**
+		 * Whether the property is readonly.
+		 */
 		public readonly readOnly: boolean,
 	) {}
 }
@@ -85,6 +99,9 @@ export class PropertyDef {
  * @alpha
  */
 export interface ExposedProperties {
+	/**
+	 * Expose a property with Zod type checking.
+	 */
 	exposeProperty<
 		S extends BindableSchema & Ctor,
 		K extends string & ExposableKeys<InstanceType<S>>,
@@ -96,6 +113,29 @@ export interface ExposedProperties {
 			TypeMatchOrError<InstanceType<S>[K], ZodInfer<TZ>>,
 	): void;
 
+	/**
+	 * Expose a property with type factory type and metadata.
+	 */
+	exposeProperty<
+		S extends BindableSchema & Ctor,
+		K extends string & ExposableKeys<InstanceType<S>>,
+	>(
+		schema: S,
+		name: K,
+		def: { schema: TypeFactoryType; description?: string; readOnly?: boolean },
+	): void;
+
+	/**
+	 * Expose a property with type factory type (simple form).
+	 */
+	exposeProperty<
+		S extends BindableSchema & Ctor,
+		K extends string & ExposableKeys<InstanceType<S>>,
+	>(schema: S, name: K, tfType: TypeFactoryType): void;
+
+	/**
+	 * Create a Zod type that references a SharedTree schema class.
+	 */
 	instanceOf<T extends TreeNodeSchemaClass>(
 		schema: T,
 	): ZodType<InstanceType<T>, ZodTypeDef, InstanceType<T>>;
@@ -116,6 +156,9 @@ export interface ExposedProperties {
  * @alpha
  */
 export interface IExposedProperties {
+	/**
+	 * Static method that exposes properties of this schema class to an agent.
+	 */
 	[exposePropertiesSymbol]?(properties: ExposedProperties): void;
 }
 
@@ -132,18 +175,32 @@ class ExposedPropertiesI implements ExposedProperties {
 	>(
 		schema: S,
 		name: K,
-		def: { schema: TZ; description?: string } & ReadOnlyRequirement<InstanceType<S>, K> &
-			TypeMatchOrError<InstanceType<S>[K], ZodInfer<TZ>>,
+		defOrType:
+			| ({ schema: TZ; description?: string } & ReadOnlyRequirement<InstanceType<S>, K> &
+					TypeMatchOrError<InstanceType<S>[K], ZodInfer<TZ>>)
+			| TypeFactoryType,
 	): void {
 		if (schema !== this.schemaClass) {
 			throw new Error('Must expose properties on the "this" schema class');
 		}
-		this.properties[name] = new PropertyDef(
-			name,
-			def.description,
-			def.schema,
-			def.readOnly === true,
-		);
+
+		// Handle TypeFactoryType (simple case - type passed directly)
+		if (isTypeFactoryType(defOrType)) {
+			this.properties[name] = new PropertyDef(name, undefined, defOrType, false);
+		} else {
+			// Handle object with schema property (works for both Zod and TypeFactory)
+			const def = defOrType as {
+				schema: TZ | TypeFactoryType;
+				description?: string;
+				readOnly?: boolean;
+			};
+			this.properties[name] = new PropertyDef(
+				name,
+				def.description,
+				def.schema,
+				def.readOnly === true,
+			);
+		}
 	}
 
 	public instanceOf<T extends TreeNodeSchemaClass>(

package/src/renderSchemaTypeScript.ts

@@ -18,7 +18,13 @@ import { z } from "zod";
 import type { BindableSchema, FunctionWrapper } from "./methodBinding.js";
 import { getExposedMethods } from "./methodBinding.js";
 import { getExposedProperties, type PropertyDef } from "./propertyBinding.js";
+import {
+	instanceOfsTypeFactory,
+	renderTypeFactoryTypeScript,
+} from "./renderTypeFactoryTypeScript.js";
 import { instanceOfs, renderZodTypeScript } from "./renderZodTypeScript.js";
+import type { TypeFactoryOptional, TypeFactoryType } from "./treeAgentTypes.js";
+import { isTypeFactoryType } from "./treeAgentTypes.js";
 import { getFriendlyName, isNamedSchema, llmDefault, unqualifySchema } from "./utils.js";
 
 interface BoundMembers {
@@ -284,7 +290,9 @@ export function renderSchemaTypeScript(
 					lines.push(`// ${note}`);
 				}
 			}
-			lines.push(formatMethod(name, method));
+			const methodString = formatMethod(name, method);
+			const methodLines = methodString.split("\n");
+			lines.push(...methodLines);
 		}
 		if (lines.length > 0) {
 			hasHelperMethods = true;
@@ -434,7 +442,11 @@ function renderPropertyLines(properties: Record<string, PropertyDef>): string[]
 			}
 		}
 		const modifier = property.readOnly ? "readonly " : "";
-		lines.push(`${modifier}${name}: ${renderZodType(property.schema)};`);
+		const typeString = renderType(property.schema, 0);
+		const propertyLine = `${modifier}${name}: ${typeString};`;
+		// Split multi-line type strings and add to lines array
+		const propertyLines = propertyLine.split("\n");
+		lines.push(...propertyLines);
 	}
 	return lines;
 }
@@ -443,13 +455,13 @@ function formatMethod(name: string, method: FunctionWrapper): string {
 	const args: string[] = [];
 	for (const [argName, argType] of method.args) {
 		const { innerType, optional } = unwrapOptional(argType);
-		const renderedType = renderZodType(innerType);
+		const renderedType = renderType(innerType, 0);
 		args.push(`${argName}${optional ? "?" : ""}: ${renderedType}`);
 	}
 	if (method.rest !== null) {
-		args.push(`...rest: ${renderZodType(method.rest)}[]`);
+		args.push(`...rest: ${renderType(method.rest, 0)}[]`);
 	}
-	return `${name}(${args.join(", ")}): ${renderZodType(method.returns)};`;
+	return `${name}(${args.join(", ")}): ${renderType(method.returns, 0)};`;
 }
 
 function renderLeaf(leafKind: ValueSchema): string {
@@ -482,7 +494,15 @@ function formatExpression(
 /**
  * Detects optional zod wrappers so argument lists can keep TypeScript optional markers in sync.
  */
-function unwrapOptional(type: z.ZodTypeAny): { innerType: z.ZodTypeAny; optional: boolean } {
+function unwrapOptional(type: z.ZodTypeAny | TypeFactoryType): {
+	innerType: z.ZodTypeAny | TypeFactoryType;
+	optional: boolean;
+} {
+	// Handle type factory optional type
+	if (isTypeFactoryType(type) && type._kind === "optional") {
+		return { innerType: (type as TypeFactoryOptional).innerType, optional: true };
+	}
+	// Handle Zod optional type
 	if (type instanceof z.ZodOptional) {
 		const inner = type.unwrap() as z.ZodTypeAny;
 		return { innerType: inner, optional: true };
@@ -516,8 +536,10 @@ function ensureNoMemberConflicts(
 }
 
 /**
- * Converts schema metadata into TypeScript declarations suitable for prompt inclusion.
+ * Dispatches to the correct renderer based on whether the type is Zod or type factory.
  */
-function renderZodType(type: z.ZodTypeAny): string {
-	return renderZodTypeScript(type, getFriendlyName, instanceOfs);
+function renderType(type: z.ZodTypeAny | TypeFactoryType, indentLevel: number = 0): string {
+	return isTypeFactoryType(type)
+		? renderTypeFactoryTypeScript(type, getFriendlyName, instanceOfsTypeFactory, indentLevel)
+		: renderZodTypeScript(type, getFriendlyName, instanceOfs);
 }

package/src/renderTypeFactoryTypeScript.ts

@@ -0,0 +1,339 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import type { ObjectNodeSchema, TreeNodeSchema } from "@fluidframework/tree/alpha";
+
+import type {
+	TypeFactoryType,
+	TypeFactoryArray,
+	TypeFactoryPromise,
+	TypeFactoryObject,
+	TypeFactoryTuple,
+	TypeFactoryRecord,
+	TypeFactoryMap,
+	TypeFactoryLiteral,
+	TypeFactoryOptional,
+	TypeFactoryReadonly,
+	TypeFactoryUnion,
+	TypeFactoryIntersection,
+	TypeFactoryFunction,
+} from "./treeAgentTypes.js";
+
+export { instanceOfsTypeFactory } from "./treeAgentTypes.js";
+
+/**
+ * Converts type factory type definitions into TypeScript declaration text.
+ * @alpha
+ */
+export function renderTypeFactoryTypeScript(
+	typeFactoryType: TypeFactoryType,
+	getFriendlyName: (schema: TreeNodeSchema) => string,
+	instanceOfLookup: WeakMap<TypeFactoryType, ObjectNodeSchema>,
+	initialIndent: number = 0,
+): string {
+	let result = "";
+	let startOfLine = false;
+	let indent = initialIndent;
+
+	appendType(typeFactoryType, TypePrecedence.Union);
+	return result;
+
+	function appendType(type: TypeFactoryType, minPrecedence = TypePrecedence.Object): void {
+		const shouldParenthesize = getTypePrecedence(type) < minPrecedence;
+		if (shouldParenthesize) {
+			append("(");
+		}
+		appendTypeDefinition(type);
+		if (shouldParenthesize) {
+			append(")");
+		}
+	}
+
+	function append(s: string): void {
+		if (startOfLine) {
+			result += "    ".repeat(indent);
+			startOfLine = false;
+		}
+		result += s;
+	}
+
+	function appendNewLine(): void {
+		append("\n");
+		startOfLine = true;
+	}
+
+	function appendTypeDefinition(type: TypeFactoryType): void {
+		switch (type._kind) {
+			case "string": {
+				append("string");
+				return;
+			}
+			case "number": {
+				append("number");
+				return;
+			}
+			case "boolean": {
+				append("boolean");
+				return;
+			}
+			case "date": {
+				append("Date");
+				return;
+			}
+			case "void": {
+				append("void");
+				return;
+			}
+			case "undefined": {
+				append("undefined");
+				return;
+			}
+			case "null": {
+				append("null");
+				return;
+			}
+			case "unknown": {
+				append("unknown");
+				return;
+			}
+			case "array": {
+				appendArrayType(type as TypeFactoryArray);
+				return;
+			}
+			case "promise": {
+				appendPromiseType(type as TypeFactoryPromise);
+				return;
+			}
+			case "object": {
+				appendObjectType(type as TypeFactoryObject);
+				return;
+			}
+			case "union": {
+				appendUnionTypes((type as TypeFactoryUnion).options, TypePrecedence.Union);
+				return;
+			}
+			case "intersection": {
+				appendIntersectionTypes(
+					(type as TypeFactoryIntersection).types,
+					TypePrecedence.Intersection,
+				);
+				return;
+			}
+			case "tuple": {
+				appendTupleType(type as TypeFactoryTuple);
+				return;
+			}
+			case "record": {
+				appendRecordType(type as TypeFactoryRecord);
+				return;
+			}
+			case "map": {
+				appendMapType(type as TypeFactoryMap);
+				return;
+			}
+			case "literal": {
+				appendLiteral((type as TypeFactoryLiteral).value);
+				return;
+			}
+			case "optional": {
+				appendUnionTypes(
+					[(type as TypeFactoryOptional).innerType, { _kind: "undefined" }],
+					TypePrecedence.Union,
+				);
+				return;
+			}
+			case "readonly": {
+				appendReadonlyType(type as TypeFactoryReadonly);
+				return;
+			}
+			case "function": {
+				appendFunctionType(type as TypeFactoryFunction);
+				return;
+			}
+			case "instanceof": {
+				const schema = instanceOfLookup.get(type);
+				if (schema === undefined) {
+					throw new UsageError(
+						"instanceof type not found in lookup - this typically indicates the type was not created via typeFactory.instanceOf",
+					);
+				}
+				append(getFriendlyName(schema));
+				return;
+			}
+			default: {
+				throw new UsageError(
+					`Unsupported type when formatting helper types: ${String(type._kind ?? "unknown")}. Expected one of: string, number, boolean, void, undefined, null, unknown, array, object, union, tuple, record, map, literal, optional, readonly, instanceof.`,
+				);
+			}
+		}
+	}
+
+	function appendArrayType(arrayType: TypeFactoryArray): void {
+		appendType(arrayType.element, TypePrecedence.Object);
+		append("[]");
+	}
+
+	function appendPromiseType(promiseType: TypeFactoryPromise): void {
+		append("Promise<");
+		appendType(promiseType.innerType, TypePrecedence.Union);
+		append(">");
+	}
+
+	function appendObjectType(objectType: TypeFactoryObject): void {
+		append("{");
+		appendNewLine();
+		indent++;
+		for (const [name, propertyType] of Object.entries(objectType.shape)) {
+			append(name);
+			if (propertyType._kind === "optional") {
+				append("?");
+				append(": ");
+				appendType((propertyType as TypeFactoryOptional).innerType);
+			} else {
+				append(": ");
+				appendType(propertyType);
+			}
+			append(";");
+			appendNewLine();
+		}
+		indent--;
+		append("}");
+	}
+
+	function appendUnionTypes(
+		types: readonly TypeFactoryType[],
+		minPrecedence: TypePrecedence,
+	): void {
+		let first = true;
+		for (const innerType of types) {
+			if (!first) {
+				append(" | ");
+			}
+			appendType(innerType, minPrecedence);
+			first = false;
+		}
+	}
+
+	function appendIntersectionTypes(
+		types: readonly TypeFactoryType[],
+		minPrecedence: TypePrecedence,
+	): void {
+		let first = true;
+		for (const innerType of types) {
+			if (!first) {
+				append(" & ");
+			}
+			appendType(innerType, minPrecedence);
+			first = false;
+		}
+	}
+
+	function appendTupleType(tupleType: TypeFactoryTuple): void {
+		append("[");
+		let first = true;
+		for (const innerType of tupleType.items) {
+			if (!first) {
+				append(", ");
+			}
+			if (innerType._kind === "optional") {
+				appendType((innerType as TypeFactoryOptional).innerType, TypePrecedence.Object);
+				append("?");
+			} else {
+				appendType(innerType);
+			}
+			first = false;
+		}
+		if (tupleType.rest !== undefined) {
+			if (!first) {
+				append(", ");
+			}
+			append("...");
+			appendType(tupleType.rest, TypePrecedence.Object);
+			append("[]");
+		}
+		append("]");
+	}
+
+	function appendRecordType(recordType: TypeFactoryRecord): void {
+		append("Record<");
+		appendType(recordType.keyType, TypePrecedence.Union);
+		append(", ");
+		appendType(recordType.valueType, TypePrecedence.Union);
+		append(">");
+	}
+
+	function appendMapType(mapType: TypeFactoryMap): void {
+		append("Map<");
+		appendType(mapType.keyType, TypePrecedence.Union);
+		append(", ");
+		appendType(mapType.valueType, TypePrecedence.Union);
+		append(">");
+	}
+
+	function appendLiteral(value: string | number | boolean): void {
+		append(JSON.stringify(value));
+	}
+
+	function appendReadonlyType(readonlyType: TypeFactoryReadonly): void {
+		append("Readonly<");
+		appendType(readonlyType.innerType);
+		append(">");
+	}
+
+	function appendFunctionType(functionType: TypeFactoryFunction): void {
+		append("(");
+		let first = true;
+		for (const param of functionType.parameters) {
+			if (!first) {
+				append(", ");
+			}
+			const [name, type] = param;
+			append(name);
+			if (type._kind === "optional") {
+				append("?");
+				append(": ");
+				appendType((type as TypeFactoryOptional).innerType, TypePrecedence.Union);
+			} else {
+				append(": ");
+				appendType(type, TypePrecedence.Union);
+			}
+			first = false;
+		}
+		if (functionType.restParameter !== undefined) {
+			if (!first) {
+				append(", ");
+			}
+			const [name, type] = functionType.restParameter;
+			append("...");
+			append(name);
+			append(": ");
+			appendType(type, TypePrecedence.Object);
+			append("[]");
+		}
+		append(") => ");
+		appendType(functionType.returnType, TypePrecedence.Union);
+	}
+}
+
+const enum TypePrecedence {
+	Union = 0,
+	Intersection = 1,
+	Object = 2,
+}
+
+function getTypePrecedence(type: TypeFactoryType): TypePrecedence {
+	switch (type._kind) {
+		case "union": {
+			return TypePrecedence.Union;
+		}
+		case "intersection": {
+			return TypePrecedence.Intersection;
+		}
+		default: {
+			return TypePrecedence.Object;
+		}
+	}
+}

package/src/subtree.ts

@@ -34,7 +34,7 @@ export class Subtree<TRoot extends ImplicitFieldSchema> {
 
 	public get branch(): TreeBranchAlpha {
 		return this.viewOrTree instanceof TreeNode
-			? (TreeAlpha.branch(this.viewOrTree) ?? fail("Node cannot be raw."))
+			? (TreeAlpha.branch(this.viewOrTree) ?? fail(0xcb3 /* Node cannot be raw. */))
 			: this.viewOrTree;
 	}
 
@@ -89,7 +89,7 @@ export class Subtree<TRoot extends ImplicitFieldSchema> {
 						}
 					}
 					default: {
-						fail("Unexpected node kind");
+						fail(0xcb4 /* Unexpected node kind */);
 					}
 				}
 			}
@@ -108,10 +108,11 @@ export class Subtree<TRoot extends ImplicitFieldSchema> {
 
 	public fork(): Subtree<TRoot> {
 		if (this.viewOrTree instanceof TreeNode) {
-			const branch = TreeAlpha.branch(this.viewOrTree) ?? fail("Node cannot be raw.");
+			const branch =
+				TreeAlpha.branch(this.viewOrTree) ?? fail(0xcb5 /* Node cannot be raw. */);
 			const node =
 				getNodeOnBranch(this.viewOrTree, branch.fork()) ??
-				fail("Expected node to be on new fork.");
+				fail(0xcb6 /* Expected node to be on new fork. */);
 
 			return new Subtree<TRoot>(node);
 		} else {