@fluidframework/tree 2.51.0 → 2.52.0

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

@@ -4,65 +4,61 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
 	CursorLocationType,
+	forbiddenFieldKindIdentifier,
 	mapCursorField,
 	mapCursorFields,
 	type ITreeCursorSynchronous,
 	type SchemaAndPolicy,
 } from "../../core/index.js";
-import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../fieldSchema.js";
+import {
+	normalizeFieldSchema,
+	type ImplicitFieldSchema,
+	type TreeFieldFromImplicitField,
+} from "../fieldSchema.js";
 import {
 	type Context,
 	getOrCreateNodeFromInnerNode,
-	type NodeKind,
 	type Unhydrated,
 	UnhydratedFlexTreeNode,
 	createField,
 } from "../core/index.js";
 import {
 	defaultSchemaPolicy,
-	inSchemaOrThrow,
 	isFieldInSchema,
+	throwOutOfSchema,
 } from "../../feature-libraries/index.js";
 import { getUnhydratedContext } from "../createContext.js";
-import { createUnknownOptionalFieldPolicy } from "../node-kinds/index.js";
-import type { SimpleNodeSchema, SimpleNodeSchemaBase } from "../simpleSchema.js";
-import { getStoredSchema } from "../toStoredSchema.js";
+import { convertField } from "../toStoredSchema.js";
 import { unknownTypeError } from "./customTree.js";
 
 /**
  * Creates an unhydrated simple-tree field from a cursor in nodes mode.
  * @remarks
- * Does not support defaults.
- * Validates the field is in schema.
- *
- * TODO: AB#43548: How this handles unknown optional fields needs to be figured out, tested and documented.
+ * Does not support providing missing defaults values.
+ * Validates the field is in schema using the provided `contextForNewNodes` of the default unhydrated context if not provided.
  */
 export function createFromCursor<const TSchema extends ImplicitFieldSchema>(
 	schema: TSchema,
 	cursor: ITreeCursorSynchronous | undefined,
+	contextForNewNodes?: Context,
 ): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
-	const context = getUnhydratedContext(schema);
+	const context = contextForNewNodes ?? getUnhydratedContext(schema);
+	assert(context.flexContext.isHydrated() === false, 0xbfe /* Expected unhydrated context */);
 	const mapTrees = cursor === undefined ? [] : [unhydratedFlexTreeFromCursor(context, cursor)];
 
-	const flexSchema = context.flexContext.schema;
+	const rootFieldSchema = convertField(normalizeFieldSchema(schema));
 
-	const schemaValidationPolicy: SchemaAndPolicy = {
-		policy: {
-			...defaultSchemaPolicy,
-			allowUnknownOptionalFields: createUnknownOptionalFieldPolicy(schema),
-		},
+	const schemaAndPolicy: SchemaAndPolicy = {
+		policy: defaultSchemaPolicy,
 		schema: context.flexContext.schema,
 	};
 
-	const maybeError = isFieldInSchema(
-		mapTrees,
-		flexSchema.rootFieldSchema,
-		schemaValidationPolicy,
-	);
-	inSchemaOrThrow(maybeError);
+	// Assuming the caller provides the correct `contextForNewNodes`, this should handle unknown optional fields.
+	isFieldInSchema(mapTrees, rootFieldSchema, schemaAndPolicy, throwOutOfSchema);
 
 	if (mapTrees.length === 0) {
 		return undefined as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
@@ -80,27 +76,44 @@ export function createFromCursor<const TSchema extends ImplicitFieldSchema>(
 /**
  * Construct an {@link UnhydratedFlexTreeNode} from a cursor in Nodes mode.
  * @remarks
- * This does not validate the node is in schema.
+ * This does not fully validate the node is in schema, but does throw UsageErrors for some cases of out-of-schema content.
+ *
+ * Does not support unknown optional fields: will throw a UsageError if the field is not in schema.
+ * This cannot easily be fixed as this code requires a schema for each subtree to process, and none is available for unknown optional fields.
  */
 export function unhydratedFlexTreeFromCursor(
 	context: Context,
 	cursor: ITreeCursorSynchronous,
 ): UnhydratedFlexTreeNode {
 	assert(cursor.mode === CursorLocationType.Nodes, 0xbb4 /* Expected nodes cursor */);
-	const schema = context.schema.get(cursor.type) ?? unknownTypeError(cursor.type);
-	const storedSchema = getStoredSchema(
-		schema as SimpleNodeSchemaBase<NodeKind> as SimpleNodeSchema,
-	);
+	const identifier = cursor.type;
+	const storedSchema =
+		context.flexContext.schema.nodeSchema.get(identifier) ?? unknownTypeError(identifier);
+
 	const fields = new Map(
-		mapCursorFields(cursor, () => [
-			cursor.getFieldKey(),
-			createField(
-				context.flexContext,
-				storedSchema.getFieldSchema(cursor.getFieldKey()).kind,
+		mapCursorFields(cursor, () => {
+			const fieldSchema = storedSchema.getFieldSchema(cursor.getFieldKey());
+			if (fieldSchema.kind === forbiddenFieldKindIdentifier) {
+				// Check for unexpected fields before recursing into children:
+				// Code which hits this case is very likely to also use an unknown type in the unexpected field, which would give a more confusing error message.
+				// This case is detected here to improve error quality.
+				// Also note that if using the view schema from above to suppress this error for unknownOptionalFields, that would not provide a way to handle unknown types in those fields:
+				// they would still error, but with that more confusing message about unknown types.
+				throw new UsageError(
+					// Using JSON.stringify to handle quoting and escaping since both key and identifier can technically contain quotes themselves.
+					`Field ${JSON.stringify(cursor.getFieldKey())} is not defined in the schema ${JSON.stringify(identifier)}.`,
+				);
+			}
+			return [
 				cursor.getFieldKey(),
-				mapCursorField(cursor, () => unhydratedFlexTreeFromCursor(context, cursor)),
-			),
-		]),
+				createField(
+					context.flexContext,
+					fieldSchema.kind,
+					cursor.getFieldKey(),
+					mapCursorField(cursor, () => unhydratedFlexTreeFromCursor(context, cursor)),
+				),
+			];
+		}),
 	);
 	return new UnhydratedFlexTreeNode(
 		{ type: cursor.type, value: cursor.value },

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

@@ -19,6 +19,7 @@ import {
 	type ITreeCursor,
 	type TreeNodeSchemaIdentifier,
 	type TreeNodeStoredSchema,
+	type TreeTypeSet,
 } from "../../core/index.js";
 import { FieldKinds, valueSchemaAllows } from "../../feature-libraries/index.js";
 import { cloneWithReplacements } from "../../util/index.js";
@@ -30,7 +31,7 @@ import {
 	numberSchema,
 	stringSchema,
 } from "../leafNodeSchema.js";
-import { isArrayNodeSchema, isObjectNodeSchema } from "../node-kinds/index.js";
+import { isObjectNodeSchema } from "../node-kinds/index.js";
 
 /**
  * Options for how to interpret or encode a tree when schema information is available.
@@ -42,7 +43,15 @@ export interface TreeEncodingOptions {
 	 * If false, use the property keys.
 	 * @remarks
 	 * Has no effect on {@link NodeKind}s other than {@link NodeKind.Object}.
+	 *
+	 * {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields|Unknown optional field} will be omitted when using property keys.
 	 * @defaultValue false.
+	 * @privateRemarks
+	 * TODO AB#43548:
+	 * Replace this with an enum that provides three options:
+	 * - `usePropertyKeys`: use property keys. Supported for import and export.
+	 * - `allStoredKeys`: use stored keys, and include unknown optional fields. Supported for export only, at least for the short term.
+	 * - `knownStoredKeys`: use stored keys but do not include unknown optional fields. Supported for import and export.
 	 */
 	readonly useStoredKeys?: boolean;
 }
@@ -77,19 +86,31 @@ export type CustomTreeNode<TChild> = TChild[] | { [key: string]: TChild };
 
 /**
  * Builds an {@link CustomTree} from a cursor in Nodes mode.
+ *
+ * @param reader - The cursor to read from.
+ * @param options - Options for how to interpret the tree.
+ * @param storedSchema - Schema which the cursor must comply with.
+ * Must be be possible to map to a view schema (mainly that sequences can only occur in the special ArrayNode pattern).
+ * Must include even unknown optional fields.
+ * @param schema - View schema used to derive the property keys for fields when `options` selects them via {@link TreeEncodingOptions.useStoredKeys}.
+ * @param childHandler - Function to handle children of the cursor.
+ *
+ * @remarks
+ * This can handle unknown optional fields only because they are included in the `storedSchema` and `schema` is only needed when using property keys, which also skips unknown optional fields.
  */
 export function customFromCursor<TChild>(
 	reader: ITreeCursor,
 	options: Required<TreeEncodingOptions>,
+	storedSchema: ReadonlyMap<string, TreeNodeStoredSchema>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 	childHandler: (
 		reader: ITreeCursor,
 		options: Required<TreeEncodingOptions>,
+		storedSchema: ReadonlyMap<string, TreeNodeStoredSchema>,
 		schema: ReadonlyMap<string, TreeNodeSchema>,
 	) => TChild,
 ): CustomTree<TChild> {
 	const type = reader.type;
-	const nodeSchema = schema.get(type) ?? fail(0xb2e /* missing schema for type in cursor */);
 
 	switch (type) {
 		case numberSchema.identifier:
@@ -105,28 +126,44 @@ export function customFromCursor<TChild>(
 			return reader.value;
 		default: {
 			assert(reader.value === undefined, 0xa54 /* out of schema: unexpected value */);
-			if (isArrayNodeSchema(nodeSchema)) {
+			const nodeSchema =
+				storedSchema.get(type) ?? fail(0xb2e /* missing schema for type in cursor */);
+			const arrayTypes = tryStoredSchemaAsArray(nodeSchema);
+
+			if (arrayTypes !== undefined) {
 				const fields = inCursorField(reader, EmptyKey, () =>
-					mapCursorField(reader, () => childHandler(reader, options, schema)),
+					mapCursorField(reader, () => childHandler(reader, options, storedSchema, schema)),
 				);
 				return fields;
 			} else {
 				const fields: Record<string, TChild> = {};
 				forEachField(reader, () => {
-					const children = mapCursorField(reader, () => childHandler(reader, options, schema));
-					if (children.length === 1) {
-						const storedKey = reader.getFieldKey();
-						const key =
-							isObjectNodeSchema(nodeSchema) && !options.useStoredKeys
-								? (nodeSchema.storedKeyToPropertyKey.get(storedKey) ??
-									fail(0xb2f /* missing property key */))
-								: storedKey;
-						// Length is checked above.
-						// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-						fields[key] = children[0]!;
+					assert(reader.getFieldLength() === 1, 0xa19 /* invalid children number */);
+					const storedKey = reader.getFieldKey();
+					let key: string;
+					if (!options.useStoredKeys) {
+						const viewSchema =
+							schema.get(type) ?? fail(0xbff /* missing schema for type in cursor */);
+						if (isObjectNodeSchema(viewSchema)) {
+							const propertyKey = viewSchema.storedKeyToPropertyKey.get(storedKey);
+							if (propertyKey === undefined) {
+								assert(
+									viewSchema.allowUnknownOptionalFields,
+									0xc00 /* found unknown field where not allowed */,
+								);
+								// Skip unknown optional fields when using property keys.
+								return;
+							}
+							key = propertyKey;
+						} else {
+							key = storedKey;
+						}
 					} else {
-						assert(children.length === 0, 0xa19 /* invalid children number */);
+						key = storedKey;
 					}
+					reader.enterNode(0);
+					fields[key] = childHandler(reader, options, storedSchema, schema);
+					reader.exitNode();
 				});
 				return fields;
 			}
@@ -181,16 +218,18 @@ export function customFromCursorStored<TChild>(
 }
 
 /**
- * Assumes `schema` corresponds to a simple-tree schema.
+ * Checks if `schema` could correspond to a simple-tree array node.
  * If it is an array schema, returns the allowed types for the array field.
  * Otherwise returns `undefined`.
+ * @remarks
+ * If the schema was defined by the public API, this will be accurate since there is no way to define an object node with a sequence field.
  */
-export function tryStoredSchemaAsArray(
-	schema: TreeNodeStoredSchema,
-): ReadonlySet<string> | undefined {
+export function tryStoredSchemaAsArray(schema: TreeNodeStoredSchema): TreeTypeSet | undefined {
 	if (schema instanceof ObjectNodeStoredSchema) {
 		const empty = schema.getFieldSchema(EmptyKey);
 		if (empty.kind === FieldKinds.sequence.identifier) {
+			// This assert can only be hit by schema created not using the public API surface.
+			// If at some point this case needs to be tolerated, it can be replaced by "return undefined"
 			assert(schema.objectNodeFields.size === 1, 0xa9f /* invalid schema */);
 			return empty.types;
 		}