@fluidframework/tree 2.0.0-dev-rc.5.0.0.271045 → 2.0.0-dev-rc.5.0.0.271717

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

@@ -2,9 +2,9 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { TreeStatus } from "../feature-libraries/index.js";
-import { NodeKind, type TreeLeafValue, TreeNodeSchema, ImplicitAllowedTypes, TreeNodeFromImplicitAllowedTypes } from "./schemaTypes.js";
-import { TreeNode } from "./types.js";
+import { type TreeStatus } from "../feature-libraries/index.js";
+import { NodeKind, type TreeLeafValue, type TreeNodeSchema, type ImplicitAllowedTypes, type TreeNodeFromImplicitAllowedTypes } from "./schemaTypes.js";
+import type { TreeNode } from "./types.js";
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
  *
@@ -54,11 +54,20 @@ export interface TreeNodeApi {
      */
     readonly status: (node: TreeNode) => TreeStatus;
     /**
-     * Returns the {@link FieldKind.Identifier | identifier} of the given node in the most compressed form possible.
+     * Returns the {@link SchemaFactory.identifier | identifier} of the given node in the most compressed form possible.
      * @remarks
-     * If the node's identifier is a valid `StableNodeKey`, then this will return a unique process-local integer corresponding to that identifier.
-     * If the node's identifier is any other string, then this will return that string.
-     * If the node has no identifier (that is, it has no field of an {@link FieldKind.Identifier | identifier} field kind), then this returns undefined.
+     * If the node's identifier is a valid UUID that was automatically generated by the SharedTree, then this will return a process-unique integer corresponding to that identifier.
+     * This is useful for performance-sensitive scenarios involving many nodes with identifiers that need to be compactly retained in memory or used for efficient lookup.
+     *
+     * If the node's identifier is any other user-provided string, then this will return that string.
+     *
+     * If the node has no identifier (that is, it has no {@link SchemaFactory.identifier | identifier} field), then this returns `undefined`.
+     *
+     * If the node has more than one identifier, then this will throw an error.
+     *
+     * The returned integer must not be serialized or preserved outside of the current process.
+     * Its lifetime is that of the current in-memory instance of the FF container for this client, and it is not guaranteed to be unique or stable outside of that context.
+     * The same node's identifier may, for example, be different across multiple sessions for the same client and document, or different across two clients in the same session.
      */
     shortId(node: TreeNode): number | string | undefined;
 }
@@ -72,7 +81,7 @@ export declare const treeNodeApi: TreeNodeApi;
  */
 export declare function tryGetSchema<T>(value: T): undefined | TreeNodeSchema<string, NodeKind, unknown, T>;
 /**
- * A collection of events that can be raised by a {@link TreeNode}.
+ * A collection of events that can be emitted by a {@link TreeNode}.
  *
  * @privateRemarks
  * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).
@@ -94,7 +103,8 @@ export declare function tryGetSchema<T>(value: T): undefined | TreeNodeSchema<st
  */
 export interface TreeChangeEvents {
     /**
-     * Emitted by a node when a batch of changes is applied to it, where a change is:
+     * Emitted by a node after a batch of changes has been applied to the tree, if a change affected the node, where a
+     * change is:
      *
      * - For an object node, when the value of one of its properties changes (i.e., the property's value is set
      * to something else, including `undefined`).
@@ -104,20 +114,19 @@ export interface TreeChangeEvents {
      * - For a map node, when an entry is added, updated, or removed.
      *
      * @remarks
-     * This event is not raised when:
+     * This event is not emitted when:
      *
      * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing
-     * elements/entries) will raise this event on the array/map node itself, but not on the node that contains the
+     * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the
      * array/map node as one of its properties.
      *
      * - The node is moved to a different location in the tree or removed from the tree.
-     * In this case the event is raised on the _parent_ node, not the node itself.
+     * In this case the event is emitted on the _parent_ node, not the node itself.
      *
      * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
      * the client that made the original edit.
-     * While a batch of edits will as a whole update the tree to the appropriate end state, no guarantees are made about
-     * how many times this event will be raised during any intermediate states.
-     * When it is raised, the tree is guaranteed to be in-schema.
+     *
+     * When it is emitted, the tree is guaranteed to be in-schema.
      *
      * @privateRemarks
      * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.
@@ -127,26 +136,20 @@ export interface TreeChangeEvents {
      */
     nodeChanged(): void;
     /**
-     * Emitted by a node when something _may_ have changed anywhere in the subtree rooted at it.
+     * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the
+     * subtree rooted at it.
      *
      * @remarks
-     * This event is guaranteed to be emitted whenever the subtree _has_ changed.
-     * However, it might also be emitted when the subtree has no visible changes compared to before the event firing.
-     *
-     * Consumers of this event have the guarantee that they won't miss any changes, but should also handle the scenario
-     * where the event fires with no visible changes as well.
-     *
-     * This event is not raised when the node itself is moved to a different location in the tree or removed from the tree.
-     * In that case it is raised on the _parent_ node, not the node itself.
+     * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.
+     * In that case it is emitted on the _parent_ node, not the node itself.
      *
      * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties
      * of the node itself.
      *
      * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
      * the client that made the original edit.
-     * While a batch of edits will as a whole update the tree to the appropriate end state, no guarantees are made about
-     * how many times this event will be raised during any intermediate states.
-     * When it is raised, the tree is guaranteed to be in-schema.
+     *
+     * When it is emitted, the tree is guaranteed to be in-schema.
      */
     treeChanged(): void;
 }

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

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

package/dist/simple-tree/treeNodeApi.js

@@ -15,6 +15,7 @@ const schemaCaching_js_1 = require("./schemaCaching.js");
 const schemaTypes_js_1 = require("./schemaTypes.js");
 const leafNodeSchema_js_1 = require("./leafNodeSchema.js");
 const internal_2 = require("@fluidframework/runtime-utils/internal");
+const internal_3 = require("@fluidframework/telemetry-utils/internal");
 /**
  * The `Tree` object holds various functions for analyzing {@link TreeNode}s.
  */
@@ -80,17 +81,21 @@ exports.treeNodeApi = {
     },
     shortId(node) {
         const flexNode = (0, proxyBinding_js_1.getFlexNode)(node);
+        let shortId;
         for (const field of flexNode.boxedIterator()) {
             if (field.schema.kind === index_js_2.FieldKinds.identifier) {
+                if (shortId !== undefined) {
+                    throw new internal_3.UsageError("shortId() may not be called on a node with more than one identifier. Consider converting extraneous identifier fields to string fields.");
+                }
                 const identifier = field.boxedAt(0);
                 (0, internal_1.assert)(identifier !== undefined, 0x927 /* The identifier must exist */);
                 const identifierValue = identifier.value;
                 const localNodeKey = identifier.context.nodeKeyManager.tryLocalizeNodeKey(identifierValue);
-                return localNodeKey !== undefined
-                    ? (0, index_js_3.extractFromOpaque)(localNodeKey)
-                    : identifierValue;
+                shortId =
+                    localNodeKey !== undefined ? (0, index_js_3.extractFromOpaque)(localNodeKey) : identifierValue;
             }
         }
+        return shortId;
     },
 };
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"treeNodeApi.js","sourceRoot":"","sources":["../../src/simple-tree/treeNodeApi.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert, unreachableCase } from \"@fluidframework/core-utils/internal\";\n\nimport { Multiplicity, rootFieldKey } from \"../core/index.js\";\nimport {\n\tFieldKinds,\n\tLazyItem,\n\tTreeStatus,\n\tisLazy,\n\tisTreeValue,\n} from \"../feature-libraries/index.js\";\nimport { fail, extractFromOpaque, isReadonlyArray } from \"../util/index.js\";\n\nimport { getOrCreateNodeProxy, isTreeNode } from \"./proxies.js\";\nimport { getFlexNode } from \"./proxyBinding.js\";\nimport { tryGetSimpleNodeSchema } from \"./schemaCaching.js\";\nimport {\n\tNodeKind,\n\ttype TreeLeafValue,\n\tTreeNodeSchema,\n\ttype ImplicitFieldSchema,\n\tFieldSchema,\n\tImplicitAllowedTypes,\n\tTreeNodeFromImplicitAllowedTypes,\n} from \"./schemaTypes.js\";\nimport { TreeNode } from \"./types.js\";\nimport {\n\tbooleanSchema,\n\thandleSchema,\n\tnullSchema,\n\tnumberSchema,\n\tstringSchema,\n} from \"./leafNodeSchema.js\";\nimport { isFluidHandle } from \"@fluidframework/runtime-utils/internal\";\n\n/**\n * Provides various functions for analyzing {@link TreeNode}s.\n *\n * @privateRemarks\n * Inlining the typing of this interface onto the `Tree` object provides slightly different .d.ts generation,\n * which avoids typescript expanding the type of TreeNodeSchema and thus encountering\n * https://github.com/microsoft/rushstack/issues/1958.\n * @public\n */\nexport interface TreeNodeApi {\n\t/**\n\t * The schema information for this node.\n\t */\n\tschema<T extends TreeNode | TreeLeafValue>(\n\t\tnode: T,\n\t): TreeNodeSchema<string, NodeKind, unknown, T>;\n\n\t/**\n\t * Narrow the type of the given value if it satisfies the given schema.\n\t * @example\n\t * ```ts\n\t * if (node.is(myNode, Point)) {\n\t *     const y = myNode.y; // `myNode` is now known to satisfy the `Point` schema and therefore has a `y` coordinate.\n\t * }\n\t * ```\n\t */\n\tis<TSchema extends ImplicitAllowedTypes>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is TreeNodeFromImplicitAllowedTypes<TSchema>;\n\n\t/**\n\t * Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).\n\t */\n\tparent(node: TreeNode): TreeNode | undefined;\n\n\t/**\n\t * The key of the given node under its parent.\n\t * @remarks\n\t * If `node` is an element in a {@link (TreeArrayNode:interface)}, this returns the index of `node` in the array node (a `number`).\n\t * Otherwise, this returns the key of the field that it is under (a `string`).\n\t */\n\tkey(node: TreeNode): string | number;\n\n\t/**\n\t * Register an event listener on the given node.\n\t * @param node - The node whose events should be subscribed to.\n\t * @param eventName - Which event to subscribe to.\n\t * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.\n\t * @returns A callback function which will deregister the event.\n\t * This callback should be called only once.\n\t */\n\ton<K extends keyof TreeChangeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeChangeEvents[K],\n\t): () => void;\n\n\t/**\n\t * Returns the {@link TreeStatus} of the given node.\n\t */\n\treadonly status: (node: TreeNode) => TreeStatus;\n\n\t/**\n\t * Returns the {@link FieldKind.Identifier | identifier} of the given node in the most compressed form possible.\n\t * @remarks\n\t * If the node's identifier is a valid `StableNodeKey`, then this will return a unique process-local integer corresponding to that identifier.\n\t * If the node's identifier is any other string, then this will return that string.\n\t * If the node has no identifier (that is, it has no field of an {@link FieldKind.Identifier | identifier} field kind), then this returns undefined.\n\t */\n\tshortId(node: TreeNode): number | string | undefined;\n}\n\n/**\n * The `Tree` object holds various functions for analyzing {@link TreeNode}s.\n */\nexport const treeNodeApi: TreeNodeApi = {\n\tparent: (node: TreeNode): TreeNode | undefined => {\n\t\tconst editNode = getFlexNode(node).parentField.parent.parent;\n\t\tif (editNode === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst output = getOrCreateNodeProxy(editNode);\n\t\tassert(\n\t\t\t!isTreeValue(output),\n\t\t\t0x87f /* Parent can't be a leaf, so it should be a node not a value */,\n\t\t);\n\t\treturn output;\n\t},\n\tkey: (node: TreeNode) => {\n\t\t// If the parent is undefined, then this node is under the root field,\n\t\t// so we know its key is the special root one.\n\t\tconst parent = treeNodeApi.parent(node);\n\t\tif (parent === undefined) {\n\t\t\treturn rootFieldKey;\n\t\t}\n\n\t\t// The flex-domain strictly operates in terms of \"stored keys\".\n\t\t// To find the associated developer-facing \"view key\", we need to look up the field associated with\n\t\t// the stored key from the flex-domain, and get view key its simple-domain counterpart was created with.\n\t\tconst storedKey = getStoredKey(node);\n\t\tconst parentSchema = treeNodeApi.schema(parent);\n\t\tconst viewKey = getViewKeyFromStoredKey(parentSchema, storedKey);\n\t\treturn viewKey;\n\t},\n\ton: <K extends keyof TreeChangeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeChangeEvents[K],\n\t) => {\n\t\tconst flex = getFlexNode(node);\n\t\tswitch (eventName) {\n\t\t\tcase \"nodeChanged\":\n\t\t\t\treturn flex.on(\"nodeChanged\", listener);\n\t\t\tcase \"treeChanged\":\n\t\t\t\treturn flex.on(\"treeChanged\", listener);\n\t\t\tdefault:\n\t\t\t\treturn unreachableCase(eventName);\n\t\t}\n\t},\n\tstatus: (node: TreeNode) => {\n\t\treturn getFlexNode(node, true).treeStatus();\n\t},\n\tis: <TSchema extends ImplicitAllowedTypes>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is TreeNodeFromImplicitAllowedTypes<TSchema> => {\n\t\tconst actualSchema = tryGetSchema(value);\n\t\tif (actualSchema === undefined) {\n\t\t\treturn false;\n\t\t}\n\t\tif (isReadonlyArray<LazyItem<TreeNodeSchema>>(schema)) {\n\t\t\tfor (const singleSchema of schema) {\n\t\t\t\tconst testSchema = isLazy(singleSchema) ? singleSchema() : singleSchema;\n\t\t\t\tif (testSchema === actualSchema) {\n\t\t\t\t\treturn true;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn false;\n\t\t} else {\n\t\t\treturn (schema as TreeNodeSchema) === actualSchema;\n\t\t}\n\t},\n\tschema<T extends TreeNode | TreeLeafValue>(\n\t\tnode: T,\n\t): TreeNodeSchema<string, NodeKind, unknown, T> {\n\t\treturn tryGetSchema(node) ?? fail(\"Not a tree node\");\n\t},\n\tshortId(node: TreeNode): number | string | undefined {\n\t\tconst flexNode = getFlexNode(node);\n\t\tfor (const field of flexNode.boxedIterator()) {\n\t\t\tif (field.schema.kind === FieldKinds.identifier) {\n\t\t\t\tconst identifier = field.boxedAt(0);\n\t\t\t\tassert(identifier !== undefined, 0x927 /* The identifier must exist */);\n\t\t\t\tconst identifierValue = identifier.value as string;\n\t\t\t\tconst localNodeKey =\n\t\t\t\t\tidentifier.context.nodeKeyManager.tryLocalizeNodeKey(identifierValue);\n\t\t\t\treturn localNodeKey !== undefined\n\t\t\t\t\t? extractFromOpaque(localNodeKey)\n\t\t\t\t\t: identifierValue;\n\t\t\t}\n\t\t}\n\t},\n};\n\n/**\n * Returns a schema for a value if the value is a {@link TreeNode} or a {@link TreeLeafValue}.\n * Returns undefined for other values.\n */\nexport function tryGetSchema<T>(\n\tvalue: T,\n): undefined | TreeNodeSchema<string, NodeKind, unknown, T> {\n\ttype TOut = TreeNodeSchema<string, NodeKind, unknown, T>;\n\tswitch (typeof value) {\n\t\tcase \"string\":\n\t\t\treturn stringSchema as TOut;\n\t\tcase \"number\":\n\t\t\treturn numberSchema as TOut;\n\t\tcase \"boolean\":\n\t\t\treturn booleanSchema as TOut;\n\t\tcase \"object\": {\n\t\t\tif (isTreeNode(value)) {\n\t\t\t\t// This case could be optimized, for example by placing the simple schema in a symbol on tree nodes.\n\t\t\t\treturn tryGetSimpleNodeSchema(getFlexNode(value).schema) as TOut;\n\t\t\t}\n\t\t\tif (value === null) {\n\t\t\t\treturn nullSchema as TOut;\n\t\t\t}\n\t\t\tif (isFluidHandle(value)) {\n\t\t\t\treturn handleSchema as TOut;\n\t\t\t}\n\t\t}\n\t\tdefault:\n\t\t\treturn undefined;\n\t}\n}\n\n/**\n * Gets the stored key with which the provided node is associated in the parent.\n */\nfunction getStoredKey(node: TreeNode): string | number {\n\t// Note: the flex domain strictly works with \"stored keys\", and knows nothing about the developer-facing\n\t// \"view keys\".\n\tconst parentField = getFlexNode(node).parentField;\n\tif (parentField.parent.schema.kind.multiplicity === Multiplicity.Sequence) {\n\t\t// The parent of `node` is an array node\n\t\treturn parentField.index;\n\t}\n\n\t// The parent of `node` is an object, a map, or undefined (and therefore `node` is a root/detached node).\n\treturn parentField.parent.key;\n}\n\n/**\n * Given a node schema, gets the view key corresponding with the provided {@link FieldProps.key | stored key}.\n */\nfunction getViewKeyFromStoredKey(\n\tschema: TreeNodeSchema,\n\tstoredKey: string | number,\n): string | number {\n\t// Only object nodes have the concept of a \"stored key\", differentiated from the developer-facing \"view key\".\n\t// For any other kind of node, the stored key and the view key are the same.\n\tif (schema.kind !== NodeKind.Object) {\n\t\treturn storedKey;\n\t}\n\n\tconst fields = schema.info as Record<string, ImplicitFieldSchema>;\n\n\t// Invariants:\n\t// - The set of all view keys under an object must be unique.\n\t// - The set of all stored keys (including those implicitly created from view keys) must be unique.\n\t// To find the view key associated with the provided stored key, first check for any stored key matches (which are optionally populated).\n\t// If we don't find any, then search for a matching view key.\n\tfor (const [viewKey, fieldSchema] of Object.entries(fields)) {\n\t\tif (fieldSchema instanceof FieldSchema && fieldSchema.props?.key === storedKey) {\n\t\t\treturn viewKey;\n\t\t}\n\t}\n\n\tif (fields[storedKey] === undefined) {\n\t\tfail(\"Existing stored key should always map to a view key\");\n\t}\n\n\treturn storedKey;\n}\n\n/**\n * A collection of events that can be raised by a {@link TreeNode}.\n *\n * @privateRemarks\n * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).\n * Probably have object node and map node specific APIs for this.\n *\n * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.\n *\n * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.\n * Some ideas:\n *\n * - treeChanged, but with some subtrees/fields/paths excluded\n * - helper to batch several nodeChanged calls to a treeChanged scope\n * - parent change (ex: registration on the parent field for a specific index: maybe allow it for a range. Ex: node event takes optional field and optional index range?)\n * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.\n * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)\n * to allow efficiently searching for new content (and initial content) of a given type.\n *\n * @public\n */\nexport interface TreeChangeEvents {\n\t/**\n\t * Emitted by a node when a batch of changes is applied to it, where a change is:\n\t *\n\t * - For an object node, when the value of one of its properties changes (i.e., the property's value is set\n\t * to something else, including `undefined`).\n\t *\n\t * - For an array node, when an element is added, removed, or moved.\n\t *\n\t * - For a map node, when an entry is added, updated, or removed.\n\t *\n\t * @remarks\n\t * This event is not raised 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 raise 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 raised 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 * While a batch of edits will as a whole update the tree to the appropriate end state, no guarantees are made about\n\t * how many times this event will be raised during any intermediate states.\n\t * When it is raised, the tree is guaranteed to be in-schema.\n\t *\n\t * @privateRemarks\n\t * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.\n\t * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the\n\t * node, or when the node has to be updated due to resolution of a merge conflict\n\t * (for example a previously applied local change might be undone, then reapplied differently or not at all).\n\t */\n\tnodeChanged(): void;\n\n\t/**\n\t * Emitted by a node when something _may_ have changed anywhere in the subtree rooted at it.\n\t *\n\t * @remarks\n\t * This event is guaranteed to be emitted whenever the subtree _has_ changed.\n\t * However, it might also be emitted when the subtree has no visible changes compared to before the event firing.\n\t *\n\t * Consumers of this event have the guarantee that they won't miss any changes, but should also handle the scenario\n\t * where the event fires with no visible changes as well.\n\t *\n\t * This event is not raised 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 raised 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 * While a batch of edits will as a whole update the tree to the appropriate end state, no guarantees are made about\n\t * how many times this event will be raised during any intermediate states.\n\t * When it is raised, the tree is guaranteed to be in-schema.\n\t */\n\ttreeChanged(): void;\n}\n"]}
+{"version":3,"file":"treeNodeApi.js","sourceRoot":"","sources":["../../src/simple-tree/treeNodeApi.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,kEAA8E;AAE9E,+CAA8D;AAC9D,4DAMuC;AACvC,+CAA4E;AAE5E,6CAAgE;AAChE,uDAAgD;AAChD,yDAA4D;AAC5D,qDAQ0B;AAE1B,2DAM6B;AAC7B,qEAAuE;AACvE,uEAAsE;AAoFtE;;GAEG;AACU,QAAA,WAAW,GAAgB;IACvC,MAAM,EAAE,CAAC,IAAc,EAAwB,EAAE;QAChD,MAAM,QAAQ,GAAG,IAAA,6BAAW,EAAC,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC;QAC7D,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,SAAS,CAAC;QAClB,CAAC;QAED,MAAM,MAAM,GAAG,IAAA,iCAAoB,EAAC,QAAQ,CAAC,CAAC;QAC9C,IAAA,iBAAM,EACL,CAAC,IAAA,sBAAW,EAAC,MAAM,CAAC,EACpB,KAAK,CAAC,gEAAgE,CACtE,CAAC;QACF,OAAO,MAAM,CAAC;IACf,CAAC;IACD,GAAG,EAAE,CAAC,IAAc,EAAE,EAAE;QACvB,sEAAsE;QACtE,8CAA8C;QAC9C,MAAM,MAAM,GAAG,mBAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,uBAAY,CAAC;QACrB,CAAC;QAED,+DAA+D;QAC/D,mGAAmG;QACnG,wGAAwG;QACxG,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,YAAY,GAAG,mBAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAChD,MAAM,OAAO,GAAG,uBAAuB,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QACjE,OAAO,OAAO,CAAC;IAChB,CAAC;IACD,EAAE,EAAE,CACH,IAAc,EACd,SAAY,EACZ,QAA6B,EAC5B,EAAE;QACH,MAAM,IAAI,GAAG,IAAA,6BAAW,EAAC,IAAI,CAAC,CAAC;QAC/B,QAAQ,SAAS,EAAE,CAAC;YACnB,KAAK,aAAa;gBACjB,OAAO,IAAI,CAAC,EAAE,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;YACzC,KAAK,aAAa;gBACjB,OAAO,IAAI,CAAC,EAAE,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;YACzC;gBACC,OAAO,IAAA,0BAAe,EAAC,SAAS,CAAC,CAAC;QACpC,CAAC;IACF,CAAC;IACD,MAAM,EAAE,CAAC,IAAc,EAAE,EAAE;QAC1B,OAAO,IAAA,6BAAW,EAAC,IAAI,EAAE,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;IAC7C,CAAC;IACD,EAAE,EAAE,CACH,KAAc,EACd,MAAe,EACsC,EAAE;QACvD,MAAM,YAAY,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAChC,OAAO,KAAK,CAAC;QACd,CAAC;QACD,IAAI,IAAA,0BAAe,EAA2B,MAAM,CAAC,EAAE,CAAC;YACvD,KAAK,MAAM,YAAY,IAAI,MAAM,EAAE,CAAC;gBACnC,MAAM,UAAU,GAAG,IAAA,iBAAM,EAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC;gBACxE,IAAI,UAAU,KAAK,YAAY,EAAE,CAAC;oBACjC,OAAO,IAAI,CAAC;gBACb,CAAC;YACF,CAAC;YACD,OAAO,KAAK,CAAC;QACd,CAAC;aAAM,CAAC;YACP,OAAQ,MAAyB,KAAK,YAAY,CAAC;QACpD,CAAC;IACF,CAAC;IACD,MAAM,CACL,IAAO;QAEP,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,IAAA,eAAI,EAAC,iBAAiB,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,CAAC,IAAc;QACrB,MAAM,QAAQ,GAAG,IAAA,6BAAW,EAAC,IAAI,CAAC,CAAC;QACnC,IAAI,OAAoC,CAAC;QACzC,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,aAAa,EAAE,EAAE,CAAC;YAC9C,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,qBAAU,CAAC,UAAU,EAAE,CAAC;gBACjD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;oBAC3B,MAAM,IAAI,qBAAU,CACnB,yIAAyI,CACzI,CAAC;gBACH,CAAC;gBACD,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBACpC,IAAA,iBAAM,EAAC,UAAU,KAAK,SAAS,EAAE,KAAK,CAAC,+BAA+B,CAAC,CAAC;gBACxE,MAAM,eAAe,GAAG,UAAU,CAAC,KAAe,CAAC;gBACnD,MAAM,YAAY,GACjB,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAC;gBAEvE,OAAO;oBACN,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,IAAA,4BAAiB,EAAC,YAAY,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC;YACjF,CAAC;QACF,CAAC;QAED,OAAO,OAAO,CAAC;IAChB,CAAC;CACD,CAAC;AAEF;;;GAGG;AACH,SAAgB,YAAY,CAC3B,KAAQ;IAGR,QAAQ,OAAO,KAAK,EAAE,CAAC;QACtB,KAAK,QAAQ;YACZ,OAAO,gCAAoB,CAAC;QAC7B,KAAK,QAAQ;YACZ,OAAO,gCAAoB,CAAC;QAC7B,KAAK,SAAS;YACb,OAAO,iCAAqB,CAAC;QAC9B,KAAK,QAAQ,CAAC,CAAC,CAAC;YACf,IAAI,IAAA,uBAAU,EAAC,KAAK,CAAC,EAAE,CAAC;gBACvB,oGAAoG;gBACpG,OAAO,IAAA,yCAAsB,EAAC,IAAA,6BAAW,EAAC,KAAK,CAAC,CAAC,MAAM,CAAS,CAAC;YAClE,CAAC;YACD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACpB,OAAO,8BAAkB,CAAC;YAC3B,CAAC;YACD,IAAI,IAAA,wBAAa,EAAC,KAAK,CAAC,EAAE,CAAC;gBAC1B,OAAO,gCAAoB,CAAC;YAC7B,CAAC;QACF,CAAC;QACD;YACC,OAAO,SAAS,CAAC;IACnB,CAAC;AACF,CAAC;AA1BD,oCA0BC;AAED;;GAEG;AACH,SAAS,YAAY,CAAC,IAAc;IACnC,wGAAwG;IACxG,eAAe;IACf,MAAM,WAAW,GAAG,IAAA,6BAAW,EAAC,IAAI,CAAC,CAAC,WAAW,CAAC;IAClD,IAAI,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,KAAK,uBAAY,CAAC,QAAQ,EAAE,CAAC;QAC3E,wCAAwC;QACxC,OAAO,WAAW,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED,yGAAyG;IACzG,OAAO,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,SAAS,uBAAuB,CAC/B,MAAsB,EACtB,SAA0B;IAE1B,6GAA6G;IAC7G,4EAA4E;IAC5E,IAAI,MAAM,CAAC,IAAI,KAAK,yBAAQ,CAAC,MAAM,EAAE,CAAC;QACrC,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,IAA2C,CAAC;IAElE,cAAc;IACd,6DAA6D;IAC7D,mGAAmG;IACnG,yIAAyI;IACzI,6DAA6D;IAC7D,KAAK,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7D,IAAI,WAAW,YAAY,4BAAW,IAAI,WAAW,CAAC,KAAK,EAAE,GAAG,KAAK,SAAS,EAAE,CAAC;YAChF,OAAO,OAAO,CAAC;QAChB,CAAC;IACF,CAAC;IAED,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;QACrC,IAAA,eAAI,EAAC,qDAAqD,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,SAAS,CAAC;AAClB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert, unreachableCase } from \"@fluidframework/core-utils/internal\";\n\nimport { Multiplicity, rootFieldKey } from \"../core/index.js\";\nimport {\n\tFieldKinds,\n\ttype LazyItem,\n\ttype TreeStatus,\n\tisLazy,\n\tisTreeValue,\n} from \"../feature-libraries/index.js\";\nimport { fail, extractFromOpaque, isReadonlyArray } from \"../util/index.js\";\n\nimport { getOrCreateNodeProxy, isTreeNode } from \"./proxies.js\";\nimport { getFlexNode } from \"./proxyBinding.js\";\nimport { tryGetSimpleNodeSchema } from \"./schemaCaching.js\";\nimport {\n\tNodeKind,\n\ttype TreeLeafValue,\n\ttype TreeNodeSchema,\n\ttype ImplicitFieldSchema,\n\tFieldSchema,\n\ttype ImplicitAllowedTypes,\n\ttype TreeNodeFromImplicitAllowedTypes,\n} from \"./schemaTypes.js\";\nimport type { TreeNode } from \"./types.js\";\nimport {\n\tbooleanSchema,\n\thandleSchema,\n\tnullSchema,\n\tnumberSchema,\n\tstringSchema,\n} from \"./leafNodeSchema.js\";\nimport { isFluidHandle } from \"@fluidframework/runtime-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\n/**\n * Provides various functions for analyzing {@link TreeNode}s.\n *\n * @privateRemarks\n * Inlining the typing of this interface onto the `Tree` object provides slightly different .d.ts generation,\n * which avoids typescript expanding the type of TreeNodeSchema and thus encountering\n * https://github.com/microsoft/rushstack/issues/1958.\n * @public\n */\nexport interface TreeNodeApi {\n\t/**\n\t * The schema information for this node.\n\t */\n\tschema<T extends TreeNode | TreeLeafValue>(\n\t\tnode: T,\n\t): TreeNodeSchema<string, NodeKind, unknown, T>;\n\n\t/**\n\t * Narrow the type of the given value if it satisfies the given schema.\n\t * @example\n\t * ```ts\n\t * if (node.is(myNode, Point)) {\n\t *     const y = myNode.y; // `myNode` is now known to satisfy the `Point` schema and therefore has a `y` coordinate.\n\t * }\n\t * ```\n\t */\n\tis<TSchema extends ImplicitAllowedTypes>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is TreeNodeFromImplicitAllowedTypes<TSchema>;\n\n\t/**\n\t * Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).\n\t */\n\tparent(node: TreeNode): TreeNode | undefined;\n\n\t/**\n\t * The key of the given node under its parent.\n\t * @remarks\n\t * If `node` is an element in a {@link (TreeArrayNode:interface)}, this returns the index of `node` in the array node (a `number`).\n\t * Otherwise, this returns the key of the field that it is under (a `string`).\n\t */\n\tkey(node: TreeNode): string | number;\n\n\t/**\n\t * Register an event listener on the given node.\n\t * @param node - The node whose events should be subscribed to.\n\t * @param eventName - Which event to subscribe to.\n\t * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.\n\t * @returns A callback function which will deregister the event.\n\t * This callback should be called only once.\n\t */\n\ton<K extends keyof TreeChangeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeChangeEvents[K],\n\t): () => void;\n\n\t/**\n\t * Returns the {@link TreeStatus} of the given node.\n\t */\n\treadonly status: (node: TreeNode) => TreeStatus;\n\n\t/**\n\t * Returns the {@link SchemaFactory.identifier | identifier} of the given node in the most compressed form possible.\n\t * @remarks\n\t * If the node's identifier is a valid UUID that was automatically generated by the SharedTree, then this will return a process-unique integer corresponding to that identifier.\n\t * This is useful for performance-sensitive scenarios involving many nodes with identifiers that need to be compactly retained in memory or used for efficient lookup.\n\t *\n\t * If the node's identifier is any other user-provided string, then this will return that string.\n\t *\n\t * If the node has no identifier (that is, it has no {@link SchemaFactory.identifier | identifier} field), then this returns `undefined`.\n\t *\n\t * If the node has more than one identifier, then this will throw an error.\n\t *\n\t * The returned integer must not be serialized or preserved outside of the current process.\n\t * Its lifetime is that of the current in-memory instance of the FF container for this client, and it is not guaranteed to be unique or stable outside of that context.\n\t * The same node's identifier may, for example, be different across multiple sessions for the same client and document, or different across two clients in the same session.\n\t */\n\tshortId(node: TreeNode): number | string | undefined;\n}\n\n/**\n * The `Tree` object holds various functions for analyzing {@link TreeNode}s.\n */\nexport const treeNodeApi: TreeNodeApi = {\n\tparent: (node: TreeNode): TreeNode | undefined => {\n\t\tconst editNode = getFlexNode(node).parentField.parent.parent;\n\t\tif (editNode === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst output = getOrCreateNodeProxy(editNode);\n\t\tassert(\n\t\t\t!isTreeValue(output),\n\t\t\t0x87f /* Parent can't be a leaf, so it should be a node not a value */,\n\t\t);\n\t\treturn output;\n\t},\n\tkey: (node: TreeNode) => {\n\t\t// If the parent is undefined, then this node is under the root field,\n\t\t// so we know its key is the special root one.\n\t\tconst parent = treeNodeApi.parent(node);\n\t\tif (parent === undefined) {\n\t\t\treturn rootFieldKey;\n\t\t}\n\n\t\t// The flex-domain strictly operates in terms of \"stored keys\".\n\t\t// To find the associated developer-facing \"view key\", we need to look up the field associated with\n\t\t// the stored key from the flex-domain, and get view key its simple-domain counterpart was created with.\n\t\tconst storedKey = getStoredKey(node);\n\t\tconst parentSchema = treeNodeApi.schema(parent);\n\t\tconst viewKey = getViewKeyFromStoredKey(parentSchema, storedKey);\n\t\treturn viewKey;\n\t},\n\ton: <K extends keyof TreeChangeEvents>(\n\t\tnode: TreeNode,\n\t\teventName: K,\n\t\tlistener: TreeChangeEvents[K],\n\t) => {\n\t\tconst flex = getFlexNode(node);\n\t\tswitch (eventName) {\n\t\t\tcase \"nodeChanged\":\n\t\t\t\treturn flex.on(\"nodeChanged\", listener);\n\t\t\tcase \"treeChanged\":\n\t\t\t\treturn flex.on(\"treeChanged\", listener);\n\t\t\tdefault:\n\t\t\t\treturn unreachableCase(eventName);\n\t\t}\n\t},\n\tstatus: (node: TreeNode) => {\n\t\treturn getFlexNode(node, true).treeStatus();\n\t},\n\tis: <TSchema extends ImplicitAllowedTypes>(\n\t\tvalue: unknown,\n\t\tschema: TSchema,\n\t): value is TreeNodeFromImplicitAllowedTypes<TSchema> => {\n\t\tconst actualSchema = tryGetSchema(value);\n\t\tif (actualSchema === undefined) {\n\t\t\treturn false;\n\t\t}\n\t\tif (isReadonlyArray<LazyItem<TreeNodeSchema>>(schema)) {\n\t\t\tfor (const singleSchema of schema) {\n\t\t\t\tconst testSchema = isLazy(singleSchema) ? singleSchema() : singleSchema;\n\t\t\t\tif (testSchema === actualSchema) {\n\t\t\t\t\treturn true;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn false;\n\t\t} else {\n\t\t\treturn (schema as TreeNodeSchema) === actualSchema;\n\t\t}\n\t},\n\tschema<T extends TreeNode | TreeLeafValue>(\n\t\tnode: T,\n\t): TreeNodeSchema<string, NodeKind, unknown, T> {\n\t\treturn tryGetSchema(node) ?? fail(\"Not a tree node\");\n\t},\n\tshortId(node: TreeNode): number | string | undefined {\n\t\tconst flexNode = getFlexNode(node);\n\t\tlet shortId: number | string | undefined;\n\t\tfor (const field of flexNode.boxedIterator()) {\n\t\t\tif (field.schema.kind === FieldKinds.identifier) {\n\t\t\t\tif (shortId !== undefined) {\n\t\t\t\t\tthrow new UsageError(\n\t\t\t\t\t\t\"shortId() may not be called on a node with more than one identifier. Consider converting extraneous identifier fields to string fields.\",\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tconst identifier = field.boxedAt(0);\n\t\t\t\tassert(identifier !== undefined, 0x927 /* The identifier must exist */);\n\t\t\t\tconst identifierValue = identifier.value as string;\n\t\t\t\tconst localNodeKey =\n\t\t\t\t\tidentifier.context.nodeKeyManager.tryLocalizeNodeKey(identifierValue);\n\n\t\t\t\tshortId =\n\t\t\t\t\tlocalNodeKey !== undefined ? extractFromOpaque(localNodeKey) : identifierValue;\n\t\t\t}\n\t\t}\n\n\t\treturn shortId;\n\t},\n};\n\n/**\n * Returns a schema for a value if the value is a {@link TreeNode} or a {@link TreeLeafValue}.\n * Returns undefined for other values.\n */\nexport function tryGetSchema<T>(\n\tvalue: T,\n): undefined | TreeNodeSchema<string, NodeKind, unknown, T> {\n\ttype TOut = TreeNodeSchema<string, NodeKind, unknown, T>;\n\tswitch (typeof value) {\n\t\tcase \"string\":\n\t\t\treturn stringSchema as TOut;\n\t\tcase \"number\":\n\t\t\treturn numberSchema as TOut;\n\t\tcase \"boolean\":\n\t\t\treturn booleanSchema as TOut;\n\t\tcase \"object\": {\n\t\t\tif (isTreeNode(value)) {\n\t\t\t\t// This case could be optimized, for example by placing the simple schema in a symbol on tree nodes.\n\t\t\t\treturn tryGetSimpleNodeSchema(getFlexNode(value).schema) as TOut;\n\t\t\t}\n\t\t\tif (value === null) {\n\t\t\t\treturn nullSchema as TOut;\n\t\t\t}\n\t\t\tif (isFluidHandle(value)) {\n\t\t\t\treturn handleSchema as TOut;\n\t\t\t}\n\t\t}\n\t\tdefault:\n\t\t\treturn undefined;\n\t}\n}\n\n/**\n * Gets the stored key with which the provided node is associated in the parent.\n */\nfunction getStoredKey(node: TreeNode): string | number {\n\t// Note: the flex domain strictly works with \"stored keys\", and knows nothing about the developer-facing\n\t// \"view keys\".\n\tconst parentField = getFlexNode(node).parentField;\n\tif (parentField.parent.schema.kind.multiplicity === Multiplicity.Sequence) {\n\t\t// The parent of `node` is an array node\n\t\treturn parentField.index;\n\t}\n\n\t// The parent of `node` is an object, a map, or undefined (and therefore `node` is a root/detached node).\n\treturn parentField.parent.key;\n}\n\n/**\n * Given a node schema, gets the view key corresponding with the provided {@link FieldProps.key | stored key}.\n */\nfunction getViewKeyFromStoredKey(\n\tschema: TreeNodeSchema,\n\tstoredKey: string | number,\n): string | number {\n\t// Only object nodes have the concept of a \"stored key\", differentiated from the developer-facing \"view key\".\n\t// For any other kind of node, the stored key and the view key are the same.\n\tif (schema.kind !== NodeKind.Object) {\n\t\treturn storedKey;\n\t}\n\n\tconst fields = schema.info as Record<string, ImplicitFieldSchema>;\n\n\t// Invariants:\n\t// - The set of all view keys under an object must be unique.\n\t// - The set of all stored keys (including those implicitly created from view keys) must be unique.\n\t// To find the view key associated with the provided stored key, first check for any stored key matches (which are optionally populated).\n\t// If we don't find any, then search for a matching view key.\n\tfor (const [viewKey, fieldSchema] of Object.entries(fields)) {\n\t\tif (fieldSchema instanceof FieldSchema && fieldSchema.props?.key === storedKey) {\n\t\t\treturn viewKey;\n\t\t}\n\t}\n\n\tif (fields[storedKey] === undefined) {\n\t\tfail(\"Existing stored key should always map to a view key\");\n\t}\n\n\treturn storedKey;\n}\n\n/**\n * A collection of events that can be emitted by a {@link TreeNode}.\n *\n * @privateRemarks\n * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).\n * Probably have object node and map node specific APIs for this.\n *\n * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.\n *\n * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.\n * Some ideas:\n *\n * - treeChanged, but with some subtrees/fields/paths excluded\n * - helper to batch several nodeChanged calls to a treeChanged scope\n * - parent change (ex: registration on the parent field for a specific index: maybe allow it for a range. Ex: node event takes optional field and optional index range?)\n * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.\n * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)\n * to allow efficiently searching for new content (and initial content) of a given type.\n *\n * @public\n */\nexport interface TreeChangeEvents {\n\t/**\n\t * Emitted by a node after a batch of changes has been applied to the tree, if a change affected the node, where a\n\t * change is:\n\t *\n\t * - For an object node, when the value of one of its properties changes (i.e., the property's value is set\n\t * to something else, including `undefined`).\n\t *\n\t * - For an array node, when an element is added, removed, or moved.\n\t *\n\t * - For a map node, when an entry is added, updated, or removed.\n\t *\n\t * @remarks\n\t * This event is not emitted when:\n\t *\n\t * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing\n\t * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the\n\t * array/map node as one of its properties.\n\t *\n\t * - The node is moved to a different location in the tree or removed from the tree.\n\t * In this case the event is emitted on the _parent_ node, not the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When it is emitted, the tree is guaranteed to be in-schema.\n\t *\n\t * @privateRemarks\n\t * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.\n\t * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the\n\t * node, or when the node has to be updated due to resolution of a merge conflict\n\t * (for example a previously applied local change might be undone, then reapplied differently or not at all).\n\t */\n\tnodeChanged(): void;\n\n\t/**\n\t * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the\n\t * subtree rooted at it.\n\t *\n\t * @remarks\n\t * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.\n\t * In that case it is emitted on the _parent_ node, not the node itself.\n\t *\n\t * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties\n\t * of the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When it is emitted, the tree is guaranteed to be in-schema.\n\t */\n\ttreeChanged(): void;\n}\n"]}

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

@@ -2,9 +2,9 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { ErasedType } from "@fluidframework/core-interfaces";
-import { WithType, type } from "./schemaTypes.js";
-import { FlexTreeNode, MapTreeNode } from "../feature-libraries/index.js";
+import type { ErasedType } from "@fluidframework/core-interfaces";
+import { type WithType, type } from "./schemaTypes.js";
+import { type FlexTreeNode, type MapTreeNode } from "../feature-libraries/index.js";
 /**
  * Type alias to document which values are un-hydrated.
  *
@@ -16,7 +16,7 @@ import { FlexTreeNode, MapTreeNode } from "../feature-libraries/index.js";
  */
 export type Unhydrated<T> = T;
 /**
- * A non-leaf SharedTree node. Includes objects, arrays, and maps.
+ * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
  *
  * @remarks
  * Base type which all nodes implement.
@@ -34,11 +34,8 @@ export type Unhydrated<T> = T;
  *
  * Not all node implementations include this in their prototype chain (some hide it with a proxy),
  * and thus cause the default/built in `instanceof` to return false despite our type checking and all other APIs treating them as TreeNodes.
- * This results in the runtime and compile time behavior of `instanceof` differing.
- * TypeScript 5.3 allows altering the compile time behavior of `instanceof`.
- * The runtime behavior can be changed by implementing `Symbol.hasInstance`.
- * One of those approaches could be used to resolve this inconsistency,
- * but for now the type-only export prevents use of `instanceof` avoiding this problem in the public API.
+ * This class provides a custom `Symbol.hasInstance` to fix `instanceof` for this class and all classes extending it.
+ * For now the type-only export prevents use of `instanceof` on this class (but allows it in subclasses like schema classes).
  * @public
  */
 export declare abstract class TreeNode implements WithType {
@@ -49,8 +46,31 @@ export declare abstract class TreeNode implements WithType {
      * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.
      */
     abstract get [type](): string;
+    /**
+     * Provides `instanceof` support for testing if a value is a `TreeNode`.
+     * @remarks
+     * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.
+     * @privateRemarks
+     * Due to type-only export, this functionality is not available outside the package.
+     */
+    static [Symbol.hasInstance](value: unknown): value is TreeNode;
+    /**
+     * Provides `instanceof` support for all schema classes with public constructors.
+     * @remarks
+     * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.
+     * @privateRemarks
+     * Despite type-only export, this functionality is available outside the package since it is inherited by subclasses.
+     */
+    static [Symbol.hasInstance]<TSchema extends abstract new (...args: any[]) => TreeNode>(this: TSchema, value: unknown): value is InstanceType<TSchema>;
     protected constructor();
 }
+/**
+ * Check if the prototype derived's prototype chain contains `base`.
+ * @param derived - prototype to check
+ * @param base - prototype to search for
+ * @returns true iff `base` is in the prototype chain starting at `derived`.
+ */
+export declare function inPrototypeChain(derived: object | null, base: object): boolean;
 /**
  * Class which all {@link TreeNode}s must extend.
  * Since this is not exported, it allows robust detection of attempts to create TreeNodes which do not go through SchemaFactory which is the only place which exposes classes that extend this.

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/simple-tree/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAG7D,OAAO,EAAkB,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EACN,YAAY,EACZ,WAAW,EAGX,MAAM,+BAA+B,CAAC;AAQvC;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,8BAAsB,QAAS,YAAW,QAAQ;;IA6BjD;;;;OAIG;IACH,aAAoB,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC;IAErC,SAAS;CAKT;AAED;;;;;;;GAOG;AACH,8BAAsB,aAAa,CAAC,MAAM,CAAE,SAAQ,QAAQ;IAC3D;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,EACjC,IAAI,EAAE,OAAO,aAAa,CAAC,CAAC,CAAC,EAC7B,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,YAAY,GACjB,aAAa,CAAC,CAAC,CAAC;IAInB;;OAEG;IACH,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,EAC9B,IAAI,EAAE,OAAO,aAAa,CAAC,CAAC,CAAC,EAC7B,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,CAAC,GACN,WAAW;IAId;;;OAGG;IACH,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI;IAErE;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,MAAM,CAAC,iBAAiB,EAAE,OAAO,aAAa,GAAG,SAAS,CAAiB;gBAElE,KAAK,EAAE,MAAM,GAAG,gBAAgB;CAwDnD;AAID;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAiB,SAAQ,UAAU,CAAC,uCAAuC,CAAC;CAAG;AAEhG,wBAAgB,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAGnE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/simple-tree/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAGlE,OAAO,EAAiC,KAAK,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACtF,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,WAAW,EAGhB,MAAM,+BAA+B,CAAC;AASvC;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,QAAS,YAAW,QAAQ;;IA6BjD;;;;OAIG;IACH,aAAoB,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC;IAErC;;;;;;OAMG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ;IAErE;;;;;;OAMG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,OAAO,SAAS,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,QAAQ,EAC3F,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,GACZ,KAAK,IAAI,YAAY,CAAC,OAAO,CAAC;IAajC,SAAS;CAKT;AAED;;;;;GAKG;AAEH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAS9E;AAED;;;;;;;GAOG;AACH,8BAAsB,aAAa,CAAC,MAAM,CAAE,SAAQ,QAAQ;IAC3D;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,EACjC,IAAI,EAAE,OAAO,aAAa,CAAC,CAAC,CAAC,EAC7B,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,YAAY,GACjB,aAAa,CAAC,CAAC,CAAC;IAInB;;OAEG;IACH,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,EAC9B,IAAI,EAAE,OAAO,aAAa,CAAC,CAAC,CAAC,EAC7B,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,CAAC,GACN,WAAW;IAId;;;OAGG;IACH,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI;IAErE;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,MAAM,CAAC,iBAAiB,EAAE,OAAO,aAAa,GAAG,SAAS,CAAiB;gBAElE,KAAK,EAAE,MAAM,GAAG,gBAAgB;CAwDnD;AAID;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAiB,SAAQ,UAAU,CAAC,uCAAuC,CAAC;CAAG;AAEhG,wBAAgB,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAGnE"}

package/dist/simple-tree/types.js

@@ -3,8 +3,9 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
+var _TreeNode_brand;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toFlexTreeNode = exports.TreeNodeValid = exports.TreeNode = void 0;
+exports.toFlexTreeNode = exports.TreeNodeValid = exports.inPrototypeChain = exports.TreeNode = void 0;
 const internal_1 = require("@fluidframework/core-utils/internal");
 const schemaTypes_js_1 = require("./schemaTypes.js");
 const index_js_1 = require("../feature-libraries/index.js");
@@ -14,8 +15,9 @@ const internal_2 = require("@fluidframework/telemetry-utils/internal");
 const toFlexSchema_js_1 = require("./toFlexSchema.js");
 const index_js_2 = require("../util/index.js");
 const proxyBinding_js_1 = require("./proxyBinding.js");
+const treeNodeApi_js_1 = require("./treeNodeApi.js");
 /**
- * A non-leaf SharedTree node. Includes objects, arrays, and maps.
+ * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
  *
  * @remarks
  * Base type which all nodes implement.
@@ -33,48 +35,71 @@ const proxyBinding_js_1 = require("./proxyBinding.js");
  *
  * Not all node implementations include this in their prototype chain (some hide it with a proxy),
  * and thus cause the default/built in `instanceof` to return false despite our type checking and all other APIs treating them as TreeNodes.
- * This results in the runtime and compile time behavior of `instanceof` differing.
- * TypeScript 5.3 allows altering the compile time behavior of `instanceof`.
- * The runtime behavior can be changed by implementing `Symbol.hasInstance`.
- * One of those approaches could be used to resolve this inconsistency,
- * but for now the type-only export prevents use of `instanceof` avoiding this problem in the public API.
+ * This class provides a custom `Symbol.hasInstance` to fix `instanceof` for this class and all classes extending it.
+ * For now the type-only export prevents use of `instanceof` on this class (but allows it in subclasses like schema classes).
  * @public
  */
 class TreeNode {
-    /**
-     * This is added to prevent TypeScript from implicitly allowing non-TreeNode types to be used as TreeNodes.
-     * @remarks
-     * This field forces TypeScript to use nominal instead of structural typing,
-     * preventing compiler error messages and tools like "add missing properties"
-     * from adding the [type] field as a solution when using a non-TreeNode object where a TreeNode is required.
-     * Instead TreeNodes must be created through the appropriate APIs, see the documentation on {@link TreeNode} for details.
-     *
-     * @privateRemarks
-     * This is a JavaScript private field, so is not accessible from outside this class.
-     * This prevents it from having name collisions with object fields.
-     * Since this is private, the type of this field is stripped in the d.ts file.
-     * To get matching type checking within and from outside the package, the least informative type (`unknown`) is used.
-     * To avoid this having any runtime impact, the field is uninitialized.
-     *
-     * 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.
-     * This is extra confusing since since the tests get in-project typing for intellisense and separate project checking at build time.
-     * To avoid all this mess, this field is required, not optional.
-     *
-     * Another option would be to use a symbol (possibly as a private field).
-     * That approach ran into some strange difficulties causing SchemaFactory to fail to compile, and was not investigated further.
-     *
-     * The [type] symbol here provides a lot of the value this private brand does, but is not all of it:
-     * someone could manually (or via Intellisense auto-implement completion, or in response to a type error)
-     * make an object literal with the [type] field and pass it off as a node: this private brand prevents that.
-     */
-    #brand;
+    static [(_TreeNode_brand = new WeakMap(), Symbol.hasInstance)](value) {
+        const schema = (0, treeNodeApi_js_1.tryGetSchema)(value);
+        if (schema === undefined || schema.kind === schemaTypes_js_1.NodeKind.Leaf) {
+            return false;
+        }
+        (0, internal_1.assert)("prototype" in schema, "expected class based schema");
+        return inPrototypeChain(schema.prototype, this.prototype);
+    }
     constructor() {
-        if (!(this instanceof TreeNodeValid)) {
+        /**
+         * This is added to prevent TypeScript from implicitly allowing non-TreeNode types to be used as TreeNodes.
+         * @remarks
+         * This field forces TypeScript to use nominal instead of structural typing,
+         * preventing compiler error messages and tools like "add missing properties"
+         * from adding the [type] field as a solution when using a non-TreeNode object where a TreeNode is required.
+         * Instead TreeNodes must be created through the appropriate APIs, see the documentation on {@link TreeNode} for details.
+         *
+         * @privateRemarks
+         * This is a JavaScript private field, so is not accessible from outside this class.
+         * This prevents it from having name collisions with object fields.
+         * Since this is private, the type of this field is stripped in the d.ts file.
+         * To get matching type checking within and from outside the package, the least informative type (`unknown`) is used.
+         * To avoid this having any runtime impact, the field is uninitialized.
+         *
+         * 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.
+         * This is extra confusing since since the tests get in-project typing for intellisense and separate project checking at build time.
+         * To avoid all this mess, this field is required, not optional.
+         *
+         * Another option would be to use a symbol (possibly as a private field).
+         * That approach ran into some strange difficulties causing SchemaFactory to fail to compile, and was not investigated further.
+         *
+         * The [type] symbol provides a lot of the value this private brand does, but is not all of it:
+         * someone could manually (or via Intellisense auto-implement completion, or in response to a type error)
+         * make an object literal with the [type] field and pass it off as a node: this private brand prevents that.
+         */
+        _TreeNode_brand.set(this, void 0);
+        if (!inPrototypeChain(Reflect.getPrototypeOf(this), TreeNodeValid.prototype)) {
             throw new internal_2.UsageError("TreeNodes must extend schema classes created by SchemaFactory");
         }
     }
 }
 exports.TreeNode = TreeNode;
+/**
+ * Check if the prototype derived's prototype chain contains `base`.
+ * @param derived - prototype to check
+ * @param base - prototype to search for
+ * @returns true iff `base` is in the prototype chain starting at `derived`.
+ */
+// eslint-disable-next-line @rushstack/no-new-null
+function inPrototypeChain(derived, base) {
+    let checking = derived;
+    while (checking !== null) {
+        if (base === checking) {
+            return true;
+        }
+        checking = Reflect.getPrototypeOf(checking);
+    }
+    return false;
+}
+exports.inPrototypeChain = inPrototypeChain;
 /**
  * Class which all {@link TreeNode}s must extend.
  * Since this is not exported, it allows robust detection of attempts to create TreeNodes which do not go through SchemaFactory which is the only place which exposes classes that extend this.
@@ -106,25 +131,6 @@ class TreeNodeValid extends TreeNode {
      * This is a good place to perform extra validation and cache schema derived data needed for the implementation of the node.
      */
     static oneTimeSetup() { }
-    /**
-     * The most derived constructor (the one invoked with the `new` operator, not a parent class constructor invoked with as `super`) used to construct an instance of this type.
-     * @remarks
-     * Captured when an instance is constructed.
-     *
-     * Used to ensure that some derived class (which must override this member, defaulting it to `undefined`) is only instantiated with a single "most derived" class (the constructor actually invoked the the user with `new`).
-     *
-     * Typically this is override in the class that statically implements {@link TreeNodeSchema} to enforce that all nodes using that schema use the same class and not different subclasses of it.
-     *
-     * Also used to detect if oneTimeSetup has run.
-     *
-     * @privateRemarks
-     * This defaults to TreeNodeValid, which is used to trigger an error if not overridden in the derived class.
-     *
-     * The value of this on TreeNodeValid must only be overridden by base classes and never modified.
-     * Ways to enforce this immutability prevent it from being overridden,
-     * so code modifying constructorCached should be extra careful to avoid accidentally modifying the base/inherited value.
-     */
-    static constructorCached = TreeNodeValid;
     constructor(input) {
         super();
         const schema = this.constructor;
@@ -163,6 +169,25 @@ class TreeNodeValid extends TreeNode {
     }
 }
 exports.TreeNodeValid = TreeNodeValid;
+/**
+ * The most derived constructor (the one invoked with the `new` operator, not a parent class constructor invoked with as `super`) used to construct an instance of this type.
+ * @remarks
+ * Captured when an instance is constructed.
+ *
+ * Used to ensure that some derived class (which must override this member, defaulting it to `undefined`) is only instantiated with a single "most derived" class (the constructor actually invoked the the user with `new`).
+ *
+ * Typically this is override in the class that statically implements {@link TreeNodeSchema} to enforce that all nodes using that schema use the same class and not different subclasses of it.
+ *
+ * Also used to detect if oneTimeSetup has run.
+ *
+ * @privateRemarks
+ * This defaults to TreeNodeValid, which is used to trigger an error if not overridden in the derived class.
+ *
+ * The value of this on TreeNodeValid must only be overridden by base classes and never modified.
+ * Ways to enforce this immutability prevent it from being overridden,
+ * so code modifying constructorCached should be extra careful to avoid accidentally modifying the base/inherited value.
+ */
+TreeNodeValid.constructorCached = TreeNodeValid;
 // Class objects are functions (callable), so we need a strong way to distinguish between `schema` and `() => schema` when used as a `LazyItem`.
 (0, index_js_1.markEager)(TreeNodeValid);
 function toFlexTreeNode(node) {

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

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/simple-tree/types.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 { ErasedType } from \"@fluidframework/core-interfaces\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport { TreeNodeSchema, WithType, type } from \"./schemaTypes.js\";\nimport {\n\tFlexTreeNode,\n\tMapTreeNode,\n\tisFlexTreeNode,\n\tmarkEager,\n} from \"../feature-libraries/index.js\";\nimport { tryGetSimpleNodeSchema } from \"./schemaCaching.js\";\nimport { isTreeNode } from \"./proxies.js\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { getFlexSchema } from \"./toFlexSchema.js\";\nimport { fail } from \"../util/index.js\";\nimport { setFlexNode } from \"./proxyBinding.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 * A non-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 results in the runtime and compile time behavior of `instanceof` differing.\n * TypeScript 5.3 allows altering the compile time behavior of `instanceof`.\n * The runtime behavior can be changed by implementing `Symbol.hasInstance`.\n * One of those approaches could be used to resolve this inconsistency,\n * but for now the type-only export prevents use of `instanceof` avoiding this problem in the public API.\n * @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 here 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 * {@inheritdoc \"type\"}\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 [type](): string;\n\n\tprotected constructor() {\n\t\tif (!(this instanceof TreeNodeValid)) {\n\t\t\tthrow new UsageError(\"TreeNodes must extend schema classes created by SchemaFactory\");\n\t\t}\n\t}\n}\n\n/**\n * Class which all {@link TreeNode}s must extend.\n * Since this is not exported, it allows robust detection of attempts to create TreeNodes which do not go through SchemaFactory which is the only place which exposes classes that extend this.\n *\n * This has static members which schema classes can override to provide schema specific functionality.\n * These static members are only intended to be used / overridden by code within this package, and are used by the various node kinds.\n * Access to these static members has to be done via `this.constructor.staticMember` to support the overrides, and thus can only be used in the constructor, after the base constructor has been invoked.\n */\nexport abstract class TreeNodeValid<TInput> extends TreeNode {\n\t/**\n\t * Schema classes can override this to control what happens at the end of the constructor.\n\t * The return value from this is returned from the constructor, allowing substituting a proxy if desired.\n\t *\n\t * This is not simply done in the derived constructor to enable:\n\t * - this class to access the value which is being returned before it's returned from the constructor.\n\t * - the derived class to be provided the input `FlexTreeNode` without relying on a field on the node to hold it.\n\t */\n\tprotected static prepareInstance<T>(\n\t\tthis: typeof TreeNodeValid<T>,\n\t\tinstance: TreeNodeValid<T>,\n\t\tinput: FlexTreeNode,\n\t): TreeNodeValid<T> {\n\t\treturn instance;\n\t}\n\n\t/**\n\t * Schema classes must override to provide an implementation of RawTreeNode construction.\n\t */\n\tprotected static buildRawNode<T>(\n\t\tthis: typeof TreeNodeValid<T>,\n\t\tinstance: TreeNodeValid<T>,\n\t\tinput: T,\n\t): MapTreeNode {\n\t\treturn fail(\"Schema must override buildRawNode\");\n\t}\n\n\t/**\n\t * Schema classes can override to provide a callback that is called once when the first node is constructed.\n\t * This is a good place to perform extra validation and cache schema derived data needed for the implementation of the node.\n\t */\n\tprotected static oneTimeSetup<T>(this: typeof TreeNodeValid<T>): void {}\n\n\t/**\n\t * The most derived constructor (the one invoked with the `new` operator, not a parent class constructor invoked with as `super`) used to construct an instance of this type.\n\t * @remarks\n\t * Captured when an instance is constructed.\n\t *\n\t * Used to ensure that some derived class (which must override this member, defaulting it to `undefined`) is only instantiated with a single \"most derived\" class (the constructor actually invoked the the user with `new`).\n\t *\n\t * Typically this is override in the class that statically implements {@link TreeNodeSchema} to enforce that all nodes using that schema use the same class and not different subclasses of it.\n\t *\n\t * Also used to detect if oneTimeSetup has run.\n\t *\n\t * @privateRemarks\n\t * This defaults to TreeNodeValid, which is used to trigger an error if not overridden in the derived class.\n\t *\n\t * The value of this on TreeNodeValid must only be overridden by base classes and never modified.\n\t * Ways to enforce this immutability prevent it from being overridden,\n\t * so code modifying constructorCached should be extra careful to avoid accidentally modifying the base/inherited value.\n\t */\n\tprotected static constructorCached: typeof TreeNodeValid | undefined = TreeNodeValid;\n\n\tpublic constructor(input: TInput | InternalTreeNode) {\n\t\tsuper();\n\t\tconst schema = this.constructor as typeof TreeNodeValid & TreeNodeSchema;\n\t\tassert(\"constructorCached\" in schema, 0x95f /* invalid schema class */);\n\t\tif (schema.constructorCached !== schema) {\n\t\t\tif (schema.constructorCached !== undefined) {\n\t\t\t\tassert(\n\t\t\t\t\tschema.constructorCached !== TreeNodeValid,\n\t\t\t\t\t0x960 /* Schema class schema must override static constructorCached member */,\n\t\t\t\t);\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`Two schema classes were instantiated (${schema.name} and ${schema.constructorCached.name}) which derived from the same SchemaFactory generated class. This is invalid`,\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tconst flexSchema = getFlexSchema(schema);\n\t\t\tassert(\n\t\t\t\ttryGetSimpleNodeSchema(flexSchema) === schema,\n\t\t\t\t0x961 /* Schema class not properly configured */,\n\t\t\t);\n\t\t\tschema.oneTimeSetup();\n\t\t\t// Set the constructorCached on the layer of the prototype chain that declared it.\n\t\t\t// This is necessary to ensure there is only one subclass of that type used:\n\t\t\t// if constructorCached was simply set on `schema`,\n\t\t\t// then a base classes between `schema` (exclusive) and where `constructorCached` is set (inclusive) and other subclasses of them\n\t\t\t// would not see the stored `constructorCached`, and the validation above against multiple derived classes would not work.\n\t\t\t{\n\t\t\t\tlet schemaBase: typeof TreeNodeValid = schema;\n\t\t\t\twhile (!Object.prototype.hasOwnProperty.call(schemaBase, \"constructorCached\")) {\n\t\t\t\t\tschemaBase = Reflect.getPrototypeOf(schemaBase) as typeof TreeNodeValid;\n\t\t\t\t}\n\t\t\t\tassert(\n\t\t\t\t\tschemaBase.constructorCached === undefined,\n\t\t\t\t\t0x962 /* overwriting wrong cache */,\n\t\t\t\t);\n\t\t\t\tschemaBase.constructorCached = schema;\n\t\t\t}\n\t\t}\n\n\t\tif (isTreeNode(input)) {\n\t\t\t// TODO: update this once we have better support for deep-copying and move operations.\n\t\t\tthrow new UsageError(\n\t\t\t\t\"Existing nodes may not be used as the constructor parameter for a new node. The existing node may be used directly instead of creating a new one, used as a child of the new node (if it has not yet been inserted into the tree). If the desired result is copying the provided node, it must be deep copied (since any child node would be parented under both the new and old nodes). Currently no API is provided to make deep copies, but it can be done manually with object spreads - for example `new Foo({...oldFoo})` will work if all fields of `oldFoo` are leaf nodes.\",\n\t\t\t);\n\t\t}\n\n\t\tconst node: FlexTreeNode = isFlexTreeNode(input) ? input : schema.buildRawNode(this, input);\n\t\tassert(\n\t\t\ttryGetSimpleNodeSchema(node.schema) === schema,\n\t\t\t0x83b /* building node with wrong schema */,\n\t\t);\n\n\t\tconst result = schema.prepareInstance(this, node);\n\t\tsetFlexNode(result, node);\n\t\treturn result;\n\t}\n}\n// Class objects are functions (callable), so we need a strong way to distinguish between `schema` and `() => schema` when used as a `LazyItem`.\nmarkEager(TreeNodeValid);\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 * @public\n */\nexport interface InternalTreeNode extends 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/types.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ErasedType } from \"@fluidframework/core-interfaces\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport { NodeKind, type TreeNodeSchema, type WithType, type } from \"./schemaTypes.js\";\nimport {\n\ttype FlexTreeNode,\n\ttype MapTreeNode,\n\tisFlexTreeNode,\n\tmarkEager,\n} from \"../feature-libraries/index.js\";\nimport { tryGetSimpleNodeSchema } from \"./schemaCaching.js\";\nimport { isTreeNode } from \"./proxies.js\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { getFlexSchema } from \"./toFlexSchema.js\";\nimport { fail } from \"../util/index.js\";\nimport { setFlexNode } from \"./proxyBinding.js\";\nimport { tryGetSchema } from \"./treeNodeApi.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 * 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 * @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 * {@inheritdoc \"type\"}\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 [type](): string;\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]<TSchema extends abstract new (...args: any[]) => TreeNode>(\n\t\tthis: TSchema,\n\t\tvalue: unknown,\n\t): value is InstanceType<TSchema>;\n\n\tpublic static [Symbol.hasInstance](this: { prototype: object }, value: unknown): boolean {\n\t\tconst schema = tryGetSchema(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, \"expected class based schema\");\n\t\treturn inPrototypeChain(schema.prototype, this.prototype);\n\t}\n\n\tprotected constructor() {\n\t\tif (!inPrototypeChain(Reflect.getPrototypeOf(this), TreeNodeValid.prototype)) {\n\t\t\tthrow new UsageError(\"TreeNodes must extend schema classes created by SchemaFactory\");\n\t\t}\n\t}\n}\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 * Class which all {@link TreeNode}s must extend.\n * Since this is not exported, it allows robust detection of attempts to create TreeNodes which do not go through SchemaFactory which is the only place which exposes classes that extend this.\n *\n * This has static members which schema classes can override to provide schema specific functionality.\n * These static members are only intended to be used / overridden by code within this package, and are used by the various node kinds.\n * Access to these static members has to be done via `this.constructor.staticMember` to support the overrides, and thus can only be used in the constructor, after the base constructor has been invoked.\n */\nexport abstract class TreeNodeValid<TInput> extends TreeNode {\n\t/**\n\t * Schema classes can override this to control what happens at the end of the constructor.\n\t * The return value from this is returned from the constructor, allowing substituting a proxy if desired.\n\t *\n\t * This is not simply done in the derived constructor to enable:\n\t * - this class to access the value which is being returned before it's returned from the constructor.\n\t * - the derived class to be provided the input `FlexTreeNode` without relying on a field on the node to hold it.\n\t */\n\tprotected static prepareInstance<T>(\n\t\tthis: typeof TreeNodeValid<T>,\n\t\tinstance: TreeNodeValid<T>,\n\t\tinput: FlexTreeNode,\n\t): TreeNodeValid<T> {\n\t\treturn instance;\n\t}\n\n\t/**\n\t * Schema classes must override to provide an implementation of RawTreeNode construction.\n\t */\n\tprotected static buildRawNode<T>(\n\t\tthis: typeof TreeNodeValid<T>,\n\t\tinstance: TreeNodeValid<T>,\n\t\tinput: T,\n\t): MapTreeNode {\n\t\treturn fail(\"Schema must override buildRawNode\");\n\t}\n\n\t/**\n\t * Schema classes can override to provide a callback that is called once when the first node is constructed.\n\t * This is a good place to perform extra validation and cache schema derived data needed for the implementation of the node.\n\t */\n\tprotected static oneTimeSetup<T>(this: typeof TreeNodeValid<T>): void {}\n\n\t/**\n\t * The most derived constructor (the one invoked with the `new` operator, not a parent class constructor invoked with as `super`) used to construct an instance of this type.\n\t * @remarks\n\t * Captured when an instance is constructed.\n\t *\n\t * Used to ensure that some derived class (which must override this member, defaulting it to `undefined`) is only instantiated with a single \"most derived\" class (the constructor actually invoked the the user with `new`).\n\t *\n\t * Typically this is override in the class that statically implements {@link TreeNodeSchema} to enforce that all nodes using that schema use the same class and not different subclasses of it.\n\t *\n\t * Also used to detect if oneTimeSetup has run.\n\t *\n\t * @privateRemarks\n\t * This defaults to TreeNodeValid, which is used to trigger an error if not overridden in the derived class.\n\t *\n\t * The value of this on TreeNodeValid must only be overridden by base classes and never modified.\n\t * Ways to enforce this immutability prevent it from being overridden,\n\t * so code modifying constructorCached should be extra careful to avoid accidentally modifying the base/inherited value.\n\t */\n\tprotected static constructorCached: typeof TreeNodeValid | undefined = TreeNodeValid;\n\n\tpublic constructor(input: TInput | InternalTreeNode) {\n\t\tsuper();\n\t\tconst schema = this.constructor as typeof TreeNodeValid & TreeNodeSchema;\n\t\tassert(\"constructorCached\" in schema, 0x95f /* invalid schema class */);\n\t\tif (schema.constructorCached !== schema) {\n\t\t\tif (schema.constructorCached !== undefined) {\n\t\t\t\tassert(\n\t\t\t\t\tschema.constructorCached !== TreeNodeValid,\n\t\t\t\t\t0x960 /* Schema class schema must override static constructorCached member */,\n\t\t\t\t);\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`Two schema classes were instantiated (${schema.name} and ${schema.constructorCached.name}) which derived from the same SchemaFactory generated class. This is invalid`,\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tconst flexSchema = getFlexSchema(schema);\n\t\t\tassert(\n\t\t\t\ttryGetSimpleNodeSchema(flexSchema) === schema,\n\t\t\t\t0x961 /* Schema class not properly configured */,\n\t\t\t);\n\t\t\tschema.oneTimeSetup();\n\t\t\t// Set the constructorCached on the layer of the prototype chain that declared it.\n\t\t\t// This is necessary to ensure there is only one subclass of that type used:\n\t\t\t// if constructorCached was simply set on `schema`,\n\t\t\t// then a base classes between `schema` (exclusive) and where `constructorCached` is set (inclusive) and other subclasses of them\n\t\t\t// would not see the stored `constructorCached`, and the validation above against multiple derived classes would not work.\n\t\t\t{\n\t\t\t\tlet schemaBase: typeof TreeNodeValid = schema;\n\t\t\t\twhile (!Object.prototype.hasOwnProperty.call(schemaBase, \"constructorCached\")) {\n\t\t\t\t\tschemaBase = Reflect.getPrototypeOf(schemaBase) as typeof TreeNodeValid;\n\t\t\t\t}\n\t\t\t\tassert(\n\t\t\t\t\tschemaBase.constructorCached === undefined,\n\t\t\t\t\t0x962 /* overwriting wrong cache */,\n\t\t\t\t);\n\t\t\t\tschemaBase.constructorCached = schema;\n\t\t\t}\n\t\t}\n\n\t\tif (isTreeNode(input)) {\n\t\t\t// TODO: update this once we have better support for deep-copying and move operations.\n\t\t\tthrow new UsageError(\n\t\t\t\t\"Existing nodes may not be used as the constructor parameter for a new node. The existing node may be used directly instead of creating a new one, used as a child of the new node (if it has not yet been inserted into the tree). If the desired result is copying the provided node, it must be deep copied (since any child node would be parented under both the new and old nodes). Currently no API is provided to make deep copies, but it can be done manually with object spreads - for example `new Foo({...oldFoo})` will work if all fields of `oldFoo` are leaf nodes.\",\n\t\t\t);\n\t\t}\n\n\t\tconst node: FlexTreeNode = isFlexTreeNode(input) ? input : schema.buildRawNode(this, input);\n\t\tassert(\n\t\t\ttryGetSimpleNodeSchema(node.schema) === schema,\n\t\t\t0x83b /* building node with wrong schema */,\n\t\t);\n\n\t\tconst result = schema.prepareInstance(this, node);\n\t\tsetFlexNode(result, node);\n\t\treturn result;\n\t}\n}\n// Class objects are functions (callable), so we need a strong way to distinguish between `schema` and `() => schema` when used as a `LazyItem`.\nmarkEager(TreeNodeValid);\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 * @public\n */\nexport interface InternalTreeNode extends 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/typesUnsafe.d.ts

@@ -2,11 +2,11 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { InternalFlexListTypes, Unenforced } from "../feature-libraries/index.js";
-import { RestrictiveReadonlyRecord } from "../util/index.js";
-import { AllowedTypes, ApplyKind, FieldKind, type FieldSchema, ImplicitAllowedTypes, ImplicitFieldSchema, NodeFromSchema, NodeKind, TreeNodeFromImplicitAllowedTypes, TreeNodeSchema, WithType } from "./schemaTypes.js";
-import { TreeArrayNodeBase, TreeArrayNode } from "./arrayNode.js";
-import { TreeNode, Unhydrated } from "./types.js";
+import type { InternalFlexListTypes, Unenforced } from "../feature-libraries/index.js";
+import type { RestrictiveReadonlyRecord } from "../util/index.js";
+import type { AllowedTypes, ApplyKind, FieldKind, FieldSchema, ImplicitAllowedTypes, ImplicitFieldSchema, NodeFromSchema, NodeKind, TreeNodeFromImplicitAllowedTypes, TreeNodeSchema, WithType } from "./schemaTypes.js";
+import type { TreeArrayNodeBase, TreeArrayNode } from "./arrayNode.js";
+import type { TreeNode, Unhydrated } from "./types.js";
 /**
  * {@link Unenforced} version of {@link ObjectFromSchemaRecord}.
  * @public