@fluidframework/tree 2.1.0 → 2.2.0

package/lib/simple-tree/proxyBinding.d.ts

@@ -3,50 +3,73 @@
  * Licensed under the MIT License.
  */
 import { type AnchorNode, type AnchorSet, type UpPath } from "../core/index.js";
-import { type FlexTreeNodeSchema, type FlexMapNodeSchema, type FlexObjectNodeSchema, type FlexTreeMapNode, type FlexTreeNode, type FlexTreeObjectNode, type FieldKinds, type FlexFieldSchema } from "../feature-libraries/index.js";
-import type { WithType } from "./schemaTypes.js";
+import { type FlexTreeNodeSchema, type FlexMapNodeSchema, type FlexObjectNodeSchema, type FlexTreeMapNode, type FlexTreeNode, type FlexTreeObjectNode, type FieldKinds, type FlexFieldSchema, type MapTreeNode } from "../feature-libraries/index.js";
+import type { WithType, TreeNode } from "./core/index.js";
 import type { TreeArrayNode } from "./arrayNode.js";
-import type { TreeNode } from "./types.js";
 import type { TreeMapNode } from "./mapNode.js";
-import { TreeNodeKernel } from "./treeNodeKernel.js";
 /**
  * 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.
+ * @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 declare function anchorProxy(anchors: AnchorSet, path: UpPath, proxy: TreeNode): AnchorNode;
 /**
- * Retrieves the flex node associated with the given target via {@link setFlexNode}.
- * @remarks Fails if the flex node has not been set.
+ * Retrieves the flex node associated with the given target via {@link setInnerNode}.
+ * @remarks
+ * For {@link Unhydrated} nodes, this returns the MapTreeNode.
+ *
+ * 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 declare function getFlexNode(proxy: TypedNode<FlexObjectNodeSchema>, allowFreed?: true): FlexTreeObjectNode;
-export declare function getFlexNode(proxy: TreeArrayNode, allowFreed?: true): FlexTreeNode;
-export declare function getFlexNode(proxy: TreeMapNode, allowFreed?: true): FlexTreeMapNode<FlexMapNodeSchema<string, FlexFieldSchema<typeof FieldKinds.optional>>>;
-export declare function getFlexNode(proxy: TreeNode, allowFreed?: true): FlexTreeNode;
+export declare function getOrCreateInnerNode(treeNode: TypedNode<FlexObjectNodeSchema>, allowFreed?: true): InnerNode & FlexTreeObjectNode;
+export declare function getOrCreateInnerNode(treeNode: TreeArrayNode, allowFreed?: true): InnerNode;
+export declare function getOrCreateInnerNode(treeNode: TreeMapNode, allowFreed?: true): InnerNode & FlexTreeMapNode<FlexMapNodeSchema<string, FlexFieldSchema<typeof FieldKinds.optional>>>;
+export declare function getOrCreateInnerNode(treeNode: TreeNode, allowFreed?: true): InnerNode;
 /**
- * Retrieves the flex node associated with the given target via {@link setFlexNode}, if any.
+ * 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 declare function tryGetFlexNode(target: unknown): FlexTreeNode | undefined;
+export declare function tryGetInnerNode(target: unknown): InnerNode | undefined;
 /**
- * Retrieves the proxy associated with the given flex node via {@link setFlexNode}, if any.
+ * Retrieves the proxy associated with the given flex node via {@link setInnerNode}, if any.
  */
-export declare function tryGetProxy(flexNode: FlexTreeNode): TreeNode | undefined;
+export declare function tryGetCachedTreeNode(flexNode: InnerNode): TreeNode | undefined;
 /**
- * Associate the given proxy and the given flex node.
- * @returns The proxy
+ * Associate the given TreeNode and the given flex node.
+ * @returns The node.
  * @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}.
+ * 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 declare function setFlexNode<TProxy extends TreeNode>(proxy: TProxy, flexNode: FlexTreeNode): TProxy;
+export declare function setInnerNode<TNode extends TreeNode>(node: TNode, innerNode: InnerNode): TNode;
 /**
  * Given a node's schema, return the corresponding object in the proxy-based API.
  */
 type TypedNode<TSchema extends FlexTreeNodeSchema> = TreeNode & WithType<TSchema["name"]>;
-export declare function createKernel(node: TreeNode): void;
-export declare function getKernel(node: TreeNode): TreeNodeKernel;
 export declare function tryDisposeTreeNode(anchorNode: AnchorNode): void;
 export {};
 //# sourceMappingURL=proxyBinding.d.ts.map

package/lib/simple-tree/proxyBinding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxyBinding.d.ts","sourceRoot":"","sources":["../../src/simple-tree/proxyBinding.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,MAAM,EAAc,MAAM,kBAAkB,CAAC;AAC5F,OAAO,EAEN,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EAGvB,KAAK,UAAU,EACf,KAAK,eAAe,EAGpB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAyBrD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,UAAU,CAezF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAC1B,KAAK,EAAE,SAAS,CAAC,oBAAoB,CAAC,EACtC,UAAU,CAAC,EAAE,IAAI,GACf,kBAAkB,CAAC;AACtB,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,EAAE,UAAU,CAAC,EAAE,IAAI,GAAG,YAAY,CAAC;AACnF,wBAAgB,WAAW,CAC1B,KAAK,EAAE,WAAW,EAClB,UAAU,CAAC,EAAE,IAAI,GACf,eAAe,CAAC,iBAAiB,CAAC,MAAM,EAAE,eAAe,CAAC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAC3F,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,CAAC,EAAE,IAAI,GAAG,YAAY,CAAC;AAyB9E;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAOxE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,SAAS,CAKxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,SAAS,QAAQ,EAClD,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,YAAY,GACpB,MAAM,CAiBR;AAwBD;;GAEG;AACH,KAAK,SAAS,CAAC,OAAO,SAAS,kBAAkB,IAAI,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAE1F,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,cAAc,CAIxD;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAO/D"}
+{"version":3,"file":"proxyBinding.d.ts","sourceRoot":"","sources":["../../src/simple-tree/proxyBinding.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,MAAM,EAAc,MAAM,kBAAkB,CAAC;AAC5F,OAAO,EAEN,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EAGvB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,WAAW,EAEhB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAgDhD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,UAAU,CAezF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CACnC,QAAQ,EAAE,SAAS,CAAC,oBAAoB,CAAC,EACzC,UAAU,CAAC,EAAE,IAAI,GACf,SAAS,GAAG,kBAAkB,CAAC;AAClC,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,aAAa,EAAE,UAAU,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;AAC5F,wBAAgB,oBAAoB,CACnC,QAAQ,EAAE,WAAW,EACrB,UAAU,CAAC,EAAE,IAAI,GACf,SAAS,GACX,eAAe,CAAC,iBAAiB,CAAC,MAAM,EAAE,eAAe,CAAC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AACzF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;AA0BvF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,WAAW,CAAC;AAEnD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAoBtE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAO9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,SAAS,QAAQ,EAClD,IAAI,EAAE,KAAK,EACX,SAAS,EAAE,SAAS,GAClB,KAAK,CAmBP;AAwBD;;GAEG;AACH,KAAK,SAAS,CAAC,OAAO,SAAS,kBAAkB,IAAI,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAE1F,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAM/D"}

package/lib/simple-tree/proxyBinding.js

@@ -9,35 +9,61 @@ import { fail } from "../util/index.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 { TreeNodeKernel } from "./treeNodeKernel.js";
-// This file contains various maps and helpers for supporting proxy binding (a.k.a. proxy hydration).
+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 node proxy, if there is one.
+ * 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();
-// The following records are maintained as WeakMaps, rather than a private symbol (e.g. like `targetSymbol`) on the node proxy itself.
+// 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. */
+/**
+ * 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();
-// Map unhydrated nodes to and from their underlying flex tree implementation.
-// These maps are populated after a user calls `const proxy = new Foo({})` but before `proxy` is inserted into the tree and queried.
+/**
+ * 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();
+/**
+ * {@inheritdoc proxyToMapTreeNode}
+ */
 const mapTreeNodeToProxy = new WeakMap();
-/** Used by `anchorProxy` as an optimization to ensure that only one anchor is remembered at a time for a given anchor node */
+/**
+ * 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();
 /**
  * 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.
+ * @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, path, proxy) {
     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);
+    bindHydratedNodeToAnchor(proxy, anchorNode);
     const forget = () => {
         if (anchors.locate(anchor)) {
             anchors.forget(anchor);
@@ -49,8 +75,8 @@ export function anchorProxy(anchors, path, proxy) {
     const off = anchorNode.on("afterDestroy", forget);
     return anchorNode;
 }
-export function getFlexNode(proxy, allowFreed = false) {
-    const anchorNode = proxyToAnchorNode.get(proxy);
+export function getOrCreateInnerNode(treeNode, allowFreed = false) {
+    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);
@@ -63,87 +89,98 @@ export function getFlexNode(proxy, allowFreed = false) {
         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)?.();
+        anchorForgetters?.get(treeNode)?.();
         if (!allowFreed) {
             assertFlexTreeEntityNotFreed(newFlexNode);
         }
         return newFlexNode;
     }
-    return proxyToMapTreeNode.get(proxy) ?? fail("Expected raw tree node for proxy");
+    // Unhydrated case
+    return proxyToMapTreeNode.get(treeNode) ?? fail("Expected raw tree node for proxy");
 }
 /**
- * Retrieves the flex node associated with the given target via {@link setFlexNode}, if any.
+ * 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 tryGetFlexNode(target) {
+export function tryGetInnerNode(target) {
     // 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)?.slots.get(flexTreeSlot) ??
-        proxyToMapTreeNode.get(target));
+    const anchorNode = proxyToAnchorNode.get(target);
+    // 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) === undefined, 0xa05 /* marinated nodes should not have MapTreeNodes */);
+        return undefined;
+    }
+    // Unhydrated node or not a node case:
+    return proxyToMapTreeNode.get(target);
 }
 /**
- * Retrieves the proxy associated with the given flex node via {@link setFlexNode}, if any.
+ * Retrieves the proxy associated with the given flex node via {@link setInnerNode}, if any.
  */
-export function tryGetProxy(flexNode) {
+export function tryGetCachedTreeNode(flexNode) {
     if (isMapTreeNode(flexNode)) {
+        // Unhydrated case
         return mapTreeNodeToProxy.get(flexNode);
     }
+    // Hydrated case
     return flexNode.anchorNode.slots.get(proxySlot);
 }
 /**
- * Associate the given proxy and the given flex node.
- * @returns The proxy
+ * Associate the given TreeNode and the given flex node.
+ * @returns The node.
  * @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}.
+ * 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 setFlexNode(proxy, flexNode) {
-    const existingFlexNode = proxyToAnchorNode.get(proxy)?.slots.get(flexTreeSlot);
+export function setInnerNode(node, innerNode) {
+    const existingFlexNode = proxyToAnchorNode.get(node)?.slots.get(flexTreeSlot);
     assert(existingFlexNode === undefined, 0x91d /* Cannot associate a flex node with multiple targets */);
-    if (isMapTreeNode(flexNode)) {
-        proxyToMapTreeNode.set(proxy, flexNode);
-        mapTreeNodeToProxy.set(flexNode, proxy);
+    if (isMapTreeNode(innerNode)) {
+        // Unhydrated case
+        proxyToMapTreeNode.set(node, innerNode);
+        mapTreeNodeToProxy.set(innerNode, node);
     }
     else {
-        assert(tryGetProxy(flexNode) === undefined, 0x7f5 /* Cannot associate an flex node with multiple targets */);
-        bindProxyToAnchorNode(proxy, flexNode.anchorNode);
+        // Hydrated case
+        assert(tryGetCachedTreeNode(innerNode) === undefined, 0x7f5 /* Cannot associate an flex node with multiple targets */);
+        bindHydratedNodeToAnchor(node, innerNode.anchorNode);
     }
-    return proxy;
+    return node;
 }
 /**
- * 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.
+ * 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 bindProxyToAnchorNode(proxy, anchorNode) {
+function bindHydratedNodeToAnchor(node, anchorNode) {
     // If the proxy currently has a raw node, forget it
-    const mapTreeNode = proxyToMapTreeNode.get(proxy);
+    const mapTreeNode = proxyToMapTreeNode.get(node);
     if (mapTreeNode !== undefined) {
-        proxyToMapTreeNode.delete(proxy);
+        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(proxy), 0x91e /* Proxy has already been bound to a different anchor node */);
-    proxyToAnchorNode.set(proxy, anchorNode);
+    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, proxy);
-    getKernel(proxy).hydrate(anchorNode);
-}
-export function createKernel(node) {
-    treeNodeToKernel.set(node, new TreeNodeKernel(node));
-}
-export function getKernel(node) {
-    const kernel = treeNodeToKernel.get(node);
-    assert(kernel !== undefined, 0x9b1 /* Expected tree node to have kernel */);
-    return kernel;
+    anchorNode.slots.set(proxySlot, node);
+    getKernel(node).hydrate(anchorNode);
 }
 export function tryDisposeTreeNode(anchorNode) {
     const treeNode = anchorNode.slots.get(proxySlot);
     if (treeNode !== undefined) {
-        const kernel = treeNodeToKernel.get(treeNode);
-        assert(kernel !== undefined, 0x9b2 /* Expected tree node to have kernel */);
+        const kernel = getKernel(treeNode);
         kernel.dispose();
     }
 }
-const treeNodeToKernel = new WeakMap();
 //# sourceMappingURL=proxyBinding.js.map

package/lib/simple-tree/proxyBinding.js.map

@@ -1 +1 @@
-{"version":3,"file":"proxyBinding.js","sourceRoot":"","sources":["../../src/simple-tree/proxyBinding.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport { type AnchorNode, type AnchorSet, type UpPath, anchorSlot } from \"../core/index.js\";\nimport {\n\tContextSlot,\n\ttype FlexTreeNodeSchema,\n\ttype FlexMapNodeSchema,\n\ttype FlexObjectNodeSchema,\n\ttype FlexTreeMapNode,\n\ttype FlexTreeNode,\n\ttype FlexTreeObjectNode,\n\tassertFlexTreeEntityNotFreed,\n\tflexTreeSlot,\n\ttype FieldKinds,\n\ttype FlexFieldSchema,\n\ttype MapTreeNode,\n\tisMapTreeNode,\n} from \"../feature-libraries/index.js\";\nimport { fail } from \"../util/index.js\";\nimport type { WithType } from \"./schemaTypes.js\";\nimport type { TreeArrayNode } from \"./arrayNode.js\";\nimport type { TreeNode } from \"./types.js\";\n// TODO: decide how to deal with dependencies on flex-tree implementation.\n// eslint-disable-next-line import/no-internal-modules\nimport { makeTree } from \"../feature-libraries/flex-tree/lazyNode.js\";\nimport type { TreeMapNode } from \"./mapNode.js\";\nimport { TreeNodeKernel } from \"./treeNodeKernel.js\";\n\n// This file contains various maps and helpers for supporting proxy binding (a.k.a. proxy hydration).\n// See ./ProxyBinding.md for a high-level overview of the process.\n\n/**\n * An anchor slot which associates an anchor with its corresponding node proxy, if there is one.\n */\nconst proxySlot = anchorSlot<TreeNode>();\n\n// The following records are maintained as WeakMaps, rather than a private symbol (e.g. like `targetSymbol`) on the node proxy itself.\n// 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).\n// Since `SharedTreeNodes` are proxies with non-trivial `get` traps, this choice is meant to prevent the confusion of the lookup passing through multiple objects\n// via the trap, or the trap not properly handling the special symbol, etc.\n\n/** A reverse mapping of {@link proxySlot} that is updated at the same time. */\nconst proxyToAnchorNode = new WeakMap<TreeNode, AnchorNode>();\n\n// Map unhydrated nodes to and from their underlying flex tree implementation.\n// These maps are populated after a user calls `const proxy = new Foo({})` but before `proxy` is inserted into the tree and queried.\nconst proxyToMapTreeNode = new WeakMap<TreeNode, MapTreeNode>();\nconst mapTreeNodeToProxy = new WeakMap<MapTreeNode, TreeNode>();\n/** Used by `anchorProxy` as an optimization to ensure that only one anchor is remembered at a time for a given anchor node */\nconst anchorForgetters = new WeakMap<TreeNode, () => void>();\n\n/**\n * Creates an anchor node and associates it with the given proxy.\n * @privateRemarks Use `forgetters` to cleanup the anchor allocated by this function once the anchor is no longer needed.\n * 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.\n */\nexport function anchorProxy(anchors: AnchorSet, path: UpPath, proxy: TreeNode): AnchorNode {\n\tassert(!anchorForgetters.has(proxy), 0x91c /* Proxy anchor should not be set twice */);\n\tconst anchor = anchors.track(path);\n\tconst anchorNode = anchors.locate(anchor) ?? fail(\"Expected anchor node to be present\");\n\tbindProxyToAnchorNode(proxy, anchorNode);\n\tconst forget = (): void => {\n\t\tif (anchors.locate(anchor)) {\n\t\t\tanchors.forget(anchor);\n\t\t}\n\t\tanchorForgetters.delete(proxy);\n\t\toff();\n\t};\n\tanchorForgetters.set(proxy, forget);\n\tconst off = anchorNode.on(\"afterDestroy\", forget);\n\treturn anchorNode;\n}\n\n/**\n * Retrieves the flex node associated with the given target via {@link setFlexNode}.\n * @remarks Fails if the flex node has not been set.\n */\nexport function getFlexNode(\n\tproxy: TypedNode<FlexObjectNodeSchema>,\n\tallowFreed?: true,\n): FlexTreeObjectNode;\nexport function getFlexNode(proxy: TreeArrayNode, allowFreed?: true): FlexTreeNode;\nexport function getFlexNode(\n\tproxy: TreeMapNode,\n\tallowFreed?: true,\n): FlexTreeMapNode<FlexMapNodeSchema<string, FlexFieldSchema<typeof FieldKinds.optional>>>;\nexport function getFlexNode(proxy: TreeNode, allowFreed?: true): FlexTreeNode;\nexport function getFlexNode(proxy: TreeNode, allowFreed = false): FlexTreeNode {\n\tconst anchorNode = proxyToAnchorNode.get(proxy);\n\tif (anchorNode !== undefined) {\n\t\t// The proxy is bound to an anchor node, but it may or may not have an actual flex node yet\n\t\tconst flexNode = anchorNode.slots.get(flexTreeSlot);\n\t\tif (flexNode !== undefined) {\n\t\t\treturn flexNode; // If it does have a flex node, return it...\n\t\t} // ...otherwise, the flex node must be created\n\t\tconst context = anchorNode.anchorSet.slots.get(ContextSlot) ?? fail(\"missing context\");\n\t\tconst cursor = context.checkout.forest.allocateCursor(\"getFlexNode\");\n\t\tcontext.checkout.forest.moveCursorToPath(anchorNode, cursor);\n\t\tconst newFlexNode = makeTree(context, cursor);\n\t\tcursor.free();\n\t\t// Calling this is a performance improvement, however, do this only after demand to avoid momentarily having no anchors to anchorNode\n\t\tanchorForgetters?.get(proxy)?.();\n\t\tif (!allowFreed) {\n\t\t\tassertFlexTreeEntityNotFreed(newFlexNode);\n\t\t}\n\t\treturn newFlexNode;\n\t}\n\n\treturn proxyToMapTreeNode.get(proxy) ?? fail(\"Expected raw tree node for proxy\");\n}\n\n/**\n * Retrieves the flex node associated with the given target via {@link setFlexNode}, if any.\n */\nexport function tryGetFlexNode(target: unknown): FlexTreeNode | undefined {\n\t// Calling 'WeakMap.get()' with primitives (numbers, strings, etc.) will return undefined.\n\t// This is in contrast to 'WeakMap.set()', which will throw a TypeError if given a non-object key.\n\treturn (\n\t\tproxyToAnchorNode.get(target as TreeNode)?.slots.get(flexTreeSlot) ??\n\t\tproxyToMapTreeNode.get(target as TreeNode)\n\t);\n}\n\n/**\n * Retrieves the proxy associated with the given flex node via {@link setFlexNode}, if any.\n */\nexport function tryGetProxy(flexNode: FlexTreeNode): TreeNode | undefined {\n\tif (isMapTreeNode(flexNode)) {\n\t\treturn mapTreeNodeToProxy.get(flexNode);\n\t}\n\treturn flexNode.anchorNode.slots.get(proxySlot);\n}\n\n/**\n * Associate the given proxy and the given flex node.\n * @returns The proxy\n * @remarks\n * This creates a 1:1 mapping between the proxy and tree node.\n * Either can be retrieved from the other via {@link getFlexNode}/{@link tryGetFlexNode} or {@link tryGetProxy}.\n * If the given proxy is already mapped to an flex node, the existing mapping will be overwritten.\n * If the given flex node is already mapped to a different proxy, this function will fail.\n */\nexport function setFlexNode<TProxy extends TreeNode>(\n\tproxy: TProxy,\n\tflexNode: FlexTreeNode,\n): TProxy {\n\tconst existingFlexNode = proxyToAnchorNode.get(proxy)?.slots.get(flexTreeSlot);\n\tassert(\n\t\texistingFlexNode === undefined,\n\t\t0x91d /* Cannot associate a flex node with multiple targets */,\n\t);\n\tif (isMapTreeNode(flexNode)) {\n\t\tproxyToMapTreeNode.set(proxy, flexNode);\n\t\tmapTreeNodeToProxy.set(flexNode, proxy);\n\t} else {\n\t\tassert(\n\t\t\ttryGetProxy(flexNode) === undefined,\n\t\t\t0x7f5 /* Cannot associate an flex node with multiple targets */,\n\t\t);\n\t\tbindProxyToAnchorNode(proxy, flexNode.anchorNode);\n\t}\n\treturn proxy;\n}\n\n/**\n * Bi-directionally associates the given proxy to the given anchor node.\n * @remarks Cleans up mappings to raw flex nodes - it is assumed that they are no longer needed once the proxy has an anchor node.\n */\nfunction bindProxyToAnchorNode(proxy: TreeNode, anchorNode: AnchorNode): void {\n\t// If the proxy currently has a raw node, forget it\n\tconst mapTreeNode = proxyToMapTreeNode.get(proxy);\n\tif (mapTreeNode !== undefined) {\n\t\tproxyToMapTreeNode.delete(proxy);\n\t\tmapTreeNodeToProxy.delete(mapTreeNode);\n\t}\n\t// Once a proxy has been associated with an anchor node, it should never change to another anchor node\n\tassert(\n\t\t!proxyToAnchorNode.has(proxy),\n\t\t0x91e /* Proxy has already been bound to a different anchor node */,\n\t);\n\tproxyToAnchorNode.set(proxy, anchorNode);\n\t// However, it's fine for an anchor node to rotate through different proxies when the content at that place in the tree is replaced.\n\tanchorNode.slots.set(proxySlot, proxy);\n\tgetKernel(proxy).hydrate(anchorNode);\n}\n\n/**\n * Given a node's schema, return the corresponding object in the proxy-based API.\n */\ntype TypedNode<TSchema extends FlexTreeNodeSchema> = TreeNode & WithType<TSchema[\"name\"]>;\n\nexport function createKernel(node: TreeNode): void {\n\ttreeNodeToKernel.set(node, new TreeNodeKernel(node));\n}\n\nexport function getKernel(node: TreeNode): TreeNodeKernel {\n\tconst kernel = treeNodeToKernel.get(node);\n\tassert(kernel !== undefined, 0x9b1 /* Expected tree node to have kernel */);\n\treturn kernel;\n}\n\nexport function tryDisposeTreeNode(anchorNode: AnchorNode): void {\n\tconst treeNode = anchorNode.slots.get(proxySlot);\n\tif (treeNode !== undefined) {\n\t\tconst kernel = treeNodeToKernel.get(treeNode);\n\t\tassert(kernel !== undefined, 0x9b2 /* Expected tree node to have kernel */);\n\t\tkernel.dispose();\n\t}\n}\n\nconst treeNodeToKernel = new WeakMap<TreeNode, TreeNodeKernel>();\n"]}
+{"version":3,"file":"proxyBinding.js","sourceRoot":"","sources":["../../src/simple-tree/proxyBinding.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport { type AnchorNode, type AnchorSet, type UpPath, anchorSlot } from \"../core/index.js\";\nimport {\n\tContextSlot,\n\ttype FlexTreeNodeSchema,\n\ttype FlexMapNodeSchema,\n\ttype FlexObjectNodeSchema,\n\ttype FlexTreeMapNode,\n\ttype FlexTreeNode,\n\ttype FlexTreeObjectNode,\n\tassertFlexTreeEntityNotFreed,\n\tflexTreeSlot,\n\ttype FieldKinds,\n\ttype FlexFieldSchema,\n\ttype MapTreeNode,\n\tisMapTreeNode,\n} from \"../feature-libraries/index.js\";\nimport { fail } from \"../util/index.js\";\nimport type { WithType, TreeNode } from \"./core/index.js\";\nimport type { TreeArrayNode } from \"./arrayNode.js\";\n// TODO: decide how to deal with dependencies on flex-tree implementation.\n// eslint-disable-next-line import/no-internal-modules\nimport { makeTree } from \"../feature-libraries/flex-tree/lazyNode.js\";\nimport type { TreeMapNode } from \"./mapNode.js\";\nimport { getKernel } from \"./core/index.js\";\n\n// This file contains various maps and helpers for supporting associating simple TreeNodes with their InnerNodes, and swapping those InnerNodes as part of hydration.\n// See ./ProxyBinding.md for a high-level overview of the process.\n\n/**\n * An anchor slot which associates an anchor with its corresponding TreeNode, if there is one.\n * @remarks\n * For this to work, we have to require that there is at most a single view using a given AnchorSet.\n * FlexTree already has this assumption, and we also assume there is a single simple-tree per FlexTree, so this is valid.\n */\nconst proxySlot = anchorSlot<TreeNode>();\n\n// The following records are maintained as WeakMaps, rather than a private symbol (e.g. like `targetSymbol`) on the TreeNode.\n// 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).\n// Since `SharedTreeNodes` are proxies with non-trivial `get` traps, this choice is meant to prevent the confusion of the lookup passing through multiple objects\n// via the trap, or the trap not properly handling the special symbol, etc.\n\n/**\n * A reverse mapping of {@link proxySlot} that is updated at the same time.\n *\n * @remarks\n * Nodes in this map are hydrated (and thus \"marinated\" or \"cooked\").\n * Nodes not in this map are known to be {@link Unhydrated}.\n * Thus this map can be used to check if a node is hydrated.\n *\n * Any node not in this map must be in {@link proxyToMapTreeNode} since it contains all unhydrated nodes.\n * It also contains \"marinated\" nodes which are in both.\n */\nconst proxyToAnchorNode = new WeakMap<TreeNode, AnchorNode>();\n\n/**\n * Map {@link Unhydrated} nodes and \"marinated\" nodes to and from their underlying MapTreeNode.\n * These maps are populated by the TreeNode's constructor when called by a user before the node is inserted into the tree and queried.\n */\nconst proxyToMapTreeNode = new WeakMap<TreeNode, MapTreeNode>();\n\n/**\n * {@inheritdoc proxyToMapTreeNode}\n */\nconst mapTreeNodeToProxy = new WeakMap<MapTreeNode, TreeNode>();\n\n/**\n * Used by {@link anchorProxy} as an optimization to ensure that only one anchor is remembered at a time for a given anchor node\n */\nconst anchorForgetters = new WeakMap<TreeNode, () => void>();\n\n/**\n * Creates an anchor node and associates it with the given proxy.\n * @privateRemarks\n * Use `forgetters` to cleanup the anchor allocated by this function once the anchor is no longer needed.\n * 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.\n *\n * The FlexTreeNode holds a reference to the same anchor, and has a lifetime at least as long as the simple-tree,\n * so this would be unnecessary except for the case of \"marinated\" nodes, which have an anchor,\n * but might not have a FlexTreeNode.\n * Handling this case is an optimization assuming that this extra anchor reference is cheaper than eagerly creating FlexTreeNodes.\n */\nexport function anchorProxy(anchors: AnchorSet, path: UpPath, proxy: TreeNode): AnchorNode {\n\tassert(!anchorForgetters.has(proxy), 0x91c /* Proxy anchor should not be set twice */);\n\tconst anchor = anchors.track(path);\n\tconst anchorNode = anchors.locate(anchor) ?? fail(\"Expected anchor node to be present\");\n\tbindHydratedNodeToAnchor(proxy, anchorNode);\n\tconst forget = (): void => {\n\t\tif (anchors.locate(anchor)) {\n\t\t\tanchors.forget(anchor);\n\t\t}\n\t\tanchorForgetters.delete(proxy);\n\t\toff();\n\t};\n\tanchorForgetters.set(proxy, forget);\n\tconst off = anchorNode.on(\"afterDestroy\", forget);\n\treturn anchorNode;\n}\n\n/**\n * Retrieves the flex node associated with the given target via {@link setInnerNode}.\n * @remarks\n * For {@link Unhydrated} nodes, this returns the MapTreeNode.\n *\n * For hydrated nodes it returns a FlexTreeNode backed by the forest.\n * Note that for \"marinated\" nodes, this FlexTreeNode exists and returns it: it does not return the MapTreeNode which is the current InnerNode.\n */\nexport function getOrCreateInnerNode(\n\ttreeNode: TypedNode<FlexObjectNodeSchema>,\n\tallowFreed?: true,\n): InnerNode & FlexTreeObjectNode;\nexport function getOrCreateInnerNode(treeNode: TreeArrayNode, allowFreed?: true): InnerNode;\nexport function getOrCreateInnerNode(\n\ttreeNode: TreeMapNode,\n\tallowFreed?: true,\n): InnerNode &\n\tFlexTreeMapNode<FlexMapNodeSchema<string, FlexFieldSchema<typeof FieldKinds.optional>>>;\nexport function getOrCreateInnerNode(treeNode: TreeNode, allowFreed?: true): InnerNode;\nexport function getOrCreateInnerNode(treeNode: TreeNode, allowFreed = false): InnerNode {\n\tconst anchorNode = proxyToAnchorNode.get(treeNode);\n\tif (anchorNode !== undefined) {\n\t\t// The proxy is bound to an anchor node, but it may or may not have an actual flex node yet\n\t\tconst flexNode = anchorNode.slots.get(flexTreeSlot);\n\t\tif (flexNode !== undefined) {\n\t\t\treturn flexNode; // If it does have a flex node, return it...\n\t\t} // ...otherwise, the flex node must be created\n\t\tconst context = anchorNode.anchorSet.slots.get(ContextSlot) ?? fail(\"missing context\");\n\t\tconst cursor = context.checkout.forest.allocateCursor(\"getFlexNode\");\n\t\tcontext.checkout.forest.moveCursorToPath(anchorNode, cursor);\n\t\tconst newFlexNode = makeTree(context, cursor);\n\t\tcursor.free();\n\t\t// Calling this is a performance improvement, however, do this only after demand to avoid momentarily having no anchors to anchorNode\n\t\tanchorForgetters?.get(treeNode)?.();\n\t\tif (!allowFreed) {\n\t\t\tassertFlexTreeEntityNotFreed(newFlexNode);\n\t\t}\n\t\treturn newFlexNode;\n\t}\n\n\t// Unhydrated case\n\treturn proxyToMapTreeNode.get(treeNode) ?? fail(\"Expected raw tree node for proxy\");\n}\n\n/**\n * For \"cooked\" nodes this is a FlexTreeNode thats a projection of forest content.\n * For {@link Unhydrated} nodes this is a MapTreeNode.\n * For \"marinated\" nodes, some code (ex: getOrCreateInnerNode) returns the FlexTreeNode thats a projection of forest content, and some code (ex: tryGetInnerNode) returns undefined.\n *\n * @remarks\n * Currently MapTreeNode extends FlexTreeNode, and most code which can work with either just uses FlexTreeNode.\n * TODO: Code should be migrating toward using this type to distinguish to two use-cases.\n *\n * TODO: The inconsistent handling of \"marinated\" cases should be cleaned up.\n * Maybe getOrCreateInnerNode should cook marinated nodes so they have a proper InnerNode?\n */\nexport type InnerNode = FlexTreeNode | MapTreeNode;\n\n/**\n * Retrieves the InnerNode associated with the given target via {@link setInnerNode}, if any.\n * @remarks\n * If `target` is a unhydrated node, returns its MapTreeNode.\n * If `target` is a cooked node (or marinated but a FlexTreeNode exists) returns the FlexTreeNode.\n * If the target is not a node, or a marinated node with no FlexTreeNode for its anchor, returns undefined.\n */\nexport function tryGetInnerNode(target: unknown): InnerNode | undefined {\n\t// Calling 'WeakMap.get()' with primitives (numbers, strings, etc.) will return undefined.\n\t// This is in contrast to 'WeakMap.set()', which will throw a TypeError if given a non-object key.\n\tconst anchorNode = proxyToAnchorNode.get(target as TreeNode);\n\t// Hydrated node case\n\tif (anchorNode !== undefined) {\n\t\tconst flex = anchorNode.slots.get(flexTreeSlot);\n\t\tif (flex !== undefined) {\n\t\t\t// Cooked, or possible Marinated but something else cased the flex tree node to exist.\n\t\t\treturn flex;\n\t\t}\n\t\t// Marinated case\n\t\tassert(\n\t\t\tproxyToMapTreeNode.get(target as TreeNode) === undefined,\n\t\t\t0xa05 /* marinated nodes should not have MapTreeNodes */,\n\t\t);\n\t\treturn undefined;\n\t}\n\t// Unhydrated node or not a node case:\n\treturn proxyToMapTreeNode.get(target as TreeNode);\n}\n\n/**\n * Retrieves the proxy associated with the given flex node via {@link setInnerNode}, if any.\n */\nexport function tryGetCachedTreeNode(flexNode: InnerNode): TreeNode | undefined {\n\tif (isMapTreeNode(flexNode)) {\n\t\t// Unhydrated case\n\t\treturn mapTreeNodeToProxy.get(flexNode);\n\t}\n\t// Hydrated case\n\treturn flexNode.anchorNode.slots.get(proxySlot);\n}\n\n/**\n * Associate the given TreeNode and the given flex node.\n * @returns The node.\n * @remarks\n * This creates a 1:1 mapping between the tree node and InnerNode.\n * Either can be retrieved from the other via {@link getOrCreateInnerNode}/{@link tryGetInnerNode} or {@link tryGetCachedTreeNode}.\n * If the given proxy is already mapped to an flex node, the existing mapping will be overwritten.\n * If the given flex node is already mapped to a different proxy, this function will fail.\n */\nexport function setInnerNode<TNode extends TreeNode>(\n\tnode: TNode,\n\tinnerNode: InnerNode,\n): TNode {\n\tconst existingFlexNode = proxyToAnchorNode.get(node)?.slots.get(flexTreeSlot);\n\tassert(\n\t\texistingFlexNode === undefined,\n\t\t0x91d /* Cannot associate a flex node with multiple targets */,\n\t);\n\tif (isMapTreeNode(innerNode)) {\n\t\t// Unhydrated case\n\t\tproxyToMapTreeNode.set(node, innerNode);\n\t\tmapTreeNodeToProxy.set(innerNode, node);\n\t} else {\n\t\t// Hydrated case\n\t\tassert(\n\t\t\ttryGetCachedTreeNode(innerNode) === undefined,\n\t\t\t0x7f5 /* Cannot associate an flex node with multiple targets */,\n\t\t);\n\t\tbindHydratedNodeToAnchor(node, innerNode.anchorNode);\n\t}\n\treturn node;\n}\n\n/**\n * Bi-directionally associates the given hydrated TreeNode to the given anchor node.\n * @remarks Cleans up mappings to {@link MapTreeNode} - it is assumed that they are no longer needed once the proxy has an anchor node.\n */\nfunction bindHydratedNodeToAnchor(node: TreeNode, anchorNode: AnchorNode): void {\n\t// If the proxy currently has a raw node, forget it\n\tconst mapTreeNode = proxyToMapTreeNode.get(node);\n\tif (mapTreeNode !== undefined) {\n\t\tproxyToMapTreeNode.delete(node);\n\t\tmapTreeNodeToProxy.delete(mapTreeNode);\n\t}\n\t// Once a proxy has been associated with an anchor node, it should never change to another anchor node\n\tassert(\n\t\t!proxyToAnchorNode.has(node),\n\t\t0x91e /* Proxy has already been bound to a different anchor node */,\n\t);\n\tproxyToAnchorNode.set(node, anchorNode);\n\t// However, it's fine for an anchor node to rotate through different proxies when the content at that place in the tree is replaced.\n\tanchorNode.slots.set(proxySlot, node);\n\tgetKernel(node).hydrate(anchorNode);\n}\n\n/**\n * Given a node's schema, return the corresponding object in the proxy-based API.\n */\ntype TypedNode<TSchema extends FlexTreeNodeSchema> = TreeNode & WithType<TSchema[\"name\"]>;\n\nexport function tryDisposeTreeNode(anchorNode: AnchorNode): void {\n\tconst treeNode = anchorNode.slots.get(proxySlot);\n\tif (treeNode !== undefined) {\n\t\tconst kernel = getKernel(treeNode);\n\t\tkernel.dispose();\n\t}\n}\n"]}

package/lib/simple-tree/schemaTypes.d.ts

@@ -5,116 +5,13 @@
 import type { ErasedType, IFluidHandle } from "@fluidframework/core-interfaces";
 import { type LazyItem, type NodeKeyManager, type FlexListToUnion } from "../feature-libraries/index.js";
 import { type MakeNominal } from "../util/index.js";
-import type { InternalTreeNode, Unhydrated } from "./types.js";
+import type { Unhydrated, NodeKind, TreeNodeSchema, TreeNodeSchemaClass } from "./core/index.js";
 import type { FieldKey } from "../core/index.js";
 import type { InsertableContent } from "./proxies.js";
 /**
- * Schema for a tree node.
- * @typeParam Name - The full (including scope) name/identifier for the schema.
- * @typeParam Kind - Which kind of node this schema is for.
- * @typeParam TNode - API for nodes that use this schema.
- * @typeParam TBuild - Data which can be used to construct an {@link Unhydrated} node of this type.
- * @typeParam Info - Data used when defining this schema.
- * @remarks
- * Captures the schema both as runtime data and compile time type information.
- * @sealed @public
- */
-export type TreeNodeSchema<Name extends string = string, Kind extends NodeKind = NodeKind, TNode = unknown, TBuild = never, ImplicitlyConstructable extends boolean = boolean, Info = unknown> = TreeNodeSchemaClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info> | TreeNodeSchemaNonClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>;
-/**
- * Schema which is not a class.
- * @remarks
- * This is used for schema which cannot have their instances constructed using constructors, like leaf schema.
- * @privateRemarks
- * Non-class based schema can have issues with recursive types due to https://github.com/microsoft/TypeScript/issues/55832.
- * @sealed @public
- */
-export interface TreeNodeSchemaNonClass<out Name extends string = string, out Kind extends NodeKind = NodeKind, out TNode = unknown, in TInsertable = never, out ImplicitlyConstructable extends boolean = boolean, out Info = unknown> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {
-    create(data: TInsertable): TNode;
-}
-/**
- * Tree node schema which is implemented using a class.
- * @remarks
- * Instances of this class are nodes in the tree.
- * This is also a constructor so that it can be subclassed.
- *
- * Using classes in this way allows introducing a named type and a named value at the same time, helping keep the runtime and compile time information together and easy to refer to un a uniform way.
- * Additionally, this works around https://github.com/microsoft/TypeScript/issues/55832 which causes similar patterns with less explicit types to infer "any" in the d.ts file.
- *
- * When sub-classing a a `TreeNodeSchemaClass`, some extra rules must be followed:
- *
- * - Only ever use a single class from the schema's class hierarchy within a document and its schema.
- * For example, if using {@link SchemaFactory.object} you can do:
- * ```typescript
- * // Recommended "customizable" object schema pattern.
- * class Good extends schemaFactory.object("A", {
- * 	exampleField: schemaFactory.number,
- * }) {
- * 	public exampleCustomMethod(): void {
- * 		this.exampleField++;
- * 	}
- * }
- * ```
- * But should avoid:
- * ```typescript
- * // This by itself is ok, and opts into "POJO mode".
- * const base = schemaFactory.object("A", {});
- * // This is a bad pattern since it leaves two classes in scope which derive from the same SchemaFactory defined class.
- * // If both get used, its an error!
- * class Invalid extends base {}
- * ```
- * - Do not modify the constructor input parameter types or values:
- * ```typescript
- * class Invalid extends schemaFactory.object("A", {
- * 	exampleField: schemaFactory.number,
- * }) {
- * 	// This Modifies the type of the constructor input.
- * 	// This is unsupported due to programmatic access to the constructor being used internally.
- * 	public constructor(a: number) {
- * 		super({ exampleField: a });
- * 	}
- * }
- * ```
- * @sealed @public
- */
-export interface TreeNodeSchemaClass<out Name extends string = string, out Kind extends NodeKind = NodeKind, out TNode = unknown, in TInsertable = never, out ImplicitlyConstructable extends boolean = boolean, out Info = unknown> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {
-    /**
-     * Constructs an {@link Unhydrated} node with this schema.
-     * @remarks
-     * This constructor is also used internally to construct hydrated nodes with a different parameter type.
-     * Therefore, overriding this constructor with different argument types is not type-safe and is not supported.
-     * @sealed
-     */
-    new (data: TInsertable | InternalTreeNode): Unhydrated<TNode>;
-}
-/**
- * Data common to all tree node schema.
- * @remarks
- * Implementation detail of {@link TreeNodeSchema} which should be accessed instead of referring to this type directly.
- * @sealed @public
+ * Returns true if the given schema is a {@link TreeNodeSchemaClass}, or otherwise false if it is a {@link TreeNodeSchemaNonClass}.
  */
-export interface TreeNodeSchemaCore<out Name extends string, out Kind extends NodeKind, out ImplicitlyConstructable extends boolean, out Info = unknown> {
-    readonly identifier: Name;
-    readonly kind: Kind;
-    /**
-     * Data used to define this schema.
-     *
-     * @remarks
-     * The format depends on the kind of node it is for.
-     * For example, the "object" node kind could store the field schema here.
-     */
-    readonly info: Info;
-    /**
-     * When constructing insertable content,
-     * data that could be passed to the node's constructor can be used instead of an {@link Unhydrated} node
-     * iff implicitlyConstructable is true.
-     * @privateRemarks
-     * Currently the logic for traversing insertable content,
-     * both to build trees and to hydrate them does not defer to the schema classes to handle the policy,
-     * so if their constructors differ from what is supported, some cases will not work.
-     * Setting this to false adjusts the insertable types to disallow cases which could be impacted by these inconsistencies.
-     */
-    readonly implicitlyConstructable: ImplicitlyConstructable;
-}
+export declare function isTreeNodeSchemaClass<Name extends string, Kind extends NodeKind, TNode, TBuild, ImplicitlyConstructable extends boolean, Info>(schema: TreeNodeSchema<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>): schema is TreeNodeSchemaClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>;
 /**
  * Types for use in fields.
  * @remarks
@@ -149,32 +46,6 @@ export declare enum FieldKind {
      */
     Identifier = 2
 }
-/**
- * Kind of tree node.
- * @remarks
- * More kinds may be added over time, so do not assume this is an exhaustive set.
- * @public
- */
-export declare enum NodeKind {
-    /**
-     * A node which serves as a map, storing children under string keys.
-     */
-    Map = 0,
-    /**
-     * A node which serves as an array, storing children in an ordered sequence.
-     */
-    Array = 1,
-    /**
-     * A node which stores a heterogenous collection of children in named fields.
-     * @remarks
-     * Each field gets its own schema.
-     */
-    Object = 2,
-    /**
-     * A node which stores a single leaf value.
-     */
-    Leaf = 3
-}
 /**
  * Maps from a view key to its corresponding {@link FieldProps.key | stored key} for the provided
  * {@link ImplicitFieldSchema | field schema}.
@@ -312,13 +183,17 @@ export declare class FieldSchema<out Kind extends FieldKind = FieldKind, out Typ
      * This class is used with instanceof, and therefore should have nominal typing.
      * This field enforces that.
      */
-    protected _typeCheck?: MakeNominal;
+    protected _typeCheck: MakeNominal;
     private readonly lazyTypes;
     /**
      * What types of tree nodes are allowed in this field.
      * @remarks Counterpart to {@link FieldSchema.allowedTypes}, with any lazy definitions evaluated.
      */
     get allowedTypeSet(): ReadonlySet<TreeNodeSchema>;
+    /**
+     * True if and only if, when constructing a node with this field, a value must be provided for it.
+     */
+    readonly requiresValue: boolean;
     private constructor();
 }
 /**
@@ -402,33 +277,9 @@ export type InsertableTypedNode<T extends TreeNodeSchema> = (T extends {
 export type NodeBuilderData<T extends TreeNodeSchema> = T extends TreeNodeSchema<string, NodeKind, unknown, infer TBuild> ? TBuild : never;
 /**
  * Value that may be stored as a leaf node.
- * @public
- */
-export type TreeLeafValue = number | string | boolean | IFluidHandle | null;
-/**
- * The type of a {@link TreeNode}.
- * For more information about the type, use `Tree.schema(theNode)` instead.
  * @remarks
- * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.
- * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.
- *
- * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where nodes are expected.
- * Instead construct a real node of the desired type using its constructor.
- * @privateRemarks
- * This prevents non-nodes from being accidentally used as nodes, as well as allows the type checker to distinguish different node types.
+ * Some limitations apply, see the documentation for {@link SchemaFactory.number} and {@link SchemaFactory.string} for those restrictions.
  * @public
  */
-export declare const typeNameSymbol: unique symbol;
-/**
- * Adds a type symbol to a type for stronger typing.
- * @remarks
- * An implementation detail of {@link TreeNode}'s strong typing setup: not intended for direct use outside of this package.
- * @sealed @public
- */
-export interface WithType<TName extends string = string> {
-    /**
-     * Type symbol, marking a type in a way to increase type safety via strong type checking.
-     */
-    get [typeNameSymbol](): TName;
-}
+export type TreeLeafValue = number | string | boolean | IFluidHandle | null;
 //# sourceMappingURL=schemaTypes.d.ts.map