@fluidframework/tree 2.23.0-323641 → 2.23.0-325054

package/src/simple-tree/treeNodeValid.ts

@@ -58,15 +58,17 @@ 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 */);
 	}
 
 	/**
 	 * Schema classes can override to provide a callback that is called once when the first node is constructed.
 	 * This is a good place to perform extra validation and cache schema derived data needed for the implementation of the node.
+	 * @remarks
+	 * It is valid to dereference LazyItem schema references in this function (or anything that runs after it).
 	 */
 	protected static oneTimeSetup<T>(this: typeof TreeNodeValid<T>): Context {
-		fail("Missing oneTimeSetup");
+		fail(0xae5 /* Missing oneTimeSetup */);
 	}
 
 	/**
@@ -119,6 +121,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
@@ -143,7 +148,7 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 	}
 
 	/**
-	 * @see {@link TreeNodeSchemaCore.createFromInsertable}.
+	 * See {@link TreeNodeSchemaCore.createFromInsertable}.
 	 */
 	public static createFromInsertable<TInput, TOut, TThis extends new (args: TInput) => TOut>(
 		this: TThis,
@@ -152,13 +157,22 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 		return new this(input);
 	}
 
+	/**
+	 * Idempotent initialization function that pre-caches data and can dereference lazy schema references.
+	 */
+	public static oneTimeInitialize(
+		this: typeof TreeNodeValid & TreeNodeSchema,
+	): Required<MostDerivedData> {
+		const cache = this.markMostDerived();
+		cache.oneTimeInitialized ??= this.oneTimeSetup();
+		// Typescript fails to narrow the type of `oneTimeInitialized` to `Context` here, so use a cast:
+		return cache as MostDerivedData & { oneTimeInitialized: Context };
+	}
+
 	public constructor(input: TInput | InternalTreeNode) {
 		super(privateToken);
 		const schema = this.constructor as typeof TreeNodeValid & TreeNodeSchema;
-		const cache = schema.markMostDerived();
-		if (cache.oneTimeInitialized === undefined) {
-			cache.oneTimeInitialized = schema.oneTimeSetup();
-		}
+		const cache = schema.oneTimeInitialize();
 
 		if (isTreeNode(input)) {
 			// TODO: update this once we have better support for deep-copying and move operations.

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";
@@ -96,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