@fluidframework/tree 2.111.0 → 2.112.0

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -109,6 +109,14 @@ export interface TreeArrayNode<
 > extends ReadonlyArrayNode<T> {
 	/**
 	 * Inserts new item(s) at a specified location.
+	 *
+	 * @remarks
+	 * All items inserted by a single call to this method are inserted consecutively.
+	 * The order of the inserted items relative to other concurrently inserted items at the same location is only partially specified:
+	 * Concurrently inserting `[A, B]` and `[X, Y]` at the same location may yield
+	 * either `[A, B, X, Y]` or `[X, Y, A, B]`, regardless of the order in which those edits are sequenced.
+	 * No other interleavings are possible. (e.g. `[A, X, B, Y]` is not possible.)
+	 *
 	 * @param index - The index at which to insert `value`.
 	 * @param value - The content to insert.
 	 * @throws Throws if `index` is not in the range [0, `array.length`).
@@ -117,12 +125,18 @@ export interface TreeArrayNode<
 
 	/**
 	 * Inserts new item(s) at the start of the array.
+	 * @remarks
+	 * Equivalent to `insertAt(0, ...value)`:
+	 * see {@link (TreeArrayNode:interface).insertAt} for details, including merge semantics with concurrent edits.
 	 * @param value - The content to insert.
 	 */
 	insertAtStart(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void;
 
 	/**
 	 * Inserts new item(s) at the end of the array.
+	 * @remarks
+	 * Equivalent to `insertAt(array.length, ...value)`:
+	 * see {@link (TreeArrayNode:interface).insertAt} for details, including merge semantics with concurrent edits.
 	 * @param value - The content to insert.
 	 */
 	insertAtEnd(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void;
@@ -131,10 +145,10 @@ export interface TreeArrayNode<
 	 * Inserts new item(s) at the end of the array.
 	 *
 	 * @remarks
-	 * The order of the inserted items relative to other concurrently inserted items at the same location is only partially specified:
-	 * Concurrently inserting `[A, B]` and `[X, Y]` at the same location may yield
-	 * either `[A, B, X, Y]` or `[X, Y, A, B]`, regardless of the order in which those edits are sequenced.
-	 * No other interleavings are possible. (e.g. `[A, X, B, Y]` is not possible.)
+	 * Unlike `Array.prototype.push`, this method does not return the new length of the array.
+	 *
+	 * Equivalent to `insertAt(array.length, ...value)`:
+	 * see {@link (TreeArrayNode:interface).insertAt} for details, including merge semantics with concurrent edits.
 	 *
 	 * @param value - The content to insert.
 	 */
@@ -460,6 +474,87 @@ export interface TreeArrayNodeAlpha<
 		? InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes>
 		: InsertableTreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>,
 > extends TreeArrayNode<TAllowedTypes, T, TNew> {
+	/**
+	 * Returns the item located at the specified index.
+	 * @param index - The zero-based index of the item to retrieve.
+	 * Negative indices count back from the last item in the array: for `index < 0`, `index + array.length` is used.
+	 * @returns The item at the specified index, or `undefined` if the index is out of bounds.
+	 */
+	at(index: number): T | undefined;
+
+	/**
+	 * Returns the last item in the array for which the given type guard returns `true`,
+	 * searching from the last item to the first.
+	 * @remarks
+	 * The array's length is captured when the search begins; items are read live as the search progresses.
+	 * If `predicate` edits the array, behavior matches {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findLast | Array.prototype.findLast}.
+	 * @typeParam S - The subtype of `T` asserted by the `predicate` type guard.
+	 * @param predicate - Evaluated once per item, starting from the last item and moving towards the first, until it returns `true`.
+	 * Receives the item, its index, and the array being searched.
+	 * @param thisArg - If provided, used as `this` when invoking `predicate`.
+	 * @returns The last item for which `predicate` returns `true` (narrowed to the guarded type), or `undefined` if there is no such item.
+	 */
+	findLast<S extends T>(
+		predicate: (value: T, index: number, array: readonly T[]) => value is S,
+		thisArg?: unknown,
+	): S | undefined;
+
+	/**
+	 * Returns the last item in the array for which the given predicate returns a truthy value,
+	 * searching from the last item to the first.
+	 * @remarks
+	 * The array's length is captured when the search begins; items are read live as the search progresses.
+	 * If `predicate` edits the array, behavior matches {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findLast | Array.prototype.findLast}.
+	 * @param predicate - Evaluated once per item, starting from the last item and moving towards the first, until it returns a truthy value.
+	 * Receives the item, its index, and the array being searched.
+	 * @param thisArg - If provided, used as `this` when invoking `predicate`.
+	 * @returns The last item for which `predicate` returns a truthy value, or `undefined` if there is no such item.
+	 */
+	findLast(
+		predicate: (value: T, index: number, array: readonly T[]) => unknown,
+		thisArg?: unknown,
+	): T | undefined;
+
+	/**
+	 * Returns the index of the last item in the array for which the given predicate returns a truthy value,
+	 * searching from the last item to the first.
+	 * @remarks
+	 * The array's length is captured when the search begins; items are read live as the search progresses.
+	 * If `predicate` edits the array, behavior matches {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findLastIndex | Array.prototype.findLastIndex}.
+	 * @param predicate - Evaluated once per item, starting from the last item and moving towards the first, until it returns a truthy value.
+	 * Receives the item, its index, and the array being searched.
+	 * @param thisArg - If provided, used as `this` when invoking `predicate`.
+	 * @returns The index of the last item for which `predicate` returns a truthy value, or `-1` if there is no such item.
+	 */
+	findLastIndex(
+		predicate: (value: T, index: number, array: readonly T[]) => unknown,
+		thisArg?: unknown,
+	): number;
+
+	/**
+	 * Removes the last item from the array and returns it.
+	 * @returns The removed item, or `undefined` if the array is empty (in which case the array is not modified).
+	 */
+	pop(): T | undefined;
+
+	/**
+	 * Removes the first item from the array and returns it.
+	 * @returns The removed item, or `undefined` if the array is empty (in which case the array is not modified).
+	 */
+	shift(): T | undefined;
+
+	/**
+	 * Inserts new item(s) at the start of the array.
+	 *
+	 * @param value - The content to insert.
+	 * @remarks
+	 * Unlike `Array.prototype.unshift`, this method does not return the new length of the array.
+	 *
+	 * Equivalent to `insertAt(0, ...value)`:
+	 * see {@link (TreeArrayNode:interface).insertAt} for details, including merge semantics with concurrent edits.
+	 */
+	unshift(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void;
+
 	/**
 	 * Removes existing item(s) and/or adds new item(s).
 	 * @param start - The index at which to start changing the array. If negative, it is treated as `array.length + start`.
@@ -995,6 +1090,58 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 
 		return getOrCreateNodeFromInnerNode(val) as TreeNodeFromImplicitAllowedTypes<T>;
 	}
+	public findLast<S extends TreeNodeFromImplicitAllowedTypes<T>>(
+		predicate: (
+			value: TreeNodeFromImplicitAllowedTypes<T>,
+			index: number,
+			array: readonly TreeNodeFromImplicitAllowedTypes<T>[],
+		) => value is S,
+		thisArg?: unknown,
+	): S | undefined;
+	public findLast(
+		predicate: (
+			value: TreeNodeFromImplicitAllowedTypes<T>,
+			index: number,
+			array: readonly TreeNodeFromImplicitAllowedTypes<T>[],
+		) => unknown,
+		thisArg?: unknown,
+	): TreeNodeFromImplicitAllowedTypes<T> | undefined;
+	public findLast(
+		predicate: (
+			value: TreeNodeFromImplicitAllowedTypes<T>,
+			index: number,
+			array: readonly TreeNodeFromImplicitAllowedTypes<T>[],
+		) => unknown,
+		thisArg?: unknown,
+	): TreeNodeFromImplicitAllowedTypes<T> | undefined {
+		const array = this as readonly TreeNodeFromImplicitAllowedTypes<T>[];
+		for (let index = this.length - 1; index >= 0; index--) {
+			const value = this.at(index) as TreeNodeFromImplicitAllowedTypes<T>;
+			const matched = Boolean(predicate.call(thisArg, value, index, array));
+			if (matched) {
+				return value;
+			}
+		}
+		return undefined;
+	}
+	public findLastIndex(
+		predicate: (
+			value: TreeNodeFromImplicitAllowedTypes<T>,
+			index: number,
+			array: readonly TreeNodeFromImplicitAllowedTypes<T>[],
+		) => unknown,
+		thisArg?: unknown,
+	): number {
+		const array = this as readonly TreeNodeFromImplicitAllowedTypes<T>[];
+		for (let index = this.length - 1; index >= 0; index--) {
+			const value = this.at(index) as TreeNodeFromImplicitAllowedTypes<T>;
+			const matched = Boolean(predicate.call(thisArg, value, index, array));
+			if (matched) {
+				return index;
+			}
+		}
+		return -1;
+	}
 	public insertAt(index: number, ...value: Insertable<T>): void {
 		const field = getSequenceField(this);
 		validateIndex(index, field, "TreeArrayNode.insertAt", true);
@@ -1010,6 +1157,23 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	public push(...value: Insertable<T>): void {
 		this.insertAt(this.length, ...value);
 	}
+	public unshift(...value: Insertable<T>): void {
+		this.insertAt(0, ...value);
+	}
+	public pop(): TreeNodeFromImplicitAllowedTypes<T> | undefined {
+		const value = this.at(-1);
+		if (value !== undefined) {
+			this.removeAt(this.length - 1);
+		}
+		return value;
+	}
+	public shift(): TreeNodeFromImplicitAllowedTypes<T> | undefined {
+		const value = this.at(0);
+		if (value !== undefined) {
+			this.removeAt(0);
+		}
+		return value;
+	}
 	public removeAt(index: number): void {
 		const field = getSequenceField(this);
 		validateIndex(index, field, "TreeArrayNode.removeAt");

package/src/simple-tree/simpleSchemaFormatV1.ts

@@ -7,7 +7,7 @@
  * This file contains a format for serializing the compatibility impacting subset of simple schema.
 
  * This format can be used for both view and stored simple schema.
- * This only includes all parts of the schema that impact compatibility according to SchemaCompatibilityTester.
+ * This only includes all parts of the schema that impact compatibility according to {@link checkSchemaCompatibility}.
  * It may not include some details which impact maintenance of application enforced invariants (like persisted metadata or logic in view schema).
  */
 

package/src/treeFactory.ts

@@ -77,7 +77,7 @@ function treeKernelFactory(
 		};
 
 		return new SharedTreeKernel(
-			new Breakable("SharedTree"),
+			new Breakable("SharedTree", args.logger),
 			args.sharedObject,
 			args.serializer,
 			args.submitLocalMessage,

package/src/util/breakable.ts

@@ -4,7 +4,7 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { UsageError, type TelemetryLoggerExt } from "@fluidframework/telemetry-utils/internal";
 
 /**
  * An object which can enter a "broken" state where trying to use it is a UsageError.
@@ -22,6 +22,13 @@ export class Breakable {
 		 * This is useful for documenting the semantics of a given Breakable and when inspecting things in the debugger, but is currently otherwise unused.
 		 */
 		private readonly name: string,
+		/**
+		 * Optional logger for telemetry.
+		 * @remarks
+		 * When provided, subsystems that have access to a Breakable can use this logger to emit telemetry
+		 * without requiring additional plumbing.
+		 */
+		public readonly logger?: TelemetryLoggerExt,
 	) {}
 
 	/**

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