@fluidframework/tree 2.41.0 → 2.42.0

package/.vscode/settings.json

@@ -24,6 +24,7 @@
 		"endregion",
 		"fluidframework",
 		"insertable",
+		"parameterizing",
 		"reentrantly",
 		"typeparam",
 		"unannotate",

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @fluidframework/tree
 
+## 2.42.0
+
+### Minor Changes
+
+- Fix Tree.key and Tree.parent for Unhydrated nodes after edits ([#24708](https://github.com/microsoft/FluidFramework/pull/24708)) [8aa5c233e2](https://github.com/microsoft/FluidFramework/commit/8aa5c233e2d59f440fd9c923bca14687bb958d66)
+
+  In some cases, editing [Unhydrated](https://fluidframework.com/docs/api/fluid-framework/unhydrated-typealias) nodes could result in incorrect results being returned from [Tree.key](https://fluidframework.com/docs/data-structures/tree/nodes#treekey) and [Tree.parent](https://fluidframework.com/docs/data-structures/tree/nodes#treeparent).
+  This has been fixed.
+
+- Defaulted identifier fields on unhydrated nodes are now enumerable ([#24739](https://github.com/microsoft/FluidFramework/pull/24739)) [3a5d0acfb6](https://github.com/microsoft/FluidFramework/commit/3a5d0acfb65f93a927405241e6047c8a04c8da58)
+
+  Previously, there was a special case for defaulted [identifier](https://fluidframework.com/docs/api/fluid-framework/schemafactory-class#identifier-property) fields on unhydrated nodes where they were not enumerable.
+  This special case has been removed: they are now enumerable independent of hydration status and defaulting.
+
+- Name collisions from structurally named schema now error ([#24707](https://github.com/microsoft/FluidFramework/pull/24707)) [a343f0498f](https://github.com/microsoft/FluidFramework/commit/a343f0498f2039e68aa11e8ede98f32391ce727d)
+
+  It is legal to have multiple [TreeNodeSchema](https://fluidframework.com/docs/api/fluid-framework/treenodeschema-typealias) with the same name so long as they are not used together in the same tree.
+  Using different schema with the same name when building otherwise identical [structurally named](https://fluidframework.com/docs/api/fluid-framework/schemafactory-class#schemafactory-remarks) in the same [SchemaFactory](https://fluidframework.com/docs/api/fluid-framework/schemafactory-class) is not valid, however.
+  Previously doing this would not error, and instead return the first structurally named schema with that name.
+  Now this case throws an informative error:
+
+  ```typescript
+  const factory = new SchemaFactory(undefined);
+  class Child1 extends factory.object("Child", {}) {}
+  class Child2 extends factory.object("Child", {}) {}
+
+  const a = factory.map(Child1);
+
+  // Throws a UsageError with the message:
+  // "Structurally named schema collision: two schema named "Array<["Child"]>" were defined with different input schema."
+  const b = factory.array(Child2);
+  ```
+
 ## 2.41.0
 
 ### Minor Changes

package/api-report/tree.alpha.api.md

@@ -94,6 +94,11 @@ export function cloneWithReplacements(root: unknown, rootKey: string, replacer:
     value: unknown;
 }): unknown;
 
+// @alpha @input
+export interface CodecWriteOptions extends ICodecOptions {
+    readonly oldestCompatibleClient: FluidClientVersion;
+}
+
 // @public
 export enum CommitKind {
     Default = 0,
@@ -274,7 +279,7 @@ export function getSimpleSchema(schema: ImplicitFieldSchema): SimpleTreeSchema;
 // @alpha
 export type HandleConverter<TCustom> = (data: IFluidHandle) => TCustom;
 
-// @alpha
+// @alpha @input
 export interface ICodecOptions {
     readonly jsonValidator: JsonValidator;
 }
@@ -501,7 +506,7 @@ export type JsonTreeSchema = JsonFieldSchema & {
     readonly $defs: Record<JsonSchemaId, JsonNodeSchema>;
 };
 
-// @alpha
+// @alpha @input
 export interface JsonValidator {
     compile<Schema extends TSchema>(schema: Schema): SchemaValidationFunction<Schema>;
 }
@@ -803,7 +808,7 @@ export interface SchemaStatics {
     readonly string: LeafSchema<"string", string>;
 }
 
-// @alpha
+// @alpha @input
 export interface SchemaValidationFunction<Schema extends TSchema> {
     check(data: unknown): data is Static<Schema>;
 }
@@ -827,8 +832,8 @@ export const SharedTreeFormatVersion: {
 // @alpha
 export type SharedTreeFormatVersion = typeof SharedTreeFormatVersion;
 
-// @alpha
-export type SharedTreeOptions = Partial<ICodecOptions> & Partial<SharedTreeFormatOptions> & ForestOptions;
+// @alpha @input
+export type SharedTreeOptions = Partial<CodecWriteOptions> & Partial<SharedTreeFormatOptions> & ForestOptions;
 
 // @alpha @sealed
 export interface SimpleArrayNodeSchema<out TCustomMetadata = unknown> extends SimpleNodeSchemaBase<NodeKind.Array, TCustomMetadata> {
@@ -1175,9 +1180,8 @@ export interface TreeAlpha {
     branch(node: TreeNode): TreeBranch | undefined;
     create<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: InsertableField<TSchema>): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>;
     exportCompressed(tree: TreeNode | TreeLeafValue, options: {
-        oldestCompatibleClient: FluidClientVersion;
         idCompressor?: IIdCompressor;
-    }): JsonCompatible<IFluidHandle>;
+    } & Pick<CodecWriteOptions, "oldestCompatibleClient">): JsonCompatible<IFluidHandle>;
     exportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;
     exportConcise(node: TreeNode | TreeLeafValue | undefined, options?: TreeEncodingOptions): ConciseTree | undefined;
     exportVerbose(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): VerboseTree;

package/dist/alpha.d.ts

@@ -103,6 +103,7 @@ export {
 	ArrayNodePojoEmulationSchema, 
 	ArrayNodeSchema, 
 	BranchableTree, 
+	CodecWriteOptions, 
 	ConciseTree, 
 	FactoryContent, 
 	FactoryContentObject, 

package/dist/codec/codec.d.ts

@@ -29,7 +29,7 @@ export interface IDecoder<TDecoded, TEncoded, TContext> {
 /**
  * Validates data complies with some particular schema.
  * Implementations are typically created by a {@link JsonValidator}.
- * @alpha
+ * @alpha @input
  */
 export interface SchemaValidationFunction<Schema extends TSchema> {
     /**
@@ -39,7 +39,7 @@ export interface SchemaValidationFunction<Schema extends TSchema> {
 }
 /**
  * JSON schema validator compliant with draft 6 schema. See https://json-schema.org.
- * @alpha
+ * @alpha @input
  */
 export interface JsonValidator {
     /**
@@ -55,7 +55,9 @@ export interface JsonValidator {
 }
 /**
  * Options relating to handling of persisted data.
- * @alpha
+ *
+ * @see {@link CodecWriteOptions} for options that are specific to encoding data.
+ * @alpha @input
  */
 export interface ICodecOptions {
     /**
@@ -73,6 +75,24 @@ export interface ICodecOptions {
      */
     readonly jsonValidator: JsonValidator;
 }
+/**
+ * Options relating to encoding of persisted data.
+ * @remarks
+ * Extends {@link ICodecOptions} with options that are specific to encoding data.
+ * @alpha @input
+ */
+export interface CodecWriteOptions extends ICodecOptions {
+    /**
+     * The minimum version of the Fluid Framework client output must be encoded to be compatible with.
+     * @remarks
+     * This is used to ensure that the the output from this codec can be used with older versions of the Fluid Framework client.
+     * This includes both concurrent collaboration, and an older version opening the document later.
+     *
+     * Note that versions older than this should not result in data corruption if they access the data:
+     * the data's format should be versioned and if they can't handle the format they should error.
+     */
+    readonly oldestCompatibleClient: FluidClientVersion;
+}
 /**
  * `TContext` allows passing context to the codec which may configure how data is encoded/decoded.
  * This parameter is typically used for:

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

@@ -1 +1 @@
-{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/codec/codec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAkB,MAAM,8BAA8B,CAAC;AAEzE,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAErE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE/D;;;GAGG;AACH,MAAM,WAAW,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ;IACrD;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,GAAG,QAAQ,CAAC;CACnD;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ;IACrD;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,GAAG,QAAQ,CAAC;CACnD;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB,CAAC,MAAM,SAAS,OAAO;IAC/D;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;CAC7C;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,SAAS,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;CAClF;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,UAAU,CAC1B,QAAQ,EACR,QAAQ,GAAG,sBAAsB,EACjC,SAAS,GAAG,QAAQ,EACpB,QAAQ,GAAG,IAAI,CACd,SAAQ,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC;IACxC,aAAa,CAAC,EAAE,UAAU,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CACtD,SAAQ,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,EAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC;CAAG;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB,CACjC,QAAQ,EACR,YAAY,SAAS,sBAAsB,GAAG,sBAAsB,EACpE,aAAa,GAAG,YAAY,EAC5B,QAAQ,GAAG,IAAI;IAEf,IAAI,EAAE,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;IAClE,MAAM,EAAE,YAAY,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAEzC,uEAAuE;IACvE,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,uEAAuE;IACvE,MAAM,CAAC,EAAE,KAAK,CAAC;CACf;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IACtD;;;;;;OAMG;IACH,OAAO,CACN,aAAa,EAAE,aAAa,GAC1B,iBAAiB,CAAC,QAAQ,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,QAAQ,CAAC,CAAC;IAEzF;;OAEG;IACH,mBAAmB,IAAI,QAAQ,CAAC,aAAa,CAAC,CAAC;CAC/C;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EACjD,QAAQ,EAAE,QAAQ,CACjB;IACC,aAAa,EAAE,aAAa;IAC5B,KAAK,EACF,iBAAiB,CAAC,QAAQ,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,QAAQ,CAAC,GACrF,UAAU,CAAC,QAAQ,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,QAAQ,CAAC;CACjF,CACD,GACC,YAAY,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAwBlC;AA4BD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,QAAQ,EAC3D,SAAS,EAAE,UAAU,CAAC,QAAQ,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,QAAQ,CAAC,GACvF,iBAAiB,CAAC,QAAQ,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,QAAQ,CAAC,CAKvF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,EACtD,KAAK,EACF,iBAAiB,CAAC,QAAQ,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,QAAQ,CAAC,GACrF,UAAU,CAAC,QAAQ,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,QAAQ,CAAC,GAC/E,iBAAiB,CAAC,QAAQ,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,QAAQ,CAAC,CAEvF;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,iBAAiB,CACxC,CAAC,EACD,sBAAsB,EACtB,sBAAsB,EACtB,OAAO,CAUP,CAAC;AAEF;;;GAGG;AACH,wBAAgB,oBAAoB,CACnC,eAAe,EACf,aAAa,SAAS,OAAO,EAC7B,cAAc,GAAG,sBAAsB,EACvC,SAAS,GAAG,cAAc,EAC1B,QAAQ,GAAG,qBAAqB,EAEhC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,UAAU,CAAC,eAAe,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,CAAC,EACvE,SAAS,CAAC,EAAE,aAAa,GACvB,UAAU,CAAC,eAAe,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,CAAC,CAqBlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,oBAAY,kBAAkB;IAC7B;;;;;;OAMG;IAGH,4CAA4C;IAC5C,IAAI,IAAM;IAEV,4CAA4C;IAM5C,6CAA6C;IAI7C;;;;;;;;OAQG;IACH,sBAAiD;CACjD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,EAAE,kBAA4C,CAAC"}
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/codec/codec.ts"],"names":[],"mappings":"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"}

package/dist/codec/codec.js.map

@@ -1 +1 @@
-{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/codec/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 { IsoBuffer, bufferToString } from \"@fluid-internal/client-utils\";\nimport { assert, fail } from \"@fluidframework/core-utils/internal\";\nimport type { Static, TAnySchema, TSchema } from \"@sinclair/typebox\";\n\nimport type { ChangeEncodingContext } from \"../core/index.js\";\nimport type { JsonCompatibleReadOnly } from \"../util/index.js\";\n\n/**\n * Translates decoded data to encoded data.\n * @remarks Typically paired with an {@link IEncoder}.\n */\nexport interface IEncoder<TDecoded, TEncoded, TContext> {\n\t/**\n\t * Encodes `obj` into some encoded format.\n\t */\n\tencode(obj: TDecoded, context: TContext): TEncoded;\n}\n\n/**\n * Translates encoded data to decoded data.\n * @remarks Typically paired with an {@link IEncoder}.\n */\nexport interface IDecoder<TDecoded, TEncoded, TContext> {\n\t/**\n\t * Decodes `obj` from some encoded format.\n\t */\n\tdecode(obj: TEncoded, context: TContext): TDecoded;\n}\n\n/**\n * Validates data complies with some particular schema.\n * Implementations are typically created by a {@link JsonValidator}.\n * @alpha\n */\nexport interface SchemaValidationFunction<Schema extends TSchema> {\n\t/**\n\t * Returns whether the data matches a schema.\n\t */\n\tcheck(data: unknown): data is Static<Schema>;\n}\n\n/**\n * JSON schema validator compliant with draft 6 schema. See https://json-schema.org.\n * @alpha\n */\nexport interface JsonValidator {\n\t/**\n\t * Compiles the provided JSON schema into a validator for that schema.\n\t * @param schema - A valid draft 6 JSON schema\n\t * @remarks IFluidHandles--which have circular property references--are used in various places in SharedTree's persisted\n\t * format. Handles should only be contained in sections of data which are validated against the empty schema `{}`\n\t * (see https://datatracker.ietf.org/doc/html/draft-wright-json-schema-01#section-4.4).\n\t *\n\t * Implementations of `JsonValidator` must therefore tolerate these values, despite the input not being valid JSON.\n\t */\n\tcompile<Schema extends TSchema>(schema: Schema): SchemaValidationFunction<Schema>;\n}\n\n/**\n * Options relating to handling of persisted data.\n * @alpha\n */\nexport interface ICodecOptions {\n\t/**\n\t * {@link JsonValidator} which SharedTree uses to validate persisted data it reads & writes\n\t * matches the expected encoded format (i.e. the wire format for ops and summaries).\n\t *\n\t * See {@link noopValidator} and {@link typeboxValidator} for out-of-the-box implementations.\n\t *\n\t * This option is not \"on-by-default\" because JSON schema validation comes with a small but noticeable\n\t * runtime performance cost, and popular schema validation libraries have relatively large bundle size.\n\t *\n\t * SharedTree users are still encouraged to use a non-trivial validator (i.e. not `noopValidator`)\n\t * whenever reasonable: it gives better fail-fast behavior when unexpected encoded data is found,\n\t * which reduces the risk of unrecoverable data corruption.\n\t */\n\treadonly jsonValidator: JsonValidator;\n}\n\n/**\n * `TContext` allows passing context to the codec which may configure how data is encoded/decoded.\n * This parameter is typically used for:\n * - Codecs which can pick from multiple encoding options, and imbue the encoded data with information about which option was used.\n * The caller of such a codec can provide context about which encoding choice to make as part of the `encode` call without creating\n * additional codecs. Note that this pattern can always be implemented by having the caller create multiple codecs and selecting the\n * appropriate one, but depending on API layering this might be less ergonomic.\n * - Context for the object currently being encoded, which might enable more efficient encoding. When used in this fashion, the codec author\n * should be careful to include the context somewhere in the encoded data such that decoding can correctly round-trip.\n * For example, a composed set of codecs could implement a form of [dictionary coding](https://en.wikipedia.org/wiki/Dictionary_coder)\n * using a context map which was created by the top-level codec and passed to the inner codecs.\n * This pattern is used:\n * - To avoid repeatedly encoding session ids on commits (only recording it once at the top level)\n * @remarks `TEncoded` should always be valid Json (i.e. not contain functions), but due to TypeScript's handling\n * of index signatures and `JsonCompatibleReadOnly`'s index signature in the Json object case, specifying this as a\n * type-system level constraint makes code that uses this interface more difficult to write.\n *\n * If provided, `TValidate` allows the input type passed to `decode` to be different than `TEncoded`.\n * This is useful when, for example, the type being decoded is `unknown` and must be validated to be a `TEncoded` before being decoded to a `TDecoded`.\n */\nexport interface IJsonCodec<\n\tTDecoded,\n\tTEncoded = JsonCompatibleReadOnly,\n\tTValidate = TEncoded,\n\tTContext = void,\n> extends IEncoder<TDecoded, TEncoded, TContext>,\n\t\tIDecoder<TDecoded, TValidate, TContext> {\n\tencodedSchema?: TAnySchema;\n}\n\n/**\n * @remarks TODO: We might consider using DataView or some kind of writer instead of IsoBuffer.\n */\nexport interface IBinaryCodec<TDecoded, TContext = void>\n\textends IEncoder<TDecoded, IsoBuffer, TContext>,\n\t\tIDecoder<TDecoded, IsoBuffer, TContext> {}\n\n/**\n * Contains knowledge of how to encode some in-memory type into JSON and binary formats,\n * as well as how to decode those representations.\n *\n * @remarks Codecs are typically used in shared-tree to convert data into some persisted format.\n * For this common use case, any format for encoding that was ever actually used needs to\n * be supported for decoding in all future code versions.\n *\n * Using an {@link ICodecFamily} is the recommended strategy for managing this support, keeping in\n * mind evolution of encodings over time.\n */\nexport interface IMultiFormatCodec<\n\tTDecoded,\n\tTJsonEncoded extends JsonCompatibleReadOnly = JsonCompatibleReadOnly,\n\tTJsonValidate = TJsonEncoded,\n\tTContext = void,\n> {\n\tjson: IJsonCodec<TDecoded, TJsonEncoded, TJsonValidate, TContext>;\n\tbinary: IBinaryCodec<TDecoded, TContext>;\n\n\t/** Ensures multi-format codecs cannot also be single-format codecs. */\n\tencode?: never;\n\t/** Ensures multi-format codecs cannot also be single-format codecs. */\n\tdecode?: never;\n}\n\n/**\n * Represents a family of codecs that can be used to encode and decode data in different formats.\n * The family is identified by a format version, which is typically used to select the codec to use.\n *\n * Separating codecs into families rather than having a single codec support multiple versions (i.e. currying\n * the `formatVersion` parameter)\n * allows avoiding some duplicate work at encode/decode time, since the vast majority of document usage will not\n * involve mixed format versions.\n *\n * @privateRemarks - This interface currently assumes all codecs in a family require the same encode/decode context,\n * which isn't necessarily true.\n * This may need to be relaxed in the future.\n */\nexport interface ICodecFamily<TDecoded, TContext = void> {\n\t/**\n\t * @returns a codec that can be used to encode and decode data in the specified format.\n\t * @throws - if the format version is not supported by this family.\n\t * @remarks Implementations should typically emit telemetry (either indirectly by throwing a well-known error with\n\t * logged properties or directly using some logger) when a format version is requested that is not supported.\n\t * This ensures that applications can diagnose compatibility issues.\n\t */\n\tresolve(\n\t\tformatVersion: FormatVersion,\n\t): IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>;\n\n\t/**\n\t * @returns an iterable of all format versions supported by this family.\n\t */\n\tgetSupportedFormats(): Iterable<FormatVersion>;\n}\n\n/**\n * A version stamp for encoded data.\n *\n * Undefined is tolerated to enable the scenario where data was not initially versioned.\n */\nexport type FormatVersion = number | undefined;\n\n/**\n * Creates a codec family from a registry of codecs.\n * Any codec that is not a {@link IMultiFormatCodec} will be wrapped with a default binary encoding.\n */\nexport function makeCodecFamily<TDecoded, TContext>(\n\tregistry: Iterable<\n\t\t[\n\t\t\tformatVersion: FormatVersion,\n\t\t\tcodec:\n\t\t\t\t| IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>\n\t\t\t\t| IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,\n\t\t]\n\t>,\n): ICodecFamily<TDecoded, TContext> {\n\tconst codecs: Map<\n\t\tFormatVersion,\n\t\tIMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>\n\t> = new Map();\n\tfor (const [formatVersion, codec] of registry) {\n\t\tif (codecs.has(formatVersion)) {\n\t\t\tfail(0xabf /* Duplicate codecs specified. */);\n\t\t}\n\t\tcodecs.set(formatVersion, ensureBinaryEncoding(codec));\n\t}\n\n\treturn {\n\t\tresolve(\n\t\t\tformatVersion: number,\n\t\t): IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {\n\t\t\tconst codec = codecs.get(formatVersion);\n\t\t\tassert(codec !== undefined, 0x5e6 /* Requested coded for unsupported format. */);\n\t\t\treturn codec;\n\t\t},\n\t\tgetSupportedFormats(): Iterable<FormatVersion> {\n\t\t\treturn codecs.keys();\n\t\t},\n\t};\n}\n\nclass DefaultBinaryCodec<TDecoded, TContext> implements IBinaryCodec<TDecoded, TContext> {\n\tpublic constructor(\n\t\tprivate readonly jsonCodec: IJsonCodec<TDecoded, unknown, unknown, TContext>,\n\t) {}\n\n\tpublic encode(change: TDecoded, context: TContext): IsoBuffer {\n\t\tconst jsonable = this.jsonCodec.encode(change, context);\n\t\tconst json = JSON.stringify(jsonable);\n\t\treturn IsoBuffer.from(json);\n\t}\n\n\tpublic decode(change: IsoBuffer, context: TContext): TDecoded {\n\t\tconst json = bufferToString(change, \"utf8\");\n\t\tconst jsonable = JSON.parse(json);\n\t\treturn this.jsonCodec.decode(jsonable, context);\n\t}\n}\n\nfunction isJsonCodec<TDecoded, TContext>(\n\tcodec:\n\t\t| IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>\n\t\t| IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,\n): codec is IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {\n\treturn typeof codec.encode === \"function\" && typeof codec.decode === \"function\";\n}\n\n/**\n * Constructs a {@link IMultiFormatCodec} from a `IJsonCodec` using a generic binary encoding that simply writes\n * the json representation of the object to a buffer.\n */\nexport function withDefaultBinaryEncoding<TDecoded, TContext>(\n\tjsonCodec: IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,\n): IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {\n\treturn {\n\t\tjson: jsonCodec,\n\t\tbinary: new DefaultBinaryCodec(jsonCodec),\n\t};\n}\n\n/**\n * Ensures that the provided single or multi-format codec has a binary encoding.\n * Adapts the json encoding using {@link withDefaultBinaryEncoding} if necessary.\n */\nexport function ensureBinaryEncoding<TDecoded, TContext>(\n\tcodec:\n\t\t| IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>\n\t\t| IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,\n): IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {\n\treturn isJsonCodec(codec) ? withDefaultBinaryEncoding(codec) : codec;\n}\n\n/**\n * Codec for objects which carry no information.\n */\nexport const unitCodec: IMultiFormatCodec<\n\t0,\n\tJsonCompatibleReadOnly,\n\tJsonCompatibleReadOnly,\n\tunknown\n> = {\n\tjson: {\n\t\tencode: () => 0,\n\t\tdecode: () => 0,\n\t},\n\tbinary: {\n\t\tencode: () => IsoBuffer.from(\"\"),\n\t\tdecode: () => 0,\n\t},\n};\n\n/**\n * Wraps a codec with JSON schema validation for its encoded type.\n * @returns An {@link IJsonCodec} which validates the data it encodes and decodes matches the provided schema.\n */\nexport function withSchemaValidation<\n\tTInMemoryFormat,\n\tEncodedSchema extends TSchema,\n\tTEncodedFormat = JsonCompatibleReadOnly,\n\tTValidate = TEncodedFormat,\n\tTContext = ChangeEncodingContext,\n>(\n\tschema: EncodedSchema,\n\tcodec: IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate, TContext>,\n\tvalidator?: JsonValidator,\n): IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate, TContext> {\n\tif (!validator) {\n\t\treturn codec;\n\t}\n\tconst compiledFormat = validator.compile(schema);\n\treturn {\n\t\tencode: (obj: TInMemoryFormat, context: TContext): TEncodedFormat => {\n\t\t\tconst encoded = codec.encode(obj, context);\n\t\t\tif (!compiledFormat.check(encoded)) {\n\t\t\t\tfail(0xac0 /* Encoded schema should validate */);\n\t\t\t}\n\t\t\treturn encoded;\n\t\t},\n\t\tdecode: (encoded: TValidate, context: TContext): TInMemoryFormat => {\n\t\t\tif (!compiledFormat.check(encoded)) {\n\t\t\t\tfail(0xac1 /* Encoded schema should validate */);\n\t\t\t}\n\t\t\t// TODO: would be nice to provide a more specific validate type to the inner codec than the outer one gets.\n\t\t\treturn codec.decode(encoded, context) as unknown as TInMemoryFormat;\n\t\t},\n\t};\n}\n\n/**\n * Versions of Fluid Framework client packages.\n * @remarks\n * Used to express compatibility requirements by indicating the oldest version with which compatibility must be maintained.\n *\n * When no compatibility-impacting change is made in a given version, the value associated with its enum entry may point to the older version which it's fully compatible with.\n * Note that this can change if a future version of the framework introduces an option to use something which is only supported at a particular version. In which case, the values of the enum may shift,\n * but the semantics of keys in this enum will not change.\n *\n * Do not depend on the value of this enums's entries: only depend on the keys (enum members) themselves.\n *\n * Some release may also be omitted if there is currently no need to express that specific version.\n * If the need arises, they might be added in the future.\n *\n * @privateRemarks\n * Entries in these enums should document the user facing impact of opting into a particular version.\n * For example, document if there is an encoding efficiency improvement of oping into that version or newer.\n * Versions with no notable impact can be omitted.\n *\n * These use numeric values for easy threshold comparisons.\n * Without zero padding, version 2.10 is treated as 2.1, which is numerically less than 2.2.\n * Adding leading zeros to the minor version ensures correct comparisons.\n * For example, version 2.20.0 is encoded as 2.020, and version 2.2.0 is encoded as 2.002.\n * For example FF 2.20.0 is encoded as 2.020 and FF 2.2.0 is encoded as 2.002.\n *\n * Three digits was selected as that will likely be enough, while two digits could easily be too few.\n * If three digits ends up being too few, minor releases of 1000 and higher\n * could still be handled using something like 2.999_00001 without having to change the lower releases.\n *\n * This scheme assumes a single version will always be enough to communicate compatibility.\n * For this to work, compatibility has to be strictly increasing.\n * If this is violated (for example a subset of incompatible features from 3.x that are not in 3.0 are back ported to 2.x),\n * a more complex scheme may be needed to allow safely opting into incompatible features in those cases:\n * such a system can be added if/when its needed since it will be opt in and thus non-breaking.\n *\n * TODO: this should likely be defined higher in the stack and specified when creating the container, possibly as part of its schema.\n * TODO: compatibility requirements for how this enum can and cannot be changed should be clarified when/if it's used across multiple layers in the stack.\n * For example, if needed, would adding more leading zeros to the minor version break things.\n * @alpha\n */\nexport enum FluidClientVersion {\n\t/**\n\t * Fluid Framework Client 1.4 and newer.\n\t * @remarks\n\t * This opts into support for the 1.4 LTS branch.\n\t * @privateRemarks\n\t * As long as this code is in Tree, there is no reason to have this option as SharedTree did not exist in 1.4.\n\t */\n\t// v1_4 = 1.004,\n\n\t/** Fluid Framework Client 2.0 and newer. */\n\tv2_0 = 2.0,\n\n\t/** Fluid Framework Client 2.1 and newer. */\n\t// If we think we might want to start allowing opting into something that landed in 2.1 (without opting into something newer),\n\t// we could add an entry like this to allow users to indicate that they can be opted in once we are ready,\n\t// then update it to \"2.001\" once we actually have the opt in working.\n\t// v2_1 = v2_0,\n\n\t/** Fluid Framework Client 2.41 and newer. */\n\t// If we land some new formats in 2.41, we can enable selecting\n\t// v2_41 = 2.041,\n\n\t/**\n\t * Enable unreleased and unfinished features.\n\t * @remarks\n\t * Using this value can result in documents which can not be opened in future versions of the framework.\n\t * It can also result in data corruption by enabling unfinished features which may not handle all cases correctly.\n\t *\n\t * This can be used with specific APIs when the caller has knowledge of what specific features those APIs will be opted into with it.\n\t * This is useful for testing features before they are released, but should not be used in production code.\n\t */\n\tEnableUnstableFeatures = Number.POSITIVE_INFINITY,\n}\n\n/**\n * An up to date version which includes all the important stable features.\n * @remarks\n * Use for cases when data is not persisted and thus would only ever be read by the current version of the framework.\n *\n * @privateRemarks\n * Update as needed.\n * TODO: Consider using packageVersion.ts to keep this current.\n */\nexport const currentVersion: FluidClientVersion = FluidClientVersion.v2_0;\n"]}
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/codec/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 { IsoBuffer, bufferToString } from \"@fluid-internal/client-utils\";\nimport { assert, fail } from \"@fluidframework/core-utils/internal\";\nimport type { Static, TAnySchema, TSchema } from \"@sinclair/typebox\";\n\nimport type { ChangeEncodingContext } from \"../core/index.js\";\nimport type { JsonCompatibleReadOnly } from \"../util/index.js\";\n\n/**\n * Translates decoded data to encoded data.\n * @remarks Typically paired with an {@link IEncoder}.\n */\nexport interface IEncoder<TDecoded, TEncoded, TContext> {\n\t/**\n\t * Encodes `obj` into some encoded format.\n\t */\n\tencode(obj: TDecoded, context: TContext): TEncoded;\n}\n\n/**\n * Translates encoded data to decoded data.\n * @remarks Typically paired with an {@link IEncoder}.\n */\nexport interface IDecoder<TDecoded, TEncoded, TContext> {\n\t/**\n\t * Decodes `obj` from some encoded format.\n\t */\n\tdecode(obj: TEncoded, context: TContext): TDecoded;\n}\n\n/**\n * Validates data complies with some particular schema.\n * Implementations are typically created by a {@link JsonValidator}.\n * @alpha @input\n */\nexport interface SchemaValidationFunction<Schema extends TSchema> {\n\t/**\n\t * Returns whether the data matches a schema.\n\t */\n\tcheck(data: unknown): data is Static<Schema>;\n}\n\n/**\n * JSON schema validator compliant with draft 6 schema. See https://json-schema.org.\n * @alpha @input\n */\nexport interface JsonValidator {\n\t/**\n\t * Compiles the provided JSON schema into a validator for that schema.\n\t * @param schema - A valid draft 6 JSON schema\n\t * @remarks IFluidHandles--which have circular property references--are used in various places in SharedTree's persisted\n\t * format. Handles should only be contained in sections of data which are validated against the empty schema `{}`\n\t * (see https://datatracker.ietf.org/doc/html/draft-wright-json-schema-01#section-4.4).\n\t *\n\t * Implementations of `JsonValidator` must therefore tolerate these values, despite the input not being valid JSON.\n\t */\n\tcompile<Schema extends TSchema>(schema: Schema): SchemaValidationFunction<Schema>;\n}\n\n/**\n * Options relating to handling of persisted data.\n *\n * @see {@link CodecWriteOptions} for options that are specific to encoding data.\n * @alpha @input\n */\nexport interface ICodecOptions {\n\t/**\n\t * {@link JsonValidator} which SharedTree uses to validate persisted data it reads & writes\n\t * matches the expected encoded format (i.e. the wire format for ops and summaries).\n\t *\n\t * See {@link noopValidator} and {@link typeboxValidator} for out-of-the-box implementations.\n\t *\n\t * This option is not \"on-by-default\" because JSON schema validation comes with a small but noticeable\n\t * runtime performance cost, and popular schema validation libraries have relatively large bundle size.\n\t *\n\t * SharedTree users are still encouraged to use a non-trivial validator (i.e. not `noopValidator`)\n\t * whenever reasonable: it gives better fail-fast behavior when unexpected encoded data is found,\n\t * which reduces the risk of unrecoverable data corruption.\n\t */\n\treadonly jsonValidator: JsonValidator;\n}\n\n/**\n * Options relating to encoding of persisted data.\n * @remarks\n * Extends {@link ICodecOptions} with options that are specific to encoding data.\n * @alpha @input\n */\nexport interface CodecWriteOptions extends ICodecOptions {\n\t/**\n\t * The minimum version of the Fluid Framework client output must be encoded to be compatible with.\n\t * @remarks\n\t * This is used to ensure that the the output from this codec can be used with older versions of the Fluid Framework client.\n\t * This includes both concurrent collaboration, and an older version opening the document later.\n\t *\n\t * Note that versions older than this should not result in data corruption if they access the data:\n\t * the data's format should be versioned and if they can't handle the format they should error.\n\t */\n\treadonly oldestCompatibleClient: FluidClientVersion;\n}\n\n/**\n * `TContext` allows passing context to the codec which may configure how data is encoded/decoded.\n * This parameter is typically used for:\n * - Codecs which can pick from multiple encoding options, and imbue the encoded data with information about which option was used.\n * The caller of such a codec can provide context about which encoding choice to make as part of the `encode` call without creating\n * additional codecs. Note that this pattern can always be implemented by having the caller create multiple codecs and selecting the\n * appropriate one, but depending on API layering this might be less ergonomic.\n * - Context for the object currently being encoded, which might enable more efficient encoding. When used in this fashion, the codec author\n * should be careful to include the context somewhere in the encoded data such that decoding can correctly round-trip.\n * For example, a composed set of codecs could implement a form of [dictionary coding](https://en.wikipedia.org/wiki/Dictionary_coder)\n * using a context map which was created by the top-level codec and passed to the inner codecs.\n * This pattern is used:\n * - To avoid repeatedly encoding session ids on commits (only recording it once at the top level)\n * @remarks `TEncoded` should always be valid Json (i.e. not contain functions), but due to TypeScript's handling\n * of index signatures and `JsonCompatibleReadOnly`'s index signature in the Json object case, specifying this as a\n * type-system level constraint makes code that uses this interface more difficult to write.\n *\n * If provided, `TValidate` allows the input type passed to `decode` to be different than `TEncoded`.\n * This is useful when, for example, the type being decoded is `unknown` and must be validated to be a `TEncoded` before being decoded to a `TDecoded`.\n */\nexport interface IJsonCodec<\n\tTDecoded,\n\tTEncoded = JsonCompatibleReadOnly,\n\tTValidate = TEncoded,\n\tTContext = void,\n> extends IEncoder<TDecoded, TEncoded, TContext>,\n\t\tIDecoder<TDecoded, TValidate, TContext> {\n\tencodedSchema?: TAnySchema;\n}\n\n/**\n * @remarks TODO: We might consider using DataView or some kind of writer instead of IsoBuffer.\n */\nexport interface IBinaryCodec<TDecoded, TContext = void>\n\textends IEncoder<TDecoded, IsoBuffer, TContext>,\n\t\tIDecoder<TDecoded, IsoBuffer, TContext> {}\n\n/**\n * Contains knowledge of how to encode some in-memory type into JSON and binary formats,\n * as well as how to decode those representations.\n *\n * @remarks Codecs are typically used in shared-tree to convert data into some persisted format.\n * For this common use case, any format for encoding that was ever actually used needs to\n * be supported for decoding in all future code versions.\n *\n * Using an {@link ICodecFamily} is the recommended strategy for managing this support, keeping in\n * mind evolution of encodings over time.\n */\nexport interface IMultiFormatCodec<\n\tTDecoded,\n\tTJsonEncoded extends JsonCompatibleReadOnly = JsonCompatibleReadOnly,\n\tTJsonValidate = TJsonEncoded,\n\tTContext = void,\n> {\n\tjson: IJsonCodec<TDecoded, TJsonEncoded, TJsonValidate, TContext>;\n\tbinary: IBinaryCodec<TDecoded, TContext>;\n\n\t/** Ensures multi-format codecs cannot also be single-format codecs. */\n\tencode?: never;\n\t/** Ensures multi-format codecs cannot also be single-format codecs. */\n\tdecode?: never;\n}\n\n/**\n * Represents a family of codecs that can be used to encode and decode data in different formats.\n * The family is identified by a format version, which is typically used to select the codec to use.\n *\n * Separating codecs into families rather than having a single codec support multiple versions (i.e. currying\n * the `formatVersion` parameter)\n * allows avoiding some duplicate work at encode/decode time, since the vast majority of document usage will not\n * involve mixed format versions.\n *\n * @privateRemarks - This interface currently assumes all codecs in a family require the same encode/decode context,\n * which isn't necessarily true.\n * This may need to be relaxed in the future.\n */\nexport interface ICodecFamily<TDecoded, TContext = void> {\n\t/**\n\t * @returns a codec that can be used to encode and decode data in the specified format.\n\t * @throws - if the format version is not supported by this family.\n\t * @remarks Implementations should typically emit telemetry (either indirectly by throwing a well-known error with\n\t * logged properties or directly using some logger) when a format version is requested that is not supported.\n\t * This ensures that applications can diagnose compatibility issues.\n\t */\n\tresolve(\n\t\tformatVersion: FormatVersion,\n\t): IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>;\n\n\t/**\n\t * @returns an iterable of all format versions supported by this family.\n\t */\n\tgetSupportedFormats(): Iterable<FormatVersion>;\n}\n\n/**\n * A version stamp for encoded data.\n *\n * Undefined is tolerated to enable the scenario where data was not initially versioned.\n */\nexport type FormatVersion = number | undefined;\n\n/**\n * Creates a codec family from a registry of codecs.\n * Any codec that is not a {@link IMultiFormatCodec} will be wrapped with a default binary encoding.\n */\nexport function makeCodecFamily<TDecoded, TContext>(\n\tregistry: Iterable<\n\t\t[\n\t\t\tformatVersion: FormatVersion,\n\t\t\tcodec:\n\t\t\t\t| IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>\n\t\t\t\t| IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,\n\t\t]\n\t>,\n): ICodecFamily<TDecoded, TContext> {\n\tconst codecs: Map<\n\t\tFormatVersion,\n\t\tIMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>\n\t> = new Map();\n\tfor (const [formatVersion, codec] of registry) {\n\t\tif (codecs.has(formatVersion)) {\n\t\t\tfail(0xabf /* Duplicate codecs specified. */);\n\t\t}\n\t\tcodecs.set(formatVersion, ensureBinaryEncoding(codec));\n\t}\n\n\treturn {\n\t\tresolve(\n\t\t\tformatVersion: number,\n\t\t): IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {\n\t\t\tconst codec = codecs.get(formatVersion);\n\t\t\tassert(codec !== undefined, 0x5e6 /* Requested coded for unsupported format. */);\n\t\t\treturn codec;\n\t\t},\n\t\tgetSupportedFormats(): Iterable<FormatVersion> {\n\t\t\treturn codecs.keys();\n\t\t},\n\t};\n}\n\nclass DefaultBinaryCodec<TDecoded, TContext> implements IBinaryCodec<TDecoded, TContext> {\n\tpublic constructor(\n\t\tprivate readonly jsonCodec: IJsonCodec<TDecoded, unknown, unknown, TContext>,\n\t) {}\n\n\tpublic encode(change: TDecoded, context: TContext): IsoBuffer {\n\t\tconst jsonable = this.jsonCodec.encode(change, context);\n\t\tconst json = JSON.stringify(jsonable);\n\t\treturn IsoBuffer.from(json);\n\t}\n\n\tpublic decode(change: IsoBuffer, context: TContext): TDecoded {\n\t\tconst json = bufferToString(change, \"utf8\");\n\t\tconst jsonable = JSON.parse(json);\n\t\treturn this.jsonCodec.decode(jsonable, context);\n\t}\n}\n\nfunction isJsonCodec<TDecoded, TContext>(\n\tcodec:\n\t\t| IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>\n\t\t| IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,\n): codec is IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {\n\treturn typeof codec.encode === \"function\" && typeof codec.decode === \"function\";\n}\n\n/**\n * Constructs a {@link IMultiFormatCodec} from a `IJsonCodec` using a generic binary encoding that simply writes\n * the json representation of the object to a buffer.\n */\nexport function withDefaultBinaryEncoding<TDecoded, TContext>(\n\tjsonCodec: IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,\n): IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {\n\treturn {\n\t\tjson: jsonCodec,\n\t\tbinary: new DefaultBinaryCodec(jsonCodec),\n\t};\n}\n\n/**\n * Ensures that the provided single or multi-format codec has a binary encoding.\n * Adapts the json encoding using {@link withDefaultBinaryEncoding} if necessary.\n */\nexport function ensureBinaryEncoding<TDecoded, TContext>(\n\tcodec:\n\t\t| IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>\n\t\t| IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,\n): IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {\n\treturn isJsonCodec(codec) ? withDefaultBinaryEncoding(codec) : codec;\n}\n\n/**\n * Codec for objects which carry no information.\n */\nexport const unitCodec: IMultiFormatCodec<\n\t0,\n\tJsonCompatibleReadOnly,\n\tJsonCompatibleReadOnly,\n\tunknown\n> = {\n\tjson: {\n\t\tencode: () => 0,\n\t\tdecode: () => 0,\n\t},\n\tbinary: {\n\t\tencode: () => IsoBuffer.from(\"\"),\n\t\tdecode: () => 0,\n\t},\n};\n\n/**\n * Wraps a codec with JSON schema validation for its encoded type.\n * @returns An {@link IJsonCodec} which validates the data it encodes and decodes matches the provided schema.\n */\nexport function withSchemaValidation<\n\tTInMemoryFormat,\n\tEncodedSchema extends TSchema,\n\tTEncodedFormat = JsonCompatibleReadOnly,\n\tTValidate = TEncodedFormat,\n\tTContext = ChangeEncodingContext,\n>(\n\tschema: EncodedSchema,\n\tcodec: IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate, TContext>,\n\tvalidator?: JsonValidator,\n): IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate, TContext> {\n\tif (!validator) {\n\t\treturn codec;\n\t}\n\tconst compiledFormat = validator.compile(schema);\n\treturn {\n\t\tencode: (obj: TInMemoryFormat, context: TContext): TEncodedFormat => {\n\t\t\tconst encoded = codec.encode(obj, context);\n\t\t\tif (!compiledFormat.check(encoded)) {\n\t\t\t\tfail(0xac0 /* Encoded schema should validate */);\n\t\t\t}\n\t\t\treturn encoded;\n\t\t},\n\t\tdecode: (encoded: TValidate, context: TContext): TInMemoryFormat => {\n\t\t\tif (!compiledFormat.check(encoded)) {\n\t\t\t\tfail(0xac1 /* Encoded schema should validate */);\n\t\t\t}\n\t\t\t// TODO: would be nice to provide a more specific validate type to the inner codec than the outer one gets.\n\t\t\treturn codec.decode(encoded, context) as unknown as TInMemoryFormat;\n\t\t},\n\t};\n}\n\n/**\n * Versions of Fluid Framework client packages.\n * @remarks\n * Used to express compatibility requirements by indicating the oldest version with which compatibility must be maintained.\n *\n * When no compatibility-impacting change is made in a given version, the value associated with its enum entry may point to the older version which it's fully compatible with.\n * Note that this can change if a future version of the framework introduces an option to use something which is only supported at a particular version. In which case, the values of the enum may shift,\n * but the semantics of keys in this enum will not change.\n *\n * Do not depend on the value of this enums's entries: only depend on the keys (enum members) themselves.\n *\n * Some release may also be omitted if there is currently no need to express that specific version.\n * If the need arises, they might be added in the future.\n *\n * @privateRemarks\n * Entries in these enums should document the user facing impact of opting into a particular version.\n * For example, document if there is an encoding efficiency improvement of oping into that version or newer.\n * Versions with no notable impact can be omitted.\n *\n * These use numeric values for easy threshold comparisons.\n * Without zero padding, version 2.10 is treated as 2.1, which is numerically less than 2.2.\n * Adding leading zeros to the minor version ensures correct comparisons.\n * For example, version 2.20.0 is encoded as 2.020, and version 2.2.0 is encoded as 2.002.\n * For example FF 2.20.0 is encoded as 2.020 and FF 2.2.0 is encoded as 2.002.\n *\n * Three digits was selected as that will likely be enough, while two digits could easily be too few.\n * If three digits ends up being too few, minor releases of 1000 and higher\n * could still be handled using something like 2.999_00001 without having to change the lower releases.\n *\n * This scheme assumes a single version will always be enough to communicate compatibility.\n * For this to work, compatibility has to be strictly increasing.\n * If this is violated (for example a subset of incompatible features from 3.x that are not in 3.0 are back ported to 2.x),\n * a more complex scheme may be needed to allow safely opting into incompatible features in those cases:\n * such a system can be added if/when its needed since it will be opt in and thus non-breaking.\n *\n * TODO: this should likely be defined higher in the stack and specified when creating the container, possibly as part of its schema.\n * TODO: compatibility requirements for how this enum can and cannot be changed should be clarified when/if it's used across multiple layers in the stack.\n * For example, if needed, would adding more leading zeros to the minor version break things.\n * @alpha\n */\nexport enum FluidClientVersion {\n\t/**\n\t * Fluid Framework Client 1.4 and newer.\n\t * @remarks\n\t * This opts into support for the 1.4 LTS branch.\n\t * @privateRemarks\n\t * As long as this code is in Tree, there is no reason to have this option as SharedTree did not exist in 1.4.\n\t */\n\t// v1_4 = 1.004,\n\n\t/** Fluid Framework Client 2.0 and newer. */\n\tv2_0 = 2.0,\n\n\t/** Fluid Framework Client 2.1 and newer. */\n\t// If we think we might want to start allowing opting into something that landed in 2.1 (without opting into something newer),\n\t// we could add an entry like this to allow users to indicate that they can be opted in once we are ready,\n\t// then update it to \"2.001\" once we actually have the opt in working.\n\t// v2_1 = v2_0,\n\n\t/** Fluid Framework Client 2.41 and newer. */\n\t// If we land some new formats in 2.41, we can enable selecting\n\t// v2_41 = 2.041,\n\n\t/**\n\t * Enable unreleased and unfinished features.\n\t * @remarks\n\t * Using this value can result in documents which can not be opened in future versions of the framework.\n\t * It can also result in data corruption by enabling unfinished features which may not handle all cases correctly.\n\t *\n\t * This can be used with specific APIs when the caller has knowledge of what specific features those APIs will be opted into with it.\n\t * This is useful for testing features before they are released, but should not be used in production code.\n\t */\n\tEnableUnstableFeatures = Number.POSITIVE_INFINITY,\n}\n\n/**\n * An up to date version which includes all the important stable features.\n * @remarks\n * Use for cases when data is not persisted and thus would only ever be read by the current version of the framework.\n *\n * @privateRemarks\n * Update as needed.\n * TODO: Consider using packageVersion.ts to keep this current.\n */\nexport const currentVersion: FluidClientVersion = FluidClientVersion.v2_0;\n"]}

package/dist/codec/index.d.ts

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-export { type FormatVersion, type IBinaryCodec, type ICodecFamily, type ICodecOptions, type IDecoder, type IEncoder, type IJsonCodec, type IMultiFormatCodec, type JsonValidator, makeCodecFamily, type SchemaValidationFunction, unitCodec, withDefaultBinaryEncoding, withSchemaValidation, FluidClientVersion, currentVersion, } from "./codec.js";
+export { type FormatVersion, type IBinaryCodec, type ICodecFamily, type ICodecOptions, type CodecWriteOptions, type IDecoder, type IEncoder, type IJsonCodec, type IMultiFormatCodec, type JsonValidator, makeCodecFamily, type SchemaValidationFunction, unitCodec, withDefaultBinaryEncoding, withSchemaValidation, FluidClientVersion, currentVersion, } from "./codec.js";
 export { DiscriminatedUnionDispatcher, type DiscriminatedUnionLibrary, unionOptions, } from "./discriminatedUnions.js";
 export { noopValidator } from "./noopValidator.js";
 export { Versioned, makeVersionedCodec, makeVersionedValidatedCodec, makeVersionDispatchingCodec, } from "./versioned/index.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/codec/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,eAAe,EACf,KAAK,wBAAwB,EAC7B,SAAS,EACT,yBAAyB,EACzB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,4BAA4B,EAC5B,KAAK,yBAAyB,EAC9B,YAAY,GACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACN,SAAS,EACT,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,GAC3B,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/codec/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,eAAe,EACf,KAAK,wBAAwB,EAC7B,SAAS,EACT,yBAAyB,EACzB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,4BAA4B,EAC5B,KAAK,yBAAyB,EAC9B,YAAY,GACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACN,SAAS,EACT,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,GAC3B,MAAM,sBAAsB,CAAC"}

package/dist/codec/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/codec/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,uCAiBoB;AAPnB,2GAAA,eAAe,OAAA;AAEf,qGAAA,SAAS,OAAA;AACT,qHAAA,yBAAyB,OAAA;AACzB,gHAAA,oBAAoB,OAAA;AACpB,8GAAA,kBAAkB,OAAA;AAClB,0GAAA,cAAc,OAAA;AAEf,mEAIkC;AAHjC,sIAAA,4BAA4B,OAAA;AAE5B,sHAAA,YAAY,OAAA;AAEb,uDAAmD;AAA1C,iHAAA,aAAa,OAAA;AACtB,iDAK8B;AAJ7B,qGAAA,SAAS,OAAA;AACT,8GAAA,kBAAkB,OAAA;AAClB,uHAAA,2BAA2B,OAAA;AAC3B,uHAAA,2BAA2B,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport {\n\ttype FormatVersion,\n\ttype IBinaryCodec,\n\ttype ICodecFamily,\n\ttype ICodecOptions,\n\ttype IDecoder,\n\ttype IEncoder,\n\ttype IJsonCodec,\n\ttype IMultiFormatCodec,\n\ttype JsonValidator,\n\tmakeCodecFamily,\n\ttype SchemaValidationFunction,\n\tunitCodec,\n\twithDefaultBinaryEncoding,\n\twithSchemaValidation,\n\tFluidClientVersion,\n\tcurrentVersion,\n} from \"./codec.js\";\nexport {\n\tDiscriminatedUnionDispatcher,\n\ttype DiscriminatedUnionLibrary,\n\tunionOptions,\n} from \"./discriminatedUnions.js\";\nexport { noopValidator } from \"./noopValidator.js\";\nexport {\n\tVersioned,\n\tmakeVersionedCodec,\n\tmakeVersionedValidatedCodec,\n\tmakeVersionDispatchingCodec,\n} from \"./versioned/index.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/codec/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,uCAkBoB;AAPnB,2GAAA,eAAe,OAAA;AAEf,qGAAA,SAAS,OAAA;AACT,qHAAA,yBAAyB,OAAA;AACzB,gHAAA,oBAAoB,OAAA;AACpB,8GAAA,kBAAkB,OAAA;AAClB,0GAAA,cAAc,OAAA;AAEf,mEAIkC;AAHjC,sIAAA,4BAA4B,OAAA;AAE5B,sHAAA,YAAY,OAAA;AAEb,uDAAmD;AAA1C,iHAAA,aAAa,OAAA;AACtB,iDAK8B;AAJ7B,qGAAA,SAAS,OAAA;AACT,8GAAA,kBAAkB,OAAA;AAClB,uHAAA,2BAA2B,OAAA;AAC3B,uHAAA,2BAA2B,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport {\n\ttype FormatVersion,\n\ttype IBinaryCodec,\n\ttype ICodecFamily,\n\ttype ICodecOptions,\n\ttype CodecWriteOptions,\n\ttype IDecoder,\n\ttype IEncoder,\n\ttype IJsonCodec,\n\ttype IMultiFormatCodec,\n\ttype JsonValidator,\n\tmakeCodecFamily,\n\ttype SchemaValidationFunction,\n\tunitCodec,\n\twithDefaultBinaryEncoding,\n\twithSchemaValidation,\n\tFluidClientVersion,\n\tcurrentVersion,\n} from \"./codec.js\";\nexport {\n\tDiscriminatedUnionDispatcher,\n\ttype DiscriminatedUnionLibrary,\n\tunionOptions,\n} from \"./discriminatedUnions.js\";\nexport { noopValidator } from \"./noopValidator.js\";\nexport {\n\tVersioned,\n\tmakeVersionedCodec,\n\tmakeVersionedValidatedCodec,\n\tmakeVersionDispatchingCodec,\n} from \"./versioned/index.js\";\n"]}

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

@@ -4,16 +4,49 @@
  */
 import type { TSchema } from "@sinclair/typebox";
 import type { JsonCompatibleReadOnly } from "../../util/index.js";
-import { type ICodecFamily, type ICodecOptions, type IJsonCodec, type FormatVersion } from "../codec.js";
+import { type ICodecFamily, type ICodecOptions, type IJsonCodec, type FormatVersion, type FluidClientVersion, type CodecWriteOptions } from "../codec.js";
 import { Versioned } from "./format.js";
 export declare function makeVersionedCodec<TDecoded, TEncoded extends Versioned = JsonCompatibleReadOnly & Versioned, TValidate = TEncoded, TContext = void>(supportedVersions: Set<FormatVersion>, { jsonValidator: validator }: ICodecOptions, inner: IJsonCodec<TDecoded, TEncoded, TValidate, TContext>): IJsonCodec<TDecoded, TEncoded, TValidate, TContext>;
 export declare function makeVersionedValidatedCodec<EncodedSchema extends TSchema, TDecoded, TEncoded extends Versioned = JsonCompatibleReadOnly & Versioned, TValidate = TEncoded, TContext = void>(options: ICodecOptions, supportedVersions: Set<number>, schema: EncodedSchema, codec: IJsonCodec<TDecoded, TEncoded, TValidate, TContext>): IJsonCodec<TDecoded, TEncoded, TValidate, TContext>;
 /**
  * Creates a codec which dispatches to the appropriate member of a codec family based on the version of
  * data it encounters.
- * Each member of the codec family must write an explicit version number into the data it encodes.
+ * @remarks
+ * Each member of the codec family must write an explicit version number into the data it encodes (implementing {@link Versioned}).
+ *
+ * TODO: Users of this should migrate to {@link ClientVersionDispatchingCodecBuilder} so that the actual format version used can be encapsulated.
  */
 export declare function makeVersionDispatchingCodec<TDecoded, TContext>(family: ICodecFamily<TDecoded, TContext>, options: ICodecOptions & {
     writeVersion: number;
 }): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>;
+/**
+ * Creates a codec which dispatches to the appropriate member of a codec family based on the `oldestCompatibleClient` 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 declare class ClientVersionDispatchingCodecBuilder<TDecoded, TContext> {
+    /**
+     * The codec family to dispatch to.
+     */
+    private readonly family;
+    /**
+     * A function which maps a {@link FluidClientVersion} 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.
+     */
+    private readonly versionMapping;
+    constructor(
+    /**
+     * The codec family to dispatch to.
+     */
+    family: ICodecFamily<TDecoded, TContext>, 
+    /**
+     * A function which maps a {@link FluidClientVersion} 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.
+     */
+    versionMapping: (oldestCompatibleClient: FluidClientVersion) => number);
+    build(options: CodecWriteOptions): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>;
+}
 //# 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":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,UAAU,EAEf,KAAK,aAAa,EAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,wBAAgB,kBAAkB,CACjC,QAAQ,EACR,QAAQ,SAAS,SAAS,GAAG,sBAAsB,GAAG,SAAS,EAC/D,SAAS,GAAG,QAAQ,EACpB,QAAQ,GAAG,IAAI,EAEf,iBAAiB,EAAE,GAAG,CAAC,aAAa,CAAC,EACrC,EAAE,aAAa,EAAE,SAAS,EAAE,EAAE,aAAa,EAC3C,KAAK,EAAE,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,GACxD,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,CAwBrD;AAED,wBAAgB,2BAA2B,CAC1C,aAAa,SAAS,OAAO,EAC7B,QAAQ,EACR,QAAQ,SAAS,SAAS,GAAG,sBAAsB,GAAG,SAAS,EAC/D,SAAS,GAAG,QAAQ,EACpB,QAAQ,GAAG,IAAI,EAEf,OAAO,EAAE,aAAa,EACtB,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,EAC9B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,GACxD,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,CAMrD;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,QAAQ,EAC7D,MAAM,EAAE,YAAY,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACxC,OAAO,EAAE,aAAa,GAAG;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,GAC/C,UAAU,CAAC,QAAQ,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,QAAQ,CAAC,CAYhF"}
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../../src/codec/versioned/codec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,UAAU,EAEf,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,wBAAgB,kBAAkB,CACjC,QAAQ,EACR,QAAQ,SAAS,SAAS,GAAG,sBAAsB,GAAG,SAAS,EAC/D,SAAS,GAAG,QAAQ,EACpB,QAAQ,GAAG,IAAI,EAEf,iBAAiB,EAAE,GAAG,CAAC,aAAa,CAAC,EACrC,EAAE,aAAa,EAAE,SAAS,EAAE,EAAE,aAAa,EAC3C,KAAK,EAAE,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,GACxD,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,CA0BrD;AAED,wBAAgB,2BAA2B,CAC1C,aAAa,SAAS,OAAO,EAC7B,QAAQ,EACR,QAAQ,SAAS,SAAS,GAAG,sBAAsB,GAAG,SAAS,EAC/D,SAAS,GAAG,QAAQ,EACpB,QAAQ,GAAG,IAAI,EAEf,OAAO,EAAE,aAAa,EACtB,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,EAC9B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,GACxD,UAAU,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,CAMrD;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,QAAQ,EAC7D,MAAM,EAAE,YAAY,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACxC,OAAO,EAAE,aAAa,GAAG;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,GAC/C,UAAU,CAAC,QAAQ,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,QAAQ,CAAC,CAYhF;AAED;;;;;GAKG;AACH,qBAAa,oCAAoC,CAAC,QAAQ,EAAE,QAAQ;IAElE;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc;;IAT/B;;OAEG;IACc,MAAM,EAAE,YAAY,CAAC,QAAQ,EAAE,QAAQ,CAAC;IACzD;;;;OAIG;IACc,cAAc,EAAE,CAAC,sBAAsB,EAAE,kBAAkB,KAAK,MAAM;IAGjF,KAAK,CACX,OAAO,EAAE,iBAAiB,GACxB,UAAU,CAAC,QAAQ,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,QAAQ,CAAC;CAIjF"}

package/dist/codec/versioned/codec.js

@@ -4,10 +4,12 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.makeVersionDispatchingCodec = exports.makeVersionedValidatedCodec = exports.makeVersionedCodec = void 0;
+exports.ClientVersionDispatchingCodecBuilder = exports.makeVersionDispatchingCodec = exports.makeVersionedValidatedCodec = exports.makeVersionedCodec = void 0;
 const internal_1 = require("@fluidframework/core-utils/internal");
+const internal_2 = require("@fluidframework/telemetry-utils/internal");
 const codec_js_1 = require("../codec.js");
 const format_js_1 = require("./format.js");
+const packageVersion_js_1 = require("../../packageVersion.js");
 function makeVersionedCodec(supportedVersions, { jsonValidator: validator }, inner) {
     const codec = {
         encode: (data, context) => {
@@ -17,7 +19,10 @@ function makeVersionedCodec(supportedVersions, { jsonValidator: validator }, inn
         },
         decode: (data, context) => {
             const versioned = data; // Validated by withSchemaValidation
-            (0, internal_1.assert)(supportedVersions.has(versioned.version), 0x88c /* version being decoded is not supported */);
+            if (!supportedVersions.has(versioned.version)) {
+                throw new internal_2.UsageError(`Unsupported version ${versioned.version} encountered while decoding data. Supported versions for this data are: ${Array.from(supportedVersions).join(", ")}.
+The client which encoded this data likely specified an "oldestCompatibleClient" value which corresponds to a version newer than the version of this client ("${packageVersion_js_1.pkgVersion}").`);
+            }
             const decoded = inner.decode(data, context);
             return decoded;
         },
@@ -34,7 +39,10 @@ exports.makeVersionedValidatedCodec = makeVersionedValidatedCodec;
 /**
  * Creates a codec which dispatches to the appropriate member of a codec family based on the version of
  * data it encounters.
- * Each member of the codec family must write an explicit version number into the data it encodes.
+ * @remarks
+ * Each member of the codec family must write an explicit version number into the data it encodes (implementing {@link Versioned}).
+ *
+ * TODO: Users of this should migrate to {@link ClientVersionDispatchingCodecBuilder} so that the actual format version used can be encapsulated.
  */
 function makeVersionDispatchingCodec(family, options) {
     const writeCodec = family.resolve(options.writeVersion).json;
@@ -50,4 +58,31 @@ function makeVersionDispatchingCodec(family, options) {
     });
 }
 exports.makeVersionDispatchingCodec = makeVersionDispatchingCodec;
+/**
+ * Creates a codec which dispatches to the appropriate member of a codec family based on the `oldestCompatibleClient` 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.
+ */
+class ClientVersionDispatchingCodecBuilder {
+    constructor(
+    /**
+     * The codec family to dispatch to.
+     */
+    family, 
+    /**
+     * A function which maps a {@link FluidClientVersion} 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.
+     */
+    versionMapping) {
+        this.family = family;
+        this.versionMapping = versionMapping;
+    }
+    build(options) {
+        const writeVersion = this.versionMapping(options.oldestCompatibleClient);
+        return makeVersionDispatchingCodec(this.family, { ...options, writeVersion });
+    }
+}
+exports.ClientVersionDispatchingCodecBuilder = ClientVersionDispatchingCodecBuilder;
 //# sourceMappingURL=codec.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../../src/codec/versioned/codec.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,kEAA6D;AAI7D,0CAMqB;AAErB,2CAAwC;AAExC,SAAgB,kBAAkB,CAMjC,iBAAqC,EACrC,EAAE,aAAa,EAAE,SAAS,EAAiB,EAC3C,KAA0D;IAE1D,MAAM,KAAK,GAAG;QACb,MAAM,EAAE,CAAC,IAAc,EAAE,OAAiB,EAAY,EAAE;YACvD,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC5C,IAAA,iBAAM,EACL,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,EACtC,KAAK,CAAC,+CAA+C,CACrD,CAAC;YACF,OAAO,OAAO,CAAC;QAChB,CAAC;QACD,MAAM,EAAE,CAAC,IAAe,EAAE,OAAiB,EAAY,EAAE;YACxD,MAAM,SAAS,GAAG,IAAiB,CAAC,CAAC,oCAAoC;YACzE,IAAA,iBAAM,EACL,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,EACxC,KAAK,CAAC,4CAA4C,CAClD,CAAC;YACF,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC5C,OAAO,OAAO,CAAC;QAChB,CAAC;KACD,CAAC;IAEF,OAAO,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC;QACtC,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,IAAA,+BAAoB,EAAC,qBAAS,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;AACtD,CAAC;AAjCD,gDAiCC;AAED,SAAgB,2BAA2B,CAO1C,OAAsB,EACtB,iBAA8B,EAC9B,MAAqB,EACrB,KAA0D;IAE1D,OAAO,kBAAkB,CACxB,iBAAiB,EACjB,OAAO,EACP,IAAA,+BAAoB,EAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,CAC1D,CAAC;AACH,CAAC;AAjBD,kEAiBC;AAED;;;;GAIG;AACH,SAAgB,2BAA2B,CAC1C,MAAwC,EACxC,OAAiD;IAEjD,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC;IAC7D,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAChE,OAAO,kBAAkB,CAAC,iBAAiB,EAAE,OAAO,EAAE;QACrD,MAAM,CAAC,IAAI,EAAE,OAAO;YACnB,OAAO,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAc,CAAC;QACtD,CAAC;QACD,MAAM,CAAC,IAAe,EAAE,OAAO;YAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC3C,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC;KACD,CAAC,CAAC;AACJ,CAAC;AAfD,kEAeC","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 { TSchema } from \"@sinclair/typebox\";\n\nimport type { JsonCompatibleReadOnly } from \"../../util/index.js\";\nimport {\n\ttype ICodecFamily,\n\ttype ICodecOptions,\n\ttype IJsonCodec,\n\twithSchemaValidation,\n\ttype FormatVersion,\n} from \"../codec.js\";\n\nimport { Versioned } from \"./format.js\";\n\nexport function makeVersionedCodec<\n\tTDecoded,\n\tTEncoded extends Versioned = JsonCompatibleReadOnly & Versioned,\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\tassert(\n\t\t\t\tsupportedVersions.has(versioned.version),\n\t\t\t\t0x88c /* version being decoded is not supported */,\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\treturn supportedVersions.has(undefined)\n\t\t? codec\n\t\t: withSchemaValidation(Versioned, codec, validator);\n}\n\nexport function makeVersionedValidatedCodec<\n\tEncodedSchema extends TSchema,\n\tTDecoded,\n\tTEncoded extends Versioned = JsonCompatibleReadOnly & Versioned,\n\tTValidate = TEncoded,\n\tTContext = void,\n>(\n\toptions: ICodecOptions,\n\tsupportedVersions: Set<number>,\n\tschema: EncodedSchema,\n\tcodec: IJsonCodec<TDecoded, TEncoded, TValidate, TContext>,\n): IJsonCodec<TDecoded, TEncoded, TValidate, TContext> {\n\treturn makeVersionedCodec(\n\t\tsupportedVersions,\n\t\toptions,\n\t\twithSchemaValidation(schema, codec, options.jsonValidator),\n\t);\n}\n\n/**\n * Creates a codec which dispatches to the appropriate member of a codec family based on the version of\n * data it encounters.\n * Each member of the codec family must write an explicit version number into the data it encodes.\n */\nexport function makeVersionDispatchingCodec<TDecoded, TContext>(\n\tfamily: ICodecFamily<TDecoded, TContext>,\n\toptions: ICodecOptions & { writeVersion: number },\n): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {\n\tconst writeCodec = family.resolve(options.writeVersion).json;\n\tconst supportedVersions = new Set(family.getSupportedFormats());\n\treturn makeVersionedCodec(supportedVersions, options, {\n\t\tencode(data, context): Versioned {\n\t\t\treturn writeCodec.encode(data, context) as Versioned;\n\t\t},\n\t\tdecode(data: Versioned, context) {\n\t\t\tconst codec = family.resolve(data.version);\n\t\t\treturn codec.json.decode(data, context);\n\t\t},\n\t});\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 } from \"@fluidframework/core-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport type { TSchema } from \"@sinclair/typebox\";\n\nimport type { JsonCompatibleReadOnly } from \"../../util/index.js\";\nimport {\n\ttype ICodecFamily,\n\ttype ICodecOptions,\n\ttype IJsonCodec,\n\twithSchemaValidation,\n\ttype FormatVersion,\n\ttype FluidClientVersion,\n\ttype CodecWriteOptions,\n} from \"../codec.js\";\n\nimport { Versioned } from \"./format.js\";\nimport { pkgVersion } from \"../../packageVersion.js\";\n\nexport function makeVersionedCodec<\n\tTDecoded,\n\tTEncoded extends Versioned = JsonCompatibleReadOnly & Versioned,\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: ${Array.from(supportedVersions).join(\", \")}.\nThe client which encoded this data likely specified an \"oldestCompatibleClient\" 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\treturn supportedVersions.has(undefined)\n\t\t? codec\n\t\t: withSchemaValidation(Versioned, codec, validator);\n}\n\nexport function makeVersionedValidatedCodec<\n\tEncodedSchema extends TSchema,\n\tTDecoded,\n\tTEncoded extends Versioned = JsonCompatibleReadOnly & Versioned,\n\tTValidate = TEncoded,\n\tTContext = void,\n>(\n\toptions: ICodecOptions,\n\tsupportedVersions: Set<number>,\n\tschema: EncodedSchema,\n\tcodec: IJsonCodec<TDecoded, TEncoded, TValidate, TContext>,\n): IJsonCodec<TDecoded, TEncoded, TValidate, TContext> {\n\treturn makeVersionedCodec(\n\t\tsupportedVersions,\n\t\toptions,\n\t\twithSchemaValidation(schema, codec, options.jsonValidator),\n\t);\n}\n\n/**\n * Creates a codec which dispatches to the appropriate member of a codec family based on the version of\n * data it encounters.\n * @remarks\n * Each member of the codec family must write an explicit version number into the data it encodes (implementing {@link Versioned}).\n *\n * TODO: Users of this should migrate to {@link ClientVersionDispatchingCodecBuilder} so that the actual format version used can be encapsulated.\n */\nexport function makeVersionDispatchingCodec<TDecoded, TContext>(\n\tfamily: ICodecFamily<TDecoded, TContext>,\n\toptions: ICodecOptions & { writeVersion: number },\n): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {\n\tconst writeCodec = family.resolve(options.writeVersion).json;\n\tconst supportedVersions = new Set(family.getSupportedFormats());\n\treturn makeVersionedCodec(supportedVersions, options, {\n\t\tencode(data, context): Versioned {\n\t\t\treturn writeCodec.encode(data, context) as Versioned;\n\t\t},\n\t\tdecode(data: Versioned, context) {\n\t\t\tconst codec = family.resolve(data.version);\n\t\t\treturn codec.json.decode(data, context);\n\t\t},\n\t});\n}\n\n/**\n * Creates a codec which dispatches to the appropriate member of a codec family based on the `oldestCompatibleClient` 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<TDecoded, TContext> {\n\tpublic constructor(\n\t\t/**\n\t\t * The codec family to dispatch to.\n\t\t */\n\t\tprivate readonly family: ICodecFamily<TDecoded, TContext>,\n\t\t/**\n\t\t * A function which maps a {@link FluidClientVersion} to a version number for the codec family which is supported by that version.\n\t\t * This can (and typically does) pick the newest version of the codec which is known to be compatible with the client version so that\n\t\t * any improvements in newer versions of the codec can be used when allowed.\n\t\t */\n\t\tprivate readonly versionMapping: (oldestCompatibleClient: FluidClientVersion) => number,\n\t) {}\n\n\tpublic build(\n\t\toptions: CodecWriteOptions,\n\t): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {\n\t\tconst writeVersion = this.versionMapping(options.oldestCompatibleClient);\n\t\treturn makeVersionDispatchingCodec(this.family, { ...options, writeVersion });\n\t}\n}\n"]}

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 import type { IIdCompressor } from "@fluidframework/id-compressor";
-import { type ICodecOptions } from "../../codec/index.js";
+import { type CodecWriteOptions } from "../../codec/index.js";
 import { type IdAllocator, type JsonCompatibleReadOnly } from "../../util/index.js";
 import type { RevisionTag, RevisionTagCodec } from "../rebase/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
@@ -44,7 +44,7 @@ export declare class DetachedFieldIndex {
      * @param name - A name for the index, used as a prefix for the generated field keys.
      * @param rootIdAllocator - An ID allocator used to generate unique field keys.
      */
-    constructor(name: string, rootIdAllocator: IdAllocator<ForestRootId>, revisionTagCodec: RevisionTagCodec, idCompressor: IIdCompressor, options?: ICodecOptions);
+    constructor(name: string, rootIdAllocator: IdAllocator<ForestRootId>, revisionTagCodec: RevisionTagCodec, idCompressor: IIdCompressor, options?: CodecWriteOptions);
     clone(): DetachedFieldIndex;
     entries(): Generator<{
         root: ForestRootId;

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

@@ -1 +1 @@
-{"version":3,"file":"detachedFieldIndex.d.ts","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndex.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,EAAE,KAAK,aAAa,EAAkC,MAAM,sBAAsB,CAAC;AAC1F,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAS3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAC;AAGzC,OAAO,KAAK,EAGX,YAAY,EACZ,KAAK,EAEL,MAAM,8BAA8B,CAAC;AAEtC;;GAEG;AACH,qBAAa,kBAAkB;IAoC7B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,eAAe;IACvB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAtC9B;;OAEG;IACH,OAAO,CAAC,mBAAmB,CAAqD;IAChF;;;;;;OAMG;IACH,OAAO,CAAC,8BAA8B,CAIxB;IAEd,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+C;IACrE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IAExC;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa,CAAQ;IAE7B;;;OAGG;gBAEe,IAAI,EAAE,MAAM,EACrB,eAAe,EAAE,WAAW,CAAC,YAAY,CAAC,EACjC,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,EAC5C,OAAO,CAAC,EAAE,aAAa;IAMjB,KAAK,IAAI,kBAAkB;IAiB1B,OAAO,IAAI,SAAS,CAAC;QAC5B,IAAI,EAAE,YAAY,CAAC;QACnB,sBAAsB,CAAC,EAAE,WAAW,CAAC;QACrC,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC;KACzB,CAAC;IAkBF;;OAEG;IACI,KAAK,IAAI,IAAI;IAKb,WAAW,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,GAAG,IAAI;IAiExD;;;OAGG;IACI,UAAU,CAAC,EAAE,EAAE,YAAY,GAAG,QAAQ;IAI7C;;;OAGG;IACI,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,cAAc,GAAG,YAAY,GAAG,SAAS;IAItE;;;OAGG;IACI,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,cAAc,GAAG,YAAY;IAMvD;;OAEG;IACK,6BAA6B,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,CAAC,YAAY,CAAC;IAOpF;;OAEG;IACI,gCAAgC,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI;IAiB7D,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,cAAc,GAAG,IAAI;IAWtD;;;;;;;OAOG;IACI,WAAW,CACjB,MAAM,CAAC,EAAE,KAAK,CAAC,cAAc,EAC7B,QAAQ,CAAC,EAAE,WAAW,EACtB,KAAK,GAAE,MAAU,GACf,YAAY;IAmBf;;OAEG;IACI,oBAAoB,CAC1B,EAAE,EAAE,KAAK,CAAC,cAAc,EACxB,QAAQ,EAAE,WAAW,GAAG,SAAS,GAC/B,IAAI;IAmBA,MAAM,IAAI,sBAAsB;IAOvC;;OAEG;IACI,QAAQ,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI;IAmBnD;;;;OAIG;IACI,yBAAyB,CAAC,cAAc,EAAE,WAAW,GAAG,IAAI;CAqBnE"}
+{"version":3,"file":"detachedFieldIndex.d.ts","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndex.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,EACN,KAAK,iBAAiB,EAItB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAS3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAC;AAGzC,OAAO,KAAK,EAGX,YAAY,EACZ,KAAK,EAEL,MAAM,8BAA8B,CAAC;AAEtC;;GAEG;AACH,qBAAa,kBAAkB;IAoC7B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,eAAe;IACvB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAtC9B;;OAEG;IACH,OAAO,CAAC,mBAAmB,CAAqD;IAChF;;;;;;OAMG;IACH,OAAO,CAAC,8BAA8B,CAIxB;IAEd,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+C;IACrE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAE5C;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa,CAAQ;IAE7B;;;OAGG;gBAEe,IAAI,EAAE,MAAM,EACrB,eAAe,EAAE,WAAW,CAAC,YAAY,CAAC,EACjC,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,EAC5C,OAAO,CAAC,EAAE,iBAAiB;IAUrB,KAAK,IAAI,kBAAkB;IAiB1B,OAAO,IAAI,SAAS,CAAC;QAC5B,IAAI,EAAE,YAAY,CAAC;QACnB,sBAAsB,CAAC,EAAE,WAAW,CAAC;QACrC,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC;KACzB,CAAC;IAkBF;;OAEG;IACI,KAAK,IAAI,IAAI;IAKb,WAAW,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,GAAG,IAAI;IAiExD;;;OAGG;IACI,UAAU,CAAC,EAAE,EAAE,YAAY,GAAG,QAAQ;IAI7C;;;OAGG;IACI,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,cAAc,GAAG,YAAY,GAAG,SAAS;IAItE;;;OAGG;IACI,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,cAAc,GAAG,YAAY;IAMvD;;OAEG;IACK,6BAA6B,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,CAAC,YAAY,CAAC;IAOpF;;OAEG;IACI,gCAAgC,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI;IAiB7D,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,cAAc,GAAG,IAAI;IAWtD;;;;;;;OAOG;IACI,WAAW,CACjB,MAAM,CAAC,EAAE,KAAK,CAAC,cAAc,EAC7B,QAAQ,CAAC,EAAE,WAAW,EACtB,KAAK,GAAE,MAAU,GACf,YAAY;IAmBf;;OAEG;IACI,oBAAoB,CAC1B,EAAE,EAAE,KAAK,CAAC,cAAc,EACxB,QAAQ,EAAE,WAAW,GAAG,SAAS,GAC/B,IAAI;IAmBA,MAAM,IAAI,sBAAsB;IAOvC;;OAEG;IACI,QAAQ,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI;IAmBnD;;;;OAIG;IACI,yBAAyB,CAAC,cAAc,EAAE,WAAW,GAAG,IAAI;CAqBnE"}

package/dist/core/tree/detachedFieldIndex.js

@@ -43,7 +43,11 @@ class DetachedFieldIndex {
          * This helps ensure that `setRevisionsForLoadedData` is only called after `loadData` and only called once.
          */
         this.isFullyLoaded = true;
-        this.options = options ?? { jsonValidator: index_js_1.noopValidator };
+        this.options = options ?? {
+            jsonValidator: index_js_1.noopValidator,
+            oldestCompatibleClient: index_js_1.FluidClientVersion.v2_0,
+        };
+        // TODO: this should take in CodecWriteOptions, and use it to pick the write version.
         this.codec = (0, detachedFieldIndexCodec_js_1.makeDetachedNodeToFieldCodec)(revisionTagCodec, this.options, idCompressor);
     }
     clone() {