@fluidframework/tree 2.1.0-276985 → 2.1.0

package/src/simple-tree/tree.ts

@@ -9,11 +9,20 @@ import type { CommitMetadata } from "../core/index.js";
 import type { Listenable } from "../events/index.js";
 import type { RevertibleFactory } from "../shared-tree/index.js";
 
-import type {
-	ImplicitFieldSchema,
-	InsertableTreeFieldFromImplicitField,
-	TreeFieldFromImplicitField,
+import {
+	type ImplicitAllowedTypes,
+	NodeKind,
+	normalizeFieldSchema,
+	type ImplicitFieldSchema,
+	type InsertableTreeFieldFromImplicitField,
+	type TreeFieldFromImplicitField,
+	type TreeNodeSchema,
 } from "./schemaTypes.js";
+import { toFlexSchema } from "./toFlexSchema.js";
+import { LeafNodeSchema } from "./leafNodeSchema.js";
+import { assert } from "@fluidframework/core-utils/internal";
+import { isObjectNodeSchema } from "./objectNode.js";
+import { markSchemaMostDerived } from "./schemaFactory.js";
 
 /**
  * Channel for a Fluid Tree DDS.
@@ -130,6 +139,61 @@ export class TreeViewConfiguration<TSchema extends ImplicitFieldSchema = Implici
 		const config = { ...defaultTreeConfigurationOptions, ...props };
 		this.schema = config.schema;
 		this.enableSchemaValidation = config.enableSchemaValidation;
+
+		// Ensure all reachable schema are marked as most derived.
+		// This ensures if multiple schema extending the same schema factory generated class are present (or have been constructed, or get constructed in the future),
+		// an error is reported.
+		walkFieldSchema(config.schema, markSchemaMostDerived);
+		// Eagerly perform this conversion to surface errors sooner.
+		toFlexSchema(config.schema);
+	}
+}
+
+export function walkNodeSchema(
+	schema: TreeNodeSchema,
+	visitor: (schema: TreeNodeSchema) => void,
+	visitedSet: Set<TreeNodeSchema>,
+): void {
+	if (visitedSet.has(schema)) {
+		return;
+	}
+	visitedSet.add(schema);
+	if (schema instanceof LeafNodeSchema) {
+		// nothing to do
+	} else if (isObjectNodeSchema(schema)) {
+		for (const field of schema.fields.values()) {
+			walkAllowedTypes(field.allowedTypeSet, visitor, visitedSet);
+		}
+	} else {
+		assert(
+			schema.kind === NodeKind.Array || schema.kind === NodeKind.Map,
+			0x9b3 /* invalid schema */,
+		);
+		const childTypes = schema.info as ImplicitAllowedTypes;
+		walkFieldSchema(childTypes, visitor, visitedSet);
+	}
+	// This visit is done at the end so the traversal order is most inner types first.
+	// This was picked since when fixing errors,
+	// working from the inner types out to the types that use them will probably go better than the reverse.
+	// This does not however ensure all types referenced by a type are visited before it, since in recursive cases thats impossible.
+	visitor(schema);
+}
+
+export function walkFieldSchema(
+	schema: ImplicitFieldSchema,
+	visitor: (schema: TreeNodeSchema) => void,
+	visitedSet: Set<TreeNodeSchema> = new Set(),
+): void {
+	walkAllowedTypes(normalizeFieldSchema(schema).allowedTypeSet, visitor, visitedSet);
+}
+
+export function walkAllowedTypes(
+	allowedTypes: Iterable<TreeNodeSchema>,
+	visitor: (schema: TreeNodeSchema) => void,
+	visitedSet: Set<TreeNodeSchema>,
+): void {
+	for (const childType of allowedTypes) {
+		walkNodeSchema(childType, visitor, visitedSet);
 	}
 }
 

package/src/simple-tree/treeNodeApi.ts

@@ -3,20 +3,20 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 
 import { Multiplicity, rootFieldKey } from "../core/index.js";
 import {
-	FieldKinds,
 	type LazyItem,
 	type TreeStatus,
 	isLazy,
 	isTreeValue,
+	FlexObjectNodeSchema,
 } 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 { getFlexNode, getKernel } from "./proxyBinding.js";
 import { tryGetSimpleNodeSchema } from "./schemaCaching.js";
 import {
 	NodeKind,
@@ -27,7 +27,7 @@ import {
 	type ImplicitAllowedTypes,
 	type TreeNodeFromImplicitAllowedTypes,
 } from "./schemaTypes.js";
-import type { TreeNode } from "./types.js";
+import type { TreeNode, TreeChangeEvents } from "./types.js";
 import {
 	booleanSchema,
 	handleSchema,
@@ -37,6 +37,7 @@ import {
 } from "./leafNodeSchema.js";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import type { Off } from "../events/index.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
@@ -102,7 +103,7 @@ 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.
@@ -127,7 +128,7 @@ export interface TreeNodeApi {
  * The `Tree` object holds various functions for analyzing {@link TreeNode}s.
  */
 export const treeNodeApi: TreeNodeApi = {
-	parent: (node: TreeNode): TreeNode | undefined => {
+	parent(node: TreeNode): TreeNode | undefined {
 		const editNode = getFlexNode(node).parentField.parent.parent;
 		if (editNode === undefined) {
 			return undefined;
@@ -140,7 +141,7 @@ export const treeNodeApi: TreeNodeApi = {
 		);
 		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 +157,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;
@@ -201,26 +194,26 @@ export const treeNodeApi: TreeNodeApi = {
 	},
 	shortId(node: TreeNode): number | string | undefined {
 		const flexNode = getFlexNode(node);
-		let shortId: number | string | undefined;
-		for (const field of flexNode.boxedIterator()) {
-			if (field.schema.kind === FieldKinds.identifier) {
-				if (shortId !== undefined) {
-					throw new UsageError(
-						"shortId() may not be called on a node with more than one identifier. Consider converting extraneous identifier fields to string fields.",
-					);
-				}
-				const identifier = field.boxedAt(0);
+		const flexSchema = flexNode.schema;
+		const identifierFieldKeys =
+			flexSchema instanceof FlexObjectNodeSchema ? flexSchema.identifierFieldKeys : [];
+
+		switch (identifierFieldKeys.length) {
+			case 0:
+				return undefined;
+			case 1: {
+				const identifier = flexNode.tryGetField(identifierFieldKeys[0])?.boxedAt(0);
 				assert(identifier !== undefined, 0x927 /* The identifier must exist */);
 				const identifierValue = identifier.value as string;
 				const localNodeKey =
 					identifier.context.nodeKeyManager.tryLocalizeNodeKey(identifierValue);
-
-				shortId =
-					localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : identifierValue;
+				return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : identifierValue;
 			}
+			default:
+				throw new UsageError(
+					"shortId() may not be called on a node with more than one identifier. Consider converting extraneous identifier fields to string fields.",
+				);
 		}
-
-		return shortId;
 	},
 };
 
@@ -304,78 +297,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;
-}

package/src/simple-tree/treeNodeKernel.ts

@@ -0,0 +1,91 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+import { createEmitter, type Listenable, type Off } from "../events/index.js";
+import type { TreeChangeEvents, TreeNode } from "./types.js";
+import type { AnchorNode } from "../core/index.js";
+import {
+	flexTreeSlot,
+	isFreedSymbol,
+	LazyEntity,
+	TreeStatus,
+	treeStatusFromAnchorCache,
+} from "../feature-libraries/index.js";
+
+/**
+ * Contains state and an internal API for managing {@link TreeNode}s.
+ * @remarks All {@link TreeNode}s have an associated kernel object.
+ * The kernel has the same lifetime as the node and spans both its unhydrated and hydrated states.
+ * When hydration occurs, the kernel is notified via the {@link TreeNodeKernel.hydrate | hydrate} method.
+ */
+export class TreeNodeKernel implements Listenable<TreeChangeEvents> {
+	#hydrated?: {
+		anchorNode: AnchorNode;
+		offAnchorNode: Off;
+	};
+	#events = createEmitter<TreeChangeEvents>();
+
+	public constructor(public readonly node: TreeNode) {}
+
+	public hydrate(anchorNode: AnchorNode): void {
+		const offChildrenChanged = anchorNode.on("childrenChangedAfterBatch", () => {
+			this.#events.emit("nodeChanged");
+		});
+
+		const offSubtreeChanged = anchorNode.on("subtreeChangedAfterBatch", () => {
+			this.#events.emit("treeChanged");
+		});
+
+		const offAfterDestroy = anchorNode.on("afterDestroy", () => this.dispose());
+
+		this.#hydrated = {
+			anchorNode,
+			offAnchorNode: () => {
+				offChildrenChanged();
+				offSubtreeChanged();
+				offAfterDestroy();
+			},
+		};
+	}
+
+	public dehydrate(): void {
+		this.#hydrated?.offAnchorNode?.();
+		this.#hydrated = undefined;
+	}
+
+	public isHydrated(): boolean {
+		return this.#hydrated !== undefined;
+	}
+
+	public getStatus(): TreeStatus {
+		if (this.#hydrated?.anchorNode === undefined) {
+			return TreeStatus.New;
+		}
+
+		// TODO: Replace this check with the proper check against the cursor state when the cursor becomes part of the kernel
+		const flex = this.#hydrated.anchorNode.slots.get(flexTreeSlot);
+		if (flex !== undefined) {
+			assert(flex instanceof LazyEntity, 0x9b4 /* Unexpected flex node implementation */);
+			if (flex[isFreedSymbol]()) {
+				return TreeStatus.Deleted;
+			}
+		}
+
+		return treeStatusFromAnchorCache(this.#hydrated.anchorNode);
+	}
+
+	public on<K extends keyof TreeChangeEvents>(
+		eventName: K,
+		listener: TreeChangeEvents[K],
+	): Off {
+		return this.#events.on(eventName, listener);
+	}
+
+	public dispose(): void {
+		this.dehydrate();
+		// TODO: go to the context and remove myself from withAnchors
+	}
+}