@fluidframework/tree 2.1.0-281041 → 2.2.0

package/src/simple-tree/{treeNodeApi.ts → api/treeNodeApi.ts}

@@ -3,40 +3,47 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 
-import { Multiplicity, rootFieldKey } from "../core/index.js";
+import { Multiplicity, rootFieldKey } from "../../core/index.js";
 import {
 	type LazyItem,
 	type TreeStatus,
 	isLazy,
 	isTreeValue,
 	FlexObjectNodeSchema,
-} from "../feature-libraries/index.js";
-import { fail, extractFromOpaque, isReadonlyArray } from "../util/index.js";
+	isMapTreeNode,
+} from "../../feature-libraries/index.js";
+import { fail, extractFromOpaque, isReadonlyArray } from "../../util/index.js";
 
-import { getOrCreateNodeProxy, isTreeNode } from "./proxies.js";
-import { getFlexNode } from "./proxyBinding.js";
-import { tryGetSimpleNodeSchema } from "./schemaCaching.js";
+import { getOrCreateNodeFromFlexTreeNode } from "../proxies.js";
+import { getOrCreateInnerNode } from "../proxyBinding.js";
 import {
-	NodeKind,
 	type TreeLeafValue,
-	type TreeNodeSchema,
 	type ImplicitFieldSchema,
 	FieldSchema,
 	type ImplicitAllowedTypes,
 	type TreeNodeFromImplicitAllowedTypes,
-} from "./schemaTypes.js";
-import type { TreeNode } from "./types.js";
+} from "../schemaTypes.js";
 import {
 	booleanSchema,
 	handleSchema,
 	nullSchema,
 	numberSchema,
 	stringSchema,
-} from "./leafNodeSchema.js";
+} from "../leafNodeSchema.js";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import type { Off } from "../../events/index.js";
+import {
+	getKernel,
+	isTreeNode,
+	type TreeNodeSchema,
+	NodeKind,
+	type TreeNode,
+	type TreeChangeEvents,
+	tryGetTreeNodeSchema,
+} from "../core/index.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
@@ -54,9 +61,7 @@ export interface TreeNodeApi {
 	/**
 	 * The schema information for this node.
 	 */
-	schema<T extends TreeNode | TreeLeafValue>(
-		node: T,
-	): TreeNodeSchema<string, NodeKind, unknown, T>;
+	schema(node: TreeNode | TreeLeafValue): TreeNodeSchema;
 
 	/**
 	 * Narrow the type of the given value if it satisfies the given schema.
@@ -102,12 +107,13 @@ export interface TreeNodeApi {
 	/**
 	 * Returns the {@link TreeStatus} of the given node.
 	 */
-	readonly status: (node: TreeNode) => TreeStatus;
+	status(node: TreeNode): TreeStatus;
 
 	/**
 	 * Returns the {@link SchemaFactory.identifier | identifier} of the given node in the most compressed form possible.
 	 * @remarks
 	 * If the node's identifier is a valid UUID that was automatically generated by the SharedTree, then this will return a process-unique integer corresponding to that identifier.
+	 * Note that the node must already have been inserted into the tree in order to retrieve a generated UUID (or shortId will error).
 	 * This is useful for performance-sensitive scenarios involving many nodes with identifiers that need to be compactly retained in memory or used for efficient lookup.
 	 *
 	 * If the node's identifier is any other user-provided string, then this will return that string.
@@ -127,20 +133,20 @@ export interface TreeNodeApi {
  * The `Tree` object holds various functions for analyzing {@link TreeNode}s.
  */
 export const treeNodeApi: TreeNodeApi = {
-	parent: (node: TreeNode): TreeNode | undefined => {
-		const editNode = getFlexNode(node).parentField.parent.parent;
+	parent(node: TreeNode): TreeNode | undefined {
+		const editNode = getOrCreateInnerNode(node).parentField.parent.parent;
 		if (editNode === undefined) {
 			return undefined;
 		}
 
-		const output = getOrCreateNodeProxy(editNode);
+		const output = getOrCreateNodeFromFlexTreeNode(editNode);
 		assert(
 			!isTreeValue(output),
 			0x87f /* Parent can't be a leaf, so it should be a node not a value */,
 		);
 		return output;
 	},
-	key: (node: TreeNode) => {
+	key(node: TreeNode): string | number {
 		// If the parent is undefined, then this node is under the root field,
 		// so we know its key is the special root one.
 		const parent = treeNodeApi.parent(node);
@@ -156,28 +162,20 @@ export const treeNodeApi: TreeNodeApi = {
 		const viewKey = getViewKeyFromStoredKey(parentSchema, storedKey);
 		return viewKey;
 	},
-	on: <K extends keyof TreeChangeEvents>(
+	on<K extends keyof TreeChangeEvents>(
 		node: TreeNode,
 		eventName: K,
 		listener: TreeChangeEvents[K],
-	) => {
-		const flex = getFlexNode(node);
-		switch (eventName) {
-			case "nodeChanged":
-				return flex.on("nodeChanged", listener);
-			case "treeChanged":
-				return flex.on("treeChanged", listener);
-			default:
-				return unreachableCase(eventName);
-		}
+	): Off {
+		return getKernel(node).on(eventName, listener);
 	},
-	status: (node: TreeNode) => {
-		return getFlexNode(node, true).treeStatus();
+	status(node: TreeNode): TreeStatus {
+		return getKernel(node).getStatus();
 	},
-	is: <TSchema extends ImplicitAllowedTypes>(
+	is<TSchema extends ImplicitAllowedTypes>(
 		value: unknown,
 		schema: TSchema,
-	): value is TreeNodeFromImplicitAllowedTypes<TSchema> => {
+	): value is TreeNodeFromImplicitAllowedTypes<TSchema> {
 		const actualSchema = tryGetSchema(value);
 		if (actualSchema === undefined) {
 			return false;
@@ -191,16 +189,16 @@ export const treeNodeApi: TreeNodeApi = {
 			}
 			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;
 		}
 	},
-	schema<T extends TreeNode | TreeLeafValue>(
-		node: T,
-	): TreeNodeSchema<string, NodeKind, unknown, T> {
+	schema(node: TreeNode | TreeLeafValue): TreeNodeSchema {
 		return tryGetSchema(node) ?? fail("Not a tree node");
 	},
 	shortId(node: TreeNode): number | string | undefined {
-		const flexNode = getFlexNode(node);
+		const flexNode = getOrCreateInnerNode(node);
 		const flexSchema = flexNode.schema;
 		const identifierFieldKeys =
 			flexSchema instanceof FlexObjectNodeSchema ? flexSchema.identifierFieldKeys : [];
@@ -209,9 +207,18 @@ export const treeNodeApi: TreeNodeApi = {
 			case 0:
 				return undefined;
 			case 1: {
-				const identifier = flexNode.tryGetField(identifierFieldKeys[0])?.boxedAt(0);
-				assert(identifier !== undefined, 0x927 /* The identifier must exist */);
+				const identifier = flexNode.tryGetField(identifierFieldKeys[0] ?? oob())?.boxedAt(0);
+				if (isMapTreeNode(flexNode)) {
+					if (identifier === undefined) {
+						throw new UsageError(
+							"Tree.shortId cannot access default identifiers on unhydrated nodes",
+						);
+					}
+					return identifier.value as string;
+				}
+				assert(identifier?.context !== undefined, 0xa12 /* Expected LazyIdentifierField */);
 				const identifierValue = identifier.value as string;
+
 				const localNodeKey =
 					identifier.context.nodeKeyManager.tryLocalizeNodeKey(identifierValue);
 				return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : identifierValue;
@@ -228,27 +235,24 @@ export const treeNodeApi: TreeNodeApi = {
  * Returns a schema for a value if the value is a {@link TreeNode} or a {@link TreeLeafValue}.
  * Returns undefined for other values.
  */
-export function tryGetSchema<T>(
-	value: T,
-): undefined | TreeNodeSchema<string, NodeKind, unknown, T> {
-	type TOut = TreeNodeSchema<string, NodeKind, unknown, T>;
+export function tryGetSchema(value: unknown): undefined | TreeNodeSchema {
 	switch (typeof value) {
 		case "string":
-			return stringSchema as TOut;
+			return stringSchema;
 		case "number":
-			return numberSchema as TOut;
+			return numberSchema;
 		case "boolean":
-			return booleanSchema as TOut;
+			return booleanSchema;
 		case "object": {
 			if (isTreeNode(value)) {
 				// This case could be optimized, for example by placing the simple schema in a symbol on tree nodes.
-				return tryGetSimpleNodeSchema(getFlexNode(value).schema) as TOut;
+				return tryGetTreeNodeSchema(value);
 			}
 			if (value === null) {
-				return nullSchema as TOut;
+				return nullSchema;
 			}
 			if (isFluidHandle(value)) {
-				return handleSchema as TOut;
+				return handleSchema;
 			}
 		}
 		default:
@@ -262,13 +266,13 @@ export function tryGetSchema<T>(
 function getStoredKey(node: TreeNode): string | number {
 	// Note: the flex domain strictly works with "stored keys", and knows nothing about the developer-facing
 	// "view keys".
-	const parentField = getFlexNode(node).parentField;
+	const parentField = getOrCreateInnerNode(node).parentField;
 	if (parentField.parent.schema.kind.multiplicity === Multiplicity.Sequence) {
 		// The parent of `node` is an array node
 		return parentField.index;
 	}
 
-	// The parent of `node` is an object, a map, or undefined (and therefore `node` is a root/detached node).
+	// The parent of `node` is an object, a map, or undefined. If undefined, then `node` is a root/detached node.
 	return parentField.parent.key;
 }
 
@@ -304,78 +308,3 @@ function getViewKeyFromStoredKey(
 
 	return storedKey;
 }
-
-/**
- * A collection of events that can be emitted by a {@link TreeNode}.
- *
- * @privateRemarks
- * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).
- * Probably have object node and map node specific APIs for this.
- *
- * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.
- *
- * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.
- * Some ideas:
- *
- * - treeChanged, but with some subtrees/fields/paths excluded
- * - helper to batch several nodeChanged calls to a treeChanged scope
- * - parent change (ex: registration on the parent field for a specific index: maybe allow it for a range. Ex: node event takes optional field and optional index range?)
- * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.
- * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)
- * to allow efficiently searching for new content (and initial content) of a given type.
- *
- * @sealed @public
- */
-export interface TreeChangeEvents {
-	/**
-	 * Emitted by a node after a batch of changes has been applied to the tree, if a change affected the node, where a
-	 * change is:
-	 *
-	 * - For an object node, when the value of one of its properties changes (i.e., the property's value is set
-	 * to something else, including `undefined`).
-	 *
-	 * - For an array node, when an element is added, removed, or moved.
-	 *
-	 * - For a map node, when an entry is added, updated, or removed.
-	 *
-	 * @remarks
-	 * This event is not emitted when:
-	 *
-	 * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing
-	 * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the
-	 * array/map node as one of its properties.
-	 *
-	 * - The node is moved to a different location in the tree or removed from the tree.
-	 * In this case the event is emitted on the _parent_ node, not the node itself.
-	 *
-	 * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
-	 * the client that made the original edit.
-	 *
-	 * When it is emitted, the tree is guaranteed to be in-schema.
-	 *
-	 * @privateRemarks
-	 * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.
-	 * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the
-	 * node, or when the node has to be updated due to resolution of a merge conflict
-	 * (for example a previously applied local change might be undone, then reapplied differently or not at all).
-	 */
-	nodeChanged(): void;
-
-	/**
-	 * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the
-	 * subtree rooted at it.
-	 *
-	 * @remarks
-	 * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.
-	 * In that case it is emitted on the _parent_ node, not the node itself.
-	 *
-	 * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties
-	 * of the node itself.
-	 *
-	 * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
-	 * the client that made the original edit.
-	 *
-	 * When it is emitted, the tree is guaranteed to be in-schema.
-	 */
-	treeChanged(): void;
-}