@fluidframework/tree 2.70.0-361092 → 2.70.0-361788

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

@@ -60,7 +60,7 @@ export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
  * @privateRemarks
  * Since this is sealed, users are not supposed to create instances of it directly.
  * Making it extend ErasedType could enforce that.
- * @alpha
+ * @beta
  * @sealed
  */
 export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
@@ -77,7 +77,7 @@ export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
 /**
  * {@link AllowedTypesFull} but with the lazy schema references eagerly evaluated.
  * @sealed
- * @alpha
+ * @beta
  */
 export type AllowedTypesFullEvaluated = AllowedTypesFull<
 	readonly AnnotatedAllowedType<TreeNodeSchema>[]
@@ -95,7 +95,7 @@ export function isAnnotatedAllowedTypes(
 
 /**
  * Stores annotations for a set of allowed types.
- * @alpha
+ * @beta
  * @sealed
  */
 export interface AnnotatedAllowedTypes<T = readonly AnnotatedAllowedType[]>
@@ -139,7 +139,7 @@ export interface AnnotatedAllowedTypes<T = readonly AnnotatedAllowedType[]>
  * Stores annotations for a set of allowed types.
  * @remarks
  * Most expressive form of AllowedTypes which any of the implicit types can be normalized to.
- * @alpha
+ * @beta
  * @sealed
  */
 export type AllowedTypesFull<
@@ -148,8 +148,7 @@ export type AllowedTypesFull<
 
 /**
  * Creates an {@link AllowedTypesFull} type from a mixed array of annotated and unannotated allowed types.
- * @alpha
- * @sealed
+ * @system @sealed @beta
  */
 export type AllowedTypesFullFromMixed<
 	T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[],
@@ -360,7 +359,7 @@ export class AnnotatedAllowedTypesInternal<
  * Annotations that apply to a set of allowed types.
  * @remarks
  * Additional optionals may be added to this as non-breaking changes, so implementations of it should be simple object literals with no unlisted members.
- * @alpha
+ * @beta
  * @input
  */
 export interface AllowedTypesMetadata {
@@ -385,7 +384,7 @@ export function isAnnotatedAllowedType(
  * Annotations that apply to an individual allowed type.
  * @remarks
  * Additional optionals may be added to this as non-breaking changes, so implementations of it should be simple object literals with no unlisted members.
- * @alpha
+ * @beta
  * @input
  */
 export interface AllowedTypeMetadata {
@@ -413,7 +412,7 @@ export let createSchemaUpgrade: () => SchemaUpgrade;
  * TODO:#38722 implement runtime schema upgrades.
  * Until then, the class purely behaves mostly as a placeholder.
  * TODO: Consider allowing users to store a name for the upgrade to use in error messages.
- * @sealed @alpha
+ * @sealed @beta
  */
 export class SchemaUpgrade {
 	protected _typeCheck!: MakeNominal;
@@ -461,7 +460,7 @@ export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;
 
 /**
  * Removes annotations from a list of allowed types that may contain annotations.
- * @system @alpha
+ * @system @beta
  */
 export type UnannotateAllowedTypesList<
 	T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[],
@@ -471,7 +470,7 @@ export type UnannotateAllowedTypesList<
 
 /**
  * Add annotations to a list of allowed types that may or may not contain annotations.
- * @system @alpha
+ * @system @beta
  */
 export type AnnotateAllowedTypesList<
 	T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[],

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

@@ -16,7 +16,12 @@ export {
 	SimpleContextSlot,
 	withBufferedTreeEvents,
 } from "./treeNodeKernel.js";
-export { type WithType, typeNameSymbol, typeSchemaSymbol } from "./withType.js";
+export {
+	type WithType,
+	typeNameSymbol,
+	typeSchemaSymbol,
+	contentSchemaSymbol,
+} from "./withType.js";
 export {
 	type Unhydrated,
 	type InternalTreeNode,

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

@@ -10,7 +10,7 @@ import type { SimpleNodeSchemaBase } from "./simpleNodeSchemaBase.js";
 import type { TreeNode } from "./treeNode.js";
 import type { InternalTreeNode, Unhydrated } from "./types.js";
 import type { UnionToIntersection } from "../../util/index.js";
-import type { ImplicitAllowedTypes, AllowedTypesFullEvaluated } from "./allowedTypes.js";
+import type { AllowedTypesFullEvaluated, AllowedTypesFull } from "./allowedTypes.js";
 import type { Context } from "./context.js";
 import type { FieldKey, NodeData, TreeNodeStoredSchema } from "../../core/index.js";
 import type { UnhydratedFlexTreeField } from "./unhydratedFlexTree.js";
@@ -379,16 +379,11 @@ export interface TreeNodeSchemaPrivateData {
 	 * In this case "field" includes anything that is a field in the internal (flex-tree) abstraction layer.
 	 * This includes the content field for arrays, and all the fields for map nodes.
 	 * If this node does not have fields (and thus is a leaf), the array will be empty.
-	 *
-	 * This set cannot be used before the schema in it have been defined:
-	 * more specifically, when using lazy schema references (for example to make foreword references to schema which have not yet been defined),
-	 * users must wait until after the schema are defined to access this array.
-	 *
 	 * @privateRemarks
 	 * If this is stabilized, it will live alongside the childTypes property on {@link TreeNodeSchemaCore}.
 	 * @system
 	 */
-	readonly childAnnotatedAllowedTypes: readonly ImplicitAllowedTypes[];
+	readonly childAllowedTypes: readonly AllowedTypesFull[];
 
 	/**
 	 * Idempotent initialization function that pre-caches data and can dereference lazy schema references.
@@ -422,7 +417,7 @@ export interface TreeNodeSchemaInitializedData {
 	 * If this is stabilized, it will live alongside the childTypes property on {@link TreeNodeSchemaCore}.
 	 * @system
 	 */
-	readonly childAnnotatedAllowedTypes: readonly AllowedTypesFullEvaluated[];
+	readonly childAllowedTypes: readonly AllowedTypesFullEvaluated[];
 
 	/**
 	 * A {@link Context} which can be used for unhydrated nodes of this schema.

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

@@ -25,7 +25,7 @@ import {
 } from "./treeNodeKernel.js";
 import type { InternalTreeNode } from "./types.js";
 import { typeSchemaSymbol } from "./withType.js";
-import type { ImplicitAllowedTypes } from "./allowedTypes.js";
+import type { AllowedTypesFull } from "./allowedTypes.js";
 import type { SimpleNodeSchemaBase } from "./simpleNodeSchemaBase.js";
 
 /**
@@ -259,7 +259,7 @@ export function isClassBasedSchema(
  */
 export function createTreeNodeSchemaPrivateData(
 	schema: TreeNodeSchemaCore<string, NodeKind, boolean>,
-	childAnnotatedAllowedTypes: readonly ImplicitAllowedTypes[],
+	childAllowedTypes: readonly AllowedTypesFull[],
 	toStored: TreeNodeSchemaPrivateData["toStored"],
 ): TreeNodeSchemaPrivateData {
 	const schemaValid = schemaAsTreeNodeValid(schema);
@@ -269,7 +269,7 @@ export function createTreeNodeSchemaPrivateData(
 
 	return {
 		idempotentInitialize: () => schemaValid.oneTimeInitialize().oneTimeInitialized,
-		childAnnotatedAllowedTypes,
+		childAllowedTypes,
 		toStored,
 	};
 }

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

@@ -28,8 +28,7 @@ export function walkNodeSchema(
 	// Since walkNodeSchema is used in the implementation of TreeNodeSchemaPrivateData.idempotentInitialize,
 	// Avoid depending on it here to avoid circular dependencies for recursive schema.
 	// Instead normalize/evaluate the allowed types as needed.
-	const annotatedAllowedTypes =
-		getTreeNodeSchemaPrivateData(schema).childAnnotatedAllowedTypes;
+	const annotatedAllowedTypes = getTreeNodeSchemaPrivateData(schema).childAllowedTypes;
 
 	for (const fieldAllowedTypes of annotatedAllowedTypes) {
 		walkAllowedTypes(

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

@@ -5,6 +5,9 @@
 
 import type { TreeNode } from "./treeNode.js";
 import type { NodeKind, TreeNodeSchemaClass } from "./treeNodeSchema.js";
+// Used by doc links:
+// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports
+import type { TreeAlpha } from "../../shared-tree/index.js";
 
 /**
  * The type of a {@link TreeNode}.
@@ -39,6 +42,27 @@ export const typeNameSymbol: unique symbol = Symbol("TreeNode Type");
  */
 export const typeSchemaSymbol: unique symbol = Symbol("TreeNode Schema");
 
+/**
+ * The intended type of insertable content that is to become a {@link TreeNode}.
+ * @remarks Use the type-safe {@link (TreeAlpha:interface).tagContentSchema} function to tag insertable content with this symbol.
+ *
+ * If a property with this symbol key is present on an object that is inserted into the tree,
+ * the tree will use the schema identifier specified by the value of this property when creating the node.
+ * This is particularly useful for specifying the intended schema of untyped content when it would otherwise be ambiguous.
+ * @example
+ * ```typescript
+ * const sf = new SchemaFactory("example");
+ * class Dog extends sf.object("Dog", { name: sf.string() }) {}
+ * class Cat extends sf.object("Cat", { name: sf.string() }) {}
+ * class Root extends sf.object("Root", { pet: [Dog, Cat] }) {}
+ * // ...
+ * view.root.pet = { name: "Max" }; // Error: ambiguous schema - is it a Dog or a Cat?
+ * view.root.pet = { name: "Max", [contentSchemaSymbol]: "example.Dog" }; // No error - it's a Dog.
+ * ```
+ * @alpha
+ */
+export const contentSchemaSymbol: unique symbol = Symbol("SharedTree Schema");
+
 /**
  * Adds a type symbol to a type for stronger typing.
  *

package/src/simple-tree/createContext.ts

@@ -9,7 +9,6 @@ import { getOrCreate } from "../util/index.js";
 import {
 	Context,
 	getTreeNodeSchemaPrivateData,
-	normalizeAndEvaluateAnnotatedAllowedTypes,
 	UnhydratedContext,
 	type TreeNodeSchema,
 	type TreeNodeSchemaInitializedData,
@@ -50,8 +49,6 @@ export function getTreeNodeSchemaInitializedData(
 	return {
 		...handler,
 		context: getUnhydratedContext(schema),
-		childAnnotatedAllowedTypes: data.childAnnotatedAllowedTypes.map(
-			normalizeAndEvaluateAnnotatedAllowedTypes,
-		),
+		childAllowedTypes: data.childAllowedTypes.map((t) => t.evaluate()),
 	};
 }

package/src/simple-tree/index.ts

@@ -6,6 +6,7 @@
 export {
 	typeNameSymbol,
 	typeSchemaSymbol,
+	contentSchemaSymbol,
 	type WithType,
 	type TreeNodeSchema,
 	type AnnotatedAllowedType,
@@ -135,7 +136,9 @@ export {
 	type UnannotateAllowedTypesListUnsafe,
 	type AnnotateAllowedTypesListUnsafe,
 	type TreeViewAlpha,
+	type TreeViewBeta,
 	type TreeBranch,
+	type TreeBranchAlpha,
 	type TreeBranchEvents,
 	getPropertyKeyFromStoredKey,
 	getStoredKey,
@@ -180,6 +183,8 @@ export {
 	type SchemaStaticsAlpha,
 	KeyEncodingOptions,
 	type TreeParsingOptions,
+	incrementalSummaryHint,
+	getShouldIncrementallySummarizeAllowedTypes,
 	type SchemaFactory_base,
 } from "./api/index.js";
 export type {

package/src/simple-tree/leafNodeSchema.ts

@@ -63,7 +63,7 @@ export class LeafNodeSchema<Name extends string, const T extends ValueSchema>
 					allowedTypes: ReadonlySet<TreeNodeSchema>,
 				): FlexContent => leafToFlexContent(data, this, allowedTypes),
 			})),
-		childAnnotatedAllowedTypes: [],
+		childAllowedTypes: [],
 		toStored: () => new LeafNodeStoredSchema(this.leafKind),
 	};
 	#initializedData: TreeNodeSchemaInitializedData | undefined;

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -1273,8 +1273,11 @@ export function arraySchema<
 		}
 
 		public static get [privateDataSymbol](): TreeNodeSchemaPrivateData {
-			return (privateData ??= createTreeNodeSchemaPrivateData(this, [info], (storedOptions) =>
-				arrayNodeStoredSchema(convertAllowedTypes(info, storedOptions), persistedMetadata),
+			return (privateData ??= createTreeNodeSchemaPrivateData(
+				this,
+				[normalizedTypes],
+				(storedOptions) =>
+					arrayNodeStoredSchema(convertAllowedTypes(info, storedOptions), persistedMetadata),
 			));
 		}
 	}

package/src/simple-tree/node-kinds/map/mapNode.ts

@@ -336,7 +336,7 @@ export function mapSchema<
 		public static get [privateDataSymbol](): TreeNodeSchemaPrivateData {
 			return (privateData ??= createTreeNodeSchemaPrivateData(
 				this,
-				[info],
+				[normalizedTypes],
 				(storedOptions) =>
 					new MapNodeStoredSchema(
 						{

package/src/simple-tree/node-kinds/object/objectNode.ts

@@ -577,10 +577,7 @@ export function objectSchema<
 		public static get [privateDataSymbol](): TreeNodeSchemaPrivateData {
 			return (privateData ??= createTreeNodeSchemaPrivateData(
 				this,
-				Array.from(
-					flexKeyMap.values(),
-					({ schema }) => normalizeFieldSchema(schema).allowedTypes,
-				),
+				Array.from(CustomObjectNode.fields.values(), (schema) => schema.allowedTypesFull),
 				(storedOptions) => {
 					const fields: Map<FieldKey, TreeFieldStoredSchema> = new Map();
 					for (const fieldSchema of flexKeyMap.values()) {

package/src/simple-tree/node-kinds/record/recordNode.ts

@@ -381,7 +381,7 @@ export function recordSchema<
 		public static get [privateDataSymbol](): TreeNodeSchemaPrivateData {
 			return (privateData ??= createTreeNodeSchemaPrivateData(
 				this,
-				[info],
+				[normalizedTypes],
 				(storedOptions) =>
 					new MapNodeStoredSchema(
 						{

package/src/simple-tree/unhydratedFlexTreeFromInsertable.ts

@@ -17,6 +17,7 @@ import {
 	isTreeNode,
 	type TreeNode,
 	type TreeNodeSchema,
+	contentSchemaSymbol,
 	type Unhydrated,
 	UnhydratedFlexTreeNode,
 } from "./core/index.js";
@@ -125,16 +126,28 @@ For class-based schema, this can be done by replacing an expression like "{foo:
 
 /**
  * Returns all types for which the data is schema-compatible.
+ * @remarks This will respect the {@link contentSchemaSymbol} property on data to disambiguate types - if present, only that type will be returned.
  */
 export function getPossibleTypes(
 	allowedTypes: ReadonlySet<TreeNodeSchema>,
 	data: FactoryContent,
 ): TreeNodeSchema[] {
 	assert(data !== undefined, 0x889 /* undefined cannot be used as FactoryContent. */);
+	const type =
+		typeof data === "object" && data !== null
+			? (data as Partial<{ [contentSchemaSymbol]: string }>)[contentSchemaSymbol]
+			: undefined;
 
 	let best = CompatibilityLevel.None;
 	const possibleTypes: TreeNodeSchema[] = [];
 	for (const schema of allowedTypes) {
+		if (type !== undefined) {
+			if (schema.identifier === type) {
+				return [schema];
+			} else {
+				continue;
+			}
+		}
 		const handler = getTreeNodeSchemaPrivateData(schema).idempotentInitialize();
 		const level = handler.shallowCompatibilityTest(data);
 		if (level > best) {

package/src/util/nestedMap.ts

@@ -49,7 +49,7 @@ export function tryAddToNestedMap<Key1, Key2, Value>(
  * @param destination - The map to copy data into. Both the outer and inner map may be mutated.
  * @param override - Whether existing entries in `destination` should be replaced by corresponding entries in `source`.
  *
- * @remarks - This function performs deep copying when necessary.
+ * @remarks This function performs deep copying when necessary.
  * This ensures that mutating `destination` after this call will not result in unexpected mutations to `source`.
  */
 export function populateNestedMap<Key1, Key2, Value>(

package/src/util/referenceCounting.ts

@@ -8,7 +8,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 /**
  * An object which counts the number of users / references to it.
  * @remarks
- * This implements the [Reference counting](https://en.wikipedia.org/wiki/Reference_counting) pattern.
+ * This implements the {@link https://en.wikipedia.org/wiki/Reference_counting | Reference counting} pattern.
  * Getting the reference count correct is difficult in TypeScript and great care must be used.
  * Because of this, this interface should not be used in the public API.
  */