@fluidframework/tree 2.101.0 → 2.102.0

package/dist/codec/versioned/codec.d.ts

@@ -15,16 +15,16 @@ type VersionedJson = JsonCompatibleReadOnlyObject & Versioned;
 /**
  * Creates a codec version which always throws a UsageError when encoding or decoding, indicating that the format version is discontinued.
  */
-export declare function makeDiscontinuedCodecAndSchema<TDecoded, TContext, TFormatVersion extends FormatVersion = FormatVersion>(discontinuedVersion: TFormatVersion, discontinuedSince: SemanticVersion): CodecVersion<TDecoded, TContext, TFormatVersion>;
+export declare function makeDiscontinuedCodecAndSchema<TDecoded, TFormatVersion extends FormatVersion = FormatVersion>(discontinuedVersion: TFormatVersion, discontinuedSince: SemanticVersion): CodecVersion<TDecoded, unknown, TFormatVersion, ICodecOptions, unknown>;
 /**
  * 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> = {
+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.
  */
@@ -48,7 +48,7 @@ export interface CodecVersionBase<T = unknown, TFormatVersion extends FormatVers
  * 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 ICodecOptions = ICodecOptions> extends CodecVersionBase<CodecAndSchema<TDecoded, TContext> | ((options: TBuildOptions) => CodecAndSchema<TDecoded, TContext>), TFormatVersion> {
+export interface CodecVersion<TDecoded, TEncodeContext, TFormatVersion extends FormatVersion, TBuildOptions extends ICodecOptions = ICodecOptions, TDecodeContext = TEncodeContext> extends CodecVersionBase<CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext> | ((options: TBuildOptions) => CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext>), TFormatVersion> {
 }
 /**
  * {@link CodecVersion} after normalization into a consistent type.
@@ -56,29 +56,47 @@ export interface CodecVersion<TDecoded, TContext, TFormatVersion extends FormatV
  * Produced by {@link normalizeCodecVersion}.
  * Includes schema validation.
  */
-export interface NormalizedCodecVersion<TDecoded, TContext, TFormatVersion extends FormatVersion, TBuildOptions extends ICodecOptions> extends CodecVersionBase<(options: TBuildOptions) => CodecAndSchema<TDecoded, TContext>, TFormatVersion> {
+export interface NormalizedCodecVersion<TDecoded, TEncodeContext, TFormatVersion extends FormatVersion, TBuildOptions extends ICodecOptions, TDecodeContext = TEncodeContext> extends CodecVersionBase<(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> {
 }
 /**
- * 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 declare class ClientVersionDispatchingCodecBuilder<TBuildOptions extends ICodecOptions = ICodecOptions, TDecoded = unknown, TContext = unknown, TFormatVersion extends FormatVersion = FormatVersion, TName extends CodecName = string> {
+export declare class VersionDispatchingCodecBuilder<TBuildOptions extends ICodecOptions = ICodecOptions, TDecoded = unknown, TEncodeContext = unknown, TFormatVersion extends FormatVersion = FormatVersion, TName extends CodecName = string, TDecodeContext = TEncodeContext> {
     /**
      * See {@link CodecName}.
      */
     readonly name: TName;
-    readonly registry: readonly NormalizedCodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>[];
+    readonly registry: readonly NormalizedCodecVersion<TDecoded, TEncodeContext, TFormatVersion, 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.
@@ -87,37 +105,47 @@ export declare class ClientVersionDispatchingCodecBuilder<TBuildOptions extends
      */
     private constructor();
     /**
-     * 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.
      */
-    applyOptions(options: TBuildOptions): EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>[];
+    applyOptions(options: TBuildOptions): EvaluatedCodecVersion<TDecoded, TEncodeContext, TFormatVersion, TDecodeContext>[];
     /**
-     * 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.
      */
-    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;
-    };
+    build(options: TBuildOptions & CodecWriteOptions): VersionDispatchingCodec<TDecoded, TEncodeContext, TFormatVersion, TDecodeContext>;
     private buildDecoderInternal;
     /**
-     * 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
      */
-    buildDecoder(options: TBuildOptions): Pick<IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>, "decode">;
+    buildDecoder(options: TBuildOptions): Pick<VersionDispatchingCodec<TDecoded, TEncodeContext, TFormatVersion, TDecodeContext>, "decode">;
     getCodecTree(clientVersion: MinimumVersionForCollab): CodecTree<TFormatVersion>;
     /**
-     * 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 } },
+     * ]);
+     * ```
      */
-    static build<Name extends CodecName, Entry extends CodecVersion<unknown, unknown, FormatVersion, never>>(name: Name, inputRegistry: readonly Entry[]): ClientVersionDispatchingCodecBuilder<Entry extends CodecVersion<unknown, unknown, FormatVersion, infer B extends ICodecOptions> ? B : never, Entry extends CodecVersion<infer D, unknown, FormatVersion, never> ? D : never, unknown extends (Entry extends CodecVersion<unknown, infer C, FormatVersion, never> ? C : never) ? void : Entry extends CodecVersion<unknown, infer C, FormatVersion, never> ? C : never, Entry extends CodecVersion<unknown, unknown, infer F extends FormatVersion, never> ? F : never, Name>;
+    static build<Name extends CodecName, Entry extends CodecVersion<unknown, unknown, FormatVersion, never, unknown>>(name: Name, inputRegistry: readonly Entry[]): VersionDispatchingCodecBuilder<Entry extends CodecVersion<unknown, unknown, FormatVersion, infer B extends ICodecOptions, unknown> ? B : never, Entry extends CodecVersion<infer D, unknown, FormatVersion, never, unknown> ? D : never, unknown extends (Entry extends CodecVersion<unknown, infer C, FormatVersion, never, unknown> ? C : never) ? void : Entry extends CodecVersion<unknown, infer C, FormatVersion, never, unknown> ? C : never, Entry extends CodecVersion<unknown, unknown, infer F extends FormatVersion, never, unknown> ? F : never, Name, unknown extends (Entry extends CodecVersion<unknown, unknown, FormatVersion, never, infer D_1> ? D_1 : never) ? unknown extends (Entry extends CodecVersion<unknown, infer C, FormatVersion, never, unknown> ? C : never) ? void : Entry extends CodecVersion<unknown, infer C, FormatVersion, never, unknown> ? C : never : Entry extends CodecVersion<unknown, unknown, FormatVersion, never, infer D_1> ? D_1 : never>;
 }
 export {};
 //# sourceMappingURL=codec.d.ts.map

package/dist/codec/versioned/codec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../../src/codec/versioned/codec.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../../src/codec/versioned/codec.ts"],"names":[],"mappings":"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"}

package/dist/codec/versioned/codec.js

@@ -4,7 +4,7 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ClientVersionDispatchingCodecBuilder = exports.makeDiscontinuedCodecAndSchema = void 0;
+exports.VersionDispatchingCodecBuilder = exports.makeDiscontinuedCodecAndSchema = void 0;
 const internal_1 = require("@fluidframework/core-utils/internal");
 const internal_2 = require("@fluidframework/runtime-utils/internal");
 const internal_3 = require("@fluidframework/telemetry-utils/internal");
@@ -94,14 +94,14 @@ function normalizeCodecVersion(codecVersion) {
     };
 }
 /**
- * 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.
+ * 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.
  */
-class ClientVersionDispatchingCodecBuilder {
+class VersionDispatchingCodecBuilder {
     /**
-     * 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.
@@ -141,7 +141,7 @@ class ClientVersionDispatchingCodecBuilder {
         this.registry = normalizedRegistry;
     }
     /**
-     * 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.
@@ -154,7 +154,8 @@ 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.
      */
     build(options) {
         const [applied, decoder] = this.buildDecoderInternal(options);
@@ -186,7 +187,14 @@ 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
      */
     buildDecoder(options) {
         return this.buildDecoderInternal(options)[1];
@@ -200,20 +208,29 @@ 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
     static build(name, inputRegistry) {
         const input = inputRegistry;
-        const builder = new ClientVersionDispatchingCodecBuilder(name, input);
+        const builder = new VersionDispatchingCodecBuilder(name, input);
         return builder;
     }
 }
-exports.ClientVersionDispatchingCodecBuilder = ClientVersionDispatchingCodecBuilder;
+exports.VersionDispatchingCodecBuilder = VersionDispatchingCodecBuilder;
 /**
  * Selects which format should be used when writing data.
  * @remarks

package/dist/codec/versioned/codec.js.map

@@ -1 +1 @@
-{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../../src/codec/versioned/codec.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert, debugAssert } from \"@fluidframework/core-utils/internal\";\nimport type { MinimumVersionForCollab } from \"@fluidframework/runtime-definitions/internal\";\nimport {\n\tgetConfigForMinVersionForCollabIterable,\n\tlowestMinVersionForCollab,\n\ttype MinimumMinorSemanticVersion,\n\ttype SemanticVersion,\n} from \"@fluidframework/runtime-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport type { TSchema } from \"@sinclair/typebox\";\nimport { gt } from \"semver-ts\";\n\nimport { pkgVersion } from \"../../packageVersion.js\";\nimport {\n\tJsonCompatibleReadOnlySchema,\n\ttype JsonCompatibleReadOnly,\n\ttype JsonCompatibleReadOnlyObject,\n} from \"../../util/index.js\";\nimport {\n\ttype ICodecOptions,\n\ttype IJsonCodec,\n\twithSchemaValidation,\n\ttype FormatVersion,\n\ttype CodecWriteOptions,\n\ttype CodecName,\n\ttype CodecTree,\n} from \"../codec.js\";\n\nimport { Versioned } from \"./format.js\";\n\n/**\n * Json compatible data with a format version.\n */\ntype VersionedJson = JsonCompatibleReadOnlyObject & Versioned;\n\n/**\n * Validate that the version is one of the supported values.\n * @remarks\n * If supportedVersions contains undefined, data with no version field is also accepted despite the return type indicating otherwise.\n * This is for legacy compatibility where older data may not have a version field.\n */\nfunction makeVersionedCodec<\n\tTDecoded,\n\tTEncoded extends Versioned = VersionedJson,\n\tTValidate = TEncoded,\n\tTContext = void,\n>(\n\tsupportedVersions: Set<FormatVersion>,\n\t{ jsonValidator: validator }: ICodecOptions,\n\tinner: IJsonCodec<TDecoded, TEncoded, TValidate, TContext>,\n): IJsonCodec<TDecoded, TEncoded, TValidate, TContext> {\n\tconst codec = {\n\t\tencode: (data: TDecoded, context: TContext): TEncoded => {\n\t\t\tconst encoded = inner.encode(data, context);\n\t\t\tassert(\n\t\t\t\tsupportedVersions.has(encoded.version),\n\t\t\t\t0x88b /* version being encoded should be supported */,\n\t\t\t);\n\t\t\treturn encoded;\n\t\t},\n\t\tdecode: (data: TValidate, context: TContext): TDecoded => {\n\t\t\tconst versioned = data as Versioned; // Validated by withSchemaValidation\n\t\t\tif (!supportedVersions.has(versioned.version)) {\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`Unsupported version ${versioned.version} encountered while decoding data. Supported versions for this data are: ${[...supportedVersions].join(\", \")}.\nThe client which encoded this data likely specified an \"minVersionForCollab\" value which corresponds to a version newer than the version of this client (\"${pkgVersion}\").`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst decoded = inner.decode(data, context);\n\t\t\treturn decoded;\n\t\t},\n\t};\n\n\t// If undefined is a supported version, skip using withSchemaValidation to enforce there is a version field.\n\t// Codec will still assert the content of the field is in supportedVersions, so it is still somewhat validated, just in a different way.\n\tif (supportedVersions.has(undefined)) {\n\t\treturn codec;\n\t}\n\n\treturn withSchemaValidation(Versioned, codec, validator);\n}\n\n/**\n * Wrap a codec with version checking and schema validation.\n * @remarks\n * The passed in codec should not perform its own schema validation.\n * The schema validation gets added here.\n */\nfunction makeVersionedValidatedCodec<\n\tEncodedSchema extends TSchema,\n\tTDecoded,\n\tTEncoded extends Versioned = VersionedJson,\n\tTValidate = TEncoded,\n\tTContext = void,\n>(\n\toptions: ICodecOptions,\n\tsupportedVersions: Set<FormatVersion>,\n\tschema: EncodedSchema,\n\tcodec: IJsonCodec<TDecoded, TEncoded, TValidate, TContext>,\n): IJsonCodec<TDecoded, TEncoded, TValidate, TContext> &\n\tPick<CodecAndSchema<TDecoded, TContext>, \"schema\"> {\n\treturn {\n\t\t...makeVersionedCodec(\n\t\t\tsupportedVersions,\n\t\t\toptions,\n\t\t\twithSchemaValidation(schema, codec, options.jsonValidator),\n\t\t),\n\t\tschema,\n\t};\n}\n\n/**\n * Creates a codec version which always throws a UsageError when encoding or decoding, indicating that the format version is discontinued.\n */\nexport function makeDiscontinuedCodecAndSchema<\n\tTDecoded,\n\tTContext,\n\tTFormatVersion extends FormatVersion = FormatVersion,\n>(\n\tdiscontinuedVersion: TFormatVersion,\n\tdiscontinuedSince: SemanticVersion,\n): CodecVersion<TDecoded, TContext, TFormatVersion> {\n\treturn {\n\t\tminVersionForCollab: undefined,\n\t\tformatVersion: discontinuedVersion,\n\t\tcodec: {\n\t\t\tschema: JsonCompatibleReadOnlySchema,\n\t\t\tencode: (_data: TDecoded) => {\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`Cannot encode data to format ${discontinuedVersion}. The codec was discontinued in Fluid Framework client version ${discontinuedSince}.`,\n\t\t\t\t);\n\t\t\t},\n\t\t\tdecode: (data: unknown) => {\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`Cannot decode data in format ${discontinuedVersion}. The codec was discontinued in Fluid Framework client version ${discontinuedSince}.`,\n\t\t\t\t);\n\t\t\t},\n\t\t},\n\t};\n}\n\n/**\n * A friendly format for codec authors use to define their codec and schema for use in {@link CodecVersion}.\n * @remarks\n * The codec should not perform its own schema validation.\n * The schema validation gets added when normalizing to {@link NormalizedCodecVersion}.\n */\nexport type CodecAndSchema<TDecoded, TContext = void> = {\n\treadonly schema: TSchema;\n} & IJsonCodec<TDecoded, VersionedJson, JsonCompatibleReadOnly, TContext>;\n\n/**\n * A codec alongside its format version and schema.\n */\nexport interface CodecVersionBase<\n\tT = unknown,\n\tTFormatVersion extends FormatVersion = FormatVersion,\n> {\n\t/**\n\t * When `undefined` the codec will never be selected as a write version except via override.\n\t * @remarks\n\t * This format will be used for decode if data in it needs to be decoded, regardless of `minVersionForCollab`.\n\t * `undefined` should be used for unstable codec versions (with string FormatVersions),\n\t * as well as previously stabilized formats that are discontinued (meaning we always prefer to use some other format for encoding).\n\t */\n\treadonly minVersionForCollab: MinimumVersionForCollab | undefined;\n\treadonly formatVersion: TFormatVersion;\n\treadonly codec: T;\n}\n\n/**\n * A particular version of a codec and when to use it.\n * @privateRemarks\n * This allows lazy building of the codec with options.\n * This option can likely be removed as the codec handling is made simpler and more consistent.\n * Removing support for this laziness would be nice to help prevent unexpected coupling and alteration to codec behavior,\n * helping ensure that tests and production code behave the same.\n */\nexport interface CodecVersion<\n\tTDecoded,\n\tTContext,\n\tTFormatVersion extends FormatVersion,\n\tTBuildOptions extends ICodecOptions = ICodecOptions,\n> extends CodecVersionBase<\n\t\t| CodecAndSchema<TDecoded, TContext>\n\t\t| ((options: TBuildOptions) => CodecAndSchema<TDecoded, TContext>),\n\t\tTFormatVersion\n\t> {}\n\n/**\n * {@link CodecVersion} after normalization into a consistent type.\n * @remarks\n * Produced by {@link normalizeCodecVersion}.\n * Includes schema validation.\n */\nexport interface NormalizedCodecVersion<\n\tTDecoded,\n\tTContext,\n\tTFormatVersion extends FormatVersion,\n\tTBuildOptions extends ICodecOptions,\n> extends CodecVersionBase<\n\t\t(options: TBuildOptions) => CodecAndSchema<TDecoded, TContext>,\n\t\tTFormatVersion\n\t> {}\n\n/**\n * {@link NormalizedCodecVersion} after applying the build options.\n * @remarks\n * Produced by {@link ClientVersionDispatchingCodecBuilder.applyOptions}.\n */\ninterface EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion extends FormatVersion>\n\textends CodecVersionBase<CodecAndSchema<TDecoded, TContext>, TFormatVersion> {}\n\n/**\n * Normalize the codec to a single format.\n * @remarks\n * Bakes in schema validation, so output no longer exposes the schema.\n */\nfunction normalizeCodecVersion<\n\tTDecoded,\n\tTContext,\n\tTFormatVersion extends FormatVersion,\n\tTBuildOptions extends ICodecOptions,\n>(\n\tcodecVersion: CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>,\n): NormalizedCodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions> {\n\tconst codecBuilder: (options: TBuildOptions) => CodecAndSchema<TDecoded, TContext> =\n\t\ttypeof codecVersion.codec === \"function\"\n\t\t\t? codecVersion.codec\n\t\t\t: () => codecVersion.codec as CodecAndSchema<TDecoded, TContext>;\n\tconst codec = (options: TBuildOptions): CodecAndSchema<TDecoded, TContext> => {\n\t\tconst built = codecBuilder(options);\n\t\treturn makeVersionedValidatedCodec(\n\t\t\toptions,\n\t\t\tnew Set([codecVersion.formatVersion]),\n\t\t\tbuilt.schema,\n\t\t\tbuilt,\n\t\t);\n\t};\n\n\treturn {\n\t\tminVersionForCollab: codecVersion.minVersionForCollab,\n\t\tformatVersion: codecVersion.formatVersion,\n\t\tcodec,\n\t};\n}\n\n/**\n * Creates a codec which dispatches to the appropriate member of a codec family based on the `minVersionForCollab` for encode and the\n * version number in data it encounters for decode.\n * @privateRemarks\n * This is a two stage builder so the first stage can encapsulate all codec specific details and the second can bring in configuration.\n */\nexport class ClientVersionDispatchingCodecBuilder<\n\tTBuildOptions extends ICodecOptions = ICodecOptions,\n\tTDecoded = unknown,\n\tTContext = unknown,\n\tTFormatVersion extends FormatVersion = FormatVersion,\n\tTName extends CodecName = string,\n> {\n\tpublic readonly registry: readonly NormalizedCodecVersion<\n\t\tTDecoded,\n\t\tTContext,\n\t\tTFormatVersion,\n\t\tTBuildOptions\n\t>[];\n\n\t/**\n\t * Use {@link ClientVersionDispatchingCodecBuilder.build} to create an instance of this class.\n\t * @remarks\n\t * Inputs to this are assumed to be constants in the code controlled by the developers of this package,\n\t * and constructed at least once during tests.\n\t * Because of this, the validation of these inputs done with debugAssert should be sufficient,\n\t * and using debugAssert avoids bloating the bundle size for production users.\n\t */\n\tprivate constructor(\n\t\t/**\n\t\t * See {@link CodecName}.\n\t\t */\n\t\tpublic readonly name: TName,\n\t\t/**\n\t\t * The registry of codecs which this builder can use to encode and decode data.\n\t\t */\n\t\tinputRegistry: readonly CodecVersion<TDecoded, TContext, TFormatVersion, TBuildOptions>[],\n\t) {\n\t\ttype Normalized = NormalizedCodecVersion<\n\t\t\tTDecoded,\n\t\t\tTContext,\n\t\t\tTFormatVersion,\n\t\t\tTBuildOptions\n\t\t>;\n\t\tconst normalizedRegistry: Normalized[] = [];\n\t\tconst formats: Set<FormatVersion> = new Set();\n\t\tconst versions: Set<string | undefined> = new Set();\n\n\t\tfor (const codec of inputRegistry) {\n\t\t\tdebugAssert(\n\t\t\t\t() =>\n\t\t\t\t\t!formats.has(codec.formatVersion) ||\n\t\t\t\t\t`duplicate codec format ${name} ${codec.formatVersion}`,\n\t\t\t);\n\t\t\tdebugAssert(\n\t\t\t\t() =>\n\t\t\t\t\tcodec.minVersionForCollab === undefined ||\n\t\t\t\t\ttypeof codec.formatVersion !== \"string\" ||\n\t\t\t\t\t`unstable format ${JSON.stringify(codec.formatVersion)} (string formats) must not have a minVersionForCollab in ${name}`,\n\t\t\t);\n\t\t\tformats.add(codec.formatVersion);\n\t\t\tconst normalizedCodec = normalizeCodecVersion(codec);\n\t\t\tnormalizedRegistry.push(normalizedCodec);\n\t\t\tif (codec.minVersionForCollab !== undefined) {\n\t\t\t\tdebugAssert(\n\t\t\t\t\t() =>\n\t\t\t\t\t\t!versions.has(codec.minVersionForCollab) ||\n\t\t\t\t\t\t`Codec ${name} has multiple entries for version ${JSON.stringify(codec.minVersionForCollab)}`,\n\t\t\t\t);\n\t\t\t\tversions.add(codec.minVersionForCollab);\n\t\t\t}\n\t\t}\n\n\t\tdebugAssert(\n\t\t\t() =>\n\t\t\t\tversions.has(lowestMinVersionForCollab) ||\n\t\t\t\t`Codec ${name} is missing entry for lowestMinVersionForCollab`,\n\t\t);\n\n\t\tthis.registry = normalizedRegistry;\n\t}\n\n\t/**\n\t * Applies the provided options to the codec registry to produce a list of evaluated codecs.\n\t * @remarks\n\t * This is used by build, which is what production code should use.\n\t * This is only exposed for testing purposes.\n\t */\n\tpublic applyOptions(\n\t\toptions: TBuildOptions,\n\t): EvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>[] {\n\t\treturn this.registry.map((codec) => ({\n\t\t\tminVersionForCollab: codec.minVersionForCollab,\n\t\t\tformatVersion: codec.formatVersion,\n\t\t\tcodec: codec.codec(options),\n\t\t}));\n\t}\n\n\t/**\n\t * Produce a single codec which can read any supported format, and writes a version selected based on the provided options.\n\t */\n\tpublic build(options: TBuildOptions & CodecWriteOptions): IJsonCodec<\n\t\tTDecoded,\n\t\tJsonCompatibleReadOnly,\n\t\tJsonCompatibleReadOnly,\n\t\tTContext\n\t> & {\n\t\t/**\n\t\t * The format version which this codec writes.\n\t\t * @remarks\n\t\t * This is selected based on the provided {@link CodecWriteOptions}.\n\t\t */\n\t\treadonly writeVersion: TFormatVersion;\n\t} {\n\t\tconst [applied, decoder] = this.buildDecoderInternal(options);\n\t\tconst writeVersion = getWriteVersion(this.name, options, applied);\n\t\treturn {\n\t\t\t...decoder,\n\t\t\tencode: (data: TDecoded, context: TContext): JsonCompatibleReadOnly => {\n\t\t\t\treturn writeVersion.codec.encode(data, context);\n\t\t\t},\n\t\t\twriteVersion: writeVersion.formatVersion,\n\t\t};\n\t}\n\n\tprivate buildDecoderInternal(\n\t\toptions: TBuildOptions,\n\t): [\n\t\tEvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>[],\n\t\tPick<\n\t\t\tIJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,\n\t\t\t\"decode\"\n\t\t>,\n\t] {\n\t\tconst applied = this.applyOptions(options);\n\t\tconst fromFormatVersion = new Map<\n\t\t\tFormatVersion,\n\t\t\tEvaluatedCodecVersion<TDecoded, TContext, TFormatVersion>\n\t\t>(applied.map((codec) => [codec.formatVersion, codec]));\n\t\treturn [\n\t\t\tapplied,\n\t\t\t{\n\t\t\t\tdecode: (data: JsonCompatibleReadOnly, context: TContext): TDecoded => {\n\t\t\t\t\tconst versioned = data as Partial<Versioned>;\n\t\t\t\t\tconst codec = fromFormatVersion.get(versioned.version);\n\t\t\t\t\tif (codec === undefined) {\n\t\t\t\t\t\tthrow new UsageError(\n\t\t\t\t\t\t\t`Unsupported version ${versioned.version} encountered while decoding ${this.name} data. Supported versions for this data are: ${versionList(applied)}.\nThe client which encoded this data likely specified an \"minVersionForCollab\" value which corresponds to a version newer than the version of this client (\"${pkgVersion}\").`,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\treturn codec.codec.decode(data, context);\n\t\t\t\t},\n\t\t\t},\n\t\t];\n\t}\n\n\t/**\n\t * Produce a single codec which can read any supported format.\n\t */\n\tpublic buildDecoder(\n\t\toptions: TBuildOptions,\n\t): Pick<\n\t\tIJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,\n\t\t\"decode\"\n\t> {\n\t\treturn this.buildDecoderInternal(options)[1];\n\t}\n\n\tpublic getCodecTree(clientVersion: MinimumVersionForCollab): CodecTree<TFormatVersion> {\n\t\t// TODO: add support for children codecs.\n\t\tconst selected = getWriteVersionNoOverrides(this.registry, clientVersion);\n\t\treturn {\n\t\t\tname: this.name,\n\t\t\tversion: selected.formatVersion,\n\t\t};\n\t}\n\n\t/**\n\t * Builds a ClientVersionDispatchingCodecBuilder from the provided registry.\n\t * @remarks\n\t * This static method infers the types of the builder from the provided registry,\n\t * making it easier to create builders without needing to explicitly specify all type parameters.\n\t * This gets better type inference than the constructor.\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic static build<\n\t\tName extends CodecName,\n\t\tEntry extends CodecVersion<unknown, unknown, FormatVersion, never>,\n\t>(name: Name, inputRegistry: readonly Entry[]) {\n\t\ttype TDecoded2 =\n\t\t\tEntry extends CodecVersion<infer D, unknown, FormatVersion, never> ? D : never;\n\t\ttype TContext2 =\n\t\t\tEntry extends CodecVersion<unknown, infer C, FormatVersion, never> ? C : never;\n\t\ttype TFormatVersion2 =\n\t\t\tEntry extends CodecVersion<unknown, unknown, infer F, never> ? F : never;\n\t\ttype TBuildOptions2 =\n\t\t\tEntry extends CodecVersion<unknown, unknown, FormatVersion, infer B> ? B : never;\n\n\t\ttype CodecFinal = CodecVersion<\n\t\t\tTDecoded2,\n\t\t\t// If it does not matter what context is provided, undefined is fine, so allow it to be omitted.\n\t\t\tunknown extends TContext2 ? void : TContext2,\n\t\t\tTFormatVersion2,\n\t\t\tTBuildOptions2\n\t\t>;\n\n\t\tconst input = inputRegistry as readonly unknown[] as readonly CodecFinal[];\n\n\t\tconst builder = new ClientVersionDispatchingCodecBuilder<\n\t\t\tTBuildOptions2,\n\t\t\tTDecoded2,\n\t\t\tunknown extends TContext2 ? void : TContext2,\n\t\t\tTFormatVersion2,\n\t\t\tName\n\t\t>(name, input);\n\t\treturn builder;\n\t}\n}\n\n/**\n * Selects which format should be used when writing data.\n * @remarks\n * This either uses the override specified in the options, or selects the newest format compatible with the provided minVersionForCollab.\n */\nfunction getWriteVersion<T extends CodecVersionBase>(\n\tname: CodecName,\n\toptions: CodecWriteOptions,\n\tversions: readonly T[],\n): T {\n\tif (options.writeVersionOverrides?.has(name) === true) {\n\t\tconst selectedFormatVersion = options.writeVersionOverrides.get(name);\n\t\tconst selected = versions.find((codec) => codec.formatVersion === selectedFormatVersion);\n\t\tif (selected === undefined) {\n\t\t\tthrow new UsageError(\n\t\t\t\t`Codec \"${name}\" does not support requested format version ${JSON.stringify(selectedFormatVersion)}. Supported versions are: ${versionList(versions)}.`,\n\t\t\t);\n\t\t} else if (options.allowPossiblyIncompatibleWriteVersionOverrides !== true) {\n\t\t\tconst selectedMinVersionForCollab = selected.minVersionForCollab;\n\t\t\tif (selectedMinVersionForCollab === undefined) {\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`Codec \"${name}\" does not support requested format version ${JSON.stringify(selectedFormatVersion)} because it has minVersionForCollab undefined. Use \"allowPossiblyIncompatibleWriteVersionOverrides\" to suppress this error if appropriate.`,\n\t\t\t\t);\n\t\t\t} else if (gt(selectedMinVersionForCollab, options.minVersionForCollab)) {\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`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.`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\treturn selected;\n\t}\n\n\treturn getWriteVersionNoOverrides(versions, options.minVersionForCollab);\n}\n\n/**\n * Selects which format should be used when writing data, without consider overrides.\n */\nfunction getWriteVersionNoOverrides<T extends CodecVersionBase>(\n\tversions: readonly T[],\n\tminVersionForCollab: MinimumVersionForCollab,\n): T {\n\tconst stableVersions: [MinimumMinorSemanticVersion | MinimumVersionForCollab, T][] = [];\n\tfor (const version of versions) {\n\t\tif (version.minVersionForCollab !== undefined) {\n\t\t\tstableVersions.push([version.minVersionForCollab, version]);\n\t\t}\n\t}\n\n\tconst result: T = getConfigForMinVersionForCollabIterable(\n\t\tminVersionForCollab,\n\t\tstableVersions,\n\t);\n\treturn result;\n}\n\n/**\n * Formats a list of versions for use in UsageErrors.\n */\nfunction versionList(versions: readonly CodecVersionBase[]): string {\n\treturn JSON.stringify(Array.from(versions, (codec) => codec.formatVersion));\n}\n"]}
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../../src/codec/versioned/codec.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert, debugAssert } from \"@fluidframework/core-utils/internal\";\nimport type { MinimumVersionForCollab } from \"@fluidframework/runtime-definitions/internal\";\nimport {\n\tgetConfigForMinVersionForCollabIterable,\n\tlowestMinVersionForCollab,\n\ttype MinimumMinorSemanticVersion,\n\ttype SemanticVersion,\n} from \"@fluidframework/runtime-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport type { TSchema } from \"@sinclair/typebox\";\nimport { gt } from \"semver-ts\";\n\nimport { pkgVersion } from \"../../packageVersion.js\";\nimport {\n\tJsonCompatibleReadOnlySchema,\n\ttype JsonCompatibleReadOnly,\n\ttype JsonCompatibleReadOnlyObject,\n} from \"../../util/index.js\";\nimport {\n\ttype ICodecOptions,\n\ttype IJsonCodec,\n\twithSchemaValidation,\n\ttype FormatVersion,\n\ttype CodecWriteOptions,\n\ttype CodecName,\n\ttype CodecTree,\n} from \"../codec.js\";\n\nimport { Versioned } from \"./format.js\";\n\n/**\n * Json compatible data with a format version.\n */\ntype VersionedJson = JsonCompatibleReadOnlyObject & Versioned;\n\n/**\n * Validate that the version is one of the supported values.\n * @remarks\n * If supportedVersions contains undefined, data with no version field is also accepted despite the return type indicating otherwise.\n * This is for legacy compatibility where older data may not have a version field.\n */\nfunction makeVersionedCodec<\n\tTDecoded,\n\tTEncoded extends Versioned = VersionedJson,\n\tTValidate = TEncoded,\n\tTEncodeContext = void,\n\tTDecodeContext = TEncodeContext,\n>(\n\tsupportedVersions: Set<FormatVersion>,\n\t{ jsonValidator: validator }: ICodecOptions,\n\tinner: IJsonCodec<TDecoded, TEncoded, TValidate, TEncodeContext, TDecodeContext>,\n): IJsonCodec<TDecoded, TEncoded, TValidate, TEncodeContext, TDecodeContext> {\n\tconst codec = {\n\t\tencode: (data: TDecoded, context: TEncodeContext): TEncoded => {\n\t\t\tconst encoded = inner.encode(data, context);\n\t\t\tassert(\n\t\t\t\tsupportedVersions.has(encoded.version),\n\t\t\t\t0x88b /* version being encoded should be supported */,\n\t\t\t);\n\t\t\treturn encoded;\n\t\t},\n\t\tdecode: (data: TValidate, context: TDecodeContext): TDecoded => {\n\t\t\tconst versioned = data as Versioned; // Validated by withSchemaValidation\n\t\t\tif (!supportedVersions.has(versioned.version)) {\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`Unsupported version ${versioned.version} encountered while decoding data. Supported versions for this data are: ${[...supportedVersions].join(\", \")}.\nThe client which encoded this data likely specified an \"minVersionForCollab\" value which corresponds to a version newer than the version of this client (\"${pkgVersion}\").`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst decoded = inner.decode(data, context);\n\t\t\treturn decoded;\n\t\t},\n\t};\n\n\t// If undefined is a supported version, skip using withSchemaValidation to enforce there is a version field.\n\t// Codec will still assert the content of the field is in supportedVersions, so it is still somewhat validated, just in a different way.\n\tif (supportedVersions.has(undefined)) {\n\t\treturn codec;\n\t}\n\n\treturn withSchemaValidation(Versioned, codec, validator);\n}\n\n/**\n * Wrap a codec with version checking and schema validation.\n * @remarks\n * The passed in codec should not perform its own schema validation.\n * The schema validation gets added here.\n */\nfunction makeVersionedValidatedCodec<\n\tEncodedSchema extends TSchema,\n\tTDecoded,\n\tTEncoded extends Versioned = VersionedJson,\n\tTValidate = TEncoded,\n\tTEncodeContext = void,\n\tTDecodeContext = TEncodeContext,\n>(\n\toptions: ICodecOptions,\n\tsupportedVersions: Set<FormatVersion>,\n\tschema: EncodedSchema,\n\tcodec: IJsonCodec<TDecoded, TEncoded, TValidate, TEncodeContext, TDecodeContext>,\n): IJsonCodec<TDecoded, TEncoded, TValidate, TEncodeContext, TDecodeContext> &\n\tPick<CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext>, \"schema\"> {\n\treturn {\n\t\t...makeVersionedCodec(\n\t\t\tsupportedVersions,\n\t\t\toptions,\n\t\t\twithSchemaValidation(schema, codec, options.jsonValidator),\n\t\t),\n\t\tschema,\n\t};\n}\n\n/**\n * Creates a codec version which always throws a UsageError when encoding or decoding, indicating that the format version is discontinued.\n */\nexport function makeDiscontinuedCodecAndSchema<\n\tTDecoded,\n\tTFormatVersion extends FormatVersion = FormatVersion,\n>(\n\tdiscontinuedVersion: TFormatVersion,\n\tdiscontinuedSince: SemanticVersion,\n): CodecVersion<TDecoded, unknown, TFormatVersion, ICodecOptions, unknown> {\n\treturn {\n\t\tminVersionForCollab: undefined,\n\t\tformatVersion: discontinuedVersion,\n\t\tcodec: {\n\t\t\tschema: JsonCompatibleReadOnlySchema,\n\t\t\tencode: (_data: TDecoded) => {\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`Cannot encode data to format ${discontinuedVersion}. The codec was discontinued in Fluid Framework client version ${discontinuedSince}.`,\n\t\t\t\t);\n\t\t\t},\n\t\t\tdecode: (data: unknown) => {\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`Cannot decode data in format ${discontinuedVersion}. The codec was discontinued in Fluid Framework client version ${discontinuedSince}.`,\n\t\t\t\t);\n\t\t\t},\n\t\t},\n\t};\n}\n\n/**\n * A friendly format for codec authors use to define their codec and schema for use in {@link CodecVersion}.\n * @remarks\n * The codec should not perform its own schema validation.\n * The schema validation gets added when normalizing to {@link NormalizedCodecVersion}.\n */\nexport type CodecAndSchema<\n\tTDecoded,\n\tTEncodeContext = void,\n\tTDecodeContext = TEncodeContext,\n> = {\n\treadonly schema: TSchema;\n} & IJsonCodec<\n\tTDecoded,\n\tVersionedJson,\n\tJsonCompatibleReadOnly,\n\tTEncodeContext,\n\tTDecodeContext\n>;\n\n/**\n * A codec alongside its format version and schema.\n */\nexport interface CodecVersionBase<\n\tT = unknown,\n\tTFormatVersion extends FormatVersion = FormatVersion,\n> {\n\t/**\n\t * When `undefined` the codec will never be selected as a write version except via override.\n\t * @remarks\n\t * This format will be used for decode if data in it needs to be decoded, regardless of `minVersionForCollab`.\n\t * `undefined` should be used for unstable codec versions (with string FormatVersions),\n\t * as well as previously stabilized formats that are discontinued (meaning we always prefer to use some other format for encoding).\n\t */\n\treadonly minVersionForCollab: MinimumVersionForCollab | undefined;\n\treadonly formatVersion: TFormatVersion;\n\treadonly codec: T;\n}\n\n/**\n * A particular version of a codec and when to use it.\n * @privateRemarks\n * This allows lazy building of the codec with options.\n * This option can likely be removed as the codec handling is made simpler and more consistent.\n * Removing support for this laziness would be nice to help prevent unexpected coupling and alteration to codec behavior,\n * helping ensure that tests and production code behave the same.\n */\nexport interface CodecVersion<\n\tTDecoded,\n\tTEncodeContext,\n\tTFormatVersion extends FormatVersion,\n\tTBuildOptions extends ICodecOptions = ICodecOptions,\n\tTDecodeContext = TEncodeContext,\n> extends CodecVersionBase<\n\t\t| CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext>\n\t\t| ((options: TBuildOptions) => CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext>),\n\t\tTFormatVersion\n\t> {}\n\n/**\n * {@link CodecVersion} after normalization into a consistent type.\n * @remarks\n * Produced by {@link normalizeCodecVersion}.\n * Includes schema validation.\n */\nexport interface NormalizedCodecVersion<\n\tTDecoded,\n\tTEncodeContext,\n\tTFormatVersion extends FormatVersion,\n\tTBuildOptions extends ICodecOptions,\n\tTDecodeContext = TEncodeContext,\n> extends CodecVersionBase<\n\t\t(options: TBuildOptions) => CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext>,\n\t\tTFormatVersion\n\t> {}\n\n/**\n * {@link NormalizedCodecVersion} after applying the build options.\n * @remarks\n * Produced by {@link VersionDispatchingCodecBuilder.applyOptions}.\n */\ninterface EvaluatedCodecVersion<\n\tTDecoded,\n\tTEncodeContext,\n\tTFormatVersion extends FormatVersion,\n\tTDecodeContext = TEncodeContext,\n> extends CodecVersionBase<\n\t\tCodecAndSchema<TDecoded, TEncodeContext, TDecodeContext>,\n\t\tTFormatVersion\n\t> {}\n\n/**\n * Normalize the codec to a single format.\n * @remarks\n * Bakes in schema validation, so output no longer exposes the schema.\n */\nfunction normalizeCodecVersion<\n\tTDecoded,\n\tTEncodeContext,\n\tTFormatVersion extends FormatVersion,\n\tTBuildOptions extends ICodecOptions,\n\tTDecodeContext = TEncodeContext,\n>(\n\tcodecVersion: CodecVersion<\n\t\tTDecoded,\n\t\tTEncodeContext,\n\t\tTFormatVersion,\n\t\tTBuildOptions,\n\t\tTDecodeContext\n\t>,\n): NormalizedCodecVersion<\n\tTDecoded,\n\tTEncodeContext,\n\tTFormatVersion,\n\tTBuildOptions,\n\tTDecodeContext\n> {\n\tconst codecBuilder: (\n\t\toptions: TBuildOptions,\n\t) => CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext> =\n\t\ttypeof codecVersion.codec === \"function\"\n\t\t\t? codecVersion.codec\n\t\t\t: () => codecVersion.codec as CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext>;\n\tconst codec = (\n\t\toptions: TBuildOptions,\n\t): CodecAndSchema<TDecoded, TEncodeContext, TDecodeContext> => {\n\t\tconst built = codecBuilder(options);\n\t\treturn makeVersionedValidatedCodec(\n\t\t\toptions,\n\t\t\tnew Set([codecVersion.formatVersion]),\n\t\t\tbuilt.schema,\n\t\t\tbuilt,\n\t\t);\n\t};\n\n\treturn {\n\t\tminVersionForCollab: codecVersion.minVersionForCollab,\n\t\tformatVersion: codecVersion.formatVersion,\n\t\tcodec,\n\t};\n}\n\n/**\n * A codec that can read multiple format versions and write a single selected version.\n * @remarks\n * Produced by {@link VersionDispatchingCodecBuilder.build}.\n *\n * @typeParam TDecoded - The in memory (not encoded) format.\n * @typeParam TEncodeContext - Context type passed to encode operations.\n * @typeParam TFormatVersion - The type of format version identifiers used by this codec.\n * @typeParam TDecodeContext - Context type passed to decode operations. Defaults to `TEncodeContext`.\n */\nexport interface VersionDispatchingCodec<\n\tTDecoded,\n\tTEncodeContext,\n\tTFormatVersion extends FormatVersion,\n\tTDecodeContext = TEncodeContext,\n> extends IJsonCodec<\n\t\tTDecoded,\n\t\tJsonCompatibleReadOnly,\n\t\tJsonCompatibleReadOnly,\n\t\tTEncodeContext,\n\t\tTDecodeContext\n\t> {\n\t/**\n\t * The format version which this codec writes.\n\t * @remarks\n\t * Selected by {@link VersionDispatchingCodecBuilder.build} based on the provided options.\n\t */\n\treadonly writeVersion: TFormatVersion;\n}\n\n/**\n * Creates a {@link VersionDispatchingCodec} using a {@link CodecVersion} to select the {@link VersionDispatchingCodec.writeVersion}.\n * @privateRemarks\n * This is a two stage builder so the first stage (the static build) can encapsulate all codec specific details and\n * the second (the instance build) can bring in configuration.\n */\nexport class VersionDispatchingCodecBuilder<\n\tTBuildOptions extends ICodecOptions = ICodecOptions,\n\tTDecoded = unknown,\n\tTEncodeContext = unknown,\n\tTFormatVersion extends FormatVersion = FormatVersion,\n\tTName extends CodecName = string,\n\tTDecodeContext = TEncodeContext,\n> {\n\tpublic readonly registry: readonly NormalizedCodecVersion<\n\t\tTDecoded,\n\t\tTEncodeContext,\n\t\tTFormatVersion,\n\t\tTBuildOptions,\n\t\tTDecodeContext\n\t>[];\n\n\t/**\n\t * Use {@link VersionDispatchingCodecBuilder.build} to create an instance of this class.\n\t * @remarks\n\t * Inputs to this are assumed to be constants in the code controlled by the developers of this package,\n\t * and constructed at least once during tests.\n\t * Because of this, the validation of these inputs done with debugAssert should be sufficient,\n\t * and using debugAssert avoids bloating the bundle size for production users.\n\t */\n\tprivate constructor(\n\t\t/**\n\t\t * See {@link CodecName}.\n\t\t */\n\t\tpublic readonly name: TName,\n\t\t/**\n\t\t * The registry of codecs which this builder can use to encode and decode data.\n\t\t */\n\t\tinputRegistry: readonly CodecVersion<\n\t\t\tTDecoded,\n\t\t\tTEncodeContext,\n\t\t\tTFormatVersion,\n\t\t\tTBuildOptions,\n\t\t\tTDecodeContext\n\t\t>[],\n\t) {\n\t\ttype Normalized = NormalizedCodecVersion<\n\t\t\tTDecoded,\n\t\t\tTEncodeContext,\n\t\t\tTFormatVersion,\n\t\t\tTBuildOptions,\n\t\t\tTDecodeContext\n\t\t>;\n\t\tconst normalizedRegistry: Normalized[] = [];\n\t\tconst formats: Set<FormatVersion> = new Set();\n\t\tconst versions: Set<string | undefined> = new Set();\n\n\t\tfor (const codec of inputRegistry) {\n\t\t\tdebugAssert(\n\t\t\t\t() =>\n\t\t\t\t\t!formats.has(codec.formatVersion) ||\n\t\t\t\t\t`duplicate codec format ${name} ${codec.formatVersion}`,\n\t\t\t);\n\t\t\tdebugAssert(\n\t\t\t\t() =>\n\t\t\t\t\tcodec.minVersionForCollab === undefined ||\n\t\t\t\t\ttypeof codec.formatVersion !== \"string\" ||\n\t\t\t\t\t`unstable format ${JSON.stringify(codec.formatVersion)} (string formats) must not have a minVersionForCollab in ${name}`,\n\t\t\t);\n\t\t\tformats.add(codec.formatVersion);\n\t\t\tconst normalizedCodec = normalizeCodecVersion(codec);\n\t\t\tnormalizedRegistry.push(normalizedCodec);\n\t\t\tif (codec.minVersionForCollab !== undefined) {\n\t\t\t\tdebugAssert(\n\t\t\t\t\t() =>\n\t\t\t\t\t\t!versions.has(codec.minVersionForCollab) ||\n\t\t\t\t\t\t`Codec ${name} has multiple entries for version ${JSON.stringify(codec.minVersionForCollab)}`,\n\t\t\t\t);\n\t\t\t\tversions.add(codec.minVersionForCollab);\n\t\t\t}\n\t\t}\n\n\t\tdebugAssert(\n\t\t\t() =>\n\t\t\t\tversions.has(lowestMinVersionForCollab) ||\n\t\t\t\t`Codec ${name} is missing entry for lowestMinVersionForCollab`,\n\t\t);\n\n\t\tthis.registry = normalizedRegistry;\n\t}\n\n\t/**\n\t * Applies `options` to the codec registry to produce a list of evaluated codecs.\n\t * @remarks\n\t * This is used by build, which is what production code should use.\n\t * This is only exposed for testing purposes.\n\t */\n\tpublic applyOptions(\n\t\toptions: TBuildOptions,\n\t): EvaluatedCodecVersion<TDecoded, TEncodeContext, TFormatVersion, TDecodeContext>[] {\n\t\treturn this.registry.map((codec) => ({\n\t\t\tminVersionForCollab: codec.minVersionForCollab,\n\t\t\tformatVersion: codec.formatVersion,\n\t\t\tcodec: codec.codec(options),\n\t\t}));\n\t}\n\n\t/**\n\t * Builds a complete {@link VersionDispatchingCodec} that can decode all registered versions\n\t * and encode a version selected by the provided options.\n\t */\n\tpublic build(\n\t\toptions: TBuildOptions & CodecWriteOptions,\n\t): VersionDispatchingCodec<TDecoded, TEncodeContext, TFormatVersion, TDecodeContext> {\n\t\tconst [applied, decoder] = this.buildDecoderInternal(options);\n\t\tconst writeVersion = getWriteVersion(this.name, options, applied);\n\t\treturn {\n\t\t\t...decoder,\n\t\t\tencode: (data: TDecoded, context: TEncodeContext): JsonCompatibleReadOnly => {\n\t\t\t\treturn writeVersion.codec.encode(data, context);\n\t\t\t},\n\t\t\twriteVersion: writeVersion.formatVersion,\n\t\t};\n\t}\n\n\tprivate buildDecoderInternal(\n\t\toptions: TBuildOptions,\n\t): [\n\t\tEvaluatedCodecVersion<TDecoded, TEncodeContext, TFormatVersion, TDecodeContext>[],\n\t\tPick<\n\t\t\tIJsonCodec<\n\t\t\t\tTDecoded,\n\t\t\t\tJsonCompatibleReadOnly,\n\t\t\t\tJsonCompatibleReadOnly,\n\t\t\t\tTEncodeContext,\n\t\t\t\tTDecodeContext\n\t\t\t>,\n\t\t\t\"decode\"\n\t\t>,\n\t] {\n\t\tconst applied = this.applyOptions(options);\n\t\tconst fromFormatVersion = new Map<\n\t\t\tFormatVersion,\n\t\t\tEvaluatedCodecVersion<TDecoded, TEncodeContext, TFormatVersion, TDecodeContext>\n\t\t>(applied.map((codec) => [codec.formatVersion, codec]));\n\t\treturn [\n\t\t\tapplied,\n\t\t\t{\n\t\t\t\tdecode: (data: JsonCompatibleReadOnly, context: TDecodeContext): TDecoded => {\n\t\t\t\t\tconst versioned = data as Partial<Versioned>;\n\t\t\t\t\tconst codec = fromFormatVersion.get(versioned.version);\n\t\t\t\t\tif (codec === undefined) {\n\t\t\t\t\t\tthrow new UsageError(\n\t\t\t\t\t\t\t`Unsupported version ${versioned.version} encountered while decoding ${this.name} data. Supported versions for this data are: ${versionList(applied)}.\nThe client which encoded this data likely specified an \"minVersionForCollab\" value which corresponds to a version newer than the version of this client (\"${pkgVersion}\").`,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\treturn codec.codec.decode(data, context);\n\t\t\t\t},\n\t\t\t},\n\t\t];\n\t}\n\n\t/**\n\t * Builds a decoder-only codec that can decode any supported format without encoding capability.\n\t *\n\t * @remarks\n\t * The returned codec contains only the `decode` method and can be used when only decoding is needed.\n\t * This is useful for scenarios where reading/decoding versioned data is sufficient.\n\t *\n\t * @param options - Build options (typically containing the `jsonValidator`)\n\t * @returns An object with a `decode` method that can handle any supported format version\n\t */\n\tpublic buildDecoder(\n\t\toptions: TBuildOptions,\n\t): Pick<\n\t\tVersionDispatchingCodec<TDecoded, TEncodeContext, TFormatVersion, TDecodeContext>,\n\t\t\"decode\"\n\t> {\n\t\treturn this.buildDecoderInternal(options)[1];\n\t}\n\n\tpublic getCodecTree(clientVersion: MinimumVersionForCollab): CodecTree<TFormatVersion> {\n\t\t// TODO: add support for children codecs.\n\t\tconst selected = getWriteVersionNoOverrides(this.registry, clientVersion);\n\t\treturn {\n\t\t\tname: this.name,\n\t\t\tversion: selected.formatVersion,\n\t\t};\n\t}\n\n\t/**\n\t * Creates a new VersionDispatchingCodecBuilder from the provided codec registry.\n\t *\n\t * @remarks\n\t * This static method infers the types of the builder from the provided registry,\n\t * making it easier to create builders without needing to explicitly specify all type parameters.\n\t * This gets better type inference than the constructor.\n\t *\n\t * @example\n\t * ```typescript\n\t * const builder = VersionDispatchingCodecBuilder.build('myCodec', [\n\t *   { minVersionForCollab: lowestMinVersionForCollab, formatVersion: 1, codec: { encode, decode, schema } },\n\t *   { minVersionForCollab: '2.100.0', formatVersion: 2, codec: { encode, decode, schema } },\n\t * ]);\n\t * ```\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic static build<\n\t\tName extends CodecName,\n\t\tEntry extends CodecVersion<unknown, unknown, FormatVersion, never, unknown>,\n\t>(name: Name, inputRegistry: readonly Entry[]) {\n\t\ttype TDecoded2 =\n\t\t\tEntry extends CodecVersion<infer D, unknown, FormatVersion, never, unknown> ? D : never;\n\t\ttype TEncodeContext2 =\n\t\t\tEntry extends CodecVersion<unknown, infer C, FormatVersion, never, unknown> ? C : never;\n\t\ttype TFormatVersion2 =\n\t\t\tEntry extends CodecVersion<unknown, unknown, infer F, never, unknown> ? F : never;\n\t\ttype TBuildOptions2 =\n\t\t\tEntry extends CodecVersion<unknown, unknown, FormatVersion, infer B, unknown>\n\t\t\t\t? B\n\t\t\t\t: never;\n\t\ttype TDecodeContext2 =\n\t\t\tEntry extends CodecVersion<unknown, unknown, FormatVersion, never, infer D> ? D : never;\n\n\t\ttype ResolvedEncodeContext = unknown extends TEncodeContext2 ? void : TEncodeContext2;\n\t\ttype ResolvedDecodeContext = unknown extends TDecodeContext2\n\t\t\t? ResolvedEncodeContext\n\t\t\t: TDecodeContext2;\n\n\t\ttype CodecFinal = CodecVersion<\n\t\t\tTDecoded2,\n\t\t\t// If it does not matter what context is provided, undefined is fine, so allow it to be omitted.\n\t\t\tResolvedEncodeContext,\n\t\t\tTFormatVersion2,\n\t\t\tTBuildOptions2,\n\t\t\tResolvedDecodeContext\n\t\t>;\n\n\t\tconst input = inputRegistry as readonly unknown[] as readonly CodecFinal[];\n\n\t\tconst builder = new VersionDispatchingCodecBuilder<\n\t\t\tTBuildOptions2,\n\t\t\tTDecoded2,\n\t\t\tResolvedEncodeContext,\n\t\t\tTFormatVersion2,\n\t\t\tName,\n\t\t\tResolvedDecodeContext\n\t\t>(name, input);\n\t\treturn builder;\n\t}\n}\n\n/**\n * Selects which format should be used when writing data.\n * @remarks\n * This either uses the override specified in the options, or selects the newest format compatible with the provided minVersionForCollab.\n */\nfunction getWriteVersion<T extends CodecVersionBase>(\n\tname: CodecName,\n\toptions: CodecWriteOptions,\n\tversions: readonly T[],\n): T {\n\tif (options.writeVersionOverrides?.has(name) === true) {\n\t\tconst selectedFormatVersion = options.writeVersionOverrides.get(name);\n\t\tconst selected = versions.find((codec) => codec.formatVersion === selectedFormatVersion);\n\t\tif (selected === undefined) {\n\t\t\tthrow new UsageError(\n\t\t\t\t`Codec \"${name}\" does not support requested format version ${JSON.stringify(selectedFormatVersion)}. Supported versions are: ${versionList(versions)}.`,\n\t\t\t);\n\t\t} else if (options.allowPossiblyIncompatibleWriteVersionOverrides !== true) {\n\t\t\tconst selectedMinVersionForCollab = selected.minVersionForCollab;\n\t\t\tif (selectedMinVersionForCollab === undefined) {\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`Codec \"${name}\" does not support requested format version ${JSON.stringify(selectedFormatVersion)} because it has minVersionForCollab undefined. Use \"allowPossiblyIncompatibleWriteVersionOverrides\" to suppress this error if appropriate.`,\n\t\t\t\t);\n\t\t\t} else if (gt(selectedMinVersionForCollab, options.minVersionForCollab)) {\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`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.`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\treturn selected;\n\t}\n\n\treturn getWriteVersionNoOverrides(versions, options.minVersionForCollab);\n}\n\n/**\n * Selects which format should be used when writing data, without consider overrides.\n */\nfunction getWriteVersionNoOverrides<T extends CodecVersionBase>(\n\tversions: readonly T[],\n\tminVersionForCollab: MinimumVersionForCollab,\n): T {\n\tconst stableVersions: [MinimumMinorSemanticVersion | MinimumVersionForCollab, T][] = [];\n\tfor (const version of versions) {\n\t\tif (version.minVersionForCollab !== undefined) {\n\t\t\tstableVersions.push([version.minVersionForCollab, version]);\n\t\t}\n\t}\n\n\tconst result: T = getConfigForMinVersionForCollabIterable(\n\t\tminVersionForCollab,\n\t\tstableVersions,\n\t);\n\treturn result;\n}\n\n/**\n * Formats a list of versions for use in UsageErrors.\n */\nfunction versionList(versions: readonly CodecVersionBase[]): string {\n\treturn JSON.stringify(Array.from(versions, (codec) => codec.formatVersion));\n}\n"]}

package/dist/codec/versioned/index.d.ts

@@ -3,5 +3,5 @@
  * Licensed under the MIT License.
  */
 export { Versioned, versionField } from "./format.js";
-export { makeDiscontinuedCodecAndSchema, ClientVersionDispatchingCodecBuilder, type CodecVersion, type CodecAndSchema, } from "./codec.js";
+export { makeDiscontinuedCodecAndSchema, VersionDispatchingCodecBuilder, type VersionDispatchingCodec, type CodecVersion, type CodecAndSchema, } from "./codec.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/codec/versioned/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/codec/versioned/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EACN,8BAA8B,EAC9B,oCAAoC,EACpC,KAAK,YAAY,EACjB,KAAK,cAAc,GACnB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/codec/versioned/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EACN,8BAA8B,EAC9B,8BAA8B,EAC9B,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EACjB,KAAK,cAAc,GACnB,MAAM,YAAY,CAAC"}

package/dist/codec/versioned/index.js

@@ -4,11 +4,11 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ClientVersionDispatchingCodecBuilder = exports.makeDiscontinuedCodecAndSchema = exports.versionField = exports.Versioned = void 0;
+exports.VersionDispatchingCodecBuilder = exports.makeDiscontinuedCodecAndSchema = exports.versionField = exports.Versioned = void 0;
 var format_js_1 = require("./format.js");
 Object.defineProperty(exports, "Versioned", { enumerable: true, get: function () { return format_js_1.Versioned; } });
 Object.defineProperty(exports, "versionField", { enumerable: true, get: function () { return format_js_1.versionField; } });
 var codec_js_1 = require("./codec.js");
 Object.defineProperty(exports, "makeDiscontinuedCodecAndSchema", { enumerable: true, get: function () { return codec_js_1.makeDiscontinuedCodecAndSchema; } });
-Object.defineProperty(exports, "ClientVersionDispatchingCodecBuilder", { enumerable: true, get: function () { return codec_js_1.ClientVersionDispatchingCodecBuilder; } });
+Object.defineProperty(exports, "VersionDispatchingCodecBuilder", { enumerable: true, get: function () { return codec_js_1.VersionDispatchingCodecBuilder; } });
 //# sourceMappingURL=index.js.map

package/dist/codec/versioned/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/codec/versioned/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,yCAAsD;AAA7C,sGAAA,SAAS,OAAA;AAAE,yGAAA,YAAY,OAAA;AAChC,uCAKoB;AAJnB,0HAAA,8BAA8B,OAAA;AAC9B,gIAAA,oCAAoC,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport { Versioned, versionField } from \"./format.js\";\nexport {\n\tmakeDiscontinuedCodecAndSchema,\n\tClientVersionDispatchingCodecBuilder,\n\ttype CodecVersion,\n\ttype CodecAndSchema,\n} from \"./codec.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/codec/versioned/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,yCAAsD;AAA7C,sGAAA,SAAS,OAAA;AAAE,yGAAA,YAAY,OAAA;AAChC,uCAMoB;AALnB,0HAAA,8BAA8B,OAAA;AAC9B,0HAAA,8BAA8B,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport { Versioned, versionField } from \"./format.js\";\nexport {\n\tmakeDiscontinuedCodecAndSchema,\n\tVersionDispatchingCodecBuilder,\n\ttype VersionDispatchingCodec,\n\ttype CodecVersion,\n\ttype CodecAndSchema,\n} from \"./codec.js\";\n"]}

package/dist/core/tree/deltaUtil.d.ts

@@ -11,13 +11,13 @@ export declare function offsetDetachId(id: DetachedNodeId, offset: number): Deta
 export declare function offsetDetachId(id: DetachedNodeId | undefined, offset: number): DetachedNodeId | undefined;
 export declare function areDetachedNodeIdsEqual(a: DetachedNodeId, b: DetachedNodeId): boolean;
 /**
- * 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
  */
 export declare function deltaFieldMapHasVisibleChanges(fields: FieldMap | undefined): boolean;
 /**
- * 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/dist/core/tree/deltaUtil.js

@@ -44,7 +44,7 @@ function areDetachedNodeIdsEqual(a, b) {
 }
 exports.areDetachedNodeIdsEqual = areDetachedNodeIdsEqual;
 /**
- * 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
  */
@@ -61,7 +61,7 @@ function deltaFieldMapHasVisibleChanges(fields) {
 }
 exports.deltaFieldMapHasVisibleChanges = deltaFieldMapHasVisibleChanges;
 /**
- * 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/dist/core/tree/deltaUtil.js.map

@@ -1 +1 @@
-{"version":3,"file":"deltaUtil.js","sourceRoot":"","sources":["../../../src/core/tree/deltaUtil.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAOH,yCAA0C;AAE7B,QAAA,UAAU,GAAS,EAAE,CAAC;AAEnC,SAAgB,0BAA0B,CAAC,OAAkB;IAC5D,IAAI,OAAO,CAAC,cAAc,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,kBAAU,CAAC;IACnB,CAAC;IACD,MAAM,OAAO,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAS;QACnB,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QACxC,MAAM,EAAE,IAAI,GAAG,CAAyB;YACvC,CAAC,uBAAY,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;SAC/E,CAAC;KACF,CAAC;IACF,OAAO,KAAK,CAAC;AACd,CAAC;AAZD,gEAYC;AAED,SAAgB,kBAAkB,CACjC,KAA8B,EAC9B,KAA8B;IAE9B,MAAM,GAAG,GAA4B,EAAE,KAAK,EAAE,CAAC;IAC/C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACzB,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;IACnB,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AATD,gDASC;AAOD,SAAgB,cAAc,CAC7B,EAA8B,EAC9B,MAAc;IAEd,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,OAAO;QACN,GAAG,EAAE;QACL,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,MAAM;KACxB,CAAC;AACH,CAAC;AAXD,wCAWC;AAED,SAAgB,uBAAuB,CAAC,CAAiB,EAAE,CAAiB;IAC3E,OAAO,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,CAAC;AACnD,CAAC;AAFD,0DAEC;AAED;;;;GAIG;AACH,SAAgB,8BAA8B,CAAC,MAA4B;IAC1E,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAC;IACd,CAAC;IACD,KAAK,MAAM,CAAC,EAAE,YAAY,CAAC,IAAI,MAAM,EAAE,CAAC;QACvC,IAAI,mCAAmC,CAAC,YAAY,CAAC,EAAE,CAAC;YACvD,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAVD,wEAUC;AAED;;;;GAIG;AACH,SAAgB,mCAAmC,CAAC,YAA0B;IAC7E,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,KAAK,EAAE,CAAC;QACvC,IACC,IAAI,CAAC,MAAM,KAAK,SAAS;YACzB,IAAI,CAAC,MAAM,KAAK,SAAS;YACzB,8BAA8B,CAAC,IAAI,CAAC,MAAM,CAAC,EAC1C,CAAC;YACF,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC;AAZD,kFAYC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { Mutable } from \"../../util/index.js\";\nimport type { FieldKey } from \"../schema-stored/index.js\";\n\nimport type { TreeChunk } from \"./chunk.js\";\nimport type { DetachedNodeId, FieldChanges, FieldMap, Root } from \"./delta.js\";\nimport { rootFieldKey } from \"./types.js\";\n\nexport const emptyDelta: Root = {};\n\nexport function deltaForRootInitialization(content: TreeChunk): Root {\n\tif (content.topLevelLength === 0) {\n\t\treturn emptyDelta;\n\t}\n\tconst buildId = { minor: 0 };\n\tconst delta: Root = {\n\t\tbuild: [{ id: buildId, trees: content }],\n\t\tfields: new Map<FieldKey, FieldChanges>([\n\t\t\t[rootFieldKey, { marks: [{ count: content.topLevelLength, attach: buildId }] }],\n\t\t]),\n\t};\n\treturn delta;\n}\n\nexport function makeDetachedNodeId(\n\tmajor: DetachedNodeId[\"major\"],\n\tminor: DetachedNodeId[\"minor\"],\n): DetachedNodeId {\n\tconst out: Mutable<DetachedNodeId> = { minor };\n\tif (major !== undefined) {\n\t\tout.major = major;\n\t}\n\treturn out;\n}\n\nexport function offsetDetachId(id: DetachedNodeId, offset: number): DetachedNodeId;\nexport function offsetDetachId(\n\tid: DetachedNodeId | undefined,\n\toffset: number,\n): DetachedNodeId | undefined;\nexport function offsetDetachId(\n\tid: DetachedNodeId | undefined,\n\toffset: number,\n): DetachedNodeId | undefined {\n\tif (id === undefined) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\t...id,\n\t\tminor: id.minor + offset,\n\t};\n}\n\nexport function areDetachedNodeIdsEqual(a: DetachedNodeId, b: DetachedNodeId): boolean {\n\treturn a.major === b.major && a.minor === b.minor;\n}\n\n/**\n * Returns true if a delta field map contains any changes that would be visible in the document (eg, an insert, move, edit)\n * @param fields - Delta FieldMap to check for visible changes\n * @returns True if change map contains any changes that would be visible in the document, false otherwise\n */\nexport function deltaFieldMapHasVisibleChanges(fields: FieldMap | undefined): boolean {\n\tif (fields === undefined || fields.size === 0) {\n\t\treturn false;\n\t}\n\tfor (const [, fieldChanges] of fields) {\n\t\tif (deltaFieldChangesHaveVisibleChanges(fieldChanges)) {\n\t\t\treturn true;\n\t\t}\n\t}\n\treturn false;\n}\n\n/**\n * Returns true if the given field changes contains any changes that would be visible in the document (eg, an insert, move, edit)\n * @param fieldChanges - Field changes to check for visible changes\n * @returns True if the field changes contain any changes that would be visible in the document, false otherwise\n */\nexport function deltaFieldChangesHaveVisibleChanges(fieldChanges: FieldChanges): boolean {\n\tfor (const mark of fieldChanges.marks) {\n\t\tif (\n\t\t\tmark.attach !== undefined ||\n\t\t\tmark.detach !== undefined ||\n\t\t\tdeltaFieldMapHasVisibleChanges(mark.fields)\n\t\t) {\n\t\t\treturn true;\n\t\t}\n\t}\n\n\treturn false;\n}\n"]}
+{"version":3,"file":"deltaUtil.js","sourceRoot":"","sources":["../../../src/core/tree/deltaUtil.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAOH,yCAA0C;AAE7B,QAAA,UAAU,GAAS,EAAE,CAAC;AAEnC,SAAgB,0BAA0B,CAAC,OAAkB;IAC5D,IAAI,OAAO,CAAC,cAAc,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,kBAAU,CAAC;IACnB,CAAC;IACD,MAAM,OAAO,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAS;QACnB,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QACxC,MAAM,EAAE,IAAI,GAAG,CAAyB;YACvC,CAAC,uBAAY,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;SAC/E,CAAC;KACF,CAAC;IACF,OAAO,KAAK,CAAC;AACd,CAAC;AAZD,gEAYC;AAED,SAAgB,kBAAkB,CACjC,KAA8B,EAC9B,KAA8B;IAE9B,MAAM,GAAG,GAA4B,EAAE,KAAK,EAAE,CAAC;IAC/C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACzB,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;IACnB,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AATD,gDASC;AAOD,SAAgB,cAAc,CAC7B,EAA8B,EAC9B,MAAc;IAEd,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,OAAO;QACN,GAAG,EAAE;QACL,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,MAAM;KACxB,CAAC;AACH,CAAC;AAXD,wCAWC;AAED,SAAgB,uBAAuB,CAAC,CAAiB,EAAE,CAAiB;IAC3E,OAAO,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,CAAC;AACnD,CAAC;AAFD,0DAEC;AAED;;;;GAIG;AACH,SAAgB,8BAA8B,CAAC,MAA4B;IAC1E,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAC;IACd,CAAC;IACD,KAAK,MAAM,CAAC,EAAE,YAAY,CAAC,IAAI,MAAM,EAAE,CAAC;QACvC,IAAI,mCAAmC,CAAC,YAAY,CAAC,EAAE,CAAC;YACvD,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAVD,wEAUC;AAED;;;;GAIG;AACH,SAAgB,mCAAmC,CAAC,YAA0B;IAC7E,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,KAAK,EAAE,CAAC;QACvC,IACC,IAAI,CAAC,MAAM,KAAK,SAAS;YACzB,IAAI,CAAC,MAAM,KAAK,SAAS;YACzB,8BAA8B,CAAC,IAAI,CAAC,MAAM,CAAC,EAC1C,CAAC;YACF,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC;AAZD,kFAYC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { Mutable } from \"../../util/index.js\";\nimport type { FieldKey } from \"../schema-stored/index.js\";\n\nimport type { TreeChunk } from \"./chunk.js\";\nimport type { DetachedNodeId, FieldChanges, FieldMap, Root } from \"./delta.js\";\nimport { rootFieldKey } from \"./types.js\";\n\nexport const emptyDelta: Root = {};\n\nexport function deltaForRootInitialization(content: TreeChunk): Root {\n\tif (content.topLevelLength === 0) {\n\t\treturn emptyDelta;\n\t}\n\tconst buildId = { minor: 0 };\n\tconst delta: Root = {\n\t\tbuild: [{ id: buildId, trees: content }],\n\t\tfields: new Map<FieldKey, FieldChanges>([\n\t\t\t[rootFieldKey, { marks: [{ count: content.topLevelLength, attach: buildId }] }],\n\t\t]),\n\t};\n\treturn delta;\n}\n\nexport function makeDetachedNodeId(\n\tmajor: DetachedNodeId[\"major\"],\n\tminor: DetachedNodeId[\"minor\"],\n): DetachedNodeId {\n\tconst out: Mutable<DetachedNodeId> = { minor };\n\tif (major !== undefined) {\n\t\tout.major = major;\n\t}\n\treturn out;\n}\n\nexport function offsetDetachId(id: DetachedNodeId, offset: number): DetachedNodeId;\nexport function offsetDetachId(\n\tid: DetachedNodeId | undefined,\n\toffset: number,\n): DetachedNodeId | undefined;\nexport function offsetDetachId(\n\tid: DetachedNodeId | undefined,\n\toffset: number,\n): DetachedNodeId | undefined {\n\tif (id === undefined) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\t...id,\n\t\tminor: id.minor + offset,\n\t};\n}\n\nexport function areDetachedNodeIdsEqual(a: DetachedNodeId, b: DetachedNodeId): boolean {\n\treturn a.major === b.major && a.minor === b.minor;\n}\n\n/**\n * Returns true if a delta field map contains any changes that would be visible in the document (i.e., a detach or an attach)\n * @param fields - Delta FieldMap to check for visible changes\n * @returns True if change map contains any changes that would be visible in the document, false otherwise\n */\nexport function deltaFieldMapHasVisibleChanges(fields: FieldMap | undefined): boolean {\n\tif (fields === undefined || fields.size === 0) {\n\t\treturn false;\n\t}\n\tfor (const [, fieldChanges] of fields) {\n\t\tif (deltaFieldChangesHaveVisibleChanges(fieldChanges)) {\n\t\t\treturn true;\n\t\t}\n\t}\n\treturn false;\n}\n\n/**\n * Returns true if the given field changes contains any changes that would be visible in the document (i.e., a detach or an attach)\n * @param fieldChanges - Field changes to check for visible changes\n * @returns True if the field changes contain any changes that would be visible in the document, false otherwise\n */\nexport function deltaFieldChangesHaveVisibleChanges(fieldChanges: FieldChanges): boolean {\n\tfor (const mark of fieldChanges.marks) {\n\t\tif (\n\t\t\tmark.attach !== undefined ||\n\t\t\tmark.detach !== undefined ||\n\t\t\tdeltaFieldMapHasVisibleChanges(mark.fields)\n\t\t) {\n\t\t\treturn true;\n\t\t}\n\t}\n\n\treturn false;\n}\n"]}

package/dist/core/tree/detachedFieldIndexCodecV1.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detachedFieldIndexCodecV1.d.ts","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV1.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,sBAAsB,CAAC;AAEvE,OAAO,EAEN,KAAK,gBAAgB,EAGrB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EAAE,wBAAwB,EAAS,MAAM,8BAA8B,CAAC;AAkDpF,wBAAgB,8BAA8B,CAC7C,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,GACzB,cAAc,CAAC,wBAAwB,CAAC,CAO1C"}
+{"version":3,"file":"detachedFieldIndexCodecV1.d.ts","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV1.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAGnE,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,sBAAsB,CAAC;AAEvE,OAAO,EAEN,KAAK,gBAAgB,EAGrB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EAAE,wBAAwB,EAAS,MAAM,8BAA8B,CAAC;AAkDpF,wBAAgB,8BAA8B,CAC7C,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,GACzB,cAAc,CAAC,wBAAwB,CAAC,CAO1C"}

package/dist/core/tree/detachedFieldIndexCodecV1.js

@@ -6,6 +6,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeDetachedNodeToFieldCodecV1 = void 0;
 const internal_1 = require("@fluidframework/core-utils/internal");
+const internal_2 = require("@fluidframework/id-compressor/internal");
 const index_js_1 = require("../../util/index.js");
 const index_js_2 = require("../rebase/index.js");
 const detachedFieldIndexCodecCommon_js_1 = require("./detachedFieldIndexCodecCommon.js");
@@ -35,11 +36,11 @@ class MajorCodec {
          * but not when the container is already attached and it's just the shared-tree that is attaching.
          * The assert below will fail in such a scenario. This is addressed in the v2 codec.
          */
-        (0, internal_1.assert)(id === "root" || id >= 0, 0x88f /* Expected final id on encode of detached field index revision */);
+        (0, internal_1.assert)(id === "root" || (0, internal_2.isFinalId)(id), 0x88f /* Expected final id on encode of detached field index revision */);
         return id;
     }
     decode(major) {
-        (0, internal_1.assert)(major === "root" || major >= 0, 0x890 /* Expected final id on decode of detached field index revision */);
+        (0, internal_1.assert)(major === "root" || (0, internal_2.isFinalId)(major), 0x890 /* Expected final id on decode of detached field index revision */);
         return this.revisionTagCodec.decode(major, {
             originatorId: this.revisionTagCodec.localSessionId,
             idCompressor: this.idCompressor,

package/dist/core/tree/detachedFieldIndexCodecV1.js.map

@@ -1 +1 @@
-{"version":3,"file":"detachedFieldIndexCodecV1.js","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV1.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,kEAA6D;AAI7D,kDAA4C;AAC5C,iDAK4B;AAE5B,yFAA+F;AAC/F,2FAAsF;AAGtF,MAAM,UAAU;IACf,YACkB,gBAAkC,EAClC,YAA2B;QAD3B,qBAAgB,GAAhB,gBAAgB,CAAkB;QAClC,iBAAY,GAAZ,YAAY,CAAe;IAC1C,CAAC;IAEG,MAAM,CAAC,KAAY;QACzB,IAAA,iBAAM,EAAC,KAAK,KAAK,SAAS,EAAE,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvE,MAAM,EAAE,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/C;;;;;;;;;;;;;;;;WAgBG;QACH,IAAA,iBAAM,EACL,EAAE,KAAK,MAAM,IAAI,EAAE,IAAI,CAAC,EACxB,KAAK,CAAC,kEAAkE,CACxE,CAAC;QACF,OAAO,EAAE,CAAC;IACX,CAAC;IAEM,MAAM,CAAC,KAAyB;QACtC,IAAA,iBAAM,EACL,KAAK,KAAK,MAAM,IAAI,KAAK,IAAI,CAAC,EAC9B,KAAK,CAAC,kEAAkE,CACxE,CAAC;QACF,OAAO,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE;YAC1C,YAAY,EAAE,IAAI,CAAC,gBAAgB,CAAC,cAAc;YAClD,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,QAAQ,EAAE,SAAS;YACnB,6DAA6D;YAC7D,SAAS,EAAE,IAAI;SACf,CAAC,CAAC;IACJ,CAAC;CACD;AAED,SAAgB,8BAA8B,CAC7C,gBAAkC,EAClC,YAA2B;IAE3B,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;IAClE,OAAO,IAAA,4EAAyC,EAC/C,UAAU,EACV,IAAA,gBAAK,EAAC,mEAA+B,CAAC,EAAE,CAAC,EACzC,4BAAiB,CACjB,CAAC;AACH,CAAC;AAVD,wEAUC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport type { IIdCompressor } from \"@fluidframework/id-compressor\";\n\nimport type { CodecAndSchema, IJsonCodec } from \"../../codec/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\ttype EncodedRevisionTag,\n\ttype RevisionTagCodec,\n\ttype RevisionTag,\n\tRevisionTagSchema,\n} from \"../rebase/index.js\";\n\nimport { makeDetachedFieldIndexCodecFromMajorCodec } from \"./detachedFieldIndexCodecCommon.js\";\nimport { DetachedFieldIndexFormatVersion } from \"./detachedFieldIndexFormatCommon.js\";\nimport type { DetachedFieldSummaryData, Major } from \"./detachedFieldIndexTypes.js\";\n\nclass MajorCodec implements IJsonCodec<Major, EncodedRevisionTag> {\n\tpublic constructor(\n\t\tprivate readonly revisionTagCodec: RevisionTagCodec,\n\t\tprivate readonly idCompressor: IIdCompressor,\n\t) {}\n\n\tpublic encode(major: Major): EncodedRevisionTag {\n\t\tassert(major !== undefined, 0x88e /* Unexpected undefined revision */);\n\t\tconst id = this.revisionTagCodec.encode(major);\n\t\t/**\n\t\t * Preface: this codec is only used at summarization time (not for ops).\n\t\t * Note that the decode path must provide a session id in which to interpret the revision tag.\n\t\t * The revision associated with a detached root generally comes from the session which detaches that subtree,\n\t\t * which isn't generally the local session (nor is it available at decode time with the layering of the tree\n\t\t * package), despite decode using the local session id.\n\t\t *\n\t\t * This is made OK by enforcing that all ids on encode/decode are non-local, since local ids won't be interpretable\n\t\t * at decode time.\n\t\t * This assert is valid because the revision for an acked edit will have already been finalized, and a revision\n\t\t * for a local-only edit will be finalizable at summarization time (local edits can only occur on a summarizing client\n\t\t * if they're created while detached, and local ids made while detached are finalized before generating the attach summary).\n\t\t *\n\t\t * WARNING: the above is true when the whole container transitions from detached to attached,\n\t\t * but not when the container is already attached and it's just the shared-tree that is attaching.\n\t\t * The assert below will fail in such a scenario. This is addressed in the v2 codec.\n\t\t */\n\t\tassert(\n\t\t\tid === \"root\" || id >= 0,\n\t\t\t0x88f /* Expected final id on encode of detached field index revision */,\n\t\t);\n\t\treturn id;\n\t}\n\n\tpublic decode(major: EncodedRevisionTag): RevisionTag {\n\t\tassert(\n\t\t\tmajor === \"root\" || major >= 0,\n\t\t\t0x890 /* Expected final id on decode of detached field index revision */,\n\t\t);\n\t\treturn this.revisionTagCodec.decode(major, {\n\t\t\toriginatorId: this.revisionTagCodec.localSessionId,\n\t\t\tidCompressor: this.idCompressor,\n\t\t\trevision: undefined,\n\t\t\t// DetachedFieldIndex codecs are only used by the summarizer.\n\t\t\tisSummary: true,\n\t\t});\n\t}\n}\n\nexport function makeDetachedNodeToFieldCodecV1(\n\trevisionTagCodec: RevisionTagCodec,\n\tidCompressor: IIdCompressor,\n): CodecAndSchema<DetachedFieldSummaryData> {\n\tconst majorCodec = new MajorCodec(revisionTagCodec, idCompressor);\n\treturn makeDetachedFieldIndexCodecFromMajorCodec(\n\t\tmajorCodec,\n\t\tbrand(DetachedFieldIndexFormatVersion.v1),\n\t\tRevisionTagSchema,\n\t);\n}\n"]}
+{"version":3,"file":"detachedFieldIndexCodecV1.js","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV1.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,kEAA6D;AAE7D,qEAAmE;AAGnE,kDAA4C;AAC5C,iDAK4B;AAE5B,yFAA+F;AAC/F,2FAAsF;AAGtF,MAAM,UAAU;IACf,YACkB,gBAAkC,EAClC,YAA2B;QAD3B,qBAAgB,GAAhB,gBAAgB,CAAkB;QAClC,iBAAY,GAAZ,YAAY,CAAe;IAC1C,CAAC;IAEG,MAAM,CAAC,KAAY;QACzB,IAAA,iBAAM,EAAC,KAAK,KAAK,SAAS,EAAE,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvE,MAAM,EAAE,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/C;;;;;;;;;;;;;;;;WAgBG;QACH,IAAA,iBAAM,EACL,EAAE,KAAK,MAAM,IAAI,IAAA,oBAAS,EAAC,EAAE,CAAC,EAC9B,KAAK,CAAC,kEAAkE,CACxE,CAAC;QACF,OAAO,EAAE,CAAC;IACX,CAAC;IAEM,MAAM,CAAC,KAAyB;QACtC,IAAA,iBAAM,EACL,KAAK,KAAK,MAAM,IAAI,IAAA,oBAAS,EAAC,KAAK,CAAC,EACpC,KAAK,CAAC,kEAAkE,CACxE,CAAC;QACF,OAAO,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE;YAC1C,YAAY,EAAE,IAAI,CAAC,gBAAgB,CAAC,cAAc;YAClD,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,QAAQ,EAAE,SAAS;YACnB,6DAA6D;YAC7D,SAAS,EAAE,IAAI;SACf,CAAC,CAAC;IACJ,CAAC;CACD;AAED,SAAgB,8BAA8B,CAC7C,gBAAkC,EAClC,YAA2B;IAE3B,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;IAClE,OAAO,IAAA,4EAAyC,EAC/C,UAAU,EACV,IAAA,gBAAK,EAAC,mEAA+B,CAAC,EAAE,CAAC,EACzC,4BAAiB,CACjB,CAAC;AACH,CAAC;AAVD,wEAUC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport type { IIdCompressor } from \"@fluidframework/id-compressor\";\nimport { isFinalId } from \"@fluidframework/id-compressor/internal\";\n\nimport type { CodecAndSchema, IJsonCodec } from \"../../codec/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\ttype EncodedRevisionTag,\n\ttype RevisionTagCodec,\n\ttype RevisionTag,\n\tRevisionTagSchema,\n} from \"../rebase/index.js\";\n\nimport { makeDetachedFieldIndexCodecFromMajorCodec } from \"./detachedFieldIndexCodecCommon.js\";\nimport { DetachedFieldIndexFormatVersion } from \"./detachedFieldIndexFormatCommon.js\";\nimport type { DetachedFieldSummaryData, Major } from \"./detachedFieldIndexTypes.js\";\n\nclass MajorCodec implements IJsonCodec<Major, EncodedRevisionTag> {\n\tpublic constructor(\n\t\tprivate readonly revisionTagCodec: RevisionTagCodec,\n\t\tprivate readonly idCompressor: IIdCompressor,\n\t) {}\n\n\tpublic encode(major: Major): EncodedRevisionTag {\n\t\tassert(major !== undefined, 0x88e /* Unexpected undefined revision */);\n\t\tconst id = this.revisionTagCodec.encode(major);\n\t\t/**\n\t\t * Preface: this codec is only used at summarization time (not for ops).\n\t\t * Note that the decode path must provide a session id in which to interpret the revision tag.\n\t\t * The revision associated with a detached root generally comes from the session which detaches that subtree,\n\t\t * which isn't generally the local session (nor is it available at decode time with the layering of the tree\n\t\t * package), despite decode using the local session id.\n\t\t *\n\t\t * This is made OK by enforcing that all ids on encode/decode are non-local, since local ids won't be interpretable\n\t\t * at decode time.\n\t\t * This assert is valid because the revision for an acked edit will have already been finalized, and a revision\n\t\t * for a local-only edit will be finalizable at summarization time (local edits can only occur on a summarizing client\n\t\t * if they're created while detached, and local ids made while detached are finalized before generating the attach summary).\n\t\t *\n\t\t * WARNING: the above is true when the whole container transitions from detached to attached,\n\t\t * but not when the container is already attached and it's just the shared-tree that is attaching.\n\t\t * The assert below will fail in such a scenario. This is addressed in the v2 codec.\n\t\t */\n\t\tassert(\n\t\t\tid === \"root\" || isFinalId(id),\n\t\t\t0x88f /* Expected final id on encode of detached field index revision */,\n\t\t);\n\t\treturn id;\n\t}\n\n\tpublic decode(major: EncodedRevisionTag): RevisionTag {\n\t\tassert(\n\t\t\tmajor === \"root\" || isFinalId(major),\n\t\t\t0x890 /* Expected final id on decode of detached field index revision */,\n\t\t);\n\t\treturn this.revisionTagCodec.decode(major, {\n\t\t\toriginatorId: this.revisionTagCodec.localSessionId,\n\t\t\tidCompressor: this.idCompressor,\n\t\t\trevision: undefined,\n\t\t\t// DetachedFieldIndex codecs are only used by the summarizer.\n\t\t\tisSummary: true,\n\t\t});\n\t}\n}\n\nexport function makeDetachedNodeToFieldCodecV1(\n\trevisionTagCodec: RevisionTagCodec,\n\tidCompressor: IIdCompressor,\n): CodecAndSchema<DetachedFieldSummaryData> {\n\tconst majorCodec = new MajorCodec(revisionTagCodec, idCompressor);\n\treturn makeDetachedFieldIndexCodecFromMajorCodec(\n\t\tmajorCodec,\n\t\tbrand(DetachedFieldIndexFormatVersion.v1),\n\t\tRevisionTagSchema,\n\t);\n}\n"]}

package/dist/core/tree/detachedFieldIndexCodecV2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detachedFieldIndexCodecV2.d.ts","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV2.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,+BAA+B,CAAC;AAG7E,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAsB,gBAAgB,EAAe,MAAM,oBAAoB,CAAC;AAK5F,OAAO,KAAK,EAAE,wBAAwB,EAAS,MAAM,8BAA8B,CAAC;AA0CpF,wBAAgB,8BAA8B,CAC7C,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,GACzB,cAAc,CAAC,wBAAwB,CAAC,CAO1C"}
+{"version":3,"file":"detachedFieldIndexCodecV2.d.ts","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV2.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,+BAA+B,CAAC;AAG7E,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAsB,gBAAgB,EAAe,MAAM,oBAAoB,CAAC;AAK5F,OAAO,KAAK,EAAE,wBAAwB,EAAS,MAAM,8BAA8B,CAAC;AA4CpF,wBAAgB,8BAA8B,CAC7C,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,GACzB,cAAc,CAAC,wBAAwB,CAAC,CAO1C"}

package/dist/core/tree/detachedFieldIndexCodecV2.js

@@ -18,7 +18,7 @@ class MajorCodec {
     encode(major) {
         (0, internal_1.assert)(major !== undefined, 0xbfb /* Unexpected undefined revision */);
         const id = this.revisionTagCodec.encode(major);
-        if (id !== "root" && id < 0) {
+        if (id !== "root" && !(0, internal_2.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.
@@ -30,7 +30,9 @@ class MajorCodec {
         return id;
     }
     decode(major) {
-        (0, internal_1.assert)(major === "root" || (typeof major === "string" && (0, internal_2.isStableId)(major)) || major >= 0, 0xbfd /* Expected root, stable, or final compressed id */);
+        (0, internal_1.assert)(major === "root" ||
+            (typeof major === "string" && (0, internal_2.isStableId)(major)) ||
+            (typeof major === "number" && (0, internal_2.isFinalId)(major)), 0xbfd /* Expected root, stable, or final compressed id */);
         if (typeof major === "string" && (0, internal_2.isStableId)(major)) {
             return this.idCompressor.recompress(major);
         }