@fluidframework/tree 2.33.1 → 2.40.0-336023

package/src/simple-tree/api/schemaFactoryAlpha.ts

@@ -12,6 +12,8 @@ import {
 } from "./schemaFactory.js";
 import type {
 	ImplicitAllowedTypes,
+	ImplicitAnnotatedAllowedTypes,
+	ImplicitAnnotatedFieldSchema,
 	ImplicitFieldSchema,
 	NodeSchemaOptions,
 } from "../schemaTypes.js";
@@ -56,9 +58,9 @@ export class SchemaFactoryAlpha<
 	 * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.
 	 * @param options - Additional options for the schema.
 	 */
-	public override object<
+	public objectAlpha<
 		const Name extends TName,
-		const T extends RestrictiveStringRecord<ImplicitFieldSchema>,
+		const T extends RestrictiveStringRecord<ImplicitAnnotatedFieldSchema>,
 		const TCustomMetadata = unknown,
 	>(
 		name: Name,
@@ -121,7 +123,7 @@ export class SchemaFactoryAlpha<
 		Pick<ObjectNodeSchema, "fields"> {
 		// TODO: syntax highting is vs code is broken here. Don't trust it. Use the compiler instead.
 		type TScopedName = ScopedSchemaName<TScope, Name>;
-		return this.object(
+		return this.objectAlpha(
 			name,
 			t as T & RestrictiveStringRecord<ImplicitFieldSchema>,
 			options,
@@ -184,7 +186,7 @@ export class SchemaFactoryAlpha<
 	 */
 	public mapAlpha<
 		Name extends TName,
-		const T extends ImplicitAllowedTypes,
+		const T extends ImplicitAnnotatedAllowedTypes,
 		const TCustomMetadata = unknown,
 	>(
 		name: Name,
@@ -228,7 +230,7 @@ export class SchemaFactoryAlpha<
 	 */
 	public arrayAlpha<
 		const Name extends TName,
-		const T extends ImplicitAllowedTypes,
+		const T extends ImplicitAnnotatedAllowedTypes,
 		const TCustomMetadata = unknown,
 	>(
 		name: Name,

package/src/simple-tree/api/schemaFactoryRecursive.ts

@@ -14,13 +14,7 @@ import {
 	type ImplicitFieldSchema,
 	type InsertableTreeNodeFromImplicitAllowedTypes,
 } from "../schemaTypes.js";
-import type {
-	NodeKind,
-	TreeNodeSchemaClass,
-	TreeNodeSchema,
-	WithType,
-	TreeNode,
-} from "../core/index.js";
+import type { NodeKind, TreeNodeSchema, WithType, TreeNode } from "../core/index.js";
 import type { FieldSchemaAlphaUnsafe, System_Unsafe } from "./typesUnsafe.js";
 
 export function createFieldSchemaUnsafe<
@@ -33,7 +27,11 @@ export function createFieldSchemaUnsafe<
 	props?: FieldProps<TCustomMetadata>,
 ): FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata> {
 	// At runtime, we still want this to be a FieldSchema instance, but we can't satisfy its extends clause, so just return it as an FieldSchemaUnsafe
-	return createFieldSchema(kind, allowedTypes as ImplicitAllowedTypes & Types, props);
+	return createFieldSchema(
+		kind,
+		allowedTypes as ImplicitAllowedTypes & Types,
+		props,
+	) as FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata>;
 }
 
 /**
@@ -159,37 +157,103 @@ export function createFieldSchemaUnsafe<
  */
 export type ValidateRecursiveSchema<
 	// Recursive types should always be using TreeNodeSchemaClass (not TreeNodeSchemaNonClass) as thats part of the requirements for the type to work across compilation boundaries correctly.
-	T extends TreeNodeSchemaClass<
-		// Name: This validator places no restrictions on the name other than that it's a string (as required by TreeNodeSchemaClass).
-		string,
-		// NodeKind: These are the NodeKinds which currently can be used recursively.
-		NodeKind.Array | NodeKind.Map | NodeKind.Object,
-		// TNode: The produced node API. This is pretty minimal validation: more could be added if similar to how TInsertable works below if needed.
-		TreeNode & WithType<T["identifier"], T["kind"]>,
-		// TInsertable: What can be passed to the constructor. This should be enough to catch most issues with incorrect schema.
-		// These match whats defined in the recursive methods on `SchemaFactory` except they do not use `Unenforced`.
-		{
-			[NodeKind.Object]: T["info"] extends RestrictiveStringRecord<ImplicitFieldSchema>
-				? InsertableObjectFromSchemaRecord<T["info"]>
-				: unknown;
-			[NodeKind.Array]: T["info"] extends ImplicitAllowedTypes
-				? Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T["info"]>>
-				: unknown;
-			[NodeKind.Map]: T["info"] extends ImplicitAllowedTypes
-				? Iterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T["info"]>]>
-				: unknown;
-		}[T["kind"]],
-		// ImplicitlyConstructable: recursive types are currently not implicitly constructable.
-		false,
-		// Info: What's passed to the method to create the schema. Constraining these here should be about as effective as if the actual constraints existed on the actual method itself.
-		{
-			[NodeKind.Object]: RestrictiveStringRecord<ImplicitFieldSchema>;
-			[NodeKind.Array]: ImplicitAllowedTypes;
-			[NodeKind.Map]: ImplicitAllowedTypes;
-		}[T["kind"]]
-	>,
+	T extends ValidateRecursiveSchemaTemplate<T>,
 > = true;
 
+/**
+ * Validation logic used by {@link ValidateRecursiveSchema}.
+ * @system @public
+ */
+export type ValidateRecursiveSchemaTemplate<T extends TreeNodeSchema> = TreeNodeSchema<
+	// Name: This validator places no restrictions on the name other than that it's a string (as required by TreeNodeSchemaClass).
+	string,
+	// NodeKind: These are the NodeKinds which currently can be used recursively.
+	NodeKind.Array | NodeKind.Map | NodeKind.Object,
+	// TNode: The produced node API. This is pretty minimal validation: more could be added if similar to how TInsertable works below if needed.
+	TreeNode & WithType<T["identifier"], T["kind"]>,
+	// TInsertable: What can be passed to the constructor. This should be enough to catch most issues with incorrect schema.
+	// These match whats defined in the recursive methods on `SchemaFactory` except they do not use `Unenforced`.
+	{
+		[NodeKind.Object]: T["info"] extends RestrictiveStringRecord<ImplicitFieldSchema>
+			? InsertableObjectFromSchemaRecord<T["info"]>
+			: unknown;
+		[NodeKind.Array]: T["info"] extends ImplicitAllowedTypes
+			? Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T["info"]>>
+			: unknown;
+		[NodeKind.Map]: T["info"] extends ImplicitAllowedTypes
+			? Iterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T["info"]>]>
+			: unknown;
+		[NodeKind.Leaf]: unknown;
+	}[T["kind"]],
+	// ImplicitlyConstructable: recursive types are currently not implicitly constructable.
+	false,
+	// Info: What's passed to the method to create the schema. Constraining these here should be about as effective as if the actual constraints existed on the actual method itself.
+	{
+		[NodeKind.Object]: RestrictiveStringRecord<ImplicitFieldSchema>;
+		[NodeKind.Array]: ImplicitAllowedTypes;
+		[NodeKind.Map]: ImplicitAllowedTypes;
+		[NodeKind.Leaf]: unknown;
+	}[T["kind"]]
+>;
+
+/**
+ * Workaround for "Type instantiation is excessively deep and possibly infinite.ts" errors.
+ * @remarks
+ *
+ * Generally this workaround should be avoided if possible,
+ * especially for exported types, as it is likely to result in issues when exporting or importing schema where the user will be forced to use the workaround as well.
+ * This is particularly problematic since in some cases it may not be possible for the user to replicate the pattern.
+ * Additionally, which cases hit these limits may vary based on TypeScript version and implementation details of this library.
+ *
+ * This workaround is provided and documented as a last resort to be able to keep an app compiling.
+ * Future version of SharedTree should provide schema type erasure functionality as a better alternative for most cases.
+ *
+ * When TypeScript gives the error "Error (TS2589) Type instantiation is excessively deep and possibly infinite." on the invocation of `ValidateRecursiveSchema`
+ * for a large schema, it can sometimes be worked around by repeating the usage of the type multiple times.
+ * This works because the TypeScript compiler caches some of the intermediate results from the first usage, and thus can get further on the second.
+ *
+ * This utility can be referenced when applying this pattern.
+ * For recursive types this can be used directly:
+ *
+ * ```typescript
+ * {
+ *     // @ts-expect-error Recursion limit
+ *     type _check1 = FixRecursiveRecursionLimit<typeof LargeType>;
+ *     type _check2 = FixRecursiveRecursionLimit<typeof LargeType>;
+ *     type _check3 = ValidateRecursiveSchemaTemplate<typeof LargeType>;
+ * }
+ * ```
+ *
+ * For non-recursive types, they can be ported to the more flexible recursive APIs and use the pattern above.
+ *
+ * Non-recursive types can also use this workaround by making a duplicate copy of the problematic schema written using the recursive APIs.
+ * Then this pattern can be applied to the duplicate copy.
+ *
+ * ```typescript
+ * // Workaround TypeScript recursion limit
+ * 	{
+ * 		class LargeUnionObjectNode_Fix extends schema.objectRecursive("ObjectNode", {
+ * 			x: largeUnion,
+ * 		}) {}
+ *
+ * 		// @ts-expect-error Recursion limit
+ * 		allowUnused<FixRecursiveRecursionLimit<typeof LargeUnionObjectNode_Fix>>();
+ * 		allowUnused<FixRecursiveRecursionLimit<typeof LargeUnionObjectNode_Fix>>();
+ * 		allowUnused<ValidateRecursiveSchema<typeof LargeUnionObjectNode_Fix>>();
+ * 		}
+ *
+ * 	// Fails to compile without the above workaround.
+ * 	class LargeUnionObjectNode extends schema.object("ObjectNode", { x: largeUnion }) {}
+ * ```
+ * @privateRemarks
+ * Using this is real sketchy, and leads to a lot of issues (errors which depend on how the schema is compiled, making different build setups produce different results and complicating exports).
+ * This is being kept as internal for now: if a customer really needs it, we have this as a documented workaround, but it would be much better to find an alternative solution before using this one.
+ * This uses ValidateRecursiveSchemaTemplate since it was found to evaluate enough of the type to work.
+ * @internal
+ */
+export type FixRecursiveRecursionLimit<T extends TreeNodeSchema> =
+	T extends ValidateRecursiveSchemaTemplate<T> ? undefined : undefined;
+
 /**
  * Does nothing with the provided value, but appears to use it to make unused locals warnings and errors go away.
  *
@@ -215,7 +279,7 @@ export function allowUnused<T>(t?: T): void {}
  *
  * This type always evaluates to `undefined` to ensure the dummy export (which doesn't exist at runtime) is typed correctly.
  *
- * [TypeScript Issue 59550](https://github.com/microsoft/TypeScript/issues/59550) tracks a suggestion which would make this workaround unnecessary.
+ * {@link https://github.com/microsoft/TypeScript/issues/59550|TypeScript Issue 59550} tracks a suggestion which would make this workaround unnecessary.
  *
  * @example Usage
  * Since recursive type handling in TypeScript is order dependent, putting just the right kind of usages of the type before the declarations can cause it to not hit this error.

package/src/simple-tree/api/schemaFromSimple.ts

@@ -18,7 +18,7 @@ import type {
 	SimpleTreeSchema,
 } from "../simpleSchema.js";
 import { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
-import type { TreeSchema } from "./tree.js";
+import type { TreeSchema } from "./configuration.js";
 
 const factory = new SchemaFactoryAlpha(undefined);
 
@@ -100,7 +100,7 @@ function generateNode(
 			}
 			// Here allowUnknownOptionalFields is implicitly defaulting. This is a subjective policy choice:
 			// users of this code are expected to handle what ever choice this code makes for cases like this.
-			return factory.object(id, fields, { metadata: schema.metadata });
+			return factory.objectAlpha(id, fields, { metadata: schema.metadata });
 		}
 		case NodeKind.Array:
 			return factory.arrayAlpha(

package/src/simple-tree/api/simpleSchemaToJsonSchema.ts

@@ -26,7 +26,7 @@ import type {
 	SimpleMapNodeSchema,
 } from "../simpleSchema.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
-import type { TreeSchema } from "./tree.js";
+import type { TreeSchema } from "./configuration.js";
 import type { TreeSchemaEncodingOptions } from "./getJsonSchema.js";
 import { ObjectNodeSchema } from "../objectNodeTypes.js";
 import { ArrayNodeSchema } from "../arrayNodeTypes.js";

package/src/simple-tree/api/storedSchema.ts

@@ -13,10 +13,10 @@ import {
 // eslint-disable-next-line import/no-internal-modules
 import type { Format } from "../../feature-libraries/schema-index/index.js";
 import type { JsonCompatible } from "../../util/index.js";
-import type { ImplicitFieldSchema } from "../schemaTypes.js";
+import { normalizeFieldSchema, type ImplicitFieldSchema } from "../schemaTypes.js";
 import { toStoredSchema } from "../toStoredSchema.js";
 import type { SchemaCompatibilityStatus } from "./tree.js";
-import { ViewSchema } from "./view.js";
+import { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
 
 /**
  * Dumps the "persisted" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable, but unspecified format.
@@ -91,7 +91,11 @@ export function comparePersistedSchema(
 ): SchemaCompatibilityStatus {
 	const schemaCodec = makeSchemaCodec(options);
 	const stored = schemaCodec.decode(persisted as Format);
-	const viewSchema = new ViewSchema(defaultSchemaPolicy, {}, view);
+	const viewSchema = new SchemaCompatibilityTester(
+		defaultSchemaPolicy,
+		{},
+		normalizeFieldSchema(view),
+	);
 	return comparePersistedSchemaInternal(stored, viewSchema, canInitialize);
 }
 
@@ -101,7 +105,7 @@ export function comparePersistedSchema(
  */
 export function comparePersistedSchemaInternal(
 	stored: TreeStoredSchema,
-	viewSchema: ViewSchema,
+	viewSchema: SchemaCompatibilityTester,
 	canInitialize: boolean,
 ): SchemaCompatibilityStatus {
 	return {