feat: customizeSchemaTyping

.changeset/metal-sloths-join.md

@@ -0,0 +1,27 @@
+---
+"fluid-framework": minor
+"@fluidframework/tree": minor
+---
+---
+"section": tree
+---
+
+Disallow some invalid and unsafe ObjectNode field assignments at compile time
+
+The compile time validation of the type of values assigned to ObjectNode fields is limited by TypeScript's limitations.
+Two cases which were actually possible to disallow and should be disallowed for consistency with runtime behavior and similar APIs were being allowed:
+
+1. [Identifier fields](https://fluidframework.com/docs/api/v2/fluid-framework/schemafactory-class#identifier-property):
+   Identifier fields are immutable, and setting them produces a runtime error.
+   This changes fixes them to no longer be typed as assignable.
+
+2. Fields with non-exact schema:
+   When non-exact scheme is used for a field (for example the schema is either a schema only allowing numbers or a schema only allowing strings) the field is no longer typed as assignable.
+   This matches how constructors and implicit node construction work.
+   For example when a node `Foo` has such an non-exact schema for field `bar`, you can no longer unsafely do `foo.bar = 5` just like how you could already not do `new Foo({bar: 5})`.
+
+This fix only applies to [`SchemaFactory.object`](https://fluidframework.com/docs/api/v2/fluid-framework/schemafactory-class#object-method).
+[`SchemaFactory.objectRecursive`](https://fluidframework.com/docs/api/v2/fluid-framework/schemafactory-class#objectrecursive-method) was unable to be updated to match due to TypeScript limitations on recursive types.
+
+An `@alpha` API, `customizeSchemaTyping` has been added to allow control over the types generated from schema.
+For example code relying on the unsound typing fixed above can restore the behavior using `customizeSchemaTyping`:

packages/dds/tree/.vscode/settings.json

@@ -22,6 +22,7 @@
 		"contravariance",
 		"contravariantly",
 		"covariantly",
+		"Customizer",
 		"deprioritized",
 		"endregion",
 		"fluidframework",

packages/dds/tree/package.json

@@ -237,7 +237,11 @@
 		}
 	},
 	"typeValidation": {
-		"broken": {},
+		"broken": {
+			"TypeAlias_InsertableTreeNodeFromImplicitAllowedTypes": {
+				"backCompat": false
+			}
+		},
 		"entrypoint": "public"
 	}
 }

packages/dds/tree/src/index.ts

@@ -244,6 +244,17 @@ export {
 	type NodeSchemaOptions,
 	type NodeSchemaOptionsAlpha,
 	type NodeSchemaMetadata,
+	type AssignableTreeFieldFromImplicitField,
+	type ApplyKindAssignment,
+	type Customizer,
+	type GetTypes,
+	type StrictTypes,
+	type CustomTypes,
+	type CustomizedSchemaTyping,
+	CustomizedTyping,
+	type DefaultInsertableTreeNodeFromImplicitAllowedTypes,
+	customizeSchemaTyping,
+	type SchemaUnionToIntersection,
 	type SchemaStatics,
 	type ITreeAlpha,
 	type TransactionConstraint,
@@ -283,6 +294,11 @@ export {
 	type SchemaFactory_base,
 	type NumberKeys,
 	type SimpleAllowedTypeAttributes,
+	type DefaultTreeNodeFromImplicitAllowedTypes,
+	type ObjectFromSchemaRecordRelaxed,
+	type ObjectSchemaTypingOptions,
+	type AssignableTreeFieldFromImplicitFieldDefault,
+	type TreeFieldFromImplicitFieldDefault,
 } from "./simple-tree/index.js";
 export {
 	SharedTree,
@@ -323,6 +339,7 @@ export type {
 	JsonCompatibleObject,
 	JsonCompatibleReadOnly,
 	JsonCompatibleReadOnlyObject,
+	PreventExtraProperties,
 } from "./util/index.js";
 export { cloneWithReplacements } from "./util/index.js";
 

packages/dds/tree/src/simple-tree/api/index.ts

@@ -37,7 +37,11 @@ export {
 	type SchemaFactory_base,
 } from "./schemaFactory.js";
 export { SchemaFactoryBeta } from "./schemaFactoryBeta.js";
-export { SchemaFactoryAlpha, type SchemaStaticsAlpha } from "./schemaFactoryAlpha.js";
+export {
+	SchemaFactoryAlpha,
+	type SchemaStaticsAlpha,
+	relaxObject,
+} from "./schemaFactoryAlpha.js";
 export type {
 	ValidateRecursiveSchema,
 	FixRecursiveArraySchema,
@@ -99,6 +103,7 @@ export type {
 	AllowedTypesFullFromMixedUnsafe,
 	UnannotateAllowedTypesListUnsafe,
 	AnnotateAllowedTypesListUnsafe,
+	customizeSchemaTypingUnsafe,
 } from "./typesUnsafe.js";
 
 export {

packages/dds/tree/src/simple-tree/api/schemaFactory.ts

@@ -50,6 +50,7 @@ import {
 	type InsertableObjectFromSchemaRecord,
 	type TreeMapNode,
 	type TreeObjectNode,
+	type ObjectSchemaTypingOptions,
 } from "../node-kinds/index.js";
 import {
 	FieldKind,
@@ -100,7 +101,8 @@ export function schemaFromValue(value: TreeValue): TreeNodeSchema {
  * @beta
  */
 export interface ObjectSchemaOptions<TCustomMetadata = unknown>
-	extends NodeSchemaOptions<TCustomMetadata> {
+	extends NodeSchemaOptions<TCustomMetadata>,
+		ObjectSchemaTypingOptions {
 	/**
 	 * Allow nodes typed with this object node schema to contain optional fields that are not present in the schema declaration.
 	 * Such nodes can come into existence either via import APIs (see remarks) or by way of collaboration with another client
@@ -159,16 +161,6 @@ export interface ObjectSchemaOptionsAlpha<TCustomMetadata = unknown>
 	extends ObjectSchemaOptions<TCustomMetadata>,
 		NodeSchemaOptionsAlpha<TCustomMetadata> {}
 
-/**
- * Default options for Object node schema creation.
- * @remarks Omits parameters that are not relevant for common use cases.
- */
-export const defaultSchemaFactoryObjectOptions: Required<
-	Pick<ObjectSchemaOptions, "allowUnknownOptionalFields">
-> = {
-	allowUnknownOptionalFields: false,
-};
-
 /**
  * The name of a schema produced by {@link SchemaFactory}, including its optional scope prefix.
  *
@@ -397,9 +389,7 @@ export class SchemaFactory<
 		true,
 		T
 	> {
-		return objectSchema(scoped(this, name), fields, true, {
-			...defaultSchemaFactoryObjectOptions,
-		});
+		return objectSchema(scoped(this, name), fields, true);
 	}
 
 	/**

packages/dds/tree/src/simple-tree/api/schemaFactoryAlpha.ts

@@ -8,21 +8,21 @@ import {
 	arraySchema,
 	type MapNodeCustomizableSchema,
 	mapSchema,
+	type ObjectFromSchemaRecordRelaxed,
 	type ObjectNodeSchema,
 	objectSchema,
 	type RecordNodeCustomizableSchema,
 	recordSchema,
 } from "../node-kinds/index.js";
 import {
-	defaultSchemaFactoryObjectOptions,
 	scoped,
 	type NodeSchemaOptionsAlpha,
 	type ObjectSchemaOptionsAlpha,
 	type ScopedSchemaName,
 } from "./schemaFactory.js";
 import { schemaStatics } from "./schemaStatics.js";
 import type { ImplicitFieldSchema } from "../fieldSchema.js";
-import type { RestrictiveStringRecord } from "../../util/index.js";
+import type { PreventExtraProperties, RestrictiveStringRecord } from "../../util/index.js";
 import type {
 	NodeKind,
 	TreeNodeSchema,
@@ -33,6 +33,7 @@ import type {
 	WithType,
 	AllowedTypesMetadata,
 	AllowedTypesFullFromMixed,
+	TreeNode,
 } from "../core/index.js";
 import {
 	normalizeToAnnotatedAllowedType,
@@ -200,12 +201,12 @@ export class SchemaFactoryAlpha<
 	public objectAlpha<
 		const Name extends TName,
 		const T extends RestrictiveStringRecord<ImplicitFieldSchema>,
-		const TCustomMetadata = unknown,
+		const TOptions extends ObjectSchemaOptionsAlpha = ObjectSchemaOptionsAlpha,
 	>(
 		name: Name,
 		fields: T,
-		options?: ObjectSchemaOptionsAlpha<TCustomMetadata>,
-	): ObjectNodeSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> & {
+		options?: PreventExtraProperties<TOptions, ObjectSchemaOptionsAlpha>,
+	): ObjectNodeSchema<ScopedSchemaName<TScope, Name>, T, true, TOptions> & {
 		/**
 		 * Typing checking workaround: not for for actual use.
 		 * @remarks
@@ -218,10 +219,7 @@ export class SchemaFactoryAlpha<
 		 */
 		readonly createFromInsertable: unknown;
 	} {
-		return objectSchema(scoped<TScope, TName, Name>(this, name), fields, true, {
-			...defaultSchemaFactoryObjectOptions,
-			...(options ?? {}),
-		});
+		return objectSchema(scoped<TScope, TName, Name>(this, name), fields, true, options);
 	}
 
 	/**
@@ -230,11 +228,11 @@ export class SchemaFactoryAlpha<
 	public override objectRecursive<
 		const Name extends TName,
 		const T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>,
-		const TCustomMetadata = unknown,
+		const TOptions extends ObjectSchemaOptionsAlpha = ObjectSchemaOptionsAlpha,
 	>(
 		name: Name,
 		t: T,
-		options?: ObjectSchemaOptionsAlpha<TCustomMetadata>,
+		options?: PreventExtraProperties<TOptions, ObjectSchemaOptionsAlpha>,
 	): TreeNodeSchemaClass<
 		ScopedSchemaName<TScope, Name>,
 		NodeKind.Object,
@@ -243,9 +241,15 @@ export class SchemaFactoryAlpha<
 		false,
 		T,
 		never,
-		TCustomMetadata
+		TOptions extends ObjectSchemaOptionsAlpha<infer TCustomMetadataX>
+			? TCustomMetadataX
+			: unknown
 	> &
-		SimpleObjectNodeSchema<TCustomMetadata> &
+		SimpleObjectNodeSchema<
+			TOptions extends ObjectSchemaOptionsAlpha<infer TCustomMetadataX>
+				? TCustomMetadataX
+				: unknown
+		> &
 		// We can't just use non generic `ObjectNodeSchema` here since "Base constructors must all have the same return type".
 		// We also can't just use generic `ObjectNodeSchema` here and not `TreeNodeSchemaClass` since that doesn't work with unsafe recursive types.
 		// ObjectNodeSchema<
@@ -270,13 +274,15 @@ export class SchemaFactoryAlpha<
 			false,
 			T,
 			never,
-			TCustomMetadata
+			TOptions extends ObjectSchemaOptionsAlpha<infer TCustomMetadataX>
+				? TCustomMetadataX
+				: unknown
 		> &
 			ObjectNodeSchema<
 				ScopedSchemaName<TScope, Name>,
 				RestrictiveStringRecord<ImplicitFieldSchema>,
 				false,
-				TCustomMetadata
+				TOptions
 			>;
 	}
 
@@ -559,3 +565,37 @@ export class SchemaFactoryAlpha<
 		return new SchemaFactoryAlpha(scoped<TScope, TName, T>(this, name));
 	}
 }
+
+/**
+ * Convert an object node to a version with a relaxed types for its fields.
+ * @remarks
+ * This can help get TypeScript to allow sub-classing it in generic contexts.
+ * This must be to the class from the SchemaFactory then subclassed.
+ * @alpha
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function relaxObject<const T extends TreeNodeSchemaClass<string, NodeKind.Object>>(
+	t: T,
+) {
+	return t as T extends TreeNodeSchemaClass<
+		infer Name,
+		NodeKind.Object,
+		TreeNode,
+		infer TInsertable,
+		infer ImplicitlyConstructable,
+		infer Info extends RestrictiveStringRecord<ImplicitFieldSchema>,
+		infer TConstructorExtra,
+		infer TCustomMetadata
+	>
+		? TreeNodeSchemaClass<
+				Name,
+				NodeKind.Object,
+				TreeNode & WithType<Name, NodeKind.Object, T> & ObjectFromSchemaRecordRelaxed<Info>,
+				TInsertable,
+				ImplicitlyConstructable,
+				Info,
+				TConstructorExtra,
+				TCustomMetadata
+			>
+		: T;
+}

packages/dds/tree/src/simple-tree/api/schemaFactoryBeta.ts

@@ -22,12 +22,12 @@ import {
 	type TreeRecordNode,
 } from "../node-kinds/index.js";
 import {
-	defaultSchemaFactoryObjectOptions,
 	SchemaFactory,
 	scoped,
 	structuralName,
 	type NodeSchemaOptions,
 	type ObjectSchemaOptions,
+	type ObjectSchemaOptionsAlpha,
 	type ScopedSchemaName,
 } from "./schemaFactory.js";
 import type { System_Unsafe, TreeRecordNodeUnsafe } from "./typesUnsafe.js";
@@ -43,8 +43,8 @@ import type {
 } from "../fieldSchema.js";
 import type { LeafSchema } from "../leafNodeSchema.js";
 import type { SimpleLeafNodeSchema } from "../simpleSchema.js";
-import type { RestrictiveStringRecord } from "../../util/index.js";
 /* eslint-enable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import/no-duplicates */
+import type { PreventExtraProperties, RestrictiveStringRecord } from "../../util/index.js";
 
 /**
  * {@link SchemaFactory} with additional beta APIs.
@@ -77,25 +77,37 @@ export class SchemaFactoryBeta<
 	public override object<
 		const Name extends TName,
 		const T extends RestrictiveStringRecord<ImplicitFieldSchema>,
-		const TCustomMetadata = unknown,
+		const TOptions extends ObjectSchemaOptions = ObjectSchemaOptions,
 	>(
 		name: Name,
 		fields: T,
-		options?: ObjectSchemaOptions<TCustomMetadata>,
+		options?: PreventExtraProperties<TOptions, ObjectSchemaOptions>,
 	): TreeNodeSchemaClass<
 		ScopedSchemaName<TScope, Name>,
 		NodeKind.Object,
-		TreeObjectNode<T, ScopedSchemaName<TScope, Name>>,
+		TreeObjectNode<T, ScopedSchemaName<TScope, Name>, TOptions>,
 		object & InsertableObjectFromSchemaRecord<T>,
 		true,
 		T,
 		never,
-		TCustomMetadata
+		TOptions extends ObjectSchemaOptions<infer TCustomMetadata> ? TCustomMetadata : unknown
 	> {
-		return objectSchema(scoped<TScope, TName, Name>(this, name), fields, true, {
-			...defaultSchemaFactoryObjectOptions,
-			...(options ?? {}),
-		});
+		// TODO: make type safe
+		return objectSchema(
+			scoped<TScope, TName, Name>(this, name),
+			fields,
+			true,
+			options as PreventExtraProperties<TOptions, ObjectSchemaOptionsAlpha>,
+		) as TreeNodeSchemaClass<
+			ScopedSchemaName<TScope, Name>,
+			NodeKind.Object,
+			TreeObjectNode<T, ScopedSchemaName<TScope, Name>, TOptions>,
+			object & InsertableObjectFromSchemaRecord<T>,
+			true,
+			T,
+			never,
+			TOptions extends ObjectSchemaOptions<infer TCustomMetadata> ? TCustomMetadata : unknown
+		>;
 	}
 
 	public override objectRecursive<