@fluidframework/tree 2.111.0 → 2.113.0-411909

package/src/util/compressedIds.ts

@@ -152,9 +152,10 @@ export function tryDecodeEncodedIdWithoutSession(
  * the user-facing {@link SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode}
  * option — see that option for the user-facing rationale and trade-offs.
  *
- * Carried by decode-side contexts (`ChangeEncodingContext.healing`,
+ * Carried by decode-side contexts ({@link IdDecoderOptionsOriginatorless},
+ * `ChangeEncodingContext.healing`,
  * `EditManagerEncodingContext.healing`, etc.) when the workaround is enabled.
- * Presence enables healing; `undefined` opts out. There is no separate boolean,
+ * Presence enables healing; `undefined` means healing is disabled. There is no separate boolean,
  * which makes it impossible to enable healing without supplying the namespace
  * input.
  */
@@ -214,3 +215,90 @@ export function decompressIdentifierIfNeeded(
 		return decompressed;
 	}
 }
+
+/**
+ * Options for creating an {@link IdDecodingContext} without an originator.
+ * @remarks
+ * Decodes {@link OriginatorlessEncodedId} instances, and optionally has a {@link IdentifierHealingConfig} fallback for {@link OriginatorDependentEncodedId} instances.
+ */
+export interface IdDecoderOptionsOriginatorless {
+	readonly idCompressor: IIdCompressor;
+	/**
+	 * Optional {@link IdentifierHealingConfig} to use for healing unresolvable identifiers.
+	 * @privateRemarks
+	 * This is a required field which can be undefined to make it explicit when this is not provided.
+	 * This explicitness helps ensure we we don't accidentally drop the healing config as that would break
+	 * an edge case which does not get a lot of testing.
+	 */
+	readonly healing: IdentifierHealingConfig | undefined;
+}
+
+/**
+ * Options for creating an {@link IdDecodingContext} with an originator.
+ * @remarks
+ * Decodes {@link OriginatorDependentEncodedId} instances.
+ */
+export interface IdDecoderOptionsWithOriginator {
+	readonly idCompressor: IIdCompressor;
+	/**
+	 * The ID of the session that encoded the ids.
+	 */
+	readonly originatorId: SessionId;
+}
+
+/**
+ * Context for decoding identifiers.
+ * @remarks
+ * Depended on how this is constructed, it may or may not handle {@link OriginatorDependentEncodedId} instances.
+ *
+ * This intentionally avoids exposing anything which depends on the underlying id-compressor's session ID to avoid confusion with the session ID of the compressor which encoded the data.
+ * If the session ID of the encoder which encoded the data is known, that information is baked into `resolveEncodedId`.
+ *
+ * @privateRemarks
+ * We have code (FieldBatchDecodingContext) which sometimes has a session ID and sometimes doesn't, so we need a flexible decoding context.
+ * Additionally, since this is about serialized data, having stronger types is often counterproductive, as it just relies more on type casts when parsing.
+ * This is why we use this flexible pattern rather than code strongly typed over which kind of encoded ids are expected.
+ */
+export class IdDecodingContext {
+	/**
+	 * Used internally to prevent the use of this decoder in incremental chunks if it has a session id (which would be wrong in those chunks).
+	 */
+	protected readonly hasOriginatorSessionId: boolean;
+
+	/**
+	 * Compressor which can decompress session-space identifiers from {@link resolveEncodedId} as needed.
+	 */
+	public readonly idCompressor: Pick<IIdCompressor, "decompress">;
+
+	/**
+	 * Resolves an encoded op-space identifier to either a session-space ID
+	 * (which {@link idCompressor} can decompress if needed)
+	 * or a string (which passes through unchanged).
+	 * @remarks
+	 * In contexts where non-final identifiers can't be supported (where no originator session is available),
+	 * if a non-final identifier is encountered, this may throw or perform a data healing workaround.
+	 * See {@link FieldBatchDecodingContext.forOp} and {@link FieldBatchDecodingContext.forSummary} for details.
+	 */
+	public readonly resolveEncodedId: (
+		id: OpSpaceCompressedId,
+	) => SessionSpaceCompressedId | string;
+
+	/**
+	 * Creates a new instance of the context.
+	 * @param options - The options for creating the context.
+	 */
+	public constructor(
+		options: IdDecoderOptionsOriginatorless | IdDecoderOptionsWithOriginator,
+	) {
+		this.idCompressor = options.idCompressor;
+		if ("originatorId" in options) {
+			this.hasOriginatorSessionId = true;
+			this.resolveEncodedId = (id): SessionSpaceCompressedId | string =>
+				options.idCompressor.normalizeToSessionSpace(id, options.originatorId);
+		} else {
+			this.hasOriginatorSessionId = false;
+			this.resolveEncodedId = (id): SessionSpaceCompressedId | string =>
+				forceDecodeEncodedIdWithoutSession(id, options.idCompressor, options.healing);
+		}
+	}
+}

package/src/util/index.ts

@@ -106,7 +106,6 @@ export {
 	hasSingle,
 	defineLazyCachedProperty,
 	copyPropertyIfDefined as copyProperty,
-	getOrAddInMap,
 	iterableHasSome,
 } from "./utils.js";
 export { ReferenceCountedBase, type ReferenceCounted } from "./referenceCounting.js";
@@ -179,4 +178,7 @@ export {
 	tryDecodeEncodedIdWithoutSession,
 	forceDecodeEncodedIdWithoutSession,
 	decompressIdentifierIfNeeded,
+	IdDecodingContext,
+	type IdDecoderOptionsOriginatorless,
+	type IdDecoderOptionsWithOriginator,
 } from "./compressedIds.js";

package/src/util/nestedMap.ts

@@ -5,7 +5,7 @@
 
 import { oob } from "@fluidframework/core-utils/internal";
 
-import { getOrAddInMap, getOrCreate } from "./utils.js";
+import { getOrCreate } from "./utils.js";
 
 /**
  * A dictionary whose values are keyed off of two objects (key1, key2).
@@ -72,6 +72,23 @@ export function populateNestedMap<Key1, Key2, Value>(
 	}
 }
 
+/**
+ * Sets the value at `key` in map to new Map if not already present.
+ * Returns the value at `key` after setting it.
+ */
+function getOrAddInMap<Key1, Key2, Value>(
+	map: NestedMap<Key1, Key2, Value>,
+	key1: Key1,
+): Map<Key2, Value> {
+	const currentValue = map.get(key1);
+	if (currentValue !== undefined) {
+		return currentValue;
+	}
+	const value = new Map<Key2, Value>();
+	map.set(key1, value);
+	return value;
+}
+
 /**
  * Sets the value at (key1, key2) in map to value.
  * If there already is a value for (key1, key2), it is replaced with the provided one.
@@ -82,7 +99,7 @@ export function setInNestedMap<Key1, Key2, Value>(
 	key2: Key2,
 	value: Value,
 ): void {
-	const innerMap = getOrAddInMap(map, key1, new Map<Key2, Value>());
+	const innerMap = getOrAddInMap(map, key1);
 	innerMap.set(key2, value);
 }
 
@@ -95,7 +112,7 @@ export function getOrCreateInNestedMap<Key1, Key2, Value>(
 	key2: Key2,
 	defaultValue: (key1: Key1, key2: Key2) => Value,
 ): Value {
-	const innerMap = getOrAddInMap(map, key1, new Map<Key2, Value>());
+	const innerMap = getOrAddInMap(map, key1);
 	return getOrCreate(innerMap, key2, (): Value => defaultValue(key1, key2));
 }
 
@@ -193,7 +210,7 @@ export function nestedMapFromFlatList<Key1, Key2, Value>(
 ): NestedMap<Key1, Key2, Value> {
 	const map = new Map<Key1, Map<Key2, Value>>();
 	for (const [key1, key2, val] of list) {
-		getOrAddInMap(map, key1, new Map<Key2, Value>()).set(key2, val);
+		getOrAddInMap(map, key1).set(key2, val);
 	}
 	return map;
 }

package/src/util/nestedSet.ts

@@ -5,7 +5,7 @@
 
 import { type NestedMap, getOrDefaultInNestedMap, setInNestedMap } from "./nestedMap.js";
 
-export type NestedSet<Key1, Key2> = NestedMap<Key1, Key2, boolean>;
+export type NestedSet<Key1, Key2> = NestedMap<Key1, Key2, true>;
 
 export function addToNestedSet<Key1, Key2>(
 	set: NestedSet<Key1, Key2>,

package/src/util/utils.ts

@@ -192,24 +192,6 @@ export function compareSets<T>({
 	return true;
 }
 
-/**
- * Sets the value at `key` in map to value if not already present.
- * Returns the value at `key` after setting it.
- * This is equivalent to a get or default that adds the default to the map.
- */
-export function getOrAddInMap<Key, Value>(
-	map: MapGetSet<Key, Value>,
-	key: Key,
-	value: Value,
-): Value {
-	const currentValue = map.get(key);
-	if (currentValue !== undefined) {
-		return currentValue;
-	}
-	map.set(key, value);
-	return value;
-}
-
 /**
  * Retrieve a value from a map with the given key, or create a new entry if the key is not in the map.
  * @param map - The map to query/update