@fluidframework/tree 2.81.0 → 2.82.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.81.0",
+  "version": "2.82.0",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -101,17 +101,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.81.0",
-    "@fluidframework/container-runtime": "~2.81.0",
-    "@fluidframework/core-interfaces": "~2.81.0",
-    "@fluidframework/core-utils": "~2.81.0",
-    "@fluidframework/datastore-definitions": "~2.81.0",
-    "@fluidframework/driver-definitions": "~2.81.0",
-    "@fluidframework/id-compressor": "~2.81.0",
-    "@fluidframework/runtime-definitions": "~2.81.0",
-    "@fluidframework/runtime-utils": "~2.81.0",
-    "@fluidframework/shared-object-base": "~2.81.0",
-    "@fluidframework/telemetry-utils": "~2.81.0",
+    "@fluid-internal/client-utils": "~2.82.0",
+    "@fluidframework/container-runtime": "~2.82.0",
+    "@fluidframework/core-interfaces": "~2.82.0",
+    "@fluidframework/core-utils": "~2.82.0",
+    "@fluidframework/datastore-definitions": "~2.82.0",
+    "@fluidframework/driver-definitions": "~2.82.0",
+    "@fluidframework/id-compressor": "~2.82.0",
+    "@fluidframework/runtime-definitions": "~2.82.0",
+    "@fluidframework/runtime-utils": "~2.82.0",
+    "@fluidframework/shared-object-base": "~2.82.0",
+    "@fluidframework/telemetry-utils": "~2.82.0",
     "@sinclair/typebox": "^0.34.13",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
     "@types/ungap__structured-clone": "^1.2.0",
@@ -122,25 +122,25 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "~2.81.0",
-    "@fluid-private/stochastic-test-utils": "~2.81.0",
-    "@fluid-private/test-dds-utils": "~2.81.0",
-    "@fluid-private/test-drivers": "~2.81.0",
+    "@fluid-internal/mocha-test-setup": "~2.82.0",
+    "@fluid-private/stochastic-test-utils": "~2.82.0",
+    "@fluid-private/test-dds-utils": "~2.82.0",
+    "@fluid-private/test-drivers": "~2.82.0",
     "@fluid-tools/benchmark": "^0.52.0",
     "@fluid-tools/build-cli": "^0.63.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.63.0",
-    "@fluidframework/container-definitions": "~2.81.0",
-    "@fluidframework/container-loader": "~2.81.0",
-    "@fluidframework/eslint-config-fluid": "~2.81.0",
-    "@fluidframework/test-runtime-utils": "~2.81.0",
-    "@fluidframework/test-utils": "~2.81.0",
-    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.80.0",
+    "@fluidframework/container-definitions": "~2.82.0",
+    "@fluidframework/container-loader": "~2.82.0",
+    "@fluidframework/eslint-config-fluid": "~2.82.0",
+    "@fluidframework/test-runtime-utils": "~2.82.0",
+    "@fluidframework/test-utils": "~2.82.0",
+    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.81.0",
     "@microsoft/api-extractor": "7.52.11",
     "@types/diff": "^3.5.1",
     "@types/easy-table": "^0.0.32",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^18.19.0",
+    "@types/node": "~20.19.30",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "c8": "^10.1.3",

package/src/codec/codec.ts

@@ -10,7 +10,6 @@ import type { MinimumVersionForCollab } from "@fluidframework/runtime-definition
 import { cleanedPackageVersion as runtimeUtilsCleanedPackageVersion } from "@fluidframework/runtime-utils/internal";
 import type { Static, TAnySchema, TSchema } from "@sinclair/typebox";
 
-import type { ChangeEncodingContext } from "../core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";
 
 /**
@@ -139,11 +138,9 @@ export interface ICodecOptions {
 
 /**
  * Options relating to encoding of persisted data.
- * @remarks
- * Extends {@link ICodecOptions} with options that are specific to encoding data.
- * @alpha @input
+ * @input @beta
  */
-export interface CodecWriteOptions extends ICodecOptions {
+export interface CodecWriteOptionsBeta {
 	/**
 	 * The minimum version of the Fluid Framework client output must be encoded to be compatible with.
 	 * @remarks
@@ -154,16 +151,24 @@ export interface CodecWriteOptions extends ICodecOptions {
 	 * the data's format should be versioned and if they can't handle the format they should error.
 	 */
 	readonly minVersionForCollab: MinimumVersionForCollab;
+}
 
+/**
+ * Options relating to encoding of persisted data.
+ * @remarks
+ * Extends {@link ICodecOptions} with options that are specific to encoding data.
+ * @alpha @input
+ */
+export interface CodecWriteOptions extends ICodecOptions, CodecWriteOptionsBeta {
 	/**
 	 * Overrides the version of the codec to use for encoding.
 	 * @remarks
-	 * Without an override, the selected version will be based on {@link CodecWriteOptions.minVersionForCollab}.
+	 * Without an override, the selected version will be based on {@link CodecWriteOptionsBeta.minVersionForCollab}.
 	 */
 	readonly writeVersionOverrides?: ReadonlyMap<CodecName, FormatVersion>;
 
 	/**
-	 * If true, suppress errors when `writeVersionOverrides` selects a version which may not be compatible with the {@link CodecWriteOptions.minVersionForCollab}.
+	 * If true, suppress errors when `writeVersionOverrides` selects a version which may not be compatible with the {@link CodecWriteOptionsBeta.minVersionForCollab}.
 	 */
 	readonly allowPossiblyIncompatibleWriteVersionOverrides?: boolean;
 }
@@ -198,6 +203,20 @@ export interface IJsonCodec<
 	encodedSchema?: TAnySchema;
 }
 
+/**
+ * Type erase the more detailed encoded type from a codec.
+ */
+export function eraseEncodedType<
+	TDecoded,
+	TEncoded = JsonCompatibleReadOnly,
+	TValidate = TEncoded,
+	TContext = void,
+>(
+	codec: IJsonCodec<TDecoded, TEncoded, TValidate, TContext>,
+): IJsonCodec<TDecoded, TValidate, TValidate, TContext> {
+	return codec as unknown as IJsonCodec<TDecoded, TValidate, TValidate, TContext>;
+}
+
 /**
  * @remarks TODO: We might consider using DataView or some kind of writer instead of IsoBuffer.
  */
@@ -381,7 +400,7 @@ class DefaultBinaryCodec<TDecoded, TContext> implements IBinaryCodec<TDecoded, T
 
 	public decode(change: IsoBuffer, context: TContext): TDecoded {
 		const json = bufferToString(change, "utf8");
-		const jsonable = JSON.parse(json);
+		const jsonable = JSON.parse(json) as JsonCompatibleReadOnly;
 		return this.jsonCodec.decode(jsonable, context);
 	}
 }
@@ -453,9 +472,9 @@ export const unitCodec: IMultiFormatCodec<
 export function withSchemaValidation<
 	TInMemoryFormat,
 	EncodedSchema extends TSchema,
-	TEncodedFormat = JsonCompatibleReadOnly,
-	TValidate = TEncodedFormat,
-	TContext = ChangeEncodingContext,
+	TEncodedFormat,
+	TValidate,
+	TContext,
 >(
 	schema: EncodedSchema,
 	codec: IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate, TContext>,

package/src/codec/index.ts

@@ -10,6 +10,7 @@ export {
 	type ICodecFamily,
 	type ICodecOptions,
 	type CodecWriteOptions,
+	type CodecWriteOptionsBeta,
 	type IDecoder,
 	type IEncoder,
 	type IJsonCodec,
@@ -29,6 +30,7 @@ export {
 	jsonableCodecTree,
 	extractJsonValidator,
 	type CodecName,
+	eraseEncodedType,
 } from "./codec.js";
 export {
 	DiscriminatedUnionDispatcher,

package/src/codec/versioned/codec.ts

@@ -401,25 +401,21 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 		Name extends CodecName,
 		Entry extends CodecVersion<unknown, unknown, FormatVersion, never>,
 	>(name: Name, inputRegistry: ConfigMapEntry<Entry>) {
-		type TDecoded2 = Entry extends CodecVersion<infer D, unknown, FormatVersion, never>
-			? D
-			: never;
-		type TContext2 = Entry extends CodecVersion<unknown, infer C, FormatVersion, never>
-			? C
-			: never;
-		type TFormatVersion2 = Entry extends CodecVersion<unknown, unknown, infer F, never>
-			? F
-			: never;
-		type TBuildOptions2 = Entry extends CodecVersion<unknown, unknown, FormatVersion, infer B>
-			? B
-			: never;
+		type TDecoded2 =
+			Entry extends CodecVersion<infer D, unknown, FormatVersion, never> ? D : never;
+		type TContext2 =
+			Entry extends CodecVersion<unknown, infer C, FormatVersion, never> ? C : never;
+		type TFormatVersion2 =
+			Entry extends CodecVersion<unknown, unknown, infer F, never> ? F : never;
+		type TBuildOptions2 =
+			Entry extends CodecVersion<unknown, unknown, FormatVersion, infer B> ? B : never;
 		const builder = new ClientVersionDispatchingCodecBuilder(
 			name,
 			inputRegistry as ConfigMapEntry<unknown> as ConfigMapEntry<
 				CodecVersion<
 					TDecoded2,
 					// If it does not matter what context is provided, undefined is fine, so allow it to be omitted.
-					TContext2 extends unknown ? void : TContext2,
+					unknown extends TContext2 ? void : TContext2,
 					TFormatVersion2,
 					TBuildOptions2
 				>

package/src/core/index.ts

@@ -212,7 +212,9 @@ export {
 	isAncestor,
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
-	compareRevisions,
+	comparePartialRevisions,
+	compareChangesetLocalIds,
+	comparePartialChangesetLocalIds,
 	diffHistories,
 	type RevisionReplacer,
 } from "./rebase/index.js";

package/src/core/rebase/changeRebaser.ts

@@ -121,13 +121,14 @@ export interface RevisionReplacer {
 
 	/**
 	 * Returns the updated ID for the given ID.
-	 * @param id - The ID to update.
+	 * @param id - The ID of the first change atom to update.
+	 * @param count - The number of contiguous change atoms to update. Defaults to 1.
 	 * @returns an updated ID iff the given `id` needs updating, otherwise returns the given `id`.
 	 * @remarks
 	 * This function always maps the same input {@link ChangeAtomId.revision | revision} and {@link ChangeAtomId.localId | local ID} to the same output revision local ID.
 	 * This means multiple references to the same atom of change will remain consistent after revision replacement.
 	 */
-	getUpdatedAtomId<T extends ChangeAtomId>(id: T): T;
+	getUpdatedAtomId<T extends ChangeAtomId>(id: T, count?: number): T;
 }
 
 export interface TaggedChange<TChangeset, TTag = RevisionTag | undefined> {

package/src/core/rebase/index.ts

@@ -31,7 +31,9 @@ export {
 	subtractChangeAtomIds,
 	type ChangeAtomIdRangeMap,
 	newChangeAtomIdRangeMap,
-	compareRevisions,
+	comparePartialRevisions,
+	compareChangesetLocalIds,
+	comparePartialChangesetLocalIds,
 } from "./types.js";
 export { RevisionTagCodec } from "./revisionTagCodec.js";
 export {

package/src/core/rebase/types.ts

@@ -19,6 +19,7 @@ import {
 	brand,
 	brandedNumberType,
 	brandedStringType,
+	comparePartialStrings,
 } from "../../util/index.js";
 import type { RevertibleAlpha } from "../revertible.js";
 
@@ -46,6 +47,9 @@ export const StableIdSchema = Type.String();
 
 /**
  * An ID which is unique within a revision of a `ModularChangeset`.
+ * @remarks
+ * Always a real number (never `NaN` or +/- `Infinity`).
+ *
  * A `ModularChangeset` which is a composition of multiple revisions may contain duplicate `ChangesetLocalId`s,
  * but they are unique when qualified by the revision of the change they are used in.
  */
@@ -122,10 +126,30 @@ export function taggedOptAtomId(
 	return taggedAtomId(id, revision);
 }
 
-export function offsetChangeAtomId(id: ChangeAtomId, offset: number): ChangeAtomId {
+export function offsetChangeAtomId<T extends ChangeAtomId>(id: T, offset: number): T {
 	return { ...id, localId: brand(id.localId + offset) };
 }
 
+// #region These comparison functions are used instead of e.g. `compareNumbers` as a performance optimization
+
+export function compareChangesetLocalIds(a: ChangesetLocalId, b: ChangesetLocalId): number {
+	return a - b; // No need to consider `NaN` or `Infinity` since ChangesetLocalId is always a real number
+}
+
+export function comparePartialChangesetLocalIds(
+	a: ChangesetLocalId | undefined,
+	b: ChangesetLocalId | undefined,
+): number {
+	if (a === undefined) {
+		return b === undefined ? 0 : -1;
+	} else if (b === undefined) {
+		return 1;
+	}
+	return compareChangesetLocalIds(a, b);
+}
+
+// #endregion
+
 /**
  * A node in a graph of commits. A commit's parent is the commit on which it was based.
  */
@@ -204,6 +228,12 @@ export interface LocalChangeMetadata extends CommitMetadata {
 	getRevertible(
 		onDisposed?: (revertible: RevertibleAlpha) => void,
 	): RevertibleAlpha | undefined;
+
+	/**
+	 * Optional label provided by the user when commit was created.
+	 * This can be used by undo/redo to group or classify edits.
+	 */
+	readonly label?: unknown;
 }
 
 /**
@@ -225,6 +255,11 @@ export interface RemoteChangeMetadata extends CommitMetadata {
 	 * @remarks This is only available for {@link LocalChangeMetadata | local changes}.
 	 */
 	readonly getRevertible?: undefined;
+	/**
+	 * Label provided by the user when commit was created.
+	 * @remarks This is only available for {@link LocalChangeMetadata | local changes}.
+	 */
+	readonly label?: undefined;
 }
 
 /**
@@ -255,12 +290,14 @@ export function mintCommit<TChange>(
 
 export type ChangeAtomIdRangeMap<V> = RangeMap<ChangeAtomId, V>;
 
-export function newChangeAtomIdRangeMap<V>(): ChangeAtomIdRangeMap<V> {
-	return new RangeMap(offsetChangeAtomId, subtractChangeAtomIds);
+export function newChangeAtomIdRangeMap<V>(
+	offsetValue?: (value: V, offset: number) => V,
+): ChangeAtomIdRangeMap<V> {
+	return new RangeMap(offsetChangeAtomId, subtractChangeAtomIds, offsetValue);
 }
 
 export function subtractChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): number {
-	const cmp = compareRevisions(a.revision, b.revision);
+	const cmp = comparePartialRevisions(a.revision, b.revision);
 	if (cmp !== 0) {
 		return cmp * Number.POSITIVE_INFINITY;
 	}
@@ -268,19 +305,20 @@ export function subtractChangeAtomIds(a: ChangeAtomId, b: ChangeAtomId): number
 	return a.localId - b.localId;
 }
 
-export function compareRevisions(
+/**
+ * Compares two {@link RevisionTag}s to form a strict total ordering.
+ * @remarks This function tolerates arbitrary strings, not just the string "root".
+ * It sorts as follows: `undefined` \< `string` \< `number`
+ */
+export function comparePartialRevisions(
 	a: RevisionTag | undefined,
 	b: RevisionTag | undefined,
 ): number {
-	if (a === undefined) {
-		return b === undefined ? 0 : -1;
-	} else if (b === undefined) {
-		return 1;
-	} else if (a < b) {
+	if (typeof a === "number") {
+		return typeof b === "number" ? a - b : 1;
+	} else if (typeof b === "number") {
 		return -1;
-	} else if (a > b) {
-		return 1;
 	}
 
-	return 0;
+	return comparePartialStrings(a, b);
 }

package/src/core/schema-stored/formatV1.ts

@@ -52,6 +52,7 @@ const FieldSchemaFormatBase = Type.Object({
 
 const noAdditionalProps: ObjectOptions = { additionalProperties: false };
 
+export type FieldSchemaFormat = Static<typeof FieldSchemaFormat>;
 export const FieldSchemaFormat = Type.Composite([FieldSchemaFormatBase], noAdditionalProps);
 
 /**
@@ -70,6 +71,7 @@ export enum PersistedValueSchema {
  *
  * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
  */
+export type TreeNodeSchemaDataFormat = Static<typeof TreeNodeSchemaDataFormat>;
 export const TreeNodeSchemaDataFormat = Type.Object(
 	{
 		/**
@@ -87,7 +89,3 @@ export const TreeNodeSchemaDataFormat = Type.Object(
 	},
 	unionOptions,
 );
-
-export type TreeNodeSchemaDataFormat = Static<typeof TreeNodeSchemaDataFormat>;
-
-export type FieldSchemaFormat = Static<typeof FieldSchemaFormat>;

package/src/core/schema-stored/formatV2.ts

@@ -6,6 +6,7 @@
 import { type ObjectOptions, type Static, Type } from "@sinclair/typebox";
 
 import { unionOptions } from "../../codec/index.js";
+import type { JsonCompatibleReadOnlyObject } from "../../util/index.js";
 import { JsonCompatibleReadOnlySchema } from "../../util/index.js";
 
 import {
@@ -14,7 +15,12 @@ import {
 	TreeNodeSchemaIdentifierSchema,
 } from "./formatV1.js";
 
-export const PersistedMetadataFormat = Type.Optional(JsonCompatibleReadOnlySchema);
+export type PersistedMetadataFormat = Static<typeof PersistedMetadataFormat>;
+export const PersistedMetadataFormat = Type.Optional(
+	Type.Unsafe<JsonCompatibleReadOnlyObject>(
+		Type.Record(Type.String(), JsonCompatibleReadOnlySchema),
+	),
+);
 
 const FieldSchemaFormatBase = Type.Object({
 	kind: FieldKindIdentifierSchema,
@@ -24,6 +30,7 @@ const FieldSchemaFormatBase = Type.Object({
 
 const noAdditionalProps: ObjectOptions = { additionalProperties: false };
 
+export type FieldSchemaFormat = Static<typeof FieldSchemaFormat>;
 export const FieldSchemaFormat = Type.Composite([FieldSchemaFormatBase], noAdditionalProps);
 
 /**
@@ -56,6 +63,7 @@ export type TreeNodeSchemaUnionFormat = Static<typeof TreeNodeSchemaUnionFormat>
  *
  * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
  */
+export type TreeNodeSchemaDataFormat = Static<typeof TreeNodeSchemaDataFormat>;
 export const TreeNodeSchemaDataFormat = Type.Object(
 	{
 		/**
@@ -71,9 +79,3 @@ export const TreeNodeSchemaDataFormat = Type.Object(
 	},
 	noAdditionalProps,
 );
-
-export type TreeNodeSchemaDataFormat = Static<typeof TreeNodeSchemaDataFormat>;
-
-export type FieldSchemaFormat = Static<typeof FieldSchemaFormat>;
-
-export type PersistedMetadataFormat = Static<typeof PersistedMetadataFormat>;

package/src/core/schema-stored/index.ts

@@ -37,6 +37,8 @@ export { Multiplicity } from "./multiplicity.js";
 export type { TreeNodeSchemaIdentifier, FieldKey, FieldKindIdentifier } from "./formatV1.js";
 
 import * as schemaFormatV1 from "./formatV1.js";
+// eslint-disable-next-line unicorn/prefer-export-from -- fixing requires `export * as` (breaks API-Extractor) or named exports (changes public API)
 export { schemaFormatV1 };
 import * as schemaFormatV2 from "./formatV2.js";
+// eslint-disable-next-line unicorn/prefer-export-from -- fixing requires `export * as` (breaks API-Extractor) or named exports (changes public API)
 export { schemaFormatV2 };

package/src/core/schema-stored/schema.ts

@@ -253,7 +253,10 @@ export class ObjectNodeStoredSchema extends TreeNodeStoredSchema {
 	private encodeFieldsObject(
 		encodeFieldSchema: (storedFieldSchema: TreeFieldStoredSchema) => FieldSchemaFormat,
 	): Record<string, FieldSchemaFormat> {
-		const fieldsObject: Record<string, FieldSchemaFormat> = Object.create(null);
+		const fieldsObject: Record<string, FieldSchemaFormat> = Object.create(null) as Record<
+			string,
+			FieldSchemaFormat
+		>;
 		// Sort fields to ensure output is identical for for equivalent schema (since field order is not considered significant).
 		// This makes comparing schema easier, and ensures chunk reuse for schema summaries isn't needlessly broken.
 		for (const key of [...this.objectNodeFields.keys()].sort()) {

package/src/core/tree/anchorSet.ts

@@ -128,9 +128,7 @@ export interface AnchorEvents {
 	 *
 	 * Compare to {@link AnchorEvents.childrenChanged} which is emitted in the middle of the batch/delta-visit.
 	 */
-	childrenChangedAfterBatch(arg: {
-		changedFields: ReadonlySet<FieldKey>;
-	}): void;
+	childrenChangedAfterBatch(arg: { changedFields: ReadonlySet<FieldKey> }): void;
 
 	/**
 	 * Emitted in the middle of applying a batch of changes (i.e. during a delta a visit), if something in the subtree

package/src/core/tree/delta.ts

@@ -196,10 +196,12 @@ export interface DetachedNodeRename {
 	readonly newId: DetachedNodeId;
 }
 
-/**
- * Represents a list of changes to the nodes in the field.
- * The index of each mark within the range of nodes, before
- * applying any of the changes, is not represented explicitly.
- * It corresponds to the sum of `mark.count` values for all previous marks for which `isAttachMark(mark)` is false.
- */
-export type FieldChanges = readonly Mark[];
+export interface FieldChanges {
+	/**
+	 * Represents a list of changes to the nodes in the field.
+	 * The index of each mark within the range of nodes, before
+	 * applying any of the changes, is not represented explicitly.
+	 * It corresponds to the sum of `mark.count` values for all previous marks for which `isAttachMark(mark)` is false.
+	 */
+	readonly marks: readonly Mark[];
+}

package/src/core/tree/deltaUtil.ts

@@ -20,7 +20,7 @@ export function deltaForRootInitialization(content: TreeChunk): Root {
 	const delta: Root = {
 		build: [{ id: buildId, trees: content }],
 		fields: new Map<FieldKey, FieldChanges>([
-			[rootFieldKey, [{ count: content.topLevelLength, attach: buildId }]],
+			[rootFieldKey, { marks: [{ count: content.topLevelLength, attach: buildId }] }],
 		]),
 	};
 	return delta;

package/src/core/tree/visitDelta.ts

@@ -402,7 +402,7 @@ function detachPass(
 	config: PassConfig,
 ): void {
 	let index = 0;
-	for (const mark of fieldChanges) {
+	for (const mark of fieldChanges.marks) {
 		if (mark.fields !== undefined) {
 			assert(
 				mark.attach === undefined || mark.detach !== undefined,
@@ -512,7 +512,7 @@ function attachPass(
 	config: PassConfig,
 ): void {
 	let index = 0;
-	for (const mark of fieldChanges) {
+	for (const mark of fieldChanges.marks) {
 		if (mark.attach !== undefined) {
 			for (let i = 0; i < mark.count; i += 1) {
 				const offsetAttachId = offsetDetachId(mark.attach, i);