@fluidframework/tree 2.0.0-rc.2.0.2 → 2.0.0-rc.3.0.0

package/src/simple-tree/proxyBinding.ts

@@ -0,0 +1,182 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+
+import { AnchorNode, AnchorSet, UpPath, anchorSlot } from "../core/index.js";
+import {
+	ContextSlot,
+	FlexTreeNodeSchema,
+	FlexMapNodeSchema,
+	FlexObjectNodeSchema,
+	FlexTreeMapNode,
+	FlexTreeNode,
+	FlexTreeObjectNode,
+	assertFlexTreeEntityNotFreed,
+	flexTreeSlot,
+} from "../feature-libraries/index.js";
+import { fail } from "../util/index.js";
+import { RawTreeNode } from "./rawNode.js";
+import { WithType } from "./schemaTypes.js";
+import { TreeArrayNode } from "./arrayNode.js";
+import { TreeNode } from "./types.js";
+// TODO: decide how to deal with dependencies on flex-tree implementation.
+// eslint-disable-next-line import/no-internal-modules
+import { makeTree } from "../feature-libraries/flex-tree/lazyNode.js";
+import { TreeMapNode } from "./mapNode.js";
+
+// This file contains various maps and helpers for supporting proxy binding (a.k.a. proxy hydration).
+// See ./ProxyBinding.md for a high-level overview of the process.
+
+/**
+ * An anchor slot which associates an anchor with its corresponding node proxy, if there is one.
+ */
+const proxySlot = anchorSlot<TreeNode>();
+
+// The following records are maintained as WeakMaps, rather than a private symbol (e.g. like `targetSymbol`) on the node proxy itself.
+// The map behaves essentially the same, except that performing a lookup in the map will not perform a property read/get on the key object (as is the case with a symbol).
+// Since `SharedTreeNodes` are proxies with non-trivial `get` traps, this choice is meant to prevent the confusion of the lookup passing through multiple objects
+// via the trap, or the trap not properly handling the special symbol, etc.
+
+/** A reverse mapping of {@link proxySlot} that is updated at the same time. */
+const proxyToAnchorNode = new WeakMap<TreeNode, AnchorNode>();
+/**
+ * Maps proxies to their "raw" tree nodes.
+ * The raw node exists when the proxy is first created but before it has been associated with a real {@link FlexTreeNode}.
+ * For example, after a user calls `const proxy = new Foo({})` but before `proxy` is inserted into the tree and queried.
+ */
+const proxyToRawFlexNode = new WeakMap<TreeNode, RawTreeNode<FlexTreeNodeSchema, unknown>>();
+/** Used by `anchorProxy` as an optimization to ensure that only one anchor is remembered at a time for a given anchor node */
+const anchorForgetters = new WeakMap<TreeNode, () => void>();
+
+/**
+ * Creates an anchor node and associates it with the given proxy.
+ * @privateRemarks Use `forgetters` to cleanup the anchor allocated by this function once the anchor is no longer needed.
+ * In practice, this happens when either the anchor node is destroyed, or another anchor to the same node is created by a new flex node.
+ */
+export function anchorProxy(anchors: AnchorSet, path: UpPath, proxy: TreeNode): void {
+	assert(!anchorForgetters.has(proxy), 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");
+	bindProxyToAnchorNode(proxy, anchorNode);
+	const forget = () => {
+		if (anchors.locate(anchor)) {
+			anchors.forget(anchor);
+		}
+		anchorForgetters.delete(proxy);
+		off();
+	};
+	anchorForgetters.set(proxy, forget);
+	const off = anchorNode.on("afterDestroy", forget);
+}
+
+/**
+ * Retrieves the flex node associated with the given target via {@link setFlexNode}.
+ * @remarks Fails if the flex node has not been set.
+ */
+export function getFlexNode(
+	proxy: TypedNode<FlexObjectNodeSchema>,
+	allowFreed?: true,
+): FlexTreeObjectNode;
+export function getFlexNode(proxy: TreeArrayNode, allowFreed?: true): FlexTreeNode;
+export function getFlexNode(
+	proxy: TreeMapNode,
+	allowFreed?: true,
+): FlexTreeMapNode<FlexMapNodeSchema>;
+export function getFlexNode(proxy: TreeNode, allowFreed?: true): FlexTreeNode;
+export function getFlexNode(proxy: TreeNode, allowFreed = false): FlexTreeNode {
+	const anchorNode = proxyToAnchorNode.get(proxy);
+	if (anchorNode !== undefined) {
+		// The proxy is bound to an anchor node, but it may or may not have an actual flex node yet
+		const flexNode = anchorNode.slots.get(flexTreeSlot);
+		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 cursor = context.forest.allocateCursor();
+		context.forest.moveCursorToPath(anchorNode, cursor);
+		const newFlexNode = makeTree(context, cursor);
+		cursor.free();
+		// Calling this is a performance improvement, however, do this only after demand to avoid momentarily having no anchors to anchorNode
+		anchorForgetters?.get(proxy)?.();
+		if (!allowFreed) {
+			assertFlexTreeEntityNotFreed(newFlexNode);
+		}
+		return newFlexNode;
+	}
+
+	return proxyToRawFlexNode.get(proxy) ?? fail("Expected raw tree node for proxy");
+}
+
+/**
+ * Retrieves the flex node associated with the given target via {@link setFlexNode}, if any.
+ */
+export function tryGetFlexNode(target: unknown): FlexTreeNode | undefined {
+	// Calling 'WeakMap.get()' with primitives (numbers, strings, etc.) will return undefined.
+	// This is in contrast to 'WeakMap.set()', which will throw a TypeError if given a non-object key.
+	return (
+		proxyToAnchorNode.get(target as TreeNode)?.slots.get(flexTreeSlot) ??
+		proxyToRawFlexNode.get(target as TreeNode)
+	);
+}
+
+/**
+ * Retrieves the proxy associated with the given flex node via {@link setFlexNode}, if any.
+ */
+export function tryGetProxy(flexNode: FlexTreeNode): TreeNode | undefined {
+	return flexNode.anchorNode.slots.get(proxySlot);
+}
+
+/**
+ * Associate the given proxy and the given flex node.
+ * @returns The proxy
+ * @remarks
+ * This creates a 1:1 mapping between the proxy and tree node.
+ * Either can be retrieved from the other via {@link getFlexNode}/{@link tryGetFlexNode} or {@link tryGetProxy}.
+ * If the given proxy is already mapped to an flex node, the existing mapping will be overwritten.
+ * If the given flex node is already mapped to a different proxy, this function will fail.
+ */
+export function setFlexNode<TProxy extends TreeNode>(
+	proxy: TProxy,
+	flexNode: FlexTreeNode,
+): TProxy {
+	const existingFlexNode = proxyToAnchorNode.get(proxy)?.slots.get(flexTreeSlot);
+	assert(
+		existingFlexNode === undefined,
+		0x91d /* Cannot associate a flex node with multiple targets */,
+	);
+	if (flexNode instanceof RawTreeNode) {
+		proxyToRawFlexNode.set(proxy, flexNode);
+	} else {
+		assert(
+			tryGetProxy(flexNode) === undefined,
+			0x7f5 /* Cannot associate an flex node with multiple targets */,
+		);
+		bindProxyToAnchorNode(proxy, flexNode.anchorNode);
+	}
+	return proxy;
+}
+
+/**
+ * Bi-directionally associates the given proxy to the given anchor node.
+ * @remarks Cleans up mappings to raw flex nodes - it is assumed that they are no longer needed once the proxy has an anchor node.
+ */
+function bindProxyToAnchorNode(proxy: TreeNode, anchorNode: AnchorNode): void {
+	// If the proxy currently has a raw node, forget it
+	proxyToRawFlexNode.delete(proxy);
+	// Once a proxy has been associated with an anchor node, it should never change to another anchor node
+	assert(
+		!proxyToAnchorNode.has(proxy),
+		0x91e /* Proxy has already been bound to a different anchor node */,
+	);
+	proxyToAnchorNode.set(proxy, anchorNode);
+	// However, it's fine for an anchor node to rotate through different proxies when the content at that place in the tree is replaced.
+	anchorNode.slots.set(proxySlot, proxy);
+}
+
+/**
+ * Given a node's schema, return the corresponding object in the proxy-based API.
+ */
+type TypedNode<TSchema extends FlexTreeNodeSchema> = TreeNode & WithType<TSchema["name"]>;

package/src/simple-tree/rawNode.ts

@@ -3,34 +3,22 @@
  * Licensed under the MIT License.
  */
 
-import { FieldKey, TreeNodeSchemaIdentifier } from "../core/index.js";
+import { Anchor, AnchorNode, FieldKey, TreeNodeSchemaIdentifier } from "../core/index.js";
 import {
-	EditableTreeEvents,
-	FlexFieldNodeSchema,
 	FlexTreeContext,
+	FlexTreeEntityKind,
 	FlexTreeField,
 	FlexTreeNode,
-	FlexTreeTypedNode,
-	FlexTreeEntityKind,
-	FlexTreeMapNode,
-	FlexTreeObjectNode,
-	FlexTreeTypedField,
-	FlexTreeUnboxField,
-	FlexibleFieldContent,
-	flexTreeMarker,
-	onNextChange,
-	LocalNodeKey,
-	FlexMapNodeSchema,
-	FlexObjectNodeSchema,
+	FlexTreeNodeEvents,
 	FlexTreeNodeSchema,
+	FlexTreeTypedNode,
 	TreeStatus,
-	FlexTreeFieldNode,
+	flexTreeMarker,
 } from "../feature-libraries/index.js";
 import { fail } from "../util/index.js";
-import { InsertableContent } from "./proxies.js";
 
 /** Stores the content of the raw node, i.e. the data that was passed to the factory */
-const nodeContent = Symbol();
+export const nodeContent = Symbol();
 interface HasNodeContent<T> {
 	[nodeContent]: T;
 }
@@ -52,39 +40,23 @@ export function extractRawNodeContent(node: object): object | undefined {
 }
 
 /**
- * Creates a node that pretends to satisfy the given schema while wrapping the given node content.
+ * Node that pretends to satisfy the given schema while wrapping the given node content.
  * Retrieve the node content via {@link extractRawNodeContent}.
  *
  * @remarks This is useful for creating "raw" nodes: nodes which capture data about a pending insertion but are not yet inserted.
  * These raw nodes can be then used on the right-hand side of an assignment (via `=`) to the tree.
  * However, many of their properties and methods are currently unimplemented and will error if accessed.
  */
-export function createRawNode(
-	schema: FlexTreeNodeSchema,
-	content: InsertableContent,
-): RawTreeNode<FlexTreeNodeSchema, InsertableContent> {
-	if (schema instanceof FlexObjectNodeSchema) {
-		return new RawObjectNode(schema, content as object);
-	}
-	if (schema instanceof FlexMapNodeSchema) {
-		return new RawMapNode(schema, content as ReadonlyMap<string, InsertableContent>);
-	}
-	if (schema instanceof FlexFieldNodeSchema) {
-		return new RawFieldNode(schema, content);
-	}
-	fail("Unrecognized schema");
-}
-
-/**
- * The base implementation of a node created by {@link createRawNode}.
- */
 export abstract class RawTreeNode<TSchema extends FlexTreeNodeSchema, TContent>
 	implements FlexTreeNode, HasNodeContent<TContent>
 {
 	public readonly [flexTreeMarker] = FlexTreeEntityKind.Node as const;
 	public readonly [nodeContent]: TContent;
 
+	#anchor: Anchor | undefined;
+
 	public readonly type: TreeNodeSchemaIdentifier;
+
 	public constructor(
 		public readonly schema: TSchema,
 		content: TContent,
@@ -111,6 +83,10 @@ export abstract class RawTreeNode<TSchema extends FlexTreeNodeSchema, TContent>
 		throw rawError("Reading fields");
 	}
 
+	public getBoxed(key: string): never {
+		throw rawError("Reading boxed fields");
+	}
+
 	public boxedIterator(): IterableIterator<FlexTreeField> {
 		throw rawError("Boxed iteration");
 	}
@@ -122,111 +98,19 @@ export abstract class RawTreeNode<TSchema extends FlexTreeNodeSchema, TContent>
 
 	public value: undefined;
 
-	public on<K extends keyof EditableTreeEvents>(
+	public on<K extends keyof FlexTreeNodeEvents>(
 		eventName: K,
-		listener: EditableTreeEvents[K],
+		listener: FlexTreeNodeEvents[K],
 	): () => void {
 		throw rawError("Event registration");
 	}
 
-	public [onNextChange](fn: (node: FlexTreeNode) => void): () => void {
-		throw rawError("onNextChange event registration");
-	}
-}
-
-/**
- * The implementation of an object node created by {@link createRawNode}.
- */
-export class RawObjectNode<TSchema extends FlexObjectNodeSchema, TContent extends object>
-	extends RawTreeNode<TSchema, TContent>
-	implements FlexTreeObjectNode
-{
-	public get localNodeKey(): LocalNodeKey | undefined {
-		throw rawError("Reading local node keys");
-	}
-}
-
-/**
- * The implementation of a map node created by {@link createRawNode}.
- */
-export class RawMapNode<TSchema extends FlexMapNodeSchema>
-	extends RawTreeNode<TSchema, ReadonlyMap<string, InsertableContent>>
-	implements FlexTreeMapNode<TSchema>
-{
-	public get size(): number {
-		return this[nodeContent].size;
-	}
-	public has(key: string): boolean {
-		return this[nodeContent].has(key);
-	}
-	public get(key: string): FlexTreeUnboxField<TSchema["info"]> {
-		return this[nodeContent].get(key) as FlexTreeUnboxField<TSchema["info"]>;
-	}
-	public getBoxed(key: string): FlexTreeTypedField<TSchema["info"]> {
-		throw rawError("Reading boxed map values");
-	}
-	public keys(): IterableIterator<FieldKey> {
-		return this[nodeContent].keys() as IterableIterator<FieldKey>;
-	}
-	public values(): IterableIterator<FlexTreeUnboxField<TSchema["info"], "notEmpty">> {
-		throw rawError("Iterating map values");
-	}
-	public entries(): IterableIterator<
-		[FieldKey, FlexTreeUnboxField<TSchema["info"], "notEmpty">]
-	> {
-		throw rawError("Iterating map entries");
-	}
-	public forEach(
-		callbackFn: (
-			value: FlexTreeUnboxField<TSchema["info"], "notEmpty">,
-			key: FieldKey,
-			map: FlexTreeMapNode<TSchema>,
-		) => void,
-		thisArg?: any,
-	): void {
-		throw rawError("Iterating maps with forEach");
-	}
-	public set(key: string, value: FlexibleFieldContent<TSchema["info"]> | undefined): void {
-		throw rawError("Setting a map entry");
-	}
-	public delete(key: string): void {
-		throw rawError("Deleting a map entry");
-	}
-
-	public get asObject(): {
-		readonly [P in FieldKey]?: FlexTreeUnboxField<TSchema["info"], "notEmpty">;
-	} {
-		throw rawError("Converting a map to an object");
-	}
-
-	public [Symbol.iterator](): IterableIterator<
-		[FieldKey, FlexTreeUnboxField<TSchema["info"], "notEmpty">]
-	> {
-		return this.entries();
-	}
-
-	public override boxedIterator(): IterableIterator<FlexTreeTypedField<TSchema["info"]>> {
-		throw rawError("Boxed iteration");
-	}
-}
-
-/**
- * The implementation of a field node created by {@link createRawNode}.
- */
-export class RawFieldNode<TSchema extends FlexFieldNodeSchema>
-	extends RawTreeNode<TSchema, InsertableContent>
-	implements FlexTreeFieldNode<TSchema>
-{
-	public get content(): FlexTreeUnboxField<TSchema["info"]> {
-		throw rawError("Reading content of an array node");
-	}
-
-	public get boxedContent(): FlexTreeTypedField<TSchema["info"]> {
-		throw rawError("Reading boxed content of an array node");
+	public get anchorNode(): AnchorNode {
+		throw rawError("Reading anchor node");
 	}
 }
 
-function rawError(message?: string): Error {
+export function rawError(message?: string): Error {
 	return new Error(
 		`${
 			message ?? "Operation"

package/src/simple-tree/schemaCaching.ts

@@ -0,0 +1,90 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+
+import {
+	type FlexFieldSchema,
+	type FlexTreeNodeSchema,
+	TreeNodeSchemaBase,
+} from "../feature-libraries/index.js";
+import { fail } from "../util/index.js";
+
+import {
+	FieldSchema,
+	type ImplicitFieldSchema,
+	TreeNodeSchema,
+	normalizeFieldSchema,
+} from "./schemaTypes.js";
+
+/**
+ * A symbol for storing FlexTreeSchema on TreeNodeSchema.
+ * Eagerly set on leaves, and lazily set for other cases.
+ */
+const flexSchemaSymbol: unique symbol = Symbol(`flexSchema`);
+
+/**
+ * A symbol for storing TreeNodeSchema on FlexTreeNode's schema.
+ */
+const simpleNodeSchemaSymbol: unique symbol = Symbol(`simpleNodeSchema`);
+
+/**
+ * A symbol for storing {@link FieldSchema}s on a {@link FlexFieldSchema}.
+ */
+const simpleFieldSchemaSymbol: unique symbol = Symbol(`simpleFieldSchema`);
+
+export function cachedFlexSchemaFromClassSchema(
+	schema: TreeNodeSchema,
+): TreeNodeSchemaBase | undefined {
+	return (schema as any)[flexSchemaSymbol] as TreeNodeSchemaBase | undefined;
+}
+
+export function setFlexSchemaFromClassSchema(
+	simple: TreeNodeSchema,
+	flex: TreeNodeSchemaBase,
+): void {
+	assert(!(flexSchemaSymbol in simple), 0x91f /* simple schema already marked */);
+	assert(!(simpleNodeSchemaSymbol in flex), 0x920 /* flex schema already marked */);
+	(simple as any)[flexSchemaSymbol] = flex;
+	(flex as any)[simpleNodeSchemaSymbol] = simple;
+}
+
+/**
+ * Gets the {@link TreeNodeSchema} cached on the provided {@link FlexTreeNodeSchema | flexSchema}.
+ * Returns `undefined` if no cached value is found.
+ */
+export function tryGetSimpleNodeSchema(flexSchema: FlexTreeNodeSchema): TreeNodeSchema | undefined {
+	if (simpleNodeSchemaSymbol in flexSchema) {
+		return flexSchema[simpleNodeSchemaSymbol] as TreeNodeSchema;
+	}
+	return undefined;
+}
+
+/**
+ * Gets the {@link TreeNodeSchema} cached on the provided {@link FlexTreeNodeSchema | flexSchema}.
+ * Fails if no cached value is found.
+ */
+export function getSimpleNodeSchema(flexSchema: FlexTreeNodeSchema): TreeNodeSchema {
+	return tryGetSimpleNodeSchema(flexSchema) ?? fail("missing simple schema");
+}
+
+/**
+ * Gets the {@link FieldSchema} which corresponds with the provided {@link FlexFieldSchema | flexSchema}.
+ * Caches the result on the provided `flexSchema` for future access.
+ * @param flexSchema - The flex schema on which the result will be cached.
+ * @param implicitSimpleSchema - The allowed types from which the `FieldSchema` will be derived.
+ */
+export function getSimpleFieldSchema(
+	flexSchema: FlexFieldSchema,
+	implicitSimpleSchema: ImplicitFieldSchema,
+): FieldSchema {
+	if (simpleFieldSchemaSymbol in flexSchema) {
+		return flexSchema[simpleFieldSchemaSymbol] as FieldSchema;
+	}
+
+	const fieldSchema = normalizeFieldSchema(implicitSimpleSchema);
+	(flexSchema as any)[simpleFieldSchemaSymbol] = fieldSchema;
+	return fieldSchema;
+}

package/src/simple-tree/schemaCreationUtilities.ts

@@ -3,18 +3,15 @@
  * Licensed under the MIT License.
  */
 
-import { UsageError } from "@fluidframework/telemetry-utils";
-import { fail } from "../util/index.js";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
 import { EmptyObject } from "../feature-libraries/index.js";
+import { fail } from "../util/index.js";
+
 import { SchemaFactory, type ScopedSchemaName } from "./schemaFactory.js";
-import {
-	InsertableObjectFromSchemaRecord,
-	NodeFromSchema,
-	NodeKind,
-	ObjectFromSchemaRecord,
-	TreeNodeSchemaClass,
-} from "./schemaTypes.js";
+import { NodeFromSchema, NodeKind, TreeNodeSchemaClass } from "./schemaTypes.js";
 import { TreeNode } from "./types.js";
+import { InsertableObjectFromSchemaRecord, ObjectFromSchemaRecord } from "./objectNode.js";
 
 /**
  * Create a schema for a node with no state.