@fluidframework/tree 2.81.1 → 2.83.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.81.1",
+  "version": "2.83.0",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -101,19 +101,19 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.81.1",
-    "@fluidframework/container-runtime": "~2.81.1",
-    "@fluidframework/core-interfaces": "~2.81.1",
-    "@fluidframework/core-utils": "~2.81.1",
-    "@fluidframework/datastore-definitions": "~2.81.1",
-    "@fluidframework/driver-definitions": "~2.81.1",
-    "@fluidframework/id-compressor": "~2.81.1",
-    "@fluidframework/runtime-definitions": "~2.81.1",
-    "@fluidframework/runtime-utils": "~2.81.1",
-    "@fluidframework/shared-object-base": "~2.81.1",
-    "@fluidframework/telemetry-utils": "~2.81.1",
+    "@fluid-internal/client-utils": "~2.83.0",
+    "@fluidframework/container-runtime": "~2.83.0",
+    "@fluidframework/core-interfaces": "~2.83.0",
+    "@fluidframework/core-utils": "~2.83.0",
+    "@fluidframework/datastore-definitions": "~2.83.0",
+    "@fluidframework/driver-definitions": "~2.83.0",
+    "@fluidframework/id-compressor": "~2.83.0",
+    "@fluidframework/runtime-definitions": "~2.83.0",
+    "@fluidframework/runtime-utils": "~2.83.0",
+    "@fluidframework/shared-object-base": "~2.83.0",
+    "@fluidframework/telemetry-utils": "~2.83.0",
     "@sinclair/typebox": "^0.34.13",
-    "@tylerbu/sorted-btree-es6": "^1.8.0",
+    "@tylerbu/sorted-btree-es6": "^2.1.1",
     "@types/ungap__structured-clone": "^1.2.0",
     "@ungap/structured-clone": "^1.2.0",
     "semver-ts": "^1.0.3",
@@ -122,25 +122,25 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "~2.81.1",
-    "@fluid-private/stochastic-test-utils": "~2.81.1",
-    "@fluid-private/test-dds-utils": "~2.81.1",
-    "@fluid-private/test-drivers": "~2.81.1",
+    "@fluid-internal/mocha-test-setup": "~2.83.0",
+    "@fluid-private/stochastic-test-utils": "~2.83.0",
+    "@fluid-private/test-dds-utils": "~2.83.0",
+    "@fluid-private/test-drivers": "~2.83.0",
     "@fluid-tools/benchmark": "^0.52.0",
     "@fluid-tools/build-cli": "^0.63.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.63.0",
-    "@fluidframework/container-definitions": "~2.81.1",
-    "@fluidframework/container-loader": "~2.81.1",
-    "@fluidframework/eslint-config-fluid": "~2.81.1",
-    "@fluidframework/test-runtime-utils": "~2.81.1",
-    "@fluidframework/test-utils": "~2.81.1",
-    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.81.0",
+    "@fluidframework/container-definitions": "~2.83.0",
+    "@fluidframework/container-loader": "~2.83.0",
+    "@fluidframework/eslint-config-fluid": "~2.83.0",
+    "@fluidframework/test-runtime-utils": "~2.83.0",
+    "@fluidframework/test-utils": "~2.83.0",
+    "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.82.0",
     "@microsoft/api-extractor": "7.52.11",
     "@types/diff": "^3.5.1",
     "@types/easy-table": "^0.0.32",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^18.19.0",
+    "@types/node": "~20.19.30",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "c8": "^10.1.3",

package/src/codec/codec.ts

@@ -3,14 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import { IsoBuffer, bufferToString } from "@fluid-internal/client-utils";
 import type { ErasedType } from "@fluidframework/core-interfaces/internal";
 import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
 import { cleanedPackageVersion as runtimeUtilsCleanedPackageVersion } from "@fluidframework/runtime-utils/internal";
 import type { Static, TAnySchema, TSchema } from "@sinclair/typebox";
 
-import type { ChangeEncodingContext } from "../core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";
 
 /**
@@ -139,11 +137,9 @@ export interface ICodecOptions {
 
 /**
  * Options relating to encoding of persisted data.
- * @remarks
- * Extends {@link ICodecOptions} with options that are specific to encoding data.
- * @alpha @input
+ * @input @beta
  */
-export interface CodecWriteOptions extends ICodecOptions {
+export interface CodecWriteOptionsBeta {
 	/**
 	 * The minimum version of the Fluid Framework client output must be encoded to be compatible with.
 	 * @remarks
@@ -154,16 +150,24 @@ export interface CodecWriteOptions extends ICodecOptions {
 	 * the data's format should be versioned and if they can't handle the format they should error.
 	 */
 	readonly minVersionForCollab: MinimumVersionForCollab;
+}
 
+/**
+ * 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, CodecWriteOptionsBeta {
 	/**
 	 * Overrides the version of the codec to use for encoding.
 	 * @remarks
-	 * Without an override, the selected version will be based on {@link CodecWriteOptions.minVersionForCollab}.
+	 * Without an override, the selected version will be based on {@link CodecWriteOptionsBeta.minVersionForCollab}.
 	 */
 	readonly writeVersionOverrides?: ReadonlyMap<CodecName, FormatVersion>;
 
 	/**
-	 * If true, suppress errors when `writeVersionOverrides` selects a version which may not be compatible with the {@link CodecWriteOptions.minVersionForCollab}.
+	 * If true, suppress errors when `writeVersionOverrides` selects a version which may not be compatible with the {@link CodecWriteOptionsBeta.minVersionForCollab}.
 	 */
 	readonly allowPossiblyIncompatibleWriteVersionOverrides?: boolean;
 }
@@ -199,36 +203,17 @@ export interface IJsonCodec<
 }
 
 /**
- * @remarks TODO: We might consider using DataView or some kind of writer instead of IsoBuffer.
+ * Type erase the more detailed encoded type from a codec.
  */
-export interface IBinaryCodec<TDecoded, TContext = void>
-	extends IEncoder<TDecoded, IsoBuffer, TContext>,
-		IDecoder<TDecoded, IsoBuffer, TContext> {}
-
-/**
- * Contains knowledge of how to encode some in-memory type into JSON and binary formats,
- * as well as how to decode those representations.
- *
- * @remarks Codecs are typically used in shared-tree to convert data into some persisted format.
- * For this common use case, any format for encoding that was ever actually used needs to
- * be supported for decoding in all future code versions.
- *
- * Using an {@link ICodecFamily} is the recommended strategy for managing this support, keeping in
- * mind evolution of encodings over time.
- */
-export interface IMultiFormatCodec<
+export function eraseEncodedType<
 	TDecoded,
-	TJsonEncoded extends JsonCompatibleReadOnly = JsonCompatibleReadOnly,
-	TJsonValidate = TJsonEncoded,
+	TEncoded = JsonCompatibleReadOnly,
+	TValidate = TEncoded,
 	TContext = void,
-> {
-	json: IJsonCodec<TDecoded, TJsonEncoded, TJsonValidate, TContext>;
-	binary: IBinaryCodec<TDecoded, TContext>;
-
-	/** Ensures multi-format codecs cannot also be single-format codecs. */
-	encode?: never;
-	/** Ensures multi-format codecs cannot also be single-format codecs. */
-	decode?: never;
+>(
+	codec: IJsonCodec<TDecoded, TEncoded, TValidate, TContext>,
+): IJsonCodec<TDecoded, TValidate, TValidate, TContext> {
+	return codec as unknown as IJsonCodec<TDecoded, TValidate, TValidate, TContext>;
 }
 
 /**
@@ -254,7 +239,7 @@ export interface ICodecFamily<TDecoded, TContext = void> {
 	 */
 	resolve(
 		formatVersion: FormatVersion,
-	): IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>;
+	): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>;
 
 	/**
 	 * @returns an iterable of all format versions supported by this family.
@@ -331,35 +316,32 @@ export const DependentFormatVersion = {
 
 /**
  * Creates a codec family from a registry of codecs.
- * Any codec that is not a {@link IMultiFormatCodec} will be wrapped with a default binary encoding.
  */
 export function makeCodecFamily<TDecoded, TContext>(
 	registry: Iterable<
 		[
 			formatVersion: FormatVersion,
-			codec:
-				| IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>
-				| IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,
+			codec: IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,
 		]
 	>,
 ): ICodecFamily<TDecoded, TContext> {
 	const codecs: Map<
 		FormatVersion,
-		IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>
+		IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>
 	> = new Map();
 	for (const [formatVersion, codec] of registry) {
 		if (codecs.has(formatVersion)) {
 			fail(0xabf /* Duplicate codecs specified. */);
 		}
-		codecs.set(formatVersion, ensureBinaryEncoding(codec));
+		codecs.set(formatVersion, codec);
 	}
 
 	return {
 		resolve(
-			formatVersion: number,
-		): IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
+			formatVersion: FormatVersion,
+		): IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
 			const codec = codecs.get(formatVersion);
-			assert(codec !== undefined, 0x5e6 /* Requested coded for unsupported format. */);
+			assert(codec !== undefined, 0x5e6 /* Requested codec for unsupported format. */);
 			return codec;
 		},
 		getSupportedFormats(): Iterable<FormatVersion> {
@@ -368,82 +350,17 @@ export function makeCodecFamily<TDecoded, TContext>(
 	};
 }
 
-class DefaultBinaryCodec<TDecoded, TContext> implements IBinaryCodec<TDecoded, TContext> {
-	public constructor(
-		private readonly jsonCodec: IJsonCodec<TDecoded, unknown, unknown, TContext>,
-	) {}
-
-	public encode(change: TDecoded, context: TContext): IsoBuffer {
-		const jsonable = this.jsonCodec.encode(change, context);
-		const json = JSON.stringify(jsonable);
-		return IsoBuffer.from(json);
-	}
-
-	public decode(change: IsoBuffer, context: TContext): TDecoded {
-		const json = bufferToString(change, "utf8");
-		const jsonable = JSON.parse(json);
-		return this.jsonCodec.decode(jsonable, context);
-	}
-}
-
-function isJsonCodec<TDecoded, TContext>(
-	codec:
-		| IMultiFormatCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>
-		| IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext>,
-): codec is IJsonCodec<TDecoded, JsonCompatibleReadOnly, JsonCompatibleReadOnly, TContext> {
-	return typeof codec.encode === "function" && typeof codec.decode === "function";
-}
-
-/**
- * Constructs a {@link IMultiFormatCodec} from a `IJsonCodec` using a generic binary encoding that simply writes
- * the json representation of the object to a buffer.
- */
-export function withDefaultBinaryEncoding<
-	TDecoded,
-	TContext,
-	TEncoded extends JsonCompatibleReadOnly = JsonCompatibleReadOnly,
->(
-	jsonCodec: IJsonCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext>,
-): IMultiFormatCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext> {
-	return {
-		json: jsonCodec,
-		binary: new DefaultBinaryCodec(jsonCodec),
-	};
-}
-
-/**
- * Ensures that the provided single or multi-format codec has a binary encoding.
- * Adapts the json encoding using {@link withDefaultBinaryEncoding} if necessary.
- */
-export function ensureBinaryEncoding<
-	TDecoded,
-	TContext,
-	TEncoded extends JsonCompatibleReadOnly = JsonCompatibleReadOnly,
->(
-	codec:
-		| IMultiFormatCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext>
-		| IJsonCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext>,
-): IMultiFormatCodec<TDecoded, TEncoded, JsonCompatibleReadOnly, TContext> {
-	return isJsonCodec(codec) ? withDefaultBinaryEncoding(codec) : codec;
-}
-
 /**
  * Codec for objects which carry no information.
  */
-export const unitCodec: IMultiFormatCodec<
+export const unitCodec: IJsonCodec<
 	0,
 	JsonCompatibleReadOnly,
 	JsonCompatibleReadOnly,
 	unknown
 > = {
-	json: {
-		encode: () => 0,
-		decode: () => 0,
-	},
-	binary: {
-		encode: () => IsoBuffer.from(""),
-		decode: () => 0,
-	},
+	encode: () => 0,
+	decode: () => 0,
 };
 
 /**
@@ -453,9 +370,9 @@ export const unitCodec: IMultiFormatCodec<
 export function withSchemaValidation<
 	TInMemoryFormat,
 	EncodedSchema extends TSchema,
-	TEncodedFormat = JsonCompatibleReadOnly,
-	TValidate = TEncodedFormat,
-	TContext = ChangeEncodingContext,
+	TEncodedFormat,
+	TValidate,
+	TContext,
 >(
 	schema: EncodedSchema,
 	codec: IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate, TContext>,

package/src/codec/index.ts

@@ -6,19 +6,17 @@
 export {
 	type FormatVersion,
 	DependentFormatVersion,
-	type IBinaryCodec,
 	type ICodecFamily,
 	type ICodecOptions,
 	type CodecWriteOptions,
+	type CodecWriteOptionsBeta,
 	type IDecoder,
 	type IEncoder,
 	type IJsonCodec,
-	type IMultiFormatCodec,
 	type JsonValidator,
 	makeCodecFamily,
 	type SchemaValidationFunction,
 	unitCodec,
-	withDefaultBinaryEncoding,
 	withSchemaValidation,
 	FluidClientVersion,
 	currentVersion,
@@ -29,6 +27,7 @@ export {
 	jsonableCodecTree,
 	extractJsonValidator,
 	type CodecName,
+	eraseEncodedType,
 } from "./codec.js";
 export {
 	DiscriminatedUnionDispatcher,