@fluidframework/tree 2.1.0-281041 → 2.2.0

package/src/simple-tree/{types.ts → treeNodeValid.ts}

@@ -3,156 +3,30 @@
  * Licensed under the MIT License.
  */
 
-import type { ErasedType } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 
 import {
-	NodeKind,
 	type TreeNodeSchema,
-	type WithType,
-	typeNameSymbol,
-} from "./schemaTypes.js";
+	type TreeNodeSchemaClass,
+	NodeKind,
+	tryGetSimpleNodeSchema,
+	isTreeNode,
+	TreeNodeKernel,
+	privateToken,
+	TreeNode,
+	type InternalTreeNode,
+} from "./core/index.js";
 import {
 	type FlexTreeNode,
 	type MapTreeNode,
 	isFlexTreeNode,
 	markEager,
 } from "../feature-libraries/index.js";
-import { tryGetSimpleNodeSchema } from "./schemaCaching.js";
-import { isTreeNode } from "./proxies.js";
 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.
- *
- * 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 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 abstract class TreeNode implements WithType {
-	/**
-	 * 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.
-	 */
-	readonly #brand!: unknown;
 
-	/**
-	 * Adds a type symbol for stronger typing.
-	 * @privateRemarks
-	 * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.
-	 */
-	public abstract get [typeNameSymbol](): 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, 0x98a /* expected class based schema */);
-		return inPrototypeChain(schema.prototype, this.prototype);
-	}
-
-	protected constructor() {
-		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;
-}
+import { getFlexSchema } from "./toFlexSchema.js";
+import { getOrCreateInnerNode, setInnerNode } from "./proxyBinding.js";
 
 /**
  * Class which all {@link TreeNode}s must extend.
@@ -239,7 +113,7 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 			schemaBase.constructorCached = { constructor: this, oneTimeInitialized: false };
 			assert(
 				this.constructorCached === schemaBase.constructorCached,
-				"Inheritance should work",
+				0x9b5 /* Inheritance should work */,
 			);
 			return this.constructorCached;
 		} else if (this.constructorCached.constructor === this) {
@@ -256,7 +130,7 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 	}
 
 	public constructor(input: TInput | InternalTreeNode) {
-		super();
+		super(privateToken);
 		const schema = this.constructor as typeof TreeNodeValid & TreeNodeSchema;
 		const cache = schema.markMostDerived();
 		if (!cache.oneTimeInitialized) {
@@ -285,7 +159,8 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 		);
 
 		const result = schema.prepareInstance(this, node);
-		setFlexNode(result, node);
+		new TreeNodeKernel(result, schema);
+		setInnerNode(result, node);
 		return result;
 	}
 }
@@ -308,18 +183,158 @@ export interface MostDerivedData {
 	oneTimeInitialized: boolean;
 }
 
+// #region NodeJS custom inspect for TreeNodes.
+
 /**
- * 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
+ * Used to customize "inspect" behavior in NodeJS.
+ * See https://nodejs.org/api/util.html#utilinspectcustom for details.
+ *
+ * VS-Code's debugger also uses this to inspect objects,
+ * see https://github.com/microsoft/vscode-js-debug/blob/64df2686c92bac402909dee5c3c389bbb7a81f6d/src/adapter/templates/getStringyProps.ts#L11 for details.
+ */
+const customInspectSymbol = Symbol.for("nodejs.util.inspect.custom");
+
+/**
+ * Node inspecting function for use with {@link customInspectSymbol}.
+ */
+function inspectNodeFunction(
+	this: TreeNodeValid<unknown>,
+	depth: number,
+	options?: unknown,
+	inspect?: unknown,
+): unknown {
+	// TODO: replicated from tryGetSchema to avoid cycle.
+	// This case could be optimized, for example by placing the simple schema in a symbol on tree nodes.
+	const schema = tryGetSimpleNodeSchema(
+		getOrCreateInnerNode(this).schema,
+	) as TreeNodeSchemaClass;
+	const title = `${schema.name}: ${NodeKind[schema.kind]} Node (${schema.identifier})`;
+
+	if (depth < 2) {
+		const short = shortContent(this);
+		if (short !== undefined) {
+			return `${title} ${short}`;
+		}
+		return title;
+	}
+	const content = `${title} ${JSON.stringify(this)}`;
+	return content;
+}
+
+/**
+ * If the node has no items, a short JSON string for it.
+ */
+function shortContent(node: TreeNodeValid<unknown>): string | undefined {
+	if (Object.values(node).length === 0) {
+		return JSON.stringify(node);
+	}
+	return undefined;
+}
+
+/**
+ * Add inherited non-enumerable symbol for NodeJS inspection to all nodes.
+ *
+ * See {@link customInspectSymbol}.
  */
-export interface InternalTreeNode
-	extends ErasedType<"@fluidframework/tree.InternalTreeNode"> {}
+Object.defineProperty(TreeNodeValid.prototype, customInspectSymbol, {
+	value: inspectNodeFunction,
+	enumerable: false,
+});
 
-export function toFlexTreeNode(node: InternalTreeNode): FlexTreeNode {
-	assert(isFlexTreeNode(node), 0x963 /* Invalid InternalTreeNode */);
-	return node;
+// #endregion
+
+// #region Browser custom debug format for TreeNodes
+
+// This section has side-effects, so including it in this file ensures its loaded whenever TreeNodes could exist.
+// Supported in at least Chrome and FireFox, more details at https://firefox-source-docs.mozilla.org/devtools-user/custom_formatters/index.html
+// For this to work the browser's dev tools generally have to "Enable custom formatters".
+
+// This formatter is inspired by https://github.com/andrewdavey/immutable-devtools/blob/master/src/createFormatters.js which provides a similar formatter for the immutable.js library.
+
+const globals = typeof window === "undefined" ? globalThis : window;
+const formatters = ((
+	globals as { devtoolsFormatters?: DevtoolsFormatter.DevtoolsFormatter[] }
+).devtoolsFormatters ??= []);
+
+const nodeFormatter: DevtoolsFormatter.DevtoolsFormatter = {
+	header(object, config) {
+		if (isTreeNode(object)) {
+			return ["span", `${inspectNodeFunction.call(object, 1)}`];
+		}
+		return null;
+	},
+	body(object, config): DevtoolsFormatter.Item {
+		const children: DevtoolsFormatter.Item[] = [];
+		for (const [key, value] of Object.entries(object as TreeNode)) {
+			children.push(["li", ["span", `${key}: `], formattedReference(value)]);
+		}
+
+		// TODO:
+		// for array nodes, this isn't great since (at least in FireFox) the list items show up with a prefixed number starting from 1.
+		// This looks messy when followed by the array index.
+		// Find a way to hide the list index.
+		// { style: 'list-style-type: none` } did not seem to work.
+
+		return ["ol", ...children];
+	},
+	hasBody(object, config) {
+		return shortContent(object as TreeNodeValid<undefined>) === undefined;
+	},
+};
+
+function formattedReference(
+	object: unknown,
+	config?: DevtoolsFormatter.ObjectConfig,
+): DevtoolsFormatter.Item {
+	if (typeof object === "undefined") {
+		return ["span", "undefined"];
+	} else if (object === "null") {
+		return ["span", "null"];
+	}
+
+	return ["object", { object, config }];
+}
+
+formatters.push(nodeFormatter);
+
+// #endregion
+
+// These types are based on https://github.com/BenjaminAster/Better-TypeScript/blob/main/types/devtools-formatters.d.ts
+// however the original package causes multiple compile errors due to some of its other types it used, so the relevant part has been extracted and adjusted to better match our conventions.
+declare namespace DevtoolsFormatter {
+	type ObjectConfig = Record<string | symbol, unknown>;
+
+	type ElementTagName = "div" | "span" | "ol" | "li" | "table" | "tr" | "td";
+
+	type ElementTemplate = StyledElementTemplate | UnstyledElementTemplate;
+
+	type StyledElementTemplate = readonly [
+		ElementTagName,
+		{
+			style?: string;
+		},
+		...Item[],
+	];
+
+	type UnstyledElementTemplate = readonly [ElementTagName, ...Item[]];
+
+	type ObjectReference = readonly [
+		"object",
+		{
+			object: unknown;
+			config?: ObjectConfig;
+		},
+	];
+
+	type Item = string | ElementTemplate | ObjectReference;
+
+	interface DevtoolsFormatter {
+		header(
+			object?: unknown,
+			config?: ObjectConfig,
+			// eslint-disable-next-line @rushstack/no-new-null
+		): Item | null;
+		hasBody(object?: unknown, config?: ObjectConfig): boolean;
+		body(object?: unknown, config?: ObjectConfig): Item;
+	}
 }

package/src/simple-tree/typesUnsafe.ts

@@ -14,13 +14,16 @@ import type {
 	ImplicitAllowedTypes,
 	ImplicitFieldSchema,
 	NodeFromSchema,
-	NodeKind,
 	TreeNodeFromImplicitAllowedTypes,
+} from "./schemaTypes.js";
+import type {
+	NodeKind,
 	TreeNodeSchema,
 	WithType,
-} from "./schemaTypes.js";
+	TreeNode,
+	Unhydrated,
+} from "./core/index.js";
 import type { TreeArrayNodeBase, TreeArrayNode } from "./arrayNode.js";
-import type { TreeNode, Unhydrated } from "./types.js";
 
 /*
  * TODO:
@@ -55,7 +58,7 @@ export type ObjectFromSchemaRecordUnsafe<
 export type TreeObjectNodeUnsafe<
 	T extends Unenforced<RestrictiveReadonlyRecord<string, ImplicitFieldSchema>>,
 	TypeName extends string = string,
-> = TreeNode & ObjectFromSchemaRecordUnsafe<T> & WithType<TypeName>;
+> = TreeNode & ObjectFromSchemaRecordUnsafe<T> & WithType<TypeName, NodeKind.Object>;
 
 /**
  * {@link Unenforced} version of {@link TreeFieldFromImplicitField}.
@@ -147,7 +150,7 @@ export interface TreeArrayNodeUnsafe<TAllowedTypes extends Unenforced<ImplicitAl
  * @sealed @public
  */
 export interface TreeMapNodeUnsafe<T extends Unenforced<ImplicitAllowedTypes>>
-	extends ReadonlyMap<string, TreeNodeFromImplicitAllowedTypesUnsafe<T>>,
+	extends ReadonlyMapInlined<string, T>,
 		TreeNode {
 	/**
 	 * {@inheritdoc TreeMapNode.set}
@@ -163,6 +166,49 @@ export interface TreeMapNodeUnsafe<T extends Unenforced<ImplicitAllowedTypes>>
 	delete(key: string): void;
 }
 
+/**
+ * Copy of TypeScript's ReadonlyMap, but with `TreeNodeFromImplicitAllowedTypesUnsafe<T>` inlined into it.
+ * Using this instead of ReadonlyMap in TreeMapNodeUnsafe is necessary to make recursive map schema not generate compile errors in the d.ts files when exported.
+ * @remarks
+ * Do note use this type directly: its only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @privateRemarks
+ * This is the same as `ReadonlyMap<K, TreeNodeFromImplicitAllowedTypesUnsafe<T>>` (Checked in test),
+ * except that it avoids the above mentioned compile error.
+ * Authored by manually inlining ReadonlyMap from from the TypeScript lib which can be found by navigating to the definition of `ReadonlyMap`.
+ * @system @sealed @public
+ */
+export interface ReadonlyMapInlined<K, T extends Unenforced<ImplicitAllowedTypes>> {
+	/** Returns an iterable of entries in the map. */
+	[Symbol.iterator](): IterableIterator<[K, TreeNodeFromImplicitAllowedTypesUnsafe<T>]>;
+
+	/**
+	 * Returns an iterable of key, value pairs for every entry in the map.
+	 */
+	entries(): IterableIterator<[K, TreeNodeFromImplicitAllowedTypesUnsafe<T>]>;
+
+	/**
+	 * Returns an iterable of keys in the map
+	 */
+	keys(): IterableIterator<K>;
+
+	/**
+	 * Returns an iterable of values in the map
+	 */
+	values(): IterableIterator<TreeNodeFromImplicitAllowedTypesUnsafe<T>>;
+
+	forEach(
+		callbackfn: (
+			value: TreeNodeFromImplicitAllowedTypesUnsafe<T>,
+			key: K,
+			map: ReadonlyMap<K, TreeNodeFromImplicitAllowedTypesUnsafe<T>>,
+		) => void,
+		thisArg?: any,
+	): void;
+	get(key: K): TreeNodeFromImplicitAllowedTypesUnsafe<T> | undefined;
+	has(key: K): boolean;
+	readonly size: number;
+}
+
 /**
  * {@link Unenforced} version of `FieldHasDefault`.
  * @remarks

package/src/simple-tree/viewSchemaToSimpleSchema.ts

@@ -0,0 +1,209 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import {
+	normalizeFieldSchema,
+	type FieldSchema,
+	type ImplicitAllowedTypes,
+} from "./schemaTypes.js";
+import type {
+	SimpleArrayNodeSchema,
+	SimpleFieldSchema,
+	SimpleLeafNodeSchema,
+	SimpleMapNodeSchema,
+	SimpleNodeSchema,
+	SimpleObjectNodeSchema,
+	SimpleTreeSchema,
+} from "./simpleSchema.js";
+import type { ValueSchema } from "../core/index.js";
+import { getOrCreate } from "../util/index.js";
+import { isObjectNodeSchema, type ObjectNodeSchema } from "./objectNodeTypes.js";
+import { NodeKind, type TreeNodeSchema } from "./core/index.js";
+
+/**
+ * Converts a "view" schema to a "simple" schema representation.
+ */
+export function toSimpleTreeSchema(schema: ImplicitAllowedTypes): SimpleTreeSchema {
+	const normalizedSchema = normalizeFieldSchema(schema);
+
+	const allowedTypes = allowedTypesFromFieldSchema(normalizedSchema);
+
+	const definitions = new Map<string, SimpleNodeSchema>();
+	populateSchemaDefinitionsForField(normalizedSchema, definitions);
+
+	return {
+		allowedTypes,
+		definitions,
+	};
+}
+
+/**
+ * Cache in which the results of {@link toSimpleNodeSchema} are saved.
+ */
+const simpleNodeSchemaCache = new WeakMap<TreeNodeSchema, SimpleNodeSchema>();
+
+/**
+ * Creates a {@link SimpleNodeSchema} from a {@link TreeNodeSchema}.
+ *
+ * @remarks Caches the result on the input schema for future calls.
+ */
+function toSimpleNodeSchema(schema: TreeNodeSchema): SimpleNodeSchema {
+	return getOrCreate(simpleNodeSchemaCache, schema, () => {
+		const kind = schema.kind;
+		switch (kind) {
+			case NodeKind.Leaf: {
+				return leafSchemaToSimpleSchema(schema);
+			}
+			case NodeKind.Map: {
+				return mapSchemaToSimpleSchema(schema);
+			}
+			case NodeKind.Array: {
+				return arraySchemaToSimpleSchema(schema);
+			}
+			case NodeKind.Object: {
+				assert(isObjectNodeSchema(schema), 0xa06 /* Expected object schema */);
+				return objectSchemaToSimpleSchema(schema);
+			}
+			default: {
+				unreachableCase(kind);
+			}
+		}
+	});
+}
+
+// TODO: Use a stronger type for leaf schemas once one is available (see object schema handler for an example).
+function leafSchemaToSimpleSchema(schema: TreeNodeSchema): SimpleLeafNodeSchema {
+	return {
+		kind: NodeKind.Leaf,
+		leafKind: schema.info as ValueSchema,
+	};
+}
+
+// TODO: Use a stronger type for array schemas once one is available (see object schema handler for an example).
+function arraySchemaToSimpleSchema(schema: TreeNodeSchema): SimpleArrayNodeSchema {
+	const fieldSchema = normalizeFieldSchema(schema.info as ImplicitAllowedTypes);
+	const allowedTypes = allowedTypesFromFieldSchema(fieldSchema);
+	return {
+		kind: NodeKind.Array,
+		allowedTypes,
+	};
+}
+
+// TODO: Use a stronger type for map schemas once one is available (see object schema handler for an example).
+function mapSchemaToSimpleSchema(schema: TreeNodeSchema): SimpleMapNodeSchema {
+	const fieldSchema = normalizeFieldSchema(schema.info as ImplicitAllowedTypes);
+	const allowedTypes = allowedTypesFromFieldSchema(fieldSchema);
+	return {
+		kind: NodeKind.Map,
+		allowedTypes,
+	};
+}
+
+function objectSchemaToSimpleSchema(schema: ObjectNodeSchema): SimpleObjectNodeSchema {
+	const fields: Record<string, SimpleFieldSchema> = {};
+	for (const [key, field] of schema.fields) {
+		fields[key] = fieldSchemaToSimpleSchema(field);
+	}
+	return {
+		kind: NodeKind.Object,
+		fields,
+	};
+}
+
+/**
+ * Private symbol under which the results of {@link toSimpleNodeSchema} are cached on an input {@link TreeNodeSchema}.
+ */
+const simpleFieldSchemaCacheSymbol = Symbol("simpleFieldSchemaCache");
+
+function fieldSchemaToSimpleSchema(schema: FieldSchema): SimpleFieldSchema {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((schema as any)[simpleFieldSchemaCacheSymbol] !== undefined) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		return (schema as any)[simpleFieldSchemaCacheSymbol] as SimpleFieldSchema;
+	}
+
+	const allowedTypes = allowedTypesFromFieldSchema(schema);
+	const result = {
+		kind: schema.kind,
+		allowedTypes,
+	};
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	(schema as any)[simpleFieldSchemaCacheSymbol] = result;
+
+	return result;
+}
+
+function allowedTypesFromFieldSchema(schema: FieldSchema): Set<string> {
+	const allowedTypes = new Set<string>();
+	for (const type of schema.allowedTypeSet) {
+		allowedTypes.add(type.identifier);
+	}
+	return allowedTypes;
+}
+
+/**
+ * Recursively populates `definitions` by walking the input field schema tree.
+ */
+function populateSchemaDefinitionsForField(
+	schema: FieldSchema,
+	definitions: Map<string, SimpleNodeSchema>,
+): void {
+	for (const child of schema.allowedTypeSet) {
+		populateSchemaDefinitionsForNode(child, definitions);
+	}
+}
+
+/**
+ * Recursively populates `definitions` by walking the input node schema tree.
+ */
+function populateSchemaDefinitionsForNode(
+	schema: TreeNodeSchema,
+	definitions: Map<string, SimpleNodeSchema>,
+): void {
+	if (definitions.has(schema.identifier)) {
+		// If the definition has already been populated, no need to recurse.
+		return;
+	}
+
+	// Populate definition for this schema
+	definitions.set(schema.identifier, toSimpleNodeSchema(schema));
+
+	// Recurse into children to populate definitions for them
+	const kind = schema.kind;
+	switch (kind) {
+		case NodeKind.Leaf: {
+			// Leaf node, so no need to recurse
+			break;
+		}
+		case NodeKind.Map: {
+			// TODO: Utilize a map schema type-guard once one exists (see object case for an example).
+
+			// Recursively populate definitions for allowed map children
+			const fieldSchema = normalizeFieldSchema(schema.info as ImplicitAllowedTypes);
+			populateSchemaDefinitionsForField(fieldSchema, definitions);
+			break;
+		}
+		case NodeKind.Array: {
+			// TODO: Utilize an array schema type-guard once one exists (see object case for an example).
+
+			// Recursively populate definitions for allowed map children
+			const fieldSchema = normalizeFieldSchema(schema.info as ImplicitAllowedTypes);
+			populateSchemaDefinitionsForField(fieldSchema, definitions);
+			break;
+		}
+		case NodeKind.Object: {
+			assert(isObjectNodeSchema(schema), 0xa07 /* Expected object schema */);
+			for (const [, field] of schema.fields) {
+				populateSchemaDefinitionsForField(field, definitions);
+			}
+			break;
+		}
+		default: {
+			unreachableCase(kind);
+		}
+	}
+}

package/src/util/brand.ts

@@ -69,7 +69,7 @@ export abstract class BrandedType<out ValueType, Name> {
 	 */
 	public static [Symbol.hasInstance](value: never): value is never {
 		throw new UsageError(
-			"BrandedType is a compile time type brand not a real class that can be used with `instancof` at runtime.",
+			"BrandedType is a compile time type brand not a real class that can be used with `instanceof` at runtime.",
 		);
 	}
 }
@@ -77,7 +77,6 @@ export abstract class BrandedType<out ValueType, Name> {
 /**
  * Implementation detail of type branding. Should not be used directly outside this file,
  * but shows up as part of branded types so API-Extractor requires it to be exported.
- * @internal
  */
 export type ValueFromBranded<T extends BrandedType<unknown, unknown>> = T extends BrandedType<
 	infer ValueType,
@@ -89,7 +88,6 @@ export type ValueFromBranded<T extends BrandedType<unknown, unknown>> = T extend
 /**
  * Implementation detail of type branding. Should not be used directly outside this file,
  * but shows up as part of branded types so API-Extractor requires it to be exported.
- * @internal
  */
 export type NameFromBranded<T extends BrandedType<unknown, unknown>> = T extends BrandedType<
 	unknown,
@@ -109,7 +107,6 @@ export type NameFromBranded<T extends BrandedType<unknown, unknown>> = T extends
  * For example leaving T unconstrained instead allows the union of `BrandedType | undefined` to distribute over the conditional allowing the branding only the the union members which should be branded.
  * This does not permit branding an optional value into an optional field since non branded union members are still excluded from input to this function:
  * this is an intended restriction as it causes compile errors for misuse of this function (like using brand when the relevant type is not a branded type).
- * @internal
  */
 export function brand<T>(
 	value: T extends BrandedType<infer ValueType, unknown> ? ValueType : never,