@fluidframework/tree 2.101.0 → 2.102.0

package/src/codec/versioned/codec.ts

@@ -48,14 +48,15 @@ function makeVersionedCodec<
 	TDecoded,
 	TEncoded extends Versioned = VersionedJson,
 	TValidate = TEncoded,
-	TContext = void,
+	TEncodeContext = void,
+	TDecodeContext = TEncodeContext,
 >(
 	supportedVersions: Set<FormatVersion>,
 	{ jsonValidator: validator }: ICodecOptions,
-	inner: IJsonCodec<TDecoded, TEncoded, TValidate, TContext>,
-): IJsonCodec<TDecoded, TEncoded, TValidate, TContext> {
+	inner: IJsonCodec<TDecoded, TEncoded, TValidate, TEncodeContext, TDecodeContext>,
+): IJsonCodec<TDecoded, TEncoded, TValidate, TEncodeContext, TDecodeContext> {
 	const codec = {
-		encode: (data: TDecoded, context: TContext): TEncoded => {
+		encode: (data: TDecoded, context: TEncodeContext): TEncoded => {
 			const encoded = inner.encode(data, context);
 			assert(
 				supportedVersions.has(encoded.version),
@@ -63,7 +64,7 @@ function makeVersionedCodec<
 			);
 			return encoded;
 		},
-		decode: (data: TValidate, context: TContext): TDecoded => {
+		decode: (data: TValidate, context: TDecodeContext): TDecoded => {
 			const versioned = data as Versioned; // Validated by withSchemaValidation
 			if (!supportedVersions.has(versioned.version)) {
 				throw new UsageError(
@@ -96,14 +97,15 @@ function makeVersionedValidatedCodec<
 	TDecoded,
 	TEncoded extends Versioned = VersionedJson,
 	TValidate = TEncoded,
-	TContext = void,
+	TEncodeContext = void,
+	TDecodeContext = TEncodeContext,
 >(
 	options: ICodecOptions,
 	supportedVersions: Set<FormatVersion>,
 	schema: EncodedSchema,
-	codec: IJsonCodec<TDecoded, TEncoded, TValidate, TContext>,
-): IJsonCodec<TDecoded, TEncoded, TValidate, TContext> &
-	Pick<CodecAndSchema<TDecoded, TContext>, "schema"> {
+	codec: IJsonCodec<TDecoded, TEncoded, TValidate, TEncodeContext, TDecodeContext>,
+): IJsonCodec<TDecoded, TEncoded, TValidate, TEncodeContext, TDecodeContext> &
+	Pick<CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext>, "schema"> {
 	return {
 		...makeVersionedCodec(
 			supportedVersions,
@@ -119,12 +121,11 @@ function makeVersionedValidatedCodec<
  */
 export function makeDiscontinuedCodecAndSchema<
 	TDecoded,
-	TContext,
 	TFormatVersion extends FormatVersion = FormatVersion,
 >(
 	discontinuedVersion: TFormatVersion,
 	discontinuedSince: SemanticVersion,
-): CodecVersion<TDecoded, TContext, TFormatVersion> {
+): CodecVersion<TDecoded, unknown, TFormatVersion, ICodecOptions, unknown> {
 	return {
 		minVersionForCollab: undefined,
 		formatVersion: discontinuedVersion,
@@ -150,9 +151,19 @@ export function makeDiscontinuedCodecAndSchema<
  * The codec should not perform its own schema validation.
  * The schema validation gets added when normalizing to {@link NormalizedCodecVersion}.
  */
-export type CodecAndSchema<TDecoded, TContext = void> = {
+export type CodecAndSchema<
+	TDecoded,
+	TEncodeContext = void,
+	TDecodeContext = TEncodeContext,
+> = {
 	readonly schema: TSchema;
-} & IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>;
+} & IJsonCodec<
+	TDecoded,
+	VersionedJson,
+	JsonCompatibleReadOnly,
+	TEncodeContext,
+	TDecodeContext
+>;
 
 /**
  * A codec alongside its format version and schema.
@@ -183,12 +194,13 @@ export interface CodecVersionBase<
  */
 export interface CodecVersion<
 	TDecoded,
-	TContext,
+	TEncodeContext,
 	TFormatVersion extends FormatVersion,
 	TBuildOptions extends ICodecOptions = ICodecOptions,
+	TDecodeContext = TEncodeContext,
 > extends CodecVersionBase<
-		| CodecAndSchema<TDecoded, TContext>
-		| ((options: TBuildOptions) => CodecAndSchema<TDecoded, TContext>),
+		| CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext>
+		| ((options: TBuildOptions) => CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext>),
 		TFormatVersion
 	> {}
 
@@ -200,21 +212,29 @@ export interface CodecVersion<
  */
 export interface NormalizedCodecVersion<
 	TDecoded,
-	TContext,
+	TEncodeContext,
 	TFormatVersion extends FormatVersion,
 	TBuildOptions extends ICodecOptions,
+	TDecodeContext = TEncodeContext,
 > extends CodecVersionBase<
-		(options: TBuildOptions) => CodecAndSchema<TDecoded, TContext>,
+		(options: TBuildOptions) => CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext>,
 		TFormatVersion
 	> {}
 
 /**
  * {@link NormalizedCodecVersion} after applying the build options.
  * @remarks
- * Produced by {@link ClientVersionDispatchingCodecBuilder.applyOptions}.
+ * Produced by {@link VersionDispatchingCodecBuilder.applyOptions}.
  */
-interface EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion extends FormatVersion>
-	extends CodecVersionBase<CodecAndSchema<TDecoded, TContext>, TFormatVersion> {}
+interface EvaluatedCodecVersion<
+	TDecoded,
+	TEncodeContext,
+	TFormatVersion extends FormatVersion,
+	TDecodeContext = TEncodeContext,
+> extends CodecVersionBase<
+		CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext>,
+		TFormatVersion
+	> {}
 
 /**
  * Normalize the codec to a single format.
@@ -223,17 +243,34 @@ interface EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion extends Forma
  */
 function normalizeCodecVersion<
 	TDecoded,
-	TContext,
+	TEncodeContext,
 	TFormatVersion extends FormatVersion,
 	TBuildOptions extends ICodecOptions,
+	TDecodeContext = TEncodeContext,
 >(
-	codecVersion: CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>,
-): NormalizedCodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions> {
-	const codecBuilder: (options: TBuildOptions) => CodecAndSchema<TDecoded, TContext> =
+	codecVersion: CodecVersion<
+		TDecoded,
+		TEncodeContext,
+		TFormatVersion,
+		TBuildOptions,
+		TDecodeContext
+	>,
+): NormalizedCodecVersion<
+	TDecoded,
+	TEncodeContext,
+	TFormatVersion,
+	TBuildOptions,
+	TDecodeContext
+> {
+	const codecBuilder: (
+		options: TBuildOptions,
+	) => CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext> =
 		typeof codecVersion.codec === "function"
 			? codecVersion.codec
-			: () => codecVersion.codec as CodecAndSchema<TDecoded, TContext>;
-	const codec = (options: TBuildOptions): CodecAndSchema<TDecoded, TContext> => {
+			: () => codecVersion.codec as CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext>;
+	const codec = (
+		options: TBuildOptions,
+	): CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext> => {
 		const built = codecBuilder(options);
 		return makeVersionedValidatedCodec(
 			options,
@@ -251,27 +288,59 @@ function normalizeCodecVersion<
 }
 
 /**
- * Creates a codec which dispatches to the appropriate member of a codec family based on the `minVersionForCollab` for encode and the
- * version number in data it encounters for decode.
+ * A codec that can read multiple format versions and write a single selected version.
+ * @remarks
+ * Produced by {@link VersionDispatchingCodecBuilder.build}.
+ *
+ * @typeParam TDecoded - The in memory (not encoded) format.
+ * @typeParam TEncodeContext - Context type passed to encode operations.
+ * @typeParam TFormatVersion - The type of format version identifiers used by this codec.
+ * @typeParam TDecodeContext - Context type passed to decode operations. Defaults to `TEncodeContext`.
+ */
+export interface VersionDispatchingCodec<
+	TDecoded,
+	TEncodeContext,
+	TFormatVersion extends FormatVersion,
+	TDecodeContext = TEncodeContext,
+> extends IJsonCodec<
+		TDecoded,
+		JsonCompatibleReadOnly,
+		JsonCompatibleReadOnly,
+		TEncodeContext,
+		TDecodeContext
+	> {
+	/**
+	 * The format version which this codec writes.
+	 * @remarks
+	 * Selected by {@link VersionDispatchingCodecBuilder.build} based on the provided options.
+	 */
+	readonly writeVersion: TFormatVersion;
+}
+
+/**
+ * Creates a {@link VersionDispatchingCodec} using a {@link CodecVersion} to select the {@link VersionDispatchingCodec.writeVersion}.
  * @privateRemarks
- * This is a two stage builder so the first stage can encapsulate all codec specific details and the second can bring in configuration.
+ * This is a two stage builder so the first stage (the static build) can encapsulate all codec specific details and
+ * the second (the instance build) can bring in configuration.
  */
-export class ClientVersionDispatchingCodecBuilder<
+export class VersionDispatchingCodecBuilder<
 	TBuildOptions extends ICodecOptions = ICodecOptions,
 	TDecoded = unknown,
-	TContext = unknown,
+	TEncodeContext = unknown,
 	TFormatVersion extends FormatVersion = FormatVersion,
 	TName extends CodecName = string,
+	TDecodeContext = TEncodeContext,
 > {
 	public readonly registry: readonly NormalizedCodecVersion<
 		TDecoded,
-		TContext,
+		TEncodeContext,
 		TFormatVersion,
-		TBuildOptions
+		TBuildOptions,
+		TDecodeContext
 	>[];
 
 	/**
-	 * Use {@link ClientVersionDispatchingCodecBuilder.build} to create an instance of this class.
+	 * Use {@link VersionDispatchingCodecBuilder.build} to create an instance of this class.
 	 * @remarks
 	 * Inputs to this are assumed to be constants in the code controlled by the developers of this package,
 	 * and constructed at least once during tests.
@@ -286,13 +355,20 @@ export class ClientVersionDispatchingCodecBuilder<
 		/**
 		 * The registry of codecs which this builder can use to encode and decode data.
 		 */
-		inputRegistry: readonly CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>[],
+		inputRegistry: readonly CodecVersion<
+			TDecoded,
+			TEncodeContext,
+			TFormatVersion,
+			TBuildOptions,
+			TDecodeContext
+		>[],
 	) {
 		type Normalized = NormalizedCodecVersion<
 			TDecoded,
-			TContext,
+			TEncodeContext,
 			TFormatVersion,
-			TBuildOptions
+			TBuildOptions,
+			TDecodeContext
 		>;
 		const normalizedRegistry: Normalized[] = [];
 		const formats: Set<FormatVersion> = new Set();
@@ -333,14 +409,14 @@ export class ClientVersionDispatchingCodecBuilder<
 	}
 
 	/**
-	 * Applies the provided options to the codec registry to produce a list of evaluated codecs.
+	 * Applies `options` to the codec registry to produce a list of evaluated codecs.
 	 * @remarks
 	 * This is used by build, which is what production code should use.
 	 * This is only exposed for testing purposes.
 	 */
 	public applyOptions(
 		options: TBuildOptions,
-	): EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>[] {
+	): EvaluatedCodecVersion<TDecoded, TEncodeContext, TFormatVersion, TDecodeContext>[] {
 		return this.registry.map((codec) => ({
 			minVersionForCollab: codec.minVersionForCollab,
 			formatVersion: codec.formatVersion,
@@ -349,26 +425,17 @@ export class ClientVersionDispatchingCodecBuilder<
 	}
 
 	/**
-	 * Produce a single codec which can read any supported format, and writes a version selected based on the provided options.
+	 * Builds a complete {@link VersionDispatchingCodec} that can decode all registered versions
+	 * and encode a version selected by the provided options.
 	 */
-	public build(options: TBuildOptions & CodecWriteOptions): IJsonCodec<
-		TDecoded,
-		JsonCompatibleReadOnly,
-		JsonCompatibleReadOnly,
-		TContext
-	> & {
-		/**
-		 * The format version which this codec writes.
-		 * @remarks
-		 * This is selected based on the provided {@link CodecWriteOptions}.
-		 */
-		readonly writeVersion: TFormatVersion;
-	} {
+	public build(
+		options: TBuildOptions & CodecWriteOptions,
+	): VersionDispatchingCodec<TDecoded, TEncodeContext, TFormatVersion, TDecodeContext> {
 		const [applied, decoder] = this.buildDecoderInternal(options);
 		const writeVersion = getWriteVersion(this.name, options, applied);
 		return {
 			...decoder,
-			encode: (data: TDecoded, context: TContext): JsonCompatibleReadOnly => {
+			encode: (data: TDecoded, context: TEncodeContext): JsonCompatibleReadOnly => {
 				return writeVersion.codec.encode(data, context);
 			},
 			writeVersion: writeVersion.formatVersion,
@@ -378,21 +445,27 @@ export class ClientVersionDispatchingCodecBuilder<
 	private buildDecoderInternal(
 		options: TBuildOptions,
 	): [
-		EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>[],
+		EvaluatedCodecVersion<TDecoded, TEncodeContext, TFormatVersion, TDecodeContext>[],
 		Pick<
-			IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,
+			IJsonCodec<
+				TDecoded,
+				JsonCompatibleReadOnly,
+				JsonCompatibleReadOnly,
+				TEncodeContext,
+				TDecodeContext
+			>,
 			"decode"
 		>,
 	] {
 		const applied = this.applyOptions(options);
 		const fromFormatVersion = new Map<
 			FormatVersion,
-			EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>
+			EvaluatedCodecVersion<TDecoded, TEncodeContext, TFormatVersion, TDecodeContext>
 		>(applied.map((codec) => [codec.formatVersion, codec]));
 		return [
 			applied,
 			{
-				decode: (data: JsonCompatibleReadOnly, context: TContext): TDecoded => {
+				decode: (data: JsonCompatibleReadOnly, context: TDecodeContext): TDecoded => {
 					const versioned = data as Partial<Versioned>;
 					const codec = fromFormatVersion.get(versioned.version);
 					if (codec === undefined) {
@@ -408,12 +481,19 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 	}
 
 	/**
-	 * Produce a single codec which can read any supported format.
+	 * Builds a decoder-only codec that can decode any supported format without encoding capability.
+	 *
+	 * @remarks
+	 * The returned codec contains only the `decode` method and can be used when only decoding is needed.
+	 * This is useful for scenarios where reading/decoding versioned data is sufficient.
+	 *
+	 * @param options - Build options (typically containing the `jsonValidator`)
+	 * @returns An object with a `decode` method that can handle any supported format version
 	 */
 	public buildDecoder(
 		options: TBuildOptions,
 	): Pick<
-		IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,
+		VersionDispatchingCodec<TDecoded, TEncodeContext, TFormatVersion, TDecodeContext>,
 		"decode"
 	> {
 		return this.buildDecoderInternal(options)[1];
@@ -429,42 +509,62 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 	}
 
 	/**
-	 * Builds a ClientVersionDispatchingCodecBuilder from the provided registry.
+	 * Creates a new VersionDispatchingCodecBuilder from the provided codec registry.
+	 *
 	 * @remarks
 	 * This static method infers the types of the builder from the provided registry,
 	 * making it easier to create builders without needing to explicitly specify all type parameters.
 	 * This gets better type inference than the constructor.
+	 *
+	 * @example
+	 * ```typescript
+	 * const builder = VersionDispatchingCodecBuilder.build('myCodec', [
+	 *   { minVersionForCollab: lowestMinVersionForCollab, formatVersion: 1, codec: { encode, decode, schema } },
+	 *   { minVersionForCollab: '2.100.0', formatVersion: 2, codec: { encode, decode, schema } },
+	 * ]);
+	 * ```
 	 */
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	public static build<
 		Name extends CodecName,
-		Entry extends CodecVersion<unknown, unknown, FormatVersion, never>,
+		Entry extends CodecVersion<unknown, unknown, FormatVersion, never, unknown>,
 	>(name: Name, inputRegistry: readonly 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;
+			Entry extends CodecVersion<infer D, unknown, FormatVersion, never, unknown> ? D : never;
+		type TEncodeContext2 =
+			Entry extends CodecVersion<unknown, infer C, FormatVersion, never, unknown> ? C : never;
 		type TFormatVersion2 =
-			Entry extends CodecVersion<unknown, unknown, infer F, never> ? F : never;
+			Entry extends CodecVersion<unknown, unknown, infer F, never, unknown> ? F : never;
 		type TBuildOptions2 =
-			Entry extends CodecVersion<unknown, unknown, FormatVersion, infer B> ? B : never;
+			Entry extends CodecVersion<unknown, unknown, FormatVersion, infer B, unknown>
+				? B
+				: never;
+		type TDecodeContext2 =
+			Entry extends CodecVersion<unknown, unknown, FormatVersion, never, infer D> ? D : never;
+
+		type ResolvedEncodeContext = unknown extends TEncodeContext2 ? void : TEncodeContext2;
+		type ResolvedDecodeContext = unknown extends TDecodeContext2
+			? ResolvedEncodeContext
+			: TDecodeContext2;
 
 		type CodecFinal = CodecVersion<
 			TDecoded2,
 			// If it does not matter what context is provided, undefined is fine, so allow it to be omitted.
-			unknown extends TContext2 ? void : TContext2,
+			ResolvedEncodeContext,
 			TFormatVersion2,
-			TBuildOptions2
+			TBuildOptions2,
+			ResolvedDecodeContext
 		>;
 
 		const input = inputRegistry as readonly unknown[] as readonly CodecFinal[];
 
-		const builder = new ClientVersionDispatchingCodecBuilder<
+		const builder = new VersionDispatchingCodecBuilder<
 			TBuildOptions2,
 			TDecoded2,
-			unknown extends TContext2 ? void : TContext2,
+			ResolvedEncodeContext,
 			TFormatVersion2,
-			Name
+			Name,
+			ResolvedDecodeContext
 		>(name, input);
 		return builder;
 	}

package/src/codec/versioned/index.ts

@@ -6,7 +6,8 @@
 export { Versioned, versionField } from "./format.js";
 export {
 	makeDiscontinuedCodecAndSchema,
-	ClientVersionDispatchingCodecBuilder,
+	VersionDispatchingCodecBuilder,
+	type VersionDispatchingCodec,
 	type CodecVersion,
 	type CodecAndSchema,
 } from "./codec.js";

package/src/core/tree/deltaUtil.ts

@@ -60,7 +60,7 @@ export function areDetachedNodeIdsEqual(a: DetachedNodeId, b: DetachedNodeId): b
 }
 
 /**
- * Returns true if a delta field map contains any changes that would be visible in the document (eg, an insert, move, edit)
+ * Returns true if a delta field map contains any changes that would be visible in the document (i.e., a detach or an attach)
  * @param fields - Delta FieldMap to check for visible changes
  * @returns True if change map contains any changes that would be visible in the document, false otherwise
  */
@@ -77,7 +77,7 @@ export function deltaFieldMapHasVisibleChanges(fields: FieldMap | undefined): bo
 }
 
 /**
- * Returns true if the given field changes contains any changes that would be visible in the document (eg, an insert, move, edit)
+ * Returns true if the given field changes contains any changes that would be visible in the document (i.e., a detach or an attach)
  * @param fieldChanges - Field changes to check for visible changes
  * @returns True if the field changes contain any changes that would be visible in the document, false otherwise
  */

package/src/core/tree/detachedFieldIndexCodecV1.ts

@@ -5,6 +5,7 @@
 
 import { assert } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
+import { isFinalId } from "@fluidframework/id-compressor/internal";
 
 import type { CodecAndSchema, IJsonCodec } from "../../codec/index.js";
 import { brand } from "../../util/index.js";
@@ -46,7 +47,7 @@ class MajorCodec implements IJsonCodec<Major, EncodedRevisionTag> {
 		 * The assert below will fail in such a scenario. This is addressed in the v2 codec.
 		 */
 		assert(
-			id === "root" || id >= 0,
+			id === "root" || isFinalId(id),
 			0x88f /* Expected final id on encode of detached field index revision */,
 		);
 		return id;
@@ -54,7 +55,7 @@ class MajorCodec implements IJsonCodec<Major, EncodedRevisionTag> {
 
 	public decode(major: EncodedRevisionTag): RevisionTag {
 		assert(
-			major === "root" || major >= 0,
+			major === "root" || isFinalId(major),
 			0x890 /* Expected final id on decode of detached field index revision */,
 		);
 		return this.revisionTagCodec.decode(major, {

package/src/core/tree/detachedFieldIndexCodecV2.ts

@@ -5,7 +5,7 @@
 
 import { assert } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor, StableId } from "@fluidframework/id-compressor";
-import { isStableId } from "@fluidframework/id-compressor/internal";
+import { isFinalId, isStableId } from "@fluidframework/id-compressor/internal";
 
 import type { CodecAndSchema, IJsonCodec } from "../../codec/index.js";
 import type { EncodedRevisionTag, RevisionTagCodec, RevisionTag } from "../rebase/index.js";
@@ -25,7 +25,7 @@ class MajorCodec implements IJsonCodec<Major> {
 		assert(major !== undefined, 0xbfb /* Unexpected undefined revision */);
 		const id = this.revisionTagCodec.encode(major);
 
-		if (id !== "root" && id < 0) {
+		if (id !== "root" && !isFinalId(id)) {
 			/**
 			 * This code path handles the case where the major revision is not finalized.
 			 * This can happen the SharedTree is being attached to an already attached container.
@@ -39,7 +39,9 @@ class MajorCodec implements IJsonCodec<Major> {
 
 	public decode(major: EncodedRevisionTag | StableId): RevisionTag {
 		assert(
-			major === "root" || (typeof major === "string" && isStableId(major)) || major >= 0,
+			major === "root" ||
+				(typeof major === "string" && isStableId(major)) ||
+				(typeof major === "number" && isFinalId(major)),
 			0xbfd /* Expected root, stable, or final compressed id */,
 		);
 		if (typeof major === "string" && isStableId(major)) {

package/src/core/tree/detachedFieldIndexCodecs.ts

@@ -7,7 +7,7 @@ import type { IIdCompressor } from "@fluidframework/id-compressor";
 import { lowestMinVersionForCollab } from "@fluidframework/runtime-utils/internal";
 
 import {
-	ClientVersionDispatchingCodecBuilder,
+	VersionDispatchingCodecBuilder,
 	FluidClientVersion,
 	type ICodecOptions,
 } from "../../codec/index.js";
@@ -22,7 +22,7 @@ type BuildData = ICodecOptions & {
 	readonly idCompressor: IIdCompressor;
 };
 
-export const detachedFieldIndexCodecBuilder = ClientVersionDispatchingCodecBuilder.build(
+export const detachedFieldIndexCodecBuilder = VersionDispatchingCodecBuilder.build(
 	"DetachedFieldIndex",
 	[
 		{