@fluidframework/tree 2.1.0 → 2.3.0-288113

package/lib/simple-tree/{schemaCaching.js → core/schemaCaching.js}

@@ -3,8 +3,7 @@
  * Licensed under the MIT License.
  */
 import { assert } from "@fluidframework/core-utils/internal";
-import { fail } from "../util/index.js";
-import { normalizeFieldSchema, } from "./schemaTypes.js";
+import { fail } from "../../util/index.js";
 /**
  * A symbol for storing FlexTreeSchema on TreeNodeSchema.
  * Eagerly set on leaves, and lazily set for other cases.
@@ -14,10 +13,6 @@ const flexSchemaSymbol = Symbol(`flexSchema`);
  * A symbol for storing TreeNodeSchema on FlexTreeNode's schema.
  */
 const simpleNodeSchemaSymbol = Symbol(`simpleNodeSchema`);
-/**
- * A symbol for storing {@link FieldSchema}s on a {@link FlexFieldSchema}.
- */
-const simpleFieldSchemaSymbol = Symbol(`simpleFieldSchema`);
 export function cachedFlexSchemaFromClassSchema(schema) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     return schema[flexSchemaSymbol];
@@ -47,19 +42,4 @@ export function tryGetSimpleNodeSchema(flexSchema) {
 export function getSimpleNodeSchema(flexSchema) {
     return tryGetSimpleNodeSchema(flexSchema) ?? fail("missing simple schema");
 }
-/**
- * Gets the {@link FieldSchema} which corresponds with the provided {@link FlexFieldSchema | flexSchema}.
- * Caches the result on the provided `flexSchema` for future access.
- * @param flexSchema - The flex schema on which the result will be cached.
- * @param implicitSimpleSchema - The allowed types from which the `FieldSchema` will be derived.
- */
-export function getSimpleFieldSchema(flexSchema, implicitSimpleSchema) {
-    if (simpleFieldSchemaSymbol in flexSchema) {
-        return flexSchema[simpleFieldSchemaSymbol];
-    }
-    const fieldSchema = normalizeFieldSchema(implicitSimpleSchema);
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    flexSchema[simpleFieldSchemaSymbol] = fieldSchema;
-    return fieldSchema;
-}
 //# sourceMappingURL=schemaCaching.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemaCaching.js","sourceRoot":"","sources":["../../../src/simple-tree/core/schemaCaching.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAG7D,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAI3C;;;GAGG;AACH,MAAM,gBAAgB,GAAkB,MAAM,CAAC,YAAY,CAAC,CAAC;AAE7D;;GAEG;AACH,MAAM,sBAAsB,GAAkB,MAAM,CAAC,kBAAkB,CAAC,CAAC;AAEzE,MAAM,UAAU,+BAA+B,CAC9C,MAAsB;IAEtB,8DAA8D;IAC9D,OAAQ,MAAc,CAAC,gBAAgB,CAAmC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,4BAA4B,CAC3C,MAAsB,EACtB,IAAwB;IAExB,MAAM,CAAC,CAAC,CAAC,gBAAgB,IAAI,MAAM,CAAC,EAAE,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAChF,MAAM,CAAC,CAAC,CAAC,sBAAsB,IAAI,IAAI,CAAC,EAAE,KAAK,CAAC,gCAAgC,CAAC,CAAC;IAClF,8DAA8D;IAC7D,MAAc,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC;IACzC,8DAA8D;IAC7D,IAAY,CAAC,sBAAsB,CAAC,GAAG,MAAM,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACrC,UAA8B;IAE9B,IAAI,sBAAsB,IAAI,UAAU,EAAE,CAAC;QAC1C,OAAO,UAAU,CAAC,sBAAsB,CAAmB,CAAC;IAC7D,CAAC;IACD,OAAO,SAAS,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAA8B;IACjE,OAAO,sBAAsB,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,uBAAuB,CAAC,CAAC;AAC5E,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport type { FlexTreeNodeSchema, TreeNodeSchemaBase } from \"../../feature-libraries/index.js\";\nimport { fail } from \"../../util/index.js\";\n\nimport type { TreeNodeSchema } from \"./treeNodeSchema.js\";\n\n/**\n * A symbol for storing FlexTreeSchema on TreeNodeSchema.\n * Eagerly set on leaves, and lazily set for other cases.\n */\nconst flexSchemaSymbol: unique symbol = Symbol(`flexSchema`);\n\n/**\n * A symbol for storing TreeNodeSchema on FlexTreeNode's schema.\n */\nconst simpleNodeSchemaSymbol: unique symbol = Symbol(`simpleNodeSchema`);\n\nexport function cachedFlexSchemaFromClassSchema(\n\tschema: TreeNodeSchema,\n): TreeNodeSchemaBase | undefined {\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\treturn (schema as any)[flexSchemaSymbol] as TreeNodeSchemaBase | undefined;\n}\n\nexport function setFlexSchemaFromClassSchema(\n\tsimple: TreeNodeSchema,\n\tflex: TreeNodeSchemaBase,\n): void {\n\tassert(!(flexSchemaSymbol in simple), 0x91f /* simple schema already marked */);\n\tassert(!(simpleNodeSchemaSymbol in flex), 0x920 /* flex schema already marked */);\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t(simple as any)[flexSchemaSymbol] = flex;\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t(flex as any)[simpleNodeSchemaSymbol] = simple;\n}\n\n/**\n * Gets the {@link TreeNodeSchema} cached on the provided {@link FlexTreeNodeSchema | flexSchema}.\n * Returns `undefined` if no cached value is found.\n */\nexport function tryGetSimpleNodeSchema(\n\tflexSchema: FlexTreeNodeSchema,\n): TreeNodeSchema | undefined {\n\tif (simpleNodeSchemaSymbol in flexSchema) {\n\t\treturn flexSchema[simpleNodeSchemaSymbol] as TreeNodeSchema;\n\t}\n\treturn undefined;\n}\n\n/**\n * Gets the {@link TreeNodeSchema} cached on the provided {@link FlexTreeNodeSchema | flexSchema}.\n * Fails if no cached value is found.\n */\nexport function getSimpleNodeSchema(flexSchema: FlexTreeNodeSchema): TreeNodeSchema {\n\treturn tryGetSimpleNodeSchema(flexSchema) ?? fail(\"missing simple schema\");\n}\n"]}

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

@@ -0,0 +1,70 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { type Listenable, type Off } from "../../events/index.js";
+import type { TreeNode, Unhydrated } from "./types.js";
+import type { AnchorEvents, AnchorNode } from "../../core/index.js";
+import { TreeStatus } from "../../feature-libraries/index.js";
+import type { TreeNodeSchema } from "./treeNodeSchema.js";
+export declare function getKernel(node: TreeNode): TreeNodeKernel;
+/**
+ * Detects if the given 'candidate' is a TreeNode.
+ *
+ * @remarks
+ * Supports both Hydrated and {@link Unhydrated} TreeNodes, both of which return true.
+ *
+ * Because the common usage is to check if a value being inserted/set is a TreeNode,
+ * this function permits calling with primitives as well as objects.
+ *
+ * Primitives will always return false (as they are copies of data, not references to nodes).
+ *
+ * @param candidate - Value which may be a TreeNode
+ * @returns true if the given 'candidate' is a hydrated TreeNode.
+ */
+export declare function isTreeNode(candidate: unknown): candidate is TreeNode | Unhydrated<TreeNode>;
+/**
+ * Returns a schema for a value if the value is a {@link TreeNode}.
+ *
+ * Returns undefined for other values.
+ * @remarks
+ * Does not give schema for a {@link TreeLeafValue}.
+ */
+export declare function tryGetTreeNodeSchema(value: unknown): undefined | TreeNodeSchema;
+/**
+ * Contains state and an internal API for managing {@link TreeNode}s.
+ * @remarks All {@link TreeNode}s have an associated kernel object.
+ * The kernel has the same lifetime as the node and spans both its unhydrated and hydrated states.
+ * When hydration occurs, the kernel is notified via the {@link TreeNodeKernel.hydrate | hydrate} method.
+ */
+export declare class TreeNodeKernel implements Listenable<KernelEvents> {
+    #private;
+    readonly node: TreeNode;
+    readonly schema: TreeNodeSchema;
+    private disposed;
+    /**
+     * Generation number which is incremented any time we have an edit on the node.
+     * Used during iteration to make sure there has been no edits that were concurrently made.
+     */
+    generationNumber: number;
+    /**
+     * Create a TreeNodeKernel which can be looked up with {@link getKernel}.
+     * @remarks
+     * Exactly one kernel per TreeNode should be created.
+     */
+    constructor(node: TreeNode, schema: TreeNodeSchema);
+    /**
+     * Transition from {@link Unhydrated} to hydrated.
+     * @remarks
+     * Happens at most once for any given node.
+     */
+    hydrate(anchorNode: AnchorNode): void;
+    isHydrated(): boolean;
+    getStatus(): TreeStatus;
+    on<K extends keyof KernelEvents>(eventName: K, listener: KernelEvents[K]): Off;
+    dispose(): void;
+}
+declare const kernelEvents: readonly ["childrenChangedAfterBatch", "subtreeChangedAfterBatch"];
+type KernelEvents = Pick<AnchorEvents, (typeof kernelEvents)[number]>;
+export {};
+//# sourceMappingURL=treeNodeKernel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"treeNodeKernel.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/core/treeNodeKernel.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAIN,KAAK,UAAU,EACf,KAAK,GAAG,EACR,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAIN,UAAU,EAEV,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,cAAc,CAIxD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,IAAI,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAE3F;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,cAAc,CAG/E;AAED;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,UAAU,CAAC,YAAY,CAAC;;aAiD7C,IAAI,EAAE,QAAQ;aACd,MAAM,EAAE,cAAc;IAjDvC,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;OAGG;IACI,gBAAgB,EAAE,MAAM,CAAK;IAoCpC;;;;OAIG;gBAEc,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,cAAc;IAMvC;;;;OAIG;IACI,OAAO,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI;IA8BrC,UAAU,IAAI,OAAO;IAKrB,SAAS,IAAI,UAAU;IAoBvB,EAAE,CAAC,CAAC,SAAS,MAAM,YAAY,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,GAAG;IAI9E,OAAO,IAAI,IAAI;CAOtB;AAED,QAAA,MAAM,YAAY,oEAAqE,CAAC;AAExF,KAAK,YAAY,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC"}

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

@@ -0,0 +1,157 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _TreeNodeKernel_instances, _TreeNodeKernel_hydrated, _TreeNodeKernel_preHydrationEvents, _TreeNodeKernel_events_get;
+import { assert } from "@fluidframework/core-utils/internal";
+import { createEmitter, } from "../../events/index.js";
+import { flexTreeSlot, isFreedSymbol, LazyEntity, TreeStatus, treeStatusFromAnchorCache, } from "../../feature-libraries/index.js";
+const treeNodeToKernel = new WeakMap();
+export function getKernel(node) {
+    const kernel = treeNodeToKernel.get(node);
+    assert(kernel !== undefined, 0x9b1 /* Expected tree node to have kernel */);
+    return kernel;
+}
+/**
+ * Detects if the given 'candidate' is a TreeNode.
+ *
+ * @remarks
+ * Supports both Hydrated and {@link Unhydrated} TreeNodes, both of which return true.
+ *
+ * Because the common usage is to check if a value being inserted/set is a TreeNode,
+ * this function permits calling with primitives as well as objects.
+ *
+ * Primitives will always return false (as they are copies of data, not references to nodes).
+ *
+ * @param candidate - Value which may be a TreeNode
+ * @returns true if the given 'candidate' is a hydrated TreeNode.
+ */
+export function isTreeNode(candidate) {
+    return treeNodeToKernel.has(candidate);
+}
+/**
+ * Returns a schema for a value if the value is a {@link TreeNode}.
+ *
+ * Returns undefined for other values.
+ * @remarks
+ * Does not give schema for a {@link TreeLeafValue}.
+ */
+export function tryGetTreeNodeSchema(value) {
+    const kernel = treeNodeToKernel.get(value);
+    return kernel?.schema;
+}
+/**
+ * Contains state and an internal API for managing {@link TreeNode}s.
+ * @remarks All {@link TreeNode}s have an associated kernel object.
+ * The kernel has the same lifetime as the node and spans both its unhydrated and hydrated states.
+ * When hydration occurs, the kernel is notified via the {@link TreeNodeKernel.hydrate | hydrate} method.
+ */
+export class TreeNodeKernel {
+    /**
+     * Create a TreeNodeKernel which can be looked up with {@link getKernel}.
+     * @remarks
+     * Exactly one kernel per TreeNode should be created.
+     */
+    constructor(node, schema) {
+        _TreeNodeKernel_instances.add(this);
+        this.node = node;
+        this.schema = schema;
+        this.disposed = false;
+        /**
+         * Generation number which is incremented any time we have an edit on the node.
+         * Used during iteration to make sure there has been no edits that were concurrently made.
+         */
+        this.generationNumber = 0;
+        _TreeNodeKernel_hydrated.set(this, void 0);
+        /**
+         * Events registered before hydration.
+         * @remarks
+         *
+         */
+        _TreeNodeKernel_preHydrationEvents.set(this, void 0);
+        assert(!treeNodeToKernel.has(node), 0xa1a /* only one kernel per node can be made */);
+        treeNodeToKernel.set(node, this);
+    }
+    /**
+     * Transition from {@link Unhydrated} to hydrated.
+     * @remarks
+     * Happens at most once for any given node.
+     */
+    hydrate(anchorNode) {
+        assert(!this.disposed, "cannot use a disposed node");
+        __classPrivateFieldSet(this, _TreeNodeKernel_hydrated, {
+            anchorNode,
+            offAnchorNode: new Set([
+                anchorNode.on("afterDestroy", () => this.dispose()),
+                // TODO: this should be triggered on change even for unhydrated nodes.
+                anchorNode.on("childrenChanging", () => {
+                    this.generationNumber += 1;
+                }),
+            ]),
+        }, "f");
+        // If needed, register forwarding emitters for events from before hydration
+        if (__classPrivateFieldGet(this, _TreeNodeKernel_preHydrationEvents, "f") !== undefined) {
+            for (const eventName of kernelEvents) {
+                if (__classPrivateFieldGet(this, _TreeNodeKernel_preHydrationEvents, "f").hasListeners(eventName)) {
+                    __classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f").offAnchorNode.add(
+                    // Argument is forwarded between matching events, so the type should be correct.
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    anchorNode.on(eventName, (arg) => __classPrivateFieldGet(this, _TreeNodeKernel_preHydrationEvents, "f")?.emit(eventName, arg)));
+                }
+            }
+        }
+    }
+    isHydrated() {
+        assert(!this.disposed, "cannot use a disposed node");
+        return __classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f") !== undefined;
+    }
+    getStatus() {
+        if (this.disposed) {
+            return TreeStatus.Deleted;
+        }
+        if (__classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f")?.anchorNode === undefined) {
+            return TreeStatus.New;
+        }
+        // TODO: Replace this check with the proper check against the cursor state when the cursor becomes part of the kernel
+        const flex = __classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f").anchorNode.slots.get(flexTreeSlot);
+        if (flex !== undefined) {
+            assert(flex instanceof LazyEntity, 0x9b4 /* Unexpected flex node implementation */);
+            if (flex[isFreedSymbol]()) {
+                return TreeStatus.Deleted;
+            }
+        }
+        return treeStatusFromAnchorCache(__classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f").anchorNode);
+    }
+    on(eventName, listener) {
+        return __classPrivateFieldGet(this, _TreeNodeKernel_instances, "a", _TreeNodeKernel_events_get).on(eventName, listener);
+    }
+    dispose() {
+        this.disposed = true;
+        for (const off of __classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f")?.offAnchorNode ?? []) {
+            off();
+        }
+        // TODO: go to the context and remove myself from withAnchors
+    }
+}
+_TreeNodeKernel_hydrated = new WeakMap(), _TreeNodeKernel_preHydrationEvents = new WeakMap(), _TreeNodeKernel_instances = new WeakSet(), _TreeNodeKernel_events_get = function _TreeNodeKernel_events_get() {
+    if (__classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f") === undefined) {
+        __classPrivateFieldSet(this, _TreeNodeKernel_preHydrationEvents, __classPrivateFieldGet(this, _TreeNodeKernel_preHydrationEvents, "f") ?? createEmitter(), "f");
+        return __classPrivateFieldGet(this, _TreeNodeKernel_preHydrationEvents, "f");
+    }
+    else {
+        return __classPrivateFieldGet(this, _TreeNodeKernel_hydrated, "f").anchorNode;
+    }
+};
+const kernelEvents = ["childrenChangedAfterBatch", "subtreeChangedAfterBatch"];
+//# sourceMappingURL=treeNodeKernel.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"treeNodeKernel.js","sourceRoot":"","sources":["../../../src/simple-tree/core/treeNodeKernel.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport {\n\tcreateEmitter,\n\ttype HasListeners,\n\ttype IEmitter,\n\ttype Listenable,\n\ttype Off,\n} from \"../../events/index.js\";\nimport type { TreeNode, Unhydrated } from \"./types.js\";\nimport type { AnchorEvents, AnchorNode } from \"../../core/index.js\";\nimport {\n\tflexTreeSlot,\n\tisFreedSymbol,\n\tLazyEntity,\n\tTreeStatus,\n\ttreeStatusFromAnchorCache,\n} from \"../../feature-libraries/index.js\";\nimport type { TreeNodeSchema } from \"./treeNodeSchema.js\";\n\nconst treeNodeToKernel = new WeakMap<TreeNode, TreeNodeKernel>();\n\nexport function getKernel(node: TreeNode): TreeNodeKernel {\n\tconst kernel = treeNodeToKernel.get(node);\n\tassert(kernel !== undefined, 0x9b1 /* Expected tree node to have kernel */);\n\treturn kernel;\n}\n\n/**\n * Detects if the given 'candidate' is a TreeNode.\n *\n * @remarks\n * Supports both Hydrated and {@link Unhydrated} TreeNodes, both of which return true.\n *\n * Because the common usage is to check if a value being inserted/set is a TreeNode,\n * this function permits calling with primitives as well as objects.\n *\n * Primitives will always return false (as they are copies of data, not references to nodes).\n *\n * @param candidate - Value which may be a TreeNode\n * @returns true if the given 'candidate' is a hydrated TreeNode.\n */\nexport function isTreeNode(candidate: unknown): candidate is TreeNode | Unhydrated<TreeNode> {\n\treturn treeNodeToKernel.has(candidate as TreeNode);\n}\n\n/**\n * Returns a schema for a value if the value is a {@link TreeNode}.\n *\n * Returns undefined for other values.\n * @remarks\n * Does not give schema for a {@link TreeLeafValue}.\n */\nexport function tryGetTreeNodeSchema(value: unknown): undefined | TreeNodeSchema {\n\tconst kernel = treeNodeToKernel.get(value as TreeNode);\n\treturn kernel?.schema;\n}\n\n/**\n * Contains state and an internal API for managing {@link TreeNode}s.\n * @remarks All {@link TreeNode}s have an associated kernel object.\n * The kernel has the same lifetime as the node and spans both its unhydrated and hydrated states.\n * When hydration occurs, the kernel is notified via the {@link TreeNodeKernel.hydrate | hydrate} method.\n */\nexport class TreeNodeKernel implements Listenable<KernelEvents> {\n\tprivate disposed = false;\n\n\t/**\n\t * Generation number which is incremented any time we have an edit on the node.\n\t * Used during iteration to make sure there has been no edits that were concurrently made.\n\t */\n\tpublic generationNumber: number = 0;\n\n\t#hydrated?: {\n\t\tanchorNode: AnchorNode;\n\t\toffAnchorNode: Set<Off>;\n\t};\n\n\t/**\n\t * Events registered before hydration.\n\t * @remarks\n\t *\n\t */\n\t#preHydrationEvents?: Listenable<KernelEvents> &\n\t\tIEmitter<KernelEvents> &\n\t\tHasListeners<KernelEvents>;\n\n\t/**\n\t * Get the listener.\n\t * @remarks\n\t * If before hydration, allocates and uses `#preHydrationEvents`, otherwise the anchorNode.\n\t * This design avoids allocating `#preHydrationEvents` if unneeded.\n\t *\n\t * This design also avoids extra forwarding overhead for events from anchorNode and also\n\t * avoids registering for events that the are unneeded.\n\t * This means optimizations like skipping processing data in subtrees where no subtreeChanged events are subscribed to would be able to work,\n\t * since this code does not unconditionally subscribe to those events (like a design simply forwarding all events would).\n\t */\n\tget #events(): Listenable<KernelEvents> {\n\t\tif (this.#hydrated === undefined) {\n\t\t\tthis.#preHydrationEvents ??= createEmitter<KernelEvents>();\n\t\t\treturn this.#preHydrationEvents;\n\t\t} else {\n\t\t\treturn this.#hydrated.anchorNode;\n\t\t}\n\t}\n\n\t/**\n\t * Create a TreeNodeKernel which can be looked up with {@link getKernel}.\n\t * @remarks\n\t * Exactly one kernel per TreeNode should be created.\n\t */\n\tpublic constructor(\n\t\tpublic readonly node: TreeNode,\n\t\tpublic readonly schema: TreeNodeSchema,\n\t) {\n\t\tassert(!treeNodeToKernel.has(node), 0xa1a /* only one kernel per node can be made */);\n\t\ttreeNodeToKernel.set(node, this);\n\t}\n\n\t/**\n\t * Transition from {@link Unhydrated} to hydrated.\n\t * @remarks\n\t * Happens at most once for any given node.\n\t */\n\tpublic hydrate(anchorNode: AnchorNode): void {\n\t\tassert(!this.disposed, \"cannot use a disposed node\");\n\n\t\tthis.#hydrated = {\n\t\t\tanchorNode,\n\t\t\toffAnchorNode: new Set([\n\t\t\t\tanchorNode.on(\"afterDestroy\", () => this.dispose()),\n\t\t\t\t// TODO: this should be triggered on change even for unhydrated nodes.\n\t\t\t\tanchorNode.on(\"childrenChanging\", () => {\n\t\t\t\t\tthis.generationNumber += 1;\n\t\t\t\t}),\n\t\t\t]),\n\t\t};\n\n\t\t// If needed, register forwarding emitters for events from before hydration\n\t\tif (this.#preHydrationEvents !== undefined) {\n\t\t\tfor (const eventName of kernelEvents) {\n\t\t\t\tif (this.#preHydrationEvents.hasListeners(eventName)) {\n\t\t\t\t\tthis.#hydrated.offAnchorNode.add(\n\t\t\t\t\t\t// Argument is forwarded between matching events, so the type should be correct.\n\t\t\t\t\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t\t\t\t\tanchorNode.on(eventName, (arg: any) =>\n\t\t\t\t\t\t\tthis.#preHydrationEvents?.emit(eventName, arg),\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tpublic isHydrated(): boolean {\n\t\tassert(!this.disposed, \"cannot use a disposed node\");\n\t\treturn this.#hydrated !== undefined;\n\t}\n\n\tpublic getStatus(): TreeStatus {\n\t\tif (this.disposed) {\n\t\t\treturn TreeStatus.Deleted;\n\t\t}\n\t\tif (this.#hydrated?.anchorNode === undefined) {\n\t\t\treturn TreeStatus.New;\n\t\t}\n\n\t\t// TODO: Replace this check with the proper check against the cursor state when the cursor becomes part of the kernel\n\t\tconst flex = this.#hydrated.anchorNode.slots.get(flexTreeSlot);\n\t\tif (flex !== undefined) {\n\t\t\tassert(flex instanceof LazyEntity, 0x9b4 /* Unexpected flex node implementation */);\n\t\t\tif (flex[isFreedSymbol]()) {\n\t\t\t\treturn TreeStatus.Deleted;\n\t\t\t}\n\t\t}\n\n\t\treturn treeStatusFromAnchorCache(this.#hydrated.anchorNode);\n\t}\n\n\tpublic on<K extends keyof KernelEvents>(eventName: K, listener: KernelEvents[K]): Off {\n\t\treturn this.#events.on(eventName, listener);\n\t}\n\n\tpublic dispose(): void {\n\t\tthis.disposed = true;\n\t\tfor (const off of this.#hydrated?.offAnchorNode ?? []) {\n\t\t\toff();\n\t\t}\n\t\t// TODO: go to the context and remove myself from withAnchors\n\t}\n}\n\nconst kernelEvents = [\"childrenChangedAfterBatch\", \"subtreeChangedAfterBatch\"] as const;\n\ntype KernelEvents = Pick<AnchorEvents, (typeof kernelEvents)[number]>;\n"]}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"treeNodeSchema.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/core/treeNodeSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,CACzB,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,IAAI,SAAS,QAAQ,GAAG,QAAQ,EAChC,KAAK,GAAG,OAAO,EACf,MAAM,GAAG,KAAK,EACd,uBAAuB,SAAS,OAAO,GAAG,OAAO,EACjD,IAAI,GAAG,OAAO,IAEZ,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,uBAAuB,EAAE,IAAI,CAAC,GAC7E,sBAAsB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,uBAAuB,EAAE,IAAI,CAAC,CAAC;AAEpF;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB,CACtC,GAAG,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAChC,GAAG,CAAC,IAAI,SAAS,QAAQ,GAAG,QAAQ,EACpC,GAAG,CAAC,KAAK,GAAG,OAAO,EACnB,EAAE,CAAC,WAAW,GAAG,KAAK,EACtB,GAAG,CAAC,uBAAuB,SAAS,OAAO,GAAG,OAAO,EACrD,GAAG,CAAC,IAAI,GAAG,OAAO,CACjB,SAAQ,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,uBAAuB,EAAE,IAAI,CAAC;IACtE,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,KAAK,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,WAAW,mBAAmB,CACnC,GAAG,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAChC,GAAG,CAAC,IAAI,SAAS,QAAQ,GAAG,QAAQ,EACpC,GAAG,CAAC,KAAK,GAAG,OAAO,EACnB,EAAE,CAAC,WAAW,GAAG,KAAK,EACtB,GAAG,CAAC,uBAAuB,SAAS,OAAO,GAAG,OAAO,EACrD,GAAG,CAAC,IAAI,GAAG,OAAO,CACjB,SAAQ,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,uBAAuB,EAAE,IAAI,CAAC;IACtE;;;;;;OAMG;IACH,KAAK,IAAI,EAAE,WAAW,GAAG,gBAAgB,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;CAC9D;AACD;;;;;GAKG;AAEH,MAAM,WAAW,kBAAkB,CAClC,GAAG,CAAC,IAAI,SAAS,MAAM,EACvB,GAAG,CAAC,IAAI,SAAS,QAAQ,EACzB,GAAG,CAAC,uBAAuB,SAAS,OAAO,EAC3C,GAAG,CAAC,IAAI,GAAG,OAAO;IAElB;;;;;;;;;OASG;IACH,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAEpB;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAEpB;;;;;;;;;OASG;IACH,QAAQ,CAAC,uBAAuB,EAAE,uBAAuB,CAAC;CAC1D;AAED;;;;;GAKG;AACH,oBAAY,QAAQ;IACnB;;OAEG;IACH,GAAG,IAAA;IACH;;OAEG;IACH,KAAK,IAAA;IACL;;;;OAIG;IACH,MAAM,IAAA;IACN;;OAEG;IACH,IAAI,IAAA;CACJ"}

package/lib/simple-tree/core/treeNodeSchema.js

@@ -0,0 +1,32 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Kind of tree node.
+ * @remarks
+ * More kinds may be added over time, so do not assume this is an exhaustive set.
+ * @public
+ */
+export var NodeKind;
+(function (NodeKind) {
+    /**
+     * A node which serves as a map, storing children under string keys.
+     */
+    NodeKind[NodeKind["Map"] = 0] = "Map";
+    /**
+     * A node which serves as an array, storing children in an ordered sequence.
+     */
+    NodeKind[NodeKind["Array"] = 1] = "Array";
+    /**
+     * A node which stores a heterogenous collection of children in named fields.
+     * @remarks
+     * Each field gets its own schema.
+     */
+    NodeKind[NodeKind["Object"] = 2] = "Object";
+    /**
+     * A node which stores a single leaf value.
+     */
+    NodeKind[NodeKind["Leaf"] = 3] = "Leaf";
+})(NodeKind || (NodeKind = {}));
+//# sourceMappingURL=treeNodeSchema.js.map

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

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