@fluidframework/tree 2.10.0 → 2.12.0

package/src/feature-libraries/modular-schema/discrepancies.ts

@@ -6,6 +6,7 @@
 import { assert } from "@fluidframework/core-utils/internal";
 
 import {
+	type FieldKey,
 	type FieldKindIdentifier,
 	LeafNodeStoredSchema,
 	MapNodeStoredSchema,
@@ -25,6 +26,7 @@ import { brand } from "../../util/index.js";
 // Rather than both existing, one of which just returns boolean and the other which returns additional details, a simple comparison which returns everything needed should be used.
 
 /**
+ * Discriminated union (keyed on `mismatch`) of discrepancies between a view and stored schema.
  * @remarks
  *
  * 1. FieldDiscrepancy
@@ -60,47 +62,73 @@ export type Discrepancy = FieldDiscrepancy | NodeDiscrepancy;
 
 export type NodeDiscrepancy = NodeKindDiscrepancy | NodeFieldsDiscrepancy;
 
+/**
+ * A discrepancy in the declaration of a field.
+ */
 export type FieldDiscrepancy =
 	| AllowedTypeDiscrepancy
 	| FieldKindDiscrepancy
 	| ValueSchemaDiscrepancy;
 
-export interface AllowedTypeDiscrepancy {
-	identifier: string | undefined; // undefined indicates root field schema
+/**
+ * Information about where a field discrepancy is located within a collection of schema.
+ */
+export interface FieldDiscrepancyLocation {
+	/**
+	 * The {@link TreeNodeSchemaIdentifier} that contains the discrepancy.
+	 *
+	 * Undefined iff the discrepancy is part of the root field schema.
+	 */
+	identifier: TreeNodeSchemaIdentifier | undefined;
+	/**
+	 * The {@link FieldKey} for the field that contains the discrepancy.
+	 * Undefined when:
+	 * - the discrepancy is part of the root field schema
+	 * - the discrepancy is for 'all fields' of a map node
+	 */
+	fieldKey: FieldKey | undefined;
+}
+
+/**
+ * A discrepancy in the allowed types of a field.
+ *
+ * @remarks
+ * This reports the symmetric difference of allowed types in view/stored to enable more efficient checks for compatibility
+ */
+export interface AllowedTypeDiscrepancy extends FieldDiscrepancyLocation {
 	mismatch: "allowedTypes";
 	/**
-	 * List of allowed type identifiers in viewed schema
+	 * List of allowed type identifiers in viewed schema which are not allowed in stored schema
 	 */
-	view: string[];
+	view: TreeNodeSchemaIdentifier[];
 	/**
-	 * List of allowed type identifiers in stored schema
+	 * List of allowed type identifiers in stored schema which are not allowed in view schema
 	 */
-	stored: string[];
+	stored: TreeNodeSchemaIdentifier[];
 }
 
-export interface FieldKindDiscrepancy {
-	identifier: string | undefined; // undefined indicates root field schema
+export interface FieldKindDiscrepancy extends FieldDiscrepancyLocation {
 	mismatch: "fieldKind";
 	view: FieldKindIdentifier;
 	stored: FieldKindIdentifier;
 }
 
 export interface ValueSchemaDiscrepancy {
-	identifier: string;
+	identifier: TreeNodeSchemaIdentifier;
 	mismatch: "valueSchema";
 	view: ValueSchema | undefined;
 	stored: ValueSchema | undefined;
 }
 
 export interface NodeKindDiscrepancy {
-	identifier: string;
+	identifier: TreeNodeSchemaIdentifier;
 	mismatch: "nodeKind";
 	view: SchemaFactoryNodeKind | undefined;
 	stored: SchemaFactoryNodeKind | undefined;
 }
 
 export interface NodeFieldsDiscrepancy {
-	identifier: string;
+	identifier: TreeNodeSchemaIdentifier;
 	mismatch: "fields";
 	differences: FieldDiscrepancy[];
 }
@@ -121,26 +149,25 @@ function getNodeSchemaType(nodeSchema: TreeNodeStoredSchema): SchemaFactoryNodeK
 /**
  * Finds and reports discrepancies between a view schema and a stored schema.
  *
- * The workflow for finding schema incompatibilities:
- * 1. Compare the two root schemas to identify any `FieldDiscrepancy`.
- *
- * 2. For each node schema in the `view`:
- * - Verify if the node schema exists in the stored. If it does, ensure that the `SchemaFactoryNodeKind` are
- * consistent. Otherwise this difference is treated as `NodeKindDiscrepancy`
- * - If a node schema with the same identifier exists in both view and stored, and their `SchemaFactoryNodeKind`
- * are consistent, perform a exhaustive validation to identify all `FieldDiscrepancy`.
- *
- * 3. For each node schema in the stored, verify if it exists in the view. The overlapping parts were already
- * addressed in the previous step.
+ * See documentation on {@link Discrepancy} for details of possible discrepancies.
+ * @remarks
+ * This function does not attempt to distinguish between equivalent representations of a node/field involving extraneous never trees.
+ * For example, a Forbidden field with allowed type set `[]` is equivalent to an optional field with allowed type set `[]`,
+ * as well as an optional field with an allowed type set containing only unconstructable types.
  *
- * @returns the discrepancies between two TreeStoredSchema objects
+ * It is up to the caller to determine whether such discrepancies matter.
  */
 export function* getAllowedContentDiscrepancies(
 	view: TreeStoredSchema,
 	stored: TreeStoredSchema,
 ): Iterable<Discrepancy> {
 	// check root schema discrepancies
-	yield* getFieldDiscrepancies(view.rootFieldSchema, stored.rootFieldSchema);
+	yield* getFieldDiscrepancies(
+		view.rootFieldSchema,
+		stored.rootFieldSchema,
+		undefined,
+		undefined,
+	);
 
 	for (const result of compareMaps(view.nodeSchema, stored.nodeSchema)) {
 		switch (result.type) {
@@ -195,6 +222,7 @@ function* getNodeDiscrepancies(
 		case "object": {
 			const differences = Array.from(
 				trackObjectNodeDiscrepancies(
+					identifier,
 					view as ObjectNodeStoredSchema,
 					stored as ObjectNodeStoredSchema,
 				),
@@ -213,6 +241,7 @@ function* getNodeDiscrepancies(
 				(view as MapNodeStoredSchema).mapFields,
 				(stored as MapNodeStoredSchema).mapFields,
 				identifier,
+				undefined,
 			);
 			break;
 		case "leaf": {
@@ -241,7 +270,8 @@ function* getNodeDiscrepancies(
 function* getFieldDiscrepancies(
 	view: TreeFieldStoredSchema,
 	stored: TreeFieldStoredSchema,
-	keyOrRoot?: string,
+	identifier: TreeNodeSchemaIdentifier | undefined,
+	fieldKey: FieldKey | undefined,
 ): Iterable<FieldDiscrepancy> {
 	// Only track the symmetric differences of two sets.
 	const findSetDiscrepancies = (
@@ -256,7 +286,8 @@ function* getFieldDiscrepancies(
 	const [viewExtra, storedExtra] = findSetDiscrepancies(view.types, stored.types);
 	if (viewExtra.length > 0 || storedExtra.length > 0) {
 		yield {
-			identifier: keyOrRoot,
+			identifier,
+			fieldKey,
 			mismatch: "allowedTypes",
 			view: viewExtra,
 			stored: storedExtra,
@@ -265,7 +296,8 @@ function* getFieldDiscrepancies(
 
 	if (view.kind !== stored.kind) {
 		yield {
-			identifier: keyOrRoot,
+			identifier,
+			fieldKey,
 			mismatch: "fieldKind",
 			view: view.kind,
 			stored: stored.kind,
@@ -274,6 +306,7 @@ function* getFieldDiscrepancies(
 }
 
 function* trackObjectNodeDiscrepancies(
+	identifier: TreeNodeSchemaIdentifier,
 	view: ObjectNodeStoredSchema,
 	stored: ObjectNodeStoredSchema,
 ): Iterable<FieldDiscrepancy> {
@@ -298,7 +331,8 @@ function* trackObjectNodeDiscrepancies(
 					break;
 				}
 				yield {
-					identifier: fieldKey,
+					identifier,
+					fieldKey,
 					mismatch: "fieldKind",
 					view: result.value.kind,
 					stored: storedEmptyFieldSchema.kind,
@@ -312,7 +346,8 @@ function* trackObjectNodeDiscrepancies(
 					break;
 				}
 				yield {
-					identifier: fieldKey,
+					identifier,
+					fieldKey,
 					mismatch: "fieldKind",
 					view: storedEmptyFieldSchema.kind,
 					stored: result.value.kind,
@@ -320,12 +355,11 @@ function* trackObjectNodeDiscrepancies(
 				break;
 			}
 			case "both": {
-				yield* getFieldDiscrepancies(result.valueA, result.valueB, fieldKey);
+				yield* getFieldDiscrepancies(result.valueA, result.valueB, identifier, fieldKey);
 				break;
 			}
-			default: {
+			default:
 				break;
-			}
 		}
 	}
 }
@@ -428,13 +462,13 @@ function isFieldDiscrepancyCompatible(discrepancy: FieldDiscrepancy): boolean {
  *
  * The linear extension is represented as a lookup from each poset element to its index in the linear extension.
  */
-type LinearExtension<T> = Map<T, number>;
+export type LinearExtension<T> = Map<T, number>;
 
 /**
  * A realizer for a partially-ordered set. See:
  * https://en.wikipedia.org/wiki/Order_dimension
  */
-type Realizer<T> = LinearExtension<T>[];
+export type Realizer<T> = LinearExtension<T>[];
 
 /**
  * @privateRemarks
@@ -468,7 +502,7 @@ const FieldKindIdentifiers = {
  * identifier
  * ```
  */
-const fieldRealizer: Realizer<FieldKindIdentifier> = [
+export const fieldRealizer: Realizer<FieldKindIdentifier> = [
 	[
 		FieldKindIdentifiers.forbidden,
 		FieldKindIdentifiers.identifier,
@@ -485,7 +519,7 @@ const fieldRealizer: Realizer<FieldKindIdentifier> = [
 	],
 ].map((extension) => new Map(extension.map((identifier, index) => [identifier, index])));
 
-const PosetComparisonResult = {
+export const PosetComparisonResult = {
 	Less: "<",
 	Greater: ">",
 	Equal: "=",
@@ -494,7 +528,11 @@ const PosetComparisonResult = {
 type PosetComparisonResult =
 	(typeof PosetComparisonResult)[keyof typeof PosetComparisonResult];
 
-function comparePosetElements<T>(a: T, b: T, realizer: Realizer<T>): PosetComparisonResult {
+export function comparePosetElements<T>(
+	a: T,
+	b: T,
+	realizer: Realizer<T>,
+): PosetComparisonResult {
 	let hasLessThanResult = false;
 	let hasGreaterThanResult = false;
 	for (const extension of realizer) {
@@ -517,7 +555,7 @@ function comparePosetElements<T>(a: T, b: T, realizer: Realizer<T>): PosetCompar
 			: PosetComparisonResult.Equal;
 }
 
-function posetLte<T>(a: T, b: T, realizer: Realizer<T>): boolean {
+export function posetLte<T>(a: T, b: T, realizer: Realizer<T>): boolean {
 	const comparison = comparePosetElements(a, b, realizer);
 	return (
 		comparison === PosetComparisonResult.Less || comparison === PosetComparisonResult.Equal

package/src/feature-libraries/modular-schema/index.ts

@@ -77,4 +77,17 @@ export type {
 export {
 	getAllowedContentDiscrepancies,
 	isRepoSuperset,
+	type AllowedTypeDiscrepancy,
+	type FieldKindDiscrepancy,
+	type ValueSchemaDiscrepancy,
+	type FieldDiscrepancy,
+	type NodeDiscrepancy,
+	type NodeKindDiscrepancy,
+	type NodeFieldsDiscrepancy,
+	type LinearExtension,
+	type Realizer,
+	fieldRealizer,
+	PosetComparisonResult,
+	comparePosetElements,
+	posetLte,
 } from "./discrepancies.js";

package/src/feature-libraries/modular-schema/isNeverTree.ts

@@ -19,9 +19,7 @@ import { fail } from "../../util/index.js";
 import type { FullSchemaPolicy } from "./fieldKind.js";
 
 /**
- * @internal
  */
-
 export function isNeverField(
 	policy: FullSchemaPolicy,
 	originalData: TreeStoredSchema,

package/src/feature-libraries/object-forest/objectForest.ts

@@ -4,10 +4,13 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+import { createEmitter } from "@fluid-internal/client-utils";
+import type { Listenable } from "@fluidframework/core-interfaces";
 
 import {
 	type Anchor,
 	AnchorSet,
+	type AnnouncedVisitor,
 	type CursorLocationType,
 	type DeltaVisitor,
 	type DetachedField,
@@ -31,9 +34,9 @@ import {
 	type UpPath,
 	type Value,
 	aboveRootPlaceholder,
+	combineVisitors,
 	deepCopyMapTree,
 } from "../../core/index.js";
-import { createEmitter, type Listenable } from "../../events/index.js";
 import {
 	assertNonNegativeSafeInteger,
 	assertValidIndex,
@@ -72,6 +75,7 @@ export class ObjectForest implements IEditableForest {
 
 	// All cursors that are in the "Current" state. Must be empty when editing.
 	public readonly currentCursors: Set<Cursor> = new Set();
+	private readonly deltaVisitors: Set<() => AnnouncedVisitor> = new Set();
 
 	readonly #events = createEmitter<ForestEvents>();
 	public readonly events: Listenable<ForestEvents> = this.#events;
@@ -254,9 +258,23 @@ export class ObjectForest implements IEditableForest {
 			}
 		}
 
-		const visitor = new Visitor(this);
-		this.activeVisitor = visitor;
-		return visitor;
+		const forestVisitor = new Visitor(this);
+		const announcedVisitors: AnnouncedVisitor[] = [];
+		this.deltaVisitors.forEach((getVisitor) => announcedVisitors.push(getVisitor()));
+		const combinedVisitor = combineVisitors(
+			[forestVisitor, ...announcedVisitors],
+			announcedVisitors,
+		);
+		this.activeVisitor = combinedVisitor;
+		return combinedVisitor;
+	}
+
+	public registerAnnouncedVisitor(visitor: () => AnnouncedVisitor): void {
+		this.deltaVisitors.add(visitor);
+	}
+
+	public deregisterAnnouncedVisitor(visitor: () => AnnouncedVisitor): void {
+		this.deltaVisitors.delete(visitor);
 	}
 
 	private nextRange = 0;

package/src/feature-libraries/sequence-field/invert.ts

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase, oob } from "@fluidframework/core-utils/internal";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 
 import type { RevisionTag } from "../../core/index.js";
-import { type IdAllocator, type Mutable, fail } from "../../util/index.js";
+import { type IdAllocator, type Mutable, fail, hasSingle } from "../../util/index.js";
 import {
 	type CrossFieldManager,
 	CrossFieldTarget,
@@ -257,11 +257,11 @@ function invertMark(
 			}
 
 			assert(
-				detachInverses.length === 1,
+				hasSingle(detachInverses),
 				0x80d /* Only expected MoveIn marks to be split when inverting */,
 			);
 
-			let detachInverse = detachInverses[0] ?? oob();
+			let detachInverse = detachInverses[0];
 			assert(isAttach(detachInverse), 0x80e /* Inverse of a detach should be an attach */);
 
 			const inverses: Mark[] = [];

package/src/feature-libraries/sequence-field/sequenceFieldToDelta.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase, oob } from "@fluidframework/core-utils/internal";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 
 import {
 	type DeltaDetachedNodeChanges,
@@ -12,7 +12,7 @@ import {
 	type DeltaMark,
 	areEqualChangeAtomIds,
 } from "../../core/index.js";
-import type { Mutable } from "../../util/index.js";
+import { getLast, hasSome, type Mutable } from "../../util/index.js";
 import { nodeIdFromChangeAtom } from "../deltaUtils.js";
 
 import { isMoveIn, isMoveOut } from "./moveEffectTable.js";
@@ -176,8 +176,8 @@ export function sequenceFieldToDelta(
 		}
 	}
 	// Remove trailing no-op marks
-	while (local.length > 0) {
-		const lastMark = local[local.length - 1] ?? oob();
+	while (hasSome(local)) {
+		const lastMark = getLast(local);
 		if (
 			lastMark.attach !== undefined ||
 			lastMark.detach !== undefined ||

package/src/feature-libraries/sequence-field/types.ts

@@ -25,7 +25,6 @@ export interface HasMoveId {
 }
 
 /**
- * @internal
  */
 export interface CellId extends ChangeAtomId {}
 

package/src/index.ts

@@ -4,51 +4,35 @@
  */
 
 export {
-	EmptyKey,
-	type FieldKey,
-	type TreeValue,
-	type FieldMapObject,
-	type NodeData,
-	type GenericTreeNode,
-	type JsonableTree,
-	type GenericFieldsNode,
-	type TreeNodeSchemaIdentifier,
-	type TreeFieldStoredSchema,
 	ValueSchema,
-	TreeNodeStoredSchema,
-	type FieldKindIdentifier,
-	type TreeTypeSet,
-	type TreeStoredSchema,
 	type Revertible,
 	CommitKind,
 	RevertibleStatus,
 	type CommitMetadata,
-	type StoredSchemaCollection,
-	type ErasedTreeNodeSchemaDataFormat,
-	ObjectNodeStoredSchema,
-	MapNodeStoredSchema,
-	LeafNodeStoredSchema,
 	type RevertibleFactory,
+	type RevertibleAlphaFactory,
+	type RevertibleAlpha,
 } from "./core/index.js";
-export { type Brand } from "./util/index.js";
 
-export {
-	type Listeners,
-	type IsListener,
-	type Listenable,
-	type Off,
-} from "./events/index.js";
+export type {
+	Listeners,
+	IsListener,
+	Listenable,
+	Off,
+} from "@fluidframework/core-interfaces";
 
 export {
 	TreeStatus,
 	TreeCompressionStrategy,
+	type TreeIndex,
+	type TreeIndexKey,
+	type TreeIndexNodes,
 } from "./feature-libraries/index.js";
 
 export {
-	type ISharedTree,
+	type ITreeInternal,
 	type SharedTreeOptions,
 	ForestType,
-	type SharedTreeContentSnapshot,
 	type SharedTreeFormatOptions,
 	SharedTreeFormatVersion,
 	Tree,
@@ -126,6 +110,11 @@ export {
 	// Recursive Schema APIs
 	type ValidateRecursiveSchema,
 	type FixRecursiveArraySchema,
+	// Index APIs
+	type SimpleTreeIndex,
+	type IdentifierIndex,
+	createSimpleTreeIndex,
+	createIdentifierIndex,
 	// experimental @alpha APIs:
 	adaptEnum,
 	enumFromStrings,
@@ -180,11 +169,6 @@ export {
 	type SimpleObjectNodeSchema,
 	normalizeAllowedTypes,
 	getSimpleSchema,
-	numberSchema,
-	stringSchema,
-	booleanSchema,
-	handleSchema,
-	nullSchema,
 	type ReadonlyArrayNode,
 	type InsertableTreeNodeFromAllowedTypes,
 	type Input,
@@ -207,8 +191,6 @@ export { noopValidator } from "./codec/index.js";
 export { typeboxValidator } from "./external-utilities/index.js";
 
 export {
-	type Covariant,
-	BrandedType,
 	type RestrictiveReadonlyRecord,
 	type RestrictiveStringRecord,
 	type MakeNominal,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.10.0";
+export const pkgVersion = "2.12.0";

package/src/shared-tree/index.ts

@@ -16,15 +16,14 @@ export {
 	buildConfiguredForest,
 	defaultSharedTreeOptions,
 	type ForestOptions,
+	type ITreeInternal,
 } from "./sharedTree.js";
 
 export {
 	createTreeCheckout,
 	TreeCheckout,
 	type ITreeCheckout,
-	runSynchronous,
 	type CheckoutEvents,
-	type ITransaction,
 	type ITreeCheckoutFork,
 	type BranchableTree,
 	type TreeBranchFork,

package/src/shared-tree/schematizeTree.ts

@@ -7,7 +7,6 @@ import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 
 import {
 	AllowedUpdateType,
-	Compatibility,
 	CursorLocationType,
 	type ITreeCursorSynchronous,
 	type TreeStoredSchema,
@@ -24,7 +23,7 @@ import {
 import { fail, isReadonlyArray } from "../util/index.js";
 
 import type { ITreeCheckout } from "./treeCheckout.js";
-import type { ViewSchema } from "../simple-tree/index.js";
+import { toStoredSchema, type ViewSchema } from "../simple-tree/index.js";
 
 /**
  * Modify `storedSchema` and invoke `setInitialTree` when it's time to set the tree content.
@@ -120,10 +119,7 @@ export function evaluateUpdate(
 ): UpdateType {
 	const compatibility = viewSchema.checkCompatibility(checkout.storedSchema);
 
-	if (
-		compatibility.read === Compatibility.Compatible &&
-		compatibility.write === Compatibility.Compatible
-	) {
+	if (compatibility.canUpgrade && compatibility.canView) {
 		// Compatible as is
 		return UpdateType.None;
 	}
@@ -133,13 +129,13 @@ export function evaluateUpdate(
 		return UpdateType.Initialize;
 	}
 
-	if (compatibility.read !== Compatibility.Compatible) {
+	if (!compatibility.canUpgrade) {
 		// Existing stored schema permits trees which are incompatible with the view schema, so schema can not be updated
 		return UpdateType.Incompatible;
 	}
 
-	assert(compatibility.write === Compatibility.Incompatible, 0x8bd /* unexpected case */);
-	assert(compatibility.read === Compatibility.Compatible, 0x8be /* unexpected case */);
+	assert(!compatibility.canView, 0x8bd /* unexpected case */);
+	assert(compatibility.canUpgrade, 0x8be /* unexpected case */);
 
 	// eslint-disable-next-line no-bitwise
 	return allowedSchemaModifications & AllowedUpdateType.SchemaCompatible
@@ -244,7 +240,7 @@ export function ensureSchema(
 			return false;
 		}
 		case UpdateType.SchemaCompatible: {
-			checkout.updateSchema(viewSchema.schema);
+			checkout.updateSchema(toStoredSchema(viewSchema.schema));
 			return true;
 		}
 		case UpdateType.Initialize: {