@fluidframework/tree 2.3.0-288113 → 2.3.1

package/dist/simple-tree/core/treeNodeKernel.js

@@ -16,10 +16,15 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
 };
 var _TreeNodeKernel_instances, _TreeNodeKernel_hydrated, _TreeNodeKernel_preHydrationEvents, _TreeNodeKernel_events_get;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TreeNodeKernel = exports.tryGetTreeNodeSchema = exports.isTreeNode = exports.getKernel = void 0;
+exports.tryDisposeTreeNode = exports.tryGetCachedTreeNode = exports.TreeNodeKernel = exports.tryGetTreeNodeSchema = exports.isTreeNode = exports.getKernel = void 0;
 const internal_1 = require("@fluidframework/core-utils/internal");
 const index_js_1 = require("../../events/index.js");
-const index_js_2 = require("../../feature-libraries/index.js");
+const index_js_2 = require("../../core/index.js");
+const index_js_3 = require("../../feature-libraries/index.js");
+const index_js_4 = require("../../util/index.js");
+// TODO: decide how to deal with dependencies on flex-tree implementation.
+// eslint-disable-next-line import/no-internal-modules
+const lazyNode_js_1 = require("../../feature-libraries/flex-tree/lazyNode.js");
 const treeNodeToKernel = new WeakMap();
 function getKernel(node) {
     const kernel = treeNodeToKernel.get(node);
@@ -66,36 +71,63 @@ exports.tryGetTreeNodeSchema = tryGetTreeNodeSchema;
 class TreeNodeKernel {
     /**
      * Create a TreeNodeKernel which can be looked up with {@link getKernel}.
+     *
+     * @param innerNode - When unhydrated/raw or marinated the MapTreeNode. FlexTreeNode when cooked.
      * @remarks
      * Exactly one kernel per TreeNode should be created.
      */
-    constructor(node, schema) {
+    constructor(node, schema, innerNode) {
         _TreeNodeKernel_instances.add(this);
         this.node = node;
         this.schema = schema;
+        this.innerNode = innerNode;
         this.disposed = false;
         /**
          * Generation number which is incremented any time we have an edit on the node.
          * Used during iteration to make sure there has been no edits that were concurrently made.
+         * @remarks
+         * This is updated monotonically by this class when edits are applied.
+         * TODO: update this when applying edits to unhydrated trees.
+         *
+         * If TypeScript supported making this immutable from outside the class without making it readonly from inside, that would be used here,
+         * but they only way to do that is add a separate public accessor and make it private, which was deemed not worth the boilerplate, runtime overhead and bundle size.
          */
         this.generationNumber = 0;
         _TreeNodeKernel_hydrated.set(this, void 0);
         /**
          * Events registered before hydration.
          * @remarks
-         *
+         * As an optimization these are allocated lazily as they are usually unused.
          */
         _TreeNodeKernel_preHydrationEvents.set(this, void 0);
         (0, internal_1.assert)(!treeNodeToKernel.has(node), 0xa1a /* only one kernel per node can be made */);
         treeNodeToKernel.set(node, this);
+        if ((0, index_js_3.isMapTreeNode)(innerNode)) {
+            // Unhydrated case
+            mapTreeNodeToProxy.set(innerNode, node);
+        }
+        else {
+            // Hydrated case
+            (0, internal_1.assert)(!innerNode.anchorNode.slots.has(proxySlot), 0x7f5 /* Cannot associate an flex node with multiple simple-tree nodes */);
+            this.hydrate(innerNode.anchorNode);
+        }
     }
     /**
      * Transition from {@link Unhydrated} to hydrated.
+     * Bi-directionally associates the given hydrated TreeNode to the given anchor node.
      * @remarks
      * Happens at most once for any given node.
+     * Cleans up mappings to {@link MapTreeNode} - it is assumed that they are no longer needed once the proxy has an anchor node.
      */
     hydrate(anchorNode) {
-        (0, internal_1.assert)(!this.disposed, "cannot use a disposed node");
+        (0, internal_1.assert)(!this.disposed, 0xa2a /* cannot hydrate a disposed node */);
+        (0, internal_1.assert)(__classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f") === undefined, 0xa2b /* hydration should only happen once */);
+        // If the this node is raw and thus has a MapTreeNode, forget it:
+        if ((0, index_js_3.isMapTreeNode)(this.innerNode)) {
+            mapTreeNodeToProxy.delete(this.innerNode);
+        }
+        // However, it's fine for an anchor node to rotate through different proxies when the content at that place in the tree is replaced.
+        anchorNode.slots.set(proxySlot, this.node);
         __classPrivateFieldSet(this, _TreeNodeKernel_hydrated, {
             anchorNode,
             offAnchorNode: new Set([
@@ -119,25 +151,25 @@ class TreeNodeKernel {
         }
     }
     isHydrated() {
-        (0, internal_1.assert)(!this.disposed, "cannot use a disposed node");
+        (0, internal_1.assert)(!this.disposed, 0xa2c /* cannot use a disposed node */);
         return __classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f") !== undefined;
     }
     getStatus() {
         if (this.disposed) {
-            return index_js_2.TreeStatus.Deleted;
+            return index_js_3.TreeStatus.Deleted;
         }
         if (__classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f")?.anchorNode === undefined) {
-            return index_js_2.TreeStatus.New;
+            return index_js_3.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(index_js_2.flexTreeSlot);
+        const flex = __classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f").anchorNode.slots.get(index_js_3.flexTreeSlot);
         if (flex !== undefined) {
-            (0, internal_1.assert)(flex instanceof index_js_2.LazyEntity, 0x9b4 /* Unexpected flex node implementation */);
-            if (flex[index_js_2.isFreedSymbol]()) {
-                return index_js_2.TreeStatus.Deleted;
+            (0, internal_1.assert)(flex instanceof index_js_3.LazyEntity, 0x9b4 /* Unexpected flex node implementation */);
+            if (flex[index_js_3.isFreedSymbol]()) {
+                return index_js_3.TreeStatus.Deleted;
             }
         }
-        return (0, index_js_2.treeStatusFromAnchorCache)(__classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f").anchorNode);
+        return (0, index_js_3.treeStatusFromAnchorCache)(__classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f").anchorNode);
     }
     on(eventName, listener) {
         return __classPrivateFieldGet(this, _TreeNodeKernel_instances, "a", _TreeNodeKernel_events_get).on(eventName, listener);
@@ -149,6 +181,92 @@ class TreeNodeKernel {
         }
         // TODO: go to the context and remove myself from withAnchors
     }
+    /**
+     * Retrieves the flex node associated with the given target via {@link setInnerNode}.
+     * @remarks
+     * For {@link Unhydrated} nodes, this returns the MapTreeNode.
+     *
+     * For hydrated nodes it returns a FlexTreeNode backed by the forest.
+     * Note that for "marinated" nodes, this FlexTreeNode exists and returns it: it does not return the MapTreeNode which is the current InnerNode.
+     */
+    getOrCreateInnerNode(allowFreed = false) {
+        if (!(0, index_js_3.isMapTreeNode)(this.innerNode)) {
+            // Cooked case
+            return this.innerNode;
+        }
+        if (__classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f") === undefined) {
+            // Unhydrated case
+            return this.innerNode;
+        }
+        // Marinated case -> cooked
+        const anchorNode = __classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f").anchorNode;
+        // The proxy is bound to an anchor node, but it may or may not have an actual flex node yet
+        const flexNode = anchorNode.slots.get(index_js_3.flexTreeSlot);
+        if (flexNode !== undefined) {
+            this.innerNode = flexNode;
+            return flexNode; // If it does have a flex node, return it...
+        } // ...otherwise, the flex node must be created
+        const context = anchorNode.anchorSet.slots.get(index_js_3.ContextSlot) ?? (0, index_js_4.fail)("missing context");
+        const cursor = context.checkout.forest.allocateCursor("getFlexNode");
+        context.checkout.forest.moveCursorToPath(anchorNode, cursor);
+        const newFlexNode = (0, lazyNode_js_1.makeTree)(context, cursor);
+        cursor.free();
+        this.innerNode = newFlexNode;
+        // Calling this is a performance improvement, however, do this only after demand to avoid momentarily having no anchors to anchorNode
+        anchorForgetters?.get(this.node)?.();
+        if (!allowFreed) {
+            (0, index_js_3.assertFlexTreeEntityNotFreed)(newFlexNode);
+        }
+        return newFlexNode;
+    }
+    /**
+     * Creates an anchor node and associates it with the given proxy.
+     * @privateRemarks
+     * Use `forgetters` to cleanup the anchor allocated by this function once the anchor is no longer needed.
+     * In practice, this happens when either the anchor node is destroyed, or another anchor to the same node is created by a new flex node.
+     *
+     * The FlexTreeNode holds a reference to the same anchor, and has a lifetime at least as long as the simple-tree,
+     * so this would be unnecessary except for the case of "marinated" nodes, which have an anchor,
+     * but might not have a FlexTreeNode.
+     * Handling this case is an optimization assuming that this extra anchor reference is cheaper than eagerly creating FlexTreeNodes.
+     */
+    anchorProxy(anchors, path) {
+        (0, internal_1.assert)(!anchorForgetters.has(this.node), 0x91c /* Proxy anchor should not be set twice */);
+        const anchor = anchors.track(path);
+        const anchorNode = anchors.locate(anchor) ?? (0, index_js_4.fail)("Expected anchor node to be present");
+        this.hydrate(anchorNode);
+        const forget = () => {
+            if (anchors.locate(anchor)) {
+                anchors.forget(anchor);
+            }
+            anchorForgetters.delete(this.node);
+            off();
+        };
+        anchorForgetters.set(this.node, forget);
+        const off = anchorNode.on("afterDestroy", forget);
+        return anchorNode;
+    }
+    /**
+     * Retrieves the InnerNode associated with the given target via {@link setInnerNode}, if any.
+     * @remarks
+     * If `target` is a unhydrated node, returns its MapTreeNode.
+     * If `target` is a cooked node (or marinated but a FlexTreeNode exists) returns the FlexTreeNode.
+     * If the target is not a node, or a marinated node with no FlexTreeNode for its anchor, returns undefined.
+     */
+    tryGetInnerNode() {
+        if ((0, index_js_3.isFlexTreeNode)(this.innerNode)) {
+            // Cooked case
+            return this.innerNode;
+        }
+        if (__classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f") === undefined) {
+            // Unhydrated case
+            return this.innerNode;
+        }
+        // Marinated case -> cooked
+        const anchorNode = __classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f").anchorNode;
+        // The proxy is bound to an anchor node, but it may or may not have an actual flex node yet
+        return anchorNode.slots.get(index_js_3.flexTreeSlot);
+    }
 }
 exports.TreeNodeKernel = TreeNodeKernel;
 _TreeNodeKernel_hydrated = new WeakMap(), _TreeNodeKernel_preHydrationEvents = new WeakMap(), _TreeNodeKernel_instances = new WeakSet(), _TreeNodeKernel_events_get = function _TreeNodeKernel_events_get() {
@@ -160,5 +278,40 @@ _TreeNodeKernel_hydrated = new WeakMap(), _TreeNodeKernel_preHydrationEvents = n
         return __classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f").anchorNode;
     }
 };
+/**
+ * Used by {@link anchorProxy} as an optimization to ensure that only one anchor is remembered at a time for a given anchor node
+ */
+const anchorForgetters = new WeakMap();
 const kernelEvents = ["childrenChangedAfterBatch", "subtreeChangedAfterBatch"];
+/**
+ * {@inheritdoc proxyToMapTreeNode}
+ */
+const mapTreeNodeToProxy = new WeakMap();
+/**
+ * An anchor slot which associates an anchor with its corresponding TreeNode, if there is one.
+ * @remarks
+ * For this to work, we have to require that there is at most a single view using a given AnchorSet.
+ * FlexTree already has this assumption, and we also assume there is a single simple-tree per FlexTree, so this is valid.
+ */
+const proxySlot = (0, index_js_2.anchorSlot)();
+/**
+ * Retrieves the proxy associated with the given flex node via {@link setInnerNode}, if any.
+ */
+function tryGetCachedTreeNode(flexNode) {
+    if ((0, index_js_3.isMapTreeNode)(flexNode)) {
+        // Unhydrated case
+        return mapTreeNodeToProxy.get(flexNode);
+    }
+    // Hydrated case
+    return flexNode.anchorNode.slots.get(proxySlot);
+}
+exports.tryGetCachedTreeNode = tryGetCachedTreeNode;
+function tryDisposeTreeNode(anchorNode) {
+    const treeNode = anchorNode.slots.get(proxySlot);
+    if (treeNode !== undefined) {
+        const kernel = getKernel(treeNode);
+        kernel.dispose();
+    }
+}
+exports.tryDisposeTreeNode = tryDisposeTreeNode;
 //# sourceMappingURL=treeNodeKernel.js.map

package/dist/simple-tree/core/treeNodeKernel.js.map

@@ -1 +1 @@
-{"version":3,"file":"treeNodeKernel.js","sourceRoot":"","sources":["../../../src/simple-tree/core/treeNodeKernel.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\";\nimport {\n\tcreateEmitter,\n\ttype HasListeners,\n\ttype IEmitter,\n\ttype Listenable,\n\ttype Off,\n} from \"../../events/index.js\";\nimport type { TreeNode, Unhydrated } from \"./types.js\";\nimport type { AnchorEvents, AnchorNode } from \"../../core/index.js\";\nimport {\n\tflexTreeSlot,\n\tisFreedSymbol,\n\tLazyEntity,\n\tTreeStatus,\n\ttreeStatusFromAnchorCache,\n} from \"../../feature-libraries/index.js\";\nimport type { TreeNodeSchema } from \"./treeNodeSchema.js\";\n\nconst treeNodeToKernel = new WeakMap<TreeNode, TreeNodeKernel>();\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\n/**\n * Detects if the given 'candidate' is a TreeNode.\n *\n * @remarks\n * Supports both Hydrated and {@link Unhydrated} TreeNodes, both of which return true.\n *\n * Because the common usage is to check if a value being inserted/set is a TreeNode,\n * this function permits calling with primitives as well as objects.\n *\n * Primitives will always return false (as they are copies of data, not references to nodes).\n *\n * @param candidate - Value which may be a TreeNode\n * @returns true if the given 'candidate' is a hydrated TreeNode.\n */\nexport function isTreeNode(candidate: unknown): candidate is TreeNode | Unhydrated<TreeNode> {\n\treturn treeNodeToKernel.has(candidate as TreeNode);\n}\n\n/**\n * Returns a schema for a value if the value is a {@link TreeNode}.\n *\n * Returns undefined for other values.\n * @remarks\n * Does not give schema for a {@link TreeLeafValue}.\n */\nexport function tryGetTreeNodeSchema(value: unknown): undefined | TreeNodeSchema {\n\tconst kernel = treeNodeToKernel.get(value as TreeNode);\n\treturn kernel?.schema;\n}\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<KernelEvents> {\n\tprivate disposed = false;\n\n\t/**\n\t * Generation number which is incremented any time we have an edit on the node.\n\t * Used during iteration to make sure there has been no edits that were concurrently made.\n\t */\n\tpublic generationNumber: number = 0;\n\n\t#hydrated?: {\n\t\tanchorNode: AnchorNode;\n\t\toffAnchorNode: Set<Off>;\n\t};\n\n\t/**\n\t * Events registered before hydration.\n\t * @remarks\n\t *\n\t */\n\t#preHydrationEvents?: Listenable<KernelEvents> &\n\t\tIEmitter<KernelEvents> &\n\t\tHasListeners<KernelEvents>;\n\n\t/**\n\t * Get the listener.\n\t * @remarks\n\t * If before hydration, allocates and uses `#preHydrationEvents`, otherwise the anchorNode.\n\t * This design avoids allocating `#preHydrationEvents` if unneeded.\n\t *\n\t * This design also avoids extra forwarding overhead for events from anchorNode and also\n\t * avoids registering for events that the are unneeded.\n\t * This means optimizations like skipping processing data in subtrees where no subtreeChanged events are subscribed to would be able to work,\n\t * since this code does not unconditionally subscribe to those events (like a design simply forwarding all events would).\n\t */\n\tget #events(): Listenable<KernelEvents> {\n\t\tif (this.#hydrated === undefined) {\n\t\t\tthis.#preHydrationEvents ??= createEmitter<KernelEvents>();\n\t\t\treturn this.#preHydrationEvents;\n\t\t} else {\n\t\t\treturn this.#hydrated.anchorNode;\n\t\t}\n\t}\n\n\t/**\n\t * Create a TreeNodeKernel which can be looked up with {@link getKernel}.\n\t * @remarks\n\t * Exactly one kernel per TreeNode should be created.\n\t */\n\tpublic constructor(\n\t\tpublic readonly node: TreeNode,\n\t\tpublic readonly schema: TreeNodeSchema,\n\t) {\n\t\tassert(!treeNodeToKernel.has(node), 0xa1a /* only one kernel per node can be made */);\n\t\ttreeNodeToKernel.set(node, this);\n\t}\n\n\t/**\n\t * Transition from {@link Unhydrated} to hydrated.\n\t * @remarks\n\t * Happens at most once for any given node.\n\t */\n\tpublic hydrate(anchorNode: AnchorNode): void {\n\t\tassert(!this.disposed, \"cannot use a disposed node\");\n\n\t\tthis.#hydrated = {\n\t\t\tanchorNode,\n\t\t\toffAnchorNode: new Set([\n\t\t\t\tanchorNode.on(\"afterDestroy\", () => this.dispose()),\n\t\t\t\t// TODO: this should be triggered on change even for unhydrated nodes.\n\t\t\t\tanchorNode.on(\"childrenChanging\", () => {\n\t\t\t\t\tthis.generationNumber += 1;\n\t\t\t\t}),\n\t\t\t]),\n\t\t};\n\n\t\t// If needed, register forwarding emitters for events from before hydration\n\t\tif (this.#preHydrationEvents !== undefined) {\n\t\t\tfor (const eventName of kernelEvents) {\n\t\t\t\tif (this.#preHydrationEvents.hasListeners(eventName)) {\n\t\t\t\t\tthis.#hydrated.offAnchorNode.add(\n\t\t\t\t\t\t// Argument is forwarded between matching events, so the type should be correct.\n\t\t\t\t\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t\t\t\t\tanchorNode.on(eventName, (arg: any) =>\n\t\t\t\t\t\t\tthis.#preHydrationEvents?.emit(eventName, arg),\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tpublic isHydrated(): boolean {\n\t\tassert(!this.disposed, \"cannot use a disposed node\");\n\t\treturn this.#hydrated !== undefined;\n\t}\n\n\tpublic getStatus(): TreeStatus {\n\t\tif (this.disposed) {\n\t\t\treturn TreeStatus.Deleted;\n\t\t}\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 KernelEvents>(eventName: K, listener: KernelEvents[K]): Off {\n\t\treturn this.#events.on(eventName, listener);\n\t}\n\n\tpublic dispose(): void {\n\t\tthis.disposed = true;\n\t\tfor (const off of this.#hydrated?.offAnchorNode ?? []) {\n\t\t\toff();\n\t\t}\n\t\t// TODO: go to the context and remove myself from withAnchors\n\t}\n}\n\nconst kernelEvents = [\"childrenChangedAfterBatch\", \"subtreeChangedAfterBatch\"] as const;\n\ntype KernelEvents = Pick<AnchorEvents, (typeof kernelEvents)[number]>;\n"]}
+{"version":3,"file":"treeNodeKernel.js","sourceRoot":"","sources":["../../../src/simple-tree/core/treeNodeKernel.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\";\nimport {\n\tcreateEmitter,\n\ttype HasListeners,\n\ttype IEmitter,\n\ttype Listenable,\n\ttype Off,\n} from \"../../events/index.js\";\nimport type { TreeNode, Unhydrated } from \"./types.js\";\nimport {\n\tanchorSlot,\n\ttype AnchorEvents,\n\ttype AnchorNode,\n\ttype AnchorSet,\n\ttype UpPath,\n} from \"../../core/index.js\";\nimport {\n\tassertFlexTreeEntityNotFreed,\n\tContextSlot,\n\tflexTreeSlot,\n\tisFlexTreeNode,\n\tisFreedSymbol,\n\tisMapTreeNode,\n\tLazyEntity,\n\tTreeStatus,\n\ttreeStatusFromAnchorCache,\n\ttype FlexTreeNode,\n\ttype MapTreeNode,\n} from \"../../feature-libraries/index.js\";\nimport type { TreeNodeSchema } from \"./treeNodeSchema.js\";\nimport { fail } from \"../../util/index.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\";\n\nconst treeNodeToKernel = new WeakMap<TreeNode, TreeNodeKernel>();\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\n/**\n * Detects if the given 'candidate' is a TreeNode.\n *\n * @remarks\n * Supports both Hydrated and {@link Unhydrated} TreeNodes, both of which return true.\n *\n * Because the common usage is to check if a value being inserted/set is a TreeNode,\n * this function permits calling with primitives as well as objects.\n *\n * Primitives will always return false (as they are copies of data, not references to nodes).\n *\n * @param candidate - Value which may be a TreeNode\n * @returns true if the given 'candidate' is a hydrated TreeNode.\n */\nexport function isTreeNode(candidate: unknown): candidate is TreeNode | Unhydrated<TreeNode> {\n\treturn treeNodeToKernel.has(candidate as TreeNode);\n}\n\n/**\n * Returns a schema for a value if the value is a {@link TreeNode}.\n *\n * Returns undefined for other values.\n * @remarks\n * Does not give schema for a {@link TreeLeafValue}.\n */\nexport function tryGetTreeNodeSchema(value: unknown): undefined | TreeNodeSchema {\n\tconst kernel = treeNodeToKernel.get(value as TreeNode);\n\treturn kernel?.schema;\n}\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<KernelEvents> {\n\tprivate disposed = false;\n\n\t/**\n\t * Generation number which is incremented any time we have an edit on the node.\n\t * Used during iteration to make sure there has been no edits that were concurrently made.\n\t * @remarks\n\t * This is updated monotonically by this class when edits are applied.\n\t * TODO: update this when applying edits to unhydrated trees.\n\t *\n\t * If TypeScript supported making this immutable from outside the class without making it readonly from inside, that would be used here,\n\t * but they only way to do that is add a separate public accessor and make it private, which was deemed not worth the boilerplate, runtime overhead and bundle size.\n\t */\n\tpublic generationNumber: number = 0;\n\n\t#hydrated?: {\n\t\tanchorNode: AnchorNode;\n\t\toffAnchorNode: Set<Off>;\n\t};\n\n\t/**\n\t * Events registered before hydration.\n\t * @remarks\n\t * As an optimization these are allocated lazily as they are usually unused.\n\t */\n\t#preHydrationEvents?: Listenable<KernelEvents> &\n\t\tIEmitter<KernelEvents> &\n\t\tHasListeners<KernelEvents>;\n\n\t/**\n\t * Get the listener.\n\t * @remarks\n\t * If before hydration, allocates and uses `#preHydrationEvents`, otherwise the anchorNode.\n\t * This design avoids allocating `#preHydrationEvents` if unneeded.\n\t *\n\t * This design also avoids extra forwarding overhead for events from anchorNode and also\n\t * avoids registering for events that are unneeded.\n\t * This means optimizations like skipping processing data in subtrees where no subtreeChanged events are subscribed to would be able to work,\n\t * since this code does not unconditionally subscribe to those events (like a design simply forwarding all events would).\n\t */\n\tget #events(): Listenable<KernelEvents> {\n\t\tif (this.#hydrated === undefined) {\n\t\t\tthis.#preHydrationEvents ??= createEmitter<KernelEvents>();\n\t\t\treturn this.#preHydrationEvents;\n\t\t} else {\n\t\t\treturn this.#hydrated.anchorNode;\n\t\t}\n\t}\n\n\t/**\n\t * Create a TreeNodeKernel which can be looked up with {@link getKernel}.\n\t *\n\t * @param innerNode - When unhydrated/raw or marinated the MapTreeNode. FlexTreeNode when cooked.\n\t * @remarks\n\t * Exactly one kernel per TreeNode should be created.\n\t */\n\tpublic constructor(\n\t\tpublic readonly node: TreeNode,\n\t\tpublic readonly schema: TreeNodeSchema,\n\t\tprivate innerNode: InnerNode,\n\t) {\n\t\tassert(!treeNodeToKernel.has(node), 0xa1a /* only one kernel per node can be made */);\n\t\ttreeNodeToKernel.set(node, this);\n\n\t\tif (isMapTreeNode(innerNode)) {\n\t\t\t// Unhydrated case\n\t\t\tmapTreeNodeToProxy.set(innerNode, node);\n\t\t} else {\n\t\t\t// Hydrated case\n\t\t\tassert(\n\t\t\t\t!innerNode.anchorNode.slots.has(proxySlot),\n\t\t\t\t0x7f5 /* Cannot associate an flex node with multiple simple-tree nodes */,\n\t\t\t);\n\t\t\tthis.hydrate(innerNode.anchorNode);\n\t\t}\n\t}\n\n\t/**\n\t * Transition from {@link Unhydrated} to hydrated.\n\t * Bi-directionally associates the given hydrated TreeNode to the given anchor node.\n\t * @remarks\n\t * Happens at most once for any given node.\n\t * Cleans up mappings to {@link MapTreeNode} - it is assumed that they are no longer needed once the proxy has an anchor node.\n\t */\n\tpublic hydrate(anchorNode: AnchorNode): void {\n\t\tassert(!this.disposed, 0xa2a /* cannot hydrate a disposed node */);\n\t\tassert(this.#hydrated === undefined, 0xa2b /* hydration should only happen once */);\n\n\t\t// If the this node is raw and thus has a MapTreeNode, forget it:\n\t\tif (isMapTreeNode(this.innerNode)) {\n\t\t\tmapTreeNodeToProxy.delete(this.innerNode);\n\t\t}\n\n\t\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\t\tanchorNode.slots.set(proxySlot, this.node);\n\n\t\tthis.#hydrated = {\n\t\t\tanchorNode,\n\t\t\toffAnchorNode: new Set([\n\t\t\t\tanchorNode.on(\"afterDestroy\", () => this.dispose()),\n\t\t\t\t// TODO: this should be triggered on change even for unhydrated nodes.\n\t\t\t\tanchorNode.on(\"childrenChanging\", () => {\n\t\t\t\t\tthis.generationNumber += 1;\n\t\t\t\t}),\n\t\t\t]),\n\t\t};\n\n\t\t// If needed, register forwarding emitters for events from before hydration\n\t\tif (this.#preHydrationEvents !== undefined) {\n\t\t\tfor (const eventName of kernelEvents) {\n\t\t\t\tif (this.#preHydrationEvents.hasListeners(eventName)) {\n\t\t\t\t\tthis.#hydrated.offAnchorNode.add(\n\t\t\t\t\t\t// Argument is forwarded between matching events, so the type should be correct.\n\t\t\t\t\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t\t\t\t\tanchorNode.on(eventName, (arg: any) =>\n\t\t\t\t\t\t\tthis.#preHydrationEvents?.emit(eventName, arg),\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tpublic isHydrated(): boolean {\n\t\tassert(!this.disposed, 0xa2c /* cannot use a disposed node */);\n\t\treturn this.#hydrated !== undefined;\n\t}\n\n\tpublic getStatus(): TreeStatus {\n\t\tif (this.disposed) {\n\t\t\treturn TreeStatus.Deleted;\n\t\t}\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 KernelEvents>(eventName: K, listener: KernelEvents[K]): Off {\n\t\treturn this.#events.on(eventName, listener);\n\t}\n\n\tpublic dispose(): void {\n\t\tthis.disposed = true;\n\t\tfor (const off of this.#hydrated?.offAnchorNode ?? []) {\n\t\t\toff();\n\t\t}\n\t\t// TODO: go to the context and remove myself from withAnchors\n\t}\n\n\t/**\n\t * Retrieves the flex node associated with the given target via {@link setInnerNode}.\n\t * @remarks\n\t * For {@link Unhydrated} nodes, this returns the MapTreeNode.\n\t *\n\t * For hydrated nodes it returns a FlexTreeNode backed by the forest.\n\t * Note that for \"marinated\" nodes, this FlexTreeNode exists and returns it: it does not return the MapTreeNode which is the current InnerNode.\n\t */\n\tpublic getOrCreateInnerNode(allowFreed = false): InnerNode {\n\t\tif (!isMapTreeNode(this.innerNode)) {\n\t\t\t// Cooked case\n\t\t\treturn this.innerNode;\n\t\t}\n\n\t\tif (this.#hydrated === undefined) {\n\t\t\t// Unhydrated case\n\t\t\treturn this.innerNode;\n\t\t}\n\n\t\t// Marinated case -> cooked\n\t\tconst anchorNode = this.#hydrated.anchorNode;\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\tthis.innerNode = flexNode;\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\tthis.innerNode = newFlexNode;\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(this.node)?.();\n\t\tif (!allowFreed) {\n\t\t\tassertFlexTreeEntityNotFreed(newFlexNode);\n\t\t}\n\t\treturn newFlexNode;\n\t}\n\n\t/**\n\t * Creates an anchor node and associates it with the given proxy.\n\t * @privateRemarks\n\t * Use `forgetters` to cleanup the anchor allocated by this function once the anchor is no longer needed.\n\t * 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\t *\n\t * The FlexTreeNode holds a reference to the same anchor, and has a lifetime at least as long as the simple-tree,\n\t * so this would be unnecessary except for the case of \"marinated\" nodes, which have an anchor,\n\t * but might not have a FlexTreeNode.\n\t * Handling this case is an optimization assuming that this extra anchor reference is cheaper than eagerly creating FlexTreeNodes.\n\t */\n\tpublic anchorProxy(anchors: AnchorSet, path: UpPath): AnchorNode {\n\t\tassert(!anchorForgetters.has(this.node), 0x91c /* Proxy anchor should not be set twice */);\n\t\tconst anchor = anchors.track(path);\n\t\tconst anchorNode = anchors.locate(anchor) ?? fail(\"Expected anchor node to be present\");\n\t\tthis.hydrate(anchorNode);\n\t\tconst forget = (): void => {\n\t\t\tif (anchors.locate(anchor)) {\n\t\t\t\tanchors.forget(anchor);\n\t\t\t}\n\t\t\tanchorForgetters.delete(this.node);\n\t\t\toff();\n\t\t};\n\t\tanchorForgetters.set(this.node, forget);\n\t\tconst off = anchorNode.on(\"afterDestroy\", forget);\n\t\treturn anchorNode;\n\t}\n\n\t/**\n\t * Retrieves the InnerNode associated with the given target via {@link setInnerNode}, if any.\n\t * @remarks\n\t * If `target` is a unhydrated node, returns its MapTreeNode.\n\t * If `target` is a cooked node (or marinated but a FlexTreeNode exists) returns the FlexTreeNode.\n\t * If the target is not a node, or a marinated node with no FlexTreeNode for its anchor, returns undefined.\n\t */\n\tpublic tryGetInnerNode(): InnerNode | undefined {\n\t\tif (isFlexTreeNode(this.innerNode)) {\n\t\t\t// Cooked case\n\t\t\treturn this.innerNode;\n\t\t}\n\n\t\tif (this.#hydrated === undefined) {\n\t\t\t// Unhydrated case\n\t\t\treturn this.innerNode;\n\t\t}\n\n\t\t// Marinated case -> cooked\n\t\tconst anchorNode = this.#hydrated.anchorNode;\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\treturn anchorNode.slots.get(flexTreeSlot);\n\t}\n}\n\n/**\n * Used by {@link anchorProxy} as an optimization to ensure that only one anchor is remembered at a time for a given anchor node\n */\nconst anchorForgetters = new WeakMap<TreeNode, () => void>();\n\nconst kernelEvents = [\"childrenChangedAfterBatch\", \"subtreeChangedAfterBatch\"] as const;\n\ntype KernelEvents = Pick<AnchorEvents, (typeof kernelEvents)[number]>;\n\n/**\n * For \"cooked\" nodes this is a FlexTreeNode thats a projection of forest content.\n * For {@link Unhydrated} nodes this is a MapTreeNode.\n * For \"marinated\" nodes, some code (ex: getOrCreateInnerNode) returns the FlexTreeNode thats a projection of forest content, and some code (ex: tryGetInnerNode) returns undefined.\n *\n * @remarks\n * Currently MapTreeNode extends FlexTreeNode, and most code which can work with either just uses FlexTreeNode.\n * TODO: Code should be migrating toward using this type to distinguish to two use-cases.\n *\n * TODO: The inconsistent handling of \"marinated\" cases should be cleaned up.\n * Maybe getOrCreateInnerNode should cook marinated nodes so they have a proper InnerNode?\n */\nexport type InnerNode = FlexTreeNode | MapTreeNode;\n\n/**\n * {@inheritdoc proxyToMapTreeNode}\n */\nconst mapTreeNodeToProxy = new WeakMap<MapTreeNode, TreeNode>();\n\n/**\n * An anchor slot which associates an anchor with its corresponding TreeNode, if there is one.\n * @remarks\n * For this to work, we have to require that there is at most a single view using a given AnchorSet.\n * FlexTree already has this assumption, and we also assume there is a single simple-tree per FlexTree, so this is valid.\n */\nconst proxySlot = anchorSlot<TreeNode>();\n\n/**\n * Retrieves the proxy associated with the given flex node via {@link setInnerNode}, if any.\n */\nexport function tryGetCachedTreeNode(flexNode: InnerNode): TreeNode | undefined {\n\tif (isMapTreeNode(flexNode)) {\n\t\t// Unhydrated case\n\t\treturn mapTreeNodeToProxy.get(flexNode);\n\t}\n\t// Hydrated case\n\treturn flexNode.anchorNode.slots.get(proxySlot);\n}\n\nexport function tryDisposeTreeNode(anchorNode: AnchorNode): void {\n\tconst treeNode = anchorNode.slots.get(proxySlot);\n\tif (treeNode !== undefined) {\n\t\tconst kernel = getKernel(treeNode);\n\t\tkernel.dispose();\n\t}\n}\n"]}

package/dist/simple-tree/core/treeNodeSchema.d.ts

@@ -21,7 +21,7 @@ export type TreeNodeSchema<Name extends string = string, Kind extends NodeKind =
  * This is used for schema which cannot have their instances constructed using constructors, like leaf schema.
  * @privateRemarks
  * Non-class based schema can have issues with recursive types due to https://github.com/microsoft/TypeScript/issues/55832.
- * @sealed @public
+ * @system @sealed @public
  */
 export interface TreeNodeSchemaNonClass<out Name extends string = string, out Kind extends NodeKind = NodeKind, out TNode = unknown, in TInsertable = never, out ImplicitlyConstructable extends boolean = boolean, out Info = unknown> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {
     create(data: TInsertable): TNode;

package/dist/simple-tree/core/treeNodeSchema.js.map

@@ -1 +1 @@
-{"version":3,"file":"treeNodeSchema.js","sourceRoot":"","sources":["../../../src/simple-tree/core/treeNodeSchema.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AA2JH;;;;;GAKG;AACH,IAAY,QAmBX;AAnBD,WAAY,QAAQ;IACnB;;OAEG;IACH,qCAAG,CAAA;IACH;;OAEG;IACH,yCAAK,CAAA;IACL;;;;OAIG;IACH,2CAAM,CAAA;IACN;;OAEG;IACH,uCAAI,CAAA;AACL,CAAC,EAnBW,QAAQ,wBAAR,QAAQ,QAmBnB","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { InternalTreeNode, Unhydrated } from \"./types.js\";\n\n/**\n * Schema for a tree node.\n * @typeParam Name - The full (including scope) name/identifier for the schema.\n * @typeParam Kind - Which kind of node this schema is for.\n * @typeParam TNode - API for nodes that use this schema.\n * @typeParam TBuild - Data which can be used to construct an {@link Unhydrated} node of this type.\n * @typeParam Info - Data used when defining this schema.\n * @remarks\n * Captures the schema both as runtime data and compile time type information.\n * @sealed @public\n */\nexport type TreeNodeSchema<\n\tName extends string = string,\n\tKind extends NodeKind = NodeKind,\n\tTNode = unknown,\n\tTBuild = never,\n\tImplicitlyConstructable extends boolean = boolean,\n\tInfo = unknown,\n> =\n\t| TreeNodeSchemaClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>\n\t| TreeNodeSchemaNonClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>;\n\n/**\n * Schema which is not a class.\n * @remarks\n * This is used for schema which cannot have their instances constructed using constructors, like leaf schema.\n * @privateRemarks\n * Non-class based schema can have issues with recursive types due to https://github.com/microsoft/TypeScript/issues/55832.\n * @sealed @public\n */\nexport interface TreeNodeSchemaNonClass<\n\tout Name extends string = string,\n\tout Kind extends NodeKind = NodeKind,\n\tout TNode = unknown,\n\tin TInsertable = never,\n\tout ImplicitlyConstructable extends boolean = boolean,\n\tout Info = unknown,\n> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {\n\tcreate(data: TInsertable): TNode;\n}\n\n/**\n * Tree node schema which is implemented using a class.\n * @remarks\n * Instances of this class are nodes in the tree.\n * This is also a constructor so that it can be subclassed.\n *\n * Using classes in this way allows introducing a named type and a named value at the same time, helping keep the runtime and compile time information together and easy to refer to un a uniform way.\n * Additionally, this works around https://github.com/microsoft/TypeScript/issues/55832 which causes similar patterns with less explicit types to infer \"any\" in the d.ts file.\n *\n * When sub-classing a a `TreeNodeSchemaClass`, some extra rules must be followed:\n *\n * - Only ever use a single class from the schema's class hierarchy within a document and its schema.\n * For example, if using {@link SchemaFactory.object} you can do:\n * ```typescript\n * // Recommended \"customizable\" object schema pattern.\n * class Good extends schemaFactory.object(\"A\", {\n * \texampleField: schemaFactory.number,\n * }) {\n * \tpublic exampleCustomMethod(): void {\n * \t\tthis.exampleField++;\n * \t}\n * }\n * ```\n * But should avoid:\n * ```typescript\n * // This by itself is ok, and opts into \"POJO mode\".\n * const base = schemaFactory.object(\"A\", {});\n * // This is a bad pattern since it leaves two classes in scope which derive from the same SchemaFactory defined class.\n * // If both get used, its an error!\n * class Invalid extends base {}\n * ```\n * - Do not modify the constructor input parameter types or values:\n * ```typescript\n * class Invalid extends schemaFactory.object(\"A\", {\n * \texampleField: schemaFactory.number,\n * }) {\n * \t// This Modifies the type of the constructor input.\n * \t// This is unsupported due to programmatic access to the constructor being used internally.\n * \tpublic constructor(a: number) {\n * \t\tsuper({ exampleField: a });\n * \t}\n * }\n * ```\n * @sealed @public\n */\nexport interface TreeNodeSchemaClass<\n\tout Name extends string = string,\n\tout Kind extends NodeKind = NodeKind,\n\tout TNode = unknown,\n\tin TInsertable = never,\n\tout ImplicitlyConstructable extends boolean = boolean,\n\tout Info = unknown,\n> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {\n\t/**\n\t * Constructs an {@link Unhydrated} node with this schema.\n\t * @remarks\n\t * This constructor is also used internally to construct hydrated nodes with a different parameter type.\n\t * Therefore, overriding this constructor with different argument types is not type-safe and is not supported.\n\t * @sealed\n\t */\n\tnew (data: TInsertable | InternalTreeNode): Unhydrated<TNode>;\n}\n/**\n * Data common to all tree node schema.\n * @remarks\n * Implementation detail of {@link TreeNodeSchema} which should be accessed instead of referring to this type directly.\n * @sealed @public\n */\n\nexport interface TreeNodeSchemaCore<\n\tout Name extends string,\n\tout Kind extends NodeKind,\n\tout ImplicitlyConstructable extends boolean,\n\tout Info = unknown,\n> {\n\t/**\n\t * Unique (within a document's schema) identifier used to associate nodes with their schema.\n\t * @remarks\n\t * This is used when encoding nodes, and when decoding nodes to re-associate them with the schema.\n\t * Since this decoding may happen in a different version of the application (or even a different application altogether),\n\t * this identifier should generally correspond to some specific semantics for the data (how to interpret the node with this identifier).\n\t * Any time the semantics change such that data would be misinterpreted if the old semantics were applied\n\t * (for example the units of a value are changed),\n\t * it is best practice to pick a new identifier.\n\t */\n\treadonly identifier: Name;\n\treadonly kind: Kind;\n\n\t/**\n\t * Data used to define this schema.\n\t *\n\t * @remarks\n\t * The format depends on the kind of node it is for.\n\t * For example, the \"object\" node kind could store the field schema here.\n\t */\n\treadonly info: Info;\n\n\t/**\n\t * When constructing insertable content,\n\t * data that could be passed to the node's constructor can be used instead of an {@link Unhydrated} node\n\t * iff implicitlyConstructable is true.\n\t * @privateRemarks\n\t * Currently the logic for traversing insertable content,\n\t * both to build trees and to hydrate them does not defer to the schema classes to handle the policy,\n\t * so if their constructors differ from what is supported, some cases will not work.\n\t * Setting this to false adjusts the insertable types to disallow cases which could be impacted by these inconsistencies.\n\t */\n\treadonly implicitlyConstructable: ImplicitlyConstructable;\n}\n\n/**\n * Kind of tree node.\n * @remarks\n * More kinds may be added over time, so do not assume this is an exhaustive set.\n * @public\n */\nexport enum NodeKind {\n\t/**\n\t * A node which serves as a map, storing children under string keys.\n\t */\n\tMap,\n\t/**\n\t * A node which serves as an array, storing children in an ordered sequence.\n\t */\n\tArray,\n\t/**\n\t * A node which stores a heterogenous collection of children in named fields.\n\t * @remarks\n\t * Each field gets its own schema.\n\t */\n\tObject,\n\t/**\n\t * A node which stores a single leaf value.\n\t */\n\tLeaf,\n}\n"]}
+{"version":3,"file":"treeNodeSchema.js","sourceRoot":"","sources":["../../../src/simple-tree/core/treeNodeSchema.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AA2JH;;;;;GAKG;AACH,IAAY,QAmBX;AAnBD,WAAY,QAAQ;IACnB;;OAEG;IACH,qCAAG,CAAA;IACH;;OAEG;IACH,yCAAK,CAAA;IACL;;;;OAIG;IACH,2CAAM,CAAA;IACN;;OAEG;IACH,uCAAI,CAAA;AACL,CAAC,EAnBW,QAAQ,wBAAR,QAAQ,QAmBnB","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { InternalTreeNode, Unhydrated } from \"./types.js\";\n\n/**\n * Schema for a tree node.\n * @typeParam Name - The full (including scope) name/identifier for the schema.\n * @typeParam Kind - Which kind of node this schema is for.\n * @typeParam TNode - API for nodes that use this schema.\n * @typeParam TBuild - Data which can be used to construct an {@link Unhydrated} node of this type.\n * @typeParam Info - Data used when defining this schema.\n * @remarks\n * Captures the schema both as runtime data and compile time type information.\n * @sealed @public\n */\nexport type TreeNodeSchema<\n\tName extends string = string,\n\tKind extends NodeKind = NodeKind,\n\tTNode = unknown,\n\tTBuild = never,\n\tImplicitlyConstructable extends boolean = boolean,\n\tInfo = unknown,\n> =\n\t| TreeNodeSchemaClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>\n\t| TreeNodeSchemaNonClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>;\n\n/**\n * Schema which is not a class.\n * @remarks\n * This is used for schema which cannot have their instances constructed using constructors, like leaf schema.\n * @privateRemarks\n * Non-class based schema can have issues with recursive types due to https://github.com/microsoft/TypeScript/issues/55832.\n * @system @sealed @public\n */\nexport interface TreeNodeSchemaNonClass<\n\tout Name extends string = string,\n\tout Kind extends NodeKind = NodeKind,\n\tout TNode = unknown,\n\tin TInsertable = never,\n\tout ImplicitlyConstructable extends boolean = boolean,\n\tout Info = unknown,\n> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {\n\tcreate(data: TInsertable): TNode;\n}\n\n/**\n * Tree node schema which is implemented using a class.\n * @remarks\n * Instances of this class are nodes in the tree.\n * This is also a constructor so that it can be subclassed.\n *\n * Using classes in this way allows introducing a named type and a named value at the same time, helping keep the runtime and compile time information together and easy to refer to un a uniform way.\n * Additionally, this works around https://github.com/microsoft/TypeScript/issues/55832 which causes similar patterns with less explicit types to infer \"any\" in the d.ts file.\n *\n * When sub-classing a a `TreeNodeSchemaClass`, some extra rules must be followed:\n *\n * - Only ever use a single class from the schema's class hierarchy within a document and its schema.\n * For example, if using {@link SchemaFactory.object} you can do:\n * ```typescript\n * // Recommended \"customizable\" object schema pattern.\n * class Good extends schemaFactory.object(\"A\", {\n * \texampleField: schemaFactory.number,\n * }) {\n * \tpublic exampleCustomMethod(): void {\n * \t\tthis.exampleField++;\n * \t}\n * }\n * ```\n * But should avoid:\n * ```typescript\n * // This by itself is ok, and opts into \"POJO mode\".\n * const base = schemaFactory.object(\"A\", {});\n * // This is a bad pattern since it leaves two classes in scope which derive from the same SchemaFactory defined class.\n * // If both get used, its an error!\n * class Invalid extends base {}\n * ```\n * - Do not modify the constructor input parameter types or values:\n * ```typescript\n * class Invalid extends schemaFactory.object(\"A\", {\n * \texampleField: schemaFactory.number,\n * }) {\n * \t// This Modifies the type of the constructor input.\n * \t// This is unsupported due to programmatic access to the constructor being used internally.\n * \tpublic constructor(a: number) {\n * \t\tsuper({ exampleField: a });\n * \t}\n * }\n * ```\n * @sealed @public\n */\nexport interface TreeNodeSchemaClass<\n\tout Name extends string = string,\n\tout Kind extends NodeKind = NodeKind,\n\tout TNode = unknown,\n\tin TInsertable = never,\n\tout ImplicitlyConstructable extends boolean = boolean,\n\tout Info = unknown,\n> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {\n\t/**\n\t * Constructs an {@link Unhydrated} node with this schema.\n\t * @remarks\n\t * This constructor is also used internally to construct hydrated nodes with a different parameter type.\n\t * Therefore, overriding this constructor with different argument types is not type-safe and is not supported.\n\t * @sealed\n\t */\n\tnew (data: TInsertable | InternalTreeNode): Unhydrated<TNode>;\n}\n/**\n * Data common to all tree node schema.\n * @remarks\n * Implementation detail of {@link TreeNodeSchema} which should be accessed instead of referring to this type directly.\n * @sealed @public\n */\n\nexport interface TreeNodeSchemaCore<\n\tout Name extends string,\n\tout Kind extends NodeKind,\n\tout ImplicitlyConstructable extends boolean,\n\tout Info = unknown,\n> {\n\t/**\n\t * Unique (within a document's schema) identifier used to associate nodes with their schema.\n\t * @remarks\n\t * This is used when encoding nodes, and when decoding nodes to re-associate them with the schema.\n\t * Since this decoding may happen in a different version of the application (or even a different application altogether),\n\t * this identifier should generally correspond to some specific semantics for the data (how to interpret the node with this identifier).\n\t * Any time the semantics change such that data would be misinterpreted if the old semantics were applied\n\t * (for example the units of a value are changed),\n\t * it is best practice to pick a new identifier.\n\t */\n\treadonly identifier: Name;\n\treadonly kind: Kind;\n\n\t/**\n\t * Data used to define this schema.\n\t *\n\t * @remarks\n\t * The format depends on the kind of node it is for.\n\t * For example, the \"object\" node kind could store the field schema here.\n\t */\n\treadonly info: Info;\n\n\t/**\n\t * When constructing insertable content,\n\t * data that could be passed to the node's constructor can be used instead of an {@link Unhydrated} node\n\t * iff implicitlyConstructable is true.\n\t * @privateRemarks\n\t * Currently the logic for traversing insertable content,\n\t * both to build trees and to hydrate them does not defer to the schema classes to handle the policy,\n\t * so if their constructors differ from what is supported, some cases will not work.\n\t * Setting this to false adjusts the insertable types to disallow cases which could be impacted by these inconsistencies.\n\t */\n\treadonly implicitlyConstructable: ImplicitlyConstructable;\n}\n\n/**\n * Kind of tree node.\n * @remarks\n * More kinds may be added over time, so do not assume this is an exhaustive set.\n * @public\n */\nexport enum NodeKind {\n\t/**\n\t * A node which serves as a map, storing children under string keys.\n\t */\n\tMap,\n\t/**\n\t * A node which serves as an array, storing children in an ordered sequence.\n\t */\n\tArray,\n\t/**\n\t * A node which stores a heterogenous collection of children in named fields.\n\t * @remarks\n\t * Each field gets its own schema.\n\t */\n\tObject,\n\t/**\n\t * A node which stores a single leaf value.\n\t */\n\tLeaf,\n}\n"]}

package/dist/simple-tree/core/types.d.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 import type { ErasedType } from "@fluidframework/core-interfaces";
-import { NodeKind, type TreeNodeSchemaClass } from "./treeNodeSchema.js";
+import { type TreeNodeSchemaClass } from "./treeNodeSchema.js";
 import { type WithType, typeNameSymbol, type typeSchemaSymbol } from "./withType.js";
 import { type FlexTreeNode } from "../../feature-libraries/index.js";
 /**
@@ -13,26 +13,19 @@ import { type FlexTreeNode } from "../../feature-libraries/index.js";
  *
  * Since un-hydrated nodes become hydrated when inserted, strong typing can't be used to distinguish them.
  * This no-op wrapper is used instead.
+ * @remarks
+ * Nodes which are Unhydrated report {@link TreeStatus}.new from `Tree.status(node)`.
+ * @privateRemarks
+ * TODO: Linking tree status is failing in intellisense and linking directly to its .new item is failing in API extractor as well.
+ * WOuld be nice to have a working link here.
  * @public
  */
 export type Unhydrated<T> = T;
-/**
- * Data included for {@link TreeChangeEvents.nodeChanged}.
- * @public
- */
-export interface NodeChangedData {
-    /**
-     * When the node changed is an object or Map node, this lists all the properties which changed.
-     * @remarks
-     * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).
-     */
-    readonly changedProperties?: ReadonlySet<string>;
-}
 /**
  * A collection of events that can be emitted by a {@link TreeNode}.
  *
  * @remarks
- * Currently events can be subscribed to for {@link Unhydrated} nodes, however no events will be triggered for the nodes until after they are hydrated.
+ * Currently, events can be subscribed to for {@link Unhydrated} nodes, however no events will be triggered for the nodes until after they are hydrated.
  * This is considered a known issue, and should be fixed in future versions.
  * Do not rely on the fact that editing unhydrated nodes does not trigger their events.
  *
@@ -54,16 +47,21 @@ export interface NodeChangedData {
  *
  * @sealed @public
  */
-export interface TreeChangeEvents<TNode = TreeNode> {
+export interface TreeChangeEvents {
     /**
      * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.
      *
-     * - Object nodes define a change as the value of one of its properties changing (i.e., the property's value is set, including when set to undefined).
+     * - Object nodes define a change as being when the value of one of its properties changes (i.e., the property's value is set, including when set to `undefined`).
      *
-     * - Array node define a change as when an element is added, removed, moved or replaced.
+     * - Array nodes define a change as when an element is added, removed, moved or replaced.
      *
      * - Map nodes define a change as when an entry is added, updated, or removed.
      *
+     * @param unstable - Future versions of this API (such as the one in beta on TreeBeta) may use this argument to provide additional data to the event.
+     * users of this event should ensure that they do not provide a listener callback which has an optional parameter in this position, since unexpected data might get provided to it.
+     * This parameter exists to capture this fact in the type system.
+     * Using an inline lambda expression as the listener callback is a good pattern to avoid cases like this were arguments are added from breaking due to optional arguments.
+     *
      * @remarks
      * This event is not emitted when:
      *
@@ -85,9 +83,9 @@ export interface TreeChangeEvents<TNode = TreeNode> {
      * 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).
      *
-     * TODO: defined and document event ordering (ex: bottom up, with nodeChanged before treeCHange on each level).
+     * TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).
      */
-    nodeChanged(data: NodeChangedData & (TNode extends WithType<string, NodeKind.Map | NodeKind.Object> ? Required<Pick<NodeChangedData, "changedProperties">> : unknown)): void;
+    nodeChanged(unstable?: unknown): 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.
@@ -106,7 +104,6 @@ export interface TreeChangeEvents<TNode = TreeNode> {
      */
     treeChanged(): void;
 }
-export type IsListener2<TListener> = TListener extends (...args: any[]) => void ? true : false;
 /**
  * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
  *

package/dist/simple-tree/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAElE,OAAO,EAAE,QAAQ,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAEzE,OAAO,EAAE,KAAK,QAAQ,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAErF,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC;AAE9B;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,QAAQ;IACjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,WAAW,CACV,IAAI,EAAE,eAAe,GAEpB,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,GAC5D,QAAQ,CAAC,IAAI,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAC,GACpD,OAAO,CAAC,GACV,IAAI,CAAC;IAER;;;;;;;;;;;;;;;OAeG;IACH,WAAW,IAAI,IAAI,CAAC;CACpB;AAED,MAAM,MAAM,WAAW,CAAC,SAAS,IAAI,SAAS,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,QAAS,YAAW,QAAQ;;IA6BjD;;;;;OAKG;IAEH,aAAoB,CAAC,cAAc,CAAC,IAAI,MAAM,CAAC;IAE/C;;;;OAIG;IACH,aAAoB,CAAC,gBAAgB,CAAC,IAAI,mBAAmB,CAAC;IAE9D;;;;;;OAMG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ;IAErE;;;;;;OAMG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CACjC,OAAO,SAAS,QAAQ,MACvB,GAAG,IAAI,EAAE,GAAG,EAAE,KACV,QAAQ,EACZ,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAAC,OAAO,CAAC;IAahE;;;;;;;OAOG;IACH,SAAS,aAAa,KAAK,EAAE,OAAO;CAKpC;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,IAAK,CAAC;AAE/B;;;;;GAKG;AAEH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAS9E;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAChB,SAAQ,UAAU,CAAC,uCAAuC,CAAC;CAAG;AAE/D,wBAAgB,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAGnE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAElE,OAAO,EAAY,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAEzE,OAAO,EAAE,KAAK,QAAQ,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAErF,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAErF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,WAAW,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAEtC;;;;;;;;;;;;;;;OAeG;IACH,WAAW,IAAI,IAAI,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,QAAS,YAAW,QAAQ;;IA6BjD;;;;;OAKG;IAEH,aAAoB,CAAC,cAAc,CAAC,IAAI,MAAM,CAAC;IAE/C;;;;OAIG;IACH,aAAoB,CAAC,gBAAgB,CAAC,IAAI,mBAAmB,CAAC;IAE9D;;;;;;OAMG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ;IAErE;;;;;;OAMG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CACjC,OAAO,SAAS,QAAQ,MACvB,GAAG,IAAI,EAAE,GAAG,EAAE,KACV,QAAQ,EACZ,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAAC,OAAO,CAAC;IAahE;;;;;;;OAOG;IACH,SAAS,aAAa,KAAK,EAAE,OAAO;CAKpC;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,IAAK,CAAC;AAE/B;;;;;GAKG;AAEH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAS9E;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAChB,SAAQ,UAAU,CAAC,uCAAuC,CAAC;CAAG;AAE/D,wBAAgB,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAGnE"}

package/dist/simple-tree/core/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/simple-tree/core/types.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;AAEH,kEAA6D;AAC7D,uEAAsE;AAGtE,2DAAyE;AACzE,gDAAgD;AAChD,+CAAqF;AACrF,2DAA2D;AAC3D,+DAAqF;AAkHrF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAsB,QAAQ;IAmEtB,MAAM,CAAC,mCAAC,MAAM,CAAC,WAAW,EAAC,CAA8B,KAAc;QAC7E,MAAM,MAAM,GAAG,IAAA,wCAAoB,EAAC,KAAK,CAAC,CAAC;QAE3C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,4BAAQ,CAAC,IAAI,EAAE,CAAC;YAC3D,OAAO,KAAK,CAAC;QACd,CAAC;QAED,IAAA,iBAAM,EAAC,WAAW,IAAI,MAAM,EAAE,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACvE,OAAO,gBAAgB,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;;OAOG;IACH,YAAsB,KAAc;QArFpC;;;;;;;;;;;;;;;;;;;;;;;;;WAyBG;QACM,kCAAiB;QA4DzB,IAAI,KAAK,KAAK,oBAAY,EAAE,CAAC;YAC5B,MAAM,IAAI,qBAAU,CAAC,+DAA+D,CAAC,CAAC;QACvF,CAAC;IACF,CAAC;CACD;AA3FD,4BA2FC;AAED;;GAEG;AACU,QAAA,YAAY,GAAG,EAAE,CAAC;AAE/B;;;;;GAKG;AACH,kDAAkD;AAClD,SAAgB,gBAAgB,CAAC,OAAsB,EAAE,IAAY;IACpE,IAAI,QAAQ,GAAG,OAAO,CAAC;IACvB,OAAO,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC1B,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;QACD,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AATD,4CASC;AAaD,SAAgB,cAAc,CAAC,IAAsB;IACpD,IAAA,iBAAM,EAAC,IAAA,yBAAc,EAAC,IAAI,CAAC,EAAE,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACnE,OAAO,IAAI,CAAC;AACb,CAAC;AAHD,wCAGC","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 { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport type { ErasedType } from \"@fluidframework/core-interfaces\";\n\nimport { NodeKind, type TreeNodeSchemaClass } from \"./treeNodeSchema.js\";\n// eslint-disable-next-line import/no-deprecated\nimport { type WithType, typeNameSymbol, type typeSchemaSymbol } from \"./withType.js\";\nimport { tryGetTreeNodeSchema } from \"./treeNodeKernel.js\";\nimport { isFlexTreeNode, type FlexTreeNode } from \"../../feature-libraries/index.js\";\n\n/**\n * Type alias to document which values are un-hydrated.\n *\n * Un-hydrated values are nodes produced from schema's create functions that haven't been inserted into a tree yet.\n *\n * Since un-hydrated nodes become hydrated when inserted, strong typing can't be used to distinguish them.\n * This no-op wrapper is used instead.\n * @public\n */\nexport type Unhydrated<T> = T;\n\n/**\n * Data included for {@link TreeChangeEvents.nodeChanged}.\n * @public\n */\nexport interface NodeChangedData {\n\t/**\n\t * When the node changed is an object or Map node, this lists all the properties which changed.\n\t * @remarks\n\t * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).\n\t */\n\treadonly changedProperties?: ReadonlySet<string>;\n}\n\n/**\n * A collection of events that can be emitted by a {@link TreeNode}.\n *\n * @remarks\n * Currently events can be subscribed to for {@link Unhydrated} nodes, however no events will be triggered for the nodes until after they are hydrated.\n * This is considered a known issue, and should be fixed in future versions.\n * Do not rely on the fact that editing unhydrated nodes does not trigger their events.\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<TNode = TreeNode> {\n\t/**\n\t * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.\n\t *\n\t * - Object nodes define a change as the value of one of its properties changing (i.e., the property's value is set, including when set to undefined).\n\t *\n\t * - Array node define a change as when an element is added, removed, moved or replaced.\n\t *\n\t * - Map nodes define a change as 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 the event 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\t * TODO: defined and document event ordering (ex: bottom up, with nodeChanged before treeCHange on each level).\n\t */\n\tnodeChanged(\n\t\tdata: NodeChangedData &\n\t\t\t// For object and Map nodes, make properties specific to them required instead of optional:\n\t\t\t(TNode extends WithType<string, NodeKind.Map | NodeKind.Object>\n\t\t\t\t? Required<Pick<NodeChangedData, \"changedProperties\">>\n\t\t\t\t: unknown),\n\t): 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\nexport type IsListener2<TListener> = TListener extends (...args: any[]) => void ? true : false;\n\n/**\n * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.\n *\n * @remarks\n * Base type which all nodes implement.\n *\n * This can be used as a type to indicate/document values which should be tree nodes.\n * Runtime use of this class object (for example when used with `instanceof` or extending it), is not currently supported.\n *\n * Instances of tree nodes must be created by opening an existing document, inserting values into the document,\n * or by using the constructors and create functions of {@link TreeNodeSchema} produced by {@link SchemaFactory}.\n * @privateRemarks\n * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})\n * and some runtime enforcement of schema class policy (see the the validation in the constructor).\n * This class is however only `type` exported not value exported, preventing the class object from being used,\n * similar to how interfaces work.\n *\n * Not all node implementations include this in their prototype chain (some hide it with a proxy),\n * and thus cause the default/built in `instanceof` to return false despite our type checking and all other APIs treating them as TreeNodes.\n * This class provides a custom `Symbol.hasInstance` to fix `instanceof` for this class and all classes extending it.\n * For now the type-only export prevents use of `instanceof` on this class (but allows it in subclasses like schema classes).\n * @sealed @public\n */\nexport abstract class TreeNode implements WithType {\n\t/**\n\t * This is added to prevent TypeScript from implicitly allowing non-TreeNode types to be used as TreeNodes.\n\t * @remarks\n\t * This field forces TypeScript to use nominal instead of structural typing,\n\t * preventing compiler error messages and tools like \"add missing properties\"\n\t * from adding the [type] field as a solution when using a non-TreeNode object where a TreeNode is required.\n\t * Instead TreeNodes must be created through the appropriate APIs, see the documentation on {@link TreeNode} for details.\n\t *\n\t * @privateRemarks\n\t * This is a JavaScript private field, so is not accessible from outside this class.\n\t * This prevents it from having name collisions with object fields.\n\t * Since this is private, the type of this field is stripped in the d.ts file.\n\t * To get matching type checking within and from outside the package, the least informative type (`unknown`) is used.\n\t * To avoid this having any runtime impact, the field is uninitialized.\n\t *\n\t * Making this field optional results in different type checking within this project than outside of it, since the d.ts file drops the optional aspect of the field.\n\t * This is extra confusing since since the tests get in-project typing for intellisense and separate project checking at build time.\n\t * To avoid all this mess, this field is required, not optional.\n\t *\n\t * Another option would be to use a symbol (possibly as a private field).\n\t * That approach ran into some strange difficulties causing SchemaFactory to fail to compile, and was not investigated further.\n\t *\n\t * The [type] symbol provides a lot of the value this private brand does, but is not all of it:\n\t * someone could manually (or via Intellisense auto-implement completion, or in response to a type error)\n\t * make an object literal with the [type] field and pass it off as a node: this private brand prevents that.\n\t */\n\treadonly #brand!: unknown;\n\n\t/**\n\t * Adds a type symbol for stronger typing.\n\t * @privateRemarks\n\t * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.\n\t * @deprecated Use {@link typeSchemaSymbol} instead.\n\t */\n\t// eslint-disable-next-line import/no-deprecated\n\tpublic abstract get [typeNameSymbol](): string;\n\n\t/**\n\t * Adds a type symbol for stronger typing.\n\t * @privateRemarks\n\t * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.\n\t */\n\tpublic abstract get [typeSchemaSymbol](): TreeNodeSchemaClass;\n\n\t/**\n\t * Provides `instanceof` support for testing if a value is a `TreeNode`.\n\t * @remarks\n\t * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.\n\t * @privateRemarks\n\t * Due to type-only export, this functionality is not available outside the package.\n\t */\n\tpublic static [Symbol.hasInstance](value: unknown): value is TreeNode;\n\n\t/**\n\t * Provides `instanceof` support for all schema classes with public constructors.\n\t * @remarks\n\t * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.\n\t * @privateRemarks\n\t * Despite type-only export, this functionality is available outside the package since it is inherited by subclasses.\n\t */\n\tpublic static [Symbol.hasInstance]<\n\t\tTSchema extends abstract new (\n\t\t\t...args: any[]\n\t\t) => TreeNode,\n\t>(this: TSchema, value: unknown): value is InstanceType<TSchema>;\n\n\tpublic static [Symbol.hasInstance](this: { prototype: object }, value: unknown): boolean {\n\t\tconst schema = tryGetTreeNodeSchema(value);\n\n\t\tif (schema === undefined || schema.kind === NodeKind.Leaf) {\n\t\t\treturn false;\n\t\t}\n\n\t\tassert(\"prototype\" in schema, 0x98a /* expected class based schema */);\n\t\treturn inPrototypeChain(schema.prototype, this.prototype);\n\t}\n\n\t/**\n\t * TreeNodes must extend schema classes created by SchemaFactory, and therefore this constructor should not be invoked directly by code outside this package.\n\t * @privateRemarks\n\t * `token` must be the {@link privateToken} value, which is not package exported.\n\t * This is used to detect invalid subclasses.\n\t *\n\t * All valid subclass should use {@link TreeNodeValid}, but this code doesn't directly reference it to avoid cyclic dependencies.\n\t */\n\tprotected constructor(token: unknown) {\n\t\tif (token !== privateToken) {\n\t\t\tthrow new UsageError(\"TreeNodes must extend schema classes created by SchemaFactory\");\n\t\t}\n\t}\n}\n\n/**\n * `token` to pass to {@link TreeNode}'s constructor used to detect invalid subclasses.\n */\nexport const privateToken = {};\n\n/**\n * Check if the prototype derived's prototype chain contains `base`.\n * @param derived - prototype to check\n * @param base - prototype to search for\n * @returns true iff `base` is in the prototype chain starting at `derived`.\n */\n// eslint-disable-next-line @rushstack/no-new-null\nexport function inPrototypeChain(derived: object | null, base: object): boolean {\n\tlet checking = derived;\n\twhile (checking !== null) {\n\t\tif (base === checking) {\n\t\t\treturn true;\n\t\t}\n\t\tchecking = Reflect.getPrototypeOf(checking);\n\t}\n\treturn false;\n}\n\n/**\n * A node type internal to `@fluidframework/tree`.\n * @remarks\n * This type is used in the construction of {@link TreeNode} as an implementation detail, but leaks into the public API due to how schema are implemented.\n * @privateRemarks\n * A {@link FlexTreeNode}. Includes {@link RawTreeNode}s.\n * @sealed @public\n */\nexport interface InternalTreeNode\n\textends ErasedType<\"@fluidframework/tree.InternalTreeNode\"> {}\n\nexport function toFlexTreeNode(node: InternalTreeNode): FlexTreeNode {\n\tassert(isFlexTreeNode(node), 0x963 /* Invalid InternalTreeNode */);\n\treturn node;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/simple-tree/core/types.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;AAEH,kEAA6D;AAC7D,uEAAsE;AAGtE,2DAAyE;AACzE,gDAAgD;AAChD,+CAAqF;AACrF,2DAA2D;AAC3D,+DAAqF;AAuGrF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAsB,QAAQ;IAmEtB,MAAM,CAAC,mCAAC,MAAM,CAAC,WAAW,EAAC,CAA8B,KAAc;QAC7E,MAAM,MAAM,GAAG,IAAA,wCAAoB,EAAC,KAAK,CAAC,CAAC;QAE3C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,4BAAQ,CAAC,IAAI,EAAE,CAAC;YAC3D,OAAO,KAAK,CAAC;QACd,CAAC;QAED,IAAA,iBAAM,EAAC,WAAW,IAAI,MAAM,EAAE,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACvE,OAAO,gBAAgB,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;;OAOG;IACH,YAAsB,KAAc;QArFpC;;;;;;;;;;;;;;;;;;;;;;;;;WAyBG;QACM,kCAAiB;QA4DzB,IAAI,KAAK,KAAK,oBAAY,EAAE,CAAC;YAC5B,MAAM,IAAI,qBAAU,CAAC,+DAA+D,CAAC,CAAC;QACvF,CAAC;IACF,CAAC;CACD;AA3FD,4BA2FC;AAED;;GAEG;AACU,QAAA,YAAY,GAAG,EAAE,CAAC;AAE/B;;;;;GAKG;AACH,kDAAkD;AAClD,SAAgB,gBAAgB,CAAC,OAAsB,EAAE,IAAY;IACpE,IAAI,QAAQ,GAAG,OAAO,CAAC;IACvB,OAAO,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC1B,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;QACD,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AATD,4CASC;AAaD,SAAgB,cAAc,CAAC,IAAsB;IACpD,IAAA,iBAAM,EAAC,IAAA,yBAAc,EAAC,IAAI,CAAC,EAAE,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACnE,OAAO,IAAI,CAAC;AACb,CAAC;AAHD,wCAGC","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 { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport type { ErasedType } from \"@fluidframework/core-interfaces\";\n\nimport { NodeKind, type TreeNodeSchemaClass } from \"./treeNodeSchema.js\";\n// eslint-disable-next-line import/no-deprecated\nimport { type WithType, typeNameSymbol, type typeSchemaSymbol } from \"./withType.js\";\nimport { tryGetTreeNodeSchema } from \"./treeNodeKernel.js\";\nimport { isFlexTreeNode, type FlexTreeNode } from \"../../feature-libraries/index.js\";\n\n/**\n * Type alias to document which values are un-hydrated.\n *\n * Un-hydrated values are nodes produced from schema's create functions that haven't been inserted into a tree yet.\n *\n * Since un-hydrated nodes become hydrated when inserted, strong typing can't be used to distinguish them.\n * This no-op wrapper is used instead.\n * @remarks\n * Nodes which are Unhydrated report {@link TreeStatus}.new from `Tree.status(node)`.\n * @privateRemarks\n * TODO: Linking tree status is failing in intellisense and linking directly to its .new item is failing in API extractor as well.\n * WOuld be nice to have a working link here.\n * @public\n */\nexport type Unhydrated<T> = T;\n\n/**\n * A collection of events that can be emitted by a {@link TreeNode}.\n *\n * @remarks\n * Currently, events can be subscribed to for {@link Unhydrated} nodes, however no events will be triggered for the nodes until after they are hydrated.\n * This is considered a known issue, and should be fixed in future versions.\n * Do not rely on the fact that editing unhydrated nodes does not trigger their events.\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 any of the changes affected the node.\n\t *\n\t * - Object nodes define a change as being when the value of one of its properties changes (i.e., the property's value is set, including when set to `undefined`).\n\t *\n\t * - Array nodes define a change as when an element is added, removed, moved or replaced.\n\t *\n\t * - Map nodes define a change as when an entry is added, updated, or removed.\n\t *\n\t * @param unstable - Future versions of this API (such as the one in beta on TreeBeta) may use this argument to provide additional data to the event.\n\t * users of this event should ensure that they do not provide a listener callback which has an optional parameter in this position, since unexpected data might get provided to it.\n\t * This parameter exists to capture this fact in the type system.\n\t * Using an inline lambda expression as the listener callback is a good pattern to avoid cases like this were arguments are added from breaking due to optional arguments.\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 the event 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\t * TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).\n\t */\n\tnodeChanged(unstable?: unknown): 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\n/**\n * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.\n *\n * @remarks\n * Base type which all nodes implement.\n *\n * This can be used as a type to indicate/document values which should be tree nodes.\n * Runtime use of this class object (for example when used with `instanceof` or extending it), is not currently supported.\n *\n * Instances of tree nodes must be created by opening an existing document, inserting values into the document,\n * or by using the constructors and create functions of {@link TreeNodeSchema} produced by {@link SchemaFactory}.\n * @privateRemarks\n * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})\n * and some runtime enforcement of schema class policy (see the the validation in the constructor).\n * This class is however only `type` exported not value exported, preventing the class object from being used,\n * similar to how interfaces work.\n *\n * Not all node implementations include this in their prototype chain (some hide it with a proxy),\n * and thus cause the default/built in `instanceof` to return false despite our type checking and all other APIs treating them as TreeNodes.\n * This class provides a custom `Symbol.hasInstance` to fix `instanceof` for this class and all classes extending it.\n * For now the type-only export prevents use of `instanceof` on this class (but allows it in subclasses like schema classes).\n * @sealed @public\n */\nexport abstract class TreeNode implements WithType {\n\t/**\n\t * This is added to prevent TypeScript from implicitly allowing non-TreeNode types to be used as TreeNodes.\n\t * @remarks\n\t * This field forces TypeScript to use nominal instead of structural typing,\n\t * preventing compiler error messages and tools like \"add missing properties\"\n\t * from adding the [type] field as a solution when using a non-TreeNode object where a TreeNode is required.\n\t * Instead TreeNodes must be created through the appropriate APIs, see the documentation on {@link TreeNode} for details.\n\t *\n\t * @privateRemarks\n\t * This is a JavaScript private field, so is not accessible from outside this class.\n\t * This prevents it from having name collisions with object fields.\n\t * Since this is private, the type of this field is stripped in the d.ts file.\n\t * To get matching type checking within and from outside the package, the least informative type (`unknown`) is used.\n\t * To avoid this having any runtime impact, the field is uninitialized.\n\t *\n\t * Making this field optional results in different type checking within this project than outside of it, since the d.ts file drops the optional aspect of the field.\n\t * This is extra confusing since since the tests get in-project typing for intellisense and separate project checking at build time.\n\t * To avoid all this mess, this field is required, not optional.\n\t *\n\t * Another option would be to use a symbol (possibly as a private field).\n\t * That approach ran into some strange difficulties causing SchemaFactory to fail to compile, and was not investigated further.\n\t *\n\t * The [type] symbol provides a lot of the value this private brand does, but is not all of it:\n\t * someone could manually (or via Intellisense auto-implement completion, or in response to a type error)\n\t * make an object literal with the [type] field and pass it off as a node: this private brand prevents that.\n\t */\n\treadonly #brand!: unknown;\n\n\t/**\n\t * Adds a type symbol for stronger typing.\n\t * @privateRemarks\n\t * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.\n\t * @deprecated Use {@link typeSchemaSymbol} instead.\n\t */\n\t// eslint-disable-next-line import/no-deprecated\n\tpublic abstract get [typeNameSymbol](): string;\n\n\t/**\n\t * Adds a type symbol for stronger typing.\n\t * @privateRemarks\n\t * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.\n\t */\n\tpublic abstract get [typeSchemaSymbol](): TreeNodeSchemaClass;\n\n\t/**\n\t * Provides `instanceof` support for testing if a value is a `TreeNode`.\n\t * @remarks\n\t * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.\n\t * @privateRemarks\n\t * Due to type-only export, this functionality is not available outside the package.\n\t */\n\tpublic static [Symbol.hasInstance](value: unknown): value is TreeNode;\n\n\t/**\n\t * Provides `instanceof` support for all schema classes with public constructors.\n\t * @remarks\n\t * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.\n\t * @privateRemarks\n\t * Despite type-only export, this functionality is available outside the package since it is inherited by subclasses.\n\t */\n\tpublic static [Symbol.hasInstance]<\n\t\tTSchema extends abstract new (\n\t\t\t...args: any[]\n\t\t) => TreeNode,\n\t>(this: TSchema, value: unknown): value is InstanceType<TSchema>;\n\n\tpublic static [Symbol.hasInstance](this: { prototype: object }, value: unknown): boolean {\n\t\tconst schema = tryGetTreeNodeSchema(value);\n\n\t\tif (schema === undefined || schema.kind === NodeKind.Leaf) {\n\t\t\treturn false;\n\t\t}\n\n\t\tassert(\"prototype\" in schema, 0x98a /* expected class based schema */);\n\t\treturn inPrototypeChain(schema.prototype, this.prototype);\n\t}\n\n\t/**\n\t * TreeNodes must extend schema classes created by SchemaFactory, and therefore this constructor should not be invoked directly by code outside this package.\n\t * @privateRemarks\n\t * `token` must be the {@link privateToken} value, which is not package exported.\n\t * This is used to detect invalid subclasses.\n\t *\n\t * All valid subclass should use {@link TreeNodeValid}, but this code doesn't directly reference it to avoid cyclic dependencies.\n\t */\n\tprotected constructor(token: unknown) {\n\t\tif (token !== privateToken) {\n\t\t\tthrow new UsageError(\"TreeNodes must extend schema classes created by SchemaFactory\");\n\t\t}\n\t}\n}\n\n/**\n * `token` to pass to {@link TreeNode}'s constructor used to detect invalid subclasses.\n */\nexport const privateToken = {};\n\n/**\n * Check if the prototype derived's prototype chain contains `base`.\n * @param derived - prototype to check\n * @param base - prototype to search for\n * @returns true iff `base` is in the prototype chain starting at `derived`.\n */\n// eslint-disable-next-line @rushstack/no-new-null\nexport function inPrototypeChain(derived: object | null, base: object): boolean {\n\tlet checking = derived;\n\twhile (checking !== null) {\n\t\tif (base === checking) {\n\t\t\treturn true;\n\t\t}\n\t\tchecking = Reflect.getPrototypeOf(checking);\n\t}\n\treturn false;\n}\n\n/**\n * A node type internal to `@fluidframework/tree`.\n * @remarks\n * This type is used in the construction of {@link TreeNode} as an implementation detail, but leaks into the public API due to how schema are implemented.\n * @privateRemarks\n * A {@link FlexTreeNode}. Includes {@link RawTreeNode}s.\n * @sealed @public\n */\nexport interface InternalTreeNode\n\textends ErasedType<\"@fluidframework/tree.InternalTreeNode\"> {}\n\nexport function toFlexTreeNode(node: InternalTreeNode): FlexTreeNode {\n\tassert(isFlexTreeNode(node), 0x963 /* Invalid InternalTreeNode */);\n\treturn node;\n}\n"]}

package/dist/simple-tree/core/withType.d.ts

@@ -39,6 +39,7 @@ export declare const typeSchemaSymbol: unique symbol;
  *
  * @typeParam TName - Same as {@link TreeNodeSchema}'s "Name" parameter.
  * @typeParam TKind - Same as {@link TreeNodeSchema}'s "Kind" parameter.
+ * @typeParam TInfo - Same as {@link TreeNodeSchema}'s "Info" parameter: format depends on the Kind.
  * @remarks
  * Powers {@link TreeNode}'s strong typing setup.
  * @example Narrow types for overloading based on NodeKind
@@ -68,7 +69,7 @@ export declare const typeSchemaSymbol: unique symbol;
  * ```
  * @sealed @public
  */
-export interface WithType<out TName extends string = string, out TKind extends NodeKind = NodeKind> {
+export interface WithType<out TName extends string = string, out TKind extends NodeKind = NodeKind, out TInfo = unknown> {
     /**
      * Type symbol, marking a type in a way to increase type safety via strong type checking.
      * @deprecated Use {@link typeSchemaSymbol} instead.
@@ -77,6 +78,6 @@ export interface WithType<out TName extends string = string, out TKind extends N
     /**
      * Type symbol, marking a type in a way to increase type safety via strong type checking.
      */
-    get [typeSchemaSymbol](): TreeNodeSchemaClass<TName, TKind>;
+    get [typeSchemaSymbol](): TreeNodeSchemaClass<TName, TKind, unknown, never, boolean, TInfo>;
 }
 //# sourceMappingURL=withType.d.ts.map

package/dist/simple-tree/core/withType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"withType.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/core/withType.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAEzE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,MAAgC,CAAC;AAErE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAkC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,QAAQ,CACxB,GAAG,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,EACjC,GAAG,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;IAErC;;;OAGG;IACH,IAAI,CAAC,cAAc,CAAC,IAAI,KAAK,CAAC;IAE9B;;OAEG;IACH,IAAI,CAAC,gBAAgB,CAAC,IAAI,mBAAmB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;CAC5D"}
+{"version":3,"file":"withType.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/core/withType.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAEzE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,MAAgC,CAAC;AAErE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAkC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,QAAQ,CACxB,GAAG,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,EACjC,GAAG,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,EACrC,GAAG,CAAC,KAAK,GAAG,OAAO;IAEnB;;;OAGG;IACH,IAAI,CAAC,cAAc,CAAC,IAAI,KAAK,CAAC;IAE9B;;OAEG;IACH,IAAI,CAAC,gBAAgB,CAAC,IAAI,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;CAC5F"}

package/dist/simple-tree/core/withType.js.map

@@ -1 +1 @@
-{"version":3,"file":"withType.js","sourceRoot":"","sources":["../../../src/simple-tree/core/withType.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAIH;;;;;;;;;;;;;GAaG;AACU,QAAA,cAAc,GAAkB,MAAM,CAAC,eAAe,CAAC,CAAC;AAErE;;;;;;;;;;;;;;GAcG;AACU,QAAA,gBAAgB,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { NodeKind, TreeNodeSchemaClass } from \"./treeNodeSchema.js\";\n\n/**\n * The type of a {@link TreeNode}.\n * For more information about the type, use `Tree.schema(theNode)` instead.\n * @remarks\n * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.\n * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.\n *\n * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where nodes are expected.\n * Instead construct a real node of the desired type using its constructor.\n * @privateRemarks\n * This prevents non-nodes from being accidentally used as nodes, as well as allows the type checker to distinguish different node types.\n * @deprecated External code should use `Tree.schema(theNode)` for schema related runtime data access. For type narrowing, use `WithType` instead of the symbols directly.\n * @system @public\n */\nexport const typeNameSymbol: unique symbol = Symbol(\"TreeNode Type\");\n\n/**\n * The type of a {@link TreeNode}.\n * For more information about the type, use `Tree.schema(theNode)` instead.\n * @remarks\n * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.\n * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.\n *\n * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where specific nodes are expected.\n * Instead construct a real node of the desired type using its constructor.\n *\n * This symbol should not be used directly for type narrowing. Instead use {@link WithType}.\n * @privateRemarks\n * This prevents non-nodes from being accidentally used as nodes and allows the type-checker to distinguish different node types.\n * @system @public\n */\nexport const typeSchemaSymbol: unique symbol = Symbol(\"TreeNode Schema\");\n\n/**\n * Adds a type symbol to a type for stronger typing.\n *\n * @typeParam TName - Same as {@link TreeNodeSchema}'s \"Name\" parameter.\n * @typeParam TKind - Same as {@link TreeNodeSchema}'s \"Kind\" parameter.\n * @remarks\n * Powers {@link TreeNode}'s strong typing setup.\n * @example Narrow types for overloading based on NodeKind\n * ```typescript\n * function getKeys(node: TreeNode & WithType<string, NodeKind.Array>): number[];\n * function getKeys(node: TreeNode & WithType<string, NodeKind.Map | NodeKind.Object>): string[];\n * function getKeys(node: TreeNode): string[] | number[];\n * function getKeys(node: TreeNode): string[] | number[] {\n * \tconst schema = Tree.schema(node);\n * \tswitch (schema.kind) {\n * \t\tcase NodeKind.Array: {\n * \t\t\tconst arrayNode = node as TreeArrayNode;\n * \t\t\tconst keys: number[] = [];\n * \t\t\tfor (let index = 0; index < arrayNode.length; index++) {\n * \t\t\t\tkeys.push(index);\n * \t\t\t}\n * \t\t\treturn keys;\n * \t\t}\n * \t\tcase NodeKind.Map:\n * \t\t\treturn [...(node as TreeMapNode).keys()];\n * \t\tcase NodeKind.Object:\n * \t\t\treturn Object.keys(node);\n * \t\tdefault:\n * \t\t\tthrow new Error(\"Unsupported Kind\");\n * \t}\n * }\n * ```\n * @sealed @public\n */\nexport interface WithType<\n\tout TName extends string = string,\n\tout TKind extends NodeKind = NodeKind,\n> {\n\t/**\n\t * Type symbol, marking a type in a way to increase type safety via strong type checking.\n\t * @deprecated Use {@link typeSchemaSymbol} instead.\n\t */\n\tget [typeNameSymbol](): TName;\n\n\t/**\n\t * Type symbol, marking a type in a way to increase type safety via strong type checking.\n\t */\n\tget [typeSchemaSymbol](): TreeNodeSchemaClass<TName, TKind>;\n}\n"]}
+{"version":3,"file":"withType.js","sourceRoot":"","sources":["../../../src/simple-tree/core/withType.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAIH;;;;;;;;;;;;;GAaG;AACU,QAAA,cAAc,GAAkB,MAAM,CAAC,eAAe,CAAC,CAAC;AAErE;;;;;;;;;;;;;;GAcG;AACU,QAAA,gBAAgB,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { NodeKind, TreeNodeSchemaClass } from \"./treeNodeSchema.js\";\n\n/**\n * The type of a {@link TreeNode}.\n * For more information about the type, use `Tree.schema(theNode)` instead.\n * @remarks\n * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.\n * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.\n *\n * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where nodes are expected.\n * Instead construct a real node of the desired type using its constructor.\n * @privateRemarks\n * This prevents non-nodes from being accidentally used as nodes, as well as allows the type checker to distinguish different node types.\n * @deprecated External code should use `Tree.schema(theNode)` for schema related runtime data access. For type narrowing, use `WithType` instead of the symbols directly.\n * @system @public\n */\nexport const typeNameSymbol: unique symbol = Symbol(\"TreeNode Type\");\n\n/**\n * The type of a {@link TreeNode}.\n * For more information about the type, use `Tree.schema(theNode)` instead.\n * @remarks\n * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.\n * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.\n *\n * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where specific nodes are expected.\n * Instead construct a real node of the desired type using its constructor.\n *\n * This symbol should not be used directly for type narrowing. Instead use {@link WithType}.\n * @privateRemarks\n * This prevents non-nodes from being accidentally used as nodes and allows the type-checker to distinguish different node types.\n * @system @public\n */\nexport const typeSchemaSymbol: unique symbol = Symbol(\"TreeNode Schema\");\n\n/**\n * Adds a type symbol to a type for stronger typing.\n *\n * @typeParam TName - Same as {@link TreeNodeSchema}'s \"Name\" parameter.\n * @typeParam TKind - Same as {@link TreeNodeSchema}'s \"Kind\" parameter.\n * @typeParam TInfo - Same as {@link TreeNodeSchema}'s \"Info\" parameter: format depends on the Kind.\n * @remarks\n * Powers {@link TreeNode}'s strong typing setup.\n * @example Narrow types for overloading based on NodeKind\n * ```typescript\n * function getKeys(node: TreeNode & WithType<string, NodeKind.Array>): number[];\n * function getKeys(node: TreeNode & WithType<string, NodeKind.Map | NodeKind.Object>): string[];\n * function getKeys(node: TreeNode): string[] | number[];\n * function getKeys(node: TreeNode): string[] | number[] {\n * \tconst schema = Tree.schema(node);\n * \tswitch (schema.kind) {\n * \t\tcase NodeKind.Array: {\n * \t\t\tconst arrayNode = node as TreeArrayNode;\n * \t\t\tconst keys: number[] = [];\n * \t\t\tfor (let index = 0; index < arrayNode.length; index++) {\n * \t\t\t\tkeys.push(index);\n * \t\t\t}\n * \t\t\treturn keys;\n * \t\t}\n * \t\tcase NodeKind.Map:\n * \t\t\treturn [...(node as TreeMapNode).keys()];\n * \t\tcase NodeKind.Object:\n * \t\t\treturn Object.keys(node);\n * \t\tdefault:\n * \t\t\tthrow new Error(\"Unsupported Kind\");\n * \t}\n * }\n * ```\n * @sealed @public\n */\nexport interface WithType<\n\tout TName extends string = string,\n\tout TKind extends NodeKind = NodeKind,\n\tout TInfo = unknown,\n> {\n\t/**\n\t * Type symbol, marking a type in a way to increase type safety via strong type checking.\n\t * @deprecated Use {@link typeSchemaSymbol} instead.\n\t */\n\tget [typeNameSymbol](): TName;\n\n\t/**\n\t * Type symbol, marking a type in a way to increase type safety via strong type checking.\n\t */\n\tget [typeSchemaSymbol](): TreeNodeSchemaClass<TName, TKind, unknown, never, boolean, TInfo>;\n}\n"]}