@fluidframework/tree 2.81.0-374083 → 2.81.1

package/src/feature-libraries/optional-field/optionalFieldChangeTypes.ts

@@ -6,19 +6,48 @@
 import type { ChangeAtomId } from "../../core/index.js";
 import type { NodeId } from "../modular-schema/index.js";
 
+/**
+ * Uniquely identifies a register within the scope of this changeset.
+ * The sentinel value "self" is used for the active register, which is a universally shared register
+ * (as in, any changeset referring to "self" refers to the register containing the active value of the field).
+ *
+ * See the model description in {@link OptionalChangeset} for more details.
+ */
+export type RegisterId = ChangeAtomId | "self";
+
+export type Move = readonly [src: ChangeAtomId, dst: ChangeAtomId];
+
+export type ChildChange = readonly [register: RegisterId, childChange: NodeId];
+
 /**
  * Changes to an optional field.
  *
- * The model used is that optional field consists of a single register.
- * In a given change input or output context, this register may hold 0 or 1 nodes.
+ * The model used is that optional field consists of a collection of "registers" with one designated as the "active" register.
+ * In a given change input or output context, registers may hold 0 or 1 nodes.
+ * Each register is identified using a {@link RegisterId}.
+ * The active register holds the current value of the field, and other registers hold detached roots.
  */
 export interface OptionalChangeset {
+	/**
+	 * Each entry signifies the intent to move a node from `src` to `dst`.
+	 * Moves to or from the "self" register are represented in {@link valueReplace}.
+	 *
+	 * These entries should not be interpreted as "applied one after the other", but rather as "applied simultaneously".
+	 * As such, changesets should not contain duplicated src or dst entries.
+	 */
+	readonly moves: readonly Move[];
+
+	/**
+	 * Nested changes to nodes that occupy registers.
+	 *
+	 * Nodes are identified by the register they occupy in the *input* context of the changeset.
+	 */
+	readonly childChanges: readonly ChildChange[];
+
 	/**
 	 * An optional description of how to replace the current value of the field.
 	 */
 	readonly valueReplace?: Replace;
-	readonly nodeDetach?: ChangeAtomId;
-	readonly childChange?: NodeId;
 }
 
 export interface Replace {
@@ -28,28 +57,13 @@ export interface Replace {
 	readonly isEmpty: boolean;
 
 	/**
-	 * An ID to associate with the node (if any) which is detached by this edit.
-	 *
-	 * When the field is empty in the input context, this ID is dormant in the sense that it would not be used if the changeset were applied as is.
-	 * However, it can become active if the changeset is rebased over a change that attaches a node in the field.
+	 * The ID for the node to put in this field, or undefined if the field should be emptied.
+	 * Will be "self" when the intention is to keep the current node in this field.
 	 */
-	readonly dst: ChangeAtomId;
+	readonly src?: RegisterId;
 
 	/**
-	 * The ID for the node to attach in this field, or undefined if no node should be attached.
-	 *
-	 * Note that this ID may refer to the node detached by this changeset:
-	 * The node in the field is detached and associated with ID `dst`,
-	 * then that node is renamed from `dst` to `src` (at the ModularChangeset level),
-	 * then that node is attached back into the field.
-	 * When this is the case, we say that the node is being pinned in the field.
-	 * While a pin has no effect on the document state if applied as-is, its merge semantics are different from an empty changeset.
-	 * This is because rebasing a pin over a change that detaches the node from the field will result in a changeset that re-attaches the node to the field.
-	 * In other words, a pin guarantees that the node will be in the field after the changeset is rebased and applied, whereas an empty changeset does not.
-	 *
-	 * `src` must be structurally different from `dst` even when the changeset is a pin.
-	 * An optional field changeset that aims to attach a node must be able to affect two nodes,
-	 * so unless we want to mint new IDs during rebasing, such a changeset must have two different IDs.
+	 * An ID to associate with the node (if any) which is detached by this edit.
 	 */
-	readonly src?: ChangeAtomId;
+	readonly dst: ChangeAtomId;
 }

package/src/feature-libraries/optional-field/optionalFieldCodecV2.ts

@@ -6,12 +6,11 @@
 import type { TAnySchema } from "@sinclair/typebox";
 
 import type { IJsonCodec } from "../../codec/index.js";
-import {
-	areEqualChangeAtomIdOpts,
-	type ChangeAtomId,
-	type ChangeEncodingContext,
-	type EncodedRevisionTag,
-	type RevisionTag,
+import type {
+	ChangeAtomId,
+	ChangeEncodingContext,
+	EncodedRevisionTag,
+	RevisionTag,
 } from "../../core/index.js";
 import type { Mutable } from "../../util/index.js";
 import { makeChangeAtomIdCodec } from "../changeAtomIdCodec.js";
@@ -22,10 +21,7 @@ import {
 } from "../modular-schema/index.js";
 
 import { EncodedOptionalChangeset, EncodedRegisterId } from "./optionalFieldChangeFormatV2.js";
-import type { OptionalChangeset, Replace } from "./optionalFieldChangeTypes.js";
-import { assert } from "@fluidframework/core-utils/internal";
-
-type RegisterId = ChangeAtomId | "self";
+import type { OptionalChangeset, RegisterId, Replace } from "./optionalFieldChangeTypes.js";
 
 function makeRegisterIdCodec(
 	changeAtomIdCodec: IJsonCodec<
@@ -70,62 +66,33 @@ export function makeOptionalFieldCodec(
 
 	return {
 		encode: (change: OptionalChangeset, context: FieldChangeEncodingContext) => {
-			assert(
-				change.nodeDetach === undefined ||
-					areEqualChangeAtomIdOpts(change.valueReplace?.src, change.nodeDetach),
-				"This format only supports node detach when it represents a pin",
-			);
-
 			const encoded: EncodedOptionalChangeset<TAnySchema> = {};
 
+			if (change.moves.length > 0) {
+				encoded.m = change.moves.map(([src, dst]) => [
+					changeAtomIdCodec.encode(src, context.baseContext),
+					changeAtomIdCodec.encode(dst, context.baseContext),
+				]);
+			}
+
 			if (change.valueReplace !== undefined) {
 				encoded.r = {
 					e: change.valueReplace.isEmpty,
 					d: changeAtomIdCodec.encode(change.valueReplace.dst, context.baseContext),
 				};
 				if (change.valueReplace.src !== undefined) {
-					const srcRegister =
-						change.nodeDetach === undefined ? change.valueReplace.src : "self";
-
-					encoded.r.s = registerIdCodec.encode(srcRegister, context.baseContext);
+					encoded.r.s = registerIdCodec.encode(change.valueReplace.src, context.baseContext);
 				}
 			}
 
-			const encodedChildChanges: [EncodedRegisterId, EncodedNodeChangeset][] = [];
-
-			if (change.childChange !== undefined) {
-				encodedChildChanges.push([null, context.encodeNode(change.childChange)]);
-			}
-
-			for (const [detachId, nodeId] of context.rootNodeChanges.entries()) {
-				encodedChildChanges.push([
-					changeAtomIdCodec.encode(
-						{ revision: detachId[0], localId: detachId[1] },
-						context.baseContext,
-					),
-					context.encodeNode(nodeId),
-				]);
-			}
-
-			if (encodedChildChanges.length > 0) {
-				encoded.c = encodedChildChanges;
-			}
-
-			const encodedMoves: [EncodedChangeAtomId, EncodedChangeAtomId][] = [];
-			for (const {
-				start: oldId,
-				value: newId,
-				length: count,
-			} of context.rootRenames.entries()) {
-				assert(count === 1, "Unexpected range rename in optional field");
-				encodedMoves.push([
-					changeAtomIdCodec.encode(oldId, context.baseContext),
-					changeAtomIdCodec.encode(newId, context.baseContext),
-				]);
-			}
-
-			if (encodedMoves.length > 0) {
-				encoded.m = encodedMoves;
+			if (change.childChanges.length > 0) {
+				encoded.c = [];
+				for (const [id, childChange] of change.childChanges) {
+					encoded.c.push([
+						registerIdCodec.encode(id, context.baseContext),
+						context.encodeNode(childChange),
+					]);
+				}
 			}
 
 			return encoded;
@@ -135,7 +102,18 @@ export function makeOptionalFieldCodec(
 			encoded: EncodedOptionalChangeset<TAnySchema>,
 			context: FieldChangeEncodingContext,
 		) => {
-			const decoded: Mutable<OptionalChangeset> = {};
+			const decoded: Mutable<OptionalChangeset> = {
+				moves:
+					encoded.m?.map(([encodedSrc, encodedDst]) => [
+						changeAtomIdCodec.decode(encodedSrc, context.baseContext),
+						changeAtomIdCodec.decode(encodedDst, context.baseContext),
+					]) ?? [],
+				childChanges:
+					encoded.c?.map(([id, encodedChange]) => [
+						registerIdCodec.decode(id, context.baseContext),
+						context.decodeNode(encodedChange),
+					]) ?? [],
+			};
 
 			if (encoded.r !== undefined) {
 				const replace: Mutable<Replace> = {
@@ -143,42 +121,10 @@ export function makeOptionalFieldCodec(
 					dst: changeAtomIdCodec.decode(encoded.r.d, context.baseContext),
 				};
 				if (encoded.r.s !== undefined) {
-					const register = registerIdCodec.decode(encoded.r.s, context.baseContext);
-					if (register === "self") {
-						// Note that this is safe as long as we assume that this change will not be rebased
-						// over a move to a sequence field.
-						// The ID of an attach and accompanying detach/rename is arbitrary, except in sequence field where
-						// the ID of the detach becomes a cell ID which may be referenced by other changes.
-						replace.src = context.generateId();
-						decoded.nodeDetach = replace.src;
-					} else {
-						replace.src = register;
-					}
+					replace.src = registerIdCodec.decode(encoded.r.s, context.baseContext);
 				}
 				decoded.valueReplace = replace;
 			}
-
-			if (encoded.c !== undefined) {
-				for (const [encodedDetachId, nodeChange] of encoded.c) {
-					if (encodedDetachId === null) {
-						decoded.childChange = context.decodeNode(nodeChange);
-					} else {
-						context.decodeRootNodeChange(
-							changeAtomIdCodec.decode(encodedDetachId, context.baseContext),
-							nodeChange,
-						);
-					}
-				}
-			}
-
-			for (const [encodedOldId, encodedNewId] of encoded.m ?? []) {
-				context.decodeRootRename(
-					changeAtomIdCodec.decode(encodedOldId, context.baseContext),
-					changeAtomIdCodec.decode(encodedNewId, context.baseContext),
-					1,
-				);
-			}
-
 			return decoded;
 		},
 		encodedSchema: EncodedOptionalChangeset(EncodedNodeChangeset),

package/src/feature-libraries/optional-field/optionalFieldCodecs.ts

@@ -13,7 +13,6 @@ import type { FieldChangeEncodingContext } from "../modular-schema/index.js";
 
 import type { OptionalChangeset } from "./optionalFieldChangeTypes.js";
 import { makeOptionalFieldCodec as makeV2Codec } from "./optionalFieldCodecV2.js";
-import { makeOptionalFieldCodec as makeV3Codec } from "./optionalFieldCodecV3.js";
 
 export const makeOptionalFieldCodecFamily = (
 	revisionTagCodec: IJsonCodec<
@@ -23,7 +22,4 @@ export const makeOptionalFieldCodecFamily = (
 		ChangeEncodingContext
 	>,
 ): ICodecFamily<OptionalChangeset, FieldChangeEncodingContext> =>
-	makeCodecFamily([
-		[2, makeV2Codec(revisionTagCodec)],
-		[3, makeV3Codec(revisionTagCodec)],
-	]);
+	makeCodecFamily([[2, makeV2Codec(revisionTagCodec)]]);

package/src/feature-libraries/optional-field/requiredField.ts

@@ -0,0 +1,62 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { type ChangeAtomId, Multiplicity } from "../../core/index.js";
+import { requiredIdentifier, identifierFieldIdentifier } from "../fieldKindIdentifiers.js";
+import {
+	type FieldEditor,
+	type FieldChangeHandler,
+	FlexFieldKind,
+} from "../modular-schema/index.js";
+
+import { optionalChangeHandler, optionalFieldEditor } from "./optionalField.js";
+import type { OptionalChangeset } from "./optionalFieldChangeTypes.js";
+
+// Required fields are a restricted version of optional fields that must always contain a value.
+// Because of this, the implementation of required fields lives here, inside optional.
+// This avoids having to export optional field implementation details which are only used by required.
+
+/**
+ * {@link FieldEditor} for required fields (always contain exactly 1 child).
+ * @remarks
+ * This shares code with optional fields, since they are the same edit wise except setting to empty is not allowed,
+ * and the content is always assumed to not be empty.
+ * This means the actual edits implemented for optional fields are sufficient to support required fields
+ * which is why this is defined and implemented in terms of optional fields.
+ */
+export interface RequiredFieldEditor extends FieldEditor<OptionalChangeset> {
+	/**
+	 * Creates a change which replaces the current value of the field with `newValue`.
+	 * @param ids - The ids for the fill and detach fields.
+	 */
+	set(ids: { fill: ChangeAtomId; detach: ChangeAtomId }): OptionalChangeset;
+}
+
+export const requiredFieldEditor: RequiredFieldEditor = {
+	...optionalFieldEditor,
+	set: (ids: {
+		fill: ChangeAtomId;
+		detach: ChangeAtomId;
+	}): OptionalChangeset => optionalFieldEditor.set(false, ids),
+};
+
+export const requiredFieldChangeHandler: FieldChangeHandler<
+	OptionalChangeset,
+	RequiredFieldEditor
+> = {
+	...optionalChangeHandler,
+	editor: requiredFieldEditor,
+};
+
+interface Required
+	extends FlexFieldKind<RequiredFieldEditor, typeof requiredIdentifier, Multiplicity.Single> {}
+
+/**
+ * Exactly one item.
+ */
+export const required: Required = new FlexFieldKind(requiredIdentifier, Multiplicity.Single, {
+	changeHandler: requiredFieldChangeHandler,
+	allowMonotonicUpgradeFrom: new Set([identifierFieldIdentifier]),
+});

package/src/feature-libraries/schema-edits/schemaChangeCodecs.ts

@@ -15,11 +15,11 @@ import {
 	makeVersionDispatchingCodec,
 	withSchemaValidation,
 } from "../../codec/index.js";
+import { SchemaFormatVersion } from "../../core/index.js";
 import { makeSchemaCodec, schemaCodecBuilder } from "../schema-index/index.js";
 
 import { EncodedSchemaChange } from "./schemaChangeFormat.js";
 import type { SchemaChange } from "./schemaChangeTypes.js";
-import { SchemaFormatVersion } from "../../core/index.js";
 
 /**
  * Create a family of schema change codecs.

package/src/feature-libraries/schema-edits/schemaChangeFormat.ts

@@ -4,6 +4,7 @@
  */
 
 import { type Static, Type } from "@sinclair/typebox";
+
 import { JsonCompatibleReadOnlySchema } from "../../util/index.js";
 
 export const EncodedSchemaChange = Type.Object({

package/src/feature-libraries/schemaChecker.ts

@@ -14,10 +14,11 @@ import {
 	Multiplicity,
 	type SchemaAndPolicy,
 } from "../core/index.js";
-import { allowsValue } from "./valueUtilities.js";
-import type { MapTreeFieldViewGeneric, MinimalMapTreeNodeView } from "./mapTreeCursor.js";
 import { iterableHasSome, mapIterable } from "../util/index.js";
 
+import type { MapTreeFieldViewGeneric, MinimalMapTreeNodeView } from "./mapTreeCursor.js";
+import { allowsValue } from "./valueUtilities.js";
+
 export enum SchemaValidationError {
 	Field_KindNotInSchemaPolicy,
 	Field_MissingRequiredChild,