@fluidframework/tree 2.1.0 → 2.2.0

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

@@ -3,232 +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 TreeNodeSchemaClass,
-	type WithType,
-	typeNameSymbol,
-} from "./schemaTypes.js";
+	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 { getFlexNode, createKernel, 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 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 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.
@@ -332,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) {
@@ -361,8 +159,8 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 		);
 
 		const result = schema.prepareInstance(this, node);
-		createKernel(result);
-		setFlexNode(result, node);
+		new TreeNodeKernel(result, schema);
+		setInnerNode(result, node);
 		return result;
 	}
 }
@@ -385,22 +183,6 @@ export interface MostDerivedData {
 	oneTimeInitialized: 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 function toFlexTreeNode(node: InternalTreeNode): FlexTreeNode {
-	assert(isFlexTreeNode(node), 0x963 /* Invalid InternalTreeNode */);
-	return node;
-}
-
 // #region NodeJS custom inspect for TreeNodes.
 
 /**
@@ -423,7 +205,9 @@ function inspectNodeFunction(
 ): 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(getFlexNode(this).schema) as TreeNodeSchemaClass;
+	const schema = tryGetSimpleNodeSchema(
+		getOrCreateInnerNode(this).schema,
+	) as TreeNodeSchemaClass;
 	const title = `${schema.name}: ${NodeKind[schema.kind]} Node (${schema.identifier})`;
 
 	if (depth < 2) {

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,

package/src/util/brandedMap.ts

@@ -13,12 +13,10 @@ import { getOrCreate } from "./utils.js";
  * @remarks
  * Due to the `TContent` type parameter being invariant (which it has to be since keys are used to both read and write data),
  * generic collections end up needing to constrain their key's `TContent` to `any`.
- * @internal
  */
 export type BrandedKey<TKey, TContent> = TKey & Invariant<TContent>;
 
 /**
- * @internal
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type BrandedKeyContent<TKey extends BrandedKey<unknown, any>> = TKey extends BrandedKey<
@@ -41,8 +39,6 @@ export type BrandedKeyContent<TKey extends BrandedKey<unknown, any>> = TKey exte
  *
  * @remarks
  * These APIs are designed so that a Map can be used to implement this type.
- *
- * @internal
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface BrandedMapSubset<K extends BrandedKey<unknown, any>> {
@@ -74,7 +70,6 @@ let slotCounter = 0;
 
 /**
  * Define a strongly typed slot in which data can be stored in a {@link BrandedMapSubset}.
- * @internal
  */
 export function brandedSlot<
 	// See note on BrandedKey.

package/src/util/idAllocator.ts

@@ -9,7 +9,6 @@ import { fail } from "./utils.js";
 
 /**
  * Used for allocating IDs unique to a particular instance of the allocator.
- * @internal
  */
 export interface IdAllocator<TId = number> {
 	/**
@@ -28,7 +27,6 @@ export interface IdAllocationState {
 }
 
 /**
- * @internal
  */
 export function idAllocatorFromMaxId(maxId: number | undefined = undefined): IdAllocator {
 	return idAllocatorFromState({ maxId: maxId ?? -1 });

package/src/util/index.ts

@@ -20,6 +20,7 @@ export {
 export {
 	deleteFromNestedMap,
 	getOrAddInMap,
+	getOrAddInMapLazy,
 	getOrAddInNestedMap,
 	getOrDefaultInNestedMap,
 	forEachInNestedMap,
@@ -88,6 +89,7 @@ export {
 	transformObjectMap,
 	compareStrings,
 	find,
+	count,
 } from "./utils.js";
 export { ReferenceCountedBase, type ReferenceCounted } from "./referenceCounting.js";