@fluidframework/tree 2.10.0 → 2.12.0

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

@@ -5,32 +5,56 @@
 
 import {
 	AdaptedViewSchema,
+	type TreeNodeStoredSchema,
 	type Adapters,
-	Compatibility,
 	type TreeFieldStoredSchema,
 	type TreeNodeSchemaIdentifier,
-	type TreeNodeStoredSchema,
 	type TreeStoredSchema,
 } from "../../core/index.js";
 import { fail } from "../../util/index.js";
 import {
+	FieldKinds,
 	type FullSchemaPolicy,
-	allowsRepoSuperset,
+	type FieldDiscrepancy,
+	getAllowedContentDiscrepancies,
 	isNeverTree,
+	PosetComparisonResult,
+	fieldRealizer,
+	comparePosetElements,
 } from "../../feature-libraries/index.js";
+import {
+	normalizeFieldSchema,
+	type FieldSchema,
+	type ImplicitFieldSchema,
+} from "../schemaTypes.js";
+import { toStoredSchema } from "../toStoredSchema.js";
+import { unreachableCase } from "@fluidframework/core-utils/internal";
+import type { SchemaCompatibilityStatus } from "./tree.js";
 
 /**
  * A collection of View information for schema, including policy.
  */
 export class ViewSchema {
 	/**
-	 * @param schema - Cached conversion of view schema in the stored schema format.
+	 * Cached conversion of the view schema in the stored schema format.
+	 */
+	private readonly viewSchemaAsStored: TreeStoredSchema;
+	/**
+	 * Normalized view schema (implicitly allowed view schema types are converted to their canonical form).
+	 */
+	public readonly schema: FieldSchema;
+
+	/**
+	 * @param viewSchema - Schema for the root field of this view.
 	 */
 	public constructor(
 		public readonly policy: FullSchemaPolicy,
 		public readonly adapters: Adapters,
-		public readonly schema: TreeStoredSchema,
-	) {}
+		viewSchema: ImplicitFieldSchema,
+	) {
+		this.schema = normalizeFieldSchema(viewSchema);
+		this.viewSchemaAsStored = toStoredSchema(this.schema);
+	}
 
 	/**
 	 * Determines the compatibility of a stored document
@@ -42,53 +66,168 @@ export class ViewSchema {
 	 * TODO: this API violates the parse don't validate design philosophy.
 	 * It should be wrapped with (or replaced by) a parse style API.
 	 */
-	public checkCompatibility(stored: TreeStoredSchema): {
-		read: Compatibility;
-		write: Compatibility;
-		writeAllowingStoredSchemaUpdates: Compatibility;
-	} {
+	public checkCompatibility(
+		stored: TreeStoredSchema,
+	): Omit<SchemaCompatibilityStatus, "canInitialize"> {
 		// TODO: support adapters
 		// const adapted = this.adaptRepo(stored);
 
-		const read = allowsRepoSuperset(this.policy, stored, this.schema)
-			? Compatibility.Compatible
-			: // TODO: support adapters
-				// : allowsRepoSuperset(this.policy, adapted.adaptedForViewSchema, this.storedSchema)
-				// ? Compatibility.RequiresAdapters
-				Compatibility.Incompatible;
-		// TODO: Extract subset of adapters that are valid to use on stored
-		// TODO: separate adapters from schema updates
-		const write = allowsRepoSuperset(this.policy, this.schema, stored)
-			? Compatibility.Compatible
-			: // TODO: support adapters
-				// : allowsRepoSuperset(this.policy, this.storedSchema, adapted.adaptedForViewSchema)
-				// TODO: IThis assumes adapters are bidirectional.
-				//   Compatibility.RequiresAdapters
-				Compatibility.Incompatible;
-
-		// TODO: compute this properly (and maybe include the set of schema changes needed for it?).
-		// Maybe updates would happen lazily when needed to store data?
-		// When willingness to updates can avoid need for some adapters,
-		// how should it be decided if the adapter should be used to avoid the update?
-		// TODO: is this case actually bi-variant, making this correct if we did it for each schema independently?
-		let writeAllowingStoredSchemaUpdates =
-			// TODO: This should consider just the updates needed
-			// (ex: when view covers a subset of stored after stored has a update to that subset).
-			allowsRepoSuperset(this.policy, stored, this.schema)
-				? Compatibility.Compatible
-				: // TODO: this assumes adapters can translate in both directions. In general this will not be true.
-					// TODO: this also assumes that schema updates to the adapted repo would translate to
-					// updates on the stored schema, which is also likely untrue.
-					// // TODO: support adapters
-					// allowsRepoSuperset(this.policy, adapted.adaptedForViewSchema, this.storedSchema)
-					// ? Compatibility.RequiresAdapters // Requires schema updates. TODO: consider adapters that can update writes.
-					Compatibility.Incompatible;
-
-		// Since the above does not consider partial updates,
-		// we can improve the tolerance a bit by considering the op-op update:
-		writeAllowingStoredSchemaUpdates = Math.max(writeAllowingStoredSchemaUpdates, write);
-
-		return { read, write, writeAllowingStoredSchemaUpdates };
+		// View schema allows a subset of documents that stored schema does, and the discrepancies are allowed by policy
+		// determined by the view schema (i.e. objects with extra optional fields in the stored schema have opted into allowing this.
+		// In the future, this would also include things like:
+		// - fields with more allowed types in the stored schema than in the view schema have out-of-schema "unknown content" adapters
+		let canView = true;
+		// View schema allows a superset of documents that stored schema does, hence the document could be upgraded to use a persisted version
+		// of this view schema as its stored schema.
+		let canUpgrade = true;
+
+		const updateCompatibilityFromFieldDiscrepancy = (discrepancy: FieldDiscrepancy): void => {
+			switch (discrepancy.mismatch) {
+				case "allowedTypes": {
+					// Since we only track the symmetric difference between the allowed types in the view and
+					// stored schemas, it's sufficient to check if any extra allowed types still exist in the
+					// stored schema.
+					if (
+						discrepancy.stored.some(
+							(identifier) =>
+								!isNeverTree(this.policy, stored, stored.nodeSchema.get(identifier)),
+						)
+					) {
+						// Stored schema has extra allowed types that the view schema does not.
+						canUpgrade = false;
+						canView = false;
+					}
+
+					if (
+						discrepancy.view.some(
+							(identifier) =>
+								!isNeverTree(
+									this.policy,
+									this.viewSchemaAsStored,
+									this.viewSchemaAsStored.nodeSchema.get(identifier),
+								),
+						)
+					) {
+						// View schema has extra allowed types that the stored schema does not.
+						canView = false;
+					}
+					break;
+				}
+				case "fieldKind": {
+					const result = comparePosetElements(
+						discrepancy.stored,
+						discrepancy.view,
+						fieldRealizer,
+					);
+
+					if (result === PosetComparisonResult.Greater) {
+						// Stored schema is more relaxed than view schema.
+						canUpgrade = false;
+						if (
+							discrepancy.view === FieldKinds.forbidden.identifier &&
+							discrepancy.identifier !== undefined &&
+							this.policy.allowUnknownOptionalFields(discrepancy.identifier)
+						) {
+							// When the application has opted into it, we allow viewing documents which have additional
+							// optional fields in the stored schema that are not present in the view schema.
+						} else {
+							canView = false;
+						}
+					}
+
+					if (result === PosetComparisonResult.Less) {
+						// View schema is more relaxed than stored schema.
+						canView = false;
+					}
+
+					if (result === PosetComparisonResult.Incomparable) {
+						canUpgrade = false;
+						canView = false;
+					}
+
+					break;
+				}
+				case "valueSchema": {
+					canView = false;
+					canUpgrade = false;
+					break;
+				}
+				default:
+					unreachableCase(discrepancy);
+			}
+		};
+
+		for (const discrepancy of getAllowedContentDiscrepancies(
+			this.viewSchemaAsStored,
+			stored,
+		)) {
+			if (!canView && !canUpgrade) {
+				break;
+			}
+
+			switch (discrepancy.mismatch) {
+				case "nodeKind": {
+					const viewNodeSchema = this.viewSchemaAsStored.nodeSchema.get(
+						discrepancy.identifier,
+					);
+					const storedNodeSchema = stored.nodeSchema.get(discrepancy.identifier);
+					// We conservatively do not allow node types to change.
+					// The only time this might be valid in the sense that the data canonically converts is converting an object node
+					// to a map node over the union of all the object fields' types.
+					if (discrepancy.stored === undefined) {
+						const viewIsNever =
+							viewNodeSchema !== undefined
+								? isNeverTree(this.policy, this.viewSchemaAsStored, viewNodeSchema)
+								: true;
+						if (!viewIsNever) {
+							// View schema has added a node type that the stored schema doesn't know about.
+							canView = false;
+						}
+					} else if (discrepancy.view === undefined) {
+						const storedIsNever =
+							storedNodeSchema !== undefined
+								? isNeverTree(this.policy, stored, storedNodeSchema)
+								: true;
+						if (!storedIsNever) {
+							// Stored schema has a node type that the view schema doesn't know about.
+							canUpgrade = false;
+						}
+					} else {
+						// Node type exists in both schemas but has changed. We conservatively never allow this.
+						const storedIsNever =
+							storedNodeSchema !== undefined
+								? isNeverTree(this.policy, stored, storedNodeSchema)
+								: true;
+						const viewIsNever =
+							viewNodeSchema !== undefined
+								? isNeverTree(this.policy, this.viewSchemaAsStored, viewNodeSchema)
+								: true;
+						if (!storedIsNever || !viewIsNever) {
+							canView = false;
+							canUpgrade = false;
+						}
+					}
+					break;
+				}
+				case "valueSchema":
+				case "allowedTypes":
+				case "fieldKind": {
+					updateCompatibilityFromFieldDiscrepancy(discrepancy);
+					break;
+				}
+				case "fields": {
+					discrepancy.differences.forEach(updateCompatibilityFromFieldDiscrepancy);
+					break;
+				}
+				// No default
+			}
+		}
+
+		return {
+			canView,
+			canUpgrade,
+			isEquivalent: canView && canUpgrade,
+		};
 	}
 
 	/**
@@ -102,8 +241,15 @@ export class ViewSchema {
 		// since there never is a reason to have a never type as an adapter input,
 		// and its impossible for an adapter to be correctly implemented if its output type is never
 		// (unless its input is also never).
+
 		for (const adapter of this.adapters?.tree ?? []) {
-			if (isNeverTree(this.policy, this.schema, this.schema.nodeSchema.get(adapter.output))) {
+			if (
+				isNeverTree(
+					this.policy,
+					this.viewSchemaAsStored,
+					this.viewSchemaAsStored.nodeSchema.get(adapter.output),
+				)
+			) {
 				fail("tree adapter for stored adapter.output should not be never");
 			}
 		}

package/src/simple-tree/core/index.ts

@@ -12,6 +12,7 @@ export {
 	tryDisposeTreeNode,
 	tryGetTreeNodeFromMapNode,
 	getOrCreateInnerNode,
+	treeNodeFromAnchor,
 } from "./treeNodeKernel.js";
 export { type WithType, typeNameSymbol, typeSchemaSymbol } from "./withType.js";
 export {

package/src/simple-tree/core/treeNodeKernel.ts

@@ -4,13 +4,15 @@
  */
 
 import { assert, Lazy } from "@fluidframework/core-utils/internal";
-import { createEmitter, type Listenable, type Off } from "../../events/index.js";
-import type { TreeNode, Unhydrated } from "./types.js";
+import { createEmitter } from "@fluid-internal/client-utils";
+import type { Listenable, Off } from "@fluidframework/core-interfaces";
+import type { InternalTreeNode, TreeNode, Unhydrated } from "./types.js";
 import {
 	anchorSlot,
 	type AnchorEvents,
 	type AnchorNode,
 	type AnchorSet,
+	type TreeValue,
 	type UpPath,
 } from "../../core/index.js";
 import {
@@ -447,3 +449,36 @@ export function getOrCreateInnerNode(treeNode: TreeNode, allowFreed = false): In
 	const kernel = getKernel(treeNode);
 	return kernel.getOrCreateInnerNode(allowFreed);
 }
+
+/**
+ * Gets a flex node from an anchor node
+ */
+function flexNodeFromAnchor(anchorNode: AnchorNode): FlexTreeNode {
+	// the proxy is bound to an anchor node, but it may or may not have an actual flex node yet
+	const flexNode = anchorNode.slots.get(flexTreeSlot);
+	if (flexNode !== undefined) {
+		return flexNode; // If it does have a flex node, return it...
+	} // ...otherwise, the flex node must be created
+	const context = anchorNode.anchorSet.slots.get(ContextSlot) ?? fail("missing context");
+	const cursor = context.checkout.forest.allocateCursor("getFlexNode");
+	context.checkout.forest.moveCursorToPath(anchorNode, cursor);
+	const newFlexNode = makeTree(context, cursor);
+	cursor.free();
+	return newFlexNode;
+}
+
+/**
+ * Gets a tree node from an anchor node
+ */
+export function treeNodeFromAnchor(anchorNode: AnchorNode): TreeNode | TreeValue {
+	const cached = anchorNode.slots.get(proxySlot);
+	if (cached !== undefined) {
+		return cached;
+	}
+
+	const flexNode = flexNodeFromAnchor(anchorNode);
+	const classSchema = getTreeNodeSchemaFromHydratedFlexNode(flexNode);
+	return typeof classSchema === "function"
+		? new classSchema(flexNode as unknown as InternalTreeNode)
+		: (classSchema as { create(data: FlexTreeNode): TreeValue }).create(flexNode);
+}

package/src/simple-tree/core/unhydratedFlexTree.ts

@@ -4,6 +4,8 @@
  */
 
 import { assert, oob } from "@fluidframework/core-utils/internal";
+import { createEmitter } from "@fluid-internal/client-utils";
+import type { Listenable } from "@fluidframework/core-interfaces";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
@@ -43,7 +45,6 @@ import {
 	cursorForMapTreeNode,
 } from "../../feature-libraries/index.js";
 import type { Context } from "./context.js";
-import { createEmitter, type Listenable } from "../../events/index.js";
 
 interface UnhydratedTreeSequenceFieldEditBuilder
 	extends SequenceFieldEditBuilder<ExclusiveMapTree[]> {

package/src/simple-tree/index.ts

@@ -35,6 +35,7 @@ export {
 	type SchemaCompatibilityStatus,
 	type ITreeConfigurationOptions,
 	SchemaFactory,
+	type SchemaFactoryObjectOptions,
 	type ScopedSchemaName,
 	type ValidateRecursiveSchema,
 	type FixRecursiveArraySchema,
@@ -51,6 +52,10 @@ export {
 	type NodeChangedData,
 	TreeBeta,
 	type TreeChangeEventsBeta,
+	type SimpleTreeIndex,
+	type IdentifierIndex,
+	createSimpleTreeIndex,
+	createIdentifierIndex,
 	type SimpleNodeSchemaBase,
 	type SimpleTreeSchema,
 	type SimpleNodeSchema,
@@ -114,6 +119,10 @@ export {
 	conciseFromCursor,
 	createFromCursor,
 	asTreeViewAlpha,
+	customFromCursorStored,
+	type CustomTreeNode,
+	type CustomTreeValue,
+	tryStoredSchemaAsArray,
 } from "./api/index.js";
 export {
 	type NodeFromSchema,
@@ -162,6 +171,7 @@ export {
 	type ObjectFromSchemaRecord,
 	type TreeObjectNode,
 	setField,
+	createUnknownOptionalFieldPolicy,
 } from "./objectNode.js";
 export type { TreeMapNode, MapNodeInsertableData } from "./mapNode.js";
 export {

package/src/simple-tree/leafNodeSchema.ts

@@ -68,27 +68,8 @@ function makeLeaf<Name extends string, const T extends ValueSchema>(
 }
 
 // Leaf schema shared between all SchemaFactory instances.
-/**
- * @internal
- */
 export const stringSchema = makeLeaf("string", ValueSchema.String);
-
-/**
- * @internal
- */
 export const numberSchema = makeLeaf("number", ValueSchema.Number);
-
-/**
- * @internal
- */
 export const booleanSchema = makeLeaf("boolean", ValueSchema.Boolean);
-
-/**
- * @internal
- */
 export const nullSchema = makeLeaf("null", ValueSchema.Null);
-
-/**
- * @internal
- */
 export const handleSchema = makeLeaf("handle", ValueSchema.FluidHandle);

package/src/simple-tree/objectNode.ts

@@ -6,7 +6,7 @@
 import { assert, Lazy } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import type { FieldKey } from "../core/index.js";
+import type { FieldKey, SchemaPolicy } from "../core/index.js";
 import {
 	FieldKinds,
 	type FlexTreeField,
@@ -42,7 +42,11 @@ import {
 } from "./core/index.js";
 import { mapTreeFromNodeData, type InsertableContent } from "./toMapTree.js";
 import { type RestrictiveStringRecord, fail, type FlattenKeys } from "../util/index.js";
-import type { ObjectNodeSchema, ObjectNodeSchemaInternalData } from "./objectNodeTypes.js";
+import {
+	isObjectNodeSchema,
+	type ObjectNodeSchema,
+	type ObjectNodeSchemaInternalData,
+} from "./objectNodeTypes.js";
 import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
 import { getUnhydratedContext } from "./createContext.js";
 
@@ -100,24 +104,31 @@ export type FieldHasDefault<T extends ImplicitFieldSchema> = T extends FieldSche
  *
  * @see {@link Input}
  *
- * @privateRemarks TODO: consider separating these cases into different types.
+ * @privateRemarks
+ * TODO: consider separating these cases into different types.
+ *
+ * Empty objects don't get "no excess property" checks in literals.
+ * To prevent extraneous properties in literals for the fields of an empty object from compiling, the empty case is special cased to produce `Record<string, never>`.
+ * More details at {@link https://mercury.com/blog/creating-an-emptyobject-type-in-typescript}.
  *
  * @system @public
  */
 export type InsertableObjectFromSchemaRecord<
 	T extends RestrictiveStringRecord<ImplicitFieldSchema>,
-> = FlattenKeys<
-	{
-		readonly [Property in keyof T]?: InsertableTreeFieldFromImplicitField<
-			T[Property & string]
+> = Record<string, never> extends T
+	? Record<string, never>
+	: FlattenKeys<
+			{
+				readonly [Property in keyof T]?: InsertableTreeFieldFromImplicitField<
+					T[Property & string]
+				>;
+			} & {
+				// Field does not have a known default, make it required:
+				readonly [Property in keyof T as FieldHasDefault<T[Property & string]> extends false
+					? Property
+					: never]: InsertableTreeFieldFromImplicitField<T[Property & string]>;
+			}
 		>;
-	} & {
-		// Field does not have a known default, make it required:
-		readonly [Property in keyof T as FieldHasDefault<T[Property & string]> extends false
-			? Property
-			: never]: InsertableTreeFieldFromImplicitField<T[Property & string]>;
-	}
->;
 
 /**
  * Maps from simple field keys ("property" keys) to information about the field.
@@ -323,6 +334,7 @@ export function objectSchema<
 	identifier: TName,
 	info: T,
 	implicitlyConstructable: ImplicitlyConstructable,
+	allowUnknownOptionalFields: boolean,
 ): ObjectNodeSchema<TName, T, ImplicitlyConstructable> & ObjectNodeSchemaInternalData {
 	// Ensure no collisions between final set of property keys, and final set of stored keys (including those
 	// implicitly derived from property keys)
@@ -361,6 +373,7 @@ export function objectSchema<
 			]),
 		);
 		public static readonly identifierFieldKeys: readonly FieldKey[] = identifierFieldKeys;
+		public static readonly allowUnknownOptionalFields: boolean = allowUnknownOptionalFields;
 
 		public static override prepareInstance<T2>(
 			this: typeof TreeNodeValid<T2>,
@@ -502,3 +515,21 @@ function assertUniqueKeys<
 		derivedStoredKeys.add(storedKey);
 	}
 }
+
+/**
+ * Creates a policy for allowing unknown optional fields on an object node which delegates to the policy defined
+ * on the object node's internal schema data.
+ */
+export function createUnknownOptionalFieldPolicy(
+	schema: ImplicitFieldSchema,
+): SchemaPolicy["allowUnknownOptionalFields"] {
+	const context = getUnhydratedContext(schema);
+	return (identifier) => {
+		const storedSchema = context.schema.get(identifier);
+		return (
+			storedSchema !== undefined &&
+			isObjectNodeSchema(storedSchema) &&
+			storedSchema.allowUnknownOptionalFields
+		);
+	};
+}

package/src/simple-tree/objectNodeTypes.ts

@@ -55,6 +55,11 @@ export interface ObjectNodeSchemaInternalData {
 	 * Stored keys which hold identifiers.
 	 */
 	readonly identifierFieldKeys: readonly FieldKey[];
+
+	/**
+	 * Whether to tolerate (and preserve) additional unknown optional fields in instances of this object node.
+	 */
+	readonly allowUnknownOptionalFields: boolean;
 }
 
 export const ObjectNodeSchema = {

package/src/simple-tree/schemaTypes.ts

@@ -24,6 +24,7 @@ import type {
 	TreeNodeSchemaClass,
 	TreeNode,
 	TreeNodeSchemaCore,
+	TreeNodeSchemaNonClass,
 } from "./core/index.js";
 import type { FieldKey } from "../core/index.js";
 import type { InsertableContent } from "./toMapTree.js";
@@ -759,15 +760,19 @@ export type InsertableTreeNodeFromAllowedTypes<TList extends AllowedTypes> =
 
 /**
  * Takes in `TreeNodeSchema[]` and returns a TypedNode union.
+ * @privateRemarks
+ * If a schema is both TreeNodeSchemaClass and TreeNodeSchemaNonClass, prefer TreeNodeSchemaClass since that includes subclasses properly.
  * @public
  */
-export type NodeFromSchema<T extends TreeNodeSchema> = T extends TreeNodeSchema<
+export type NodeFromSchema<T extends TreeNodeSchema> = T extends TreeNodeSchemaClass<
 	string,
 	NodeKind,
 	infer TNode
 >
 	? TNode
-	: never;
+	: T extends TreeNodeSchemaNonClass<string, NodeKind, infer TNode>
+		? TNode
+		: never;
 
 /**
  * Data which can be used as a node to be inserted.

package/src/simple-tree/toMapTree.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob } from "@fluidframework/core-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 
@@ -21,7 +21,7 @@ import {
 	valueSchemaAllows,
 	type NodeKeyManager,
 } from "../feature-libraries/index.js";
-import { brand, fail, isReadonlyArray, find } from "../util/index.js";
+import { brand, fail, isReadonlyArray, find, hasSome, hasSingle } from "../util/index.js";
 
 import { nullSchema } from "./leafNodeSchema.js";
 import {
@@ -465,10 +465,10 @@ function getType(
 		);
 	}
 	assert(
-		possibleTypes.length !== 0,
+		hasSome(possibleTypes),
 		0x84e /* data is incompatible with all types allowed by the schema */,
 	);
-	if (possibleTypes.length !== 1) {
+	if (!hasSingle(possibleTypes)) {
 		throw new UsageError(
 			`The provided data is compatible with more than one type allowed by the schema.
 The set of possible types is ${JSON.stringify([
@@ -478,7 +478,7 @@ Explicitly construct an unhydrated node of the desired type to disambiguate.
 For class-based schema, this can be done by replacing an expression like "{foo: 1}" with "new MySchema({foo: 1})".`,
 		);
 	}
-	return possibleTypes[0] ?? oob();
+	return possibleTypes[0];
 }
 
 /**