@fluidframework/tree 2.1.1 → 2.2.1

package/src/feature-libraries/memoizedIdRangeAllocator.ts

@@ -15,8 +15,6 @@ import {
 
 /**
  * A unique ID allocator that returns the output ID for the same input ID.
- *
- * @internal
  */
 export interface MemoizedIdRangeAllocator {
 	/**
@@ -42,7 +40,6 @@ export interface MemoizedIdRangeAllocator {
 }
 
 /**
- * @internal
  */
 export interface IdRange {
 	readonly first: ChangesetLocalId;
@@ -50,7 +47,6 @@ export interface IdRange {
 }
 
 /**
- * @internal
  */
 export const MemoizedIdRangeAllocator = {
 	fromNextId(nextId: number = 0): MemoizedIdRangeAllocator {

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

@@ -45,7 +45,6 @@ export function getFirstFromCrossFieldMap<T>(
 }
 
 /**
- * @internal
  */
 export enum CrossFieldTarget {
 	Source,
@@ -55,7 +54,6 @@ export enum CrossFieldTarget {
 /**
  * Used by {@link FieldChangeHandler} implementations for exchanging information across other fields
  * while rebasing, composing, or inverting a change.
- * @internal
  */
 export interface CrossFieldManager<T = unknown> {
 	/**

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

@@ -293,7 +293,7 @@ function trackFieldDiscrepancies(
 ): FieldIncompatibility[] {
 	const differences: FieldIncompatibility[] = [];
 
-	// Only track the intersection of the two sets.
+	// Only track the symmetric differences of two sets.
 	const findSetDiscrepancies = (
 		a: TreeTypeSet,
 		b: TreeTypeSet,
@@ -390,6 +390,122 @@ function trackObjectNodeDiscrepancies(
 	return differences;
 }
 
+/**
+ * @remarks
+ *
+ * This function uses incompatibilities to determine if changes to a document schema are backward-compatible, i.e., it determines
+ * whether the `view` schema allows a superset of the documents that the `stored` schema allows.
+ * According to the policy of schema evolution, `isRepoSuperset` supports three types of changes:
+ * 1. Adding an optional field to an object node.
+ * 2. Expanding the set of allowed types for a field.
+ * 3. Relaxing a field kind to a more general field kind.
+ *
+ * Notes: We expect isRepoSuperset to return consistent results with allowsRepoSuperset. However, currently there are some scenarios
+ * where the inconsistency will occur:
+ *
+ * - Different Node Kinds: If a and b have different node kinds (e.g., a is an objectNodeSchema and b is a mapNodeSchema),
+ * `isRepoSuperset` will determine that a can never be the superset of b. In contrast, `allowsRepoSuperset` will continue
+ * validating internal fields.
+ */
+export function isRepoSuperset(view: TreeStoredSchema, stored: TreeStoredSchema): boolean {
+	const incompatibilities = getAllowedContentIncompatibilities(view, stored);
+
+	for (const incompatibility of incompatibilities) {
+		switch (incompatibility.mismatch) {
+			case "nodeKind": {
+				return false;
+			}
+			case "valueSchema":
+			case "allowedTypes":
+			case "fieldKind": {
+				if (!validateFieldIncompatibility(incompatibility)) {
+					return false;
+				}
+				break;
+			}
+			case "fields": {
+				if (
+					incompatibility.differences.some(
+						(difference) => !validateFieldIncompatibility(difference),
+					)
+				) {
+					return false;
+				}
+				break;
+			}
+			// No default
+		}
+	}
+	return true;
+}
+
+function validateFieldIncompatibility(incompatibility: FieldIncompatibility): boolean {
+	switch (incompatibility.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.
+			return incompatibility.stored.length === 0;
+		}
+		case "fieldKind": {
+			if (incompatibility.stored === undefined) {
+				// Add an optional field
+				if (incompatibility.view === "Optional") {
+					return true;
+				}
+			} else {
+				// Relax the field to make it more general
+				return compareFieldKind(incompatibility.stored, incompatibility.view);
+			}
+
+			break;
+		}
+		case "valueSchema": {
+			return false;
+		}
+		// No default
+	}
+	return false;
+}
+
+/**
+ * A mapping that defines the order of field kinds for comparison purposes.
+ * The numeric values indicate the hierarchy or "strength" of each field kind, where lower numbers are more restrictive.
+ * This is used to determine if one field kind can be considered a superset of another.
+ *
+ * - "Forbidden": The most restrictive, represented by 1. Indicates a forbidden field.
+ * - "Value": Represented by 2. Indicates a required field with a specific value.
+ * - "Optional": Represented by 3. Indicates an optional field.
+ *
+ * Note:
+ * - "Sequence": (Currently commented out) was intended to represent a sequence field kind with a value of 4.
+ * Relaxing non-sequence fields to sequences is not currently supported but may be considered in the future.
+ *
+ * TODO: We may need more coverage in realm to prove the correctness of the Forbidden -\> Value transaction
+ */
+const fieldKindOrder: { [key: string]: number } = {
+	"Forbidden": 1,
+	"Value": 2,
+	"Optional": 3,
+	// "Sequence": 4,  // Relaxing non-sequence fields to sequences is not currently supported, though we could consider doing so in the future.
+};
+
+function compareFieldKind(
+	aKind: FieldKindIdentifier | undefined,
+	bKind: FieldKindIdentifier | undefined,
+): boolean {
+	if (aKind === undefined || bKind === undefined) {
+		return false;
+	}
+
+	if (!(aKind in fieldKindOrder) || !(bKind in fieldKindOrder)) {
+		return false;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+	return fieldKindOrder[aKind]! <= fieldKindOrder[bKind]!;
+}
+
 function throwUnsupportedNodeType(type: string): never {
 	throw new TypeError(`Unsupported node stored schema type: ${type}`);
 }

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

@@ -184,17 +184,14 @@ export interface FieldEditor<TChangeset> {
 /**
  * The `index` represents the index of the child node in the input context.
  * The `index` should be `undefined` iff the child node does not exist in the input context (e.g., an inserted node).
- * @internal
  */
 export type ToDelta = (child: NodeId) => DeltaFieldMap;
 
 /**
- * @internal
  */
 export type NodeChangeInverter = (change: NodeId) => NodeId;
 
 /**
- * @internal
  */
 export enum NodeAttachState {
 	Attached,
@@ -202,7 +199,6 @@ export enum NodeAttachState {
 }
 
 /**
- * @internal
  */
 export type NodeChangeRebaser = (
 	change: NodeId | undefined,
@@ -215,7 +211,6 @@ export type NodeChangeRebaser = (
 ) => NodeId | undefined;
 
 /**
- * @internal
  */
 export type NodeChangeComposer = (
 	change1: NodeId | undefined,
@@ -223,14 +218,11 @@ export type NodeChangeComposer = (
 ) => NodeId;
 
 /**
- * @internal
  */
 export type NodeChangePruner = (change: NodeId) => NodeId | undefined;
 
 /**
  * A function that returns the set of removed roots that should be in memory for a given node changeset to be applied.
- *
- * @internal
  */
 export type RelevantRemovedRootsFromChild = (child: NodeId) => Iterable<DeltaDetachedNodeId>;
 

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

@@ -22,8 +22,7 @@ import type {
  *
  * These policies include the data encoding, change encoding, change rebase and change application.
  *
- * @sealed @internal
- * @privateRemarks
+ * @sealed * @privateRemarks
  * This being @sealed is for users of this package.
  * This package itself may provide implementations.
  * This pattern was picked instead of an interface since we do not have a convention for how to mark interfaces as only allowed to be implemented by the package declaring them,
@@ -48,7 +47,6 @@ export abstract class FlexFieldKind<
 /**
  * Policy from the app for interpreting the stored schema.
  * The app must ensure consistency for all users of the document.
- * @internal
  */
 export interface FullSchemaPolicy extends SchemaPolicy {
 	/**

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

@@ -13,7 +13,7 @@ import {
 	replaceAtomRevisions,
 } from "../../core/index.js";
 import { type IdAllocator, fail } from "../../util/index.js";
-
+import { assert } from "@fluidframework/core-utils/internal";
 import type { CrossFieldManager } from "./crossFieldQueries.js";
 import type {
 	FieldChangeHandler,
@@ -25,56 +25,17 @@ import type {
 } from "./fieldChangeHandler.js";
 import { FieldKindWithEditor } from "./fieldKindWithEditor.js";
 import { makeGenericChangeCodec } from "./genericFieldKindCodecs.js";
-import type { GenericChangeset } from "./genericFieldKindTypes.js";
+import { newGenericChangeset, type GenericChangeset } from "./genericFieldKindTypes.js";
 import type { NodeId } from "./modularChangeTypes.js";
+import { BTree } from "@tylerbu/sorted-btree-es6";
 
 /**
  * {@link FieldChangeHandler} implementation for {@link GenericChangeset}.
  */
 export const genericChangeHandler: FieldChangeHandler<GenericChangeset> = {
 	rebaser: {
-		compose: (
-			change1: GenericChangeset,
-			change2: GenericChangeset,
-			composeChildren: NodeChangeComposer,
-		): GenericChangeset => {
-			const composed: GenericChangeset = [];
-
-			let listIndex1 = 0;
-			let listIndex2 = 0;
-
-			while (listIndex1 < change1.length || listIndex2 < change2.length) {
-				const next1 = change1[listIndex1];
-				const next2 = change2[listIndex2];
-				const nodeIndex1 = next1?.index ?? Infinity;
-				const nodeIndex2 = next2?.index ?? Infinity;
-				if (nodeIndex1 < nodeIndex2) {
-					composed.push({
-						index: nodeIndex1,
-						nodeChange: composeChildren(next1.nodeChange, undefined),
-					});
-					listIndex1 += 1;
-				} else if (nodeIndex2 < nodeIndex1) {
-					composed.push({
-						index: nodeIndex2,
-						nodeChange: composeChildren(undefined, next2.nodeChange),
-					});
-					listIndex2 += 1;
-				} else {
-					// Both nodes are at the same position.
-					composed.push({
-						index: nodeIndex1,
-						nodeChange: composeChildren(next1.nodeChange, next2.nodeChange),
-					});
-					listIndex1 += 1;
-					listIndex2 += 1;
-				}
-			}
-			return composed;
-		},
-		invert: (change: GenericChangeset): GenericChangeset => {
-			return change;
-		},
+		compose,
+		invert: (change: GenericChangeset): GenericChangeset => change,
 		rebase: rebaseGenericChange,
 		prune: pruneGenericChange,
 		replaceRevisions,
@@ -82,13 +43,13 @@ export const genericChangeHandler: FieldChangeHandler<GenericChangeset> = {
 	codecsFactory: makeGenericChangeCodec,
 	editor: {
 		buildChildChange(index, change): GenericChangeset {
-			return [{ index, nodeChange: change }];
+			return newGenericChangeset([[index, change]]);
 		},
 	},
 	intoDelta: (change: GenericChangeset, deltaFromChild: ToDelta): DeltaFieldChanges => {
 		let nodeIndex = 0;
 		const markList: DeltaMark[] = [];
-		for (const { index, nodeChange } of change) {
+		for (const [index, nodeChange] of change.entries()) {
 			if (nodeIndex < index) {
 				const offset = index - nodeIndex;
 				markList.push({ count: offset });
@@ -102,12 +63,27 @@ export const genericChangeHandler: FieldChangeHandler<GenericChangeset> = {
 	relevantRemovedRoots,
 	isEmpty: (change: GenericChangeset): boolean => change.length === 0,
 	getNestedChanges,
-	createEmpty: (): GenericChangeset => [],
+	createEmpty: newGenericChangeset,
 	getCrossFieldKeys: (_change) => [],
 };
 
+function compose(
+	change1: GenericChangeset,
+	change2: GenericChangeset,
+	composeChildren: NodeChangeComposer,
+): GenericChangeset {
+	const composed = change1.clone();
+	for (const [index, id2] of change2.entries()) {
+		const id1 = composed.get(index);
+		const idComposed = id1 !== undefined ? composeChildren(id1, id2) : id2;
+		composed.set(index, idComposed);
+	}
+
+	return composed;
+}
+
 function getNestedChanges(change: GenericChangeset): [NodeId, number | undefined][] {
-	return change.map(({ index, nodeChange }) => [nodeChange, index]);
+	return change.toArray().map(([index, nodeChange]) => [nodeChange, index]);
 }
 
 function rebaseGenericChange(
@@ -115,40 +91,47 @@ function rebaseGenericChange(
 	over: GenericChangeset,
 	rebaseChild: NodeChangeRebaser,
 ): GenericChangeset {
-	const rebased: GenericChangeset = [];
-	let iChange = 0;
-	let iOver = 0;
-	while (iChange < change.length || iOver < over.length) {
-		const a = change[iChange];
-		const b = over[iOver];
-		const aIndex = a?.index ?? Infinity;
-		const bIndex = b?.index ?? Infinity;
-		let nodeChangeA: NodeId | undefined;
-		let nodeChangeB: NodeId | undefined;
+	const rebased: GenericChangeset = new BTree();
+	let nextIndex = 0;
+
+	// eslint-disable-next-line no-constant-condition
+	while (true) {
+		const newEntry = change.getPairOrNextHigher(nextIndex);
+		const baseEntry = over.getPairOrNextHigher(nextIndex);
+
+		if (baseEntry === undefined && newEntry === undefined) {
+			break;
+		}
+
+		const newIndex = newEntry?.[0] ?? Infinity;
+		const baseIndex = baseEntry?.[0] ?? Infinity;
+		let newNodeChange: NodeId | undefined;
+		let baseNodeChange: NodeId | undefined;
 		let index: number;
-		if (aIndex === bIndex) {
-			index = a.index;
-			nodeChangeA = a.nodeChange;
-			nodeChangeB = b.nodeChange;
-			iChange += 1;
-			iOver += 1;
-		} else if (aIndex < bIndex) {
-			index = a.index;
-			nodeChangeA = a.nodeChange;
-			iChange += 1;
+		if (newIndex === baseIndex) {
+			assert(
+				newEntry !== undefined && baseEntry !== undefined,
+				0xa0d /* Entries should be defined */,
+			);
+			index = newIndex;
+			newNodeChange = newEntry[1];
+			baseNodeChange = baseEntry[1];
+		} else if (newIndex < baseIndex) {
+			assert(newEntry !== undefined, 0xa0e /* Entry should be defined */);
+			index = newIndex;
+			newNodeChange = newEntry[1];
 		} else {
-			index = b.index;
-			nodeChangeB = b.nodeChange;
-			iOver += 1;
+			assert(baseEntry !== undefined, 0xa0f /* Entry should be defined */);
+			index = baseIndex;
+			baseNodeChange = baseEntry[1];
 		}
 
-		const nodeChange = rebaseChild(nodeChangeA, nodeChangeB);
+		const nodeChange = rebaseChild(newNodeChange, baseNodeChange);
 		if (nodeChange !== undefined) {
-			rebased.push({
-				index,
-				nodeChange,
-			});
+			rebased.set(index, nodeChange);
 		}
+
+		nextIndex = index + 1;
 	}
 
 	return rebased;
@@ -158,11 +141,11 @@ function pruneGenericChange(
 	changeset: GenericChangeset,
 	pruneChild: NodeChangePruner,
 ): GenericChangeset {
-	const pruned: GenericChangeset = [];
-	for (const change of changeset) {
-		const prunedNode = pruneChild(change.nodeChange);
+	const pruned: GenericChangeset = new BTree();
+	for (const [index, node] of changeset.entries()) {
+		const prunedNode = pruneChild(node);
 		if (prunedNode !== undefined) {
-			pruned.push({ ...change, nodeChange: prunedNode });
+			pruned.set(index, node);
 		}
 	}
 	return pruned;
@@ -173,10 +156,7 @@ function replaceRevisions(
 	oldRevisions: Set<RevisionTag | undefined>,
 	newRevision: RevisionTag | undefined,
 ): GenericChangeset {
-	return changeset.map((change) => ({
-		...change,
-		nodeChange: replaceAtomRevisions(change.nodeChange, oldRevisions, newRevision),
-	}));
+	return changeset.mapValues((node) => replaceAtomRevisions(node, oldRevisions, newRevision));
 }
 
 /**
@@ -204,9 +184,10 @@ export function convertGenericChange<TChange>(
 	genId: IdAllocator,
 	revisionMetadata: RevisionMetadataSource,
 ): TChange {
-	const perIndex: TChange[] = changeset.map(({ index, nodeChange }) =>
-		target.editor.buildChildChange(index, nodeChange),
-	);
+	const perIndex: TChange[] = [];
+	for (const [index, nodeChange] of changeset.entries()) {
+		perIndex.push(target.editor.buildChildChange(index, nodeChange));
+	}
 
 	if (perIndex.length === 0) {
 		return target.createEmpty();
@@ -232,15 +213,11 @@ const invalidCrossFieldManager: CrossFieldManager = {
 	moveKey: invalidFunc,
 };
 
-export function newGenericChangeset(): GenericChangeset {
-	return [];
-}
-
 function* relevantRemovedRoots(
 	change: GenericChangeset,
 	relevantRemovedRootsFromChild: RelevantRemovedRootsFromChild,
 ): Iterable<DeltaDetachedNodeId> {
-	for (const { nodeChange } of change) {
+	for (const nodeChange of change.values()) {
 		yield* relevantRemovedRootsFromChild(nodeChange);
 	}
 }

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

@@ -5,11 +5,8 @@
 
 import { type ICodecFamily, type IJsonCodec, makeCodecFamily } from "../../codec/index.js";
 import type { FieldChangeEncodingContext } from "./fieldChangeHandler.js";
-import {
-	type EncodedGenericChange,
-	EncodedGenericChangeset,
-} from "./genericFieldKindFormat.js";
-import type { GenericChange, GenericChangeset } from "./genericFieldKindTypes.js";
+import { EncodedGenericChangeset } from "./genericFieldKindFormat.js";
+import { newGenericChangeset, type GenericChangeset } from "./genericFieldKindTypes.js";
 import { EncodedNodeChangeset } from "./modularChangeFormat.js";
 
 export function makeGenericChangeCodec(): ICodecFamily<
@@ -30,21 +27,17 @@ function makeV1Codec(): IJsonCodec<
 			change: GenericChangeset,
 			context: FieldChangeEncodingContext,
 		): EncodedGenericChangeset => {
-			const encoded: EncodedGenericChangeset = change.map(({ index, nodeChange }) => [
-				index,
-				context.encodeNode(nodeChange),
-			]);
+			const encoded: EncodedGenericChangeset = change
+				.toArray()
+				.map(([index, nodeChange]) => [index, context.encodeNode(nodeChange)]);
 			return encoded;
 		},
 		decode: (
 			encoded: EncodedGenericChangeset,
 			context: FieldChangeEncodingContext,
 		): GenericChangeset => {
-			return encoded.map(
-				([index, nodeChange]: EncodedGenericChange): GenericChange => ({
-					index,
-					nodeChange: context.decodeNode(nodeChange),
-				}),
+			return newGenericChangeset(
+				encoded.map(([index, nodeChange]) => [index, context.decodeNode(nodeChange)]),
 			);
 		},
 		encodedSchema: EncodedGenericChangeset(EncodedNodeChangeset),

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

@@ -3,23 +3,14 @@
  * Licensed under the MIT License.
  */
 
+import { BTree } from "@tylerbu/sorted-btree-es6";
 import type { NodeId } from "./modularChangeTypes.js";
 
-/**
- * A field-kind-agnostic change to a single node within a field.
- */
-export interface GenericChange {
-	/**
-	 * Index within the field of the changed node.
-	 */
-	index: number;
-	/**
-	 * Change to the node.
-	 */
-	nodeChange: NodeId;
-}
-
 /**
  * A field-agnostic set of changes to the elements of a field.
  */
-export type GenericChangeset = GenericChange[];
+export type GenericChangeset = BTree<number, NodeId>;
+
+export function newGenericChangeset(nodes: [number, NodeId][] = []): GenericChangeset {
+	return new BTree(nodes);
+}

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

@@ -57,7 +57,7 @@ export {
 	genericChangeHandler,
 	genericFieldKind,
 } from "./genericFieldKind.js";
-export type { GenericChange, GenericChangeset } from "./genericFieldKindTypes.js";
+export type { GenericChangeset } from "./genericFieldKindTypes.js";
 export {
 	ModularChangeFamily,
 	ModularEditBuilder,
@@ -74,4 +74,4 @@ export type {
 	FieldKindConfiguration,
 	FieldKindConfigurationEntry,
 } from "./fieldKindConfiguration.js";
-export { getAllowedContentIncompatibilities } from "./discrepancies.js";
+export { getAllowedContentIncompatibilities, isRepoSuperset } from "./discrepancies.js";