@fluidframework/tree 2.22.1 → 2.23.0

package/src/simple-tree/core/treeNodeKernel.ts

@@ -184,7 +184,7 @@ export class TreeNodeKernel {
 			// This can't be cached on this.#hydrated during hydration since initial tree is hydrated before the context is cached on the anchorSet.
 			return (
 				this.#hydrationState?.anchorNode.anchorSet.slots.get(SimpleContextSlot) ??
-				fail("missing simple-tree context")
+				fail(0xb40 /* missing simple-tree context */)
 			);
 		}
 		return this.initialContext;
@@ -303,7 +303,8 @@ export class TreeNodeKernel {
 			this.#hydrationState.innerNode = flexNode;
 		} else {
 			// ...otherwise, the flex node must be created
-			const context = anchorNode.anchorSet.slots.get(ContextSlot) ?? fail("missing context");
+			const context =
+				anchorNode.anchorSet.slots.get(ContextSlot) ?? fail(0xb41 /* missing context */);
 			const cursor = context.checkout.forest.allocateCursor("getFlexNode");
 			context.checkout.forest.moveCursorToPath(anchorNode, cursor);
 			this.#hydrationState.innerNode = makeTree(context, cursor);
@@ -332,7 +333,8 @@ export class TreeNodeKernel {
 	public anchorProxy(anchors: AnchorSet, path: UpPath): AnchorNode {
 		assert(!anchorForgetters.has(this.node), 0x91c /* Proxy anchor should not be set twice */);
 		const anchor = anchors.track(path);
-		const anchorNode = anchors.locate(anchor) ?? fail("Expected anchor node to be present");
+		const anchorNode =
+			anchors.locate(anchor) ?? fail(0xb42 /* Expected anchor node to be present */);
 		this.hydrate(anchorNode);
 		const forget = (): void => {
 			if (anchors.locate(anchor)) {
@@ -434,9 +436,9 @@ export function getTreeNodeSchemaFromHydratedFlexNode(flexNode: FlexTreeNode): T
 
 	const context =
 		flexNode.anchorNode.anchorSet.slots.get(SimpleContextSlot) ??
-		fail("Missing SimpleContextSlot");
+		fail(0xb43 /* Missing SimpleContextSlot */);
 
-	return context.schema.get(flexNode.schema) ?? fail("Missing schema");
+	return context.schema.get(flexNode.schema) ?? fail(0xb44 /* Missing schema */);
 }
 
 /**
@@ -461,7 +463,8 @@ function flexNodeFromAnchor(anchorNode: AnchorNode): FlexTreeNode {
 	if (flexNode !== undefined) {
 		return flexNode; // If it does have a flex node, return it...
 	} // ...otherwise, the flex node must be created
-	const context = anchorNode.anchorSet.slots.get(ContextSlot) ?? fail("missing context");
+	const context =
+		anchorNode.anchorSet.slots.get(ContextSlot) ?? fail(0xb45 /* missing context */);
 	const cursor = context.checkout.forest.allocateCursor("getFlexNode");
 	context.checkout.forest.moveCursorToPath(anchorNode, cursor);
 	const newFlexNode = makeTree(context, cursor);

package/src/simple-tree/core/unhydratedFlexTree.ts

@@ -79,7 +79,9 @@ export class UnhydratedFlexTreeNode implements UnhydratedFlexTreeNode {
 	}
 
 	public get storedSchema(): TreeNodeStoredSchema {
-		return this.context.schema.nodeSchema.get(this.mapTree.type) ?? fail("missing schema");
+		return (
+			this.context.schema.nodeSchema.get(this.mapTree.type) ?? fail(0xb46 /* missing schema */)
+		);
 	}
 
 	public readonly [flexTreeMarker] = FlexTreeEntityKind.Node as const;
@@ -215,7 +217,7 @@ export class UnhydratedFlexTreeNode implements UnhydratedFlexTreeNode {
 	public get anchorNode(): AnchorNode {
 		// This API is relevant to `LazyTreeNode`s, but not `UnhydratedFlexTreeNode`s.
 		// TODO: Refactor the FlexTreeNode interface so that stubbing this out isn't necessary.
-		return fail("UnhydratedFlexTreeNode does not implement anchorNode");
+		return fail(0xb47 /* UnhydratedFlexTreeNode does not implement anchorNode */);
 	}
 
 	private walkTree(): void {
@@ -294,10 +296,10 @@ const unparentedLocation: LocationInField = {
 		},
 		schema: brand(forbiddenFieldKindIdentifier),
 		get context(): never {
-			return fail("unsupported");
+			return fail(0xb48 /* unsupported */);
 		},
 		getFieldPath() {
-			fail("unsupported");
+			fail(0xb49 /* unsupported */);
 		},
 	},
 	index: -1,
@@ -489,7 +491,7 @@ export class UnhydratedTreeSequenceField
 			this.edit((mapTrees) => {
 				removed = mapTrees.splice(index, count);
 			});
-			return removed ?? fail("Expected removed to be set by edit");
+			return removed ?? fail(0xb4a /* Expected removed to be set by edit */);
 		},
 	};
 

package/src/simple-tree/objectNode.ts

@@ -262,7 +262,7 @@ function createProxyHandler(
 			// For some reason, the getOwnPropertyDescriptor is not passed in the receiver, so use a weak map.
 			// If a refactoring is done to associated flex tree data with the target not the proxy, this extra map could be removed,
 			// and the design would be more compatible with proxyless nodes.
-			const proxy = targetToProxy.get(target) ?? fail("missing proxy");
+			const proxy = targetToProxy.get(target) ?? fail(0xadd /* missing proxy */);
 			const field = getOrCreateInnerNode(proxy).tryGetField(fieldInfo.storedKey);
 
 			const p: PropertyDescriptor = {
@@ -311,7 +311,7 @@ export function setField(
 		}
 
 		default:
-			fail("invalid FieldKind");
+			fail(0xade /* invalid FieldKind */);
 	}
 }
 

package/src/simple-tree/proxies.ts

@@ -56,7 +56,7 @@ export function getTreeNodeForField(field: FlexTreeField): TreeNode | TreeValue
 		}
 
 		default:
-			fail("invalid field kind");
+			fail(0xadf /* invalid field kind */);
 	}
 }
 

package/src/simple-tree/toMapTree.ts

@@ -196,7 +196,7 @@ function nodeDataToMapTree(
 			result = objectToMapTree(data, schema);
 			break;
 		default:
-			fail("Unrecognized schema kind");
+			fail(0xae0 /* Unrecognized schema kind */);
 	}
 
 	return result;
@@ -642,7 +642,7 @@ export function addDefaultsToMapTree(
 ): void {
 	const schema =
 		find(normalizeAllowedTypes(allowedTypes), (s) => s.identifier === mapTree.type) ??
-		fail("MapTree is incompatible with schema");
+		fail(0xae1 /* MapTree is incompatible with schema */);
 
 	if (isObjectNodeSchema(schema)) {
 		for (const [_key, fieldInfo] of schema.flexKeyMap) {
@@ -660,7 +660,7 @@ export function addDefaultsToMapTree(
 						setFieldValue(mapTree.fields, data, fieldInfo.schema, fieldInfo.storedKey);
 						// call addDefaultsToMapTree on newly inserted default values
 						for (const child of mapTree.fields.get(fieldInfo.storedKey) ??
-							fail("Expected field to be populated")) {
+							fail(0xae2 /* Expected field to be populated */)) {
 							addDefaultsToMapTree(child, fieldInfo.schema.allowedTypes, context);
 						}
 					}

package/src/simple-tree/toStoredSchema.ts

@@ -71,7 +71,8 @@ export function convertField(schema: ImplicitFieldSchema): TreeFieldStoredSchema
 	let kind: FieldKindIdentifier;
 	let allowedTypes: ImplicitAllowedTypes;
 	if (schema instanceof FieldSchema) {
-		kind = convertFieldKind.get(schema.kind)?.identifier ?? fail("Invalid field kind");
+		kind =
+			convertFieldKind.get(schema.kind)?.identifier ?? fail(0xae3 /* Invalid field kind */);
 		allowedTypes = schema.allowedTypes;
 	} else {
 		kind = FieldKinds.required.identifier;

package/src/simple-tree/treeNodeValid.ts

@@ -58,7 +58,7 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 		instance: TreeNodeValid<T>,
 		input: T,
 	): UnhydratedFlexTreeNode {
-		return fail("Schema must override buildRawNode");
+		return fail(0xae4 /* Schema must override buildRawNode */);
 	}
 
 	/**
@@ -66,7 +66,7 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 	 * This is a good place to perform extra validation and cache schema derived data needed for the implementation of the node.
 	 */
 	protected static oneTimeSetup<T>(this: typeof TreeNodeValid<T>): Context {
-		fail("Missing oneTimeSetup");
+		fail(0xae5 /* Missing oneTimeSetup */);
 	}
 
 	/**
@@ -119,6 +119,9 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 			return this.constructorCached;
 		}
 
+		// If users trying to diagnose the cause of this error becomes a common issue, more information could be captured.
+		// The call stack to when a schema is first marked most derived could be captured in debug builds and stored in the `MostDerivedData` object:
+		// This could then be included in the error to aid in debugging this error.
 		throw new UsageError(
 			`Two schema classes were used (${this.name} and ${
 				this.constructorCached.constructor.name

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);
+}