@fluidframework/tree-agent 2.81.0-374083 → 2.81.1

package/src/prompt.ts

@@ -8,12 +8,17 @@ import { NodeKind, Tree, TreeNode } from "@fluidframework/tree";
 import type { ImplicitFieldSchema, TreeMapNode } from "@fluidframework/tree";
 import type { ReadableField } from "@fluidframework/tree/alpha";
 import { getSimpleSchema } from "@fluidframework/tree/alpha";
-import { normalizeFieldSchema } from "@fluidframework/tree/internal";
+import { normalizeFieldSchema, ValueSchema } from "@fluidframework/tree/internal";
 
 import type { Subtree } from "./subtree.js";
 import { generateEditTypesForPrompt } from "./typeGeneration.js";
 import { getFriendlyName, communize, findSchemas } from "./utils.js";
 
+/**
+ * The type name used for handles in generated TypeScript.
+ */
+export const fluidHandleTypeName = "_OpaqueHandle";
+
 /**
  * Produces a "system" prompt for the tree agent, based on the provided subtree.
  */
@@ -32,6 +37,7 @@ export function getPrompt(args: {
 	let nodeTypeUnion: string | undefined;
 	let hasArrays = false;
 	let hasMaps = false;
+	let hasFluidHandles = false;
 	let exampleObjectName: string | undefined;
 	for (const s of findSchemas(schema)) {
 		if (s.kind !== NodeKind.Leaf) {
@@ -54,6 +60,10 @@ export function getPrompt(args: {
 				exampleObjectName ??= getFriendlyName(s);
 				break;
 			}
+			case NodeKind.Leaf: {
+				hasFluidHandles ||= s.info === ValueSchema.FluidHandle;
+				break;
+			}
 			// No default
 		}
 	}
@@ -63,6 +73,15 @@ export function getPrompt(args: {
 		schema,
 		getSimpleSchema(schema),
 	);
+	const fluidHandleType = hasFluidHandles
+		? `/**
+ * Opaque handle type representing a reference to a Fluid object.
+ * This type should not be constructed by generated code.
+ */
+type ${fluidHandleTypeName} = unknown;
+
+`
+		: "";
 	const exampleTypeName =
 		nodeTypeUnion === undefined
 			? undefined
@@ -274,7 +293,7 @@ Finally, double check that the edits would accomplish the user's request (if it
 The JSON tree adheres to the following Typescript schema:
 
 \`\`\`typescript
-${typescriptSchemaTypes}
+${fluidHandleType}${typescriptSchemaTypes}
 \`\`\`
 
 If the user asks you a question about the tree, you should inspect the state of the tree and answer the question.

package/src/renderSchemaTypeScript.ts

@@ -17,6 +17,7 @@ import { z } from "zod";
 
 import type { BindableSchema, FunctionWrapper } from "./methodBinding.js";
 import { getExposedMethods } from "./methodBinding.js";
+import { fluidHandleTypeName } from "./prompt.js";
 import { getExposedProperties, type PropertyDef } from "./propertyBinding.js";
 import {
 	instanceOfsTypeFactory,
@@ -290,7 +291,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;
@@ -440,7 +443,11 @@ function renderPropertyLines(properties: Record<string, PropertyDef>): string[]
 			}
 		}
 		const modifier = property.readOnly ? "readonly " : "";
-		lines.push(`${modifier}${name}: ${renderType(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;
 }
@@ -449,13 +456,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 = renderType(innerType);
+		const renderedType = renderType(innerType, 0);
 		args.push(`${argName}${optional ? "?" : ""}: ${renderedType}`);
 	}
 	if (method.rest !== null) {
-		args.push(`...rest: ${renderType(method.rest)}[]`);
+		args.push(`...rest: ${renderType(method.rest, 0)}[]`);
 	}
-	return `${name}(${args.join(", ")}): ${renderType(method.returns)};`;
+	return `${name}(${args.join(", ")}): ${renderType(method.returns, 0)};`;
 }
 
 function renderLeaf(leafKind: ValueSchema): string {
@@ -472,8 +479,11 @@ function renderLeaf(leafKind: ValueSchema): string {
 		case ValueSchema.Null: {
 			return "null";
 		}
+		case ValueSchema.FluidHandle: {
+			return fluidHandleTypeName;
+		}
 		default: {
-			throw new Error(`Unsupported leaf kind ${NodeKind[leafKind]}.`);
+			throw new Error(`Unsupported leaf kind.`);
 		}
 	}
 }
@@ -532,8 +542,8 @@ function ensureNoMemberConflicts(
 /**
  * Dispatches to the correct renderer based on whether the type is Zod or type factory.
  */
-function renderType(type: z.ZodTypeAny | TypeFactoryType): string {
+function renderType(type: z.ZodTypeAny | TypeFactoryType, indentLevel: number = 0): string {
 	return isTypeFactoryType(type)
-		? renderTypeFactoryTypeScript(type, getFriendlyName, instanceOfsTypeFactory)
+		? renderTypeFactoryTypeScript(type, getFriendlyName, instanceOfsTypeFactory, indentLevel)
 		: renderZodTypeScript(type, getFriendlyName, instanceOfs);
 }

package/src/renderTypeFactoryTypeScript.ts

@@ -9,6 +9,7 @@ import type { ObjectNodeSchema, TreeNodeSchema } from "@fluidframework/tree/alph
 import type {
 	TypeFactoryType,
 	TypeFactoryArray,
+	TypeFactoryPromise,
 	TypeFactoryObject,
 	TypeFactoryTuple,
 	TypeFactoryRecord,
@@ -17,6 +18,8 @@ import type {
 	TypeFactoryOptional,
 	TypeFactoryReadonly,
 	TypeFactoryUnion,
+	TypeFactoryIntersection,
+	TypeFactoryFunction,
 } from "./treeAgentTypes.js";
 
 export { instanceOfsTypeFactory } from "./treeAgentTypes.js";
@@ -29,10 +32,11 @@ export function renderTypeFactoryTypeScript(
 	typeFactoryType: TypeFactoryType,
 	getFriendlyName: (schema: TreeNodeSchema) => string,
 	instanceOfLookup: WeakMap<TypeFactoryType, ObjectNodeSchema>,
+	initialIndent: number = 0,
 ): string {
 	let result = "";
-	let startOfLine = true;
-	let indent = 0;
+	let startOfLine = false;
+	let indent = initialIndent;
 
 	appendType(typeFactoryType, TypePrecedence.Union);
 	return result;
@@ -75,6 +79,10 @@ export function renderTypeFactoryTypeScript(
 				append("boolean");
 				return;
 			}
+			case "date": {
+				append("Date");
+				return;
+			}
 			case "void": {
 				append("void");
 				return;
@@ -95,6 +103,10 @@ export function renderTypeFactoryTypeScript(
 				appendArrayType(type as TypeFactoryArray);
 				return;
 			}
+			case "promise": {
+				appendPromiseType(type as TypeFactoryPromise);
+				return;
+			}
 			case "object": {
 				appendObjectType(type as TypeFactoryObject);
 				return;
@@ -103,6 +115,13 @@ export function renderTypeFactoryTypeScript(
 				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;
@@ -130,6 +149,10 @@ export function renderTypeFactoryTypeScript(
 				appendReadonlyType(type as TypeFactoryReadonly);
 				return;
 			}
+			case "function": {
+				appendFunctionType(type as TypeFactoryFunction);
+				return;
+			}
 			case "instanceof": {
 				const schema = instanceOfLookup.get(type);
 				if (schema === undefined) {
@@ -153,6 +176,12 @@ export function renderTypeFactoryTypeScript(
 		append("[]");
 	}
 
+	function appendPromiseType(promiseType: TypeFactoryPromise): void {
+		append("Promise<");
+		appendType(promiseType.innerType, TypePrecedence.Union);
+		append(">");
+	}
+
 	function appendObjectType(objectType: TypeFactoryObject): void {
 		append("{");
 		appendNewLine();
@@ -188,6 +217,20 @@ export function renderTypeFactoryTypeScript(
 		}
 	}
 
+	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;
@@ -239,6 +282,40 @@ export function renderTypeFactoryTypeScript(
 		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 {
@@ -252,6 +329,9 @@ function getTypePrecedence(type: TypeFactoryType): TypePrecedence {
 		case "union": {
 			return TypePrecedence.Union;
 		}
+		case "intersection": {
+			return TypePrecedence.Intersection;
+		}
 		default: {
 			return TypePrecedence.Object;
 		}

package/src/treeAgentTypes.ts

@@ -19,15 +19,19 @@ export type TypeFactoryTypeKind =
 	| "undefined"
 	| "null"
 	| "unknown"
+	| "date"
+	| "promise"
 	| "array"
 	| "object"
 	| "record"
 	| "map"
 	| "tuple"
 	| "union"
+	| "intersection"
 	| "literal"
 	| "optional"
 	| "readonly"
+	| "function"
 	| "instanceof";
 
 /**
@@ -53,15 +57,19 @@ const validTypeKinds: ReadonlySet<TypeFactoryTypeKind> = new Set<TypeFactoryType
 	"undefined",
 	"null",
 	"unknown",
+	"date",
+	"promise",
 	"array",
 	"object",
 	"record",
 	"map",
 	"tuple",
 	"union",
+	"intersection",
 	"literal",
 	"optional",
 	"readonly",
+	"function",
 	"instanceof",
 ]);
 
@@ -112,6 +120,17 @@ export interface TypeFactoryBoolean extends TypeFactoryType {
 	readonly _kind: "boolean";
 }
 
+/**
+ * Represents a Date type in the type factory system.
+ * @alpha
+ */
+export interface TypeFactoryDate extends TypeFactoryType {
+	/**
+	 * {@inheritDoc TypeFactoryType._kind}
+	 */
+	readonly _kind: "date";
+}
+
 /**
  * Represents a void type in the type factory system.
  * @alpha
@@ -173,6 +192,21 @@ export interface TypeFactoryArray extends TypeFactoryType {
 	readonly element: TypeFactoryType;
 }
 
+/**
+ * Represents a Promise type in the type factory system.
+ * @alpha
+ */
+export interface TypeFactoryPromise extends TypeFactoryType {
+	/**
+	 * {@inheritDoc TypeFactoryType._kind}
+	 */
+	readonly _kind: "promise";
+	/**
+	 * The type that the Promise resolves to.
+	 */
+	readonly innerType: TypeFactoryType;
+}
+
 /**
  * Represents an object type with a fixed shape in the type factory system.
  * @alpha
@@ -260,6 +294,21 @@ export interface TypeFactoryUnion extends TypeFactoryType {
 	readonly options: readonly TypeFactoryType[];
 }
 
+/**
+ * Represents an intersection type in the type factory system.
+ * @alpha
+ */
+export interface TypeFactoryIntersection extends TypeFactoryType {
+	/**
+	 * {@inheritDoc TypeFactoryType._kind}
+	 */
+	readonly _kind: "intersection";
+	/**
+	 * The types to intersect.
+	 */
+	readonly types: readonly TypeFactoryType[];
+}
+
 /**
  * Represents a literal type (specific string, number, or boolean value) in the type factory system.
  * @alpha
@@ -305,6 +354,35 @@ export interface TypeFactoryReadonly extends TypeFactoryType {
 	readonly innerType: TypeFactoryType;
 }
 
+/**
+ * Represents a function parameter as a tuple of [name, type].
+ * @alpha
+ */
+export type TypeFactoryFunctionParameter = readonly [name: string, type: TypeFactoryType];
+
+/**
+ * Represents a function type in the type factory system.
+ * @alpha
+ */
+export interface TypeFactoryFunction extends TypeFactoryType {
+	/**
+	 * {@inheritDoc TypeFactoryType._kind}
+	 */
+	readonly _kind: "function";
+	/**
+	 * The function parameters.
+	 */
+	readonly parameters: readonly TypeFactoryFunctionParameter[];
+	/**
+	 * The function return type.
+	 */
+	readonly returnType: TypeFactoryType;
+	/**
+	 * Optional rest parameter for variable-length argument lists.
+	 */
+	readonly restParameter?: TypeFactoryFunctionParameter;
+}
+
 /**
  * Represents an instanceof type that references a SharedTree schema class in the type factory system.
  * @alpha
@@ -349,6 +427,14 @@ export const typeFactory = {
 		return { _kind: "boolean" };
 	},
 
+	/**
+	 * Create a Date type.
+	 * @alpha
+	 */
+	date(): TypeFactoryDate {
+		return { _kind: "date" };
+	},
+
 	/**
 	 * Create a void type.
 	 * @alpha
@@ -389,6 +475,14 @@ export const typeFactory = {
 		return { _kind: "array", element };
 	},
 
+	/**
+	 * Create a Promise type.
+	 * @alpha
+	 */
+	promise(innerType: TypeFactoryType): TypeFactoryPromise {
+		return { _kind: "promise", innerType };
+	},
+
 	/**
 	 * Create an object type.
 	 * @alpha
@@ -439,6 +533,19 @@ export const typeFactory = {
 		return { _kind: "union", options };
 	},
 
+	/**
+	 * Create an intersection type.
+	 * @alpha
+	 */
+	intersection(types: readonly TypeFactoryType[]): TypeFactoryIntersection {
+		if (types.length === 0) {
+			throw new UsageError(
+				"typeFactory.intersection requires at least one type. Empty intersections are not valid TypeScript types.",
+			);
+		}
+		return { _kind: "intersection", types };
+	},
+
 	/**
 	 * Create a literal type.
 	 * @alpha
@@ -463,6 +570,20 @@ export const typeFactory = {
 		return { _kind: "readonly", innerType };
 	},
 
+	/**
+	 * Create a function type.
+	 * @alpha
+	 */
+	function(
+		parameters: readonly TypeFactoryFunctionParameter[],
+		returnType: TypeFactoryType,
+		restParameter?: TypeFactoryFunctionParameter,
+	): TypeFactoryFunction {
+		return restParameter === undefined
+			? { _kind: "function", parameters, returnType }
+			: { _kind: "function", parameters, returnType, restParameter };
+	},
+
 	/**
 	 * Create an instanceOf type for a SharedTree schema class.
 	 * @alpha