@fluidframework/tree 2.1.0 → 2.3.0-288113

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

@@ -3,29 +3,14 @@
  * Licensed under the MIT License.
  */
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
-import { type IForestSubscription, type MapTree, type TreeNodeSchemaIdentifier, type TreeValue } from "../core/index.js";
+import { type IForestSubscription, type MapTree, type TreeValue } from "../core/index.js";
 import { type FlexTreeField, type FlexTreeNode } from "../feature-libraries/index.js";
-import type { TreeNode, Unhydrated } from "./types.js";
+import { type TreeNode, type Unhydrated } from "./core/index.js";
 /**
- * Detects if the given 'candidate' is a TreeNode.
- *
- * @remarks
- * Supports both Hydrated and {@link Unhydrated} TreeNodes, both of which return true.
- *
- * Because the common usage is to check if a value being inserted/set is a TreeNode,
- * this function permits calling with primitives as well as objects.
- *
- * Primitives will always return false (as they are copies of data, not references to nodes).
- *
- * @param candidate - Value which may be a TreeNode
- * @returns true if the given 'candidate' is a hydrated TreeNode.
+ * Retrieve the associated {@link TreeNode} for the given field's content.
  */
-export declare function isTreeNode(candidate: unknown): candidate is TreeNode | Unhydrated<TreeNode>;
-/**
- * Retrieve the associated proxy for the given field.
- * */
-export declare function getProxyForField(field: FlexTreeField): TreeNode | TreeValue | undefined;
-export declare function getOrCreateNodeProxy(flexNode: FlexTreeNode): TreeNode | TreeValue;
+export declare function getTreeNodeForField(field: FlexTreeField): TreeNode | TreeValue | undefined;
+export declare function getOrCreateNodeFromFlexTreeNode(flexNode: FlexTreeNode): TreeNode | TreeValue;
 /**
  * Records any proxies in the given content tree and does the necessary bookkeeping to ensure they are synchronized with subsequent reads of the tree.
  * @remarks If the content tree contains any proxies, this function must be called just prior to inserting the content into the tree.
@@ -42,15 +27,11 @@ export declare function prepareContentForHydration(content: MapTree | readonly M
  * @remarks
  * Can contain unhydrated nodes, but can not be an unhydrated node at the root.
  */
-export type FactoryContent = IFluidHandle | string | number | boolean | null | ReadonlyMap<string, InsertableContent> | readonly InsertableContent[] | {
+export type FactoryContent = IFluidHandle | string | number | boolean | null | Iterable<readonly [string, InsertableContent]> | readonly InsertableContent[] | {
     readonly [P in string]?: InsertableContent;
 };
 /**
  * Content which can be inserted into a tree.
  */
 export type InsertableContent = Unhydrated<TreeNode> | FactoryContent;
-/**
- * Brand `copy` with the type (under {@link typeNameSymbol}) to avoid ambiguity when inferring types from this data.
- */
-export declare function markContentType(typeName: TreeNodeSchemaIdentifier, copy: object): void;
 //# sourceMappingURL=proxies.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"proxies.d.ts","sourceRoot":"","sources":["../../src/simple-tree/proxies.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAGpE,OAAO,EAEN,KAAK,mBAAmB,EACxB,KAAK,OAAO,EACZ,KAAK,wBAAwB,EAC7B,KAAK,SAAS,EAEd,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAGN,KAAK,aAAa,EAClB,KAAK,YAAY,EAKjB,MAAM,+BAA+B,CAAC;AAKvC,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,IAAI,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAE3F;AAED;;KAEK;AACL,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAqCvF;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,SAAS,CAejF;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,GAAG,SAAS,EACjD,MAAM,EAAE,mBAAmB,GACzB,IAAI,CAiBN;AAuED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACvB,YAAY,GACZ,MAAM,GACN,MAAM,GACN,OAAO,GAEP,IAAI,GACJ,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,GACtC,SAAS,iBAAiB,EAAE,GAC5B;IACA,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,iBAAiB;CACzC,CAAC;AAEL;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC;AAEtE;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,wBAAwB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEtF"}
+{"version":3,"file":"proxies.d.ts","sourceRoot":"","sources":["../../src/simple-tree/proxies.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAIpE,OAAO,EAEN,KAAK,mBAAmB,EACxB,KAAK,OAAO,EACZ,KAAK,SAAS,EAEd,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAGN,KAAK,aAAa,EAClB,KAAK,YAAY,EAIjB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EAA0B,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEzF;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAiC1F;AAED,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,SAAS,CAe5F;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,GAAG,SAAS,EACjD,MAAM,EAAE,mBAAmB,GACzB,IAAI,CAiBN;AAsFD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACvB,YAAY,GACZ,MAAM,GACN,MAAM,GACN,OAAO,GAEP,IAAI,GACJ,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,GAC9C,SAAS,iBAAiB,EAAE,GAC5B;IACA,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,iBAAiB;CACzC,CAAC;AAEL;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC"}

package/lib/simple-tree/proxies.js

@@ -2,36 +2,22 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { assert } from "@fluidframework/core-utils/internal";
 import { EmptyKey, } from "../core/index.js";
-import { FieldKinds, tryGetMapTreeNode, typeNameSymbol, isFlexTreeNode, } from "../feature-libraries/index.js";
+import { FieldKinds, tryGetMapTreeNode, isFlexTreeNode, } from "../feature-libraries/index.js";
 import { fail, isReadonlyArray } from "../util/index.js";
-import { anchorProxy, tryGetFlexNode, tryGetProxy } from "./proxyBinding.js";
-import { tryGetSimpleNodeSchema } from "./schemaCaching.js";
+import { anchorProxy, tryGetCachedTreeNode } from "./proxyBinding.js";
+import { tryGetSimpleNodeSchema } from "./core/index.js";
 /**
- * Detects if the given 'candidate' is a TreeNode.
- *
- * @remarks
- * Supports both Hydrated and {@link Unhydrated} TreeNodes, both of which return true.
- *
- * Because the common usage is to check if a value being inserted/set is a TreeNode,
- * this function permits calling with primitives as well as objects.
- *
- * Primitives will always return false (as they are copies of data, not references to nodes).
- *
- * @param candidate - Value which may be a TreeNode
- * @returns true if the given 'candidate' is a hydrated TreeNode.
+ * Retrieve the associated {@link TreeNode} for the given field's content.
  */
-export function isTreeNode(candidate) {
-    return tryGetFlexNode(candidate) !== undefined;
-}
-/**
- * Retrieve the associated proxy for the given field.
- * */
-export function getProxyForField(field) {
+export function getTreeNodeForField(field) {
     function tryToUnboxLeaves(flexField) {
         const maybeContent = flexField.content;
-        return isFlexTreeNode(maybeContent) ? getOrCreateNodeProxy(maybeContent) : maybeContent;
+        return isFlexTreeNode(maybeContent)
+            ? getOrCreateNodeFromFlexTreeNode(maybeContent)
+            : maybeContent;
     }
     switch (field.schema.kind) {
         case FieldKinds.required: {
@@ -42,12 +28,6 @@ export function getProxyForField(field) {
             const typedField = field;
             return tryToUnboxLeaves(typedField);
         }
-        // TODO: Remove if/when 'FieldNode' is removed.
-        case FieldKinds.sequence: {
-            // 'getProxyForNode' handles FieldNodes by unconditionally creating a array node proxy, making
-            // this case unreachable as long as users follow the 'array recipe'.
-            fail("'sequence' field is unexpected.");
-        }
         case FieldKinds.identifier: {
             // Identifier fields are just value fields that hold strings
             return field
@@ -57,8 +37,8 @@ export function getProxyForField(field) {
             fail("invalid field kind");
     }
 }
-export function getOrCreateNodeProxy(flexNode) {
-    const cachedProxy = tryGetProxy(flexNode);
+export function getOrCreateNodeFromFlexTreeNode(flexNode) {
+    const cachedProxy = tryGetCachedTreeNode(flexNode);
     if (cachedProxy !== undefined) {
         return cachedProxy;
     }
@@ -99,37 +79,48 @@ export function prepareContentForHydration(content, forest) {
     }
 }
 function prepareArrayContentForHydration(content, forest) {
-    const proxies = [];
-    for (let i = 0; i < content.length; i++) {
-        proxies.push({
+    const proxyPaths = [];
+    for (const item of content) {
+        const proxyPath = {
             rootPath: {
                 parent: undefined,
                 parentField: EmptyKey,
                 parentIndex: 0,
             },
             proxyPaths: [],
-        });
-        walkMapTree(content[i], proxies[i].rootPath, (p, proxy) => {
-            proxies[i].proxyPaths.push({ path: p, proxy });
+        };
+        proxyPaths.push(proxyPath);
+        walkMapTree(item, proxyPath.rootPath, (p, proxy) => {
+            proxyPath.proxyPaths.push({ path: p, proxy });
         });
     }
-    bindProxies(proxies, forest);
+    bindProxies(proxyPaths, forest);
 }
 function walkMapTree(mapTree, path, onVisitTreeNode) {
-    const mapTreeNode = tryGetMapTreeNode(mapTree);
-    if (mapTreeNode !== undefined) {
-        const treeNode = tryGetProxy(mapTreeNode);
-        if (treeNode !== undefined) {
-            onVisitTreeNode(path, treeNode);
-        }
+    if (tryGetMapTreeNode(mapTree)?.parentField.parent.parent !== undefined) {
+        throw new UsageError("Attempted to insert a node which is already under a parent. If this is desired, remove the node from its parent before inserting it elsewhere.");
     }
-    for (const [key, field] of mapTree.fields) {
-        for (let i = 0; i < field.length; i++) {
-            walkMapTree(field[i], {
-                parent: path,
-                parentField: key,
-                parentIndex: i,
-            }, onVisitTreeNode);
+    const nexts = [];
+    for (let next = [path, mapTree]; next !== undefined; next = nexts.pop()) {
+        const [p, m] = next;
+        const mapTreeNode = tryGetMapTreeNode(m);
+        if (mapTreeNode !== undefined) {
+            const treeNode = tryGetCachedTreeNode(mapTreeNode);
+            if (treeNode !== undefined) {
+                onVisitTreeNode(p, treeNode);
+            }
+        }
+        for (const [key, field] of m.fields) {
+            for (const [i, child] of field.entries()) {
+                nexts.push([
+                    {
+                        parent: p,
+                        parentField: key,
+                        parentIndex: i,
+                    },
+                    child,
+                ]);
+            }
         }
     }
 }
@@ -139,7 +130,11 @@ function bindProxies(proxies, forest) {
         // Creating a new array emits one event per element in the array, so listen to the event once for each element
         let i = 0;
         const off = forest.on("afterRootFieldCreated", (fieldKey) => {
+            // Non null asserting here because of the length check above
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
             proxies[i].rootPath.parentField = fieldKey;
+            // Non null asserting here because of the length check above
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
             for (const { path, proxy } of proxies[i].proxyPaths) {
                 anchorProxy(forest.anchors, path, proxy);
             }
@@ -149,10 +144,4 @@ function bindProxies(proxies, forest) {
         });
     }
 }
-/**
- * Brand `copy` with the type (under {@link typeNameSymbol}) to avoid ambiguity when inferring types from this data.
- */
-export function markContentType(typeName, copy) {
-    Object.defineProperty(copy, typeNameSymbol, { value: typeName });
-}
 //# sourceMappingURL=proxies.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"proxies.js","sourceRoot":"","sources":["../../src/simple-tree/proxies.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 type { IFluidHandle } from \"@fluidframework/core-interfaces\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport {\n\tEmptyKey,\n\ttype IForestSubscription,\n\ttype MapTree,\n\ttype TreeNodeSchemaIdentifier,\n\ttype TreeValue,\n\ttype UpPath,\n} from \"../core/index.js\";\n\nimport {\n\tFieldKinds,\n\ttype FlexFieldSchema,\n\ttype FlexTreeField,\n\ttype FlexTreeNode,\n\ttype FlexTreeTypedField,\n\ttryGetMapTreeNode,\n\ttypeNameSymbol,\n\tisFlexTreeNode,\n} from \"../feature-libraries/index.js\";\nimport { type Mutable, fail, isReadonlyArray } from \"../util/index.js\";\n\nimport { anchorProxy, tryGetFlexNode, tryGetProxy } from \"./proxyBinding.js\";\nimport { tryGetSimpleNodeSchema } from \"./schemaCaching.js\";\nimport type { TreeNode, Unhydrated } from \"./types.js\";\n\n/**\n * Detects if the given 'candidate' is a TreeNode.\n *\n * @remarks\n * Supports both Hydrated and {@link Unhydrated} TreeNodes, both of which return true.\n *\n * Because the common usage is to check if a value being inserted/set is a TreeNode,\n * this function permits calling with primitives as well as objects.\n *\n * Primitives will always return false (as they are copies of data, not references to nodes).\n *\n * @param candidate - Value which may be a TreeNode\n * @returns true if the given 'candidate' is a hydrated TreeNode.\n */\nexport function isTreeNode(candidate: unknown): candidate is TreeNode | Unhydrated<TreeNode> {\n\treturn tryGetFlexNode(candidate) !== undefined;\n}\n\n/**\n * Retrieve the associated proxy for the given field.\n * */\nexport function getProxyForField(field: FlexTreeField): TreeNode | TreeValue | undefined {\n\tfunction tryToUnboxLeaves(\n\t\tflexField: FlexTreeTypedField<\n\t\t\tFlexFieldSchema<typeof FieldKinds.required | typeof FieldKinds.optional>\n\t\t>,\n\t): TreeNode | TreeValue | undefined {\n\t\tconst maybeContent = flexField.content;\n\t\treturn isFlexTreeNode(maybeContent) ? getOrCreateNodeProxy(maybeContent) : maybeContent;\n\t}\n\tswitch (field.schema.kind) {\n\t\tcase FieldKinds.required: {\n\t\t\tconst typedField = field as FlexTreeTypedField<\n\t\t\t\tFlexFieldSchema<typeof FieldKinds.required>\n\t\t\t>;\n\t\t\treturn tryToUnboxLeaves(typedField);\n\t\t}\n\t\tcase FieldKinds.optional: {\n\t\t\tconst typedField = field as FlexTreeTypedField<\n\t\t\t\tFlexFieldSchema<typeof FieldKinds.optional>\n\t\t\t>;\n\t\t\treturn tryToUnboxLeaves(typedField);\n\t\t}\n\t\t// TODO: Remove if/when 'FieldNode' is removed.\n\t\tcase FieldKinds.sequence: {\n\t\t\t// 'getProxyForNode' handles FieldNodes by unconditionally creating a array node proxy, making\n\t\t\t// this case unreachable as long as users follow the 'array recipe'.\n\t\t\tfail(\"'sequence' field is unexpected.\");\n\t\t}\n\t\tcase FieldKinds.identifier: {\n\t\t\t// Identifier fields are just value fields that hold strings\n\t\t\treturn (field as FlexTreeTypedField<FlexFieldSchema<typeof FieldKinds.required>>)\n\t\t\t\t.content as string;\n\t\t}\n\n\t\tdefault:\n\t\t\tfail(\"invalid field kind\");\n\t}\n}\n\nexport function getOrCreateNodeProxy(flexNode: FlexTreeNode): TreeNode | TreeValue {\n\tconst cachedProxy = tryGetProxy(flexNode);\n\tif (cachedProxy !== undefined) {\n\t\treturn cachedProxy;\n\t}\n\n\tconst schema = flexNode.schema;\n\tconst classSchema = tryGetSimpleNodeSchema(schema);\n\tassert(classSchema !== undefined, 0x91b /* node without schema */);\n\tif (typeof classSchema === \"function\") {\n\t\tconst simpleSchema = classSchema as unknown as new (dummy: FlexTreeNode) => TreeNode;\n\t\treturn new simpleSchema(flexNode);\n\t} else {\n\t\treturn (classSchema as { create(data: FlexTreeNode): TreeNode }).create(flexNode);\n\t}\n}\n\n// #region Content insertion and proxy binding\n\n/** The path of a proxy, relative to the root of the content tree that the proxy belongs to */\ninterface RelativeProxyPath {\n\treadonly path: UpPath;\n\treadonly proxy: TreeNode;\n}\n\n/** All {@link RelativeProxyPath}s that are under the given root path */\ninterface RootedProxyPaths {\n\treadonly rootPath: UpPath;\n\treadonly proxyPaths: RelativeProxyPath[];\n}\n\n/**\n * Records any proxies in the given content tree and does the necessary bookkeeping to ensure they are synchronized with subsequent reads of the tree.\n * @remarks If the content tree contains any proxies, this function must be called just prior to inserting the content into the tree.\n * Specifically, no other content may be inserted into the tree between the invocation of this function and the insertion of `content`.\n * The insertion of `content` must occur or else this function will cause memory leaks.\n * @param content - the tree of content to be inserted, of which any of its object/map/array nodes might be a proxy\n * @param anchors - the {@link AnchorSet} for the tree\n * @returns The content after having all proxies replaced inline with plain javascript objects.\n * See {@link extractFactoryContent} for more details.\n */\nexport function prepareContentForHydration(\n\tcontent: MapTree | readonly MapTree[] | undefined,\n\tforest: IForestSubscription,\n): void {\n\tif (isReadonlyArray(content)) {\n\t\treturn prepareArrayContentForHydration(content, forest);\n\t}\n\n\tif (content !== undefined) {\n\t\tconst proxies: RootedProxyPaths = {\n\t\t\trootPath: { parent: undefined, parentField: EmptyKey, parentIndex: 0 },\n\t\t\tproxyPaths: [],\n\t\t};\n\n\t\twalkMapTree(content, proxies.rootPath, (p, proxy) => {\n\t\t\tproxies.proxyPaths.push({ path: p, proxy });\n\t\t});\n\n\t\tbindProxies([proxies], forest);\n\t}\n}\n\nfunction prepareArrayContentForHydration(\n\tcontent: readonly MapTree[],\n\tforest: IForestSubscription,\n): void {\n\tconst proxies: RootedProxyPaths[] = [];\n\tfor (let i = 0; i < content.length; i++) {\n\t\tproxies.push({\n\t\t\trootPath: {\n\t\t\t\tparent: undefined,\n\t\t\t\tparentField: EmptyKey,\n\t\t\t\tparentIndex: 0,\n\t\t\t},\n\t\t\tproxyPaths: [],\n\t\t});\n\t\twalkMapTree(content[i], proxies[i].rootPath, (p, proxy) => {\n\t\t\tproxies[i].proxyPaths.push({ path: p, proxy });\n\t\t});\n\t}\n\n\tbindProxies(proxies, forest);\n}\n\nfunction walkMapTree(\n\tmapTree: MapTree,\n\tpath: UpPath,\n\tonVisitTreeNode: (path: UpPath, treeNode: TreeNode) => void,\n): void {\n\tconst mapTreeNode = tryGetMapTreeNode(mapTree);\n\tif (mapTreeNode !== undefined) {\n\t\tconst treeNode = tryGetProxy(mapTreeNode);\n\t\tif (treeNode !== undefined) {\n\t\t\tonVisitTreeNode(path, treeNode);\n\t\t}\n\t}\n\n\tfor (const [key, field] of mapTree.fields) {\n\t\tfor (let i = 0; i < field.length; i++) {\n\t\t\twalkMapTree(\n\t\t\t\tfield[i],\n\t\t\t\t{\n\t\t\t\t\tparent: path,\n\t\t\t\t\tparentField: key,\n\t\t\t\t\tparentIndex: i,\n\t\t\t\t},\n\t\t\t\tonVisitTreeNode,\n\t\t\t);\n\t\t}\n\t}\n}\n\nfunction bindProxies(proxies: RootedProxyPaths[], forest: IForestSubscription): void {\n\t// Only subscribe to the event if there is at least one proxy tree to hydrate - this is not the case when inserting an empty array [].\n\tif (proxies.length > 0) {\n\t\t// Creating a new array emits one event per element in the array, so listen to the event once for each element\n\t\tlet i = 0;\n\t\tconst off = forest.on(\"afterRootFieldCreated\", (fieldKey) => {\n\t\t\t(proxies[i].rootPath as Mutable<UpPath>).parentField = fieldKey;\n\t\t\tfor (const { path, proxy } of proxies[i].proxyPaths) {\n\t\t\t\tanchorProxy(forest.anchors, path, proxy);\n\t\t\t}\n\t\t\tif (++i === proxies.length) {\n\t\t\t\toff();\n\t\t\t}\n\t\t});\n\t}\n}\n\n// #endregion Content insertion and proxy binding\n\n/**\n * Content which can be used to build a node.\n * @remarks\n * Can contain unhydrated nodes, but can not be an unhydrated node at the root.\n */\nexport type FactoryContent =\n\t| IFluidHandle\n\t| string\n\t| number\n\t| boolean\n\t// eslint-disable-next-line @rushstack/no-new-null\n\t| null\n\t| ReadonlyMap<string, InsertableContent>\n\t| readonly InsertableContent[]\n\t| {\n\t\t\treadonly [P in string]?: InsertableContent;\n\t  };\n\n/**\n * Content which can be inserted into a tree.\n */\nexport type InsertableContent = Unhydrated<TreeNode> | FactoryContent;\n\n/**\n * Brand `copy` with the type (under {@link typeNameSymbol}) to avoid ambiguity when inferring types from this data.\n */\nexport function markContentType(typeName: TreeNodeSchemaIdentifier, copy: object): void {\n\tObject.defineProperty(copy, typeNameSymbol, { value: typeName });\n}\n"]}
+{"version":3,"file":"proxies.js","sourceRoot":"","sources":["../../src/simple-tree/proxies.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 type { IFluidHandle } from \"@fluidframework/core-interfaces\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport {\n\tEmptyKey,\n\ttype IForestSubscription,\n\ttype MapTree,\n\ttype TreeValue,\n\ttype UpPath,\n} from \"../core/index.js\";\n\nimport {\n\tFieldKinds,\n\ttype FlexFieldSchema,\n\ttype FlexTreeField,\n\ttype FlexTreeNode,\n\ttype FlexTreeTypedField,\n\ttryGetMapTreeNode,\n\tisFlexTreeNode,\n} from \"../feature-libraries/index.js\";\nimport { type Mutable, fail, isReadonlyArray } from \"../util/index.js\";\n\nimport { anchorProxy, tryGetCachedTreeNode } from \"./proxyBinding.js\";\nimport { tryGetSimpleNodeSchema, type TreeNode, type Unhydrated } from \"./core/index.js\";\n\n/**\n * Retrieve the associated {@link TreeNode} for the given field's content.\n */\nexport function getTreeNodeForField(field: FlexTreeField): TreeNode | TreeValue | undefined {\n\tfunction tryToUnboxLeaves(\n\t\tflexField: FlexTreeTypedField<\n\t\t\tFlexFieldSchema<typeof FieldKinds.required | typeof FieldKinds.optional>\n\t\t>,\n\t): TreeNode | TreeValue | undefined {\n\t\tconst maybeContent = flexField.content;\n\t\treturn isFlexTreeNode(maybeContent)\n\t\t\t? getOrCreateNodeFromFlexTreeNode(maybeContent)\n\t\t\t: maybeContent;\n\t}\n\tswitch (field.schema.kind) {\n\t\tcase FieldKinds.required: {\n\t\t\tconst typedField = field as FlexTreeTypedField<\n\t\t\t\tFlexFieldSchema<typeof FieldKinds.required>\n\t\t\t>;\n\t\t\treturn tryToUnboxLeaves(typedField);\n\t\t}\n\t\tcase FieldKinds.optional: {\n\t\t\tconst typedField = field as FlexTreeTypedField<\n\t\t\t\tFlexFieldSchema<typeof FieldKinds.optional>\n\t\t\t>;\n\t\t\treturn tryToUnboxLeaves(typedField);\n\t\t}\n\t\tcase FieldKinds.identifier: {\n\t\t\t// Identifier fields are just value fields that hold strings\n\t\t\treturn (field as FlexTreeTypedField<FlexFieldSchema<typeof FieldKinds.required>>)\n\t\t\t\t.content as string;\n\t\t}\n\n\t\tdefault:\n\t\t\tfail(\"invalid field kind\");\n\t}\n}\n\nexport function getOrCreateNodeFromFlexTreeNode(flexNode: FlexTreeNode): TreeNode | TreeValue {\n\tconst cachedProxy = tryGetCachedTreeNode(flexNode);\n\tif (cachedProxy !== undefined) {\n\t\treturn cachedProxy;\n\t}\n\n\tconst schema = flexNode.schema;\n\tconst classSchema = tryGetSimpleNodeSchema(schema);\n\tassert(classSchema !== undefined, 0x91b /* node without schema */);\n\tif (typeof classSchema === \"function\") {\n\t\tconst simpleSchema = classSchema as unknown as new (dummy: FlexTreeNode) => TreeNode;\n\t\treturn new simpleSchema(flexNode);\n\t} else {\n\t\treturn (classSchema as { create(data: FlexTreeNode): TreeNode }).create(flexNode);\n\t}\n}\n\n// #region Content insertion and proxy binding\n\n/** The path of a proxy, relative to the root of the content tree that the proxy belongs to */\ninterface RelativeProxyPath {\n\treadonly path: UpPath;\n\treadonly proxy: TreeNode;\n}\n\n/** All {@link RelativeProxyPath}s that are under the given root path */\ninterface RootedProxyPaths {\n\treadonly rootPath: UpPath;\n\treadonly proxyPaths: RelativeProxyPath[];\n}\n\n/**\n * Records any proxies in the given content tree and does the necessary bookkeeping to ensure they are synchronized with subsequent reads of the tree.\n * @remarks If the content tree contains any proxies, this function must be called just prior to inserting the content into the tree.\n * Specifically, no other content may be inserted into the tree between the invocation of this function and the insertion of `content`.\n * The insertion of `content` must occur or else this function will cause memory leaks.\n * @param content - the tree of content to be inserted, of which any of its object/map/array nodes might be a proxy\n * @param anchors - the {@link AnchorSet} for the tree\n * @returns The content after having all proxies replaced inline with plain javascript objects.\n * See {@link extractFactoryContent} for more details.\n */\nexport function prepareContentForHydration(\n\tcontent: MapTree | readonly MapTree[] | undefined,\n\tforest: IForestSubscription,\n): void {\n\tif (isReadonlyArray(content)) {\n\t\treturn prepareArrayContentForHydration(content, forest);\n\t}\n\n\tif (content !== undefined) {\n\t\tconst proxies: RootedProxyPaths = {\n\t\t\trootPath: { parent: undefined, parentField: EmptyKey, parentIndex: 0 },\n\t\t\tproxyPaths: [],\n\t\t};\n\n\t\twalkMapTree(content, proxies.rootPath, (p, proxy) => {\n\t\t\tproxies.proxyPaths.push({ path: p, proxy });\n\t\t});\n\n\t\tbindProxies([proxies], forest);\n\t}\n}\n\nfunction prepareArrayContentForHydration(\n\tcontent: readonly MapTree[],\n\tforest: IForestSubscription,\n): void {\n\tconst proxyPaths: RootedProxyPaths[] = [];\n\tfor (const item of content) {\n\t\tconst proxyPath: RootedProxyPaths = {\n\t\t\trootPath: {\n\t\t\t\tparent: undefined,\n\t\t\t\tparentField: EmptyKey,\n\t\t\t\tparentIndex: 0,\n\t\t\t},\n\t\t\tproxyPaths: [],\n\t\t};\n\t\tproxyPaths.push(proxyPath);\n\t\twalkMapTree(item, proxyPath.rootPath, (p, proxy) => {\n\t\t\tproxyPath.proxyPaths.push({ path: p, proxy });\n\t\t});\n\t}\n\n\tbindProxies(proxyPaths, forest);\n}\n\nfunction walkMapTree(\n\tmapTree: MapTree,\n\tpath: UpPath,\n\tonVisitTreeNode: (path: UpPath, treeNode: TreeNode) => void,\n): void {\n\tif (tryGetMapTreeNode(mapTree)?.parentField.parent.parent !== undefined) {\n\t\tthrow new UsageError(\n\t\t\t\"Attempted to insert a node which is already under a parent. If this is desired, remove the node from its parent before inserting it elsewhere.\",\n\t\t);\n\t}\n\n\ttype Next = [path: UpPath, tree: MapTree];\n\tconst nexts: Next[] = [];\n\tfor (let next: Next | undefined = [path, mapTree]; next !== undefined; next = nexts.pop()) {\n\t\tconst [p, m] = next;\n\t\tconst mapTreeNode = tryGetMapTreeNode(m);\n\t\tif (mapTreeNode !== undefined) {\n\t\t\tconst treeNode = tryGetCachedTreeNode(mapTreeNode);\n\t\t\tif (treeNode !== undefined) {\n\t\t\t\tonVisitTreeNode(p, treeNode);\n\t\t\t}\n\t\t}\n\n\t\tfor (const [key, field] of m.fields) {\n\t\t\tfor (const [i, child] of field.entries()) {\n\t\t\t\tnexts.push([\n\t\t\t\t\t{\n\t\t\t\t\t\tparent: p,\n\t\t\t\t\t\tparentField: key,\n\t\t\t\t\t\tparentIndex: i,\n\t\t\t\t\t},\n\t\t\t\t\tchild,\n\t\t\t\t]);\n\t\t\t}\n\t\t}\n\t}\n}\n\nfunction bindProxies(proxies: RootedProxyPaths[], forest: IForestSubscription): void {\n\t// Only subscribe to the event if there is at least one proxy tree to hydrate - this is not the case when inserting an empty array [].\n\tif (proxies.length > 0) {\n\t\t// Creating a new array emits one event per element in the array, so listen to the event once for each element\n\t\tlet i = 0;\n\t\tconst off = forest.on(\"afterRootFieldCreated\", (fieldKey) => {\n\t\t\t// Non null asserting here because of the length check above\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n\t\t\t(proxies[i]!.rootPath as Mutable<UpPath>).parentField = fieldKey;\n\t\t\t// Non null asserting here because of the length check above\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n\t\t\tfor (const { path, proxy } of proxies[i]!.proxyPaths) {\n\t\t\t\tanchorProxy(forest.anchors, path, proxy);\n\t\t\t}\n\t\t\tif (++i === proxies.length) {\n\t\t\t\toff();\n\t\t\t}\n\t\t});\n\t}\n}\n\n// #endregion Content insertion and proxy binding\n\n/**\n * Content which can be used to build a node.\n * @remarks\n * Can contain unhydrated nodes, but can not be an unhydrated node at the root.\n */\nexport type FactoryContent =\n\t| IFluidHandle\n\t| string\n\t| number\n\t| boolean\n\t// eslint-disable-next-line @rushstack/no-new-null\n\t| null\n\t| Iterable<readonly [string, InsertableContent]>\n\t| readonly InsertableContent[]\n\t| {\n\t\t\treadonly [P in string]?: InsertableContent;\n\t  };\n\n/**\n * Content which can be inserted into a tree.\n */\nexport type InsertableContent = Unhydrated<TreeNode> | FactoryContent;\n"]}

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