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

package/src/simple-tree/types.ts

@@ -6,7 +6,7 @@
 import type { ErasedType } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 
-import { type TreeNodeSchema, type WithType, type } from "./schemaTypes.js";
+import { NodeKind, type TreeNodeSchema, type WithType, type } from "./schemaTypes.js";
 import {
 	type FlexTreeNode,
 	type MapTreeNode,
@@ -19,6 +19,7 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { getFlexSchema } from "./toFlexSchema.js";
 import { fail } from "../util/index.js";
 import { setFlexNode } from "./proxyBinding.js";
+import { tryGetSchema } from "./treeNodeApi.js";
 
 /**
  * Type alias to document which values are un-hydrated.
@@ -32,7 +33,7 @@ import { setFlexNode } from "./proxyBinding.js";
 export type Unhydrated<T> = T;
 
 /**
- * A non-leaf SharedTree node. Includes objects, arrays, and maps.
+ * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
  *
  * @remarks
  * Base type which all nodes implement.
@@ -50,11 +51,8 @@ export type Unhydrated<T> = T;
  *
  * Not all node implementations include this in their prototype chain (some hide it with a proxy),
  * and thus cause the default/built in `instanceof` to return false despite our type checking and all other APIs treating them as TreeNodes.
- * This results in the runtime and compile time behavior of `instanceof` differing.
- * TypeScript 5.3 allows altering the compile time behavior of `instanceof`.
- * The runtime behavior can be changed by implementing `Symbol.hasInstance`.
- * One of those approaches could be used to resolve this inconsistency,
- * but for now the type-only export prevents use of `instanceof` avoiding this problem in the public API.
+ * This class provides a custom `Symbol.hasInstance` to fix `instanceof` for this class and all classes extending it.
+ * For now the type-only export prevents use of `instanceof` on this class (but allows it in subclasses like schema classes).
  * @public
  */
 export abstract class TreeNode implements WithType {
@@ -80,7 +78,7 @@ export abstract class TreeNode implements WithType {
 	 * Another option would be to use a symbol (possibly as a private field).
 	 * That approach ran into some strange difficulties causing SchemaFactory to fail to compile, and was not investigated further.
 	 *
-	 * The [type] symbol here provides a lot of the value this private brand does, but is not all of it:
+	 * 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.
 	 */
@@ -93,13 +91,63 @@ export abstract class TreeNode implements WithType {
 	 */
 	public abstract get [type](): string;
 
+	/**
+	 * Provides `instanceof` support for testing if a value is a `TreeNode`.
+	 * @remarks
+	 * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.
+	 * @privateRemarks
+	 * Due to type-only export, this functionality is not available outside the package.
+	 */
+	public 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.
+	 */
+	public static [Symbol.hasInstance]<TSchema extends abstract new (...args: any[]) => TreeNode>(
+		this: TSchema,
+		value: unknown,
+	): value is InstanceType<TSchema>;
+
+	public static [Symbol.hasInstance](this: { prototype: object }, value: unknown): boolean {
+		const schema = tryGetSchema(value);
+
+		if (schema === undefined || schema.kind === NodeKind.Leaf) {
+			return false;
+		}
+
+		assert("prototype" in schema, "expected class based schema");
+		return inPrototypeChain(schema.prototype, this.prototype);
+	}
+
 	protected constructor() {
-		if (!(this instanceof TreeNodeValid)) {
+		if (!inPrototypeChain(Reflect.getPrototypeOf(this), TreeNodeValid.prototype)) {
 			throw new UsageError("TreeNodes must extend schema classes created by SchemaFactory");
 		}
 	}
 }
 
+/**
+ * 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: object | null, base: object): boolean {
+	let checking = derived;
+	while (checking !== null) {
+		if (base === checking) {
+			return true;
+		}
+		checking = Reflect.getPrototypeOf(checking);
+	}
+	return false;
+}
+
 /**
  * Class which all {@link TreeNode}s must extend.
  * Since this is not exported, it allows robust detection of attempts to create TreeNodes which do not go through SchemaFactory which is the only place which exposes classes that extend this.