@fluidframework/tree 2.1.0-281041 → 2.2.0

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"]}

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

@@ -0,0 +1,178 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { ErasedType } from "@fluidframework/core-interfaces";
+import { type TreeNodeSchemaClass } from "./treeNodeSchema.js";
+import { type WithType, typeNameSymbol, type typeSchemaSymbol } from "./withType.js";
+import { type FlexTreeNode } from "../../feature-libraries/index.js";
+/**
+ * Type alias to document which values are un-hydrated.
+ *
+ * Un-hydrated values are nodes produced from schema's create functions that haven't been inserted into a tree yet.
+ *
+ * Since un-hydrated nodes become hydrated when inserted, strong typing can't be used to distinguish them.
+ * This no-op wrapper is used instead.
+ * @public
+ */
+export type Unhydrated<T> = T;
+/**
+ * A collection of events that can be emitted by a {@link TreeNode}.
+ *
+ * @privateRemarks
+ * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).
+ * Probably have object node and map node specific APIs for this.
+ *
+ * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.
+ *
+ * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.
+ * Some ideas:
+ *
+ * - treeChanged, but with some subtrees/fields/paths excluded
+ * - helper to batch several nodeChanged calls to a treeChanged scope
+ * - parent change (ex: registration on the parent field for a specific index: maybe allow it for a range. Ex: node event takes optional field and optional index range?)
+ * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.
+ * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)
+ * to allow efficiently searching for new content (and initial content) of a given type.
+ *
+ * @sealed @public
+ */
+export interface TreeChangeEvents {
+    /**
+     * Emitted by a node after a batch of changes has been applied to the tree, if a change affected the node, where a
+     * change is:
+     *
+     * - For an object node, when the value of one of its properties changes (i.e., the property's value is set
+     * to something else, including `undefined`).
+     *
+     * - For an array node, when an element is added, removed, or moved.
+     *
+     * - For a map node, when an entry is added, updated, or removed.
+     *
+     * @remarks
+     * This event is not emitted when:
+     *
+     * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing
+     * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the
+     * array/map node as one of its properties.
+     *
+     * - The node is moved to a different location in the tree or removed from the tree.
+     * In this case the event is emitted on the _parent_ node, not the node itself.
+     *
+     * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
+     * the client that made the original edit.
+     *
+     * When it is emitted, the tree is guaranteed to be in-schema.
+     *
+     * @privateRemarks
+     * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.
+     * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the
+     * node, or when the node has to be updated due to resolution of a merge conflict
+     * (for example a previously applied local change might be undone, then reapplied differently or not at all).
+     */
+    nodeChanged(): void;
+    /**
+     * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the
+     * subtree rooted at it.
+     *
+     * @remarks
+     * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.
+     * In that case it is emitted on the _parent_ node, not the node itself.
+     *
+     * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties
+     * of the node itself.
+     *
+     * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
+     * the client that made the original edit.
+     *
+     * When it is emitted, the tree is guaranteed to be in-schema.
+     */
+    treeChanged(): void;
+}
+/**
+ * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
+ *
+ * @remarks
+ * Base type which all nodes implement.
+ *
+ * This can be used as a type to indicate/document values which should be tree nodes.
+ * Runtime use of this class object (for example when used with `instanceof` or extending it), is not currently supported.
+ *
+ * Instances of tree nodes must be created by opening an existing document, inserting values into the document,
+ * or by using the constructors and create functions of {@link TreeNodeSchema} produced by {@link SchemaFactory}.
+ * @privateRemarks
+ * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})
+ * and some runtime enforcement of schema class policy (see the the validation in the constructor).
+ * This class is however only `type` exported not value exported, preventing the class object from being used,
+ * similar to how interfaces work.
+ *
+ * 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 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).
+ * @sealed @public
+ */
+export declare abstract class TreeNode implements WithType {
+    #private;
+    /**
+     * Adds a type symbol for stronger typing.
+     * @privateRemarks
+     * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.
+     * @deprecated Use {@link typeSchemaSymbol} instead.
+     */
+    abstract get [typeNameSymbol](): string;
+    /**
+     * Adds a type symbol for stronger typing.
+     * @privateRemarks
+     * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.
+     */
+    abstract get [typeSchemaSymbol](): TreeNodeSchemaClass;
+    /**
+     * 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>;
+    /**
+     * TreeNodes must extend schema classes created by SchemaFactory, and therefore this constructor should not be invoked directly by code outside this package.
+     * @privateRemarks
+     * `token` must be the {@link privateToken} value, which is not package exported.
+     * This is used to detect invalid subclasses.
+     *
+     * All valid subclass should use {@link TreeNodeValid}, but this code doesn't directly reference it to avoid cyclic dependencies.
+     */
+    protected constructor(token: unknown);
+}
+/**
+ * `token` to pass to {@link TreeNode}'s constructor used to detect invalid subclasses.
+ */
+export declare const privateToken: {};
+/**
+ * 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;
+/**
+ * A node type internal to `@fluidframework/tree`.
+ * @remarks
+ * 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.
+ * @privateRemarks
+ * A {@link FlexTreeNode}. Includes {@link RawTreeNode}s.
+ * @sealed @public
+ */
+export interface InternalTreeNode extends ErasedType<"@fluidframework/tree.InternalTreeNode"> {
+}
+export declare function toFlexTreeNode(node: InternalTreeNode): FlexTreeNode;
+//# sourceMappingURL=types.d.ts.map

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

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

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

@@ -0,0 +1,111 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+var _TreeNode_brand;
+import { assert } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { NodeKind } from "./treeNodeSchema.js";
+// eslint-disable-next-line import/no-deprecated
+import { typeNameSymbol } from "./withType.js";
+import { tryGetTreeNodeSchema } from "./treeNodeKernel.js";
+import { isFlexTreeNode } from "../../feature-libraries/index.js";
+/**
+ * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
+ *
+ * @remarks
+ * Base type which all nodes implement.
+ *
+ * This can be used as a type to indicate/document values which should be tree nodes.
+ * Runtime use of this class object (for example when used with `instanceof` or extending it), is not currently supported.
+ *
+ * Instances of tree nodes must be created by opening an existing document, inserting values into the document,
+ * or by using the constructors and create functions of {@link TreeNodeSchema} produced by {@link SchemaFactory}.
+ * @privateRemarks
+ * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})
+ * and some runtime enforcement of schema class policy (see the the validation in the constructor).
+ * This class is however only `type` exported not value exported, preventing the class object from being used,
+ * similar to how interfaces work.
+ *
+ * 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 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).
+ * @sealed @public
+ */
+export class TreeNode {
+    static [(_TreeNode_brand = new WeakMap(), Symbol.hasInstance)](value) {
+        const schema = tryGetTreeNodeSchema(value);
+        if (schema === undefined || schema.kind === NodeKind.Leaf) {
+            return false;
+        }
+        assert("prototype" in schema, 0x98a /* expected class based schema */);
+        return inPrototypeChain(schema.prototype, this.prototype);
+    }
+    /**
+     * TreeNodes must extend schema classes created by SchemaFactory, and therefore this constructor should not be invoked directly by code outside this package.
+     * @privateRemarks
+     * `token` must be the {@link privateToken} value, which is not package exported.
+     * This is used to detect invalid subclasses.
+     *
+     * All valid subclass should use {@link TreeNodeValid}, but this code doesn't directly reference it to avoid cyclic dependencies.
+     */
+    constructor(token) {
+        /**
+         * 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 (token !== privateToken) {
+            throw new UsageError("TreeNodes must extend schema classes created by SchemaFactory");
+        }
+    }
+}
+/**
+ * `token` to pass to {@link TreeNode}'s constructor used to detect invalid subclasses.
+ */
+export const privateToken = {};
+/**
+ * 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
+export function inPrototypeChain(derived, base) {
+    let checking = derived;
+    while (checking !== null) {
+        if (base === checking) {
+            return true;
+        }
+        checking = Reflect.getPrototypeOf(checking);
+    }
+    return false;
+}
+export function toFlexTreeNode(node) {
+    assert(isFlexTreeNode(node), 0x963 /* Invalid InternalTreeNode */);
+    return node;
+}
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/simple-tree/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAGtE,OAAO,EAAE,QAAQ,EAA4B,MAAM,qBAAqB,CAAC;AACzE,gDAAgD;AAChD,OAAO,EAAiB,cAAc,EAAyB,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAqB,MAAM,kCAAkC,CAAC;AAwFrF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAgB,QAAQ;IAmEtB,MAAM,CAAC,mCAAC,MAAM,CAAC,WAAW,EAAC,CAA8B,KAAc;QAC7E,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAE3C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC3D,OAAO,KAAK,CAAC;QACd,CAAC;QAED,MAAM,CAAC,WAAW,IAAI,MAAM,EAAE,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACvE,OAAO,gBAAgB,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;;OAOG;IACH,YAAsB,KAAc;QArFpC;;;;;;;;;;;;;;;;;;;;;;;;;WAyBG;QACM,kCAAiB;QA4DzB,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;YAC5B,MAAM,IAAI,UAAU,CAAC,+DAA+D,CAAC,CAAC;QACvF,CAAC;IACF,CAAC;CACD;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC;AAE/B;;;;;GAKG;AACH,kDAAkD;AAClD,MAAM,UAAU,gBAAgB,CAAC,OAAsB,EAAE,IAAY;IACpE,IAAI,QAAQ,GAAG,OAAO,CAAC;IACvB,OAAO,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC1B,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;QACD,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAaD,MAAM,UAAU,cAAc,CAAC,IAAsB;IACpD,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACnE,OAAO,IAAI,CAAC;AACb,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\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport type { ErasedType } from \"@fluidframework/core-interfaces\";\n\nimport { NodeKind, type TreeNodeSchemaClass } from \"./treeNodeSchema.js\";\n// eslint-disable-next-line import/no-deprecated\nimport { type WithType, typeNameSymbol, type typeSchemaSymbol } from \"./withType.js\";\nimport { tryGetTreeNodeSchema } from \"./treeNodeKernel.js\";\nimport { isFlexTreeNode, type FlexTreeNode } from \"../../feature-libraries/index.js\";\n\n/**\n * Type alias to document which values are un-hydrated.\n *\n * Un-hydrated values are nodes produced from schema's create functions that haven't been inserted into a tree yet.\n *\n * Since un-hydrated nodes become hydrated when inserted, strong typing can't be used to distinguish them.\n * This no-op wrapper is used instead.\n * @public\n */\nexport type Unhydrated<T> = T;\n\n/**\n * A collection of events that can be emitted by a {@link TreeNode}.\n *\n * @privateRemarks\n * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).\n * Probably have object node and map node specific APIs for this.\n *\n * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.\n *\n * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.\n * Some ideas:\n *\n * - treeChanged, but with some subtrees/fields/paths excluded\n * - helper to batch several nodeChanged calls to a treeChanged scope\n * - parent change (ex: registration on the parent field for a specific index: maybe allow it for a range. Ex: node event takes optional field and optional index range?)\n * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.\n * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)\n * to allow efficiently searching for new content (and initial content) of a given type.\n *\n * @sealed @public\n */\nexport interface TreeChangeEvents {\n\t/**\n\t * Emitted by a node after a batch of changes has been applied to the tree, if a change affected the node, where a\n\t * change is:\n\t *\n\t * - For an object node, when the value of one of its properties changes (i.e., the property's value is set\n\t * to something else, including `undefined`).\n\t *\n\t * - For an array node, when an element is added, removed, or moved.\n\t *\n\t * - For a map node, when an entry is added, updated, or removed.\n\t *\n\t * @remarks\n\t * This event is not emitted when:\n\t *\n\t * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing\n\t * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the\n\t * array/map node as one of its properties.\n\t *\n\t * - The node is moved to a different location in the tree or removed from the tree.\n\t * In this case the event is emitted on the _parent_ node, not the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When it is emitted, the tree is guaranteed to be in-schema.\n\t *\n\t * @privateRemarks\n\t * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.\n\t * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the\n\t * node, or when the node has to be updated due to resolution of a merge conflict\n\t * (for example a previously applied local change might be undone, then reapplied differently or not at all).\n\t */\n\tnodeChanged(): void;\n\n\t/**\n\t * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the\n\t * subtree rooted at it.\n\t *\n\t * @remarks\n\t * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.\n\t * In that case it is emitted on the _parent_ node, not the node itself.\n\t *\n\t * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties\n\t * of the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When it is emitted, the tree is guaranteed to be in-schema.\n\t */\n\ttreeChanged(): void;\n}\n\n/**\n * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.\n *\n * @remarks\n * Base type which all nodes implement.\n *\n * This can be used as a type to indicate/document values which should be tree nodes.\n * Runtime use of this class object (for example when used with `instanceof` or extending it), is not currently supported.\n *\n * Instances of tree nodes must be created by opening an existing document, inserting values into the document,\n * or by using the constructors and create functions of {@link TreeNodeSchema} produced by {@link SchemaFactory}.\n * @privateRemarks\n * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})\n * and some runtime enforcement of schema class policy (see the the validation in the constructor).\n * This class is however only `type` exported not value exported, preventing the class object from being used,\n * similar to how interfaces work.\n *\n * Not all node implementations include this in their prototype chain (some hide it with a proxy),\n * and thus cause the default/built in `instanceof` to return false despite our type checking and all other APIs treating them as TreeNodes.\n * This class provides a custom `Symbol.hasInstance` to fix `instanceof` for this class and all classes extending it.\n * For now the type-only export prevents use of `instanceof` on this class (but allows it in subclasses like schema classes).\n * @sealed @public\n */\nexport abstract class TreeNode implements WithType {\n\t/**\n\t * This is added to prevent TypeScript from implicitly allowing non-TreeNode types to be used as TreeNodes.\n\t * @remarks\n\t * This field forces TypeScript to use nominal instead of structural typing,\n\t * preventing compiler error messages and tools like \"add missing properties\"\n\t * from adding the [type] field as a solution when using a non-TreeNode object where a TreeNode is required.\n\t * Instead TreeNodes must be created through the appropriate APIs, see the documentation on {@link TreeNode} for details.\n\t *\n\t * @privateRemarks\n\t * This is a JavaScript private field, so is not accessible from outside this class.\n\t * This prevents it from having name collisions with object fields.\n\t * Since this is private, the type of this field is stripped in the d.ts file.\n\t * To get matching type checking within and from outside the package, the least informative type (`unknown`) is used.\n\t * To avoid this having any runtime impact, the field is uninitialized.\n\t *\n\t * Making this field optional results in different type checking within this project than outside of it, since the d.ts file drops the optional aspect of the field.\n\t * This is extra confusing since since the tests get in-project typing for intellisense and separate project checking at build time.\n\t * To avoid all this mess, this field is required, not optional.\n\t *\n\t * Another option would be to use a symbol (possibly as a private field).\n\t * That approach ran into some strange difficulties causing SchemaFactory to fail to compile, and was not investigated further.\n\t *\n\t * The [type] symbol provides a lot of the value this private brand does, but is not all of it:\n\t * someone could manually (or via Intellisense auto-implement completion, or in response to a type error)\n\t * make an object literal with the [type] field and pass it off as a node: this private brand prevents that.\n\t */\n\treadonly #brand!: unknown;\n\n\t/**\n\t * Adds a type symbol for stronger typing.\n\t * @privateRemarks\n\t * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.\n\t * @deprecated Use {@link typeSchemaSymbol} instead.\n\t */\n\t// eslint-disable-next-line import/no-deprecated\n\tpublic abstract get [typeNameSymbol](): string;\n\n\t/**\n\t * Adds a type symbol for stronger typing.\n\t * @privateRemarks\n\t * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.\n\t */\n\tpublic abstract get [typeSchemaSymbol](): TreeNodeSchemaClass;\n\n\t/**\n\t * Provides `instanceof` support for testing if a value is a `TreeNode`.\n\t * @remarks\n\t * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.\n\t * @privateRemarks\n\t * Due to type-only export, this functionality is not available outside the package.\n\t */\n\tpublic static [Symbol.hasInstance](value: unknown): value is TreeNode;\n\n\t/**\n\t * Provides `instanceof` support for all schema classes with public constructors.\n\t * @remarks\n\t * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.\n\t * @privateRemarks\n\t * Despite type-only export, this functionality is available outside the package since it is inherited by subclasses.\n\t */\n\tpublic static [Symbol.hasInstance]<\n\t\tTSchema extends abstract new (\n\t\t\t...args: any[]\n\t\t) => TreeNode,\n\t>(this: TSchema, value: unknown): value is InstanceType<TSchema>;\n\n\tpublic static [Symbol.hasInstance](this: { prototype: object }, value: unknown): boolean {\n\t\tconst schema = tryGetTreeNodeSchema(value);\n\n\t\tif (schema === undefined || schema.kind === NodeKind.Leaf) {\n\t\t\treturn false;\n\t\t}\n\n\t\tassert(\"prototype\" in schema, 0x98a /* expected class based schema */);\n\t\treturn inPrototypeChain(schema.prototype, this.prototype);\n\t}\n\n\t/**\n\t * TreeNodes must extend schema classes created by SchemaFactory, and therefore this constructor should not be invoked directly by code outside this package.\n\t * @privateRemarks\n\t * `token` must be the {@link privateToken} value, which is not package exported.\n\t * This is used to detect invalid subclasses.\n\t *\n\t * All valid subclass should use {@link TreeNodeValid}, but this code doesn't directly reference it to avoid cyclic dependencies.\n\t */\n\tprotected constructor(token: unknown) {\n\t\tif (token !== privateToken) {\n\t\t\tthrow new UsageError(\"TreeNodes must extend schema classes created by SchemaFactory\");\n\t\t}\n\t}\n}\n\n/**\n * `token` to pass to {@link TreeNode}'s constructor used to detect invalid subclasses.\n */\nexport const privateToken = {};\n\n/**\n * Check if the prototype derived's prototype chain contains `base`.\n * @param derived - prototype to check\n * @param base - prototype to search for\n * @returns true iff `base` is in the prototype chain starting at `derived`.\n */\n// eslint-disable-next-line @rushstack/no-new-null\nexport function inPrototypeChain(derived: object | null, base: object): boolean {\n\tlet checking = derived;\n\twhile (checking !== null) {\n\t\tif (base === checking) {\n\t\t\treturn true;\n\t\t}\n\t\tchecking = Reflect.getPrototypeOf(checking);\n\t}\n\treturn false;\n}\n\n/**\n * A node type internal to `@fluidframework/tree`.\n * @remarks\n * This type is used in the construction of {@link TreeNode} as an implementation detail, but leaks into the public API due to how schema are implemented.\n * @privateRemarks\n * A {@link FlexTreeNode}. Includes {@link RawTreeNode}s.\n * @sealed @public\n */\nexport interface InternalTreeNode\n\textends ErasedType<\"@fluidframework/tree.InternalTreeNode\"> {}\n\nexport function toFlexTreeNode(node: InternalTreeNode): FlexTreeNode {\n\tassert(isFlexTreeNode(node), 0x963 /* Invalid InternalTreeNode */);\n\treturn node;\n}\n"]}

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

@@ -0,0 +1,82 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { NodeKind, TreeNodeSchemaClass } from "./treeNodeSchema.js";
+/**
+ * The type of a {@link TreeNode}.
+ * For more information about the type, use `Tree.schema(theNode)` instead.
+ * @remarks
+ * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.
+ * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.
+ *
+ * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where nodes are expected.
+ * Instead construct a real node of the desired type using its constructor.
+ * @privateRemarks
+ * This prevents non-nodes from being accidentally used as nodes, as well as allows the type checker to distinguish different node types.
+ * @deprecated External code should use `Tree.schema(theNode)` for schema related runtime data access. For type narrowing, use `WithType` instead of the symbols directly.
+ * @system @public
+ */
+export declare const typeNameSymbol: unique symbol;
+/**
+ * The type of a {@link TreeNode}.
+ * For more information about the type, use `Tree.schema(theNode)` instead.
+ * @remarks
+ * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.
+ * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.
+ *
+ * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where specific nodes are expected.
+ * Instead construct a real node of the desired type using its constructor.
+ *
+ * This symbol should not be used directly for type narrowing. Instead use {@link WithType}.
+ * @privateRemarks
+ * This prevents non-nodes from being accidentally used as nodes and allows the type-checker to distinguish different node types.
+ * @system @public
+ */
+export declare const typeSchemaSymbol: unique symbol;
+/**
+ * Adds a type symbol to a type for stronger typing.
+ *
+ * @typeParam TName - Same as {@link TreeNodeSchema}'s "Name" parameter.
+ * @typeParam TKind - Same as {@link TreeNodeSchema}'s "Kind" parameter.
+ * @remarks
+ * Powers {@link TreeNode}'s strong typing setup.
+ * @example Narrow types for overloading based on NodeKind
+ * ```typescript
+ * function getKeys(node: TreeNode & WithType<string, NodeKind.Array>): number[];
+ * function getKeys(node: TreeNode & WithType<string, NodeKind.Map | NodeKind.Object>): string[];
+ * function getKeys(node: TreeNode): string[] | number[];
+ * function getKeys(node: TreeNode): string[] | number[] {
+ * 	const schema = Tree.schema(node);
+ * 	switch (schema.kind) {
+ * 		case NodeKind.Array: {
+ * 			const arrayNode = node as TreeArrayNode;
+ * 			const keys: number[] = [];
+ * 			for (let index = 0; index < arrayNode.length; index++) {
+ * 				keys.push(index);
+ * 			}
+ * 			return keys;
+ * 		}
+ * 		case NodeKind.Map:
+ * 			return [...(node as TreeMapNode).keys()];
+ * 		case NodeKind.Object:
+ * 			return Object.keys(node);
+ * 		default:
+ * 			throw new Error("Unsupported Kind");
+ * 	}
+ * }
+ * ```
+ * @sealed @public
+ */
+export interface WithType<out TName extends string = string, out TKind extends NodeKind = NodeKind> {
+    /**
+     * Type symbol, marking a type in a way to increase type safety via strong type checking.
+     * @deprecated Use {@link typeSchemaSymbol} instead.
+     */
+    get [typeNameSymbol](): TName;
+    /**
+     * Type symbol, marking a type in a way to increase type safety via strong type checking.
+     */
+    get [typeSchemaSymbol](): TreeNodeSchemaClass<TName, TKind>;
+}
+//# sourceMappingURL=withType.d.ts.map

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

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