@fluidframework/tree 2.3.0-288113 → 2.4.0-294316

package/src/simple-tree/proxyBinding.ts

@@ -3,106 +3,9 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
-
-import { type AnchorNode, type AnchorSet, type UpPath, anchorSlot } from "../core/index.js";
-import {
-	ContextSlot,
-	type FlexTreeNodeSchema,
-	type FlexMapNodeSchema,
-	type FlexObjectNodeSchema,
-	type FlexTreeMapNode,
-	type FlexTreeNode,
-	type FlexTreeObjectNode,
-	assertFlexTreeEntityNotFreed,
-	flexTreeSlot,
-	type FieldKinds,
-	type FlexFieldSchema,
-	type MapTreeNode,
-	isMapTreeNode,
-} from "../feature-libraries/index.js";
-import { fail } from "../util/index.js";
-import type { WithType, TreeNode } from "./core/index.js";
-import type { TreeArrayNode } from "./arrayNode.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 type { TreeMapNode } from "./mapNode.js";
+import type { InnerNode, TreeNode } from "./core/index.js";
 import { getKernel } from "./core/index.js";
 
-// This file contains various maps and helpers for supporting associating simple TreeNodes with their InnerNodes, and swapping those InnerNodes as part of hydration.
-// See ./ProxyBinding.md for a high-level overview of the process.
-
-/**
- * An anchor slot which associates an anchor with its corresponding TreeNode, if there is one.
- * @remarks
- * For this to work, we have to require that there is at most a single view using a given AnchorSet.
- * FlexTree already has this assumption, and we also assume there is a single simple-tree per FlexTree, so this is valid.
- */
-const proxySlot = anchorSlot<TreeNode>();
-
-// The following records are maintained as WeakMaps, rather than a private symbol (e.g. like `targetSymbol`) on the TreeNode.
-// 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.
- *
- * @remarks
- * Nodes in this map are hydrated (and thus "marinated" or "cooked").
- * Nodes not in this map are known to be {@link Unhydrated}.
- * Thus this map can be used to check if a node is hydrated.
- *
- * Any node not in this map must be in {@link proxyToMapTreeNode} since it contains all unhydrated nodes.
- * It also contains "marinated" nodes which are in both.
- */
-const proxyToAnchorNode = new WeakMap<TreeNode, AnchorNode>();
-
-/**
- * Map {@link Unhydrated} nodes and "marinated" nodes to and from their underlying MapTreeNode.
- * These maps are populated by the TreeNode's constructor when called by a user before the node is inserted into the tree and queried.
- */
-const proxyToMapTreeNode = new WeakMap<TreeNode, MapTreeNode>();
-
-/**
- * {@inheritdoc proxyToMapTreeNode}
- */
-const mapTreeNodeToProxy = new WeakMap<MapTreeNode, TreeNode>();
-
-/**
- * Used by {@link 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.
- *
- * The FlexTreeNode holds a reference to the same anchor, and has a lifetime at least as long as the simple-tree,
- * so this would be unnecessary except for the case of "marinated" nodes, which have an anchor,
- * but might not have a FlexTreeNode.
- * Handling this case is an optimization assuming that this extra anchor reference is cheaper than eagerly creating FlexTreeNodes.
- */
-export function anchorProxy(anchors: AnchorSet, path: UpPath, proxy: TreeNode): AnchorNode {
-	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");
-	bindHydratedNodeToAnchor(proxy, anchorNode);
-	const forget = (): void => {
-		if (anchors.locate(anchor)) {
-			anchors.forget(anchor);
-		}
-		anchorForgetters.delete(proxy);
-		off();
-	};
-	anchorForgetters.set(proxy, forget);
-	const off = anchorNode.on("afterDestroy", forget);
-	return anchorNode;
-}
-
 /**
  * Retrieves the flex node associated with the given target via {@link setInnerNode}.
  * @remarks
@@ -111,161 +14,7 @@ export function anchorProxy(anchors: AnchorSet, path: UpPath, proxy: TreeNode):
  * For hydrated nodes it returns a FlexTreeNode backed by the forest.
  * Note that for "marinated" nodes, this FlexTreeNode exists and returns it: it does not return the MapTreeNode which is the current InnerNode.
  */
-export function getOrCreateInnerNode(
-	treeNode: TypedNode<FlexObjectNodeSchema>,
-	allowFreed?: true,
-): InnerNode & FlexTreeObjectNode;
-export function getOrCreateInnerNode(treeNode: TreeArrayNode, allowFreed?: true): InnerNode;
-export function getOrCreateInnerNode(
-	treeNode: TreeMapNode,
-	allowFreed?: true,
-): InnerNode &
-	FlexTreeMapNode<FlexMapNodeSchema<string, FlexFieldSchema<typeof FieldKinds.optional>>>;
-export function getOrCreateInnerNode(treeNode: TreeNode, allowFreed?: true): InnerNode;
 export function getOrCreateInnerNode(treeNode: TreeNode, allowFreed = false): InnerNode {
-	const anchorNode = proxyToAnchorNode.get(treeNode);
-	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.checkout.forest.allocateCursor("getFlexNode");
-		context.checkout.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(treeNode)?.();
-		if (!allowFreed) {
-			assertFlexTreeEntityNotFreed(newFlexNode);
-		}
-		return newFlexNode;
-	}
-
-	// Unhydrated case
-	return proxyToMapTreeNode.get(treeNode) ?? fail("Expected raw tree node for proxy");
-}
-
-/**
- * For "cooked" nodes this is a FlexTreeNode thats a projection of forest content.
- * For {@link Unhydrated} nodes this is a MapTreeNode.
- * For "marinated" nodes, some code (ex: getOrCreateInnerNode) returns the FlexTreeNode thats a projection of forest content, and some code (ex: tryGetInnerNode) returns undefined.
- *
- * @remarks
- * Currently MapTreeNode extends FlexTreeNode, and most code which can work with either just uses FlexTreeNode.
- * TODO: Code should be migrating toward using this type to distinguish to two use-cases.
- *
- * TODO: The inconsistent handling of "marinated" cases should be cleaned up.
- * Maybe getOrCreateInnerNode should cook marinated nodes so they have a proper InnerNode?
- */
-export type InnerNode = FlexTreeNode | MapTreeNode;
-
-/**
- * Retrieves the InnerNode associated with the given target via {@link setInnerNode}, if any.
- * @remarks
- * If `target` is a unhydrated node, returns its MapTreeNode.
- * If `target` is a cooked node (or marinated but a FlexTreeNode exists) returns the FlexTreeNode.
- * If the target is not a node, or a marinated node with no FlexTreeNode for its anchor, returns undefined.
- */
-export function tryGetInnerNode(target: unknown): InnerNode | 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.
-	const anchorNode = proxyToAnchorNode.get(target as TreeNode);
-	// Hydrated node case
-	if (anchorNode !== undefined) {
-		const flex = anchorNode.slots.get(flexTreeSlot);
-		if (flex !== undefined) {
-			// Cooked, or possible Marinated but something else cased the flex tree node to exist.
-			return flex;
-		}
-		// Marinated case
-		assert(
-			proxyToMapTreeNode.get(target as TreeNode) === undefined,
-			0xa05 /* marinated nodes should not have MapTreeNodes */,
-		);
-		return undefined;
-	}
-	// Unhydrated node or not a node case:
-	return proxyToMapTreeNode.get(target as TreeNode);
-}
-
-/**
- * Retrieves the proxy associated with the given flex node via {@link setInnerNode}, if any.
- */
-export function tryGetCachedTreeNode(flexNode: InnerNode): TreeNode | undefined {
-	if (isMapTreeNode(flexNode)) {
-		// Unhydrated case
-		return mapTreeNodeToProxy.get(flexNode);
-	}
-	// Hydrated case
-	return flexNode.anchorNode.slots.get(proxySlot);
-}
-
-/**
- * Associate the given TreeNode and the given flex node.
- * @returns The node.
- * @remarks
- * This creates a 1:1 mapping between the tree node and InnerNode.
- * Either can be retrieved from the other via {@link getOrCreateInnerNode}/{@link tryGetInnerNode} or {@link tryGetCachedTreeNode}.
- * 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 setInnerNode<TNode extends TreeNode>(
-	node: TNode,
-	innerNode: InnerNode,
-): TNode {
-	const existingFlexNode = proxyToAnchorNode.get(node)?.slots.get(flexTreeSlot);
-	assert(
-		existingFlexNode === undefined,
-		0x91d /* Cannot associate a flex node with multiple targets */,
-	);
-	if (isMapTreeNode(innerNode)) {
-		// Unhydrated case
-		proxyToMapTreeNode.set(node, innerNode);
-		mapTreeNodeToProxy.set(innerNode, node);
-	} else {
-		// Hydrated case
-		assert(
-			tryGetCachedTreeNode(innerNode) === undefined,
-			0x7f5 /* Cannot associate an flex node with multiple targets */,
-		);
-		bindHydratedNodeToAnchor(node, innerNode.anchorNode);
-	}
-	return node;
-}
-
-/**
- * Bi-directionally associates the given hydrated TreeNode to the given anchor node.
- * @remarks Cleans up mappings to {@link MapTreeNode} - it is assumed that they are no longer needed once the proxy has an anchor node.
- */
-function bindHydratedNodeToAnchor(node: TreeNode, anchorNode: AnchorNode): void {
-	// If the proxy currently has a raw node, forget it
-	const mapTreeNode = proxyToMapTreeNode.get(node);
-	if (mapTreeNode !== undefined) {
-		proxyToMapTreeNode.delete(node);
-		mapTreeNodeToProxy.delete(mapTreeNode);
-	}
-	// Once a proxy has been associated with an anchor node, it should never change to another anchor node
-	assert(
-		!proxyToAnchorNode.has(node),
-		0x91e /* Proxy has already been bound to a different anchor node */,
-	);
-	proxyToAnchorNode.set(node, 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, node);
-	getKernel(node).hydrate(anchorNode);
-}
-
-/**
- * Given a node's schema, return the corresponding object in the proxy-based API.
- */
-type TypedNode<TSchema extends FlexTreeNodeSchema> = TreeNode & WithType<TSchema["name"]>;
-
-export function tryDisposeTreeNode(anchorNode: AnchorNode): void {
-	const treeNode = anchorNode.slots.get(proxySlot);
-	if (treeNode !== undefined) {
-		const kernel = getKernel(treeNode);
-		kernel.dispose();
-	}
+	const kernel = getKernel(treeNode);
+	return kernel.getOrCreateInnerNode(allowFreed);
 }

package/src/simple-tree/schemaTypes.ts

@@ -21,7 +21,7 @@ import type {
 	TreeNodeSchemaClass,
 } from "./core/index.js";
 import type { FieldKey } from "../core/index.js";
-import type { InsertableContent } from "./proxies.js";
+import type { InsertableContent } from "./toMapTree.js";
 
 /**
  * Returns true if the given schema is a {@link TreeNodeSchemaClass}, or otherwise false if it is a {@link TreeNodeSchemaNonClass}.
@@ -76,15 +76,15 @@ export enum FieldKind {
 }
 
 /**
- * Maps from a view key to its corresponding {@link FieldProps.key | stored key} for the provided
+ * Maps from a property key to its corresponding {@link FieldProps.key | stored key} for the provided
  * {@link ImplicitFieldSchema | field schema}.
  *
  * @remarks
  * If an explicit stored key was specified in the schema, it will be used.
- * Otherwise, the stored key is the same as the view key.
+ * Otherwise, the stored key is the same as the property key.
  */
-export function getStoredKey(viewKey: string, fieldSchema: ImplicitFieldSchema): FieldKey {
-	return brand(getExplicitStoredKey(fieldSchema) ?? viewKey);
+export function getStoredKey(propertyKey: string, fieldSchema: ImplicitFieldSchema): FieldKey {
+	return brand(getExplicitStoredKey(fieldSchema) ?? propertyKey);
 }
 
 /**
@@ -98,9 +98,12 @@ export function getExplicitStoredKey(fieldSchema: ImplicitFieldSchema): string |
 /**
  * Additional information to provide to a {@link FieldSchema}.
  *
+ * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.
+ * See {@link FieldSchemaMetadata.custom}.
+ *
  * @public
  */
-export interface FieldProps {
+export interface FieldProps<TCustomMetadata = unknown> {
 	/**
 	 * The unique identifier of a field, used in the persisted form of the tree.
 	 *
@@ -152,12 +155,19 @@ export interface FieldProps {
 	 * @defaultValue If not specified, the key that is persisted is the property key that was specified in the schema.
 	 */
 	readonly key?: string;
+
 	/**
 	 * A default provider used for fields which were not provided any values.
 	 * @privateRemarks
 	 * We are using an erased type here, as we want to expose this API but `InsertableContent` and `NodeKeyManager` are not public.
 	 */
 	readonly defaultProvider?: DefaultProvider;
+
+	/**
+	 * Optional metadata to associate with the field.
+	 * @remarks Note: this metadata is not persisted in the document.
+	 */
+	readonly metadata?: FieldSchemaMetadata<TCustomMetadata>;
 }
 
 /**
@@ -187,7 +197,7 @@ export function isConstant(
  * Provides a default value for a field.
  * @remarks
  * If present in a `FieldSchema`, when constructing new tree content that field can be omitted, and a default will be provided.
- * @sealed @public
+ * @system @sealed @public
  */
 export interface DefaultProvider extends ErasedType<"@fluidframework/tree.FieldProvider"> {}
 
@@ -199,17 +209,44 @@ export function getDefaultProvider(input: FieldProvider): DefaultProvider {
 	return input as unknown as DefaultProvider;
 }
 
+/**
+ * Metadata associated with a {@link FieldSchema}.
+ *
+ * @remarks Specified via {@link FieldProps.metadata}.
+ *
+ * @sealed
+ * @public
+ */
+export interface FieldSchemaMetadata<TCustomMetadata = unknown> {
+	/**
+	 * User-defined metadata.
+	 */
+	custom?: TCustomMetadata;
+
+	/**
+	 * The description of the field.
+	 *
+	 * @remarks
+	 *
+	 * If provided, will be used by the system in scenarios where a description of the field is useful.
+	 * E.g., when converting a field schema to {@link https://json-schema.org/ | JSON Schema}, this description will be
+	 * used as the `description` field.
+	 */
+	description?: string | undefined;
+}
+
 /**
  * Package internal construction API.
  */
 export let createFieldSchema: <
 	Kind extends FieldKind = FieldKind,
 	Types extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+	TCustomMetadata = unknown,
 >(
 	kind: Kind,
 	allowedTypes: Types,
-	props?: FieldProps,
-) => FieldSchema<Kind, Types>;
+	props?: FieldProps<TCustomMetadata>,
+) => FieldSchema<Kind, Types, TCustomMetadata>;
 
 /**
  * All policy for a specific field,
@@ -220,20 +257,26 @@ export let createFieldSchema: <
  * @privateRemarks
  * Public access to the constructor is removed to prevent creating expressible but unsupported (or not stable) configurations.
  * {@link createFieldSchema} can be used internally to create instances.
+ *
+ * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.
+ * See {@link FieldSchemaMetadata.custom}.
+ *
  * @sealed @public
  */
 export class FieldSchema<
 	out Kind extends FieldKind = FieldKind,
 	out Types extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+	out TCustomMetadata = unknown,
 > {
 	static {
 		createFieldSchema = <
 			Kind2 extends FieldKind = FieldKind,
 			Types2 extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+			TCustomMetadata2 = unknown,
 		>(
 			kind: Kind2,
 			allowedTypes: Types2,
-			props?: FieldProps,
+			props?: FieldProps<TCustomMetadata2>,
 		) => new FieldSchema(kind, allowedTypes, props);
 	}
 	/**
@@ -257,6 +300,13 @@ export class FieldSchema<
 	 */
 	public readonly requiresValue: boolean;
 
+	/**
+	 * {@inheritDoc FieldProps.metadata}
+	 */
+	public get metadata(): FieldSchemaMetadata<TCustomMetadata> | undefined {
+		return this.props?.metadata;
+	}
+
 	private constructor(
 		/**
 		 * The {@link https://en.wikipedia.org/wiki/Kind_(type_theory) | kind } of this field.
@@ -270,7 +320,7 @@ export class FieldSchema<
 		/**
 		 * Optional properties associated with the field.
 		 */
-		public readonly props?: FieldProps,
+		public readonly props?: FieldProps<TCustomMetadata>,
 	) {
 		this.lazyTypes = new Lazy(() => normalizeAllowedTypes(this.allowedTypes));
 		// TODO: optional fields should (by default) get a default provider that returns undefined, removing the need to special case them here:
@@ -360,7 +410,7 @@ export type InsertableTreeFieldFromImplicitField<
 /**
  * Suitable for output.
  * For input must error on side of excluding undefined instead.
- * @public
+ * @system @public
  */
 export type ApplyKind<T, Kind extends FieldKind, DefaultsAreOptional extends boolean> = {
 	[FieldKind.Required]: T;
@@ -420,7 +470,7 @@ export type InsertableTypedNode<T extends TreeNodeSchema> =
  * This could be changed if needed.
  *
  * These factory functions can also take a FlexTreeNode, but this is not exposed in the public facing types.
- * @public
+ * @system @public
  */
 export type NodeBuilderData<T extends TreeNodeSchema> = T extends TreeNodeSchema<
 	string,

package/src/simple-tree/toFlexSchema.ts

@@ -3,11 +3,15 @@
  * Licensed under the MIT License.
  */
 
-/* eslint-disable import/no-internal-modules */
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { EmptyKey, type TreeNodeSchemaIdentifier } from "../core/index.js";
+import {
+	EmptyKey,
+	type TreeNodeSchemaIdentifier,
+	type TreeNodeStoredSchema,
+	type TreeStoredSchema,
+} from "../core/index.js";
 import {
 	FieldKinds,
 	type FlexAllowedTypes,
@@ -19,9 +23,12 @@ import {
 	type FlexTreeSchema,
 	TreeNodeSchemaBase,
 	defaultSchemaPolicy,
+	intoStoredSchemaCollection,
 	schemaIsLeaf,
 } from "../feature-libraries/index.js";
-import { normalizeFlexListEager } from "../feature-libraries/typed-schema/flexList.js";
+// TODO: once flex schema is gone, this code can move into simple-tree
+// eslint-disable-next-line import/no-internal-modules
+import { normalizeFlexListEager } from "../feature-libraries/typed-schema/index.js";
 import { brand, fail, isReadonlyArray, mapIterable } from "../util/index.js";
 import {
 	cachedFlexSchemaFromClassSchema,
@@ -78,6 +85,17 @@ export function toFlexSchema(root: ImplicitFieldSchema): FlexTreeSchema {
 	return typed;
 }
 
+/**
+ * Converts a {@link ImplicitFieldSchema} into a {@link TreeStoredSchema}.
+ */
+export function toStoredSchema(root: ImplicitFieldSchema): TreeStoredSchema {
+	const flex = toFlexSchema(root);
+	return {
+		rootFieldSchema: flex.rootFieldSchema.stored,
+		...intoStoredSchemaCollection(flex),
+	};
+}
+
 /**
  * Return a flex schema for the provided class schema.
  *
@@ -88,6 +106,15 @@ export function getFlexSchema(root: TreeNodeSchema): FlexTreeNodeSchema {
 	return treeSchema.rootFieldSchema.monomorphicChildType ?? fail("root should be monomorphic");
 }
 
+/**
+ * Return a stored schema for the provided class schema.
+ *
+ * This also has the side effect of populating the cached view schema on the class based schema.
+ */
+export function getStoredSchema(root: TreeNodeSchema): TreeNodeStoredSchema {
+	return getFlexSchema(root).stored;
+}
+
 /**
  * Normalizes an {@link ImplicitFieldSchema} into a {@link TreeFieldSchema}.
  */
@@ -172,7 +199,13 @@ export function convertNodeSchema(
 				);
 				// Lookup of cached schema is done here instead of before since walking the schema recursively to populate schemaMap is still required.
 				const cached = cachedFlexSchemaFromClassSchema(schema);
-				out = cached ?? FlexMapNodeSchema.create(builder, brand(schema.identifier), field);
+				out =
+					cached ??
+					FlexMapNodeSchema.create(
+						builder,
+						brand<TreeNodeSchemaIdentifier>(schema.identifier),
+						field,
+					);
 				break;
 			}
 			case NodeKind.Array: {
@@ -192,10 +225,10 @@ export function convertNodeSchema(
 			case NodeKind.Object: {
 				const info = schema.info as Record<string, ImplicitFieldSchema>;
 				const fields: Record<string, FlexFieldSchema> = Object.create(null);
-				for (const [viewKey, implicitFieldSchema] of Object.entries(info)) {
+				for (const [propertyKey, implicitFieldSchema] of Object.entries(info)) {
 					// If a `stored key` was provided, use it as the key in the flex schema.
-					// Otherwise, use the view key.
-					const flexKey = getStoredKey(viewKey, implicitFieldSchema);
+					// Otherwise, use the property key.
+					const flexKey = getStoredKey(propertyKey, implicitFieldSchema);
 
 					// This code has to be careful to avoid assigning to __proto__ or similar built-in fields.
 					Object.defineProperty(fields, flexKey, {