@fluidframework/tree-agent 2.73.0 → 2.74.0-368706

package/src/utils.ts

@@ -3,13 +3,10 @@
  * Licensed under the MIT License.
  */
 
-/* eslint-disable @typescript-eslint/no-unsafe-argument */
-/* eslint-disable @typescript-eslint/explicit-function-return-type */
-
 import { assert } from "@fluidframework/core-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import type { ImplicitFieldSchema, TreeNodeSchemaClass } from "@fluidframework/tree";
+import type { ImplicitFieldSchema } from "@fluidframework/tree";
 import type {
 	InsertableContent,
 	TreeNode,
@@ -19,15 +16,10 @@ import type {
 import {
 	ArrayNodeSchema,
 	MapNodeSchema,
-	ObjectNodeSchema,
 	RecordNodeSchema,
 	TreeAlpha,
 } from "@fluidframework/tree/alpha";
 import { NodeKind, normalizeFieldSchema } from "@fluidframework/tree/internal";
-import { z } from "zod";
-
-import { FunctionWrapper } from "./methodBinding.js";
-import { PropertyDef } from "./propertyBinding.js";
 
 /**
  * Subset of Map interface.
@@ -180,423 +172,37 @@ export function isNamedSchema(schemaIdentifier: string): boolean {
 		return false;
 	}
 
-	return schemaIdentifier.match(/(?:Array|Map|Record)<\["(.*)"]>/) === null;
+	return /(?:Array|Map|Record)<\["(.*)"]>/.exec(schemaIdentifier) === null;
 }
 
 /**
- * Returns the unqualified name of a schema (e.g. `"my.scope.MyNode"` returns `"MyNode"`).
- * @remarks This works by removing all characters before the last dot in the schema name.
- * If there is a dot in a user's schema name, this might produce unexpected results.
+ * Returns the unqualified, sanitized Typescript-safe name of a schema
+ * Examples:
+ * - `"my.scope.MyNode"` returns `"MyNode"`
+ * - `"my.scope.MyNode-2"` returns `"MyNode_2"`
+ * - `"my.scope.MyNode!"` returns `"MyNode_"`
+ * @remarks
+ * - Removes all characters before the last dot in the schema name.
+ * - Sanitizes the remainder into a valid Typescript identifier
+ * - If there is a dot in a user's schema name, this might produce unexpected results.
  */
 export function unqualifySchema(schemaIdentifier: string): string {
 	// Get the unqualified name by removing the scope (everything before the last dot).
-	const matches = schemaIdentifier.match(/[^.]+$/);
-	if (matches === null) {
-		return schemaIdentifier; // Return the original name if it is unscoped.
-	}
-	return matches[0];
-}
-
-/**
- * Details about the properties of a TypeScript schema represented as Zod.
- */
-export interface SchemaDetails {
-	hasHelperMethods: boolean;
-}
-
-// TODO: yuck, this entire file has too many statics. we should rewrite it as a generic zod schema walk.
-let detailsI: SchemaDetails = {
-	hasHelperMethods: false,
-};
-
-/**
- * Returns the TypeScript source code corresponding to a Zod schema. The schema is supplied as an object where each
- * property provides a name for an associated Zod type. The return value is a string containing the TypeScript source
- * code corresponding to the schema. Each property of the schema object is emitted as a named `interface` or `type`
- * declaration for the associated type and is referenced by that name in the emitted type declarations. Other types
- * referenced in the schema are emitted in their structural form.
- * @param schema - A schema object where each property provides a name for an associated Zod type.
- * @param details - Optional details about the schema. The fields will be set according to the details in the given schema.
- * @returns The TypeScript source code corresponding to the schema.
- */
-export function getZodSchemaAsTypeScript(
-	schema: Record<string, z.ZodType>,
-	details?: SchemaDetails,
-): string {
-	detailsI = details ?? { hasHelperMethods: false };
-	let result = "";
-	let startOfLine = true;
-	let indent = 0;
-	const entries = [...Object.entries(schema)];
-	const namedTypes = new Map<object, string>(
-		entries.map(([name, type]) => [getTypeIdentity(type), name]),
-	);
-	for (const [name, type] of entries) {
-		if (result) {
-			appendNewLine();
-		}
-		const description = type._def.description;
-		if (description !== undefined && description !== "") {
-			for (const comment of description.split("\n")) {
-				append(`// ${comment}`);
-				appendNewLine();
-			}
-		}
-		if (getTypeKind(type) === z.ZodFirstPartyTypeKind.ZodObject) {
-			append(`interface ${name} `);
-			appendObjectType(type as z.ZodObject<z.ZodRawShape>);
-		} else {
-			append(`type ${name} = `);
-			appendTypeDefinition(type);
-			append(";");
-		}
-		appendNewLine();
-	}
-	return result;
-
-	function append(s: string) {
-		if (startOfLine) {
-			result += "    ".repeat(indent);
-			startOfLine = false;
-		}
-		result += s;
-	}
-
-	function appendNewLine() {
-		append("\n");
-		startOfLine = true;
-	}
-
-	function appendType(type: z.ZodType, minPrecedence = TypePrecedence.Object) {
-		const name = namedTypes.get(getTypeIdentity(type));
-		if (name === undefined) {
-			const parenthesize = getTypePrecendece(type) < minPrecedence;
-			if (parenthesize) append("(");
-			appendTypeDefinition(type);
-			if (parenthesize) append(")");
-		} else {
-			append(name);
-		}
-	}
-
-	function appendTypeDefinition(type: z.ZodType) {
-		switch (getTypeKind(type)) {
-			case z.ZodFirstPartyTypeKind.ZodString: {
-				return append("string");
-			}
-			case z.ZodFirstPartyTypeKind.ZodNumber: {
-				return append("number");
-			}
-			case z.ZodFirstPartyTypeKind.ZodBoolean: {
-				return append("boolean");
-			}
-			case z.ZodFirstPartyTypeKind.ZodDate: {
-				return append("Date");
-			}
-			case z.ZodFirstPartyTypeKind.ZodUndefined: {
-				return append("undefined");
-			}
-			case z.ZodFirstPartyTypeKind.ZodNull: {
-				return append("null");
-			}
-			case z.ZodFirstPartyTypeKind.ZodUnknown: {
-				return append("unknown");
-			}
-			case z.ZodFirstPartyTypeKind.ZodArray: {
-				return appendArrayType(type);
-			}
-			case z.ZodFirstPartyTypeKind.ZodObject: {
-				return appendObjectType(type);
-			}
-			case z.ZodFirstPartyTypeKind.ZodUnion: {
-				return appendUnionOrIntersectionTypes(
-					(type._def as z.ZodUnionDef).options,
-					TypePrecedence.Union,
-				);
-			}
-			case z.ZodFirstPartyTypeKind.ZodDiscriminatedUnion: {
-				return appendUnionOrIntersectionTypes(
-					[...(type._def as z.ZodDiscriminatedUnionDef<string>).options.values()],
-					TypePrecedence.Union,
-				);
-			}
-			case z.ZodFirstPartyTypeKind.ZodIntersection: {
-				return appendUnionOrIntersectionTypes(
-					[
-						(type._def as z.ZodIntersectionDef).left,
-						(type._def as z.ZodIntersectionDef).right,
-					],
-					TypePrecedence.Intersection,
-				);
-			}
-			case z.ZodFirstPartyTypeKind.ZodTuple: {
-				return appendTupleType(type);
-			}
-			case z.ZodFirstPartyTypeKind.ZodRecord: {
-				return appendRecordType(type);
-			}
-			case z.ZodFirstPartyTypeKind.ZodMap: {
-				return appendMapType(type);
-			}
-			case z.ZodFirstPartyTypeKind.ZodLiteral: {
-				return appendLiteral((type._def as z.ZodLiteralDef).value);
-			}
-			case z.ZodFirstPartyTypeKind.ZodEnum: {
-				return append(
-					(type._def as z.ZodEnumDef).values.map((value) => JSON.stringify(value)).join(" | "),
-				);
-			}
-			case z.ZodFirstPartyTypeKind.ZodOptional: {
-				return appendUnionOrIntersectionTypes(
-					[(type._def as z.ZodOptionalDef).innerType, z.undefined()],
-					TypePrecedence.Union,
-				);
-			}
-			case z.ZodFirstPartyTypeKind.ZodReadonly: {
-				return appendReadonlyType(type);
-			}
-			case z.ZodFirstPartyTypeKind.ZodEffects: {
-				// Currently, this only handles schema class instances, but there are other cases in which a ZodEffects could theoretically be used.
-				if (instanceOfs.has(type)) {
-					const objectNodeSchema = instanceOfs.get(type);
-					if (objectNodeSchema === undefined) {
-						throw new UsageError(
-							`Unsupported zod effects type when transforming class method: ${getTypeKind(type)}`,
-						);
-					}
-					return append(getFriendlyName(objectNodeSchema));
-				}
-				throw new Error(
-					"Unsupported zod effects type. Did you use z.instanceOf? Use ExposedMethods.instanceOf function to reference schema classes in methods.",
-				);
-			}
-			case z.ZodFirstPartyTypeKind.ZodVoid: {
-				return append("void");
-			}
-			case z.ZodFirstPartyTypeKind.ZodLazy: {
-				return appendType((type._def as z.ZodLazyDef).getter());
-			}
-			default: {
-				throw new UsageError(
-					`Unsupported type when transforming class method: ${getTypeKind(type)}`,
-				);
-			}
-		}
-	}
-
-	function appendBoundMethods(boundType: z.ZodType): void {
-		// eslint-disable-next-line prefer-const
-		for (let [name, type] of Object.entries((boundType._def as z.ZodObjectDef).shape())) {
-			// Special handling of methods on objects
-			const method = (type as unknown as { method: object | undefined }).method;
-			if (method !== undefined && method instanceof FunctionWrapper) {
-				detailsI.hasHelperMethods = true;
-				append(name);
-				append("(");
-				let first = true;
-				for (const [argName, argType] of method.args) {
-					if (!first) append(", ");
-					if (getTypeKind(argType) === z.ZodFirstPartyTypeKind.ZodOptional) {
-						append(`${argName}?: `);
-						appendType((argType._def as z.ZodOptionalDef).innerType, TypePrecedence.Object);
-					} else {
-						append(`${argName}: `);
-						appendType(argType);
-					}
-					first = false;
-				}
-				if (method.rest !== null) {
-					if (!first) append(", ");
-					append("...rest: ");
-					appendType(method.rest, TypePrecedence.Object);
-					append("[]");
-				}
-				append(`): `);
-				appendType(method.returns, TypePrecedence.Object);
-				append(";");
-				if (method.description !== undefined) {
-					append(` // ${method.description}`);
-				}
-				appendNewLine();
-			}
-		}
-	}
-
-	function appendBoundProperties(type: z.ZodType): void {
-		const property = (type as unknown as { property?: PropertyDef }).property;
-
-		if (!(property instanceof PropertyDef)) {
-			if (type.description !== undefined && type.description !== "") {
-				append(` // ${type.description}`);
-			}
-			return;
-		}
-
-		if (property.readOnly === true) {
-			append(" // readonly");
-		}
-		if (property.description !== undefined && property.description !== "") {
-			append(` - ${property.description}`);
-		}
-	}
-
-	function appendArrayType(arrayType: z.ZodType) {
-		appendType((arrayType._def as z.ZodArrayDef).type, TypePrecedence.Object);
-		append("[]");
-	}
-
-	function appendObjectType(objectType: z.ZodType) {
-		append("{");
-		appendNewLine();
-		indent++;
-		// eslint-disable-next-line prefer-const
-		for (let [name, type] of Object.entries((objectType._def as z.ZodObjectDef).shape())) {
-			const method = (type as unknown as { method: object | undefined }).method;
-
-			if (method === undefined || !(method instanceof FunctionWrapper)) {
-				append(name);
-				if (getTypeKind(type) === z.ZodFirstPartyTypeKind.ZodOptional) {
-					append("?");
-					type = (type._def as z.ZodOptionalDef).innerType;
-				}
-				append(": ");
-				appendType(type);
-				append(";");
-				appendBoundProperties(type);
-				appendNewLine();
-			}
-		}
-		appendBoundMethods(objectType);
-		indent--;
-		append("}");
-	}
-
-	function appendUnionOrIntersectionTypes(
-		types: readonly z.ZodType[],
-		minPrecedence: TypePrecedence,
-	) {
-		let first = true;
-		for (const type of types) {
-			if (!first) append(minPrecedence === TypePrecedence.Intersection ? " & " : " | ");
-			appendType(type, minPrecedence);
-			first = false;
-		}
-	}
-
-	function appendTupleType(tupleType: z.ZodType) {
-		append("[");
-		let first = true;
-		for (const type of (tupleType._def as z.ZodTupleDef<z.ZodTupleItems, z.ZodType>).items) {
-			if (!first) append(", ");
-			if (getTypeKind(type) === z.ZodFirstPartyTypeKind.ZodOptional) {
-				appendType((type._def as z.ZodOptionalDef).innerType, TypePrecedence.Object);
-				append("?");
-			} else {
-				appendType(type);
-			}
-			first = false;
-		}
-		const rest = (tupleType._def as z.ZodTupleDef<z.ZodTupleItems, z.ZodType | null>).rest;
-		if (rest !== null) {
-			if (!first) append(", ");
-			append("...");
-			appendType(rest, TypePrecedence.Object);
-			append("[]");
-		}
-		append("]");
-	}
-
-	function appendRecordType(recordType: z.ZodType) {
-		append("Record<");
-		appendType((recordType._def as z.ZodRecordDef).keyType);
-		append(", ");
-		appendType((recordType._def as z.ZodRecordDef).valueType);
-		append(">");
-	}
-
-	function appendMapType(mapType: z.ZodType) {
-		append("Map<");
-		appendType((mapType._def as z.ZodMapDef).keyType);
-		append(", ");
-		appendType((mapType._def as z.ZodMapDef).valueType);
-		append(">");
-	}
+	const matches = /[^.]+$/.exec(schemaIdentifier);
+	const unqualifiedName = matches === null ? schemaIdentifier : matches[0];
 
-	function appendLiteral(value: unknown) {
-		append(
-			typeof value === "string" || typeof value === "number" || typeof value === "boolean"
-				? JSON.stringify(value)
-				: "any",
-		);
-	}
-
-	function appendReadonlyType(readonlyType: z.ZodType) {
-		append("Readonly<");
-		appendType((readonlyType._def as z.ZodReadonlyDef).innerType);
-		append(">");
-	}
-}
+	let sanitizedName = unqualifiedName;
 
-function getTypeKind(type: z.ZodType): z.ZodFirstPartyTypeKind {
-	return (type._def as z.ZodTypeDef & { typeName: z.ZodFirstPartyTypeKind }).typeName;
-}
+	// Replace invalid characters with "_".
+	sanitizedName = sanitizedName.replace(/[^\w$]/g, "_");
 
-function getTypeIdentity(type: z.ZodType): object {
-	switch (getTypeKind(type)) {
-		case z.ZodFirstPartyTypeKind.ZodObject: {
-			return (type._def as z.ZodObjectDef).shape();
-		}
-		case z.ZodFirstPartyTypeKind.ZodEnum: {
-			return (type._def as z.ZodEnumDef).values;
-		}
-		case z.ZodFirstPartyTypeKind.ZodUnion: {
-			return (type._def as z.ZodUnionDef).options;
-		}
-		default: {
-			return type;
-		}
+	// If the first character is a number, prefix it with "_".
+	if (!/^[$A-Z_a-z]/.test(sanitizedName)) {
+		sanitizedName = `_${sanitizedName}`;
 	}
+	return sanitizedName;
 }
 
-const enum TypePrecedence {
-	Union = 0,
-	Intersection = 1,
-	Object = 2,
-}
-
-function getTypePrecendece(type: z.ZodType): TypePrecedence {
-	switch (getTypeKind(type)) {
-		case z.ZodFirstPartyTypeKind.ZodEnum:
-		case z.ZodFirstPartyTypeKind.ZodUnion:
-		case z.ZodFirstPartyTypeKind.ZodDiscriminatedUnion: {
-			return TypePrecedence.Union;
-		}
-		case z.ZodFirstPartyTypeKind.ZodIntersection: {
-			return TypePrecedence.Intersection;
-		}
-		default: {
-			return TypePrecedence.Object;
-		}
-	}
-}
-
-/**
- * Create a Zod schema for a SharedTree schema class.
- * @alpha
- */
-export function instanceOf<T extends TreeNodeSchemaClass>(
-	schema: T,
-): z.ZodType<InstanceType<T>, z.ZodTypeDef, InstanceType<T>> {
-	if (!(schema instanceof ObjectNodeSchema)) {
-		throw new UsageError(`${schema.identifier} must be an instance of ObjectNodeSchema.`);
-	}
-	const effect = z.instanceof(schema);
-	instanceOfs.set(effect, schema);
-	return effect;
-}
-
-const instanceOfs = new WeakMap<z.ZodTypeAny, ObjectNodeSchema>();
-
 /**
  * Adds all (optionally filtered) schemas reachable from the given schema to the given set.
  * @returns The set of schemas added (same as the `schemas` parameter, if supplied).