@fluidframework/tree 2.63.0-359461 → 2.63.0-359962

package/src/index.ts

@@ -94,7 +94,8 @@ export {
 	SchemaFactory,
 	SchemaFactoryBeta,
 	SchemaFactoryAlpha,
-	type SchemaFactoryObjectOptions,
+	type ObjectSchemaOptionsAlpha,
+	type ObjectSchemaOptions,
 	type ImplicitFieldSchema,
 	type TreeFieldFromImplicitField,
 	type TreeChangeEvents,
@@ -136,6 +137,13 @@ export {
 	type ArrayNodeCustomizableSchemaUnsafe,
 	type MapNodeCustomizableSchemaUnsafe,
 	type TreeRecordNodeUnsafe,
+	type UnannotateAllowedTypeUnsafe,
+	type AnnotatedAllowedTypeUnsafe,
+	type AnnotatedAllowedTypesUnsafe,
+	type AllowedTypesFullUnsafe,
+	type AllowedTypesFullFromMixedUnsafe,
+	type UnannotateAllowedTypesListUnsafe,
+	type AnnotateAllowedTypesListUnsafe,
 	// System types (not in Internal types for various reasons, like doc links or cannot be named errors).
 	type typeSchemaSymbol,
 	type TreeNodeSchemaNonClass,
@@ -163,21 +171,16 @@ export {
 	type FactoryContentObject,
 	type ReadableField,
 	type ReadSchema,
-	type ImplicitAnnotatedAllowedTypes,
-	type ImplicitAnnotatedFieldSchema,
 	type AnnotatedAllowedType,
 	type AnnotatedAllowedTypes,
-	type NormalizedAnnotatedAllowedTypes,
+	type AllowedTypesFullEvaluated,
 	type AllowedTypeMetadata,
 	type AllowedTypesMetadata,
-	type InsertableObjectFromAnnotatedSchemaRecord,
-	type UnannotateImplicitAllowedTypes,
-	type UnannotateAllowedTypes,
-	type UnannotateAllowedType,
 	type UnannotateAllowedTypesList,
-	type UnannotateImplicitFieldSchema,
-	type UnannotateSchemaRecord,
 	type SchemaStaticsAlpha,
+	type AnnotateAllowedTypesList,
+	type AllowedTypesFull,
+	type AllowedTypesFullFromMixed,
 	// Beta APIs
 	TreeBeta,
 	type TreeChangeEventsBeta,
@@ -273,6 +276,7 @@ export {
 	KeyEncodingOptions,
 	type TreeParsingOptions,
 	type SchemaFactory_base,
+	type NumberKeys,
 } from "./simple-tree/index.js";
 export {
 	SharedTree,

package/src/jsonDomainSchema.ts

@@ -37,7 +37,7 @@ const sf = new SchemaFactoryAlpha("com.fluidframework.json");
  *
  * 2. The order of fields on an object is not preserved. The resulting order is arbitrary.
  *
- * JSON data can be imported from JSON into this format using `JSON.parse` then {@link (TreeAlpha:interface).importConcise} with the {@link JsonAsTree.(Tree:variable)} schema.
+ * JSON data can be imported from JSON into this format using `JSON.parse` then {@link (TreeBeta:interface).importConcise} with the {@link JsonAsTree.(Tree:variable)} schema.
  *
  * @alpha
  */
@@ -63,7 +63,7 @@ export namespace JsonAsTree {
 	 * {@link AllowedTypes} for any content allowed in the {@link JsonAsTree} domain.
 	 * @example
 	 * ```typescript
-	 * const tree = TreeAlpha.importConcise(JsonAsTree.Union, { example: { nested: true }, value: 5 });
+	 * const tree = TreeBeta.importConcise(JsonAsTree.Union, { example: { nested: true }, value: 5 });
 	 * ```
 	 * @privateRemarks
 	 * The order here should not matter for any functionality related reasons.
@@ -95,7 +95,7 @@ export namespace JsonAsTree {
 	 * // Due to TypeScript restrictions on recursive types, the constructor and be somewhat limiting.
 	 * const fromArray = new JsonAsTreeObject([["a", 0]]);
 	 * // Using `importConcise` can work better for JSON data:
-	 * const imported = TreeAlpha.importConcise(JsonAsTree.Object, { a: 0 });
+	 * const imported = TreeBeta.importConcise(JsonAsTree.Object, { a: 0 });
 	 * // Node API is like a Map:
 	 * const value = imported.get("a");
 	 * ```
@@ -128,13 +128,13 @@ export namespace JsonAsTree {
 	/**
 	 * Arbitrary JSON array as a {@link TreeNode}.
 	 * @remarks
-	 * This can be imported using {@link (TreeAlpha:interface).importConcise}.
+	 * This can be imported using {@link (TreeBeta:interface).importConcise}.
 	 * @example
 	 * ```typescript
 	 * // Due to TypeScript restrictions on recursive types, the constructor can be somewhat limiting.
 	 * const usingConstructor = new JsonAsTree.Array(["a", 0, new JsonAsTree.Array([1])]);
 	 * // Using `importConcise` can work better for JSON data:
-	 * const imported = TreeAlpha.importConcise(JsonAsTree.Array, ["a", 0, [1]]);
+	 * const imported = TreeBeta.importConcise(JsonAsTree.Array, ["a", 0, [1]]);
 	 * // Node API is like an Array:
 	 * const inner: JsonAsTree.Tree = imported[2];
 	 * assert(Tree.is(inner, JsonAsTree.Array));

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.63.0-359461";
+export const pkgVersion = "2.63.0-359962";

package/src/serializableDomainSchema.ts

@@ -23,14 +23,14 @@ const sf = new SchemaFactoryAlpha("com.fluidframework.serializable");
  * @remarks
  * Schema which replicate the Fluid Serializable data model with {@link TreeNode}s.
  *
- * Fluid Serializable data can be imported from the {@link FluidSerializableAsTree.Data|Fluid Serializable format} into this format using {@link (TreeAlpha:interface).importConcise} with the {@link FluidSerializableAsTree.(Tree:variable)} schema.
+ * Fluid Serializable data can be imported from the {@link FluidSerializableAsTree.Data|Fluid Serializable format} into this format using {@link (TreeBeta:interface).importConcise} with the {@link FluidSerializableAsTree.(Tree:variable)} schema.
  * @alpha
  */
 export namespace FluidSerializableAsTree {
 	/**
 	 * Data which can be serialized by Fluid.
 	 * @remarks
-	 * Can be encoded as a {@link FluidSerializableAsTree.(Tree:type)} using {@link (TreeAlpha:interface).importConcise}.
+	 * Can be encoded as a {@link FluidSerializableAsTree.(Tree:type)} using {@link (TreeBeta:interface).importConcise}.
 	 * @alpha
 	 */
 	export type Data = JsonCompatible<IFluidHandle>;
@@ -39,7 +39,7 @@ export namespace FluidSerializableAsTree {
 	 * {@link AllowedTypes} for any content allowed in the {@link FluidSerializableAsTree} domain.
 	 * @example
 	 * ```typescript
-	 * const tree = TreeAlpha.importConcise(FluidSerializableAsTree.Tree, { example: { nested: true }, value: 5 });
+	 * const tree = TreeBeta.importConcise(FluidSerializableAsTree.Tree, { example: { nested: true }, value: 5 });
 	 * ```
 	 * @alpha
 	 */
@@ -69,7 +69,7 @@ export namespace FluidSerializableAsTree {
 	 * // Due to TypeScript restrictions on recursive types, the constructor and be somewhat limiting.
 	 * const fromArray = new JsonAsTreeObject([["a", 0]]);
 	 * // Using `importConcise` can work better for Fluid Serializable data:
-	 * const imported = TreeAlpha.importConcise(FluidSerializableAsTree.Object, { a: 0 });
+	 * const imported = TreeBeta.importConcise(FluidSerializableAsTree.Object, { a: 0 });
 	 * // Node API is like a Map:
 	 * const value = imported.get("a");
 	 * ```
@@ -102,13 +102,13 @@ export namespace FluidSerializableAsTree {
 	/**
 	 * Arbitrary Fluid Serializable array as a {@link TreeNode}.
 	 * @remarks
-	 * This can be imported using {@link (TreeAlpha:interface).importConcise}.
+	 * This can be imported using {@link (TreeBeta:interface).importConcise}.
 	 * @example
 	 * ```typescript
 	 * // Due to TypeScript restrictions on recursive types, the constructor can be somewhat limiting.
 	 * const usingConstructor = new FluidSerializableAsTree.Array(["a", 0, new FluidSerializableAsTree.Array([1])]);
 	 * // Using `importConcise` can work better for Fluid Serializable data:
-	 * const imported = TreeAlpha.importConcise(FluidSerializableAsTree.Array, ["a", 0, [1]]);
+	 * const imported = TreeBeta.importConcise(FluidSerializableAsTree.Array, ["a", 0, [1]]);
 	 * // Node API is like an Array:
 	 * const inner: FluidSerializableAsTree.Tree = imported[2];
 	 * assert(Tree.is(inner, FluidSerializableAsTree.Array));

package/src/shared-tree/independentView.ts

@@ -26,6 +26,7 @@ import {
 	type FieldBatchEncodingContext,
 	defaultSchemaPolicy,
 	TreeCompressionStrategy,
+	defaultIncrementalEncodingPolicy,
 } from "../feature-libraries/index.js";
 // eslint-disable-next-line import/no-internal-modules
 import type { Format } from "../feature-libraries/schema-index/formatV1.js";
@@ -67,6 +68,7 @@ export function independentView<const TSchema extends ImplicitFieldSchema>(
 		options.forest ?? defaultSharedTreeOptions.forest,
 		schema,
 		idCompressor,
+		defaultIncrementalEncodingPolicy,
 	);
 	const checkout = createTreeCheckout(idCompressor, mintRevisionTag, revisionTagCodec, {
 		forest,
@@ -144,6 +146,7 @@ export function independentInitializedViewInternal<const TSchema extends Implici
 		options.forest ?? defaultSharedTreeOptions.forest,
 		schemaRepository,
 		idCompressor,
+		defaultIncrementalEncodingPolicy,
 	);
 
 	const checkout = createTreeCheckout(idCompressor, mintRevisionTag, revisionTagCodec, {

package/src/shared-tree/schematizingTreeView.ts

@@ -12,13 +12,17 @@ import type {
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { anchorSlot } from "../core/index.js";
+import { anchorSlot, rootFieldKey } from "../core/index.js";
 import {
 	type NodeIdentifierManager,
 	defaultSchemaPolicy,
 	cursorForMapTreeField,
 	TreeStatus,
 	Context,
+	type FlexTreeOptionalField,
+	type FlexTreeUnknownUnboxed,
+	FieldKinds,
+	type FlexTreeRequiredField,
 } from "../feature-libraries/index.js";
 import {
 	type ImplicitFieldSchema,
@@ -38,7 +42,7 @@ import {
 	type UnsafeUnknownSchema,
 	type TreeBranch,
 	type TreeBranchEvents,
-	getOrCreateInnerNode,
+	getInnerNode,
 	getKernel,
 	type VoidTransactionCallbackStatus,
 	type TransactionCallbackStatus,
@@ -117,6 +121,11 @@ export class SchematizingSimpleTreeView<
 	 */
 	private midUpgrade = false;
 
+	/**
+	 * Hydration work deferred until Context has been created.
+	 */
+	private pendingHydration?: () => void;
+
 	private readonly rootFieldSchema: FieldSchema;
 	public readonly breaker: Breakable;
 
@@ -174,6 +183,13 @@ export class SchematizingSimpleTreeView<
 
 		this.runSchemaEdit(() => {
 			const schema = toInitialSchema(this.config.schema);
+			// This has to be the contextless version, since when "initialize" is called (right after this),
+			// it will do a schema change which would dispose of the current context (see inside `update`).
+			// Thus using the current context (if any) would hydrate nodes then
+			// immediately dispose them instead of having them actually be useable after initialize.
+			// For this to work,
+			// the hydration must be deferred until after the content is inserted into the tree and the final schema change is done (for required roots),
+			// but before any user event could could run.
 			const mapTree = prepareForInsertionContextless(
 				content as InsertableContent | undefined,
 				this.rootFieldSchema,
@@ -183,6 +199,19 @@ export class SchematizingSimpleTreeView<
 				},
 				this,
 				schema.rootFieldSchema,
+				(batches, doHydration) => {
+					assert(this.pendingHydration === undefined, "pendingHydration already set");
+					this.pendingHydration = () => {
+						assert(batches.length <= 1, "initialize should at most one hydration batch");
+						for (const batch of batches) {
+							doHydration(batch, {
+								parent: undefined,
+								parentField: rootFieldKey,
+								parentIndex: 0,
+							});
+						}
+					};
+				},
 			);
 
 			this.checkout.transaction.start();
@@ -336,7 +365,7 @@ export class SchematizingSimpleTreeView<
 				new HydratedContext(
 					this.flexTreeContext,
 					HydratedContext.schemaMapFromRootSchema(
-						this.rootFieldSchema.annotatedAllowedTypesNormalized,
+						this.rootFieldSchema.allowedTypesFull.evaluate(),
 					),
 				),
 			);
@@ -350,7 +379,10 @@ export class SchematizingSimpleTreeView<
 				// TODO: provide a better event: this.view.flexTree.on(????) and/or integrate with with the normal event code paths.
 
 				// Track what the root was before to be able to detect changes.
-				let lastRoot: ReadableField<TRootSchema> = this.root;
+				// This uses the flex tree root to avoid demanding the simple-tree TreeNode when it might not be hydrated yet.
+				let lastRoot: FlexTreeUnknownUnboxed | undefined = (
+					this.flexTreeContext.root as FlexTreeOptionalField
+				).content;
 
 				this.flexTreeViewUnregisterCallbacks.add(
 					this.checkout.events.on("afterBatch", () => {
@@ -359,8 +391,8 @@ export class SchematizingSimpleTreeView<
 						// - The rootChanged event will already be raised at the end of the current upgrade
 						// - It doesn't matter that `lastRoot` isn't updated in this case, because `update` will be called again before the upgrade
 						//   completes (at which point this callback and the `lastRoot` captured here will be out of scope anyway)
-						if (!this.midUpgrade && lastRoot !== this.root) {
-							lastRoot = this.root;
+						if (!this.midUpgrade && lastRoot !== this.flexRoot.content) {
+							lastRoot = this.flexRoot.content;
 							this.events.emit("rootChanged");
 						}
 					}),
@@ -374,6 +406,10 @@ export class SchematizingSimpleTreeView<
 		);
 
 		if (!this.midUpgrade) {
+			assert(
+				this.pendingHydration === undefined,
+				"no nodes should be pending hydration when triggering events that could access nodes",
+			);
 			this.events.emit("schemaChanged");
 			this.events.emit("rootChanged");
 		}
@@ -386,6 +422,9 @@ export class SchematizingSimpleTreeView<
 		} finally {
 			this.midUpgrade = false;
 		}
+		// Ensure hydration is flushed before events run which could access nodes.
+		this.pendingHydration?.();
+		this.pendingHydration = undefined;
 		this.events.emit("schemaChanged");
 		this.events.emit("rootChanged");
 	}
@@ -426,7 +465,7 @@ export class SchematizingSimpleTreeView<
 		}
 	}
 
-	public get root(): ReadableField<TRootSchema> {
+	private get flexRoot(): FlexTreeOptionalField | FlexTreeRequiredField {
 		this.breaker.use();
 		if (!this.compatibility.canView) {
 			throw new UsageError(
@@ -434,7 +473,17 @@ export class SchematizingSimpleTreeView<
 			);
 		}
 		const view = this.getFlexTreeContext();
-		return tryGetTreeNodeForField(view.root) as ReadableField<TRootSchema>;
+		assert(
+			view.root.is(FieldKinds.optional) ||
+				view.root.is(FieldKinds.required) ||
+				view.root.is(FieldKinds.identifier),
+			"unexpected root field kind",
+		);
+		return view.root;
+	}
+
+	public get root(): ReadableField<TRootSchema> {
+		return tryGetTreeNodeForField(this.flexRoot) as ReadableField<TRootSchema>;
 	}
 
 	public set root(newRoot: InsertableField<TRootSchema>) {
@@ -499,7 +548,7 @@ export function addConstraintsToTransaction(
 	for (const constraint of constraints) {
 		switch (constraint.type) {
 			case "nodeInDocument": {
-				const node = getOrCreateInnerNode(constraint.node);
+				const node = getInnerNode(constraint.node);
 				const nodeStatus = getKernel(constraint.node).getStatus();
 				if (nodeStatus !== TreeStatus.InDocument) {
 					const revertText = constraintsOnRevert ? " on revert" : "";

package/src/shared-tree/sharedTree.ts

@@ -38,7 +38,6 @@ import {
 	type SchemaFormatVersion,
 	SchemaVersion,
 	type TreeFieldStoredSchema,
-	type TreeNodeSchemaIdentifier,
 	type TreeNodeStoredSchema,
 	type TreeStoredSchema,
 	TreeStoredSchemaRepository,
@@ -55,6 +54,7 @@ import {
 	TreeCompressionStrategy,
 	buildChunkedForest,
 	buildForest,
+	defaultIncrementalEncodingPolicy,
 	defaultSchemaPolicy,
 	getCodecTreeForFieldBatchFormat,
 	getCodecTreeForForestFormat,
@@ -64,6 +64,7 @@ import {
 	makeMitigatedChangeFamily,
 	makeSchemaCodec,
 	makeTreeChunker,
+	type IncrementalEncodingPolicy,
 	type FieldBatchFormatVersion,
 	type ForestFormatVersion,
 	type TreeCompressionStrategyPrivate,
@@ -305,7 +306,13 @@ export class SharedTreeKernel
 		const options = { ...defaultSharedTreeOptions, ...optionsParam };
 		const codecVersions = getCodecVersions(options.formatVersion);
 		const schema = new TreeStoredSchemaRepository();
-		const forest = buildConfiguredForest(breaker, options.forest, schema, idCompressor);
+		const forest = buildConfiguredForest(
+			breaker,
+			options.forest,
+			schema,
+			idCompressor,
+			options.shouldEncodeIncrementally,
+		);
 		const revisionTagCodec = new RevisionTagCodec(idCompressor);
 		const removedRoots = makeDetachedFieldIndex(
 			"repair",
@@ -339,7 +346,7 @@ export class SharedTreeKernel
 			encoderContext,
 			options,
 			idCompressor,
-			options.shouldEncodeFieldIncrementally,
+			options.shouldEncodeIncrementally,
 		);
 		const removedRootsSummarizer = new DetachedFieldIndexSummarizer(removedRoots);
 		const innerChangeFamily = new SharedTreeChangeFamily(
@@ -794,16 +801,11 @@ export interface SharedTreeOptionsInternal
 		Partial<SharedTreeFormatOptionsInternal> {
 	disposeForksAfterTransaction?: boolean;
 	/**
-	 * Returns whether a field should be incrementally encoded.
-	 * @param nodeIdentifier - The identifier of the node containing the field.
-	 * @param fieldKey - The key of the field to check.
+	 * Returns whether a node / field should be incrementally encoded.
 	 * @remarks
-	 * The policy for which fields should get incremental encoding should eventually be specified some other way.
+	 * See {@link IncrementalEncodingPolicy}.
 	 */
-	shouldEncodeFieldIncrementally?(
-		nodeIdentifier: TreeNodeSchemaIdentifier,
-		fieldKey: FieldKey,
-	): boolean;
+	shouldEncodeIncrementally?: IncrementalEncodingPolicy;
 }
 /**
  * Configuration options for SharedTree's internal tree storage.
@@ -882,8 +884,17 @@ export const ForestTypeReference = toForestType(
  * @beta
  */
 export const ForestTypeOptimized = toForestType(
-	(breaker: Breakable, schema: TreeStoredSchemaSubscription, idCompressor: IIdCompressor) =>
-		buildChunkedForest(makeTreeChunker(schema, defaultSchemaPolicy), undefined, idCompressor),
+	(
+		breaker: Breakable,
+		schema: TreeStoredSchemaSubscription,
+		idCompressor: IIdCompressor,
+		shouldEncodeIncrementally: IncrementalEncodingPolicy,
+	) =>
+		buildChunkedForest(
+			makeTreeChunker(schema, defaultSchemaPolicy, shouldEncodeIncrementally),
+			undefined,
+			idCompressor,
+		),
 );
 
 /**
@@ -904,6 +915,7 @@ type ForestFactory = (
 	breaker: Breakable,
 	schema: TreeStoredSchemaSubscription,
 	idCompressor: IIdCompressor,
+	shouldEncodeIncrementally: IncrementalEncodingPolicy,
 ) => IEditableForest;
 
 function toForestType(factory: ForestFactory): ForestType {
@@ -918,8 +930,14 @@ export function buildConfiguredForest(
 	factory: ForestType,
 	schema: TreeStoredSchemaSubscription,
 	idCompressor: IIdCompressor,
+	shouldEncodeIncrementally: IncrementalEncodingPolicy,
 ): IEditableForest {
-	return (factory as unknown as ForestFactory)(breaker, schema, idCompressor);
+	return (factory as unknown as ForestFactory)(
+		breaker,
+		schema,
+		idCompressor,
+		shouldEncodeIncrementally,
+	);
 }
 
 export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
@@ -929,12 +947,7 @@ export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	treeEncodeType: TreeCompressionStrategy.Compressed,
 	formatVersion: SharedTreeFormatVersion.v3,
 	disposeForksAfterTransaction: true,
-	shouldEncodeFieldIncrementally: (
-		nodeIdentifier: TreeNodeSchemaIdentifier,
-		fieldKey: FieldKey,
-	): boolean => {
-		return false;
-	},
+	shouldEncodeIncrementally: defaultIncrementalEncodingPolicy,
 };
 
 function exportSimpleFieldSchemaStored(schema: TreeFieldStoredSchema): SimpleFieldSchema {

package/src/shared-tree/tree.ts

@@ -11,7 +11,7 @@ import {
 	type TreeNode,
 	type TreeNodeApi,
 	type TreeView,
-	getOrCreateInnerNode,
+	getInnerNode,
 	treeNodeApi,
 	rollback,
 	type TransactionConstraint,
@@ -447,7 +447,7 @@ export function runTransaction<
 	} else {
 		const node = treeOrNode as TNode;
 		const t = transaction as (node: TNode) => TResult | typeof rollback;
-		const context = getOrCreateInnerNode(node).context;
+		const context = getInnerNode(node).context;
 		if (context.isHydrated() === false) {
 			throw new UsageError(
 				"Transactions cannot be run on Unhydrated nodes. Transactions apply to a TreeView and Unhydrated nodes are not part of a TreeView.",