@fluidframework/tree 2.113.1 → 2.115.0

package/src/shared-tree-core/messageCodecs.ts

@@ -35,6 +35,14 @@ export interface MessageEncodingContext {
 	schema?: SchemaAndPolicy;
 }
 
+/**
+ * Context required for decoding a message. Unlike {@link MessageEncodingContext}, no schema is
+ * needed: message decoding is schema-agnostic.
+ */
+export interface MessageDecodingContext {
+	idCompressor: IIdCompressor;
+}
+
 /**
  * Codec name used to identify the message codec, see {@link makeMessageCodecBuilder}.
  */
@@ -65,14 +73,16 @@ export function makeMessageCodecBuilder<TChangeset>(): VersionDispatchingCodecBu
 	DecodedMessage<TChangeset>,
 	MessageEncodingContext,
 	MessageFormatVersion | undefined,
-	typeof messageCodecName
+	typeof messageCodecName,
+	MessageDecodingContext
 > {
 	// See MessageFormatVersion and its members for documentation on what changed in each version.
 	const versions: CodecVersion<
 		DecodedMessage<TChangeset>,
 		MessageEncodingContext,
 		MessageFormatVersion | undefined,
-		MessageCodecBuilderOptions<TChangeset>
+		MessageCodecBuilderOptions<TChangeset>,
+		MessageDecodingContext
 	>[] = [
 		// The "undefined" wire format (no version field) is discontinued.
 		makeDiscontinuedCodecAndSchema(undefined, "2.73.0"),

package/src/shared-tree-core/sharedTreeCore.ts

@@ -95,12 +95,19 @@ export interface EnrichmentConfig<TChange> {
  * Generic shared tree, which needs to be configured with indexes, field kinds and other configuration.
  */
 @breakingClass
-export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
+export class SharedTreeCore<
+		TEditor extends ChangeFamilyEditor,
+		TChange,
+		TChangeProcessingContext,
+	>
 	extends VersionedSummarizer<SharedTreeSummaryFormatVersion>
 	implements WithBreakable, Summarizable
 {
-	private readonly editManager: EditManager<TEditor, TChange, ChangeFamily<TEditor, TChange>>;
-	private readonly summarizables: readonly [EditManagerSummarizer<TChange>, ...Summarizable[]];
+	private readonly editManager: EditManager<TEditor, TChange, TChangeProcessingContext>;
+	private readonly summarizables: readonly [
+		EditManagerSummarizer<TChange, TChangeProcessingContext>,
+		...Summarizable[],
+	];
 	/**
 	 * The sequence number that this instance is at.
 	 * This number is artificial in that it is made up by this instance as opposed to being provided by the runtime.
@@ -147,7 +154,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		public readonly submitLocalMessage: (content: unknown, localOpMetadata?: unknown) => void,
 		logger: ITelemetryBaseLogger | undefined,
 		summarizables: readonly Summarizable[],
-		protected readonly changeFamily: ChangeFamily<TEditor, TChange>,
+		protected readonly changeFamily: ChangeFamily<TEditor, TChange, TChangeProcessingContext>,
 		options: SharedTreeCoreOptionsInternal,
 		changeFormatVersionForEditManager: DependentFormatVersion<EditManagerFormatVersion>,
 		changeFormatVersionForMessage: DependentFormatVersion<MessageFormatVersion>,
@@ -207,7 +214,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 				options.minVersionForCollab,
 				this.schemaAndPolicy,
 				options.healUnresolvableIdentifiersOnDecode === true
-					? { sharedObjectId: sharedObject.id }
+					? { sharedObjectId: sharedObject.id, logger }
 					: undefined,
 			),
 			...summarizables,
@@ -519,7 +526,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		}
 	}
 
-	public getLocalBranch(): SharedTreeBranch<TEditor, TChange> {
+	public getLocalBranch(): SharedTreeBranch<TEditor, TChange, TChangeProcessingContext> {
 		return this.editManager.getLocalBranch("main");
 	}
 
@@ -545,7 +552,9 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		this.editManager.addNewBranch(branchId, branchName);
 	}
 
-	public getSharedBranch(branchId: BranchId): SharedTreeBranch<TEditor, TChange> {
+	public getSharedBranch(
+		branchId: BranchId,
+	): SharedTreeBranch<TEditor, TChange, TChangeProcessingContext> {
 		return this.editManager.getLocalBranch(branchId);
 	}
 

package/src/shared-tree-core/transaction.ts

@@ -17,6 +17,7 @@ import {
 	tagChange,
 	type ChangeFamilyEditor,
 	type GraphCommit,
+	type ProcessChangeFn,
 	type RevisionTag,
 } from "../core/index.js";
 import { getLast, getOrCreate } from "../util/index.js";
@@ -263,7 +264,7 @@ export enum ChangeProcessorApplicability {
  * (see the conversion helpers in the `shared-tree` layer) so that its internal
  * change representation does not leak into the public API.
  */
-export interface ChangeProcessor<TChange> {
+export interface ChangeProcessor<TChange, TChangeProcessingContext> {
 	/**
 	 * Informs what context it should be invoked for.
 	 */
@@ -271,13 +272,13 @@ export interface ChangeProcessor<TChange> {
 	/**
 	 * Processes the given change, returning a change with the same observable effect.
 	 */
-	readonly processChange: (change: TChange) => TChange;
+	readonly processChange: ProcessChangeFn<TChange, TChangeProcessingContext>;
 }
 
 /**
  * Options for {@link Transactor.start | starting} a transaction.
  */
-export interface SquashingTransactionOptions<TChange> {
+export interface SquashingTransactionOptions<TChange, TChangeProcessingContext> {
 	/**
 	 * An optional {@link ChangeProcessor} applied to the squashed change produced when a transaction that was started
 	 * with this option is committed.
@@ -288,7 +289,7 @@ export interface SquashingTransactionOptions<TChange> {
 	 * How often the processor is invoked across nested transactions is governed by its
 	 * {@link ChangeProcessor.applicability | applicability}.
 	 */
-	readonly postProcessor?: ChangeProcessor<TChange>;
+	readonly postProcessor?: ChangeProcessor<TChange, TChangeProcessingContext>;
 }
 
 /**
@@ -300,8 +301,9 @@ export interface SquashingTransactionOptions<TChange> {
 export class SquashingTransactionStack<
 	TEditor extends ChangeFamilyEditor,
 	TChange,
-> extends TransactionStack<SquashingTransactionOptions<TChange>> {
-	#transactionBranch?: SharedTreeBranch<TEditor, TChange>;
+	TChangeProcessingContext,
+> extends TransactionStack<SquashingTransactionOptions<TChange, TChangeProcessingContext>> {
+	#transactionBranch?: SharedTreeBranch<TEditor, TChange, TChangeProcessingContext>;
 
 	/**
 	 * An editor for whichever branch is currently the {@link SquashingTransactionStack.activeBranch | active branch}.
@@ -317,7 +319,7 @@ export class SquashingTransactionStack<
 	/**
 	 * Get the "active branch" for this transactor - either the transaction branch if a transaction is in progress, or the original branch otherwise.
 	 */
-	public get activeBranch(): SharedTreeBranch<TEditor, TChange> {
+	public get activeBranch(): SharedTreeBranch<TEditor, TChange, TChangeProcessingContext> {
 		return this.#transactionBranch ?? this.branch;
 	}
 
@@ -326,10 +328,16 @@ export class SquashingTransactionStack<
 	 * @remarks When the active branch changes, the listeners for these events will automatically be transferred to the new active branch.
 	 * In contrast, binding an event to the {@link SquashingTransactionStack.activeBranch | active branch} directly will not automatically transfer the listener when the active branch changes.
 	 */
-	public get activeBranchEvents(): Listenable<SharedTreeBranchEvents<TEditor, TChange>> {
+	public get activeBranchEvents(): Listenable<
+		SharedTreeBranchEvents<TEditor, TChange, TChangeProcessingContext>
+	> {
 		const off = (
-			eventName: keyof SharedTreeBranchEvents<TEditor, TChange>,
-			listener: SharedTreeBranchEvents<TEditor, TChange>[typeof eventName],
+			eventName: keyof SharedTreeBranchEvents<TEditor, TChange, TChangeProcessingContext>,
+			listener: SharedTreeBranchEvents<
+				TEditor,
+				TChange,
+				TChangeProcessingContext
+			>[typeof eventName],
 		): void => {
 			this.activeBranch.events.off(eventName, listener);
 			const listeners = this.#activeBranchEvents.get(eventName);
@@ -349,9 +357,13 @@ export class SquashingTransactionStack<
 		};
 	}
 	readonly #activeBranchEvents = new Map<
-		keyof SharedTreeBranchEvents<TEditor, TChange>,
+		keyof SharedTreeBranchEvents<TEditor, TChange, TChangeProcessingContext>,
 		Set<
-			SharedTreeBranchEvents<TEditor, TChange>[keyof SharedTreeBranchEvents<TEditor, TChange>]
+			SharedTreeBranchEvents<
+				TEditor,
+				TChange,
+				TChangeProcessingContext
+			>[keyof SharedTreeBranchEvents<TEditor, TChange, TChangeProcessingContext>]
 		>
 	>();
 
@@ -365,20 +377,23 @@ export class SquashingTransactionStack<
 	 * options rather than baked into this stack, so different transactions may supply different post-processors (or none).
 	 */
 	public constructor(
-		public readonly branch: SharedTreeBranch<TEditor, TChange>,
+		public readonly branch: SharedTreeBranch<TEditor, TChange, TChangeProcessingContext>,
 		mintRevisionTag: () => RevisionTag,
 		onPush?: () => OnPopWithViewUpdate<TChange> | void,
 	) {
 		// A stack of the post-processors to apply when each in-progress transaction commits, ordered from outermost to
 		// innermost. Each in-progress transaction contributes exactly one entry: either the processor to apply when it
 		// commits, or `undefined` when none should be applied.
-		const postProcessorStack: (ChangeProcessor<TChange> | undefined)[] = [];
+		const postProcessorStack: (
+			| ChangeProcessor<TChange, TChangeProcessingContext>
+			| undefined
+		)[] = [];
 		// Determines the entry to push for a transaction that was started with the given `requested` processor (if any).
 		// A processor with "outermost" applicability that is already active in an enclosing transaction resolves to
 		// `undefined` so that it is only applied once (at the outermost transaction that supplied it).
 		const resolvePostProcessor = (
-			requested: ChangeProcessor<TChange> | undefined,
-		): ChangeProcessor<TChange> | undefined => {
+			requested: ChangeProcessor<TChange, TChangeProcessingContext> | undefined,
+		): ChangeProcessor<TChange, TChangeProcessingContext> | undefined => {
 			if (
 				requested?.applicability === ChangeProcessorApplicability.IfOutermost &&
 				postProcessorStack.includes(requested)
@@ -391,12 +406,13 @@ export class SquashingTransactionStack<
 		super(
 			// Invoked when an outer transaction starts
 			(
-				startOptions?: SquashingTransactionOptions<TChange>,
-			): Callbacks<SquashingTransactionOptions<TChange>> => {
+				startOptions?: SquashingTransactionOptions<TChange, TChangeProcessingContext>,
+			): Callbacks<SquashingTransactionOptions<TChange, TChangeProcessingContext>> => {
 				postProcessorStack.push(resolvePostProcessor(startOptions?.postProcessor));
 				// Keep track of the commit that each transaction was on when it started
 				const startHead = this.activeBranch.getHead();
-				const rebaser = this.branch.changeFamily.rebaser;
+				const changeFamily = this.branch.changeFamily;
+				const rebaser = changeFamily.rebaser;
 				const outerOnPop = onPush?.();
 				let transactionRevision: RevisionTag | undefined;
 				const transactionBranch = this.branch.fork(
@@ -462,7 +478,9 @@ export class SquashingTransactionStack<
 								// Apply this transaction's post-processor (if any) to the squashed change (for example, to
 								// "minimize" it so that it contains no extraneous information).
 								const change =
-									postProcessor === undefined ? squash : postProcessor.processChange(squash);
+									postProcessor === undefined
+										? squash
+										: changeFamily.buildProcessor(postProcessor.processChange)(squash);
 
 								if (change !== squash) {
 									// The post-processor produced a change that differs from the
@@ -524,9 +542,9 @@ export class SquashingTransactionStack<
 					outerOnPop?.(result, viewUpdate);
 				};
 				// Invoked when a nested transaction begins
-				const onNestedTransactionPush: OnPush<SquashingTransactionOptions<TChange>> = (
-					nestedStartOptions,
-				) => {
+				const onNestedTransactionPush: OnPush<
+					SquashingTransactionOptions<TChange, TChangeProcessingContext>
+				> = (nestedStartOptions) => {
 					postProcessorStack.push(resolvePostProcessor(nestedStartOptions?.postProcessor));
 					const nestedStartHead = this.activeBranch.getHead();
 					const nestedOuterOnPop = onPush?.();
@@ -558,7 +576,9 @@ export class SquashingTransactionStack<
 												0xd07 /* Expected transaction revision in the presence of transaction steps */,
 											);
 											const squash = rebaser.compose(nestedSteps);
-											const processedSquash = nestedPostProcessor.processChange(squash);
+											const processedSquash = changeFamily.buildProcessor(
+												nestedPostProcessor.processChange,
+											)(squash);
 											// Roll back the transaction branch to the nested start head and apply the
 											// processed change if it differs from the original change.
 											if (processedSquash !== squash) {
@@ -586,7 +606,9 @@ export class SquashingTransactionStack<
 
 	/** Updates the transaction branch (and therefore the active branch) and rebinds the branch events. */
 	private setTransactionBranch(
-		transactionBranch: SharedTreeBranch<TEditor, TChange> | undefined,
+		transactionBranch:
+			| SharedTreeBranch<TEditor, TChange, TChangeProcessingContext>
+			| undefined,
 	): void {
 		const oldActiveBranch = this.activeBranch;
 		this.#transactionBranch = transactionBranch;

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

@@ -103,6 +103,21 @@ export function eraseSchemaDetails<TNode, ExtraSchemaProperties = unknown>(): <
  * const square = Square.create(10);
  * assert.equal(square.area, 100);
  * ```
+ * @remarks
+ * Care must be taken to avoid subclass members colliding with internal members of the schema.
+ * This is mainly a problem when using the output from {@link eraseSchemaDetailsSubclassable} to type a class returned to third party code which can subclass it.
+ * This pattern mainly occurs when writing generic schema factory functions which generate a schema from some parameters and return it to third party code which can subclass it.
+ *
+ * For example if the schema has a field or method named `size` (from a field, like in the `Square` example, or otherwise),
+ * then a subclass should not define a member named `size` as it will collide with the internal field.
+ *
+ * In practice, this risk can be mitigated by doing one of:
+ * 1. Using JavaScript private properties
+ * 2. Use non exported symbols for the properties
+ * 3. Use a naming convention for internal properties which you document the subclasses must not use.
+ * 4. Documenting the specific internal properties keys as not to be used by subclasses.
+ * 5. Subclass the returned class and declaring uninitialized readonly private properties to protect them (`private readonly size!: unknown;`).
+ * 6. Include the properties in `TNode` or `ExtraSchemaProperties`. This can use readonly erased types (like unknown) if desired.
  * @privateRemarks
  * See "example" test for an executable version of this example.
  * @alpha

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

@@ -67,7 +67,6 @@ export {
 	createCustomizedFluidFrameworkScopedFactory,
 } from "./schemaCreationUtilities.js";
 export {
-	deltaMarksToArrayOps,
 	getIdentifierFromNode,
 	getPropertyKeyFromStoredKey,
 	getStoredKey,

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

@@ -16,7 +16,7 @@ import {
 	type FieldSchema,
 	type FieldSchemaAlpha,
 } from "../fieldSchema.js";
-import type { LeafSchema } from "../leafNodeSchema.js";
+import type { LeafSchema, StringSchema } from "../leafNodeSchema.js";
 import {
 	stringSchema,
 	numberSchema,
@@ -252,7 +252,7 @@ export const schemaStatics = {
 		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
 	): FieldSchemaAlpha<
 		FieldKind.Identifier,
-		typeof stringSchema,
+		StringSchema,
 		TCustomMetadata,
 		FieldPropsAlpha<TCustomMetadata>
 	> => {

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

@@ -25,6 +25,7 @@ import {
 	type ImplicitAllowedTypes,
 	type TreeNodeFromImplicitAllowedTypes,
 	normalizeAllowedTypes,
+	type TreeNodeKernel,
 } from "../core/index.js";
 import { type ImplicitFieldSchema, FieldSchema } from "../fieldSchema.js";
 import { tryGetTreeNodeForField } from "../getTreeNodeForField.js";
@@ -115,6 +116,10 @@ export interface ArrayNodeRemoveOp {
  * `"remove"` and the destination array's delta contains an `"insert"` — they cannot be
  * correlated without additional bookkeeping on the caller's side.
  *
+ * The operations cover the complete array: trailing elements that were not changed are included
+ * in a final `"retain"` op. Applying every operation therefore consumes the entire pre-edit array
+ * and produces the entire post-edit array.
+ *
  * @sealed @alpha
  */
 export type ArrayNodeDeltaOp = ArrayNodeRetainOp | ArrayNodeInsertOp | ArrayNodeRemoveOp;
@@ -296,7 +301,13 @@ export const treeNodeApi: TreeNodeApi = {
 						// unavailable rather than receiving stale marks from only the first batch.
 						// TODO: Once the eventing stack is rewritten to walk the composed delta at
 						// flush time, `marks` will always be defined. Remove the `undefined` fallback.
-						const delta = marks === undefined ? undefined : deltaMarksToArrayOps(marks);
+						const delta =
+							marks === undefined
+								? undefined
+								: deltaMarksToArrayOpsWithRetain(marks, getArrayLength(kernel), (count) => ({
+										type: "retain",
+										count,
+									}));
 						listener({ delta });
 					});
 				} else {
@@ -314,7 +325,17 @@ export const treeNodeApi: TreeNodeApi = {
 					return kernel.events.on("childrenChangedAfterBatch", ({ fieldMarks }) => {
 						const marks = fieldMarks.get(EmptyKey);
 						const delta =
-							marks === undefined ? undefined : deltaMarksToArrayOpsForTreeChanged(marks);
+							marks === undefined
+								? undefined
+								: deltaMarksToArrayOpsWithRetain(
+										marks,
+										getArrayLength(kernel),
+										(count, subtreeChanged) => ({
+											type: "retain",
+											count,
+											subtreeChanged,
+										}),
+									);
 						(listener as (data: { readonly delta: typeof delta }) => void)({ delta });
 					});
 				}
@@ -351,73 +372,68 @@ export const treeNodeApi: TreeNodeApi = {
 };
 
 /**
- * Converts an array of internal {@link DeltaMark}s for a sequence field into sequential
- * array delta ops suitable for inclusion in {@link NodeChangedDataDelta.delta}.
+ * Converts internal {@link DeltaMark}s for an array's sequence field into sequential array delta
+ * operations.
+ *
+ * @remarks
+ * Each mark describes a contiguous run:
+ * - A mark with only `count` becomes a retain.
+ * - A mark with only `attach` becomes an insert.
+ * - A mark with only `detach` becomes a remove.
+ * - A mark with both `attach` and `detach` becomes a remove followed by an insert.
  *
- * Each mark in the delta describes a contiguous run of positions in the original array:
- * - A mark with only `count` (no attach/detach) → `"retain"` with no subtree information
- * - A mark with only `attach` → `"insert"` (new elements added)
- * - A mark with only `detach` → `"remove"` (elements removed)
- * - A mark with both `attach` and `detach` → `"remove"` + `"insert"`
+ * Internal mark arrays may omit an unchanged suffix. The returned operations always cover the
+ * complete array, so this function uses the array's post-edit length to append a trailing retain
+ * when needed.
  *
  * @param marks - The low-level delta marks for the array's sequence field.
+ * @param postEditLength - The array's length after the edit.
+ * @param buildRetainOp - Builds a retain operation. Its second argument indicates whether the
+ * retained element's subtree changed; it is `false` for a synthesized trailing retain.
  *
  * @privateRemarks
  * The case where both `attach` and `detach` are set is unreachable today: the sequence-field
- * encoder never emits such marks for array (EmptyKey) fields. It is handled defensively.
+ * encoder never emits such marks for array (`EmptyKey`) fields. It is handled defensively.
  */
-export function deltaMarksToArrayOps(marks: readonly DeltaMark[]): ArrayNodeDeltaOp[] {
-	const ops: ArrayNodeDeltaOp[] = [];
+export function deltaMarksToArrayOpsWithRetain<TRetain extends ArrayNodeRetainOp>(
+	marks: readonly DeltaMark[],
+	postEditLength: number,
+	buildRetainOp: (count: number, subtreeChanged: boolean) => TRetain,
+): (TRetain | ArrayNodeInsertOp | ArrayNodeRemoveOp)[] {
+	const ops: (TRetain | ArrayNodeInsertOp | ArrayNodeRemoveOp)[] = [];
+	let processedLength = 0;
 	for (const mark of marks) {
 		if (mark.detach !== undefined) {
 			ops.push({ type: "remove", count: mark.count });
 		}
 		if (mark.attach !== undefined) {
 			ops.push({ type: "insert", count: mark.count });
+			processedLength += mark.count;
 		} else if (mark.detach === undefined) {
-			// Retain: elements were not added or removed.
-			ops.push({ type: "retain", count: mark.count });
+			// When `fields` is set, `count` is guaranteed to be 1 (DeltaMark invariant).
+			ops.push(buildRetainOp(mark.count, mark.fields !== undefined));
+			processedLength += mark.count;
 		}
 	}
+	// DeltaMark arrays are allowed to omit the trailing retain, while our user facing array equivalents are not, so add it if necessary.
+	assert(
+		processedLength <= postEditLength,
+		0xd19 /* Array delta exceeds post-edit array length */,
+	);
+	if (processedLength < postEditLength) {
+		ops.push(buildRetainOp(postEditLength - processedLength, false));
+	}
 	return ops;
 }
 
 /**
- * Converts an array of internal {@link DeltaMark}s for a sequence field into sequential
- * {@link ArrayNodeTreeChangedDeltaOp}s suitable for inclusion in
- * {@link NodeChangedDataTreeDelta.delta} (delivered to {@link TreeChangeEventsAlpha.treeChanged}).
- *
- * Same conversion rules as {@link deltaMarksToArrayOps}, but retain ops additionally carry a
- * {@link ArrayNodeTreeChangedRetainOp.subtreeChanged} flag derived from whether the mark has
- * a `fields` property (indicating a descendant changed).
- *
- * @param marks - The low-level delta marks for the array's sequence field.
- *
- * @privateRemarks
- * The case where both `attach` and `detach` are set is unreachable today: the sequence-field
- * encoder never emits such marks for array (EmptyKey) fields. It is handled defensively.
+ * Returns the length of the `EmptyKey` field under the provided node kernel.
+ * @remarks
+ * Use this with the kernel of an array node to get the current length of the array.
+ * This is the same as `.length` on the array node, but is usable without having to get (and possible create) the node and narrow to the proper type to access that.
  */
-export function deltaMarksToArrayOpsForTreeChanged(
-	marks: readonly DeltaMark[],
-): ArrayNodeTreeChangedDeltaOp[] {
-	const ops: ArrayNodeTreeChangedDeltaOp[] = [];
-	for (const mark of marks) {
-		if (mark.detach !== undefined) {
-			ops.push({ type: "remove", count: mark.count });
-		}
-		if (mark.attach !== undefined) {
-			ops.push({ type: "insert", count: mark.count });
-		} else if (mark.detach === undefined) {
-			// Retain: elements were not added or removed (but may have deep changes).
-			// When `fields` is set, `count` is guaranteed to be 1 (DeltaMark invariant).
-			ops.push({
-				type: "retain",
-				count: mark.count,
-				subtreeChanged: mark.fields !== undefined,
-			});
-		}
-	}
-	return ops;
+function getArrayLength(arrayNodeKernel: TreeNodeKernel): number {
+	return arrayNodeKernel.getInnerNode().getBoxed(EmptyKey).length;
 }
 
 /**

package/src/simple-tree/core/treeNode.ts

@@ -9,8 +9,12 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { markEager } from "./flexList.js";
 import { tryGetTreeNodeSchema } from "./treeNodeKernel.js";
 import { NodeKind, type TreeNodeSchemaClass } from "./treeNodeSchema.js";
-// eslint-disable-next-line import-x/no-deprecated
-import { type WithType, typeNameSymbol, type typeSchemaSymbol } from "./withType.js";
+import type {
+	WithType,
+	// eslint-disable-next-line import-x/no-deprecated -- Required to implement the deprecated typeNameSymbol API.
+	typeNameSymbol,
+	typeSchemaSymbol,
+} from "./withType.js";
 
 /**
  * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
@@ -72,22 +76,21 @@ export abstract class TreeNode implements WithType {
 	 * 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.
 	 */
-	// eslint-disable-next-line no-unused-private-class-members
+	// eslint-disable-next-line no-unused-private-class-members -- Exists for type checking sideeffect. See private remarks above.
 	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.
+	 * Adds a schema identifier brand for stronger and more efficient type checking.
+	 * @privateRemarks Subclasses provide more specific values to distinguish otherwise type-compatible nodes.
 	 * @deprecated Use {@link typeSchemaSymbol} instead.
 	 */
-	// eslint-disable-next-line import-x/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated -- Required to implement the deprecated typeNameSymbol API.
 	public abstract get [typeNameSymbol](): string;
 
 	/**
-	 * Adds a type symbol for stronger typing.
+	 * {@inheritDoc typeSchemaSymbol}
 	 * @privateRemarks
-	 * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.
+	 * Subclasses provide more specific values for this to get strong typing of otherwise type compatible nodes.
 	 */
 	public abstract get [typeSchemaSymbol](): TreeNodeSchemaClass;
 
@@ -152,7 +155,7 @@ export const privateToken = {};
  * @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
+// eslint-disable-next-line @rushstack/no-new-null -- getPrototypeOf uses null.
 export function inPrototypeChain(derived: object | null, base: object): boolean {
 	let checking = derived;
 	while (checking !== null) {

package/src/simple-tree/core/withType.ts

@@ -11,17 +11,14 @@ import type { TreeNode } from "./treeNode.js";
 import type { NodeKind, TreeNodeSchemaClass } from "./treeNodeSchema.js";
 
 /**
- * The type of a {@link TreeNode}.
+ * An internal brand to improve compiler performance.
  * 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.
+ * The identifier of a {@link TreeNode}'s schema.
+ * This allows the type checker to distinguish different node types more efficiently than via {@link typeSchemaSymbol}.
+ * @deprecated External code should use `Tree.schema(theNode)` for schema related runtime data access. For type narrowing, use {@link WithType} instead of the symbols directly.
  * @system @public
  */
 export const typeNameSymbol: unique symbol = Symbol("TreeNode Type");
@@ -97,6 +94,13 @@ export const contentSchemaSymbol: unique symbol = Symbol("SharedTree Schema");
  * 	}
  * }
  * ```
+ * @privateRemarks
+ * The properties of this are implemented as getters rather than instance properties as that is the easiest way to make them non-enumerable,
+ * and also saves memory and time as they only have to be setup on the prototype.
+ * These being non-enumerable inherited properties minimizes impact on users,
+ * hiding them from things like `Reflect.ownKeys`, Object spread, `Object.getOwnPropertyDescriptors`, and `for...in` loops.
+ * How we declare them here actually doesn't impact that,
+ * but is a good way to communicate to users and internal devs that these should be implemented as inherited getters to accomplish the above.
  * @sealed @public
  */
 export interface WithType<
@@ -106,6 +110,15 @@ export interface WithType<
 > {
 	/**
 	 * Type symbol, marking a type in a way to increase type safety via strong type checking.
+	 *
+	 * Use `Tree.schema(theNode)` for schema related runtime data access. For type narrowing, use `WithType` instead of the symbols directly.
+	 * @remarks
+	 * This should be redundant with {@link typeSchemaSymbol}, but is kept for improved compiler performance.
+	 * If we just rely on {@link typeSchemaSymbol}, the compiler has to work much harder to distinguish schema in unions,
+	 * which can cause large schema unions to hit "error TS2859: Excessive complexity comparing types".
+	 *
+	 * This property is not intended for any use other than helping the compiler distinguish schema types,
+	 * and should not be referenced in any code other than internal to the tree package.
 	 * @deprecated Use {@link typeSchemaSymbol} instead.
 	 */
 	get [typeNameSymbol](): TName;

package/src/simple-tree/index.ts

@@ -100,7 +100,6 @@ export {
 	type ArrayNodeRetainOp,
 	type ArrayNodeTreeChangedDeltaOp,
 	type ArrayNodeTreeChangedRetainOp,
-	deltaMarksToArrayOps,
 	type NodeChangedData,
 	type NodeChangedDataAlpha,
 	type NodeChangedDataDelta,
@@ -328,6 +327,6 @@ export {
 	handleSchema,
 	nullSchema,
 } from "./leafNodeSchema.js";
-export type { LeafSchema } from "./leafNodeSchema.js";
+export type { LeafSchema, StringSchema } from "./leafNodeSchema.js";
 export { getUnhydratedContext } from "./createContext.js";
 export { type TreeSchema, createTreeSchema } from "./treeSchema.js";

package/src/simple-tree/leafNodeSchema.ts

@@ -125,7 +125,12 @@ export interface LeafSchema<Name extends string, T extends TreeLeafValue>
 	> {}
 
 // Leaf schema shared between all SchemaFactory instances.
-export const stringSchema = makeLeaf("string", ValueSchema.String);
+/**
+ * A {@link LeafSchema} for a `string`.
+ * @system @sealed @alpha
+ */
+export type StringSchema = LeafSchema<"string", string> & SimpleLeafNodeSchema;
+export const stringSchema: StringSchema = makeLeaf("string", ValueSchema.String);
 export const numberSchema = makeLeaf("number", ValueSchema.Number);
 export const booleanSchema = makeLeaf("boolean", ValueSchema.Boolean);
 export const nullSchema = makeLeaf("null", ValueSchema.Null);