@fluidframework/tree 2.23.0-323641 → 2.23.0

package/src/simple-tree/api/treeNodeApi.ts

@@ -40,6 +40,7 @@ import {
 } from "../core/index.js";
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
 import { isLazy, type LazyItem } from "../flexList.js";
+import { markSchemaMostDerived } from "./schemaFactory.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
@@ -174,7 +175,7 @@ export const treeNodeApi: TreeNodeApi = {
 								changedFields,
 								(field) =>
 									nodeSchema.storedKeyToPropertyKey.get(field) ??
-									fail("Could not find stored key in schema."),
+									fail(0xb36 /* Could not find stored key in schema. */),
 							),
 						);
 						listener({ changedProperties });
@@ -203,6 +204,10 @@ export const treeNodeApi: TreeNodeApi = {
 		value: unknown,
 		schema: TSchema,
 	): value is TreeNodeFromImplicitAllowedTypes<TSchema> {
+		// This "is" utility would return false if the provided schema is a base type of the actual schema.
+		// This could be confusing, and that case can only be hit when violating the rule that there is a single most derived schema that gets used (See documentation on TreeNodeSchemaClass).
+		// Therefore this uses markSchemaMostDerived to ensure an informative usage error is thrown in the case where a base type is used.
+
 		const actualSchema = tryGetSchema(value);
 		if (actualSchema === undefined) {
 			return false;
@@ -210,19 +215,19 @@ export const treeNodeApi: TreeNodeApi = {
 		if (isReadonlyArray<LazyItem<TreeNodeSchema>>(schema)) {
 			for (const singleSchema of schema) {
 				const testSchema = isLazy(singleSchema) ? singleSchema() : singleSchema;
+				markSchemaMostDerived(testSchema);
 				if (testSchema === actualSchema) {
 					return true;
 				}
 			}
 			return false;
 		} else {
-			// Linter is incorrect about this bering unnecessary: it does not compile without the type assertion.
-			// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
-			return (schema as TreeNodeSchema) === actualSchema;
+			markSchemaMostDerived(schema);
+			return schema === actualSchema;
 		}
 	},
 	schema(node: TreeNode | TreeLeafValue): TreeNodeSchema {
-		return tryGetSchema(node) ?? fail("Not a tree node");
+		return tryGetSchema(node) ?? fail(0xb37 /* Not a tree node */);
 	},
 	shortId(node: TreeNode): number | string | undefined {
 		const schema = node[typeSchemaSymbol];
@@ -341,7 +346,7 @@ function getPropertyKeyFromStoredKey(
 	}
 
 	if (fields[storedKey] === undefined) {
-		fail("Existing stored key should always map to a property key");
+		fail(0xb38 /* Existing stored key should always map to a property key */);
 	}
 
 	return storedKey;

package/src/simple-tree/api/verboseTree.ts

@@ -172,7 +172,8 @@ export function applySchemaToParserOptions<TCustom>(
 			: {
 					encode: (type, key: FieldKey): string => {
 						// translate stored key into property key.
-						const simpleNodeSchema = context.schema.get(brand(type)) ?? fail("missing schema");
+						const simpleNodeSchema =
+							context.schema.get(brand(type)) ?? fail(0xb39 /* missing schema */);
 						if (isObjectNodeSchema(simpleNodeSchema)) {
 							const propertyKey = simpleNodeSchema.storedKeyToPropertyKey.get(key);
 							if (propertyKey !== undefined) {
@@ -193,10 +194,12 @@ export function applySchemaToParserOptions<TCustom>(
 						return key;
 					},
 					parse: (type, inputKey): FieldKey => {
-						const simpleNodeSchema = context.schema.get(brand(type)) ?? fail("missing schema");
+						const simpleNodeSchema =
+							context.schema.get(brand(type)) ?? fail(0xb3a /* missing schema */);
 						if (isObjectNodeSchema(simpleNodeSchema)) {
 							const info =
-								simpleNodeSchema.flexKeyMap.get(inputKey) ?? fail("missing field info");
+								simpleNodeSchema.flexKeyMap.get(inputKey) ??
+								fail(0xb3b /* missing field info */);
 							return info.storedKey;
 						}
 						return brand(inputKey);
@@ -345,7 +348,8 @@ function verboseFromCursorInner<TCustom>(
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 ): VerboseTree<TCustom> {
 	const fields = customFromCursor(reader, options, schema, verboseFromCursorInner);
-	const nodeSchema = schema.get(reader.type) ?? fail("missing schema for type in cursor");
+	const nodeSchema =
+		schema.get(reader.type) ?? fail(0xb3c /* missing schema for type in cursor */);
 	if (nodeSchema.kind === NodeKind.Leaf) {
 		return fields as CustomTreeValue<TCustom>;
 	}

package/src/simple-tree/api/view.ts

@@ -250,7 +250,7 @@ export class ViewSchema {
 					this.viewSchemaAsStored.nodeSchema.get(adapter.output),
 				)
 			) {
-				fail("tree adapter for stored adapter.output should not be never");
+				fail(0xb3d /* tree adapter for stored adapter.output should not be never */);
 			}
 		}
 

package/src/simple-tree/arrayNode.ts

@@ -858,7 +858,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	// Therefore it must include `length`,
 	// even though this "length" is never invoked (due to being shadowed by the proxy provided own property).
 	public get length(): number {
-		return fail("Proxy should intercept length");
+		return fail(0xadb /* Proxy should intercept length */);
 	}
 
 	public [Symbol.iterator](): IterableIterator<TreeNodeFromImplicitAllowedTypes<T>> {
@@ -1045,7 +1045,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 			throw new UsageError(`Concurrent editing and iteration is not allowed.`);
 		}
 		for (let i = 0; i < this.length; i++) {
-			yield this.at(i) ?? fail("Index is out of bounds");
+			yield this.at(i) ?? fail(0xadc /* Index is out of bounds */);
 			if (initialLastUpdatedStamp !== kernel.generationNumber) {
 				throw new UsageError(`Concurrent editing and iteration is not allowed.`);
 			}

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

@@ -31,7 +31,8 @@ export function getOrCreateNodeFromInnerNode(flexNode: InnerNode): TreeNode | Tr
 		return cached;
 	}
 
-	const classSchema = getSimpleNodeSchemaFromInnerNode(flexNode) ?? fail("Missing schema");
+	const classSchema =
+		getSimpleNodeSchemaFromInnerNode(flexNode) ?? fail(0xb3e /* Missing schema */);
 	const node = flexNode as unknown as InternalTreeNode;
 	// eslint-disable-next-line unicorn/prefer-ternary
 	if (typeof classSchema === "function") {

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

@@ -17,7 +17,7 @@ import { SimpleContextSlot, type Context } from "./context.js";
  */
 export function getSimpleNodeSchemaFromInnerNode(innerNode: InnerNode): TreeNodeSchema {
 	const context: Context = getSimpleContextFromInnerNode(innerNode);
-	return context.schema.get(innerNode.schema) ?? fail("missing schema from context");
+	return context.schema.get(innerNode.schema) ?? fail(0xb3f /* missing schema from context */);
 }
 
 /**

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