@fluidframework/tree 2.114.0 → 2.115.0

package/src/index.ts

@@ -12,6 +12,8 @@ export {
 	CommitKind,
 	RevertibleStatus,
 	type CommitMetadata,
+	CommitOutcome,
+	type LocalCommitEvents,
 	type LocalChangeMetadata,
 	type RemoteChangeMetadata,
 	type ChangeMetadata,
@@ -300,6 +302,7 @@ export {
 	type HandleConverter,
 	allowUnused,
 	type LeafSchema,
+	type StringSchema,
 	type ArrayNodeCustomizableSchema,
 	type ArrayNodeCustomizableSchemaAlpha,
 	type ArrayNodePojoEmulationSchema,
@@ -404,7 +407,7 @@ import * as InternalTypes from "./internalTypes.js";
 export { InternalTypes };
 
 // Internal/System types:
-// These would be put in `internalTypes` except doing so tents to cause errors like:
+// These would be put in `internalTypes` except doing so tends to cause errors like:
 // The inferred type of 'NodeMap' cannot be named without a reference to '../../node_modules/@fluidframework/tree/lib/internalTypes.js'. This is likely not portable. A type annotation is necessary.
 export type { MapNodeInsertableData } from "./simple-tree/index.js";
 
@@ -414,9 +417,9 @@ export { TableSchema, type System_TableSchema } from "./tableSchema.js";
 export { asAlpha, asBeta } from "./api.js";
 
 export {
-	TextAsTree,
-	FormattedTextAsTree,
-	FormattedTextAsTreeDefault,
+	PlainText,
+	FormattedText,
+	FormattedTextDefault,
 	codePointCount,
 	utf16LengthForCodePoints,
 } from "./text/index.js";

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.114.0";
+export const pkgVersion = "2.115.0";

package/src/shared-tree/sharedTree.ts

@@ -252,7 +252,7 @@ export class SharedTreeKernel
 			idCompressor,
 			healing:
 				options.healUnresolvableIdentifiersOnDecode === true
-					? { sharedObjectId: sharedObject.id }
+					? { sharedObjectId: sharedObject.id, logger }
 					: undefined,
 		});
 		const forestSummarizer = new ForestSummarizer(
@@ -602,6 +602,11 @@ export interface SharedTreeOptionsBeta extends ForestOptions, Partial<CodecWrite
 	 * Healed identifiers are written back out at the next summary in their stable UUID form,
 	 * so the inconsistency does not need to be re-healed on every load.
 	 *
+	 * When this flag is enabled, each time an unresolvable identifier is healed a
+	 * `HealUnresolvableIdentifierOnDecode` telemetry event is emitted (at
+	 * {@link @fluidframework/core-interfaces#LogLevelConst.info | LogLevel.info}) through the shared
+	 * object's logger, allowing applications to detect which documents actually required healing.
+	 *
 	 * Off by default because enabling it for documents that are not actually corrupt
 	 * would mask genuine bugs that otherwise surface as decode failures.
 	 *

package/src/shared-tree/treeCheckout.ts

@@ -4,7 +4,11 @@
  */
 
 import { createEmitter } from "@fluid-internal/client-utils";
-import type { IFluidHandle, Listenable } from "@fluidframework/core-interfaces/internal";
+import type {
+	IEmitter,
+	IFluidHandle,
+	Listenable,
+} from "@fluidframework/core-interfaces/internal";
 import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 import { type TelemetryLoggerExt, UsageError } from "@fluidframework/telemetry-utils/internal";
@@ -21,6 +25,7 @@ import {
 	type AnchorSetRootEvents,
 	type ChangeFamily,
 	CommitKind,
+	CommitOutcome,
 	type DeltaVisitor,
 	type DetachedFieldIndex,
 	type IEditableForest,
@@ -57,6 +62,7 @@ import {
 	deltaFieldMapHasVisibleChanges,
 	findCommonAncestor,
 	rebaseBranch,
+	type LocalCommitEvents,
 } from "../core/index.js";
 import {
 	type FieldBatchCodec,
@@ -115,7 +121,12 @@ import {
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 import { SharedTreeChangeEnricher } from "./sharedTreeChangeEnricher.js";
 import type { SharedTreeChangeProcessingContext } from "./sharedTreeChangeFamily.js";
-import { SharedTreeChangeFamily, hasSchemaChange } from "./sharedTreeChangeFamily.js";
+import {
+	ConstraintStatus,
+	SharedTreeChangeFamily,
+	getConstraintStatus,
+	hasSchemaChange,
+} from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import type { ISharedTreeEditor, SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 import { extractTransactionChangeProcessor } from "./transactionPostProcessor.js";
@@ -500,6 +511,14 @@ export class TreeCheckout implements ITreeCheckout {
 
 	private readonly views = new Set<TreeView<ImplicitFieldSchema>>();
 
+	/**
+	 * Event emitters for local commits.
+	 */
+	private readonly localCommitEventEmitters = new Map<
+		RevisionTag,
+		IEmitter<LocalCommitEvents>
+	>();
+
 	/**
 	 * Revertibles maintained for automatic disposal
 	 */
@@ -668,12 +687,14 @@ export class TreeCheckout implements ITreeCheckout {
 
 	private registerForBranchEvents(): void {
 		this.#transaction.branch.events.on("afterChange", this.onAfterBranchChange);
+		this.#transaction.branch.events.on("commitSequenced", this.onCommitSequenced);
 		this.#transaction.activeBranchEvents.on("afterChange", this.onAfterChange);
 		this.#transaction.activeBranchEvents.on("ancestryTrimmed", this.onAncestryTrimmed);
 	}
 
 	private unregisterFromBranchEvents(): void {
 		this.#transaction.branch.events.off("afterChange", this.onAfterBranchChange);
+		this.#transaction.branch.events.off("commitSequenced", this.onCommitSequenced);
 		this.#transaction.activeBranchEvents.off("afterChange", this.onAfterChange);
 		this.#transaction.activeBranchEvents.off("ancestryTrimmed", this.onAncestryTrimmed);
 	}
@@ -739,6 +760,39 @@ export class TreeCheckout implements ITreeCheckout {
 		}
 	}
 
+	private readonly onCommitSequenced = (commit: GraphCommit<SharedTreeChange>): void => {
+		const emitter = this.localCommitEventEmitters.get(commit.revision);
+		if (emitter === undefined) {
+			// If the commit predates the creation of this checkout, there will be no emitter associated with the commit.
+			// In that case, we don't need to emit any events.
+			return;
+		}
+		const constraintStatus = getConstraintStatus(commit.change);
+		let outcome: CommitOutcome;
+		switch (constraintStatus) {
+			case ConstraintStatus.Satisfied: {
+				outcome = CommitOutcome.FullyApplied;
+				break;
+			}
+			case ConstraintStatus.ImplicitViolation: {
+				outcome = CommitOutcome.FullyDropped;
+				break;
+			}
+			case ConstraintStatus.ExplicitViolation: {
+				outcome = CommitOutcome.NewContentOnly;
+				break;
+			}
+			default: {
+				unreachableCase(constraintStatus);
+			}
+		}
+		this.emitChangedLocked(() => {
+			emitter.emit("settled", outcome);
+		}, "a commit settled event callback");
+		// No more events will be emitted for this commit, so we can remove the emitter from the map.
+		this.localCommitEventEmitters.delete(commit.revision);
+	};
+
 	private readonly onAfterBranchChange = (
 		event: SharedTreeBranchChange<SharedTreeChange>,
 	): void => {
@@ -787,6 +841,8 @@ export class TreeCheckout implements ITreeCheckout {
 
 				let withinEventContext = true;
 
+				const events = createEmitter<LocalCommitEvents>();
+				this.localCommitEventEmitters.set(commit.revision, events);
 				const metadata: ChangeMetadata = {
 					kind,
 					isLocal: true,
@@ -805,6 +861,7 @@ export class TreeCheckout implements ITreeCheckout {
 					getRevertible: (onDisposed) => getRevertible?.(onDisposed),
 					label: this.labelTreeNode?.label,
 					labels: buildLabelsSet(this.labelTreeNode),
+					events,
 				};
 
 				this.emitChangedLocked(() => {
@@ -838,8 +895,11 @@ export class TreeCheckout implements ITreeCheckout {
 	 * Shared by both the local and remote `changed` emission paths in {@link TreeCheckout.onAfterBranchChange}.
 	 * The `try`/`finally` ensures the lock is released even if a listener throws.
 	 */
-	private emitChangedLocked(emit: () => void): void {
-		this.editLock.lock();
+	private emitChangedLocked(
+		emit: () => void,
+		reason: string = "a change event callback",
+	): void {
+		this.editLock.lock(reason);
 		try {
 			emit();
 		} finally {
@@ -855,7 +915,7 @@ export class TreeCheckout implements ITreeCheckout {
 	}
 
 	private readonly onAfterChange = (event: SharedTreeBranchChange<SharedTreeChange>): void => {
-		this.editLock.lock();
+		this.editLock.lock("a change event callback");
 		this.#events.emit("beforeBatch", event);
 		if (event.change !== undefined) {
 			const revision =
@@ -1703,7 +1763,13 @@ class EditLock {
 	 * @remarks Edits will throw an error if the lock is currently locked.
 	 */
 	public readonly editor: ISharedTreeEditor;
-	private locked = false;
+	/**
+	 * The current status of the lock.
+	 * The `reason` string will be included in the error message if an attempt is made to edit the tree while the lock is held.
+	 */
+	private status:
+		| { readonly isLocked: false }
+		| { readonly isLocked: true; readonly reason: string } = { isLocked: false };
 
 	/**
 	 * @param editor - an editor which will be used to create a new editor that is monitored to determine if any changes are happening to the tree.
@@ -1767,14 +1833,15 @@ class EditLock {
 
 	/**
 	 * Prevent further changes from being made to {@link EditLock.editor} until {@link EditLock.unlock} is called.
+	 * @param reason - A string describing why the lock is being acquired. This will be included in the error message if an attempt is made to edit while the lock is held.
 	 * @remarks May only be called when the lock is not already locked.
 	 */
-	public lock(): void {
-		if (this.locked) {
+	public lock(reason: string): void {
+		if (this.status.isLocked) {
 			debugger;
 		}
-		assert(!this.locked, 0xaa7 /* Checkout has already been locked */);
-		this.locked = true;
+		assert(!this.status.isLocked, 0xaa7 /* Checkout has already been locked */);
+		this.status = { isLocked: true, reason };
 	}
 
 	/**
@@ -1783,8 +1850,8 @@ class EditLock {
 	 * This must start with a capital letter, as it shows up as the first part of the error message and we want it to look nice.
 	 */
 	public checkUnlocked<T extends string>(action: T extends Capitalize<T> ? T : never): void {
-		if (this.locked) {
-			throw new UsageError(`${action} is forbidden during a change event callback`);
+		if (this.status.isLocked) {
+			throw new UsageError(`${action} is forbidden during ${this.status.reason}`);
 		}
 	}
 
@@ -1793,8 +1860,8 @@ class EditLock {
 	 * @remarks May only be called when the lock is currently locked.
 	 */
 	public unlock(): void {
-		assert(this.locked, 0xaa8 /* Checkout has not been locked */);
-		this.locked = false;
+		assert(this.status.isLocked, 0xaa8 /* Checkout has not been locked */);
+		this.status = { isLocked: false };
 	}
 }
 

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

@@ -86,6 +86,7 @@ export interface SharedTreeBranchEvents<
 
 	/**
 	 * Fired when a commit is ordered by the sequencing service.
+	 * @param commit - The commit that was sequenced
 	 *
 	 * @remarks
 	 * Once a commit is sequenced, the following guarantees hold:

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

@@ -214,7 +214,7 @@ export class SharedTreeCore<
 				options.minVersionForCollab,
 				this.schemaAndPolicy,
 				options.healUnresolvableIdentifiersOnDecode === true
-					? { sharedObjectId: sharedObject.id }
+					? { sharedObjectId: sharedObject.id, logger }
 					: undefined,
 			),
 			...summarizables,

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);