@fluidframework/tree 2.1.0-281041 → 2.1.0

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 } from \"./schemaTypes.js\";\nimport type { TreeArrayNode } from \"./arrayNode.js\";\nimport type { TreeNode } from \"./types.js\";\n// TODO: decide how to deal with dependencies on flex-tree implementation.\n// eslint-disable-next-line import/no-internal-modules\nimport { makeTree } from \"../feature-libraries/flex-tree/lazyNode.js\";\nimport type { TreeMapNode } from \"./mapNode.js\";\nimport { TreeNodeKernel } from \"./treeNodeKernel.js\";\n\n// This file contains various maps and helpers for supporting proxy binding (a.k.a. proxy hydration).\n// See ./ProxyBinding.md for a high-level overview of the process.\n\n/**\n * An anchor slot which associates an anchor with its corresponding node proxy, if there is one.\n */\nconst proxySlot = anchorSlot<TreeNode>();\n\n// The following records are maintained as WeakMaps, rather than a private symbol (e.g. like `targetSymbol`) on the node proxy itself.\n// The map behaves essentially the same, except that performing a lookup in the map will not perform a property read/get on the key object (as is the case with a symbol).\n// Since `SharedTreeNodes` are proxies with non-trivial `get` traps, this choice is meant to prevent the confusion of the lookup passing through multiple objects\n// via the trap, or the trap not properly handling the special symbol, etc.\n\n/** A reverse mapping of {@link proxySlot} that is updated at the same time. */\nconst proxyToAnchorNode = new WeakMap<TreeNode, AnchorNode>();\n\n// Map unhydrated nodes to and from their underlying flex tree implementation.\n// These maps are populated after a user calls `const proxy = new Foo({})` but before `proxy` is inserted into the tree and queried.\nconst proxyToMapTreeNode = new WeakMap<TreeNode, MapTreeNode>();\nconst mapTreeNodeToProxy = new WeakMap<MapTreeNode, TreeNode>();\n/** Used by `anchorProxy` as an optimization to ensure that only one anchor is remembered at a time for a given anchor node */\nconst anchorForgetters = new WeakMap<TreeNode, () => void>();\n\n/**\n * Creates an anchor node and associates it with the given proxy.\n * @privateRemarks Use `forgetters` to cleanup the anchor allocated by this function once the anchor is no longer needed.\n * In practice, this happens when either the anchor node is destroyed, or another anchor to the same node is created by a new flex node.\n */\nexport function anchorProxy(anchors: AnchorSet, path: UpPath, proxy: TreeNode): AnchorNode {\n\tassert(!anchorForgetters.has(proxy), 0x91c /* Proxy anchor should not be set twice */);\n\tconst anchor = anchors.track(path);\n\tconst anchorNode = anchors.locate(anchor) ?? fail(\"Expected anchor node to be present\");\n\tbindProxyToAnchorNode(proxy, anchorNode);\n\tconst forget = (): void => {\n\t\tif (anchors.locate(anchor)) {\n\t\t\tanchors.forget(anchor);\n\t\t}\n\t\tanchorForgetters.delete(proxy);\n\t\toff();\n\t};\n\tanchorForgetters.set(proxy, forget);\n\tconst off = anchorNode.on(\"afterDestroy\", forget);\n\treturn anchorNode;\n}\n\n/**\n * Retrieves the flex node associated with the given target via {@link setFlexNode}.\n * @remarks Fails if the flex node has not been set.\n */\nexport function getFlexNode(\n\tproxy: TypedNode<FlexObjectNodeSchema>,\n\tallowFreed?: true,\n): FlexTreeObjectNode;\nexport function getFlexNode(proxy: TreeArrayNode, allowFreed?: true): FlexTreeNode;\nexport function getFlexNode(\n\tproxy: TreeMapNode,\n\tallowFreed?: true,\n): FlexTreeMapNode<FlexMapNodeSchema<string, FlexFieldSchema<typeof FieldKinds.optional>>>;\nexport function getFlexNode(proxy: TreeNode, allowFreed?: true): FlexTreeNode;\nexport function getFlexNode(proxy: TreeNode, allowFreed = false): FlexTreeNode {\n\tconst anchorNode = proxyToAnchorNode.get(proxy);\n\tif (anchorNode !== undefined) {\n\t\t// The proxy is bound to an anchor node, but it may or may not have an actual flex node yet\n\t\tconst flexNode = anchorNode.slots.get(flexTreeSlot);\n\t\tif (flexNode !== undefined) {\n\t\t\treturn flexNode; // If it does have a flex node, return it...\n\t\t} // ...otherwise, the flex node must be created\n\t\tconst context = anchorNode.anchorSet.slots.get(ContextSlot) ?? fail(\"missing context\");\n\t\tconst cursor = context.checkout.forest.allocateCursor(\"getFlexNode\");\n\t\tcontext.checkout.forest.moveCursorToPath(anchorNode, cursor);\n\t\tconst newFlexNode = makeTree(context, cursor);\n\t\tcursor.free();\n\t\t// Calling this is a performance improvement, however, do this only after demand to avoid momentarily having no anchors to anchorNode\n\t\tanchorForgetters?.get(proxy)?.();\n\t\tif (!allowFreed) {\n\t\t\tassertFlexTreeEntityNotFreed(newFlexNode);\n\t\t}\n\t\treturn newFlexNode;\n\t}\n\n\treturn proxyToMapTreeNode.get(proxy) ?? fail(\"Expected raw tree node for proxy\");\n}\n\n/**\n * Retrieves the flex node associated with the given target via {@link setFlexNode}, if any.\n */\nexport function tryGetFlexNode(target: unknown): FlexTreeNode | undefined {\n\t// Calling 'WeakMap.get()' with primitives (numbers, strings, etc.) will return undefined.\n\t// This is in contrast to 'WeakMap.set()', which will throw a TypeError if given a non-object key.\n\treturn (\n\t\tproxyToAnchorNode.get(target as TreeNode)?.slots.get(flexTreeSlot) ??\n\t\tproxyToMapTreeNode.get(target as TreeNode)\n\t);\n}\n\n/**\n * Retrieves the proxy associated with the given flex node via {@link setFlexNode}, if any.\n */\nexport function tryGetProxy(flexNode: FlexTreeNode): TreeNode | undefined {\n\tif (isMapTreeNode(flexNode)) {\n\t\treturn mapTreeNodeToProxy.get(flexNode);\n\t}\n\treturn flexNode.anchorNode.slots.get(proxySlot);\n}\n\n/**\n * Associate the given proxy and the given flex node.\n * @returns The proxy\n * @remarks\n * This creates a 1:1 mapping between the proxy and tree node.\n * Either can be retrieved from the other via {@link getFlexNode}/{@link tryGetFlexNode} or {@link tryGetProxy}.\n * If the given proxy is already mapped to an flex node, the existing mapping will be overwritten.\n * If the given flex node is already mapped to a different proxy, this function will fail.\n */\nexport function setFlexNode<TProxy extends TreeNode>(\n\tproxy: TProxy,\n\tflexNode: FlexTreeNode,\n): TProxy {\n\tconst existingFlexNode = proxyToAnchorNode.get(proxy)?.slots.get(flexTreeSlot);\n\tassert(\n\t\texistingFlexNode === undefined,\n\t\t0x91d /* Cannot associate a flex node with multiple targets */,\n\t);\n\tif (isMapTreeNode(flexNode)) {\n\t\tproxyToMapTreeNode.set(proxy, flexNode);\n\t\tmapTreeNodeToProxy.set(flexNode, proxy);\n\t} else {\n\t\tassert(\n\t\t\ttryGetProxy(flexNode) === undefined,\n\t\t\t0x7f5 /* Cannot associate an flex node with multiple targets */,\n\t\t);\n\t\tbindProxyToAnchorNode(proxy, flexNode.anchorNode);\n\t}\n\treturn proxy;\n}\n\n/**\n * Bi-directionally associates the given proxy to the given anchor node.\n * @remarks Cleans up mappings to raw flex nodes - it is assumed that they are no longer needed once the proxy has an anchor node.\n */\nfunction bindProxyToAnchorNode(proxy: TreeNode, anchorNode: AnchorNode): void {\n\t// If the proxy currently has a raw node, forget it\n\tconst mapTreeNode = proxyToMapTreeNode.get(proxy);\n\tif (mapTreeNode !== undefined) {\n\t\tproxyToMapTreeNode.delete(proxy);\n\t\tmapTreeNodeToProxy.delete(mapTreeNode);\n\t}\n\t// Once a proxy has been associated with an anchor node, it should never change to another anchor node\n\tassert(\n\t\t!proxyToAnchorNode.has(proxy),\n\t\t0x91e /* Proxy has already been bound to a different anchor node */,\n\t);\n\tproxyToAnchorNode.set(proxy, anchorNode);\n\t// However, it's fine for an anchor node to rotate through different proxies when the content at that place in the tree is replaced.\n\tanchorNode.slots.set(proxySlot, proxy);\n\tgetKernel(proxy).hydrate(anchorNode);\n}\n\n/**\n * Given a node's schema, return the corresponding object in the proxy-based API.\n */\ntype TypedNode<TSchema extends FlexTreeNodeSchema> = TreeNode & WithType<TSchema[\"name\"]>;\n\nexport function createKernel(node: TreeNode): void {\n\ttreeNodeToKernel.set(node, new TreeNodeKernel(node));\n}\n\nexport function getKernel(node: TreeNode): TreeNodeKernel {\n\tconst kernel = treeNodeToKernel.get(node);\n\tassert(kernel !== undefined, 0x9b1 /* Expected tree node to have kernel */);\n\treturn kernel;\n}\n\nexport function tryDisposeTreeNode(anchorNode: AnchorNode): void {\n\tconst treeNode = anchorNode.slots.get(proxySlot);\n\tif (treeNode !== undefined) {\n\t\tconst kernel = treeNodeToKernel.get(treeNode);\n\t\tassert(kernel !== undefined, 0x9b2 /* Expected tree node to have kernel */);\n\t\tkernel.dispose();\n\t}\n}\n\nconst treeNodeToKernel = new WeakMap<TreeNode, TreeNodeKernel>();\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/simple-tree/tree.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/simple-tree/tree.ts"],"names":[],"mappings":"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"}

package/lib/simple-tree/tree.js

@@ -45,7 +45,7 @@ export function walkNodeSchema(schema, visitor, visitedSet) {
         }
     }
     else {
-        assert(schema.kind === NodeKind.Array || schema.kind === NodeKind.Map, "invalid schema");
+        assert(schema.kind === NodeKind.Array || schema.kind === NodeKind.Map, 0x9b3 /* invalid schema */);
         const childTypes = schema.info;
         walkFieldSchema(childTypes, visitor, visitedSet);
     }

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

@@ -1 +1 @@
-{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../src/simple-tree/tree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,EAEN,QAAQ,EACR,oBAAoB,GAKpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAgE3D,MAAM,+BAA+B,GAAwC;IAC5E,sBAAsB,EAAE,KAAK;CAC7B,CAAC;AA2BF;;;GAGG;AACH,MAAM,OAAO,qBAAqB;IAajC;;OAEG;IACH,YAAmB,KAAsC;QACxD,MAAM,MAAM,GAAG,EAAE,GAAG,+BAA+B,EAAE,GAAG,KAAK,EAAE,CAAC;QAChE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,sBAAsB,GAAG,MAAM,CAAC,sBAAsB,CAAC;QAE5D,0DAA0D;QAC1D,8JAA8J;QAC9J,wBAAwB;QACxB,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;QACtD,4DAA4D;QAC5D,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;CACD;AAED,MAAM,UAAU,cAAc,CAC7B,MAAsB,EACtB,OAAyC,EACzC,UAA+B;IAE/B,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,OAAO;IACR,CAAC;IACD,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,IAAI,MAAM,YAAY,cAAc,EAAE,CAAC;QACtC,gBAAgB;IACjB,CAAC;SAAM,IAAI,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;QACvC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YAC5C,gBAAgB,CAAC,KAAK,CAAC,cAAc,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;QAC7D,CAAC;IACF,CAAC;SAAM,CAAC;QACP,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;QACzF,MAAM,UAAU,GAAG,MAAM,CAAC,IAA4B,CAAC;QACvD,eAAe,CAAC,UAAU,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAClD,CAAC;IACD,kFAAkF;IAClF,4CAA4C;IAC5C,wGAAwG;IACxG,gIAAgI;IAChI,OAAO,CAAC,MAAM,CAAC,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,eAAe,CAC9B,MAA2B,EAC3B,OAAyC,EACzC,aAAkC,IAAI,GAAG,EAAE;IAE3C,gBAAgB,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,cAAc,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AACpF,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC/B,YAAsC,EACtC,OAAyC,EACzC,UAA+B;IAE/B,KAAK,MAAM,SAAS,IAAI,YAAY,EAAE,CAAC;QACtC,cAAc,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAChD,CAAC;AACF,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IFluidLoadable, IDisposable } from \"@fluidframework/core-interfaces\";\n\nimport type { CommitMetadata } from \"../core/index.js\";\nimport type { Listenable } from \"../events/index.js\";\nimport type { RevertibleFactory } from \"../shared-tree/index.js\";\n\nimport {\n\ttype ImplicitAllowedTypes,\n\tNodeKind,\n\tnormalizeFieldSchema,\n\ttype ImplicitFieldSchema,\n\ttype InsertableTreeFieldFromImplicitField,\n\ttype TreeFieldFromImplicitField,\n\ttype TreeNodeSchema,\n} from \"./schemaTypes.js\";\nimport { toFlexSchema } from \"./toFlexSchema.js\";\nimport { LeafNodeSchema } from \"./leafNodeSchema.js\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport { isObjectNodeSchema } from \"./objectNode.js\";\nimport { markSchemaMostDerived } from \"./schemaFactory.js\";\n\n/**\n * Channel for a Fluid Tree DDS.\n * @remarks\n * Allows storing and collaboratively editing schema-aware hierarchial data.\n * @sealed @public\n */\nexport interface ITree extends IFluidLoadable {\n\t/**\n\t * Returns a {@link TreeView} using the provided schema.\n\t * If the stored schema is compatible with the view schema specified by `config`,\n\t * the returned {@link TreeView} will expose the root with a schema-aware API based on the provided view schema.\n\t * If the provided schema is incompatible with the stored schema, the view will instead expose a status indicating the incompatibility.\n\t *\n\t * @remarks\n\t * If the tree is uninitialized (has no schema and no content), use {@link TreeView.initialize} on the returned view to set the schema and content together.\n\t * Using `viewWith` followed by {@link TreeView.upgradeSchema} to initialize only the schema for a document is technically valid when the schema\n\t * permits trees with no content.\n\t *\n\t * Note that other clients can modify the document at any time, causing the view to change its compatibility status: see {@link TreeView.events} for how to handle invalidation in these cases.\n\t *\n\t * Only one schematized view may exist for a given ITree at a time.\n\t * If creating a second, the first must be disposed before calling `viewWith` again.\n\t *\n\t * @privateRemarks\n\t * TODO: Provide a way to make a generic view schema for any document.\n\t * TODO: Support adapters for handling out-of-schema data.\n\t *\n\t * Doing initialization here allows a small API that is hard to use incorrectly.\n\t * Other approaches tend to have easy-to-make mistakes.\n\t * For example, having a separate initialization function means apps can forget to call it, making an app that can only open existing documents,\n\t * or call it unconditionally leaving an app that can only create new documents.\n\t * It also would require the schema to be passed into separate places and could cause issues if they didn't match.\n\t * Since the initialization function couldn't return a typed tree, the type checking wouldn't help catch that.\n\t * Also, if an app manages to create a document, but the initialization fails to get persisted, an app that only calls the initialization function\n\t * on the create code-path (for example how a schematized factory might do it),\n\t * would leave the document in an unusable state which could not be repaired when it is reopened (by the same or other clients).\n\t * Additionally, once out of schema content adapters are properly supported (with lazy document updates),\n\t * this initialization could become just another out of schema content adapter and this initialization is no longer a special case.\n\t */\n\tviewWith<TRoot extends ImplicitFieldSchema>(\n\t\tconfig: TreeViewConfiguration<TRoot>,\n\t): TreeView<TRoot>;\n}\n\n/**\n * Options when constructing a tree view.\n * @public\n */\nexport interface ITreeConfigurationOptions {\n\t/**\n\t * If `true`, the tree will validate new content against its stored schema at insertion time\n\t * and throw an error if the new content doesn't match the expected schema.\n\t *\n\t * @defaultValue `false`.\n\t *\n\t * @remarks Enabling schema validation has a performance penalty when inserting new content into the tree because\n\t * additional checks are done. Enable this option only in scenarios where you are ok with that operation being a\n\t * bit slower.\n\t */\n\tenableSchemaValidation?: boolean;\n}\n\nconst defaultTreeConfigurationOptions: Required<ITreeConfigurationOptions> = {\n\tenableSchemaValidation: false,\n};\n\n/**\n * Property-bag configuration for {@link TreeViewConfiguration} construction.\n * @public\n */\nexport interface ITreeViewConfiguration<\n\tTSchema extends ImplicitFieldSchema = ImplicitFieldSchema,\n> {\n\t/**\n\t * The schema which the application wants to view the tree with.\n\t */\n\treadonly schema: TSchema;\n\n\t/**\n\t * If `true`, the tree will validate new content against its stored schema at insertion time\n\t * and throw an error if the new content doesn't match the expected schema.\n\t *\n\t * @defaultValue `false`.\n\t *\n\t * @remarks Enabling schema validation has a performance penalty when inserting new content into the tree because\n\t * additional checks are done. Enable this option only in scenarios where you are ok with that operation being a\n\t * bit slower.\n\t */\n\treadonly enableSchemaValidation?: boolean;\n}\n\n/**\n * Configuration for {@link ITree.viewWith}.\n * @sealed @public\n */\nexport class TreeViewConfiguration<TSchema extends ImplicitFieldSchema = ImplicitFieldSchema>\n\timplements Required<ITreeViewConfiguration<TSchema>>\n{\n\t/**\n\t * {@inheritDoc ITreeViewConfiguration.schema}\n\t */\n\tpublic readonly schema: TSchema;\n\n\t/**\n\t * {@inheritDoc ITreeViewConfiguration.enableSchemaValidation}\n\t */\n\tpublic readonly enableSchemaValidation: boolean;\n\n\t/**\n\t * @param props - Property bag of configuration options.\n\t */\n\tpublic constructor(props: ITreeViewConfiguration<TSchema>) {\n\t\tconst config = { ...defaultTreeConfigurationOptions, ...props };\n\t\tthis.schema = config.schema;\n\t\tthis.enableSchemaValidation = config.enableSchemaValidation;\n\n\t\t// Ensure all reachable schema are marked as most derived.\n\t\t// This ensures if multiple schema extending the same schema factory generated class are present (or have been constructed, or get constructed in the future),\n\t\t// an error is reported.\n\t\twalkFieldSchema(config.schema, markSchemaMostDerived);\n\t\t// Eagerly perform this conversion to surface errors sooner.\n\t\ttoFlexSchema(config.schema);\n\t}\n}\n\nexport function walkNodeSchema(\n\tschema: TreeNodeSchema,\n\tvisitor: (schema: TreeNodeSchema) => void,\n\tvisitedSet: Set<TreeNodeSchema>,\n): void {\n\tif (visitedSet.has(schema)) {\n\t\treturn;\n\t}\n\tvisitedSet.add(schema);\n\tif (schema instanceof LeafNodeSchema) {\n\t\t// nothing to do\n\t} else if (isObjectNodeSchema(schema)) {\n\t\tfor (const field of schema.fields.values()) {\n\t\t\twalkAllowedTypes(field.allowedTypeSet, visitor, visitedSet);\n\t\t}\n\t} else {\n\t\tassert(schema.kind === NodeKind.Array || schema.kind === NodeKind.Map, \"invalid schema\");\n\t\tconst childTypes = schema.info as ImplicitAllowedTypes;\n\t\twalkFieldSchema(childTypes, visitor, visitedSet);\n\t}\n\t// This visit is done at the end so the traversal order is most inner types first.\n\t// This was picked since when fixing errors,\n\t// working from the inner types out to the types that use them will probably go better than the reverse.\n\t// This does not however ensure all types referenced by a type are visited before it, since in recursive cases thats impossible.\n\tvisitor(schema);\n}\n\nexport function walkFieldSchema(\n\tschema: ImplicitFieldSchema,\n\tvisitor: (schema: TreeNodeSchema) => void,\n\tvisitedSet: Set<TreeNodeSchema> = new Set(),\n): void {\n\twalkAllowedTypes(normalizeFieldSchema(schema).allowedTypeSet, visitor, visitedSet);\n}\n\nexport function walkAllowedTypes(\n\tallowedTypes: Iterable<TreeNodeSchema>,\n\tvisitor: (schema: TreeNodeSchema) => void,\n\tvisitedSet: Set<TreeNodeSchema>,\n): void {\n\tfor (const childType of allowedTypes) {\n\t\twalkNodeSchema(childType, visitor, visitedSet);\n\t}\n}\n\n/**\n * An editable view of a (version control style) branch of a shared tree based on some schema.\n *\n * This schema--known as the view schema--may or may not align the stored schema of the document.\n * Information about discrepancies between the two schemas is available via {@link TreeView.compatibility | compatibility}.\n *\n * Application authors are encouraged to read [schema-evolution.md](../../docs/user-facing/schema-evolution.md) and\n * choose a schema compatibility policy that aligns with their application's needs.\n *\n * @privateRemarks\n * From an API design perspective, `upgradeSchema` could be merged into `viewWith` and/or `viewWith` could return errors explicitly on incompatible documents.\n * Such approaches would make it discoverable that out of schema handling may need to be done.\n * Doing that would however complicate trivial \"hello world\" style example slightly, as well as be a breaking API change.\n * It also seems more complex to handle invalidation with that pattern.\n * Thus this design was chosen at the risk of apps blindly accessing `root` then breaking unexpectedly when the document is incompatible.\n * @sealed @public\n */\nexport interface TreeView<TSchema extends ImplicitFieldSchema> extends IDisposable {\n\t/**\n\t * The current root of the tree.\n\t *\n\t * If the view schema not sufficiently compatible with the stored schema, accessing this will throw.\n\t * To handle this case, check {@link TreeView.compatibility | compatibility}'s {@link SchemaCompatibilityStatus.canView | canView} before using.\n\t *\n\t * To get notified about changes to this field,\n\t * use {@link TreeViewEvents.rootChanged} via `view.events.on(\"rootChanged\", callback)`.\n\t *\n\t * To get notified about changes to stored schema (which may affect compatibility between this view's schema and\n\t * the stored schema), use {@link TreeViewEvents.schemaChanged} via `view.events.on(\"schemaChanged\", callback)`.\n\t */\n\tget root(): TreeFieldFromImplicitField<TSchema>;\n\n\tset root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);\n\n\t/**\n\t * Description of the current compatibility status between the view schema and stored schema.\n\t *\n\t * {@link TreeViewEvents.schemaChanged} is fired when the compatibility status changes.\n\t */\n\treadonly compatibility: SchemaCompatibilityStatus;\n\n\t/**\n\t * When the schemas are not an exact match and {@link SchemaCompatibilityStatus.canUpgrade} is true,\n\t * this can be used to modify the stored schema to make it match the view schema.\n\t * This will update the compatibility state, and allow access to `root`.\n\t * Beware that this may impact other clients' ability to view the document depending on the application's schema compatibility policy!\n\t * @remarks\n\t * It is an error to call this when {@link SchemaCompatibilityStatus.canUpgrade} is false, and a no-op when the stored and view schema are already an exact match.\n\t * @privateRemarks\n\t * In the future, more upgrade options could be provided here.\n\t * Some options that could be added:\n\t * - check the actual document contents (not just the schema) and attempt an atomic document update if the data is compatible.\n\t * - apply converters and upgrade the document.\n\t * - apply converters to lazily to adapt the document to the requested view schema (with optional lazy schema updates or transparent conversions on write).\n\t */\n\tupgradeSchema(): void;\n\n\t/**\n\t * Initialize the tree, setting the stored schema to match this view's schema and setting the tree content.\n\t *\n\t * Only valid to call when this view's {@link SchemaCompatibilityStatus.canInitialize} is true.\n\t *\n\t * Applications should typically call this function before attaching a `SharedTree`.\n\t * @param content - The content to initialize the tree with.\n\t */\n\tinitialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;\n\n\t/**\n\t * Events for the tree.\n\t */\n\treadonly events: Listenable<TreeViewEvents>;\n}\n\n/**\n * Information about a view schema's compatibility with the document's stored schema.\n *\n * See SharedTree's README for more information about choosing a compatibility policy.\n * @sealed @public\n */\nexport interface SchemaCompatibilityStatus {\n\t/**\n\t * Whether the view schema allows exactly the same set of documents as the stored schema.\n\t *\n\t * @remarks\n\t * Equivalence here is defined in terms of allowed documents because there are some degenerate cases where schemas are not\n\t * exact matches in a strict (schema-based) sense but still allow the same documents, and the document notion is more useful to applications.\n\t *\n\t * Examples which are expressible where this may occur include:\n\t * - schema repository `A` has extra schema which schema `B` doesn't have, but they are unused (i.e. not reachable from the root schema)\n\t * - field in schema `A` has allowed field members which the corresponding field in schema `B` does not have, but those types are not constructible (ex: an object node type containing a required field with no allowed types)\n\t *\n\t * These cases are typically not interesting to applications.\n\t */\n\treadonly isEquivalent: boolean;\n\n\t/**\n\t * Whether the current view schema is sufficiently compatible with the stored schema to allow viewing tree data.\n\t * If false, {@link TreeView.root} will throw upon access.\n\t *\n\t * Currently, this field is true iff `isEquivalent` is true.\n\t * Do not rely on this:\n\t * there are near-term plans to extend support for viewing documents when the stored schema contains additional optional fields not present in the view schema.\n\t * The other two types of backward-compatible changes (field relaxations and addition of allowed field types) will eventually be supported as well,\n\t * likely through out-of-schema content adapters that the application can provide alongside their view schema.\n\t *\n\t * Be aware that even with these SharedTree limitations fixed, application logic may not correctly tolerate the documents allowable by the stored schema!\n\t * Application authors are encouraged to read docs/user-facing/schema-evolution.md and choose a schema compatibility policy that\n\t * aligns with their application's needs.\n\t *\n\t * @remarks\n\t * When the documents allowed by the view schema is a strict superset of those by the stored schema,\n\t * this is false because writes to the document using the view schema could make the document violate its stored schema.\n\t * In this case, the stored schema could be updated to match the provided view schema, allowing read-write access to the tree.\n\t * See {@link SchemaCompatibilityStatus.canUpgrade}.\n\t *\n\t * Future version of SharedTree may provide readonly access to the document in this case because that would be safe,\n\t * but this is not currently supported.\n\t *\n\t * @privateRemarks\n\t * A necessary condition for this to be true is that the documents allowed by the view schema are a subset of those allowed by the stored schema.\n\t * This is not sufficient: the simple-tree layer's read APIs do not tolerate out-of-schema data.\n\t * For example, if the view schema for a node has a required `Point` field but the stored schema has an optional `Point` field,\n\t * read APIs on the view schema do not work correctly when the document has a node with a missing `Point` field.\n\t * Similar issues happen when the view schema has a field with less allowed types than the stored schema and the document actually leverages those types.\n\t */\n\treadonly canView: boolean;\n\n\t/**\n\t * True iff the view schema supports all possible documents permitted by the stored schema.\n\t * When true, it is valid to call {@link TreeView.upgradeSchema} (though if the stored schema is already an exact match, this is a no-op).\n\t */\n\treadonly canUpgrade: boolean;\n\n\t/**\n\t * True iff the document is uninitialized (i.e. it has no schema and no content).\n\t *\n\t * To initialize the document, call {@link TreeView.initialize}.\n\t *\n\t * @remarks\n\t * It's not necessary to check this field before calling {@link TreeView.initialize} in most scenarios; application authors typically know from\n\t * context that they're in a flow which creates a new `SharedTree` and would like to initialize it.\n\t */\n\treadonly canInitialize: boolean;\n\n\t// TODO: Consider extending this status to include:\n\t// - application-defined metadata about the stored schema\n\t// - details about the differences between the stored and view schema sufficient for implementing \"safe mismatch\" policies\n}\n\n/**\n * Events for {@link TreeView}.\n * @sealed @public\n */\nexport interface TreeViewEvents {\n\t/**\n\t * Raised whenever {@link TreeView.root} is invalidated.\n\t *\n\t * This includes changes to the document schema.\n\t * It also includes changes to the field containing the root such as setting or clearing an optional root or changing which node is the root.\n\t * This does NOT include changes to the content (fields/children) of the root node: for that case subscribe to events on the root node.\n\t */\n\trootChanged(): void;\n\n\t/**\n\t * The stored schema for the document has changed.\n\t * This may affect the compatibility between the view schema and the stored schema, and thus the ability to use the view.\n\t *\n\t * @remarks\n\t * This event implies that the old {@link TreeView.root} is no longer valid, but applications need not handle that separately:\n\t * {@link TreeViewEvents.rootChanged} will be fired after this event.\n\t */\n\tschemaChanged(): void;\n\n\t/**\n\t * Fired when:\n\t * - a local commit is applied outside of a transaction\n\t * - a local transaction is committed\n\t *\n\t * The event is not fired when:\n\t * - a local commit is applied within a transaction\n\t * - a remote commit is applied\n\t *\n\t * @param data - information about the commit that was applied\n\t * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,\n\t * this commit is not revertible.\n\t */\n\tcommitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;\n}\n"]}
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../src/simple-tree/tree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,EAEN,QAAQ,EACR,oBAAoB,GAKpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAgE3D,MAAM,+BAA+B,GAAwC;IAC5E,sBAAsB,EAAE,KAAK;CAC7B,CAAC;AA2BF;;;GAGG;AACH,MAAM,OAAO,qBAAqB;IAajC;;OAEG;IACH,YAAmB,KAAsC;QACxD,MAAM,MAAM,GAAG,EAAE,GAAG,+BAA+B,EAAE,GAAG,KAAK,EAAE,CAAC;QAChE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,sBAAsB,GAAG,MAAM,CAAC,sBAAsB,CAAC;QAE5D,0DAA0D;QAC1D,8JAA8J;QAC9J,wBAAwB;QACxB,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;QACtD,4DAA4D;QAC5D,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;CACD;AAED,MAAM,UAAU,cAAc,CAC7B,MAAsB,EACtB,OAAyC,EACzC,UAA+B;IAE/B,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,OAAO;IACR,CAAC;IACD,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,IAAI,MAAM,YAAY,cAAc,EAAE,CAAC;QACtC,gBAAgB;IACjB,CAAC;SAAM,IAAI,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;QACvC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YAC5C,gBAAgB,CAAC,KAAK,CAAC,cAAc,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;QAC7D,CAAC;IACF,CAAC;SAAM,CAAC;QACP,MAAM,CACL,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,GAAG,EAC9D,KAAK,CAAC,oBAAoB,CAC1B,CAAC;QACF,MAAM,UAAU,GAAG,MAAM,CAAC,IAA4B,CAAC;QACvD,eAAe,CAAC,UAAU,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAClD,CAAC;IACD,kFAAkF;IAClF,4CAA4C;IAC5C,wGAAwG;IACxG,gIAAgI;IAChI,OAAO,CAAC,MAAM,CAAC,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,eAAe,CAC9B,MAA2B,EAC3B,OAAyC,EACzC,aAAkC,IAAI,GAAG,EAAE;IAE3C,gBAAgB,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,cAAc,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AACpF,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC/B,YAAsC,EACtC,OAAyC,EACzC,UAA+B;IAE/B,KAAK,MAAM,SAAS,IAAI,YAAY,EAAE,CAAC;QACtC,cAAc,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAChD,CAAC;AACF,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IFluidLoadable, IDisposable } from \"@fluidframework/core-interfaces\";\n\nimport type { CommitMetadata } from \"../core/index.js\";\nimport type { Listenable } from \"../events/index.js\";\nimport type { RevertibleFactory } from \"../shared-tree/index.js\";\n\nimport {\n\ttype ImplicitAllowedTypes,\n\tNodeKind,\n\tnormalizeFieldSchema,\n\ttype ImplicitFieldSchema,\n\ttype InsertableTreeFieldFromImplicitField,\n\ttype TreeFieldFromImplicitField,\n\ttype TreeNodeSchema,\n} from \"./schemaTypes.js\";\nimport { toFlexSchema } from \"./toFlexSchema.js\";\nimport { LeafNodeSchema } from \"./leafNodeSchema.js\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport { isObjectNodeSchema } from \"./objectNode.js\";\nimport { markSchemaMostDerived } from \"./schemaFactory.js\";\n\n/**\n * Channel for a Fluid Tree DDS.\n * @remarks\n * Allows storing and collaboratively editing schema-aware hierarchial data.\n * @sealed @public\n */\nexport interface ITree extends IFluidLoadable {\n\t/**\n\t * Returns a {@link TreeView} using the provided schema.\n\t * If the stored schema is compatible with the view schema specified by `config`,\n\t * the returned {@link TreeView} will expose the root with a schema-aware API based on the provided view schema.\n\t * If the provided schema is incompatible with the stored schema, the view will instead expose a status indicating the incompatibility.\n\t *\n\t * @remarks\n\t * If the tree is uninitialized (has no schema and no content), use {@link TreeView.initialize} on the returned view to set the schema and content together.\n\t * Using `viewWith` followed by {@link TreeView.upgradeSchema} to initialize only the schema for a document is technically valid when the schema\n\t * permits trees with no content.\n\t *\n\t * Note that other clients can modify the document at any time, causing the view to change its compatibility status: see {@link TreeView.events} for how to handle invalidation in these cases.\n\t *\n\t * Only one schematized view may exist for a given ITree at a time.\n\t * If creating a second, the first must be disposed before calling `viewWith` again.\n\t *\n\t * @privateRemarks\n\t * TODO: Provide a way to make a generic view schema for any document.\n\t * TODO: Support adapters for handling out-of-schema data.\n\t *\n\t * Doing initialization here allows a small API that is hard to use incorrectly.\n\t * Other approaches tend to have easy-to-make mistakes.\n\t * For example, having a separate initialization function means apps can forget to call it, making an app that can only open existing documents,\n\t * or call it unconditionally leaving an app that can only create new documents.\n\t * It also would require the schema to be passed into separate places and could cause issues if they didn't match.\n\t * Since the initialization function couldn't return a typed tree, the type checking wouldn't help catch that.\n\t * Also, if an app manages to create a document, but the initialization fails to get persisted, an app that only calls the initialization function\n\t * on the create code-path (for example how a schematized factory might do it),\n\t * would leave the document in an unusable state which could not be repaired when it is reopened (by the same or other clients).\n\t * Additionally, once out of schema content adapters are properly supported (with lazy document updates),\n\t * this initialization could become just another out of schema content adapter and this initialization is no longer a special case.\n\t */\n\tviewWith<TRoot extends ImplicitFieldSchema>(\n\t\tconfig: TreeViewConfiguration<TRoot>,\n\t): TreeView<TRoot>;\n}\n\n/**\n * Options when constructing a tree view.\n * @public\n */\nexport interface ITreeConfigurationOptions {\n\t/**\n\t * If `true`, the tree will validate new content against its stored schema at insertion time\n\t * and throw an error if the new content doesn't match the expected schema.\n\t *\n\t * @defaultValue `false`.\n\t *\n\t * @remarks Enabling schema validation has a performance penalty when inserting new content into the tree because\n\t * additional checks are done. Enable this option only in scenarios where you are ok with that operation being a\n\t * bit slower.\n\t */\n\tenableSchemaValidation?: boolean;\n}\n\nconst defaultTreeConfigurationOptions: Required<ITreeConfigurationOptions> = {\n\tenableSchemaValidation: false,\n};\n\n/**\n * Property-bag configuration for {@link TreeViewConfiguration} construction.\n * @public\n */\nexport interface ITreeViewConfiguration<\n\tTSchema extends ImplicitFieldSchema = ImplicitFieldSchema,\n> {\n\t/**\n\t * The schema which the application wants to view the tree with.\n\t */\n\treadonly schema: TSchema;\n\n\t/**\n\t * If `true`, the tree will validate new content against its stored schema at insertion time\n\t * and throw an error if the new content doesn't match the expected schema.\n\t *\n\t * @defaultValue `false`.\n\t *\n\t * @remarks Enabling schema validation has a performance penalty when inserting new content into the tree because\n\t * additional checks are done. Enable this option only in scenarios where you are ok with that operation being a\n\t * bit slower.\n\t */\n\treadonly enableSchemaValidation?: boolean;\n}\n\n/**\n * Configuration for {@link ITree.viewWith}.\n * @sealed @public\n */\nexport class TreeViewConfiguration<TSchema extends ImplicitFieldSchema = ImplicitFieldSchema>\n\timplements Required<ITreeViewConfiguration<TSchema>>\n{\n\t/**\n\t * {@inheritDoc ITreeViewConfiguration.schema}\n\t */\n\tpublic readonly schema: TSchema;\n\n\t/**\n\t * {@inheritDoc ITreeViewConfiguration.enableSchemaValidation}\n\t */\n\tpublic readonly enableSchemaValidation: boolean;\n\n\t/**\n\t * @param props - Property bag of configuration options.\n\t */\n\tpublic constructor(props: ITreeViewConfiguration<TSchema>) {\n\t\tconst config = { ...defaultTreeConfigurationOptions, ...props };\n\t\tthis.schema = config.schema;\n\t\tthis.enableSchemaValidation = config.enableSchemaValidation;\n\n\t\t// Ensure all reachable schema are marked as most derived.\n\t\t// This ensures if multiple schema extending the same schema factory generated class are present (or have been constructed, or get constructed in the future),\n\t\t// an error is reported.\n\t\twalkFieldSchema(config.schema, markSchemaMostDerived);\n\t\t// Eagerly perform this conversion to surface errors sooner.\n\t\ttoFlexSchema(config.schema);\n\t}\n}\n\nexport function walkNodeSchema(\n\tschema: TreeNodeSchema,\n\tvisitor: (schema: TreeNodeSchema) => void,\n\tvisitedSet: Set<TreeNodeSchema>,\n): void {\n\tif (visitedSet.has(schema)) {\n\t\treturn;\n\t}\n\tvisitedSet.add(schema);\n\tif (schema instanceof LeafNodeSchema) {\n\t\t// nothing to do\n\t} else if (isObjectNodeSchema(schema)) {\n\t\tfor (const field of schema.fields.values()) {\n\t\t\twalkAllowedTypes(field.allowedTypeSet, visitor, visitedSet);\n\t\t}\n\t} else {\n\t\tassert(\n\t\t\tschema.kind === NodeKind.Array || schema.kind === NodeKind.Map,\n\t\t\t0x9b3 /* invalid schema */,\n\t\t);\n\t\tconst childTypes = schema.info as ImplicitAllowedTypes;\n\t\twalkFieldSchema(childTypes, visitor, visitedSet);\n\t}\n\t// This visit is done at the end so the traversal order is most inner types first.\n\t// This was picked since when fixing errors,\n\t// working from the inner types out to the types that use them will probably go better than the reverse.\n\t// This does not however ensure all types referenced by a type are visited before it, since in recursive cases thats impossible.\n\tvisitor(schema);\n}\n\nexport function walkFieldSchema(\n\tschema: ImplicitFieldSchema,\n\tvisitor: (schema: TreeNodeSchema) => void,\n\tvisitedSet: Set<TreeNodeSchema> = new Set(),\n): void {\n\twalkAllowedTypes(normalizeFieldSchema(schema).allowedTypeSet, visitor, visitedSet);\n}\n\nexport function walkAllowedTypes(\n\tallowedTypes: Iterable<TreeNodeSchema>,\n\tvisitor: (schema: TreeNodeSchema) => void,\n\tvisitedSet: Set<TreeNodeSchema>,\n): void {\n\tfor (const childType of allowedTypes) {\n\t\twalkNodeSchema(childType, visitor, visitedSet);\n\t}\n}\n\n/**\n * An editable view of a (version control style) branch of a shared tree based on some schema.\n *\n * This schema--known as the view schema--may or may not align the stored schema of the document.\n * Information about discrepancies between the two schemas is available via {@link TreeView.compatibility | compatibility}.\n *\n * Application authors are encouraged to read [schema-evolution.md](../../docs/user-facing/schema-evolution.md) and\n * choose a schema compatibility policy that aligns with their application's needs.\n *\n * @privateRemarks\n * From an API design perspective, `upgradeSchema` could be merged into `viewWith` and/or `viewWith` could return errors explicitly on incompatible documents.\n * Such approaches would make it discoverable that out of schema handling may need to be done.\n * Doing that would however complicate trivial \"hello world\" style example slightly, as well as be a breaking API change.\n * It also seems more complex to handle invalidation with that pattern.\n * Thus this design was chosen at the risk of apps blindly accessing `root` then breaking unexpectedly when the document is incompatible.\n * @sealed @public\n */\nexport interface TreeView<TSchema extends ImplicitFieldSchema> extends IDisposable {\n\t/**\n\t * The current root of the tree.\n\t *\n\t * If the view schema not sufficiently compatible with the stored schema, accessing this will throw.\n\t * To handle this case, check {@link TreeView.compatibility | compatibility}'s {@link SchemaCompatibilityStatus.canView | canView} before using.\n\t *\n\t * To get notified about changes to this field,\n\t * use {@link TreeViewEvents.rootChanged} via `view.events.on(\"rootChanged\", callback)`.\n\t *\n\t * To get notified about changes to stored schema (which may affect compatibility between this view's schema and\n\t * the stored schema), use {@link TreeViewEvents.schemaChanged} via `view.events.on(\"schemaChanged\", callback)`.\n\t */\n\tget root(): TreeFieldFromImplicitField<TSchema>;\n\n\tset root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);\n\n\t/**\n\t * Description of the current compatibility status between the view schema and stored schema.\n\t *\n\t * {@link TreeViewEvents.schemaChanged} is fired when the compatibility status changes.\n\t */\n\treadonly compatibility: SchemaCompatibilityStatus;\n\n\t/**\n\t * When the schemas are not an exact match and {@link SchemaCompatibilityStatus.canUpgrade} is true,\n\t * this can be used to modify the stored schema to make it match the view schema.\n\t * This will update the compatibility state, and allow access to `root`.\n\t * Beware that this may impact other clients' ability to view the document depending on the application's schema compatibility policy!\n\t * @remarks\n\t * It is an error to call this when {@link SchemaCompatibilityStatus.canUpgrade} is false, and a no-op when the stored and view schema are already an exact match.\n\t * @privateRemarks\n\t * In the future, more upgrade options could be provided here.\n\t * Some options that could be added:\n\t * - check the actual document contents (not just the schema) and attempt an atomic document update if the data is compatible.\n\t * - apply converters and upgrade the document.\n\t * - apply converters to lazily to adapt the document to the requested view schema (with optional lazy schema updates or transparent conversions on write).\n\t */\n\tupgradeSchema(): void;\n\n\t/**\n\t * Initialize the tree, setting the stored schema to match this view's schema and setting the tree content.\n\t *\n\t * Only valid to call when this view's {@link SchemaCompatibilityStatus.canInitialize} is true.\n\t *\n\t * Applications should typically call this function before attaching a `SharedTree`.\n\t * @param content - The content to initialize the tree with.\n\t */\n\tinitialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;\n\n\t/**\n\t * Events for the tree.\n\t */\n\treadonly events: Listenable<TreeViewEvents>;\n}\n\n/**\n * Information about a view schema's compatibility with the document's stored schema.\n *\n * See SharedTree's README for more information about choosing a compatibility policy.\n * @sealed @public\n */\nexport interface SchemaCompatibilityStatus {\n\t/**\n\t * Whether the view schema allows exactly the same set of documents as the stored schema.\n\t *\n\t * @remarks\n\t * Equivalence here is defined in terms of allowed documents because there are some degenerate cases where schemas are not\n\t * exact matches in a strict (schema-based) sense but still allow the same documents, and the document notion is more useful to applications.\n\t *\n\t * Examples which are expressible where this may occur include:\n\t * - schema repository `A` has extra schema which schema `B` doesn't have, but they are unused (i.e. not reachable from the root schema)\n\t * - field in schema `A` has allowed field members which the corresponding field in schema `B` does not have, but those types are not constructible (ex: an object node type containing a required field with no allowed types)\n\t *\n\t * These cases are typically not interesting to applications.\n\t */\n\treadonly isEquivalent: boolean;\n\n\t/**\n\t * Whether the current view schema is sufficiently compatible with the stored schema to allow viewing tree data.\n\t * If false, {@link TreeView.root} will throw upon access.\n\t *\n\t * Currently, this field is true iff `isEquivalent` is true.\n\t * Do not rely on this:\n\t * there are near-term plans to extend support for viewing documents when the stored schema contains additional optional fields not present in the view schema.\n\t * The other two types of backward-compatible changes (field relaxations and addition of allowed field types) will eventually be supported as well,\n\t * likely through out-of-schema content adapters that the application can provide alongside their view schema.\n\t *\n\t * Be aware that even with these SharedTree limitations fixed, application logic may not correctly tolerate the documents allowable by the stored schema!\n\t * Application authors are encouraged to read docs/user-facing/schema-evolution.md and choose a schema compatibility policy that\n\t * aligns with their application's needs.\n\t *\n\t * @remarks\n\t * When the documents allowed by the view schema is a strict superset of those by the stored schema,\n\t * this is false because writes to the document using the view schema could make the document violate its stored schema.\n\t * In this case, the stored schema could be updated to match the provided view schema, allowing read-write access to the tree.\n\t * See {@link SchemaCompatibilityStatus.canUpgrade}.\n\t *\n\t * Future version of SharedTree may provide readonly access to the document in this case because that would be safe,\n\t * but this is not currently supported.\n\t *\n\t * @privateRemarks\n\t * A necessary condition for this to be true is that the documents allowed by the view schema are a subset of those allowed by the stored schema.\n\t * This is not sufficient: the simple-tree layer's read APIs do not tolerate out-of-schema data.\n\t * For example, if the view schema for a node has a required `Point` field but the stored schema has an optional `Point` field,\n\t * read APIs on the view schema do not work correctly when the document has a node with a missing `Point` field.\n\t * Similar issues happen when the view schema has a field with less allowed types than the stored schema and the document actually leverages those types.\n\t */\n\treadonly canView: boolean;\n\n\t/**\n\t * True iff the view schema supports all possible documents permitted by the stored schema.\n\t * When true, it is valid to call {@link TreeView.upgradeSchema} (though if the stored schema is already an exact match, this is a no-op).\n\t */\n\treadonly canUpgrade: boolean;\n\n\t/**\n\t * True iff the document is uninitialized (i.e. it has no schema and no content).\n\t *\n\t * To initialize the document, call {@link TreeView.initialize}.\n\t *\n\t * @remarks\n\t * It's not necessary to check this field before calling {@link TreeView.initialize} in most scenarios; application authors typically know from\n\t * context that they're in a flow which creates a new `SharedTree` and would like to initialize it.\n\t */\n\treadonly canInitialize: boolean;\n\n\t// TODO: Consider extending this status to include:\n\t// - application-defined metadata about the stored schema\n\t// - details about the differences between the stored and view schema sufficient for implementing \"safe mismatch\" policies\n}\n\n/**\n * Events for {@link TreeView}.\n * @sealed @public\n */\nexport interface TreeViewEvents {\n\t/**\n\t * Raised whenever {@link TreeView.root} is invalidated.\n\t *\n\t * This includes changes to the document schema.\n\t * It also includes changes to the field containing the root such as setting or clearing an optional root or changing which node is the root.\n\t * This does NOT include changes to the content (fields/children) of the root node: for that case subscribe to events on the root node.\n\t */\n\trootChanged(): void;\n\n\t/**\n\t * The stored schema for the document has changed.\n\t * This may affect the compatibility between the view schema and the stored schema, and thus the ability to use the view.\n\t *\n\t * @remarks\n\t * This event implies that the old {@link TreeView.root} is no longer valid, but applications need not handle that separately:\n\t * {@link TreeViewEvents.rootChanged} will be fired after this event.\n\t */\n\tschemaChanged(): void;\n\n\t/**\n\t * Fired when:\n\t * - a local commit is applied outside of a transaction\n\t * - a local transaction is committed\n\t *\n\t * The event is not fired when:\n\t * - a local commit is applied within a transaction\n\t * - a remote commit is applied\n\t *\n\t * @param data - information about the commit that was applied\n\t * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,\n\t * this commit is not revertible.\n\t */\n\tcommitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;\n}\n"]}

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

@@ -4,7 +4,7 @@
  */
 import { type TreeStatus } from "../feature-libraries/index.js";
 import { NodeKind, type TreeLeafValue, type TreeNodeSchema, type ImplicitAllowedTypes, type TreeNodeFromImplicitAllowedTypes } from "./schemaTypes.js";
-import type { TreeNode } from "./types.js";
+import type { TreeNode, TreeChangeEvents } from "./types.js";
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
  * * @remarks
@@ -55,7 +55,7 @@ export interface TreeNodeApi {
     /**
      * Returns the {@link TreeStatus} of the given node.
      */
-    readonly status: (node: TreeNode) => TreeStatus;
+    status(node: TreeNode): TreeStatus;
     /**
      * Returns the {@link SchemaFactory.identifier | identifier} of the given node in the most compressed form possible.
      * @remarks
@@ -83,77 +83,4 @@ export declare const treeNodeApi: TreeNodeApi;
  * Returns undefined for other values.
  */
 export declare function tryGetSchema<T>(value: T): undefined | TreeNodeSchema<string, NodeKind, unknown, T>;
-/**
- * A collection of events that can be emitted by a {@link TreeNode}.
- *
- * @privateRemarks
- * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).
- * Probably have object node and map node specific APIs for this.
- *
- * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.
- *
- * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.
- * Some ideas:
- *
- * - treeChanged, but with some subtrees/fields/paths excluded
- * - helper to batch several nodeChanged calls to a treeChanged scope
- * - parent change (ex: registration on the parent field for a specific index: maybe allow it for a range. Ex: node event takes optional field and optional index range?)
- * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.
- * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)
- * to allow efficiently searching for new content (and initial content) of a given type.
- *
- * @sealed @public
- */
-export interface TreeChangeEvents {
-    /**
-     * Emitted by a node after a batch of changes has been applied to the tree, if a change affected the node, where a
-     * change is:
-     *
-     * - For an object node, when the value of one of its properties changes (i.e., the property's value is set
-     * to something else, including `undefined`).
-     *
-     * - For an array node, when an element is added, removed, or moved.
-     *
-     * - For a map node, when an entry is added, updated, or removed.
-     *
-     * @remarks
-     * This event is not emitted when:
-     *
-     * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing
-     * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the
-     * array/map node as one of its properties.
-     *
-     * - The node is moved to a different location in the tree or removed from the tree.
-     * In this case the event is emitted on the _parent_ node, not the node itself.
-     *
-     * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
-     * the client that made the original edit.
-     *
-     * When it is emitted, the tree is guaranteed to be in-schema.
-     *
-     * @privateRemarks
-     * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.
-     * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the
-     * node, or when the node has to be updated due to resolution of a merge conflict
-     * (for example a previously applied local change might be undone, then reapplied differently or not at all).
-     */
-    nodeChanged(): void;
-    /**
-     * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the
-     * subtree rooted at it.
-     *
-     * @remarks
-     * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.
-     * In that case it is emitted on the _parent_ node, not the node itself.
-     *
-     * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties
-     * of the node itself.
-     *
-     * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
-     * the client that made the original edit.
-     *
-     * When it is emitted, the tree is guaranteed to be in-schema.
-     */
-    treeChanged(): void;
-}
 //# sourceMappingURL=treeNodeApi.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"treeNodeApi.d.ts","sourceRoot":"","sources":["../../src/simple-tree/treeNodeApi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAEN,KAAK,UAAU,EAIf,MAAM,+BAA+B,CAAC;AAMvC,OAAO,EACN,QAAQ,EACR,KAAK,aAAa,EAClB,KAAK,cAAc,EAGnB,KAAK,oBAAoB,EACzB,KAAK,gCAAgC,EACrC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAW3C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC3B;;OAEG;IACH,MAAM,CAAC,CAAC,SAAS,QAAQ,GAAG,aAAa,EACxC,IAAI,EAAE,CAAC,GACL,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IAEhD;;;;;;;;OAQG;IACH,EAAE,CAAC,OAAO,SAAS,oBAAoB,EACtC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,OAAO,GACb,KAAK,IAAI,gCAAgC,CAAC,OAAO,CAAC,CAAC;IAEtD;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAE7C;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IAErC;;;;;;;OAOG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,gBAAgB,EAClC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC3B,MAAM,IAAI,CAAC;IAEd;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,UAAU,CAAC;IAEhD;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACrD;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,WAgGzB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,GACN,SAAS,GAAG,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAwB1D;AAmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB;;;;;;;;;;;;;;;OAeG;IACH,WAAW,IAAI,IAAI,CAAC;CACpB"}
+{"version":3,"file":"treeNodeApi.d.ts","sourceRoot":"","sources":["../../src/simple-tree/treeNodeApi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAEN,KAAK,UAAU,EAIf,MAAM,+BAA+B,CAAC;AAMvC,OAAO,EACN,QAAQ,EACR,KAAK,aAAa,EAClB,KAAK,cAAc,EAGnB,KAAK,oBAAoB,EACzB,KAAK,gCAAgC,EACrC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAY7D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC3B;;OAEG;IACH,MAAM,CAAC,CAAC,SAAS,QAAQ,GAAG,aAAa,EACxC,IAAI,EAAE,CAAC,GACL,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IAEhD;;;;;;;;OAQG;IACH,EAAE,CAAC,OAAO,SAAS,oBAAoB,EACtC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,OAAO,GACb,KAAK,IAAI,gCAAgC,CAAC,OAAO,CAAC,CAAC;IAEtD;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAE7C;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IAErC;;;;;;;OAOG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,gBAAgB,EAClC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC3B,MAAM,IAAI,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IAEnC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACrD;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,WAwFzB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,GACN,SAAS,GAAG,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAwB1D"}

package/lib/simple-tree/treeNodeApi.js

@@ -2,12 +2,12 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 import { Multiplicity, rootFieldKey } from "../core/index.js";
 import { isLazy, isTreeValue, FlexObjectNodeSchema, } from "../feature-libraries/index.js";
 import { fail, extractFromOpaque, isReadonlyArray } from "../util/index.js";
 import { getOrCreateNodeProxy, isTreeNode } from "./proxies.js";
-import { getFlexNode } from "./proxyBinding.js";
+import { getFlexNode, getKernel } from "./proxyBinding.js";
 import { tryGetSimpleNodeSchema } from "./schemaCaching.js";
 import { NodeKind, FieldSchema, } from "./schemaTypes.js";
 import { booleanSchema, handleSchema, nullSchema, numberSchema, stringSchema, } from "./leafNodeSchema.js";
@@ -17,7 +17,7 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
  * The `Tree` object holds various functions for analyzing {@link TreeNode}s.
  */
 export const treeNodeApi = {
-    parent: (node) => {
+    parent(node) {
         const editNode = getFlexNode(node).parentField.parent.parent;
         if (editNode === undefined) {
             return undefined;
@@ -26,7 +26,7 @@ export const treeNodeApi = {
         assert(!isTreeValue(output), 0x87f /* Parent can't be a leaf, so it should be a node not a value */);
         return output;
     },
-    key: (node) => {
+    key(node) {
         // If the parent is undefined, then this node is under the root field,
         // so we know its key is the special root one.
         const parent = treeNodeApi.parent(node);
@@ -41,21 +41,13 @@ export const treeNodeApi = {
         const viewKey = getViewKeyFromStoredKey(parentSchema, storedKey);
         return viewKey;
     },
-    on: (node, eventName, listener) => {
-        const flex = getFlexNode(node);
-        switch (eventName) {
-            case "nodeChanged":
-                return flex.on("nodeChanged", listener);
-            case "treeChanged":
-                return flex.on("treeChanged", listener);
-            default:
-                return unreachableCase(eventName);
-        }
+    on(node, eventName, listener) {
+        return getKernel(node).on(eventName, listener);
     },
-    status: (node) => {
-        return getFlexNode(node, true).treeStatus();
+    status(node) {
+        return getKernel(node).getStatus();
     },
-    is: (value, schema) => {
+    is(value, schema) {
         const actualSchema = tryGetSchema(value);
         if (actualSchema === undefined) {
             return false;

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

@@ -1 +1 @@
-{"version":3,"file":"treeNodeApi.js","sourceRoot":"","sources":["../../src/simple-tree/treeNodeApi.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, unreachableCase } from \"@fluidframework/core-utils/internal\";\n\nimport { Multiplicity, rootFieldKey } from \"../core/index.js\";\nimport {\n\ttype LazyItem,\n\ttype TreeStatus,\n\tisLazy,\n\tisTreeValue,\n\tFlexObjectNodeSchema,\n} from \"../feature-libraries/index.js\";\nimport { fail, extractFromOpaque, isReadonlyArray } from \"../util/index.js\";\n\nimport { getOrCreateNodeProxy, isTreeNode } from \"./proxies.js\";\nimport { getFlexNode } from \"./proxyBinding.js\";\nimport { tryGetSimpleNodeSchema } from \"./schemaCaching.js\";\nimport {\n\tNodeKind,\n\ttype TreeLeafValue,\n\ttype TreeNodeSchema,\n\ttype ImplicitFieldSchema,\n\tFieldSchema,\n\ttype ImplicitAllowedTypes,\n\ttype TreeNodeFromImplicitAllowedTypes,\n} from \"./schemaTypes.js\";\nimport type { TreeNode } from \"./types.js\";\nimport {\n\tbooleanSchema,\n\thandleSchema,\n\tnullSchema,\n\tnumberSchema,\n\tstringSchema,\n} from \"./leafNodeSchema.js\";\nimport { isFluidHandle } from \"@fluidframework/runtime-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\n/**\n * Provides various functions for analyzing {@link TreeNode}s.\n * * @remarks\n * This type should only be used via the public `Tree` export.\n * @privateRemarks\n * Due to limitations of API-Extractor link resolution, this type can't be moved into internalTypes but should be considered just an implementation detail of the `Tree` export.\n *\n * Inlining the typing of this interface onto the `Tree` object provides slightly different .d.ts generation,\n * which avoids typescript expanding the type of TreeNodeSchema and thus encountering\n * https://github.com/microsoft/rushstack/issues/1958.\n * @sealed @public\n */\nexport interface TreeNodeApi {\n\t/**\n\t * The schema information for this node.\n\t */\n\tschema<T extends TreeNode | TreeLeafValue>(\n\t\tnode: T,\n\t): TreeNodeSchema<string, NodeKind, unknown, T>;\n\n\t/**\n\t * Narrow the type of the given value if it satisfies the given schema.\n\t * @example\n\t * ```ts\n\t * if (node.is(myNode, Point)) {\n\t *     const y = myNode.y; // `myNode` is now known to satisfy the `Point` schema and therefore has a `y` coordinate.\n\t * }\n\t * ```\n\t */\n\tis<TSchema extends ImplicitAllowedTypes>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is TreeNodeFromImplicitAllowedTypes<TSchema>;\n\n\t/**\n\t * Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).\n\t */\n\tparent(node: TreeNode): TreeNode | undefined;\n\n\t/**\n\t * The key of the given node under its parent.\n\t * @remarks\n\t * If `node` is an element in a {@link (TreeArrayNode:interface)}, this returns the index of `node` in the array node (a `number`).\n\t * Otherwise, this returns the key of the field that it is under (a `string`).\n\t */\n\tkey(node: TreeNode): string | number;\n\n\t/**\n\t * Register an event listener on the given node.\n\t * @param node - The node whose events should be subscribed to.\n\t * @param eventName - Which event to subscribe to.\n\t * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.\n\t * @returns A callback function which will deregister the event.\n\t * This callback should be called only once.\n\t */\n\ton<K extends keyof TreeChangeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeChangeEvents[K],\n\t): () => void;\n\n\t/**\n\t * Returns the {@link TreeStatus} of the given node.\n\t */\n\treadonly status: (node: TreeNode) => TreeStatus;\n\n\t/**\n\t * Returns the {@link SchemaFactory.identifier | identifier} of the given node in the most compressed form possible.\n\t * @remarks\n\t * If the node's identifier is a valid UUID that was automatically generated by the SharedTree, then this will return a process-unique integer corresponding to that identifier.\n\t * This is useful for performance-sensitive scenarios involving many nodes with identifiers that need to be compactly retained in memory or used for efficient lookup.\n\t *\n\t * If the node's identifier is any other user-provided string, then this will return that string.\n\t *\n\t * If the node has no identifier (that is, it has no {@link SchemaFactory.identifier | identifier} field), then this returns `undefined`.\n\t *\n\t * If the node has more than one identifier, then this will throw an error.\n\t *\n\t * The returned integer must not be serialized or preserved outside of the current process.\n\t * Its lifetime is that of the current in-memory instance of the FF container for this client, and it is not guaranteed to be unique or stable outside of that context.\n\t * The same node's identifier may, for example, be different across multiple sessions for the same client and document, or different across two clients in the same session.\n\t */\n\tshortId(node: TreeNode): number | string | undefined;\n}\n\n/**\n * The `Tree` object holds various functions for analyzing {@link TreeNode}s.\n */\nexport const treeNodeApi: TreeNodeApi = {\n\tparent: (node: TreeNode): TreeNode | undefined => {\n\t\tconst editNode = getFlexNode(node).parentField.parent.parent;\n\t\tif (editNode === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst output = getOrCreateNodeProxy(editNode);\n\t\tassert(\n\t\t\t!isTreeValue(output),\n\t\t\t0x87f /* Parent can't be a leaf, so it should be a node not a value */,\n\t\t);\n\t\treturn output;\n\t},\n\tkey: (node: TreeNode) => {\n\t\t// If the parent is undefined, then this node is under the root field,\n\t\t// so we know its key is the special root one.\n\t\tconst parent = treeNodeApi.parent(node);\n\t\tif (parent === undefined) {\n\t\t\treturn rootFieldKey;\n\t\t}\n\n\t\t// The flex-domain strictly operates in terms of \"stored keys\".\n\t\t// To find the associated developer-facing \"view key\", we need to look up the field associated with\n\t\t// the stored key from the flex-domain, and get view key its simple-domain counterpart was created with.\n\t\tconst storedKey = getStoredKey(node);\n\t\tconst parentSchema = treeNodeApi.schema(parent);\n\t\tconst viewKey = getViewKeyFromStoredKey(parentSchema, storedKey);\n\t\treturn viewKey;\n\t},\n\ton: <K extends keyof TreeChangeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeChangeEvents[K],\n\t) => {\n\t\tconst flex = getFlexNode(node);\n\t\tswitch (eventName) {\n\t\t\tcase \"nodeChanged\":\n\t\t\t\treturn flex.on(\"nodeChanged\", listener);\n\t\t\tcase \"treeChanged\":\n\t\t\t\treturn flex.on(\"treeChanged\", listener);\n\t\t\tdefault:\n\t\t\t\treturn unreachableCase(eventName);\n\t\t}\n\t},\n\tstatus: (node: TreeNode) => {\n\t\treturn getFlexNode(node, true).treeStatus();\n\t},\n\tis: <TSchema extends ImplicitAllowedTypes>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is TreeNodeFromImplicitAllowedTypes<TSchema> => {\n\t\tconst actualSchema = tryGetSchema(value);\n\t\tif (actualSchema === undefined) {\n\t\t\treturn false;\n\t\t}\n\t\tif (isReadonlyArray<LazyItem<TreeNodeSchema>>(schema)) {\n\t\t\tfor (const singleSchema of schema) {\n\t\t\t\tconst testSchema = isLazy(singleSchema) ? singleSchema() : singleSchema;\n\t\t\t\tif (testSchema === actualSchema) {\n\t\t\t\t\treturn true;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn false;\n\t\t} else {\n\t\t\treturn (schema as TreeNodeSchema) === actualSchema;\n\t\t}\n\t},\n\tschema<T extends TreeNode | TreeLeafValue>(\n\t\tnode: T,\n\t): TreeNodeSchema<string, NodeKind, unknown, T> {\n\t\treturn tryGetSchema(node) ?? fail(\"Not a tree node\");\n\t},\n\tshortId(node: TreeNode): number | string | undefined {\n\t\tconst flexNode = getFlexNode(node);\n\t\tconst flexSchema = flexNode.schema;\n\t\tconst identifierFieldKeys =\n\t\t\tflexSchema instanceof FlexObjectNodeSchema ? flexSchema.identifierFieldKeys : [];\n\n\t\tswitch (identifierFieldKeys.length) {\n\t\t\tcase 0:\n\t\t\t\treturn undefined;\n\t\t\tcase 1: {\n\t\t\t\tconst identifier = flexNode.tryGetField(identifierFieldKeys[0])?.boxedAt(0);\n\t\t\t\tassert(identifier !== undefined, 0x927 /* The identifier must exist */);\n\t\t\t\tconst identifierValue = identifier.value as string;\n\t\t\t\tconst localNodeKey =\n\t\t\t\t\tidentifier.context.nodeKeyManager.tryLocalizeNodeKey(identifierValue);\n\t\t\t\treturn localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : identifierValue;\n\t\t\t}\n\t\t\tdefault:\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t\"shortId() may not be called on a node with more than one identifier. Consider converting extraneous identifier fields to string fields.\",\n\t\t\t\t);\n\t\t}\n\t},\n};\n\n/**\n * Returns a schema for a value if the value is a {@link TreeNode} or a {@link TreeLeafValue}.\n * Returns undefined for other values.\n */\nexport function tryGetSchema<T>(\n\tvalue: T,\n): undefined | TreeNodeSchema<string, NodeKind, unknown, T> {\n\ttype TOut = TreeNodeSchema<string, NodeKind, unknown, T>;\n\tswitch (typeof value) {\n\t\tcase \"string\":\n\t\t\treturn stringSchema as TOut;\n\t\tcase \"number\":\n\t\t\treturn numberSchema as TOut;\n\t\tcase \"boolean\":\n\t\t\treturn booleanSchema as TOut;\n\t\tcase \"object\": {\n\t\t\tif (isTreeNode(value)) {\n\t\t\t\t// This case could be optimized, for example by placing the simple schema in a symbol on tree nodes.\n\t\t\t\treturn tryGetSimpleNodeSchema(getFlexNode(value).schema) as TOut;\n\t\t\t}\n\t\t\tif (value === null) {\n\t\t\t\treturn nullSchema as TOut;\n\t\t\t}\n\t\t\tif (isFluidHandle(value)) {\n\t\t\t\treturn handleSchema as TOut;\n\t\t\t}\n\t\t}\n\t\tdefault:\n\t\t\treturn undefined;\n\t}\n}\n\n/**\n * Gets the stored key with which the provided node is associated in the parent.\n */\nfunction getStoredKey(node: TreeNode): string | number {\n\t// Note: the flex domain strictly works with \"stored keys\", and knows nothing about the developer-facing\n\t// \"view keys\".\n\tconst parentField = getFlexNode(node).parentField;\n\tif (parentField.parent.schema.kind.multiplicity === Multiplicity.Sequence) {\n\t\t// The parent of `node` is an array node\n\t\treturn parentField.index;\n\t}\n\n\t// The parent of `node` is an object, a map, or undefined (and therefore `node` is a root/detached node).\n\treturn parentField.parent.key;\n}\n\n/**\n * Given a node schema, gets the view key corresponding with the provided {@link FieldProps.key | stored key}.\n */\nfunction getViewKeyFromStoredKey(\n\tschema: TreeNodeSchema,\n\tstoredKey: string | number,\n): string | number {\n\t// Only object nodes have the concept of a \"stored key\", differentiated from the developer-facing \"view key\".\n\t// For any other kind of node, the stored key and the view key are the same.\n\tif (schema.kind !== NodeKind.Object) {\n\t\treturn storedKey;\n\t}\n\n\tconst fields = schema.info as Record<string, ImplicitFieldSchema>;\n\n\t// Invariants:\n\t// - The set of all view keys under an object must be unique.\n\t// - The set of all stored keys (including those implicitly created from view keys) must be unique.\n\t// To find the view key associated with the provided stored key, first check for any stored key matches (which are optionally populated).\n\t// If we don't find any, then search for a matching view key.\n\tfor (const [viewKey, fieldSchema] of Object.entries(fields)) {\n\t\tif (fieldSchema instanceof FieldSchema && fieldSchema.props?.key === storedKey) {\n\t\t\treturn viewKey;\n\t\t}\n\t}\n\n\tif (fields[storedKey] === undefined) {\n\t\tfail(\"Existing stored key should always map to a view key\");\n\t}\n\n\treturn storedKey;\n}\n\n/**\n * A collection of events that can be emitted by a {@link TreeNode}.\n *\n * @privateRemarks\n * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).\n * Probably have object node and map node specific APIs for this.\n *\n * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.\n *\n * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.\n * Some ideas:\n *\n * - treeChanged, but with some subtrees/fields/paths excluded\n * - helper to batch several nodeChanged calls to a treeChanged scope\n * - parent change (ex: registration on the parent field for a specific index: maybe allow it for a range. Ex: node event takes optional field and optional index range?)\n * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.\n * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)\n * to allow efficiently searching for new content (and initial content) of a given type.\n *\n * @sealed @public\n */\nexport interface TreeChangeEvents {\n\t/**\n\t * Emitted by a node after a batch of changes has been applied to the tree, if a change affected the node, where a\n\t * change is:\n\t *\n\t * - For an object node, when the value of one of its properties changes (i.e., the property's value is set\n\t * to something else, including `undefined`).\n\t *\n\t * - For an array node, when an element is added, removed, or moved.\n\t *\n\t * - For a map node, when an entry is added, updated, or removed.\n\t *\n\t * @remarks\n\t * This event is not emitted when:\n\t *\n\t * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing\n\t * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the\n\t * array/map node as one of its properties.\n\t *\n\t * - The node is moved to a different location in the tree or removed from the tree.\n\t * In this case the event is emitted on the _parent_ node, not the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When it is emitted, the tree is guaranteed to be in-schema.\n\t *\n\t * @privateRemarks\n\t * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.\n\t * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the\n\t * node, or when the node has to be updated due to resolution of a merge conflict\n\t * (for example a previously applied local change might be undone, then reapplied differently or not at all).\n\t */\n\tnodeChanged(): void;\n\n\t/**\n\t * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the\n\t * subtree rooted at it.\n\t *\n\t * @remarks\n\t * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.\n\t * In that case it is emitted on the _parent_ node, not the node itself.\n\t *\n\t * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties\n\t * of the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When it is emitted, the tree is guaranteed to be in-schema.\n\t */\n\ttreeChanged(): void;\n}\n"]}
+{"version":3,"file":"treeNodeApi.js","sourceRoot":"","sources":["../../src/simple-tree/treeNodeApi.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 { Multiplicity, rootFieldKey } from \"../core/index.js\";\nimport {\n\ttype LazyItem,\n\ttype TreeStatus,\n\tisLazy,\n\tisTreeValue,\n\tFlexObjectNodeSchema,\n} from \"../feature-libraries/index.js\";\nimport { fail, extractFromOpaque, isReadonlyArray } from \"../util/index.js\";\n\nimport { getOrCreateNodeProxy, isTreeNode } from \"./proxies.js\";\nimport { getFlexNode, getKernel } from \"./proxyBinding.js\";\nimport { tryGetSimpleNodeSchema } from \"./schemaCaching.js\";\nimport {\n\tNodeKind,\n\ttype TreeLeafValue,\n\ttype TreeNodeSchema,\n\ttype ImplicitFieldSchema,\n\tFieldSchema,\n\ttype ImplicitAllowedTypes,\n\ttype TreeNodeFromImplicitAllowedTypes,\n} from \"./schemaTypes.js\";\nimport type { TreeNode, TreeChangeEvents } from \"./types.js\";\nimport {\n\tbooleanSchema,\n\thandleSchema,\n\tnullSchema,\n\tnumberSchema,\n\tstringSchema,\n} from \"./leafNodeSchema.js\";\nimport { isFluidHandle } from \"@fluidframework/runtime-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport type { Off } from \"../events/index.js\";\n\n/**\n * Provides various functions for analyzing {@link TreeNode}s.\n * * @remarks\n * This type should only be used via the public `Tree` export.\n * @privateRemarks\n * Due to limitations of API-Extractor link resolution, this type can't be moved into internalTypes but should be considered just an implementation detail of the `Tree` export.\n *\n * Inlining the typing of this interface onto the `Tree` object provides slightly different .d.ts generation,\n * which avoids typescript expanding the type of TreeNodeSchema and thus encountering\n * https://github.com/microsoft/rushstack/issues/1958.\n * @sealed @public\n */\nexport interface TreeNodeApi {\n\t/**\n\t * The schema information for this node.\n\t */\n\tschema<T extends TreeNode | TreeLeafValue>(\n\t\tnode: T,\n\t): TreeNodeSchema<string, NodeKind, unknown, T>;\n\n\t/**\n\t * Narrow the type of the given value if it satisfies the given schema.\n\t * @example\n\t * ```ts\n\t * if (node.is(myNode, Point)) {\n\t *     const y = myNode.y; // `myNode` is now known to satisfy the `Point` schema and therefore has a `y` coordinate.\n\t * }\n\t * ```\n\t */\n\tis<TSchema extends ImplicitAllowedTypes>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is TreeNodeFromImplicitAllowedTypes<TSchema>;\n\n\t/**\n\t * Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).\n\t */\n\tparent(node: TreeNode): TreeNode | undefined;\n\n\t/**\n\t * The key of the given node under its parent.\n\t * @remarks\n\t * If `node` is an element in a {@link (TreeArrayNode:interface)}, this returns the index of `node` in the array node (a `number`).\n\t * Otherwise, this returns the key of the field that it is under (a `string`).\n\t */\n\tkey(node: TreeNode): string | number;\n\n\t/**\n\t * Register an event listener on the given node.\n\t * @param node - The node whose events should be subscribed to.\n\t * @param eventName - Which event to subscribe to.\n\t * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.\n\t * @returns A callback function which will deregister the event.\n\t * This callback should be called only once.\n\t */\n\ton<K extends keyof TreeChangeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeChangeEvents[K],\n\t): () => void;\n\n\t/**\n\t * Returns the {@link TreeStatus} of the given node.\n\t */\n\tstatus(node: TreeNode): TreeStatus;\n\n\t/**\n\t * Returns the {@link SchemaFactory.identifier | identifier} of the given node in the most compressed form possible.\n\t * @remarks\n\t * If the node's identifier is a valid UUID that was automatically generated by the SharedTree, then this will return a process-unique integer corresponding to that identifier.\n\t * This is useful for performance-sensitive scenarios involving many nodes with identifiers that need to be compactly retained in memory or used for efficient lookup.\n\t *\n\t * If the node's identifier is any other user-provided string, then this will return that string.\n\t *\n\t * If the node has no identifier (that is, it has no {@link SchemaFactory.identifier | identifier} field), then this returns `undefined`.\n\t *\n\t * If the node has more than one identifier, then this will throw an error.\n\t *\n\t * The returned integer must not be serialized or preserved outside of the current process.\n\t * Its lifetime is that of the current in-memory instance of the FF container for this client, and it is not guaranteed to be unique or stable outside of that context.\n\t * The same node's identifier may, for example, be different across multiple sessions for the same client and document, or different across two clients in the same session.\n\t */\n\tshortId(node: TreeNode): number | string | undefined;\n}\n\n/**\n * The `Tree` object holds various functions for analyzing {@link TreeNode}s.\n */\nexport const treeNodeApi: TreeNodeApi = {\n\tparent(node: TreeNode): TreeNode | undefined {\n\t\tconst editNode = getFlexNode(node).parentField.parent.parent;\n\t\tif (editNode === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst output = getOrCreateNodeProxy(editNode);\n\t\tassert(\n\t\t\t!isTreeValue(output),\n\t\t\t0x87f /* Parent can't be a leaf, so it should be a node not a value */,\n\t\t);\n\t\treturn output;\n\t},\n\tkey(node: TreeNode): string | number {\n\t\t// If the parent is undefined, then this node is under the root field,\n\t\t// so we know its key is the special root one.\n\t\tconst parent = treeNodeApi.parent(node);\n\t\tif (parent === undefined) {\n\t\t\treturn rootFieldKey;\n\t\t}\n\n\t\t// The flex-domain strictly operates in terms of \"stored keys\".\n\t\t// To find the associated developer-facing \"view key\", we need to look up the field associated with\n\t\t// the stored key from the flex-domain, and get view key its simple-domain counterpart was created with.\n\t\tconst storedKey = getStoredKey(node);\n\t\tconst parentSchema = treeNodeApi.schema(parent);\n\t\tconst viewKey = getViewKeyFromStoredKey(parentSchema, storedKey);\n\t\treturn viewKey;\n\t},\n\ton<K extends keyof TreeChangeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeChangeEvents[K],\n\t): Off {\n\t\treturn getKernel(node).on(eventName, listener);\n\t},\n\tstatus(node: TreeNode): TreeStatus {\n\t\treturn getKernel(node).getStatus();\n\t},\n\tis<TSchema extends ImplicitAllowedTypes>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is TreeNodeFromImplicitAllowedTypes<TSchema> {\n\t\tconst actualSchema = tryGetSchema(value);\n\t\tif (actualSchema === undefined) {\n\t\t\treturn false;\n\t\t}\n\t\tif (isReadonlyArray<LazyItem<TreeNodeSchema>>(schema)) {\n\t\t\tfor (const singleSchema of schema) {\n\t\t\t\tconst testSchema = isLazy(singleSchema) ? singleSchema() : singleSchema;\n\t\t\t\tif (testSchema === actualSchema) {\n\t\t\t\t\treturn true;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn false;\n\t\t} else {\n\t\t\treturn (schema as TreeNodeSchema) === actualSchema;\n\t\t}\n\t},\n\tschema<T extends TreeNode | TreeLeafValue>(\n\t\tnode: T,\n\t): TreeNodeSchema<string, NodeKind, unknown, T> {\n\t\treturn tryGetSchema(node) ?? fail(\"Not a tree node\");\n\t},\n\tshortId(node: TreeNode): number | string | undefined {\n\t\tconst flexNode = getFlexNode(node);\n\t\tconst flexSchema = flexNode.schema;\n\t\tconst identifierFieldKeys =\n\t\t\tflexSchema instanceof FlexObjectNodeSchema ? flexSchema.identifierFieldKeys : [];\n\n\t\tswitch (identifierFieldKeys.length) {\n\t\t\tcase 0:\n\t\t\t\treturn undefined;\n\t\t\tcase 1: {\n\t\t\t\tconst identifier = flexNode.tryGetField(identifierFieldKeys[0])?.boxedAt(0);\n\t\t\t\tassert(identifier !== undefined, 0x927 /* The identifier must exist */);\n\t\t\t\tconst identifierValue = identifier.value as string;\n\t\t\t\tconst localNodeKey =\n\t\t\t\t\tidentifier.context.nodeKeyManager.tryLocalizeNodeKey(identifierValue);\n\t\t\t\treturn localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : identifierValue;\n\t\t\t}\n\t\t\tdefault:\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t\"shortId() may not be called on a node with more than one identifier. Consider converting extraneous identifier fields to string fields.\",\n\t\t\t\t);\n\t\t}\n\t},\n};\n\n/**\n * Returns a schema for a value if the value is a {@link TreeNode} or a {@link TreeLeafValue}.\n * Returns undefined for other values.\n */\nexport function tryGetSchema<T>(\n\tvalue: T,\n): undefined | TreeNodeSchema<string, NodeKind, unknown, T> {\n\ttype TOut = TreeNodeSchema<string, NodeKind, unknown, T>;\n\tswitch (typeof value) {\n\t\tcase \"string\":\n\t\t\treturn stringSchema as TOut;\n\t\tcase \"number\":\n\t\t\treturn numberSchema as TOut;\n\t\tcase \"boolean\":\n\t\t\treturn booleanSchema as TOut;\n\t\tcase \"object\": {\n\t\t\tif (isTreeNode(value)) {\n\t\t\t\t// This case could be optimized, for example by placing the simple schema in a symbol on tree nodes.\n\t\t\t\treturn tryGetSimpleNodeSchema(getFlexNode(value).schema) as TOut;\n\t\t\t}\n\t\t\tif (value === null) {\n\t\t\t\treturn nullSchema as TOut;\n\t\t\t}\n\t\t\tif (isFluidHandle(value)) {\n\t\t\t\treturn handleSchema as TOut;\n\t\t\t}\n\t\t}\n\t\tdefault:\n\t\t\treturn undefined;\n\t}\n}\n\n/**\n * Gets the stored key with which the provided node is associated in the parent.\n */\nfunction getStoredKey(node: TreeNode): string | number {\n\t// Note: the flex domain strictly works with \"stored keys\", and knows nothing about the developer-facing\n\t// \"view keys\".\n\tconst parentField = getFlexNode(node).parentField;\n\tif (parentField.parent.schema.kind.multiplicity === Multiplicity.Sequence) {\n\t\t// The parent of `node` is an array node\n\t\treturn parentField.index;\n\t}\n\n\t// The parent of `node` is an object, a map, or undefined (and therefore `node` is a root/detached node).\n\treturn parentField.parent.key;\n}\n\n/**\n * Given a node schema, gets the view key corresponding with the provided {@link FieldProps.key | stored key}.\n */\nfunction getViewKeyFromStoredKey(\n\tschema: TreeNodeSchema,\n\tstoredKey: string | number,\n): string | number {\n\t// Only object nodes have the concept of a \"stored key\", differentiated from the developer-facing \"view key\".\n\t// For any other kind of node, the stored key and the view key are the same.\n\tif (schema.kind !== NodeKind.Object) {\n\t\treturn storedKey;\n\t}\n\n\tconst fields = schema.info as Record<string, ImplicitFieldSchema>;\n\n\t// Invariants:\n\t// - The set of all view keys under an object must be unique.\n\t// - The set of all stored keys (including those implicitly created from view keys) must be unique.\n\t// To find the view key associated with the provided stored key, first check for any stored key matches (which are optionally populated).\n\t// If we don't find any, then search for a matching view key.\n\tfor (const [viewKey, fieldSchema] of Object.entries(fields)) {\n\t\tif (fieldSchema instanceof FieldSchema && fieldSchema.props?.key === storedKey) {\n\t\t\treturn viewKey;\n\t\t}\n\t}\n\n\tif (fields[storedKey] === undefined) {\n\t\tfail(\"Existing stored key should always map to a view key\");\n\t}\n\n\treturn storedKey;\n}\n"]}

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

@@ -0,0 +1,26 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { type Listenable, type Off } from "../events/index.js";
+import type { TreeChangeEvents, TreeNode } from "./types.js";
+import type { AnchorNode } from "../core/index.js";
+import { TreeStatus } from "../feature-libraries/index.js";
+/**
+ * Contains state and an internal API for managing {@link TreeNode}s.
+ * @remarks All {@link TreeNode}s have an associated kernel object.
+ * The kernel has the same lifetime as the node and spans both its unhydrated and hydrated states.
+ * When hydration occurs, the kernel is notified via the {@link TreeNodeKernel.hydrate | hydrate} method.
+ */
+export declare class TreeNodeKernel implements Listenable<TreeChangeEvents> {
+    #private;
+    readonly node: TreeNode;
+    constructor(node: TreeNode);
+    hydrate(anchorNode: AnchorNode): void;
+    dehydrate(): void;
+    isHydrated(): boolean;
+    getStatus(): TreeStatus;
+    on<K extends keyof TreeChangeEvents>(eventName: K, listener: TreeChangeEvents[K]): Off;
+    dispose(): void;
+}
+//# sourceMappingURL=treeNodeKernel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"treeNodeKernel.d.ts","sourceRoot":"","sources":["../../src/simple-tree/treeNodeKernel.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAiB,KAAK,UAAU,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAIN,UAAU,EAEV,MAAM,+BAA+B,CAAC;AAEvC;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,UAAU,CAAC,gBAAgB,CAAC;;aAO/B,IAAI,EAAE,QAAQ;gBAAd,IAAI,EAAE,QAAQ;IAE1C,OAAO,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI;IAqBrC,SAAS,IAAI,IAAI;IAKjB,UAAU,IAAI,OAAO;IAIrB,SAAS,IAAI,UAAU;IAiBvB,EAAE,CAAC,CAAC,SAAS,MAAM,gBAAgB,EACzC,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC3B,GAAG;IAIC,OAAO,IAAI,IAAI;CAItB"}

package/lib/simple-tree/treeNodeKernel.js

@@ -0,0 +1,79 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _TreeNodeKernel_hydrated, _TreeNodeKernel_events;
+import { assert } from "@fluidframework/core-utils/internal";
+import { createEmitter } from "../events/index.js";
+import { flexTreeSlot, isFreedSymbol, LazyEntity, TreeStatus, treeStatusFromAnchorCache, } from "../feature-libraries/index.js";
+/**
+ * Contains state and an internal API for managing {@link TreeNode}s.
+ * @remarks All {@link TreeNode}s have an associated kernel object.
+ * The kernel has the same lifetime as the node and spans both its unhydrated and hydrated states.
+ * When hydration occurs, the kernel is notified via the {@link TreeNodeKernel.hydrate | hydrate} method.
+ */
+export class TreeNodeKernel {
+    constructor(node) {
+        this.node = node;
+        _TreeNodeKernel_hydrated.set(this, void 0);
+        _TreeNodeKernel_events.set(this, createEmitter());
+    }
+    hydrate(anchorNode) {
+        const offChildrenChanged = anchorNode.on("childrenChangedAfterBatch", () => {
+            __classPrivateFieldGet(this, _TreeNodeKernel_events, "f").emit("nodeChanged");
+        });
+        const offSubtreeChanged = anchorNode.on("subtreeChangedAfterBatch", () => {
+            __classPrivateFieldGet(this, _TreeNodeKernel_events, "f").emit("treeChanged");
+        });
+        const offAfterDestroy = anchorNode.on("afterDestroy", () => this.dispose());
+        __classPrivateFieldSet(this, _TreeNodeKernel_hydrated, {
+            anchorNode,
+            offAnchorNode: () => {
+                offChildrenChanged();
+                offSubtreeChanged();
+                offAfterDestroy();
+            },
+        }, "f");
+    }
+    dehydrate() {
+        __classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f")?.offAnchorNode?.();
+        __classPrivateFieldSet(this, _TreeNodeKernel_hydrated, undefined, "f");
+    }
+    isHydrated() {
+        return __classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f") !== undefined;
+    }
+    getStatus() {
+        if (__classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f")?.anchorNode === undefined) {
+            return TreeStatus.New;
+        }
+        // TODO: Replace this check with the proper check against the cursor state when the cursor becomes part of the kernel
+        const flex = __classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f").anchorNode.slots.get(flexTreeSlot);
+        if (flex !== undefined) {
+            assert(flex instanceof LazyEntity, 0x9b4 /* Unexpected flex node implementation */);
+            if (flex[isFreedSymbol]()) {
+                return TreeStatus.Deleted;
+            }
+        }
+        return treeStatusFromAnchorCache(__classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f").anchorNode);
+    }
+    on(eventName, listener) {
+        return __classPrivateFieldGet(this, _TreeNodeKernel_events, "f").on(eventName, listener);
+    }
+    dispose() {
+        this.dehydrate();
+        // TODO: go to the context and remove myself from withAnchors
+    }
+}
+_TreeNodeKernel_hydrated = new WeakMap(), _TreeNodeKernel_events = new WeakMap();
+//# sourceMappingURL=treeNodeKernel.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"treeNodeKernel.js","sourceRoot":"","sources":["../../src/simple-tree/treeNodeKernel.ts"],"names":[],"mappings":"AAAA;;;GAGG;;;;;;;;;;;;;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAC7D,OAAO,EAAE,aAAa,EAA6B,MAAM,oBAAoB,CAAC;AAG9E,OAAO,EACN,YAAY,EACZ,aAAa,EACb,UAAU,EACV,UAAU,EACV,yBAAyB,GACzB,MAAM,+BAA+B,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IAO1B,YAAmC,IAAc;QAAd,SAAI,GAAJ,IAAI,CAAU;QANjD,2CAGE;QACF,iCAAU,aAAa,EAAoB,EAAC;IAEQ,CAAC;IAE9C,OAAO,CAAC,UAAsB;QACpC,MAAM,kBAAkB,GAAG,UAAU,CAAC,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;YAC1E,uBAAA,IAAI,8BAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAClC,CAAC,CAAC,CAAC;QAEH,MAAM,iBAAiB,GAAG,UAAU,CAAC,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;YACxE,uBAAA,IAAI,8BAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAClC,CAAC,CAAC,CAAC;QAEH,MAAM,eAAe,GAAG,UAAU,CAAC,EAAE,CAAC,cAAc,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAE5E,uBAAA,IAAI,4BAAa;YAChB,UAAU;YACV,aAAa,EAAE,GAAG,EAAE;gBACnB,kBAAkB,EAAE,CAAC;gBACrB,iBAAiB,EAAE,CAAC;gBACpB,eAAe,EAAE,CAAC;YACnB,CAAC;SACD,MAAA,CAAC;IACH,CAAC;IAEM,SAAS;QACf,uBAAA,IAAI,gCAAU,EAAE,aAAa,EAAE,EAAE,CAAC;QAClC,uBAAA,IAAI,4BAAa,SAAS,MAAA,CAAC;IAC5B,CAAC;IAEM,UAAU;QAChB,OAAO,uBAAA,IAAI,gCAAU,KAAK,SAAS,CAAC;IACrC,CAAC;IAEM,SAAS;QACf,IAAI,uBAAA,IAAI,gCAAU,EAAE,UAAU,KAAK,SAAS,EAAE,CAAC;YAC9C,OAAO,UAAU,CAAC,GAAG,CAAC;QACvB,CAAC;QAED,qHAAqH;QACrH,MAAM,IAAI,GAAG,uBAAA,IAAI,gCAAU,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC/D,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,CAAC,IAAI,YAAY,UAAU,EAAE,KAAK,CAAC,yCAAyC,CAAC,CAAC;YACpF,IAAI,IAAI,CAAC,aAAa,CAAC,EAAE,EAAE,CAAC;gBAC3B,OAAO,UAAU,CAAC,OAAO,CAAC;YAC3B,CAAC;QACF,CAAC;QAED,OAAO,yBAAyB,CAAC,uBAAA,IAAI,gCAAU,CAAC,UAAU,CAAC,CAAC;IAC7D,CAAC;IAEM,EAAE,CACR,SAAY,EACZ,QAA6B;QAE7B,OAAO,uBAAA,IAAI,8BAAQ,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAEM,OAAO;QACb,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,6DAA6D;IAC9D,CAAC;CACD","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\";\nimport { createEmitter, type Listenable, type Off } from \"../events/index.js\";\nimport type { TreeChangeEvents, TreeNode } from \"./types.js\";\nimport type { AnchorNode } from \"../core/index.js\";\nimport {\n\tflexTreeSlot,\n\tisFreedSymbol,\n\tLazyEntity,\n\tTreeStatus,\n\ttreeStatusFromAnchorCache,\n} from \"../feature-libraries/index.js\";\n\n/**\n * Contains state and an internal API for managing {@link TreeNode}s.\n * @remarks All {@link TreeNode}s have an associated kernel object.\n * The kernel has the same lifetime as the node and spans both its unhydrated and hydrated states.\n * When hydration occurs, the kernel is notified via the {@link TreeNodeKernel.hydrate | hydrate} method.\n */\nexport class TreeNodeKernel implements Listenable<TreeChangeEvents> {\n\t#hydrated?: {\n\t\tanchorNode: AnchorNode;\n\t\toffAnchorNode: Off;\n\t};\n\t#events = createEmitter<TreeChangeEvents>();\n\n\tpublic constructor(public readonly node: TreeNode) {}\n\n\tpublic hydrate(anchorNode: AnchorNode): void {\n\t\tconst offChildrenChanged = anchorNode.on(\"childrenChangedAfterBatch\", () => {\n\t\t\tthis.#events.emit(\"nodeChanged\");\n\t\t});\n\n\t\tconst offSubtreeChanged = anchorNode.on(\"subtreeChangedAfterBatch\", () => {\n\t\t\tthis.#events.emit(\"treeChanged\");\n\t\t});\n\n\t\tconst offAfterDestroy = anchorNode.on(\"afterDestroy\", () => this.dispose());\n\n\t\tthis.#hydrated = {\n\t\t\tanchorNode,\n\t\t\toffAnchorNode: () => {\n\t\t\t\toffChildrenChanged();\n\t\t\t\toffSubtreeChanged();\n\t\t\t\toffAfterDestroy();\n\t\t\t},\n\t\t};\n\t}\n\n\tpublic dehydrate(): void {\n\t\tthis.#hydrated?.offAnchorNode?.();\n\t\tthis.#hydrated = undefined;\n\t}\n\n\tpublic isHydrated(): boolean {\n\t\treturn this.#hydrated !== undefined;\n\t}\n\n\tpublic getStatus(): TreeStatus {\n\t\tif (this.#hydrated?.anchorNode === undefined) {\n\t\t\treturn TreeStatus.New;\n\t\t}\n\n\t\t// TODO: Replace this check with the proper check against the cursor state when the cursor becomes part of the kernel\n\t\tconst flex = this.#hydrated.anchorNode.slots.get(flexTreeSlot);\n\t\tif (flex !== undefined) {\n\t\t\tassert(flex instanceof LazyEntity, 0x9b4 /* Unexpected flex node implementation */);\n\t\t\tif (flex[isFreedSymbol]()) {\n\t\t\t\treturn TreeStatus.Deleted;\n\t\t\t}\n\t\t}\n\n\t\treturn treeStatusFromAnchorCache(this.#hydrated.anchorNode);\n\t}\n\n\tpublic on<K extends keyof TreeChangeEvents>(\n\t\teventName: K,\n\t\tlistener: TreeChangeEvents[K],\n\t): Off {\n\t\treturn this.#events.on(eventName, listener);\n\t}\n\n\tpublic dispose(): void {\n\t\tthis.dehydrate();\n\t\t// TODO: go to the context and remove myself from withAnchors\n\t}\n}\n"]}