@fluidframework/tree 2.22.1 → 2.23.0-325054

package/src/util/idAllocator.ts

@@ -44,6 +44,6 @@ export function idAllocatorFromState(state: IdAllocationState): IdAllocator {
 }
 
 export const fakeIdAllocator: IdAllocator = {
-	allocate: () => fail("Should not allocate IDs"),
+	allocate: () => fail(0xae6 /* Should not allocate IDs */),
 	getMaxId: () => 0,
 };

package/src/util/index.ts

@@ -19,8 +19,6 @@ export {
 } from "./opaque.js";
 export {
 	deleteFromNestedMap,
-	getOrAddInMap,
-	getOrAddInMapLazy,
 	getOrAddInNestedMap,
 	getOrDefaultInNestedMap,
 	forEachInNestedMap,
@@ -34,6 +32,7 @@ export {
 	mapNestedMap,
 	nestedMapToFlatList,
 	nestedMapFromFlatList,
+	getOrCreateInNestedMap,
 } from "./nestedMap.js";
 export { addToNestedSet, type NestedSet, nestedSetContains } from "./nestedSet.js";
 export { type OffsetList, OffsetListFactory } from "./offsetList.js";
@@ -56,6 +55,7 @@ export type {
 export { StackyIterator } from "./stackyIterator.js";
 export {
 	asMutable,
+	balancedReduce,
 	clone,
 	compareSets,
 	fail,
@@ -95,6 +95,7 @@ export {
 	hasSingle,
 	defineLazyCachedProperty,
 	copyPropertyIfDefined as copyProperty,
+	getOrAddInMap,
 } from "./utils.js";
 export { ReferenceCountedBase, type ReferenceCounted } from "./referenceCounting.js";
 

package/src/util/nestedMap.ts

@@ -5,7 +5,7 @@
 
 import { oob } from "@fluidframework/core-utils/internal";
 
-import type { MapGetSet } from "./utils.js";
+import { getOrAddInMap, getOrCreate } from "./utils.js";
 
 /**
  * A dictionary whose values are keyed off of two objects (key1, key2).
@@ -87,40 +87,16 @@ export function setInNestedMap<Key1, Key2, Value>(
 }
 
 /**
- * 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.
+ * {@link getOrCreate} for {@link NestedMap}.
  */
-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;
-}
-
-/**
- * Sets the value at `key` in `map` to `generateValue()` if not already present.
- * Returns the value at `key` after setting it.
- */
-export function getOrAddInMapLazy<Key, Value>(
-	map: MapGetSet<Key, Value>,
-	key: Key,
-	generateValue: () => Value,
+export function getOrCreateInNestedMap<Key1, Key2, Value>(
+	map: NestedMap<Key1, Key2, Value>,
+	key1: Key1,
+	key2: Key2,
+	defaultValue: (key1: Key1, key2: Key2) => Value,
 ): Value {
-	const currentValue = map.get(key);
-	if (currentValue !== undefined) {
-		return currentValue;
-	}
-
-	const value = generateValue();
-	map.set(key, value);
-	return value;
+	const innerMap = getOrAddInMap(map, key1, new Map<Key2, Value>());
+	return getOrCreate(innerMap, key2, (): Value => defaultValue(key1, key2));
 }
 
 /**

package/src/util/utils.ts

@@ -47,18 +47,8 @@ export function asMutable<T>(readonly: T): Mutable<T> {
 
 export const clone = structuredClone;
 
-/**
- * Throw an error with a constant message.
- * @remarks
- * Works like {@link @fluidframework/core-utils/internal#assert}.
- */
-export function fail(message: string | number): never {
-	// Declaring this here aliased to a different name avoids the assert tagging objecting to the usages of `assert` below.
-	// Since users of `fail` do the assert message tagging instead, suppressing tagging errors here makes sense.
-	const assertNoTag: (condition: boolean, message: string | number) => asserts condition =
-		assert;
-	assertNoTag(false, message);
-}
+// TODO: update usages of this to use @fluidframework/core-utils/internal directly.
+export { fail } from "@fluidframework/core-utils/internal";
 
 /**
  * Checks whether or not the given object is a `readonly` array.
@@ -177,6 +167,24 @@ 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
@@ -616,3 +624,35 @@ export function copyPropertyIfDefined<
 		}
 	}
 }
+
+/**
+ * Reduces an array of values into a single value.
+ * This is similar to `Array.prototype.reduce`,
+ * except that it recursively reduces the left and right halves of the input before reducing their respective reductions.
+ *
+ * When compared with an approach like reducing all the values left-to-right,
+ * this balanced approach is beneficial when the cost of invoking `callbackFn` is proportional to the number reduced values that its parameters collectively represent.
+ * For example, if `T` is an array, and `callbackFn` concatenates its inputs,
+ * then `balancedReduce` will have O(N*log(N)) time complexity instead of `Array.prototype.reduce`'s O(N²).
+ * However, if `callbackFn` is O(1) then both `balancedReduce` and `Array.prototype.reduce` will have O(N) complexity.
+ *
+ * @param array - The array to reduce.
+ * @param callbackFn - The function to execute for each pairwise reduction.
+ * @param emptyCase - A factory function that provides the value to return if the input array is empty.
+ */
+export function balancedReduce<T>(
+	array: readonly T[],
+	callbackFn: (left: T, right: T) => T,
+	emptyCase: () => T,
+): T {
+	if (hasSingle(array)) {
+		return array[0];
+	}
+	if (!hasSome(array)) {
+		return emptyCase();
+	}
+	const mid = Math.floor(array.length / 2);
+	const left = balancedReduce(array.slice(0, mid), callbackFn, emptyCase);
+	const right = balancedReduce(array.slice(mid), callbackFn, emptyCase);
+	return callbackFn(left, right);
+}