@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

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

@@ -0,0 +1,58 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils";
+import { DeltaDetachedNodeId, TaggedChange, offsetDetachId } from "../../core";
+import { nodeIdFromChangeAtom } from "../deltaUtils";
+import { Changeset, Mark } from "./types";
+import { isInsert, isDetachOfRemovedNodes, isAttachAndDetachEffect } from "./utils";
+
+export type RelevantRemovedRootsFromTChild<TChild> = (
+	child: TChild,
+) => Iterable<DeltaDetachedNodeId>;
+
+export function* relevantRemovedRoots<TChild>(
+	{ change, revision }: TaggedChange<Changeset<TChild>>,
+	relevantRemovedRootsFromChild: RelevantRemovedRootsFromTChild<TChild>,
+): Iterable<DeltaDetachedNodeId> {
+	for (const mark of change) {
+		if (refersToRelevantRemovedRoots(mark)) {
+			assert(
+				mark.cellId !== undefined,
+				0x81d /* marks referring to removed trees must have an assigned cell ID */,
+			);
+			const nodeId = nodeIdFromChangeAtom(mark.cellId, revision);
+			for (let i = 0; i < mark.count; i += 1) {
+				yield offsetDetachId(nodeId, i);
+			}
+		}
+		if (mark.changes !== undefined) {
+			yield* relevantRemovedRootsFromChild(mark.changes);
+		}
+	}
+}
+
+function refersToRelevantRemovedRoots<TChild>(mark: Mark<TChild>): boolean {
+	if (mark.cellId !== undefined) {
+		const effect = isAttachAndDetachEffect(mark) ? mark.attach : mark;
+		if (isInsert(effect)) {
+			// This tree is being inserted or restored.
+			return true;
+		} else if (isDetachOfRemovedNodes(mark)) {
+			// This removed tree is being restored as part of a detach.
+			return true;
+		}
+		if (mark.changes !== undefined) {
+			// This removed tree is being edited.
+			// Note: there is a possibility that the child changes only affect a distant descendant
+			// which may have been removed from this (removed) subtree. In such a case, this tree is not truly
+			// relevant, but including it is the conservative thing to do.
+			// In the future, we may represent changes to removed trees using the ID of the lowest removed
+			// ancestor, which would allow us to avoid including such trees when they truly are not needed.
+			return true;
+		}
+	}
+	return false;
+}

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

@@ -0,0 +1,24 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { FieldChangeHandler } from "../modular-schema";
+import { Changeset } from "./types";
+import { sequenceFieldChangeRebaser } from "./sequenceFieldChangeRebaser";
+import { sequenceFieldChangeCodecFactory } from "./sequenceFieldCodecs";
+import { SequenceFieldEditor, sequenceFieldEditor } from "./sequenceFieldEditor";
+import { sequenceFieldToDelta } from "./sequenceFieldToDelta";
+import { isEmpty } from "./utils";
+import { relevantRemovedRoots } from "./relevantRemovedRoots";
+
+export type SequenceFieldChangeHandler = FieldChangeHandler<Changeset, SequenceFieldEditor>;
+
+export const sequenceFieldChangeHandler: SequenceFieldChangeHandler = {
+	rebaser: sequenceFieldChangeRebaser,
+	codecsFactory: sequenceFieldChangeCodecFactory,
+	editor: sequenceFieldEditor,
+	intoDelta: sequenceFieldToDelta,
+	relevantRemovedRoots,
+	isEmpty,
+};

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

@@ -0,0 +1,21 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { FieldChangeRebaser } from "../modular-schema";
+import { amendCompose, compose } from "./compose";
+import { Changeset } from "./types";
+import { invert } from "./invert";
+import { rebase } from "./rebase";
+import { prune } from "./prune";
+
+export type SequenceChangeRebaser = FieldChangeRebaser<Changeset>;
+
+export const sequenceFieldChangeRebaser = {
+	compose,
+	amendCompose,
+	invert,
+	rebase,
+	prune,
+};

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

@@ -0,0 +1,280 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { unreachableCase } from "@fluidframework/core-utils";
+import { TAnySchema, Type } from "@sinclair/typebox";
+import { JsonCompatibleReadOnly, Mutable, fail } from "../../util";
+import { DiscriminatedUnionDispatcher, IJsonCodec, makeCodecFamily } from "../../codec";
+import { EncodedRevisionTag, RevisionTag } from "../../core";
+import { decodeChangeAtomId, encodeChangeAtomId } from "../utils";
+import {
+	Attach,
+	AttachAndDetach,
+	CellId,
+	Changeset,
+	Delete,
+	Detach,
+	Insert,
+	Mark,
+	MarkEffect,
+	MoveIn,
+	MoveOut,
+	NoopMarkType,
+} from "./types";
+import { Changeset as ChangesetSchema, Encoded } from "./format";
+import { isNoopMark } from "./utils";
+
+export const sequenceFieldChangeCodecFactory = <TNodeChange>(
+	childCodec: IJsonCodec<TNodeChange>,
+	revisionTagCodec: IJsonCodec<RevisionTag, EncodedRevisionTag>,
+) => makeCodecFamily<Changeset<TNodeChange>>([[0, makeV0Codec(childCodec, revisionTagCodec)]]);
+function makeV0Codec<TNodeChange>(
+	childCodec: IJsonCodec<TNodeChange>,
+	revisionTagCodec: IJsonCodec<RevisionTag, EncodedRevisionTag>,
+): IJsonCodec<Changeset<TNodeChange>> {
+	const markEffectCodec: IJsonCodec<MarkEffect, Encoded.MarkEffect> = {
+		encode(effect: MarkEffect): Encoded.MarkEffect {
+			const type = effect.type;
+			switch (type) {
+				case "MoveIn":
+					return {
+						moveIn: {
+							revision:
+								effect.revision === undefined
+									? undefined
+									: revisionTagCodec.encode(effect.revision),
+							finalEndpoint:
+								effect.finalEndpoint === undefined
+									? undefined
+									: encodeChangeAtomId(revisionTagCodec, effect.finalEndpoint),
+							id: effect.id,
+						},
+					};
+				case "Insert":
+					return {
+						insert: {
+							revision:
+								effect.revision === undefined
+									? undefined
+									: revisionTagCodec.encode(effect.revision),
+							id: effect.id,
+						},
+					};
+				case "Delete":
+					return {
+						delete: {
+							revision:
+								effect.revision === undefined
+									? undefined
+									: revisionTagCodec.encode(effect.revision),
+							redetachId:
+								effect.redetachId === undefined
+									? undefined
+									: cellIdCodec.encode(effect.redetachId),
+							id: effect.id,
+						},
+					};
+				case "MoveOut":
+					return {
+						moveOut: {
+							revision:
+								effect.revision === undefined
+									? undefined
+									: revisionTagCodec.encode(effect.revision),
+							finalEndpoint:
+								effect.finalEndpoint === undefined
+									? undefined
+									: encodeChangeAtomId(revisionTagCodec, effect.finalEndpoint),
+							redetachId:
+								effect.redetachId === undefined
+									? undefined
+									: cellIdCodec.encode(effect.redetachId),
+							id: effect.id,
+						},
+					};
+				case "AttachAndDetach":
+					return {
+						attachAndDetach: {
+							attach: markEffectCodec.encode(effect.attach) as Encoded.Attach,
+							detach: markEffectCodec.encode(effect.detach) as Encoded.Detach,
+						},
+					};
+				case NoopMarkType:
+					fail(`Mark type: ${type} should not be encoded.`);
+				default:
+					unreachableCase(type);
+			}
+		},
+		decode(encoded: Encoded.MarkEffect): MarkEffect {
+			return decoderLibrary.dispatch(encoded);
+		},
+	};
+
+	const decoderLibrary = new DiscriminatedUnionDispatcher<
+		Encoded.MarkEffect,
+		/* args */ [],
+		MarkEffect
+	>({
+		moveIn(encoded: Encoded.MoveIn): MoveIn {
+			const { id, finalEndpoint, revision } = encoded;
+			const mark: MoveIn = {
+				type: "MoveIn",
+				id,
+			};
+			if (revision !== undefined) {
+				mark.revision = revisionTagCodec.decode(revision);
+			}
+			if (finalEndpoint !== undefined) {
+				mark.finalEndpoint = decodeChangeAtomId(revisionTagCodec, finalEndpoint);
+			}
+			return mark;
+		},
+		insert(encoded: Encoded.Insert): Insert {
+			const { id, revision } = encoded;
+			const mark: Insert = {
+				type: "Insert",
+				id,
+			};
+			if (revision !== undefined) {
+				mark.revision = revisionTagCodec.decode(revision);
+			}
+			return mark;
+		},
+		delete(encoded: Encoded.Delete): Delete {
+			const { id, revision, redetachId } = encoded;
+			const mark: Delete = {
+				type: "Delete",
+				id,
+			};
+			if (revision !== undefined) {
+				mark.revision = revisionTagCodec.decode(revision);
+			}
+			if (redetachId !== undefined) {
+				mark.redetachId = cellIdCodec.decode(redetachId);
+			}
+			return mark;
+		},
+		moveOut(encoded: Encoded.MoveOut): MoveOut {
+			const { id, finalEndpoint, redetachId, revision } = encoded;
+			const mark: MoveOut = {
+				type: "MoveOut",
+				id,
+			};
+			if (revision !== undefined) {
+				mark.revision = revisionTagCodec.decode(revision);
+			}
+			if (finalEndpoint !== undefined) {
+				mark.finalEndpoint = decodeChangeAtomId(revisionTagCodec, finalEndpoint);
+			}
+			if (redetachId !== undefined) {
+				mark.redetachId = cellIdCodec.decode(redetachId);
+			}
+			return mark;
+		},
+		attachAndDetach(encoded: Encoded.AttachAndDetach): AttachAndDetach {
+			return {
+				type: "AttachAndDetach",
+				attach: decoderLibrary.dispatch(encoded.attach) as Attach,
+				detach: decoderLibrary.dispatch(encoded.detach) as Detach,
+			};
+		},
+	});
+
+	const cellIdCodec: IJsonCodec<CellId, Encoded.CellId> = {
+		encode: ({ localId, adjacentCells, lineage, revision }: CellId): Encoded.CellId => {
+			const encoded: Encoded.CellId = {
+				localId,
+				adjacentCells: adjacentCells?.map(({ id, count }) => [id, count]),
+				// eslint-disable-next-line @typescript-eslint/no-shadow
+				lineage: lineage?.map(({ revision, id, count, offset }) => [
+					revisionTagCodec.encode(revision),
+					id,
+					count,
+					offset,
+				]),
+				revision: revision === undefined ? revision : revisionTagCodec.encode(revision),
+			};
+			return encoded;
+		},
+		decode: ({ localId, adjacentCells, lineage, revision }: Encoded.CellId): CellId => {
+			// Note: this isn't inlined on decode so that round-tripping changes compare as deep-equal works,
+			// which is mostly just a convenience for tests. On encode, JSON.stringify() takes care of removing
+			// explicit undefined properties.
+			const decoded: Mutable<CellId> = {
+				localId,
+			};
+			if (revision !== undefined) {
+				decoded.revision = revisionTagCodec.decode(revision);
+			}
+			if (adjacentCells !== undefined) {
+				decoded.adjacentCells = adjacentCells.map(([id, count]) => ({
+					id,
+					count,
+				}));
+			}
+			if (lineage !== undefined) {
+				// eslint-disable-next-line @typescript-eslint/no-shadow
+				decoded.lineage = lineage.map(([revision, id, count, offset]) => ({
+					revision: revisionTagCodec.decode(revision),
+					id,
+					count,
+					offset,
+				}));
+			}
+			return decoded;
+		},
+	};
+
+	/**
+	 * If we want to make the node change aspect of this codec more type-safe, we could adjust generics
+	 * to be in terms of the schema rather than the concrete type of the node change.
+	 */
+	type NodeChangeSchema = TAnySchema;
+
+	return {
+		encode: (
+			changeset: Changeset<TNodeChange>,
+		): JsonCompatibleReadOnly & Encoded.Changeset<NodeChangeSchema> => {
+			const jsonMarks: Encoded.Changeset<NodeChangeSchema> = [];
+			for (const mark of changeset) {
+				const encodedMark: Encoded.Mark<NodeChangeSchema> = {
+					count: mark.count,
+				};
+				if (!isNoopMark(mark)) {
+					encodedMark.effect = markEffectCodec.encode(mark);
+				}
+				if (mark.cellId !== undefined) {
+					encodedMark.cellId = cellIdCodec.encode(mark.cellId);
+				}
+				if (mark.changes !== undefined) {
+					encodedMark.changes = childCodec.encode(mark.changes);
+				}
+				jsonMarks.push(encodedMark);
+			}
+			return jsonMarks;
+		},
+		decode: (changeset: Encoded.Changeset<NodeChangeSchema>): Changeset<TNodeChange> => {
+			const marks: Changeset<TNodeChange> = [];
+			for (const mark of changeset) {
+				const decodedMark: Mark<TNodeChange> = {
+					count: mark.count,
+				};
+
+				if (mark.effect !== undefined) {
+					Object.assign(decodedMark, markEffectCodec.decode(mark.effect));
+				}
+				if (mark.cellId !== undefined) {
+					decodedMark.cellId = cellIdCodec.decode(mark.cellId);
+				}
+				if (mark.changes !== undefined) {
+					decodedMark.changes = childCodec.decode(mark.changes);
+				}
+				marks.push(decodedMark);
+			}
+			return marks;
+		},
+		encodedSchema: ChangesetSchema(childCodec.encodedSchema ?? Type.Any()),
+	};
+}

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

@@ -0,0 +1,181 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils";
+import { ChangesetLocalId } from "../../core";
+import { FieldEditor } from "../modular-schema";
+import { brand } from "../../util";
+import {
+	CellId,
+	CellMark,
+	Changeset,
+	Insert,
+	Mark,
+	MoveId,
+	NodeChangeType,
+	MoveOut,
+	MoveIn,
+	MarkList,
+} from "./types";
+import { MarkListFactory } from "./markListFactory";
+import { splitMark } from "./utils";
+
+export interface SequenceFieldEditor extends FieldEditor<Changeset> {
+	insert(index: number, count: number, firstId: ChangesetLocalId): Changeset<never>;
+	delete(index: number, count: number, id: ChangesetLocalId): Changeset<never>;
+	revive(index: number, count: number, detachEvent: CellId, isIntention?: true): Changeset<never>;
+
+	/**
+	 *
+	 * @param sourceIndex - The index of the first node move
+	 * @param count - The number of nodes to move
+	 * @param destIndex - The index the nodes should be moved to, interpreted before detaching the moved nodes
+	 */
+	move(
+		sourceIndex: number,
+		count: number,
+		destIndex: number,
+		id: ChangesetLocalId,
+	): Changeset<never>;
+
+	moveOut(sourceIndex: number, count: number, id: ChangesetLocalId): Changeset<never>;
+	moveIn(destIndex: number, count: number, id: ChangesetLocalId): Changeset<never>;
+
+	return(
+		sourceIndex: number,
+		count: number,
+		destIndex: number,
+		detachEvent: CellId,
+	): Changeset<never>;
+}
+
+export const sequenceFieldEditor = {
+	buildChildChange: <TNodeChange = NodeChangeType>(
+		index: number,
+		change: TNodeChange,
+	): Changeset<TNodeChange> => markAtIndex(index, { count: 1, changes: change }),
+	insert: (index: number, count: number, firstId: ChangesetLocalId): Changeset<never> => {
+		const mark: CellMark<Insert, never> = {
+			type: "Insert",
+			id: firstId,
+			count,
+			cellId: { localId: firstId },
+		};
+		return markAtIndex(index, mark);
+	},
+	delete: (index: number, count: number, id: ChangesetLocalId): Changeset<never> =>
+		count === 0 ? [] : markAtIndex(index, { type: "Delete", count, id }),
+
+	revive: (index: number, count: number, detachEvent: CellId): Changeset<never> => {
+		assert(detachEvent.revision !== undefined, 0x724 /* Detach event must have a revision */);
+		const mark: CellMark<Insert, never> = {
+			type: "Insert",
+			id: detachEvent.localId,
+			count,
+			cellId: detachEvent,
+		};
+		return count === 0 ? [] : markAtIndex(index, mark);
+	},
+
+	move(
+		sourceIndex: number,
+		count: number,
+		destIndex: number,
+		id: ChangesetLocalId,
+	): Changeset<never> {
+		const moveIn: Mark<never> = {
+			type: "MoveIn",
+			id,
+			count,
+			cellId: { localId: id },
+		};
+		const moveOut: Mark<never> = {
+			type: "MoveOut",
+			id,
+			count,
+		};
+		return moveMarksToMarkList(sourceIndex, count, destIndex, moveOut, moveIn);
+	},
+
+	moveOut(sourceIndex: number, count: number, id: ChangesetLocalId): Changeset<never> {
+		const moveOut: Mark<never> = {
+			type: "MoveOut",
+			id,
+			count,
+		};
+		return markAtIndex(sourceIndex, moveOut);
+	},
+
+	moveIn(destIndex: number, count: number, id: ChangesetLocalId): Changeset<never> {
+		const moveIn: Mark<never> = {
+			type: "MoveIn",
+			id,
+			count,
+			cellId: { localId: id },
+		};
+		return markAtIndex(destIndex, moveIn);
+	},
+
+	return(
+		sourceIndex: number,
+		count: number,
+		destIndex: number,
+		detachEvent: CellId,
+	): Changeset<never> {
+		const id = brand<MoveId>(0);
+		const moveOut: CellMark<MoveOut, never> = {
+			type: "MoveOut",
+			id,
+			count,
+		};
+
+		const returnTo: CellMark<MoveIn, never> = {
+			type: "MoveIn",
+			id,
+			count,
+			cellId: detachEvent,
+		};
+
+		return moveMarksToMarkList(sourceIndex, count, destIndex, moveOut, returnTo);
+	},
+} satisfies SequenceFieldEditor;
+
+function moveMarksToMarkList(
+	sourceIndex: number,
+	count: number,
+	destIndex: number,
+	detach: CellMark<MoveOut, never>,
+	attach: CellMark<MoveIn, never>,
+): MarkList<never> {
+	if (count === 0) {
+		return [];
+	}
+	const firstIndexBeyondMoveOut = sourceIndex + count;
+	const marks = new MarkListFactory<never>();
+	marks.pushOffset(Math.min(sourceIndex, destIndex));
+	if (destIndex <= sourceIndex) {
+		// The destination is fully before the source
+		marks.pushContent(attach);
+		marks.pushOffset(sourceIndex - destIndex);
+		marks.pushContent(detach);
+	} else if (firstIndexBeyondMoveOut <= destIndex) {
+		// The destination is fully after the source
+		marks.pushContent(detach);
+		marks.pushOffset(destIndex - firstIndexBeyondMoveOut);
+		marks.pushContent(attach);
+	} else {
+		const firstSectionLength = destIndex - sourceIndex;
+		// The destination is in the middle of the source
+		const [detach1, detach2] = splitMark(detach, firstSectionLength);
+		marks.pushContent(detach1);
+		marks.pushContent(attach);
+		marks.pushContent(detach2);
+	}
+	return marks.list;
+}
+
+function markAtIndex<TNodeChange>(index: number, mark: Mark<TNodeChange>): Changeset<TNodeChange> {
+	return index === 0 ? [mark] : [{ count: index }, mark];
+}