@fluidframework/tree 2.83.0 → 2.90.0-378676

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

@@ -0,0 +1,45 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { type ObjectOptions, type Static, type TSchema, Type } from "@sinclair/typebox";
+
+import { EncodedChangeAtomId } from "../modular-schema/index.js";
+
+const noAdditionalProps: ObjectOptions = { additionalProperties: false };
+
+// Type is intentionally derived.
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export const EncodedOptionalChangeset = <Schema extends TSchema>(tNodeChange: Schema) =>
+	Type.Object(
+		{
+			// Nested changes
+			c: Type.Optional(tNodeChange),
+
+			// How to replace the current value of the field.
+			r: Type.Optional(EncodedReplace),
+
+			// Node detach
+			d: Type.Optional(EncodedChangeAtomId),
+		},
+		noAdditionalProps,
+	);
+
+export type EncodedOptionalChangeset<Schema extends TSchema> = Static<
+	ReturnType<typeof EncodedOptionalChangeset<Schema>>
+>;
+
+const EncodedReplace = Type.Object(
+	{
+		// Whether the field is empty in the input context of this change.
+		e: Type.Boolean(),
+		// 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.
+		s: Type.Optional(EncodedChangeAtomId),
+		// An ID to associate with the node (if any) which is detached by this edit.
+		d: EncodedChangeAtomId,
+	},
+	noAdditionalProps,
+);
+export type EncodedReplace = Static<typeof EncodedReplace>;

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

@@ -6,48 +6,29 @@
 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 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.
+ * 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.
  */
 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.
+	 * An optional description of how to replace the current value of the field.
 	 */
-	readonly moves: readonly Move[];
+	readonly valueReplace?: Replace;
 
 	/**
-	 * Nested changes to nodes that occupy registers.
-	 *
-	 * Nodes are identified by the register they occupy in the *input* context of the changeset.
+	 * If defined, this represents an intention to detach the node current in this field, using `nodeDetach` as the detach ID.
+	 * If this node is moved elsewhere, this detach will follow it to the new location.
+	 * This detach will be applied before any detach in `valueReplace`.
+	 * This should be undefined if this field is empty in the input context of this changeset.
 	 */
-	readonly childChanges: readonly ChildChange[];
-
+	readonly nodeDetach?: ChangeAtomId;
 	/**
-	 * An optional description of how to replace the current value of the field.
+	 * The ID of the node changeset for the node which is in this field in the input context of this changeset.
 	 */
-	readonly valueReplace?: Replace;
+	readonly childChange?: NodeId;
 }
 
 export interface Replace {
@@ -57,13 +38,28 @@ export interface Replace {
 	readonly isEmpty: boolean;
 
 	/**
-	 * 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.
+	 * 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.
 	 */
-	readonly src?: RegisterId;
+	readonly dst: ChangeAtomId;
 
 	/**
-	 * An ID to associate with the node (if any) which is detached by this edit.
+	 * 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.
 	 */
-	readonly dst: ChangeAtomId;
+	readonly src?: ChangeAtomId;
 }

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

@@ -3,14 +3,16 @@
  * Licensed under the MIT License.
  */
 
+import { assert } from "@fluidframework/core-utils/internal";
 import type { TAnySchema } from "@sinclair/typebox";
 
 import type { IJsonCodec } from "../../codec/index.js";
-import type {
-	ChangeAtomId,
-	ChangeEncodingContext,
-	EncodedRevisionTag,
-	RevisionTag,
+import {
+	areEqualChangeAtomIdOpts,
+	type ChangeAtomId,
+	type ChangeEncodingContext,
+	type EncodedRevisionTag,
+	type RevisionTag,
 } from "../../core/index.js";
 import type { Mutable } from "../../util/index.js";
 import { makeChangeAtomIdCodec } from "../changeAtomIdCodec.js";
@@ -21,7 +23,9 @@ import {
 } from "../modular-schema/index.js";
 
 import { EncodedOptionalChangeset, EncodedRegisterId } from "./optionalFieldChangeFormatV2.js";
-import type { OptionalChangeset, RegisterId, Replace } from "./optionalFieldChangeTypes.js";
+import type { OptionalChangeset, Replace } from "./optionalFieldChangeTypes.js";
+
+type RegisterId = ChangeAtomId | "self";
 
 function makeRegisterIdCodec(
 	changeAtomIdCodec: IJsonCodec<
@@ -66,14 +70,13 @@ export function makeOptionalFieldCodec(
 
 	return {
 		encode: (change: OptionalChangeset, context: FieldChangeEncodingContext) => {
-			const encoded: EncodedOptionalChangeset<TAnySchema> = {};
+			assert(
+				change.nodeDetach === undefined ||
+					areEqualChangeAtomIdOpts(change.valueReplace?.src, change.nodeDetach),
+				"This format only supports node detach when it represents a pin",
+			);
 
-			if (change.moves.length > 0) {
-				encoded.m = change.moves.map(([src, dst]) => [
-					changeAtomIdCodec.encode(src, context.baseContext),
-					changeAtomIdCodec.encode(dst, context.baseContext),
-				]);
-			}
+			const encoded: EncodedOptionalChangeset<TAnySchema> = {};
 
 			if (change.valueReplace !== undefined) {
 				encoded.r = {
@@ -81,18 +84,48 @@ export function makeOptionalFieldCodec(
 					d: changeAtomIdCodec.encode(change.valueReplace.dst, context.baseContext),
 				};
 				if (change.valueReplace.src !== undefined) {
-					encoded.r.s = registerIdCodec.encode(change.valueReplace.src, context.baseContext);
+					const srcRegister =
+						change.nodeDetach === undefined ? change.valueReplace.src : "self";
+
+					encoded.r.s = registerIdCodec.encode(srcRegister, context.baseContext);
 				}
 			}
 
-			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),
-					]);
-				}
+			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;
 			}
 
 			return encoded;
@@ -102,18 +135,7 @@ export function makeOptionalFieldCodec(
 			encoded: EncodedOptionalChangeset<TAnySchema>,
 			context: FieldChangeEncodingContext,
 		) => {
-			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),
-					]) ?? [],
-			};
+			const decoded: Mutable<OptionalChangeset> = {};
 
 			if (encoded.r !== undefined) {
 				const replace: Mutable<Replace> = {
@@ -121,10 +143,42 @@ export function makeOptionalFieldCodec(
 					dst: changeAtomIdCodec.decode(encoded.r.d, context.baseContext),
 				};
 				if (encoded.r.s !== undefined) {
-					replace.src = registerIdCodec.decode(encoded.r.s, context.baseContext);
+					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;
+					}
 				}
 				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/optionalFieldCodecV3.ts

@@ -0,0 +1,94 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { TAnySchema } from "@sinclair/typebox";
+
+import type { IJsonCodec } from "../../codec/index.js";
+import type {
+	ChangeEncodingContext,
+	EncodedRevisionTag,
+	RevisionTag,
+} from "../../core/index.js";
+import type { Mutable } from "../../util/index.js";
+import { makeChangeAtomIdCodec } from "../changeAtomIdCodec.js";
+import {
+	EncodedNodeChangeset,
+	type FieldChangeEncodingContext,
+} from "../modular-schema/index.js";
+
+import { EncodedOptionalChangeset } from "./optionalFieldChangeFormatV3.js";
+import type { OptionalChangeset, Replace } from "./optionalFieldChangeTypes.js";
+
+export function makeOptionalFieldCodec(
+	revisionTagCodec: IJsonCodec<
+		RevisionTag,
+		EncodedRevisionTag,
+		EncodedRevisionTag,
+		ChangeEncodingContext
+	>,
+): IJsonCodec<
+	OptionalChangeset,
+	EncodedOptionalChangeset<TAnySchema>,
+	EncodedOptionalChangeset<TAnySchema>,
+	FieldChangeEncodingContext
+> {
+	const changeAtomIdCodec = makeChangeAtomIdCodec(revisionTagCodec);
+
+	return {
+		encode: (change: OptionalChangeset, context: FieldChangeEncodingContext) => {
+			const encoded: EncodedOptionalChangeset<TAnySchema> = {};
+
+			if (change.valueReplace !== undefined) {
+				encoded.r = {
+					e: change.valueReplace.isEmpty,
+					d: changeAtomIdCodec.encode(change.valueReplace.dst, context.baseContext),
+				};
+
+				if (change.valueReplace.src !== undefined) {
+					encoded.r.s = changeAtomIdCodec.encode(change.valueReplace.src, context.baseContext);
+				}
+			}
+
+			if (change.nodeDetach !== undefined) {
+				encoded.d = changeAtomIdCodec.encode(change.nodeDetach, context.baseContext);
+			}
+
+			if (change.childChange !== undefined) {
+				encoded.c = context.encodeNode(change.childChange);
+			}
+
+			return encoded;
+		},
+
+		decode: (
+			encoded: EncodedOptionalChangeset<TAnySchema>,
+			context: FieldChangeEncodingContext,
+		) => {
+			const decoded: Mutable<OptionalChangeset> = {};
+
+			if (encoded.r !== undefined) {
+				const replace: Mutable<Replace> = {
+					isEmpty: encoded.r.e,
+					dst: changeAtomIdCodec.decode(encoded.r.d, context.baseContext),
+				};
+				if (encoded.r.s !== undefined) {
+					replace.src = changeAtomIdCodec.decode(encoded.r.s, context.baseContext);
+				}
+				decoded.valueReplace = replace;
+			}
+
+			if (encoded.d !== undefined) {
+				decoded.nodeDetach = changeAtomIdCodec.decode(encoded.d, context.baseContext);
+			}
+
+			if (encoded.c !== undefined) {
+				decoded.childChange = context.decodeNode(encoded.c);
+			}
+
+			return decoded;
+		},
+		encodedSchema: EncodedOptionalChangeset(EncodedNodeChangeset),
+	};
+}

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

@@ -13,6 +13,7 @@ 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<
@@ -22,4 +23,7 @@ export const makeOptionalFieldCodecFamily = (
 		ChangeEncodingContext
 	>,
 ): ICodecFamily<OptionalChangeset, FieldChangeEncodingContext> =>
-	makeCodecFamily([[2, makeV2Codec(revisionTagCodec)]]);
+	makeCodecFamily([
+		[2, makeV2Codec(revisionTagCodec)],
+		[3, makeV3Codec(revisionTagCodec)],
+	]);

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

@@ -3,15 +3,20 @@
  * Licensed under the MIT License.
  */
 
-import { type ChangeAtomId, Multiplicity } from "../../core/index.js";
+import { type ChangeAtomId, type DeltaFieldChanges, Multiplicity } from "../../core/index.js";
 import { requiredIdentifier, identifierFieldIdentifier } from "../fieldKindIdentifiers.js";
 import {
 	type FieldEditor,
 	type FieldChangeHandler,
 	FlexFieldKind,
+	type ToDelta,
 } from "../modular-schema/index.js";
 
-import { optionalChangeHandler, optionalFieldEditor } from "./optionalField.js";
+import {
+	optionalChangeHandler,
+	optionalFieldEditor,
+	optionalOrRequiredFieldIntoDelta,
+} from "./optionalField.js";
 import type { OptionalChangeset } from "./optionalFieldChangeTypes.js";
 
 // Required fields are a restricted version of optional fields that must always contain a value.
@@ -40,11 +45,19 @@ export const requiredFieldEditor: RequiredFieldEditor = {
 		optionalFieldEditor.set(false, ids),
 };
 
+export function requiredFieldIntoDelta(
+	change: OptionalChangeset,
+	deltaFromChild: ToDelta,
+): DeltaFieldChanges {
+	return optionalOrRequiredFieldIntoDelta(false, change, deltaFromChild);
+}
+
 export const requiredFieldChangeHandler: FieldChangeHandler<
 	OptionalChangeset,
 	RequiredFieldEditor
 > = {
 	...optionalChangeHandler,
+	intoDelta: requiredFieldIntoDelta,
 	editor: requiredFieldEditor,
 };