@fluidframework/tree 2.4.0-297385 → 2.4.0-299374

package/src/shared-tree/schematizingTreeView.ts

@@ -41,6 +41,7 @@ import {
 	type TreeViewConfiguration,
 	mapTreeFromNodeData,
 	prepareContentForHydration,
+	comparePersistedSchemaInternal,
 	toStoredSchema,
 } from "../simple-tree/index.js";
 import { Breakable, breakingClass, disposeSymbol, type WithBreakable } from "../util/index.js";
@@ -225,22 +226,12 @@ export class SchematizingSimpleTreeView<in out TRootSchema extends ImplicitField
 	private update(): void {
 		this.disposeView();
 
-		const result = this.viewSchema.checkCompatibility(this.checkout.storedSchema);
-
-		// TODO: AB#8121: Weaken this check to support viewing under additional circumstances.
-		// In the near term, this should support viewing documents with additional optional fields in their schema on object types.
-		// Longer-term (as demand arises), we could also add APIs to constructing view schema to allow for more flexibility
-		// (e.g. out-of-schema content handlers could allow support for viewing docs which have extra allowed types in a particular field)
-		const canView =
-			result.write === Compatibility.Compatible && result.read === Compatibility.Compatible;
-		const canUpgrade = result.read === Compatibility.Compatible;
-		const isEquivalent = canView && canUpgrade;
-		const compatibility: SchemaCompatibilityStatus = {
-			canView,
-			canUpgrade,
-			isEquivalent,
-			canInitialize: canInitialize(this.checkout),
-		};
+		const compatibility = comparePersistedSchemaInternal(
+			this.checkout.storedSchema,
+			this.viewSchema,
+			canInitialize(this.checkout),
+		);
+
 		let lastRoot =
 			this.compatibility.canView && this.view !== undefined ? this.root : undefined;
 		this.currentCompatibility = compatibility;

package/src/shared-tree/sharedTree.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import type {
 	IChannelAttributes,
 	IChannelFactory,
@@ -16,11 +16,13 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { type ICodecOptions, noopValidator } from "../codec/index.js";
 import {
+	type IEditableForest,
 	type JsonableTree,
 	RevisionTagCodec,
 	type TaggedChange,
 	type TreeStoredSchema,
 	TreeStoredSchemaRepository,
+	type TreeStoredSchemaSubscription,
 	makeDetachedFieldIndex,
 	moveToDetachedField,
 } from "../core/index.js";
@@ -67,6 +69,7 @@ import {
 	createTreeCheckout,
 } from "./treeCheckout.js";
 import { breakingClass, throwIfBroken } from "../util/index.js";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 /**
  * Copy of data from an {@link ISharedTree} at some point in time.
@@ -150,6 +153,30 @@ function getCodecVersions(formatVersion: number): ExplicitCodecVersions {
 	return versions;
 }
 
+/**
+ * Build and return a forest of the requested type.
+ */
+export function buildConfiguredForest(
+	type: ForestType,
+	schema: TreeStoredSchemaSubscription,
+	idCompressor: IIdCompressor,
+): IEditableForest {
+	switch (type) {
+		case ForestType.Optimized:
+			return buildChunkedForest(
+				makeTreeChunker(schema, defaultSchemaPolicy),
+				undefined,
+				idCompressor,
+			);
+		case ForestType.Reference:
+			return buildForest();
+		case ForestType.Expensive:
+			return buildForest(undefined, true);
+		default:
+			unreachableCase(type);
+	}
+}
+
 /**
  * Shared tree, configured with a good set of indexes and field kinds which will maintain compatibility over time.
  *
@@ -182,16 +209,7 @@ export class SharedTree
 		const options = { ...defaultSharedTreeOptions, ...optionsParam };
 		const codecVersions = getCodecVersions(options.formatVersion);
 		const schema = new TreeStoredSchemaRepository();
-		const forest =
-			options.forest === ForestType.Optimized
-				? buildChunkedForest(
-						makeTreeChunker(schema, defaultSchemaPolicy),
-						undefined,
-						runtime.idCompressor,
-					)
-				: options.forest === ForestType.Reference
-					? buildForest()
-					: buildForest(undefined, true);
+		const forest = buildConfiguredForest(options.forest, schema, runtime.idCompressor);
 		const revisionTagCodec = new RevisionTagCodec(runtime.idCompressor);
 		const removedRoots = makeDetachedFieldIndex(
 			"repair",
@@ -350,7 +368,7 @@ export function getBranch(treeOrView: ITree | TreeView<ImplicitFieldSchema>): Tr
  * Format versions supported by SharedTree.
  *
  * Each version documents a required minimum version of the \@fluidframework/tree package.
- * @internal
+ * @alpha
  */
 export const SharedTreeFormatVersion = {
 	/**
@@ -376,26 +394,38 @@ export const SharedTreeFormatVersion = {
  * Format versions supported by SharedTree.
  *
  * Each version documents a required minimum version of the \@fluidframework/tree package.
- * @internal
+ * @alpha
  * @privateRemarks
  * See packages/dds/tree/docs/main/compatibility.md for information on how to add support for a new format.
+ *
+ * TODO: Before this gets promoted past Alpha,
+ * a separate abstraction more suited for use in the public API should be adopted rather than reusing the same types used internally.
+ * Such an abstraction should probably be in the form of a Fluid-Framework wide compatibility enum.
  */
 export type SharedTreeFormatVersion = typeof SharedTreeFormatVersion;
 
 /**
- * @internal
+ * Configuration options for SharedTree.
+ * @alpha
  */
 export type SharedTreeOptions = Partial<ICodecOptions> &
-	Partial<SharedTreeFormatOptions> & {
-		/**
-		 * The {@link ForestType} indicating which forest type should be created for the SharedTree.
-		 */
-		forest?: ForestType;
-	};
+	Partial<SharedTreeFormatOptions> &
+	ForestOptions;
+
+/**
+ * Configuration options for SharedTree's internal tree storage.
+ * @alpha
+ */
+export interface ForestOptions {
+	/**
+	 * The {@link ForestType} indicating which forest type should be created for the SharedTree.
+	 */
+	readonly forest?: ForestType;
+}
 
 /**
  * Options for configuring the persisted format SharedTree uses.
- * @internal
+ * @alpha
  */
 export interface SharedTreeFormatOptions {
 	/**
@@ -419,7 +449,7 @@ export interface SharedTreeFormatOptions {
 
 /**
  * Used to distinguish between different forest types.
- * @internal
+ * @alpha
  */
 export enum ForestType {
 	/**

package/src/shared-tree/treeApi.ts

@@ -78,7 +78,10 @@ export interface RunTransaction {
 	 * If the transaction function throws an error then the transaction will be automatically rolled back (discarding any changes made to the tree so far) before the error is propagated up from this function.
 	 * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.
 	 */
-	<TView extends TreeView<ImplicitFieldSchema>, TResult>(
+	// TODO: TreeView is invariant over the schema, so to accept any view, `any` is the only real option unless a non generic (or covariant) base type for view is introduced (which is planned).
+	// This use of any is actually type safe as it is only used as a constraint, and the actual strongly typed view (TView) is passed to the callback.
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	<TView extends TreeView<any>, TResult>(
 		tree: TView,
 		transaction: (root: TView["root"]) => TResult,
 	): TResult;
@@ -123,7 +126,9 @@ export interface RunTransaction {
 	 * If the transaction function throws an error then the transaction will be automatically rolled back (discarding any changes made to the tree so far) before the error is propagated up from this function.
 	 * If the transaction is rolled back (whether by an error or by returning the {@link RunTransaction.rollback} | rollback value), a corresponding change event will also be emitted for the rollback.
 	 */
-	<TView extends TreeView<ImplicitFieldSchema>, TResult>(
+	// See comment on previous overload about use of any here.
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	<TView extends TreeView<any>, TResult>(
 		tree: TView,
 		transaction: (root: TView["root"]) => TResult | typeof rollback,
 	): TResult | typeof rollback;
@@ -161,10 +166,9 @@ export interface RunTransaction {
 	 * If the transaction function throws an error then the transaction will be automatically rolled back (discarding any changes made to the tree so far) before the error is propagated up from this function.
 	 * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.
 	 */
-	<TView extends TreeView<ImplicitFieldSchema>>(
-		tree: TView,
-		transaction: (root: TView["root"]) => void,
-	): void;
+	// See comment on previous overload about use of any here.
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	<TView extends TreeView<any>>(tree: TView, transaction: (root: TView["root"]) => void): void;
 	/**
 	 * Apply one or more edits to the tree as a single atomic unit.
 	 * @param node - The node that will be passed to `transaction`.
@@ -211,7 +215,9 @@ export interface RunTransaction {
 	 * If the transaction function throws an error then the transaction will be automatically rolled back (discarding any changes made to the tree so far) before the error is propagated up from this function.
 	 * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.
 	 */
-	<TView extends TreeView<ImplicitFieldSchema>, TResult>(
+	// See comment on previous overload about use of any here.
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	<TView extends TreeView<any>, TResult>(
 		tree: TView,
 		transaction: (root: TView["root"]) => TResult,
 		preconditions?: readonly TransactionConstraint[],
@@ -264,7 +270,9 @@ export interface RunTransaction {
 	 * If the transaction function throws an error then the transaction will be automatically rolled back (discarding any changes made to the tree so far) before the error is propagated up from this function.
 	 * If the transaction is rolled back (whether by an error or by returning the {@link RunTransaction.rollback} | rollback value), a corresponding change event will also be emitted for the rollback.
 	 */
-	<TView extends TreeView<ImplicitFieldSchema>, TResult>(
+	// See comment on previous overload about use of any here.
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	<TView extends TreeView<any>, TResult>(
 		tree: TView,
 		transaction: (root: TView["root"]) => TResult | typeof rollback,
 		preconditions?: readonly TransactionConstraint[],
@@ -313,7 +321,9 @@ export interface RunTransaction {
 	 * If the transaction function throws an error then the transaction will be automatically rolled back (discarding any changes made to the tree so far) before the error is propagated up from this function.
 	 * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.
 	 */
-	<TView extends TreeView<ImplicitFieldSchema>>(
+	// See comment on previous overload about use of any here.
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	<TView extends TreeView<any>>(
 		tree: TView,
 		transaction: (root: TView["root"]) => void,
 		preconditions?: readonly TransactionConstraint[],

package/src/simple-tree/api/conciseTree.ts

@@ -0,0 +1,58 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IFluidHandle } from "@fluidframework/core-interfaces";
+
+import type { ITreeCursor } from "../../core/index.js";
+import type { TreeLeafValue, ImplicitAllowedTypes } from "../schemaTypes.js";
+import type { TreeNodeSchema } from "../core/index.js";
+import { customFromCursorInner, type EncodeOptions } from "./customTree.js";
+import { getUnhydratedContext } from "../createContext.js";
+
+/**
+ * Concise encoding of a {@link TreeNode} or {@link TreeLeafValue}.
+ * @remarks
+ * This is "concise" meaning that explicit type information is omitted.
+ * If the schema is compatible with {@link ITreeConfigurationOptions.preventAmbiguity},
+ * types will be lossless and compatible with {@link TreeBeta.create} (unless the options are used to customize it).
+ *
+ * Every {@link TreeNode} is an array or object.
+ * Any IFluidHandle values have been replaced by `THandle`.
+ * @privateRemarks
+ * This can store all possible simple trees,
+ * but it can not store all possible trees representable by our internal representations like FlexTree and JsonableTree.
+ */
+export type ConciseTree<THandle = IFluidHandle> =
+	| Exclude<TreeLeafValue, IFluidHandle>
+	| THandle
+	| ConciseTree<THandle>[]
+	| {
+			[key: string]: ConciseTree<THandle>;
+	  };
+
+/**
+ * Used to read a node cursor as a ConciseTree.
+ */
+export function conciseFromCursor<TCustom>(
+	reader: ITreeCursor,
+	rootSchema: ImplicitAllowedTypes,
+	options: EncodeOptions<TCustom>,
+): ConciseTree<TCustom> {
+	const config: Required<EncodeOptions<TCustom>> = {
+		useStoredKeys: false,
+		...options,
+	};
+
+	const schemaMap = getUnhydratedContext(rootSchema).schema;
+	return conciseFromCursorInner(reader, config, schemaMap);
+}
+
+function conciseFromCursorInner<TCustom>(
+	reader: ITreeCursor,
+	options: Required<EncodeOptions<TCustom>>,
+	schema: ReadonlyMap<string, TreeNodeSchema>,
+): ConciseTree<TCustom> {
+	return customFromCursorInner(reader, options, schema, conciseFromCursorInner);
+}

package/src/simple-tree/api/customTree.ts

@@ -0,0 +1,119 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IFluidHandle } from "@fluidframework/core-interfaces";
+import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
+
+import {
+	EmptyKey,
+	forEachField,
+	inCursorField,
+	mapCursorField,
+	type ITreeCursor,
+} from "../../core/index.js";
+import { fail } from "../../util/index.js";
+import type { TreeLeafValue } from "../schemaTypes.js";
+import { NodeKind, type TreeNodeSchema } from "../core/index.js";
+import {
+	booleanSchema,
+	handleSchema,
+	nullSchema,
+	numberSchema,
+	stringSchema,
+} from "../leafNodeSchema.js";
+import { isObjectNodeSchema } from "../objectNodeTypes.js";
+
+/**
+ * Options for how to encode a tree.
+ */
+export interface EncodeOptions<TCustom> {
+	/**
+	 * How to encode any {@link @fluidframework/core-interfaces#IFluidHandle|IFluidHandles} in the tree.
+	 * @remarks
+	 * See note on {@link ParseOptions.valueConverter}.
+	 */
+	valueConverter(data: IFluidHandle): TCustom;
+	/**
+	 * If true, interpret the input keys of object nodes as stored keys.
+	 * If false, interpret them as property keys.
+	 * @defaultValue false.
+	 */
+	readonly useStoredKeys?: boolean;
+}
+
+/**
+ * Tree representation with fields as properties and customized handle and child representations.
+ */
+export type CustomTree<TChild, THandle> = CustomTreeNode<TChild> | CustomTreeValue<THandle>;
+
+/**
+ * TreeLeafValue except the handle type is customized.
+ */
+export type CustomTreeValue<THandle> = Exclude<TreeLeafValue, IFluidHandle> | THandle;
+
+/**
+ * Tree node representation with fields as properties and customized child representation.
+ */
+export type CustomTreeNode<TChild> = TChild[] | { [key: string]: TChild };
+
+/**
+ * Builds an {@link CustomTree} from a cursor in Nodes mode.
+ */
+export function customFromCursorInner<TChild, THandle>(
+	reader: ITreeCursor,
+	options: Required<EncodeOptions<THandle>>,
+	schema: ReadonlyMap<string, TreeNodeSchema>,
+	childHandler: (
+		reader: ITreeCursor,
+		options: Required<EncodeOptions<THandle>>,
+		schema: ReadonlyMap<string, TreeNodeSchema>,
+	) => TChild,
+): CustomTree<TChild, THandle> {
+	const type = reader.type;
+	const nodeSchema = schema.get(type) ?? fail("missing schema for type in cursor");
+
+	switch (type) {
+		case numberSchema.identifier:
+		case booleanSchema.identifier:
+		case nullSchema.identifier:
+		case stringSchema.identifier:
+			assert(reader.value !== undefined, "out of schema: missing value");
+			assert(!isFluidHandle(reader.value), "out of schema: unexpected FluidHandle");
+			return reader.value;
+		case handleSchema.identifier:
+			assert(reader.value !== undefined, "out of schema: missing value");
+			assert(isFluidHandle(reader.value), "out of schema: expected FluidHandle");
+			return options.valueConverter(reader.value);
+		default: {
+			assert(reader.value === undefined, "out of schema: unexpected value");
+			if (nodeSchema.kind === NodeKind.Array) {
+				const fields = inCursorField(reader, EmptyKey, () =>
+					mapCursorField(reader, () => childHandler(reader, options, schema)),
+				);
+				return fields;
+			} else {
+				const fields: Record<string, TChild> = {};
+				forEachField(reader, () => {
+					const children = mapCursorField(reader, () => childHandler(reader, options, schema));
+					if (children.length === 1) {
+						const storedKey = reader.getFieldKey();
+						const key =
+							isObjectNodeSchema(nodeSchema) && !options.useStoredKeys
+								? nodeSchema.storedKeyToPropertyKey.get(storedKey) ??
+									fail("missing property key")
+								: storedKey;
+						// Length is checked above.
+						// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+						fields[key] = children[0]!;
+					} else {
+						assert(children.length === 0, 0xa19 /* invalid children number */);
+					}
+				});
+				return fields;
+			}
+		}
+	}
+}

package/src/simple-tree/api/index.ts

@@ -12,6 +12,7 @@ export {
 	type ITreeViewConfiguration,
 	type SchemaCompatibilityStatus,
 	type ITreeConfigurationOptions,
+	type TreeViewAlpha,
 } from "./tree.js";
 export { SchemaFactory, type ScopedSchemaName } from "./schemaFactory.js";
 export type {
@@ -23,7 +24,6 @@ export {
 	enumFromStrings,
 	singletonSchema,
 	typedObjectValues,
-	type EmptyObject,
 } from "./schemaCreationUtilities.js";
 export { treeNodeApi, type TreeNodeApi } from "./treeNodeApi.js";
 export { createFromInsertable, cursorFromInsertable } from "./create.js";
@@ -46,9 +46,47 @@ export {
 export { getJsonSchema } from "./getJsonSchema.js";
 export { getSimpleSchema } from "./getSimpleSchema.js";
 export { ViewSchema } from "./view.js";
+export type {
+	Unenforced,
+	FieldHasDefaultUnsafe,
+	ObjectFromSchemaRecordUnsafe,
+	TreeObjectNodeUnsafe,
+	TreeFieldFromImplicitFieldUnsafe,
+	TreeNodeFromImplicitAllowedTypesUnsafe,
+	FieldSchemaUnsafe,
+	InsertableTreeNodeFromImplicitAllowedTypesUnsafe,
+	TreeArrayNodeUnsafe,
+	TreeMapNodeUnsafe,
+	InsertableObjectFromSchemaRecordUnsafe,
+	InsertableTreeFieldFromImplicitFieldUnsafe,
+	InsertableTypedNodeUnsafe,
+	NodeBuilderDataUnsafe,
+	NodeFromSchemaUnsafe,
+	ReadonlyMapInlined,
+	TreeNodeSchemaClassUnsafe,
+	TreeNodeSchemaUnsafe,
+	AllowedTypesUnsafe,
+	TreeNodeSchemaNonClassUnsafe,
+} from "./typesUnsafe.js";
+
+export type {
+	VerboseTreeNode,
+	ParseOptions,
+	VerboseTree,
+} from "./verboseTree.js";
+
+export type { EncodeOptions } from "./customTree.js";
+
+export type { ConciseTree } from "./conciseTree.js";
 
 export { TreeBeta, type NodeChangedData, type TreeChangeEventsBeta } from "./treeApiBeta.js";
 
+export {
+	extractPersistedSchema,
+	comparePersistedSchemaInternal,
+	comparePersistedSchema,
+} from "./storedSchema.js";
+
 // Exporting the schema (RecursiveObject) to test that recursive types are working correctly.
 // These are `@internal` so they can't be included in the `InternalClassTreeTypes` due to https://github.com/microsoft/rushstack/issues/3639
 export {

package/src/simple-tree/api/schemaCreationUtilities.ts

@@ -9,27 +9,29 @@ import { fail } from "../../util/index.js";
 
 import type { SchemaFactory, ScopedSchemaName } from "./schemaFactory.js";
 import type { NodeFromSchema } from "../schemaTypes.js";
-import type { NodeKind, TreeNodeSchemaClass, TreeNode } from "../core/index.js";
 import type {
-	InsertableObjectFromSchemaRecord,
-	ObjectFromSchemaRecord,
-} from "../objectNode.js";
-
-/**
- * Empty Object for use in type computations that should contribute no fields when `&`ed with another type.
- * @internal
+	InternalTreeNode,
+	NodeKind,
+	TreeNode,
+	TreeNodeSchemaClass,
+} from "../core/index.js";
+
+/*
+ * This file does two things:
+ *
+ * 1. Provides tools for making schema for cases like enums.
+ *
+ * 2. Demonstrates the kinds of schema utilities apps can write.
+ * Nothing in here needs access to package internal APIs.
  */
-// Using {} instead of interface {} or Record<string, never> for empty object here produces better IntelliSense in the generated types than `Record<string, never>` recommended by the linter.
-// Making this a type instead of an interface prevents it from showing up in IntelliSense, and also avoids breaking the typing somehow.
-// eslint-disable-next-line @typescript-eslint/ban-types, @typescript-eslint/consistent-type-definitions
-export type EmptyObject = {};
 
 /**
  * Create a schema for a node with no state.
  * @remarks
  * This is commonly used in unions when the only information needed is which kind of node the value is.
  * Enums are a common example of this pattern.
- * @internal
+ * @see {@link adaptEnum}
+ * @alpha
  */
 // Return type is intentionally derived.
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
@@ -38,7 +40,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
 	name: TName,
 ) {
 	class SingletonSchema extends factory.object(name, {}) {
-		public constructor(data?: EmptyObject) {
+		public constructor(data?: InternalTreeNode) {
 			super(data ?? {});
 		}
 		public get value(): TName {
@@ -46,9 +48,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
 		}
 	}
 
-	type NodeType = object &
-		TreeNode &
-		ObjectFromSchemaRecord<EmptyObject> & { readonly value: TName };
+	type NodeType = TreeNode & { readonly value: TName };
 
 	// Returning SingletonSchema without a type conversion results in TypeScript generating something like `readonly "__#124291@#brand": unknown;`
 	// for the private brand field of TreeNode.
@@ -59,7 +59,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
 		ScopedSchemaName<TScope, TName>,
 		NodeKind.Object,
 		NodeType,
-		object & InsertableObjectFromSchemaRecord<EmptyObject>,
+		never,
 		true
 	> &
 		(new () => NodeType) = SingletonSchema;
@@ -71,33 +71,50 @@ export function singletonSchema<TScope extends string, TName extends string | nu
  * Converts an enum into a collection of schema which can be used in a union.
  * @remarks
  * Currently only supports `string` enums.
+ * The string value of the enum is used as the name of the schema: callers must ensure that it is stable and unique.
+ * Consider making a dedicated schema factory with a nested scope to avoid the enum members colliding with other schema.
  * @example
  * ```typescript
+ * const schemaFactory = new SchemaFactory("com.myApp");
+ * // An enum for use in the tree. Must have string keys.
  * enum Mode {
  * 	a = "A",
  * 	b = "B",
  * }
- * const ModeNodes = adaptEnum(schema, Mode);
+ * // Define the schema for each member of the enum using a nested scope to group them together.
+ * const ModeNodes = adaptEnum(new SchemaFactory(`${schemaFactory.scope}.Mode`), Mode);
+ * // Defined the types of the nodes which correspond to this the schema.
  * type ModeNodes = NodeFromSchema<(typeof ModeNodes)[keyof typeof ModeNodes]>;
- * const nodeFromString: ModeNodes = ModeNodes(Mode.a);
- * const nodeFromSchema: ModeNodes = new ModeNodes.a();
- * const nameFromNode: Mode = nodeFromSchema.value;
+ * // An example schema which has an enum as a child.
  * class Parent extends schemaFactory.object("Parent", {
+ * 	// typedObjectValues extracts a list of all the fields of ModeNodes, which are the schema for each enum member.
+ * 	// This means any member of the enum is allowed in this field.
  * 	mode: typedObjectValues(ModeNodes),
  * }) {}
+ *
+ * // Example usage of enum-based nodes, showing what type to use and that `.value` can be used to read out the enum value.
+ * function getValue(node: ModeNodes): Mode {
+ * 	return node.value;
+ * }
+ *
+ * // Example constructing a tree containing an enum node from an enum value.
+ * // The syntax `new ModeNodes.a()` is also supported.
+ * function setValue(node: Parent): void {
+ * 	node.mode = ModeNodes(Mode.a);
+ * }
  * ```
  * @privateRemarks
  * TODO:
- * Extends this to support numeric enums.
- * Maybe require an explicit nested scope to group them under, or at least a warning about collisions.
- * Maybe just provide `SchemaFactory.nested` to east creating nested scopes?
- * @internal
+ * Extend this to support numeric enums.
+ * Maybe provide `SchemaFactory.nested` to ease creating nested scopes?
+ * @see {@link enumFromStrings} for a similar function that works on arrays of strings instead of an enum.
+ * @alpha
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-export function adaptEnum<TScope extends string, const TEnum extends Record<string, string>>(
-	factory: SchemaFactory<TScope>,
-	members: TEnum,
-) {
+export function adaptEnum<
+	TScope extends string,
+	const TEnum extends Record<string, string | number>,
+>(factory: SchemaFactory<TScope>, members: TEnum) {
 	type Values = TEnum[keyof TEnum];
 	const values = Object.values(members) as Values[];
 	const inverse = new Map(Object.entries(members).map(([key, value]) => [value, key])) as Map<
@@ -116,7 +133,7 @@ export function adaptEnum<TScope extends string, const TEnum extends Record<stri
 	};
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	const factoryOut = <TValue extends Values>(value: TValue) => {
-		return new out[inverse.get(value) ?? fail("missing enum value")]({}) as NodeFromSchema<
+		return new out[inverse.get(value) ?? fail("missing enum value")]() as NodeFromSchema<
 			ReturnType<typeof singletonSchema<TScope, TValue>>
 		>;
 	};
@@ -135,7 +152,9 @@ export function adaptEnum<TScope extends string, const TEnum extends Record<stri
 
 /**
  * `Object.values`, but with more specific types.
- * @internal
+ * @remarks
+ * Useful with collections of schema, like those returned by {@link adaptEnum} or {@link enumFromStrings}.
+ * @alpha
  */
 export function typedObjectValues<TKey extends string, TValues>(
 	object: Record<TKey, TValues>,
@@ -160,7 +179,8 @@ export function typedObjectValues<TKey extends string, TValues>(
  *
  * class Parent extends schemaFactory.object("Parent", { mode: typedObjectValues(Mode) }) {}
  * ```
- * @internal
+ * @see {@link adaptEnum} for a similar function that works on enums instead of arrays of strings.
+ * @alpha
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 export function enumFromStrings<TScope extends string, const Members extends string>(
@@ -175,7 +195,7 @@ export function enumFromStrings<TScope extends string, const Members extends str
 	type TOut = Record<Members, ReturnType<typeof singletonSchema<TScope, Members>>>;
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	const factoryOut = <TValue extends Members>(value: TValue) => {
-		return new out[value]({}) as NodeFromSchema<
+		return new out[value]() as NodeFromSchema<
 			ReturnType<typeof singletonSchema<TScope, TValue>>
 		>;
 	};
@@ -192,8 +212,7 @@ export function enumFromStrings<TScope extends string, const Members extends str
 	return out;
 }
 
-// TODO: Why does this one generate an invalid d.ts file if exported?
-// Tracked by https://github.com/microsoft/TypeScript/issues/58688
+// TODO: This generates an invalid d.ts file if exported due to a bug https://github.com/microsoft/TypeScript/issues/58688.
 // TODO: replace enumFromStrings above with this simpler implementation when the TypeScript bug is resolved.
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 function _enumFromStrings2<TScope extends string, const Members extends readonly string[]>(