Shared Tree: Simple Schema codec (#25741)

Introduces new APIs for encoding and decoding view schemas. Also adds
new fields to Simple Schemas to support compatibility checking
scenarios.

## Description

New APIs (in alpha):
- `encodeSimpleSchema(simpleSchema: SimpleTreeSchema):
JsonCompatibleReadOnly` - Encodes a Simple Schema into a JSON-compatible
object format.
- `decodeSimpleSchema(encodedSchema: JsonCompatibleReadOnly, validator?:
FormatValidator): SimpleTreeSchema` - Decodes a Simple Schema from a
JSON-compatible object format.

Other changes:

- Updated `toSimpleTreeSchema` to include `compatibility-related fields.
These include:
  - On SimpleAllowedTypeAttributes: `isStaged`
  - On object schemas: `allowUnknownOptionalTypes`

---------

Co-authored-by: Noah Encke <[email protected]>

Author: TommyBrosman

packages/common/core-utils/src/index.ts

@@ -33,3 +33,4 @@ export { PromiseTimer, setLongTimeout, Timer } from "./timer.js";
 export { unreachableCase } from "./unreachable.js";
 export { isObject, isPromiseLike } from "./typesGuards.js";
 export { oob } from "./oob.js";
+export { transformMapValues } from "./map.js";

packages/common/core-utils/src/map.ts

@@ -0,0 +1,19 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Transform the values of a Map using the provided transform function.
+ * @param map - The map to transform.
+ * @param transformValue - A method for transforming values in the map.
+ * @returns A new map with the transformed values.
+ *
+ * @internal
+ */
+export function transformMapValues<Key, InputValue, OutputValue>(
+	map: ReadonlyMap<Key, InputValue>,
+	transformValue: (value: InputValue, key: Key) => OutputValue,
+): Map<Key, OutputValue> {
+	return new Map([...map.entries()].map(([key, value]) => [key, transformValue(value, key)]));
+}

packages/dds/tree/api-report/tree.alpha.api.md

@@ -198,6 +198,9 @@ export function createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema,
 // @alpha
 export function createSimpleTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue, TSchema extends TreeNodeSchema>(view: TreeView<TFieldSchema>, indexer: Map<TreeNodeSchema, string>, getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey, indexableSchema: readonly TSchema[]): SimpleTreeIndex<TKey, TValue>;
 
+// @alpha
+export function decodeSimpleSchema(encodedSchema: JsonCompatibleReadOnly, validator?: FormatValidator): SimpleTreeSchema;
+
 // @public @sealed @system
 interface DefaultProvider extends ErasedType<"@fluidframework/tree.FieldProvider"> {
 }
@@ -213,6 +216,9 @@ export interface DirtyTreeMap {
 // @alpha
 export type DirtyTreeStatus = "new" | "changed" | "moved";
 
+// @alpha
+export function encodeSimpleSchema(simpleSchema: SimpleTreeSchema): JsonCompatibleReadOnly;
+
 // @beta
 export function enumFromStrings<TScope extends string, const Members extends readonly string[]>(factory: SchemaFactory<TScope>, members: Members): (<TValue extends Members[number]>(value: TValue) => TValue extends unknown ? TreeNode & {
     readonly value: TValue;
@@ -1071,6 +1077,7 @@ export interface SimpleObjectFieldSchema extends SimpleFieldSchema {
 
 // @alpha @sealed
 export interface SimpleObjectNodeSchema<out TCustomMetadata = unknown> extends SimpleNodeSchemaBaseAlpha<NodeKind.Object, TCustomMetadata> {
+    readonly allowUnknownOptionalFields: boolean | undefined;
     readonly fields: ReadonlyMap<string, SimpleObjectFieldSchema>;
 }
 

packages/dds/tree/src/index.ts

@@ -283,6 +283,8 @@ export {
 	type SchemaFactory_base,
 	type NumberKeys,
 	type SimpleAllowedTypeAttributes,
+	encodeSimpleSchema,
+	decodeSimpleSchema,
 } from "./simple-tree/index.js";
 export {
 	SharedTree,

packages/dds/tree/src/shared-tree/sharedTree.ts

@@ -935,6 +935,8 @@ function exportSimpleFieldSchemaStored(schema: TreeFieldStoredSchema): SimpleFie
  * Export a {@link SimpleNodeSchema} from a {@link TreeNodeStoredSchema}.
  * @privateRemarks
  * TODO: Persist node metadata once schema FormatV2 is supported.
+ * Note on SimpleNodeSchema construction: In the persisted format `persistedMetadata` is just called `metadata` whereas the `metadata`
+ * field on SimpleNodeSchema is not persisted.
  */
 function exportSimpleNodeSchemaStored(schema: TreeNodeStoredSchema): SimpleNodeSchema {
 	const arrayTypes = tryStoredSchemaAsArray(schema);
@@ -951,7 +953,13 @@ function exportSimpleNodeSchemaStored(schema: TreeNodeStoredSchema): SimpleNodeS
 		for (const [storedKey, field] of schema.objectNodeFields) {
 			fields.set(storedKey, { ...exportSimpleFieldSchemaStored(field), storedKey });
 		}
-		return { kind: NodeKind.Object, fields, metadata: {}, persistedMetadata: schema.metadata };
+		return {
+			kind: NodeKind.Object,
+			fields,
+			allowUnknownOptionalFields: undefined,
+			metadata: {},
+			persistedMetadata: schema.metadata,
+		};
 	}
 	if (schema instanceof MapNodeStoredSchema) {
 		assert(

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

@@ -167,3 +167,7 @@ export {
 	getShouldIncrementallySummarizeAllowedTypes,
 	incrementalSummaryHint,
 } from "./incrementalAllowedTypes.js";
+export {
+	encodeSimpleSchema,
+	decodeSimpleSchema,
+} from "./simpleSchemaCodec.js";

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

@@ -106,9 +106,12 @@ function generateNode(
 			for (const [key, field] of schema.fields) {
 				fields[key] = generateFieldSchema(field, context, field.storedKey);
 			}
-			// 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.objectAlpha(id, fields, { metadata: schema.metadata });
+			// Here allowUnknownOptionalFields is implicitly defaulting in the case where the input schema does not explicitly specify the value.
+			// 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.objectAlpha(id, fields, {
+				metadata: schema.metadata,
+				allowUnknownOptionalFields: schema.allowUnknownOptionalFields ?? false,
+			});
 		}
 		case NodeKind.Array:
 			return factory.arrayAlpha(id, generateAllowedTypes(schema.simpleAllowedTypes, context), {