@fluidframework/tree 2.82.0 → 2.83.0

package/src/codec/versioned/codec.ts

@@ -3,11 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, debugAssert } from "@fluidframework/core-utils/internal";
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
 import {
 	getConfigForMinVersionForCollabIterable,
-	type ConfigMapEntry,
+	lowestMinVersionForCollab,
 	type MinimumMinorSemanticVersion,
 	type SemanticVersion,
 } from "@fluidframework/runtime-utils/internal";
@@ -27,9 +27,7 @@ import {
 	withSchemaValidation,
 	type FormatVersion,
 	type CodecWriteOptions,
-	type IMultiFormatCodec,
 	type CodecName,
-	ensureBinaryEncoding,
 	type CodecTree,
 } from "../codec.js";
 
@@ -151,7 +149,7 @@ export function makeVersionDispatchingCodec<TDecoded, TContext>(
 	family: ICodecFamily<TDecoded, TContext>,
 	options: ICodecOptions & { writeVersion: FormatVersion },
 ): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
-	const writeCodec = family.resolve(options.writeVersion).json;
+	const writeCodec = family.resolve(options.writeVersion);
 	const supportedVersions = new Set(family.getSupportedFormats());
 	return makeVersionedCodec(supportedVersions, options, {
 		encode(data, context): Versioned {
@@ -159,7 +157,7 @@ export function makeVersionDispatchingCodec<TDecoded, TContext>(
 		},
 		decode(data: Versioned, context) {
 			const codec = family.resolve(data.version);
-			return codec.json.decode(data, context);
+			return codec.decode(data, context);
 		},
 	});
 }
@@ -170,10 +168,9 @@ export function makeVersionDispatchingCodec<TDecoded, TContext>(
  * 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> = { readonly schema: TSchema } & (
-	| IMultiFormatCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>
-	| IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>
-);
+export type CodecAndSchema<TDecoded, TContext = void> = {
+	readonly schema: TSchema;
+} & IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>;
 
 /**
  * A codec alongside its format version and schema.
@@ -182,6 +179,14 @@ export interface CodecVersionBase<
 	T = unknown,
 	TFormatVersion extends FormatVersion = FormatVersion,
 > {
+	/**
+	 * When `undefined` the codec will never be selected as a write version except via override.
+	 * @remarks
+	 * This format will be used for decode if data in it needs to be decoded, regardless of `minVersionForCollab`.
+	 * `undefined` should be used for unstable codec versions (with string FormatVersions),
+	 * as well as previously stabilized formats that are discontinued (meaning we always prefer to use some other format for encoding).
+	 */
+	readonly minVersionForCollab: MinimumVersionForCollab | undefined;
 	readonly formatVersion: TFormatVersion;
 	readonly codec: T;
 }
@@ -228,11 +233,8 @@ export interface NormalizedCodecVersion<
  * @remarks
  * Produced by {@link ClientVersionDispatchingCodecBuilder.applyOptions}.
  */
-export interface EvaluatedCodecVersion<
-	TDecoded,
-	TContext,
-	TFormatVersion extends FormatVersion,
-> extends CodecVersionBase<
+interface EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion extends FormatVersion>
+	extends CodecVersionBase<
 		IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>,
 		TFormatVersion
 	> {}
@@ -258,17 +260,16 @@ function normalizeCodecVersion<
 		options: TBuildOptions,
 	): IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext> => {
 		const built = codecBuilder(options);
-		// We currently don't expose or use binary formats, but someday we might.
-		const multiFormat = ensureBinaryEncoding<TDecoded, TContext, VersionedJson>(built);
 		return makeVersionedValidatedCodec(
 			options,
 			new Set([codecVersion.formatVersion]),
 			built.schema,
-			multiFormat.json,
+			built,
 		);
 	};
 
 	return {
+		minVersionForCollab: codecVersion.minVersionForCollab,
 		formatVersion: codecVersion.formatVersion,
 		codec,
 	};
@@ -287,13 +288,20 @@ export class ClientVersionDispatchingCodecBuilder<
 	TFormatVersion extends FormatVersion,
 	TBuildOptions extends CodecWriteOptions,
 > {
-	public readonly registry: ReadonlyMap<
-		MinimumVersionForCollab,
-		NormalizedCodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>
-	>;
+	public readonly registry: readonly NormalizedCodecVersion<
+		TDecoded,
+		TContext,
+		TFormatVersion,
+		TBuildOptions
+	>[];
 
 	/**
 	 * Use {@link ClientVersionDispatchingCodecBuilder.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.
+	 * Because of this, the validation of these inputs done with debugAssert should be sufficient,
+	 * and using debugAssert avoids bloating the bundle size for production users.
 	 */
 	private constructor(
 		/**
@@ -303,9 +311,7 @@ export class ClientVersionDispatchingCodecBuilder<
 		/**
 		 * The registry of codecs which this builder can use to encode and decode data.
 		 */
-		inputRegistry: ConfigMapEntry<
-			CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>
-		>,
+		inputRegistry: readonly CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>[],
 	) {
 		type Normalized = NormalizedCodecVersion<
 			TDecoded,
@@ -313,18 +319,41 @@ export class ClientVersionDispatchingCodecBuilder<
 			TFormatVersion,
 			TBuildOptions
 		>;
-		const normalizedRegistry = new Map<MinimumVersionForCollab, Normalized>();
-
-		for (const [minVersionForCollab, codec] of Object.entries(inputRegistry) as Iterable<
-			[
-				MinimumVersionForCollab,
-				CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>,
-			]
-		>) {
+		const normalizedRegistry: Normalized[] = [];
+		const formats: Set<FormatVersion> = new Set();
+		const versions: Set<string | undefined> = new Set();
+
+		for (const codec of inputRegistry) {
+			debugAssert(
+				() =>
+					!formats.has(codec.formatVersion) ||
+					`duplicate codec format ${name} ${codec.formatVersion}`,
+			);
+			debugAssert(
+				() =>
+					codec.minVersionForCollab === undefined ||
+					typeof codec.formatVersion !== "string" ||
+					`unstable format ${JSON.stringify(codec.formatVersion)} (string formats) must not have a minVersionForCollab in ${name}`,
+			);
+			formats.add(codec.formatVersion);
 			const normalizedCodec = normalizeCodecVersion(codec);
-			normalizedRegistry.set(minVersionForCollab, normalizedCodec);
+			normalizedRegistry.push(normalizedCodec);
+			if (codec.minVersionForCollab !== undefined) {
+				debugAssert(
+					() =>
+						!versions.has(codec.minVersionForCollab) ||
+						`Codec ${name} has multiple entries for version ${JSON.stringify(codec.minVersionForCollab)}`,
+				);
+				versions.add(codec.minVersionForCollab);
+			}
 		}
 
+		debugAssert(
+			() =>
+				versions.has(lowestMinVersionForCollab) ||
+				`Codec ${name} is missing entry for lowestMinVersionForCollab`,
+		);
+
 		this.registry = normalizedRegistry;
 	}
 
@@ -336,18 +365,12 @@ export class ClientVersionDispatchingCodecBuilder<
 	 */
 	public applyOptions(
 		options: TBuildOptions,
-	): [MinimumVersionForCollab, EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>][] {
-		return Array.from(
-			this.registry,
-			([version, codec]) =>
-				[
-					version,
-					{
-						formatVersion: codec.formatVersion,
-						codec: codec.codec(options),
-					},
-				] as const,
-		);
+	): EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>[] {
+		return this.registry.map((codec) => ({
+			minVersionForCollab: codec.minVersionForCollab,
+			formatVersion: codec.formatVersion,
+			codec: codec.codec(options),
+		}));
 	}
 
 	/**
@@ -361,7 +384,7 @@ export class ClientVersionDispatchingCodecBuilder<
 		const fromFormatVersion = new Map<
 			FormatVersion,
 			EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>
-		>(applied.map(([_version, codec]) => [codec.formatVersion, codec]));
+		>(applied.map((codec) => [codec.formatVersion, codec]));
 		return {
 			encode: (data: TDecoded, context: TContext): JsonCompatibleReadOnly => {
 				return writeVersion.codec.encode(data, context);
@@ -382,7 +405,7 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 
 	public getCodecTree(clientVersion: MinimumVersionForCollab): CodecTree {
 		// TODO: add support for children codecs.
-		const selected = getConfigForMinVersionForCollabIterable(clientVersion, this.registry);
+		const selected = getWriteVersionNoOverrides(this.registry, clientVersion);
 		return {
 			name: this.name,
 			version: selected.formatVersion,
@@ -400,7 +423,7 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 	public static build<
 		Name extends CodecName,
 		Entry extends CodecVersion<unknown, unknown, FormatVersion, never>,
-	>(name: Name, inputRegistry: ConfigMapEntry<Entry>) {
+	>(name: Name, inputRegistry: readonly Entry[]) {
 		type TDecoded2 =
 			Entry extends CodecVersion<infer D, unknown, FormatVersion, never> ? D : never;
 		type TContext2 =
@@ -409,18 +432,24 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 			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.
-					unknown extends TContext2 ? void : TContext2,
-					TFormatVersion2,
-					TBuildOptions2
-				>
-			>,
-		);
+
+		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,
+			TFormatVersion2,
+			TBuildOptions2
+		>;
+
+		const input = inputRegistry as readonly unknown[] as readonly CodecFinal[];
+
+		const builder = new ClientVersionDispatchingCodecBuilder<
+			Name,
+			TDecoded2,
+			unknown extends TContext2 ? void : TContext2,
+			TFormatVersion2,
+			TBuildOptions2
+		>(name, input);
 		return builder;
 	}
 }
@@ -433,39 +462,51 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 function getWriteVersion<T extends CodecVersionBase>(
 	name: CodecName,
 	options: CodecWriteOptions,
-	versions: readonly [MinimumMinorSemanticVersion | MinimumVersionForCollab, T][],
+	versions: readonly T[],
 ): T {
 	if (options.writeVersionOverrides?.has(name) === true) {
 		const selectedFormatVersion = options.writeVersionOverrides.get(name);
-		const selected = versions.find(
-			([_v, codec]) => codec.formatVersion === selectedFormatVersion,
-		);
+		const selected = versions.find((codec) => codec.formatVersion === selectedFormatVersion);
 		if (selected === undefined) {
 			throw new UsageError(
-				`Codec "${name}" does not support requested format version ${selectedFormatVersion}. Supported versions are: ${versionList(versions)}.`,
+				`Codec "${name}" does not support requested format version ${JSON.stringify(selectedFormatVersion)}. Supported versions are: ${versionList(versions)}.`,
 			);
 		} else if (options.allowPossiblyIncompatibleWriteVersionOverrides !== true) {
-			const selectedMinVersionForCollab = selected[0];
-			// Currently all versions must specify a minVersionForCollab, so undefined is not expected here.
-			// TODO: It should be possible to have a version which would never be automatically selected for write (and thus does not have or need a minVersionForCollab), but can be selected via override.
-			// Use-cases for this include experimental versions not yet stable, and discontinued or intermediate versions which are mainly being kept for read compatibility but still support writing (perhaps for round-trip testing).
-			// For now, this check should never pass, and there is no way to create such a version yet.
+			const selectedMinVersionForCollab = selected.minVersionForCollab;
 			if (selectedMinVersionForCollab === undefined) {
 				throw new UsageError(
-					`Codec "${name}" does not support requested format version ${selectedFormatVersion} because it does not specify a minVersionForCollab. Use "allowPossiblyIncompatibleWriteVersionOverrides" to suppress this error if appropriate.`,
+					`Codec "${name}" does not support requested format version ${JSON.stringify(selectedFormatVersion)} because it has minVersionForCollab undefined. Use "allowPossiblyIncompatibleWriteVersionOverrides" to suppress this error if appropriate.`,
 				);
 			} else if (gt(selectedMinVersionForCollab, options.minVersionForCollab)) {
 				throw new UsageError(
-					`Codec "${name}" does not support requested format version ${selectedFormatVersion} because it is only compatible back to client version ${selectedMinVersionForCollab} and the requested oldest compatible client was ${options.minVersionForCollab}. Use "allowPossiblyIncompatibleWriteVersionOverrides" to suppress this error if appropriate.`,
+					`Codec "${name}" does not support requested format version ${JSON.stringify(selectedFormatVersion)} because it is only compatible back to client version ${selectedMinVersionForCollab} and the requested oldest compatible client was ${options.minVersionForCollab}. Use "allowPossiblyIncompatibleWriteVersionOverrides" to suppress this error if appropriate.`,
 				);
 			}
 		}
 
-		return selected[1];
+		return selected;
 	}
+
+	return getWriteVersionNoOverrides(versions, options.minVersionForCollab);
+}
+
+/**
+ * Selects which format should be used when writing data, without consider overrides.
+ */
+function getWriteVersionNoOverrides<T extends CodecVersionBase>(
+	versions: readonly T[],
+	minVersionForCollab: MinimumVersionForCollab,
+): T {
+	const stableVersions: [MinimumMinorSemanticVersion | MinimumVersionForCollab, T][] = [];
+	for (const version of versions) {
+		if (version.minVersionForCollab !== undefined) {
+			stableVersions.push([version.minVersionForCollab, version]);
+		}
+	}
+
 	const result: T = getConfigForMinVersionForCollabIterable(
-		options.minVersionForCollab,
-		versions,
+		minVersionForCollab,
+		stableVersions,
 	);
 	return result;
 }
@@ -473,11 +514,6 @@ function getWriteVersion<T extends CodecVersionBase>(
 /**
  * Formats a list of versions for use in UsageErrors.
  */
-function versionList(
-	versions: readonly [
-		MinimumMinorSemanticVersion | MinimumVersionForCollab,
-		CodecVersionBase,
-	][],
-): string {
-	return `${Array.from(versions, ([_v, codec]) => codec.formatVersion).join(", ")}`;
+function versionList(versions: readonly CodecVersionBase[]): string {
+	return JSON.stringify(Array.from(versions, (codec) => codec.formatVersion));
 }

package/src/core/tree/detachedFieldIndexCodecs.ts

@@ -24,16 +24,18 @@ type BuildData = CodecWriteOptions & {
 
 export const detachedFieldIndexCodecBuilder = ClientVersionDispatchingCodecBuilder.build(
 	"DetachedFieldIndex",
-	{
-		[lowestMinVersionForCollab]: {
+	[
+		{
+			minVersionForCollab: lowestMinVersionForCollab,
 			formatVersion: DetachedFieldIndexFormatVersion.v1,
 			codec: (buildData: BuildData) =>
 				makeDetachedNodeToFieldCodecV1(buildData.revisionTagCodec, buildData.idCompressor),
 		},
-		[FluidClientVersion.v2_52]: {
+		{
+			minVersionForCollab: FluidClientVersion.v2_52,
 			formatVersion: DetachedFieldIndexFormatVersion.v2,
 			codec: (buildData: BuildData) =>
 				makeDetachedNodeToFieldCodecV2(buildData.revisionTagCodec, buildData.idCompressor),
 		},
-	},
+	],
 );

package/src/{extensibleSchemaUnion.ts → extensibleUnionNode.ts}

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
 import { TreeAlpha, Tree } from "./shared-tree/index.js";
 import type {
 	TreeNodeSchema,
@@ -15,15 +17,16 @@ import type {
 import {
 	createCustomizedFluidFrameworkScopedFactory,
 	eraseSchemaDetailsSubclassable,
+	getInnerNode,
 	SchemaFactory,
 	TreeBeta,
 } from "./simple-tree/index.js";
 import type { UnionToIntersection } from "./util/index.js";
 
 /**
- * Utilities for creating extensible schema unions.
+ * Utilities for creating extensible unions using a node.
  * @remarks
- * Use {@link ExtensibleSchemaUnion.extensibleSchemaUnion} to create the union schema.
+ * Use {@link ExtensibleUnionNode.createSchema} to create the union schema.
  *
  * Unlike a schema union created using {@link SchemaStaticsBeta.staged | staged} allowed types, this union allows for unknown future types to exist in addition to the known types.
  * This allows for faster roll-outs of new types without waiting for old clients to be updated to be aware of them.
@@ -35,42 +38,68 @@ import type { UnionToIntersection } from "./util/index.js";
  *
  * @example
  * ```typescript
- * const sf = new SchemaFactoryBeta("extensibleSchemaUnionExample.items");
+ * const sf = new SchemaFactoryBeta("extensibleUnionNodeExample.items");
  * class ItemA extends sf.object("A", { x: sf.string }) {}
  * class ItemB extends sf.object("B", { x: sf.number }) {}
  *
- * class AnyItem extends ExtensibleSchemaUnion.extensibleSchemaUnion(
+ * class AnyItem extends ExtensibleUnionNode.createSchema(
  * 	[ItemA, ItemB], // Future versions may add more members here
  * 	sf,
  * 	"ExtensibleUnion",
  * ) {}
  * // Instances of the union are created using `create`.
  * const anyItem = AnyItem.create(new ItemA({ x: "hello" }));
- * // Reading the content from the union is done via `child`,
+ * // Reading the content from the union is done via the `union` property,
  * // which can be `undefined` to handle the case where a future version of this schema allows a type unknown to the current version.
- * const childNode: ItemA | ItemB | undefined = anyItem.child;
+ * const childNode: ItemA | ItemB | undefined = anyItem.union;
  * // To determine which member of the union was present, its schema can be inspected:
  * const aSchema = Tree.schema(childNode ?? assert.fail("No child"));
  * assert.equal(aSchema, ItemA);
  * ```
- * @alpha
+ * @beta
  */
-export namespace ExtensibleSchemaUnion {
+export namespace ExtensibleUnionNode {
 	/**
-	 * Members for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.
-	 * @alpha
+	 * Members for classes created by {@link ExtensibleUnionNode.createSchema}.
+	 * @beta
 	 */
 	export interface Members<T> {
 		/**
-		 * The child wrapped by this node, which is has one of the type allowed by the union,
+		 * The child wrapped by this node has one of the types allowed by the union,
 		 * or `undefined` if the type is one which was added to the union by a future version of this schema.
+		 *
+		 * @throws if {@link ExtensibleUnionNode.Members.isValid} is false.
+		 */
+		readonly union: T | undefined;
+
+		/**
+		 * Returns true, unless this node is in an invalid state.
+		 * @remarks
+		 * A well behaved application should not need this API.
+		 * If an application is hitting errors when accessing {@link ExtensibleUnionNode.Members.union},
+		 * this API can be used to help detect and recover from the invalid state which causes those errors (for example by replacing the invalid nodes with new ones).
+		 *
+		 * In this context "invalid" means that the internal implementation details of this node have had their invariants violated.
+		 * This can happen when:
+		 * - Using weakly typed construction APIs like {@link (TreeBeta:interface).importConcise} or {@link (TreeAlpha:interface).importVerbose} to construct an invalid state directly.
+		 * Using such APIs, even when not creating invalid nodes, is not supported for this schema,
+		 * since doing so requires knowing the implementation details of this node which are subject to change.
+		 * - By editing a document using a different client using a different schema for this node.
+		 * - Violating the TypeScript types to directly manipulate the node internals.
+		 * - A bug in this node's implementation (possibly in a different client) corrupted the node.
+		 * - Corruption of the document this node is contained in.
+		 *
+		 * @privateRemarks
+		 * We could support {@link (TreeBeta:interface).exportVerbose} using {@link KeyEncodingOptions.allStoredKeys}
+		 * then {@link (TreeAlpha:interface).importVerbose} with {@link KeyEncodingOptions.knownStoredKeys}.
+		 * However, even this will error (but will not produce an invalid node) if there is a node of an unknown type in the union.
 		 */
-		readonly child: T | undefined;
+		isValid(): boolean;
 	}
 
 	/**
-	 * Statics for classes created by {@link ExtensibleSchemaUnion.extensibleSchemaUnion}.
-	 * @alpha
+	 * Statics for classes created by {@link ExtensibleUnionNode.createSchema}.
+	 * @beta
 	 */
 	export interface Statics<T extends readonly TreeNodeSchema[]> {
 		/**
@@ -86,11 +115,11 @@ export namespace ExtensibleSchemaUnion {
 	 * Create an extensible schema union which currently supports the types in `types`,
 	 * but tolerates collaboration with future versions that may include additional types.
 	 * @remarks
-	 * See {@link ExtensibleSchemaUnion} for an example use.
-	 * @alpha
+	 * See {@link ExtensibleUnionNode} for an example use.
+	 * @beta
 	 */
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-	export function extensibleSchemaUnion<
+	export function createSchema<
 		const T extends readonly TreeNodeSchema[],
 		const TScope extends string,
 		const TName extends string,
@@ -101,19 +130,32 @@ export namespace ExtensibleSchemaUnion {
 		}
 		const schemaFactory = createCustomizedFluidFrameworkScopedFactory(
 			inputSchemaFactory,
-			"extensibleSchemaUnion",
+			"extensibleUnionNode",
 		);
+
 		class Union
 			extends schemaFactory.object(name, record, { allowUnknownOptionalFields: true })
 			implements Members<TreeNodeFromImplicitAllowedTypes<T>>
 		{
-			public get child(): TreeNodeFromImplicitAllowedTypes<T> | undefined {
+			public get union(): TreeNodeFromImplicitAllowedTypes<T> | undefined {
+				if (!this.isValid()) {
+					throw new UsageError(
+						`This ExtensibleUnionNode (${Union.identifier}) is in an invalid state. It must have been edited by another client using a different schema or been directly imported or constructed in an invalid state.`,
+					);
+				}
 				for (const [_key, child] of TreeAlpha.children(this)) {
 					return child as TreeNodeFromImplicitAllowedTypes<T>;
 				}
 				return undefined;
 			}
 
+			public isValid(): boolean {
+				// Use inner node, since it includes populated fields even when they are unknown.
+				const inner = getInnerNode(this);
+				// Fields only includes non-empty fields, so this is what we need to check the one child invariant.
+				return [...inner.fields].length === 1;
+			}
+
 			public static create<TThis extends TreeNodeSchema>(
 				this: TThis,
 				child: TreeNodeFromImplicitAllowedTypes<T>,

package/src/feature-libraries/chunked-forest/codec/codecs.ts

@@ -35,13 +35,7 @@ import { TreeCompressionStrategy } from "../../treeCompressionUtils.js";
 
 import { decode } from "./chunkDecoding.js";
 import type { FieldBatch } from "./fieldBatch.js";
-import {
-	type EncodedFieldBatch,
-	validVersions,
-	FieldBatchFormatVersion,
-	EncodedFieldBatchV1,
-	EncodedFieldBatchV2,
-} from "./format.js";
+import { EncodedFieldBatch, validVersions, FieldBatchFormatVersion } from "./format.js";
 import type { IncrementalEncodingPolicy } from "./incrementalEncodingPolicy.js";
 import { schemaCompressedEncodeV1, schemaCompressedEncodeV2 } from "./schemaBasedEncode.js";
 import { uncompressedEncodeV1, uncompressedEncodeV2 } from "./uncompressedEncode.js";
@@ -157,18 +151,15 @@ export function makeFieldBatchCodec(options: CodecWriteOptions): FieldBatchCodec
 	let schemaCompressedEncodeFn:
 		| typeof schemaCompressedEncodeV1
 		| typeof schemaCompressedEncodeV2;
-	let encodedFieldBatchType: typeof EncodedFieldBatchV1 | typeof EncodedFieldBatchV2;
 	switch (writeVersion) {
 		case unbrand(FieldBatchFormatVersion.v1): {
 			uncompressedEncodeFn = uncompressedEncodeV1;
 			schemaCompressedEncodeFn = schemaCompressedEncodeV1;
-			encodedFieldBatchType = EncodedFieldBatchV1;
 			break;
 		}
 		case unbrand(FieldBatchFormatVersion.v2): {
 			uncompressedEncodeFn = uncompressedEncodeV2;
 			schemaCompressedEncodeFn = schemaCompressedEncodeV2;
-			encodedFieldBatchType = EncodedFieldBatchV2;
 			break;
 		}
 		default: {
@@ -176,7 +167,10 @@ export function makeFieldBatchCodec(options: CodecWriteOptions): FieldBatchCodec
 		}
 	}
 
-	return makeVersionedValidatedCodec(options, validVersions, encodedFieldBatchType, {
+	// Both the encode and decode logic here support both v1 and v2, as does `validVersions` and `EncodedFieldBatch`.
+	// This makes this use of makeVersionedValidatedCodec atypical as it is a single call being used to make a codec that supports all versions,
+	// instead of one call per version, then using another utility to select between them based on version.
+	return makeVersionedValidatedCodec(options, validVersions, EncodedFieldBatch, {
 		encode: (data: FieldBatch, context: FieldBatchEncodingContext): EncodedFieldBatch => {
 			for (const cursor of data) {
 				assert(

package/src/feature-libraries/forest-summary/codec.ts

@@ -9,6 +9,7 @@ import {
 	getConfigForMinVersionForCollab,
 	lowestMinVersionForCollab,
 } from "@fluidframework/runtime-utils/internal";
+import { Type } from "@sinclair/typebox";
 
 import {
 	type CodecTree,
@@ -21,12 +22,9 @@ import type { FieldKey, ITreeCursorSynchronous } from "../../core/index.js";
 import { brand, type JsonCompatibleReadOnly } from "../../util/index.js";
 import type { FieldBatchCodec, FieldBatchEncodingContext } from "../chunked-forest/index.js";
 
-import {
-	ForestFormatVersion,
-	validVersions,
-	type Format,
-	FormatCommon,
-} from "./formatCommon.js";
+import { ForestFormatVersion, validVersions, type Format } from "./formatCommon.js";
+import { FormatV1 } from "./formatV1.js";
+import { FormatV2 } from "./formatV2.js";
 
 /**
  * Uses field cursors
@@ -61,7 +59,10 @@ export function makeForestSummarizerCodec(
 ): ForestCodec {
 	const inner = fieldBatchCodec;
 	const writeVersion = clientVersionToForestFormatVersion(options.minVersionForCollab);
-	const formatSchema = FormatCommon(writeVersion);
+	const formatSchema = Type.Union([FormatV1, FormatV2]);
+	// Both the encode and decode logic here support both v1 and v2, as does `validVersions` and `formatSchema`.
+	// This makes this use of makeVersionedValidatedCodec atypical as it is a single call being used to make a codec that supports all versions,
+	// instead of one call per version, then using another utility to select between them based on version.
 	return makeVersionedValidatedCodec(options, validVersions, formatSchema, {
 		encode: (data: FieldSet, context: FieldBatchEncodingContext): Format => {
 			const keys: FieldKey[] = [];

package/src/feature-libraries/forest-summary/formatCommon.ts

@@ -20,8 +20,8 @@ export type ForestFormatVersion = Values<typeof ForestFormatVersion>;
 
 export const validVersions = new Set([...Object.values(ForestFormatVersion)]);
 
-export const FormatCommon = (
-	version: ForestFormatVersion,
+export const FormatCommon = <const TVersion extends ForestFormatVersion>(
+	version: TVersion,
 	// Return type is intentionally derived.
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 ) =>
@@ -33,4 +33,6 @@ export const FormatCommon = (
 		},
 		{ additionalProperties: false },
 	);
-export type Format = Static<ReturnType<typeof FormatCommon>>;
+export type Format<TVersion extends ForestFormatVersion = ForestFormatVersion> = Static<
+	ReturnType<typeof FormatCommon<TVersion>>
+>;

package/src/feature-libraries/forest-summary/formatV1.ts

@@ -5,9 +5,7 @@
 
 import type { Static } from "@sinclair/typebox";
 
-import { brand } from "../../util/index.js";
-
 import { FormatCommon, ForestFormatVersion } from "./formatCommon.js";
 
-export const FormatV1 = FormatCommon(brand<ForestFormatVersion>(ForestFormatVersion.v1));
+export const FormatV1 = FormatCommon(ForestFormatVersion.v1);
 export type FormatV1 = Static<typeof FormatV1>;

package/src/feature-libraries/forest-summary/formatV2.ts

@@ -5,9 +5,7 @@
 
 import type { Static } from "@sinclair/typebox";
 
-import { brand } from "../../util/index.js";
-
 import { FormatCommon, ForestFormatVersion } from "./formatCommon.js";
 
-export const FormatV2 = FormatCommon(brand<ForestFormatVersion>(ForestFormatVersion.v2));
+export const FormatV2 = FormatCommon(ForestFormatVersion.v2);
 export type FormatV2 = Static<typeof FormatV2>;