@fluidframework/tree 2.1.0-281041 → 2.2.0

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 FlexTreeNodeEvents,\n\ttype FlexTreeTypedField,\n\ttype MapTreeNode,\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\";\nimport type { Off } from \"../events/index.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 mapTreeNode: MapTreeNode;\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, mapTreeNode, proxy) => {\n\t\t\tproxies.proxyPaths.push({ path: p, mapTreeNode, 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, mapTreeNode, proxy) => {\n\t\t\tproxies[i].proxyPaths.push({ path: p, mapTreeNode, 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, mapTreeNode: MapTreeNode, 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, mapTreeNode, 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, mapTreeNode, proxy } of proxies[i].proxyPaths) {\n\t\t\t\tconst anchorNode = anchorProxy(forest.anchors, path, proxy);\n\t\t\t\tmapTreeNode.forwardEvents({\n\t\t\t\t\ton<K extends keyof FlexTreeNodeEvents>(\n\t\t\t\t\t\teventName: K,\n\t\t\t\t\t\tlistener: FlexTreeNodeEvents[K],\n\t\t\t\t\t): Off {\n\t\t\t\t\t\tswitch (eventName) {\n\t\t\t\t\t\t\tcase \"nodeChanged\": {\n\t\t\t\t\t\t\t\treturn anchorNode.on(\"childrenChangedAfterBatch\", listener);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tcase \"treeChanged\": {\n\t\t\t\t\t\t\t\treturn anchorNode.on(\"subtreeChangedAfterBatch\", listener);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tdefault:\n\t\t\t\t\t\t\t\tfail(\"Unexpected event subscription\");\n\t\t\t\t\t\t}\n\t\t\t\t\t},\n\t\t\t\t});\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,46 +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";
 /**
  * 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 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;AAyBhD;;;;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;AAuBD;;GAEG;AACH,KAAK,SAAS,CAAC,OAAO,SAAS,kBAAkB,IAAI,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC"}
+{"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,34 +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";
-// 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);
@@ -48,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);
@@ -62,69 +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);
+    anchorNode.slots.set(proxySlot, node);
+    getKernel(node).hydrate(anchorNode);
+}
+export function tryDisposeTreeNode(anchorNode) {
+    const treeNode = anchorNode.slots.get(proxySlot);
+    if (treeNode !== undefined) {
+        const kernel = getKernel(treeNode);
+        kernel.dispose();
+    }
 }
 //# 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\";\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}\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"]}
+{"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"]}