@fluidframework/tree 2.0.0-rc.2.0.2 → 2.0.0-rc.3.0.0

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

@@ -4,11 +4,12 @@
  */
 
 import { ObjectOptions, Static, Type } from "@sinclair/typebox";
-import { schemaFormat, RevisionTagSchema, ChangesetLocalId } from "../../core/index.js";
+
+import { ChangesetLocalId, RevisionTagSchema, schemaFormat } from "../../core/index.js";
 import {
-	brandedNumberType,
 	JsonCompatibleReadOnly,
 	JsonCompatibleReadOnlySchema,
+	brandedNumberType,
 } from "../../util/index.js";
 import { EncodedFieldBatch } from "../chunked-forest/index.js";
 
@@ -22,24 +23,7 @@ export const EncodedChangeAtomId = Type.Union([
 	Type.Tuple([ChangesetLocalIdSchema, RevisionTagSchema]),
 	ChangesetLocalIdSchema,
 ]);
-
-const EncodedValueChange = Type.Object(
-	{
-		revision: Type.Optional(RevisionTagSchema),
-		value: Type.Optional(JsonCompatibleReadOnlySchema),
-	},
-	noAdditionalProps,
-);
-type EncodedValueChange = Static<typeof EncodedValueChange>;
-
-const EncodedValueConstraint = Type.Object(
-	{
-		value: Type.Optional(JsonCompatibleReadOnlySchema),
-		violated: Type.Boolean(),
-	},
-	noAdditionalProps,
-);
-type EncodedValueConstraint = Static<typeof EncodedValueConstraint>;
+export type EncodedChangeAtomId = Static<typeof EncodedChangeAtomId>;
 
 const EncodedFieldChange = Type.Object(
 	{
@@ -81,9 +65,7 @@ type EncodedNodeExistsConstraint = Static<typeof EncodedNodeExistsConstraint>;
 
 export const EncodedNodeChangeset = Type.Object(
 	{
-		valueChange: Type.Optional(EncodedValueChange),
 		fieldChanges: Type.Optional(EncodedFieldChangeMap),
-		valueConstraint: Type.Optional(EncodedValueConstraint),
 		nodeExistsConstraint: Type.Optional(EncodedNodeExistsConstraint),
 	},
 	noAdditionalProps,

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

@@ -4,6 +4,7 @@
  */
 
 import {
+	ChangeAtomId,
 	ChangeAtomIdMap,
 	ChangesetLocalId,
 	FieldKey,
@@ -22,15 +23,16 @@ export interface ModularChangeset extends HasFieldChanges {
 	 * The numerically highest `ChangesetLocalId` used in this changeset.
 	 * If undefined then this changeset contains no IDs.
 	 */
-	maxId?: ChangesetLocalId;
+	readonly maxId?: ChangesetLocalId;
 	/**
 	 * The revisions included in this changeset, ordered temporally (oldest to newest).
 	 * Undefined for anonymous changesets.
 	 * Should never be empty.
 	 */
 	readonly revisions?: readonly RevisionInfo[];
-	fieldChanges: FieldChangeMap;
-	constraintViolationCount?: number;
+	readonly fieldChanges: FieldChangeMap;
+	readonly nodeChanges: ChangeAtomIdMap<NodeChangeset>;
+	readonly constraintViolationCount?: number;
 	readonly builds?: ChangeAtomIdMap<TreeChunk>;
 	readonly destroys?: ChangeAtomIdMap<number>;
 	readonly refreshers?: ChangeAtomIdMap<TreeChunk>;
@@ -51,6 +53,8 @@ export interface NodeChangeset extends HasFieldChanges {
 	nodeExistsConstraint?: NodeExistsConstraint;
 }
 
+export type NodeId = ChangeAtomId;
+
 /**
  * @internal
  */

package/src/feature-libraries/node-key/nodeKey.ts

@@ -4,8 +4,9 @@
  */
 
 import { SessionSpaceCompressedId, StableId } from "@fluidframework/id-compressor";
-import { Brand, Opaque, brand } from "../../util/index.js";
+
 import { TreeNodeSchemaIdentifier } from "../../core/index.js";
+import { Brand, Opaque, brand } from "../../util/index.js";
 
 /**
  * A key which uniquely identifies a node in the tree within this session.

package/src/feature-libraries/node-key/nodeKeyIndex.ts

@@ -3,15 +3,17 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils";
+import { assert } from "@fluidframework/core-utils/internal";
+
 import { FieldKey, ValueSchema } from "../../core/index.js";
 import {
-	FlexTreeObjectNode,
 	FlexTreeContext,
 	FlexTreeField,
 	FlexTreeNode,
+	FlexTreeObjectNode,
 } from "../flex-tree/index.js";
 import { FlexTreeSchema, LeafNodeSchema, schemaIsObjectNode } from "../typed-schema/index.js";
+
 import { LocalNodeKey, nodeKeyTreeIdentifier } from "./nodeKey.js";
 
 /**
@@ -43,7 +45,7 @@ export class NodeKeyIndex implements ReadonlyMap<LocalNodeKey, FlexTreeObjectNod
 	/**
 	 * Search the tree for all nodes with keys, and record them in this index for lookup.
 	 * This should be called each time the tree changes; each call to scan forgets all existing keys.
-	 * @param context - the editable tree context in which to search for node keys
+	 * @param context - the flex tree context in which to search for node keys
 	 */
 	// TODO: This can be optimized by responding to deltas/changes to the tree, rather than rescanning the whole tree every time
 	public scanKeys(context: FlexTreeContext): void {

package/src/feature-libraries/node-key/nodeKeyManager.ts

@@ -3,15 +3,17 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils";
+import { assert } from "@fluidframework/core-utils/internal";
 import {
-	assertIsStableId,
 	IIdCompressor,
 	SessionSpaceCompressedId,
 	StableId,
-} from "@fluidframework/id-compressor";
+	assertIsStableId,
+} from "@fluidframework/id-compressor/internal";
+
 import { brand, extractFromOpaque } from "../../util/index.js";
-import { StableNodeKey, LocalNodeKey } from "./nodeKey.js";
+
+import { LocalNodeKey, StableNodeKey } from "./nodeKey.js";
 
 /**
  * An object which handles the generation of node keys as well as conversion between their two types ({@link StableNodeKey} and {@link LocalNodeKey}).

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

@@ -3,45 +3,46 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils";
+import { assert } from "@fluidframework/core-utils/internal";
+
 import {
-	ITreeSubscriptionCursor,
-	IEditableForest,
-	ITreeSubscriptionCursorState,
-	TreeNavigationResult,
-	TreeStoredSchemaSubscription,
-	FieldKey,
-	DetachedField,
-	AnchorSet,
-	UpPath,
 	Anchor,
-	ITreeCursor,
+	AnchorSet,
 	CursorLocationType,
-	TreeNodeSchemaIdentifier,
-	MapTree,
-	getMapTreeField,
+	DeltaVisitor,
+	DetachedField,
 	FieldAnchor,
+	FieldKey,
 	FieldUpPath,
 	ForestEvents,
+	IEditableForest,
+	ITreeCursor,
+	ITreeCursorSynchronous,
+	ITreeSubscriptionCursor,
+	ITreeSubscriptionCursorState,
+	MapTree,
 	PathRootPrefix,
-	DeltaVisitor,
-	Range,
 	PlaceIndex,
+	ProtoNodes,
+	Range,
+	TreeNavigationResult,
+	TreeNodeSchemaIdentifier,
+	TreeStoredSchemaSubscription,
+	UpPath,
 	Value,
-	ITreeCursorSynchronous,
 	aboveRootPlaceholder,
-	ProtoNodes,
+	getMapTreeField,
 } from "../../core/index.js";
+import { createEmitter } from "../../events/index.js";
 import {
-	brand,
-	fail,
+	assertNonNegativeSafeInteger,
 	assertValidIndex,
 	assertValidRange,
-	assertNonNegativeSafeInteger,
+	brand,
+	fail,
 } from "../../util/index.js";
+import { cursorForMapTreeNode, mapTreeFromCursor } from "../mapTreeCursor.js";
 import { CursorWithNode, SynchronousCursor } from "../treeCursorUtils.js";
-import { mapTreeFromCursor, cursorForMapTreeNode } from "../mapTreeCursor.js";
-import { createEmitter } from "../../events/index.js";
 
 function makeRoot(): MapTree {
 	return {
@@ -131,6 +132,7 @@ export class ObjectForest implements IEditableForest {
 			},
 			create(content: ProtoNodes, destination: FieldKey): void {
 				this.forest.add(content, destination);
+				this.forest.events.emit("afterRootFieldCreated", destination);
 			},
 			attach(source: FieldKey, count: number, destination: PlaceIndex): void {
 				this.attachEdit(source, count, destination);

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-export { noChangeCodecFamily, makeOptionalFieldCodecFamily } from "./optionalFieldCodecs.js";
+export { makeOptionalFieldCodecFamily } from "./optionalFieldCodecs.js";
 export { Move, OptionalChangeset, RegisterId } from "./optionalFieldChangeTypes.js";
 export {
 	IRegisterMap,

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

@@ -3,47 +3,50 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils";
+import { assert } from "@fluidframework/core-utils/internal";
+
 import {
-	TaggedChange,
+	ChangeAtomId,
+	ChangeAtomIdMap,
 	ChangesetLocalId,
-	RevisionTag,
+	DeltaDetachedNodeChanges,
+	DeltaDetachedNodeId,
 	DeltaFieldChanges,
 	DeltaMark,
-	DeltaDetachedNodeId,
-	DeltaDetachedNodeChanges,
-	ChangeAtomId,
+	RevisionTag,
+	TaggedChange,
 	areEqualChangeAtomIds,
-	ChangeAtomIdMap,
 	makeChangeAtomId,
+	taggedAtomId,
+	taggedOptAtomId,
 } from "../../core/index.js";
 import {
-	Mutable,
 	IdAllocator,
+	Mutable,
 	SizedNestedMap,
+	deleteFromNestedMap,
 	setInNestedMap,
 	tryGetFromNestedMap,
-	deleteFromNestedMap,
 } from "../../util/index.js";
+import { nodeIdFromChangeAtom } from "../deltaUtils.js";
 import {
-	ToDelta,
+	FieldChangeHandler,
 	FieldChangeRebaser,
+	FieldEditor,
 	NodeChangeComposer,
-	NodeChangeInverter,
+	NodeChangePruner,
 	NodeChangeRebaser,
-	NodeChangeset,
-	FieldEditor,
 	NodeExistenceState,
-	FieldChangeHandler,
+	NodeId,
 	RelevantRemovedRootsFromChild,
-	NodeChangePruner,
+	ToDelta,
 } from "../modular-schema/index.js";
-import { nodeIdFromChangeAtom } from "../deltaUtils.js";
+
 import {
-	RegisterId,
-	OptionalChangeset,
-	Move,
 	ChildChange,
+	Move,
+	OptionalChangeset,
+	RegisterId,
 	Replace,
 } from "./optionalFieldChangeTypes.js";
 import { makeOptionalFieldCodecFamily } from "./optionalFieldCodecs.js";
@@ -153,7 +156,7 @@ export const optionalChangeRebaser: FieldChangeRebaser<OptionalChangeset> = {
 	): OptionalChangeset => {
 		const { srcToDst, dstToSrc } = getBidirectionalMaps(change1.moves, revision1);
 		const change1FieldSrc = taggedOptRegister(change1.valueReplace?.src, revision1);
-		const change1FieldDst = taggedOptAtomId(change1.valueReplace?.dst, revision1);
+		const change1FieldDst = taggedOptAtomId(getEffectfulDst(change1.valueReplace), revision1);
 
 		const change2FieldSrc = taggedOptRegister(change2.valueReplace?.src, revision2);
 		let composedFieldSrc: RegisterId | undefined;
@@ -161,10 +164,8 @@ export const optionalChangeRebaser: FieldChangeRebaser<OptionalChangeset> = {
 			if (change2FieldSrc === "self") {
 				composedFieldSrc = change1FieldSrc ?? change2FieldSrc;
 			} else if (
-				change1.valueReplace !== undefined &&
-				isReplaceEffectful(change1.valueReplace) &&
 				change1FieldDst !== undefined &&
-				areEqualRegisterIds(change2FieldSrc, change1FieldDst)
+				areEqualRegisterIds(change1FieldDst, change2FieldSrc)
 			) {
 				composedFieldSrc = "self";
 			} else {
@@ -179,7 +180,7 @@ export const optionalChangeRebaser: FieldChangeRebaser<OptionalChangeset> = {
 			composedFieldSrc = change1FieldSrc;
 		}
 
-		const childChanges2ByOriginalId = new RegisterMap<NodeChangeset>();
+		const childChanges2ByOriginalId = new RegisterMap<NodeId>();
 		for (const [id, change] of change2.childChanges) {
 			if (id === "self") {
 				if (change1FieldSrc !== undefined) {
@@ -280,7 +281,6 @@ export const optionalChangeRebaser: FieldChangeRebaser<OptionalChangeset> = {
 
 	invert: (
 		{ revision, change }: TaggedChange<OptionalChangeset>,
-		invertChild: NodeChangeInverter,
 		isRollback: boolean,
 		genId: IdAllocator<ChangesetLocalId>,
 	): OptionalChangeset => {
@@ -297,7 +297,8 @@ export const optionalChangeRebaser: FieldChangeRebaser<OptionalChangeset> = {
 			invertedMoves.push([taggedDst, taggedSrc]);
 		}
 		if (change.valueReplace !== undefined) {
-			if (change.valueReplace.isEmpty === false) {
+			const effectfulDst = getEffectfulDst(change.valueReplace);
+			if (effectfulDst !== undefined) {
 				invertIdMap.set("self", tagAtomId(change.valueReplace.dst));
 			}
 			if (change.valueReplace.src !== undefined) {
@@ -309,7 +310,7 @@ export const optionalChangeRebaser: FieldChangeRebaser<OptionalChangeset> = {
 			moves: invertedMoves,
 			childChanges: childChanges.map(([id, childChange]) => {
 				const taggedId = tagRegister(id);
-				return [invertIdMap.get(taggedId) ?? taggedId, invertChild(childChange)];
+				return [invertIdMap.get(taggedId) ?? taggedId, childChange];
 			}),
 		};
 
@@ -365,7 +366,8 @@ export const optionalChangeRebaser: FieldChangeRebaser<OptionalChangeset> = {
 			forwardMap.set(tagAtomId(src), tagAtomId(dst));
 		}
 		if (overChange.valueReplace !== undefined) {
-			if (overChange.valueReplace.isEmpty === false) {
+			const effectfulDst = getEffectfulDst(overChange.valueReplace);
+			if (effectfulDst !== undefined) {
 				forwardMap.set("self", tagAtomId(overChange.valueReplace.dst));
 			}
 			if (overChange.valueReplace.src !== undefined) {
@@ -379,7 +381,7 @@ export const optionalChangeRebaser: FieldChangeRebaser<OptionalChangeset> = {
 			rebasedMoves.push([src, newDst ?? dst]);
 		}
 
-		const overChildChangesBySrc = new RegisterMap<NodeChangeset>();
+		const overChildChangesBySrc = new RegisterMap<NodeId>();
 		for (const [id, childChange] of overChange.childChanges) {
 			overChildChangesBySrc.set(tagRegister(id) ?? id, childChange);
 		}
@@ -530,6 +532,12 @@ function isReplaceEffectful(replace: Replace): replace is EffectfulReplace {
 	return !replace.isEmpty || replace.src !== undefined;
 }
 
+function getEffectfulDst(replace: Replace | undefined): ChangeAtomId | undefined {
+	return replace === undefined || replace.isEmpty || replace.src === "self"
+		? undefined
+		: replace.dst;
+}
+
 function taggedOptRegister(
 	id: RegisterId | undefined,
 	revision: RevisionTag | undefined,
@@ -537,20 +545,6 @@ function taggedOptRegister(
 	return id !== undefined ? taggedRegister(id, revision) : undefined;
 }
 
-export function taggedAtomId(id: ChangeAtomId, revision: RevisionTag | undefined): ChangeAtomId {
-	return makeChangeAtomId(id.localId, id.revision ?? revision);
-}
-
-export function taggedOptAtomId(
-	id: ChangeAtomId | undefined,
-	revision: RevisionTag | undefined,
-): ChangeAtomId | undefined {
-	if (id === undefined) {
-		return undefined;
-	}
-	return taggedAtomId(id, revision);
-}
-
 export function taggedRegister(id: RegisterId, revision: RevisionTag | undefined): RegisterId {
 	if (id === "self") {
 		return id;
@@ -610,7 +604,7 @@ export const optionalFieldEditor: OptionalFieldEditor = {
 		},
 	}),
 
-	buildChildChange: (index: number, childChange: NodeChangeset): OptionalChangeset => {
+	buildChildChange: (index: number, childChange: NodeId): OptionalChangeset => {
 		assert(index === 0, 0x404 /* Optional fields only support a single child node */);
 		return {
 			moves: [],

package/src/feature-libraries/optional-field/{optionalFieldChangeFormat.ts → optionalFieldChangeFormatV1.ts}

@@ -3,7 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { Static, ObjectOptions, TSchema, Type } from "@sinclair/typebox";
+import { ObjectOptions, Static, TSchema, Type } from "@sinclair/typebox";
+
 import { EncodedChangeAtomId } from "../modular-schema/index.js";
 
 const noAdditionalProps: ObjectOptions = { additionalProperties: false };
@@ -19,9 +20,14 @@ export type EncodedBuild = Static<typeof EncodedBuild>;
 export const EncodedOptionalChangeset = <Schema extends TSchema>(tNodeChange: Schema) =>
 	Type.Object(
 		{
+			// Subtrees being created. They start as detached.
 			b: Type.Optional(Type.Array(EncodedBuild)),
+			// Subtrees being moved.
 			m: EncodedMoves,
+			// Nested changes
 			c: EncodedChildChanges(tNodeChange),
+			// Reserved ID for detaching the subtree from the field if it were to be populated.
+			// Only specified when the field is empty.
 			d: Type.Optional(EncodedRegisterId),
 		},
 		noAdditionalProps,
@@ -32,12 +38,15 @@ export type EncodedOptionalChangeset<Schema extends TSchema> = Static<
 >;
 
 const EncodedChildChanges = <Schema extends TSchema>(tNodeChange: Schema) =>
+	// Changes to the children of the node that is in the specified register in the input context of this change.
 	Type.Optional(Type.Array(Type.Tuple([EncodedRegisterId, tNodeChange])));
 
 // A list of triplets (source, destination, isNodeTargeting) each representing a move of a node
 // from its current source register to a new destination register.
 // If the move is node targeting then the intention is to move a specific node which happens to be in the source register.
 // Otherwise the intention is to move whatever node happens to be in the source register.
+// 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.
 const EncodedMoves = Type.Optional(
 	Type.Array(Type.Tuple([EncodedRegisterId, EncodedRegisterId, Type.Optional(Type.Boolean())])),
 );

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

@@ -0,0 +1,60 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ObjectOptions, Static, TSchema, Type } from "@sinclair/typebox";
+
+import { EncodedChangeAtomId } from "../modular-schema/index.js";
+
+const noAdditionalProps: ObjectOptions = { additionalProperties: false };
+
+// `null` signifies "self". Using undefined doesn't actually JSON round-trip conveniently, since
+// undefined is converted to null when inside an array (which happens in e.g. the moves array).
+export const EncodedRegisterId = Type.Union([EncodedChangeAtomId, Type.Null()]);
+export type EncodedRegisterId = Static<typeof EncodedRegisterId>;
+
+export const EncodedOptionalChangeset = <Schema extends TSchema>(tNodeChange: Schema) =>
+	Type.Object(
+		{
+			// Moves between detached fields.
+			// These entries should not be interpreted as "applied one after the other", but rather as
+			// "applied simultaneously". As such, this list should not contain duplicated src or dst entries.
+			m: Type.Optional(Type.Array(EncodedMove)),
+			// Nested changes
+			c: Type.Optional(EncodedChildChanges(tNodeChange)),
+			// How to replace the current value of the field.
+			r: Type.Optional(EncodedReplace),
+		},
+		noAdditionalProps,
+	);
+
+export type EncodedOptionalChangeset<Schema extends TSchema> = Static<
+	ReturnType<typeof EncodedOptionalChangeset<Schema>>
+>;
+
+const EncodedChildChanges = <Schema extends TSchema>(tNodeChange: Schema) =>
+	// Changes to the children of the node that is in the specified register in the input context of this change.
+	Type.Array(Type.Tuple([EncodedRegisterId, tNodeChange]));
+
+// A list of triplets (source, destination, isNodeTargeting) each representing a move of a node
+// from its current source register to a new destination register.
+// If the move is node targeting then the intention is to move a specific node which happens to be in the source register.
+// Otherwise the intention is to move whatever node happens to be in the source register.
+// 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.
+const EncodedMove = Type.Tuple([EncodedChangeAtomId, EncodedChangeAtomId]);
+
+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(EncodedRegisterId),
+		// 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

@@ -4,7 +4,7 @@
  */
 
 import { ChangeAtomId } from "../../core/index.js";
-import { NodeChangeset } from "../modular-schema/index.js";
+import { NodeId } from "../modular-schema/index.js";
 
 /**
  * Uniquely identifies a register within the scope of this changeset.
@@ -17,10 +17,7 @@ export type RegisterId = ChangeAtomId | "self";
 
 export type Move = readonly [src: ChangeAtomId, dst: ChangeAtomId];
 
-export type ChildChange<TChildChange = NodeChangeset> = readonly [
-	register: RegisterId,
-	childChange: TChildChange,
-];
+export type ChildChange = readonly [register: RegisterId, childChange: NodeId];
 
 /**
  * Changes to an optional field.
@@ -30,7 +27,7 @@ export type ChildChange<TChildChange = NodeChangeset> = readonly [
  * 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<TChildChange = NodeChangeset> {
+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}.
@@ -45,7 +42,7 @@ export interface OptionalChangeset<TChildChange = NodeChangeset> {
 	 *
 	 * Nodes are identified by the register they occupy in the *input* context of the changeset.
 	 */
-	readonly childChanges: readonly ChildChange<TChildChange>[];
+	readonly childChanges: readonly ChildChange[];
 
 	/**
 	 * An optional description of how to replace the current value of the field.