@fluidframework/tree 2.74.0-370705 → 2.80.0

package/src/codec/codec.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import { cleanedPackageVersion as runtimeUtilsCleanedPackageVersion } from "@fluidframework/runtime-utils/internal";
 import type { ErasedType } from "@fluidframework/core-interfaces/internal";
 import { IsoBuffer, bufferToString } from "@fluid-internal/client-utils";
 import { assert, fail } from "@fluidframework/core-utils/internal";
@@ -153,6 +154,18 @@ 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;
+
+	/**
+	 * Overrides the version of the codec to use for encoding.
+	 * @remarks
+	 * Without an override, the selected version will be based on {@link CodecWriteOptions.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}.
+	 */
+	readonly allowPossiblyIncompatibleWriteVersionOverrides?: boolean;
 }
 
 /**
@@ -251,13 +264,22 @@ export interface ICodecFamily<TDecoded, TContext = void> {
 
 /**
  * A version stamp for encoded data.
- *
+ * @remarks
  * Strings are used for formats that are not yet officially supported.
  * When such formats become officially supported/stable, they will be switched to using a number.
  * Undefined is tolerated to enable the scenario where data was not initially versioned.
+ * @alpha
  */
 export type FormatVersion = number | string | undefined;
 
+/**
+ * A unique name given to this codec family.
+ * @remarks
+ * This is not persisted: it is only used to specify version overrides and in errors.
+ * @alpha
+ */
+export type CodecName = string;
+
 /**
  * A format version which is dependent on some parent format version.
  */
@@ -373,9 +395,13 @@ function isJsonCodec<TDecoded, TContext>(
  * Constructs a {@link IMultiFormatCodec} from a `IJsonCodec` using a generic binary encoding that simply writes
  * the json representation of the object to a buffer.
  */
-export function withDefaultBinaryEncoding<TDecoded, TContext>(
-	jsonCodec: IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,
-): IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
+export function withDefaultBinaryEncoding<
+	TDecoded,
+	TContext,
+	TEncoded extends JsonCompatibleReadOnly = JsonCompatibleReadOnly,
+>(
+	jsonCodec: IJsonCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext>,
+): IMultiFormatCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext> {
 	return {
 		json: jsonCodec,
 		binary: new DefaultBinaryCodec(jsonCodec),
@@ -386,11 +412,15 @@ export function withDefaultBinaryEncoding<TDecoded, TContext>(
  * Ensures that the provided single or multi-format codec has a binary encoding.
  * Adapts the json encoding using {@link withDefaultBinaryEncoding} if necessary.
  */
-export function ensureBinaryEncoding<TDecoded, TContext>(
+export function ensureBinaryEncoding<
+	TDecoded,
+	TContext,
+	TEncoded extends JsonCompatibleReadOnly = JsonCompatibleReadOnly,
+>(
 	codec:
-		| IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>
-		| IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,
-): IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
+		| IMultiFormatCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext>
+		| IJsonCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext>,
+): IMultiFormatCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext> {
 	return isJsonCodec(codec) ? withDefaultBinaryEncoding(codec) : codec;
 }
 
@@ -465,8 +495,14 @@ export function withSchemaValidation<
  * If the need arises, they might be added in the future.
  *
  * @privateRemarks
- * Entries in these enums should document the user facing impact of opting into a particular version.
- * For example, document if there is an encoding efficiency improvement of oping into that version or newer.
+ * The entries in these enums should document the following:
+ * - The user facing impact of opting into a particular version. This will help customers decide if they want to opt into
+ * a new version. For example, document if there is an encoding efficiency improvement of oping into that version or newer.
+ * - Any new data formats that are introduced in that version. This will help developers tell which data formats a given
+ * version will write. For example, document if a new summary or encoding format is added in a version.
+ * - Whether the above features or data formats introduced in a version are enabled by default or require the
+ * {@link minVersionForCollab} option to be set to that particular version.
+ *
  * Versions with no notable impact can be omitted.
  *
  * This scheme assumes a single version will always be enough to communicate compatibility.
@@ -505,10 +541,10 @@ export const FluidClientVersion = {
 	 * Fluid Framework Client 2.43 and newer.
 	 * @remarks
 	 * New formats introduced in 2.43:
-	 * - SchemaFormatVersion.v2
-	 * - MessageFormatVersion.v4
-	 * - EditManagerFormatVersion.v4
-	 * - Sequence format version 3
+	 * - SchemaFormatVersion.v2 - written when minVersionForCollab \>= 2.43
+	 * - MessageFormatVersion.v4 - written when minVersionForCollab \>= 2.43
+	 * - EditManagerFormatVersion.v4 - written when minVersionForCollab \>= 2.43
+	 * - sequence-field/formatV3 - written when minVersionForCollab \>= 2.43
 	 */
 	v2_43: "2.43.0",
 
@@ -516,7 +552,7 @@ export const FluidClientVersion = {
 	 * Fluid Framework Client 2.52 and newer.
 	 * @remarks
 	 * New formats introduced in 2.52:
-	 * - DetachedFieldIndexFormatVersion.v2
+	 * - DetachedFieldIndexFormatVersion.v2 - written when minVersionForCollab \>= 2.52
 	 */
 	v2_52: "2.52.0",
 
@@ -524,7 +560,7 @@ export const FluidClientVersion = {
 	 * Fluid Framework Client 2.73 and newer.
 	 * @remarks
 	 * New formats introduced in 2.73:
-	 * - FieldBatchFormatVersion v2
+	 * - FieldBatchFormatVersion.v2 - written when minVersionForCollab \>= 2.73
 	 */
 	v2_73: "2.73.0",
 
@@ -532,25 +568,45 @@ export const FluidClientVersion = {
 	 * Fluid Framework Client 2.74 and newer.
 	 * @remarks
 	 * New formats introduced in 2.74:
-	 * - SharedTreeSummaryFormatVersion v2
-	 * - DetachedFieldIndexSummaryFormatVersion v2
-	 * - SchemaSummaryFormatVersion v2
-	 * - EditManagerSummaryFormatVersion v2
-	 * - ForestSummaryFormatVersion v2
+	 * - SharedTreeSummaryFormatVersion.v2 - written by default
+	 * - DetachedFieldIndexSummaryFormatVersion.v2 - written by default
+	 * - SchemaSummaryFormatVersion.v2 - written by default
+	 * - EditManagerSummaryFormatVersion.v2 - written by default
+	 * - ForestSummaryFormatVersion.v2 - written by default
+	 * - ForestFormatVersion.v2 - written when minVersionForCollab \>= 2.74
+	 * - ForestSummaryFormatVersion.v3 - written when minVersionForCollab \>= 2.74
 	 */
 	v2_74: "2.74.0",
+
+	/**
+	 * Fluid Framework Client 2.80 and newer.
+	 * @remarks
+	 * New formats introduced in 2.80:
+	 * - MessageFormatVersion.v6 - written when minVersionForCollab \>= 2.80
+	 * - EditManagerFormatVersion.v6 - written when minVersionForCollab \>= 2.80
+	 * - SharedTreeChangeFormatVersion.v5 - written when minVersionForCollab \>= 2.80
+	 * - ModularChangeFormatVersion.v5 - written when minVersionForCollab \>= 2.80
+	 */
+	v2_80: "2.80.0",
 } as const satisfies Record<string, MinimumVersionForCollab>;
 
 /**
- * An up to date version which includes all the important stable features.
+ * An up to date version which includes all stable features.
  * @remarks
- * Use for cases when data is not persisted and thus would only ever be read by the current version of the framework.
+ * Use for cases when data is not persisted and thus would only ever be read by the the same version of the code which read this value.
+ *
+ * The pkgVersion from this package (tree) can not be used here as it is not guaranteed to be a valid MinimumVersionForCollab
+ * and would also unexpectedly disable features in prereleases and on CI if it didn't fail validation.
+ * See {@link @fluidframework/runtime-utils/internal#cleanedPackageVersion} for more details on why cleanedPackageVersion is preferred over pkgVersion.
  *
  * @privateRemarks
- * Update as needed.
- * TODO: Consider using packageVersion.ts to keep this current.
+ * It is safe to use CleanedPackageVersion from runtime-utils here since features are enabled in minor versions,
+ * and this package (tree) depends on runtime-utils with a `~` semver range
+ * ensuring that the version of runtime-utils this was imported from will match the version of this (tree) package at least up to the minor version.
+ * Reusing this from runtime-utils avoids duplicating the cleanup logic here as well as the cost or recomputing it.
+ * If in the future for some reason this becomes not okay, runtime-utils could instead export a function that performs that cleanup logic which could be reused here.
  */
-export const currentVersion: MinimumVersionForCollab = FluidClientVersion.v2_0;
+export const currentVersion: MinimumVersionForCollab = runtimeUtilsCleanedPackageVersion;
 
 export interface CodecTree {
 	readonly name: string;

package/src/codec/index.ts

@@ -28,6 +28,7 @@ export {
 	type CodecTree,
 	jsonableCodecTree,
 	extractJsonValidator,
+	type CodecName,
 } from "./codec.js";
 export {
 	DiscriminatedUnionDispatcher,
@@ -36,8 +37,10 @@ export {
 } from "./discriminatedUnions.js";
 export {
 	Versioned,
-	makeVersionedCodec,
 	makeVersionedValidatedCodec,
 	makeVersionDispatchingCodec,
 	makeDiscontinuedCodecVersion,
+	ClientVersionDispatchingCodecBuilder,
+	type CodecVersion,
+	type CodecAndSchema,
 } from "./versioned/index.js";

package/src/codec/versioned/codec.ts

@@ -5,10 +5,19 @@
 
 import { assert } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import type { SemanticVersion } from "@fluidframework/runtime-utils/internal";
+import {
+	getConfigForMinVersionForCollabIterable,
+	type ConfigMapEntry,
+	type MinimumMinorSemanticVersion,
+	type SemanticVersion,
+} from "@fluidframework/runtime-utils/internal";
 import { Type, type TSchema } from "@sinclair/typebox";
+import { gt } from "semver-ts";
 
-import type { JsonCompatibleReadOnly } from "../../util/index.js";
+import type {
+	JsonCompatibleReadOnly,
+	JsonCompatibleReadOnlyObject,
+} from "../../util/index.js";
 import {
 	type ICodecFamily,
 	type ICodecOptions,
@@ -16,15 +25,24 @@ import {
 	withSchemaValidation,
 	type FormatVersion,
 	type CodecWriteOptions,
+	type IMultiFormatCodec,
+	type CodecName,
+	ensureBinaryEncoding,
+	type CodecTree,
 } from "../codec.js";
 
 import { Versioned } from "./format.js";
 import { pkgVersion } from "../../packageVersion.js";
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
 
-export function makeVersionedCodec<
+/**
+ * Json compatible data with a format version.
+ */
+type VersionedJson = JsonCompatibleReadOnlyObject & Versioned;
+
+function makeVersionedCodec<
 	TDecoded,
-	TEncoded extends Versioned = JsonCompatibleReadOnly & Versioned,
+	TEncoded extends Versioned = VersionedJson,
 	TValidate = TEncoded,
 	TContext = void,
 >(
@@ -45,7 +63,7 @@ export function makeVersionedCodec<
 			const versioned = data as Versioned; // Validated by withSchemaValidation
 			if (!supportedVersions.has(versioned.version)) {
 				throw new UsageError(
-					`Unsupported version ${versioned.version} encountered while decoding data. Supported versions for this data are: ${Array.from(supportedVersions).join(", ")}.
+					`Unsupported version ${versioned.version} encountered while decoding data. Supported versions for this data are: ${[...supportedVersions].join(", ")}.
 The client which encoded this data likely specified an "minVersionForCollab" value which corresponds to a version newer than the version of this client ("${pkgVersion}").`,
 				);
 			}
@@ -59,10 +77,13 @@ The client which encoded this data likely specified an "minVersionForCollab" val
 		: withSchemaValidation(Versioned, codec, validator);
 }
 
+/**
+ * TODO: users of this should migrate to {@link ClientVersionDispatchingCodecBuilder}.
+ */
 export function makeVersionedValidatedCodec<
 	EncodedSchema extends TSchema,
 	TDecoded,
-	TEncoded extends Versioned = JsonCompatibleReadOnly & Versioned,
+	TEncoded extends Versioned = VersionedJson,
 	TValidate = TEncoded,
 	TContext = void,
 >(
@@ -80,10 +101,13 @@ export function makeVersionedValidatedCodec<
 
 /**
  * Creates a codec which always throws a UsageError when encoding or decoding, indicating that the format version is discontinued.
+ *
+ * TODO: {@link ClientVersionDispatchingCodecBuilder} should get support for extra decode only entries and/or unstable formats (codecs without a minVersionForCollab that will never be selected for write unless overridden).
+ * Once done, users of this should migrate to ClientVersionDispatchingCodecBuilder and this function can be simplified.
  */
 export function makeDiscontinuedCodecVersion<
 	TDecoded,
-	TEncoded extends Versioned = JsonCompatibleReadOnly & Versioned,
+	TEncoded extends Versioned = VersionedJson,
 	TContext = unknown,
 >(
 	options: ICodecOptions,
@@ -103,12 +127,12 @@ export function makeDiscontinuedCodecVersion<
 	const codec: IJsonCodec<TDecoded, TEncoded, TEncoded, TContext> = {
 		encode: (_: TDecoded): TEncoded => {
 			throw new UsageError(
-				`Cannot encode data to format ${discontinuedVersion}. The codec was discontinued in FF version ${discontinuedSince}.`,
+				`Cannot encode data to format ${discontinuedVersion}. The codec was discontinued in Fluid Framework client version ${discontinuedSince}.`,
 			);
 		},
 		decode: (data: TEncoded): TDecoded => {
 			throw new UsageError(
-				`Cannot decode data to format ${data.version}. The codec was discontinued in FF version ${discontinuedSince}.`,
+				`Cannot decode data to format ${data.version}. The codec was discontinued in Fluid Framework client version ${discontinuedSince}.`,
 			);
 		},
 	};
@@ -125,7 +149,7 @@ export function makeDiscontinuedCodecVersion<
  */
 export function makeVersionDispatchingCodec<TDecoded, TContext>(
 	family: ICodecFamily<TDecoded, TContext>,
-	options: ICodecOptions & { writeVersion: number | string },
+	options: ICodecOptions & { writeVersion: FormatVersion },
 ): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
 	const writeCodec = family.resolve(options.writeVersion).json;
 	const supportedVersions = new Set(family.getSupportedFormats());
@@ -140,30 +164,324 @@ export function makeVersionDispatchingCodec<TDecoded, TContext>(
 	});
 }
 
+/**
+ * A friendly format for codec authors use to define their codec and schema for use in {@link CodecVersion}.
+ * @remarks
+ * 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>
+);
+
+/**
+ * A codec alongside its format version and schema.
+ */
+export interface CodecVersionBase<
+	T = unknown,
+	TFormatVersion extends FormatVersion = FormatVersion,
+> {
+	readonly formatVersion: TFormatVersion;
+	readonly codec: T;
+}
+
+/**
+ * A particular version of a codec and when to use it.
+ * @privateRemarks
+ * This allows lazy building of the codec with options.
+ * This option can likely be removed as the codec handling is made simpler and more consistent.
+ * Removing support for this laziness would be nice to help prevent unexpected coupling and alteration to codec behavior,
+ * helping ensure that tests and production code behave the same.
+ */
+export interface CodecVersion<
+	TDecoded,
+	TContext,
+	TFormatVersion extends FormatVersion,
+	TBuildOptions extends CodecWriteOptions,
+> extends CodecVersionBase<
+		| CodecAndSchema<TDecoded, TContext>
+		| ((options: TBuildOptions) => CodecAndSchema<TDecoded, TContext>),
+		TFormatVersion
+	> {}
+
+/**
+ * {@link CodecVersion} after normalization into a consistent type.
+ * @remarks
+ * Produced by {@link normalizeCodecVersion}.
+ * Includes schema validation.
+ */
+export interface NormalizedCodecVersion<
+	TDecoded,
+	TContext,
+	TFormatVersion extends FormatVersion,
+	TBuildOptions extends CodecWriteOptions,
+> extends CodecVersionBase<
+		(
+			options: TBuildOptions,
+		) => IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>,
+		TFormatVersion
+	> {}
+
+/**
+ * {@link NormalizedCodecVersion} after applying the build options.
+ * @remarks
+ * Produced by {@link ClientVersionDispatchingCodecBuilder.applyOptions}.
+ */
+export interface EvaluatedCodecVersion<
+	TDecoded,
+	TContext,
+	TFormatVersion extends FormatVersion,
+> extends CodecVersionBase<
+		IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>,
+		TFormatVersion
+	> {}
+
+/**
+ * Normalize the codec to a single format.
+ * @remarks
+ * Bakes in schema validation, so output no longer exposes the schema.
+ */
+function normalizeCodecVersion<
+	TDecoded,
+	TContext,
+	TFormatVersion extends FormatVersion,
+	TBuildOptions extends CodecWriteOptions,
+>(
+	codecVersion: CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>,
+): NormalizedCodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions> {
+	const codecBuilder: (options: TBuildOptions) => CodecAndSchema<TDecoded, TContext> =
+		typeof codecVersion.codec === "function"
+			? codecVersion.codec
+			: () => codecVersion.codec as CodecAndSchema<TDecoded, TContext>;
+	const codec = (
+		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,
+		);
+	};
+
+	return {
+		formatVersion: codecVersion.formatVersion,
+		codec,
+	};
+}
+
 /**
  * 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.
  * @privateRemarks
  * This is a two stage builder so the first stage can encapsulate all codec specific details and the second can bring in configuration.
  */
-export class ClientVersionDispatchingCodecBuilder<TDecoded, TContext> {
-	public constructor(
+export class ClientVersionDispatchingCodecBuilder<
+	Name extends CodecName,
+	TDecoded,
+	TContext,
+	TFormatVersion extends FormatVersion,
+	TBuildOptions extends CodecWriteOptions,
+> {
+	public readonly registry: ReadonlyMap<
+		MinimumVersionForCollab,
+		NormalizedCodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>
+	>;
+
+	/**
+	 * Use {@link ClientVersionDispatchingCodecBuilder.build} to create an instance of this class.
+	 */
+	private constructor(
 		/**
-		 * The codec family to dispatch to.
+		 * See {@link CodecName}.
 		 */
-		private readonly family: ICodecFamily<TDecoded, TContext>,
+		public readonly name: Name,
 		/**
-		 * A function which maps a {@link MinimumVersionForCollab} to a version number for the codec family which is supported by that version.
-		 * This can (and typically does) pick the newest version of the codec which is known to be compatible with the client version so that
-		 * any improvements in newer versions of the codec can be used when allowed.
+		 * The registry of codecs which this builder can use to encode and decode data.
 		 */
-		private readonly versionMapping: (minVersionForCollab: MinimumVersionForCollab) => number,
-	) {}
+		inputRegistry: ConfigMapEntry<
+			CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>
+		>,
+	) {
+		type Normalized = NormalizedCodecVersion<
+			TDecoded,
+			TContext,
+			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 normalizedCodec = normalizeCodecVersion(codec);
+			normalizedRegistry.set(minVersionForCollab, normalizedCodec);
+		}
+
+		this.registry = normalizedRegistry;
+	}
 
+	/**
+	 * Applies the provided 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,
+	): [MinimumVersionForCollab, EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>][] {
+		return Array.from(
+			this.registry,
+			([version, codec]) =>
+				[
+					version,
+					{
+						formatVersion: codec.formatVersion,
+						codec: codec.codec(options),
+					},
+				] as const,
+		);
+	}
+
+	/**
+	 * Produce a single codec which can read any supported format, and writes a version selected based on the provided options.
+	 */
 	public build(
-		options: CodecWriteOptions,
+		options: TBuildOptions,
 	): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
-		const writeVersion = this.versionMapping(options.minVersionForCollab);
-		return makeVersionDispatchingCodec(this.family, { ...options, writeVersion });
+		const applied = this.applyOptions(options);
+		const writeVersion = getWriteVersion(this.name, options, applied);
+		const fromFormatVersion = new Map<
+			FormatVersion,
+			EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>
+		>(applied.map(([_version, codec]) => [codec.formatVersion, codec]));
+		return {
+			encode: (data: TDecoded, context: TContext): JsonCompatibleReadOnly => {
+				return writeVersion.codec.encode(data, context);
+			},
+			decode: (data: JsonCompatibleReadOnly, context: TContext): TDecoded => {
+				const versioned = data as Partial<Versioned>;
+				const codec = fromFormatVersion.get(versioned.version);
+				if (codec === undefined) {
+					throw new UsageError(
+						`Unsupported version ${versioned.version} encountered while decoding ${this.name} data. Supported versions for this data are: ${versionList(applied)}.
+The client which encoded this data likely specified an "minVersionForCollab" value which corresponds to a version newer than the version of this client ("${pkgVersion}").`,
+					);
+				}
+				return codec.codec.decode(data, context);
+			},
+		};
+	}
+
+	public getCodecTree(clientVersion: MinimumVersionForCollab): CodecTree {
+		// TODO: add support for children codecs.
+		const selected = getConfigForMinVersionForCollabIterable(clientVersion, this.registry);
+		return {
+			name: this.name,
+			version: selected.formatVersion,
+		};
 	}
+
+	/**
+	 * Builds a ClientVersionDispatchingCodecBuilder from the provided 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.
+	 */
+	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+	public static build<
+		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;
+		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,
+					TFormatVersion2,
+					TBuildOptions2
+				>
+			>,
+		);
+		return builder;
+	}
+}
+
+/**
+ * Selects which format should be used when writing data.
+ * @remarks
+ * This either uses the override specified in the options, or selects the newest format compatible with the provided minVersionForCollab.
+ */
+function getWriteVersion<T extends CodecVersionBase>(
+	name: CodecName,
+	options: CodecWriteOptions,
+	versions: readonly [MinimumMinorSemanticVersion | MinimumVersionForCollab, T][],
+): T {
+	if (options.writeVersionOverrides?.has(name) === true) {
+		const selectedFormatVersion = options.writeVersionOverrides.get(name);
+		const selected = versions.find(
+			([_v, codec]) => codec.formatVersion === selectedFormatVersion,
+		);
+		if (selected === undefined) {
+			throw new UsageError(
+				`Codec "${name}" does not support requested format version ${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.
+			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.`,
+				);
+			} 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.`,
+				);
+			}
+		}
+
+		return selected[1];
+	}
+	const result: T = getConfigForMinVersionForCollabIterable(
+		options.minVersionForCollab,
+		versions,
+	);
+	return result;
+}
+
+/**
+ * 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(", ")}`;
 }

package/src/codec/versioned/index.ts

@@ -5,8 +5,10 @@
 
 export { Versioned } from "./format.js";
 export {
-	makeVersionedCodec,
 	makeVersionedValidatedCodec,
 	makeVersionDispatchingCodec,
 	makeDiscontinuedCodecVersion,
+	ClientVersionDispatchingCodecBuilder,
+	type CodecVersion,
+	type CodecAndSchema,
 } from "./codec.js";