@fluidframework/tree 2.90.0 → 2.92.0

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

@@ -17,6 +17,7 @@ import {
 	anchorSlot,
 	type AnchorEvents,
 	type AnchorNode,
+	type DeltaMark,
 	type FieldKey,
 	type TreeValue,
 } from "../../core/index.js";
@@ -362,6 +363,20 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 	 */
 	readonly #childrenChangedBuffer: Set<FieldKey> = new Set();
 
+	/**
+	 * Buffer of field marks accumulated since events were paused.
+	 * Emitted alongside the buffered changed-fields set when flushed.
+	 */
+	readonly #fieldMarksBuffer: Map<FieldKey, readonly DeltaMark[]> = new Map();
+
+	/**
+	 * Fields whose marks have been permanently invalidated within the current buffer window due to
+	 * two or more separate delta batches touching the same field.
+	 * Once a key is in this set it must never be re-added to the marks buffer, even if
+	 * a third (or later) batch arrives for that field.
+	 */
+	readonly #invalidatedFieldMarkKeys: Set<FieldKey> = new Set();
+
 	/**
 	 * Whether or not the subtree has changed since events were paused.
 	 * When events are flushed, a single {@link AnchorEvents.subTreeChanged} event will be emitted if and only
@@ -399,8 +414,10 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		this.#eventSource = newSource;
 
 		if (this.#events.hasListeners("childrenChangedAfterBatch")) {
-			const off = this.#eventSource.on("childrenChangedAfterBatch", ({ changedFields }) =>
-				this.#emit("childrenChangedAfterBatch", { changedFields }),
+			const off = this.#eventSource.on(
+				"childrenChangedAfterBatch",
+				({ changedFields, fieldMarks }) =>
+					this.#emit("childrenChangedAfterBatch", { changedFields, fieldMarks }),
 			);
 			this.#disposeSourceListeners.set("childrenChangedAfterBatch", off);
 		}
@@ -421,7 +438,10 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 				0xc4f /* Should not have a dispose function without listeners */,
 			);
 
-			const off = this.#eventSource.on(eventName, (args) => this.#emit(eventName, args));
+			const off: Off =
+				eventName === "childrenChangedAfterBatch"
+					? this.#eventSource.on(eventName, (args) => this.#emit(eventName, args))
+					: this.#eventSource.on(eventName, () => this.#emit(eventName));
 			this.#disposeSourceListeners.set(eventName, off);
 		}
 
@@ -444,13 +464,14 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		eventName: keyof KernelEvents,
 		arg?: {
 			changedFields: ReadonlySet<FieldKey>;
+			fieldMarks: ReadonlyMap<FieldKey, readonly DeltaMark[]>;
 		},
 	): void {
 		this.#assertNotDisposed();
 		switch (eventName) {
 			case "childrenChangedAfterBatch": {
-				assert(arg !== undefined, 0xc50 /* childrenChangedAfterBatch should have arg */);
-				return this.#handleChildrenChangedAfterBatch(arg.changedFields);
+				assert(arg !== undefined, 0xcea /* childrenChangedAfterBatch requires arg */);
+				return this.#handleChildrenChangedAfterBatch(arg.changedFields, arg.fieldMarks);
 			}
 			case "subtreeChangedAfterBatch": {
 				return this.#handleSubtreeChangedAfterBatch();
@@ -461,13 +482,33 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		}
 	}
 
-	#handleChildrenChangedAfterBatch(changedFields: ReadonlySet<FieldKey>): void {
+	#handleChildrenChangedAfterBatch(
+		changedFields: ReadonlySet<FieldKey>,
+		fieldMarks: ReadonlyMap<FieldKey, readonly DeltaMark[]>,
+	): void {
 		if (bufferTreeEvents) {
 			for (const fieldKey of changedFields) {
 				this.#childrenChangedBuffer.add(fieldKey);
 			}
+			for (const [key, marks] of fieldMarks) {
+				if (this.#invalidatedFieldMarkKeys.has(key)) {
+					// Already permanently invalidated by an earlier collision; ignore this batch too.
+					// TODO: Once the eventing stack is rewritten to walk the composed delta at flush
+					// time, this collision path will be unreachable and can be removed entirely.
+					continue;
+				}
+				if (this.#fieldMarksBuffer.has(key)) {
+					// A second batch of marks arrived for the same field before the buffer was flushed.
+					// We have no delta composition logic, so permanently invalidate this field so that
+					// any further batches are also discarded rather than incorrectly surfaced.
+					this.#fieldMarksBuffer.delete(key);
+					this.#invalidatedFieldMarkKeys.add(key);
+				} else {
+					this.#fieldMarksBuffer.set(key, marks);
+				}
+			}
 		} else {
-			this.#events.emit("childrenChangedAfterBatch", { changedFields });
+			this.#events.emit("childrenChangedAfterBatch", { changedFields, fieldMarks });
 		}
 	}
 
@@ -488,8 +529,11 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		if (this.#childrenChangedBuffer.size > 0) {
 			this.#events.emit("childrenChangedAfterBatch", {
 				changedFields: this.#childrenChangedBuffer,
+				fieldMarks: this.#fieldMarksBuffer,
 			});
 			this.#childrenChangedBuffer.clear();
+			this.#fieldMarksBuffer.clear();
+			this.#invalidatedFieldMarkKeys.clear();
 		}
 
 		if (this.#subTreeChangedBuffer) {
@@ -519,6 +563,8 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		this.#disposeSourceListeners.clear();
 
 		this.#childrenChangedBuffer.clear();
+		this.#fieldMarksBuffer.clear();
+		this.#invalidatedFieldMarkKeys.clear();
 		this.#subTreeChangedBuffer = false;
 
 		this.#disposed = true;

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

@@ -271,7 +271,11 @@ export class UnhydratedFlexTreeNode
 	}
 
 	public emitChangedEvent(key: FieldKey): void {
-		this._events.emit("childrenChangedAfterBatch", { changedFields: new Set([key]) });
+		this._events.emit("childrenChangedAfterBatch", {
+			changedFields: new Set([key]),
+			// Unhydrated nodes are not visited by the delta pipeline, so no field marks are available.
+			fieldMarks: new Map(),
+		});
 
 		// Also emit subtree changed event for this node and all ancestors.
 		this.#emitSubtreeChangedEvents();

package/src/simple-tree/fieldSchema.ts

@@ -268,6 +268,21 @@ export interface FieldSchemaMetadataAlpha<TCustomMetadata = unknown>
 /**
  * Package internal construction API.
  */
+export function createFieldSchema<
+	Kind extends FieldKind,
+	Types extends ImplicitAllowedTypes,
+	TCustomMetadata = unknown,
+>(kind: Kind, annotatedTypes: Types): FieldSchemaAlpha<Kind, Types, TCustomMetadata>;
+export function createFieldSchema<
+	Kind extends FieldKind,
+	Types extends ImplicitAllowedTypes,
+	TCustomMetadata = unknown,
+	TProps extends FieldProps<TCustomMetadata> = FieldProps<TCustomMetadata>,
+>(
+	kind: Kind,
+	annotatedTypes: Types,
+	props: TProps,
+): FieldSchemaAlpha<Kind, Types, TCustomMetadata, TProps>;
 export function createFieldSchema<
 	Kind extends FieldKind,
 	Types extends ImplicitAllowedTypes,
@@ -276,7 +291,7 @@ export function createFieldSchema<
 	kind: Kind,
 	annotatedTypes: Types,
 	props?: FieldProps<TCustomMetadata>,
-): FieldSchemaAlpha<Kind, Types, TCustomMetadata> {
+): FieldSchemaAlpha<Kind, Types, TCustomMetadata, FieldProps<TCustomMetadata> | undefined> {
 	return createFieldSchemaPrivate(kind, annotatedTypes, props);
 }
 
@@ -291,7 +306,7 @@ let createFieldSchemaPrivate: <
 	kind: Kind,
 	annotatedTypes: Types,
 	props?: FieldProps<TCustomMetadata>,
-) => FieldSchemaAlpha<Kind, Types, TCustomMetadata>;
+) => FieldSchemaAlpha<Kind, Types, TCustomMetadata, FieldProps<TCustomMetadata> | undefined>;
 
 /**
  * All policy for a specific field,
@@ -384,11 +399,14 @@ export class FieldSchemaAlpha<
 		Kind extends FieldKind = FieldKind,
 		Types extends ImplicitAllowedTypes = ImplicitAllowedTypes,
 		TCustomMetadata = unknown,
+		TProps extends FieldPropsAlpha<TCustomMetadata> | undefined =
+			| FieldPropsAlpha<TCustomMetadata>
+			| undefined,
 	>
 	extends FieldSchema<Kind, Types, TCustomMetadata>
 	implements SimpleFieldSchema<SchemaType.View>
 {
-	private readonly propsAlpha: FieldPropsAlpha<TCustomMetadata> | undefined;
+	private readonly propsAlpha: TProps;
 
 	public get persistedMetadata(): JsonCompatibleReadOnlyObject | undefined {
 		return this.propsAlpha?.persistedMetadata;
@@ -403,7 +421,13 @@ export class FieldSchemaAlpha<
 			kind: Kind2,
 			annotatedAllowedTypes: Types2,
 			props?: FieldPropsAlpha<TCustomMetadata2>,
-		) => new FieldSchemaAlpha(kind, annotatedAllowedTypes, props);
+		) =>
+			// TCustomMetadata2 requires type assertion due to limitations with dependent type parameters
+			new FieldSchemaAlpha(kind, annotatedAllowedTypes, props) as unknown as FieldSchemaAlpha<
+				Kind2,
+				Types2,
+				TCustomMetadata2
+			>;
 	}
 
 	/**
@@ -432,7 +456,7 @@ export class FieldSchemaAlpha<
 
 		const normalizedTypes = normalizeAllowedTypes(types);
 		this.allowedTypesFull = normalizedTypes;
-		this.propsAlpha = props;
+		this.propsAlpha = props as TProps;
 	}
 }
 

package/src/simple-tree/index.ts

@@ -79,6 +79,8 @@ export {
 	SchemaFactoryBeta,
 	type SchemaStaticsBeta,
 	SchemaFactoryAlpha,
+	type SchemaStaticsAlpha,
+	type NodeProvider,
 	type ObjectSchemaOptionsAlpha,
 	type ObjectSchemaOptions,
 	type ScopedSchemaName,
@@ -89,12 +91,20 @@ export {
 	singletonSchema,
 	treeNodeApi,
 	type TreeNodeApi,
+	type ArrayNodeDeltaOp,
+	type ArrayNodeInsertOp,
+	type ArrayNodeRemoveOp,
+	type ArrayNodeRetainOp,
 	type NodeChangedData,
+	type NodeChangedDataAlpha,
+	type NodeChangedDataDelta,
+	type NodeChangedDataProperties,
 	borrowCursorFromTreeNodeOrValue,
 	exportConcise,
 	importConcise,
 	TreeBeta,
 	type TreeChangeEventsBeta,
+	type TreeChangeEventsAlpha,
 	type IdentifierIndex,
 	createTreeIndex,
 	createIdentifierIndex,
@@ -139,6 +149,8 @@ export {
 	type AllowedTypesFullFromMixedUnsafe,
 	type UnannotateAllowedTypesListUnsafe,
 	type AnnotateAllowedTypesListUnsafe,
+	type FieldHasDefaultAlphaUnsafe,
+	type InsertableObjectFromSchemaRecordAlphaUnsafe,
 	type TreeViewAlpha,
 	type TreeViewBeta,
 	type TreeBranch,
@@ -197,6 +209,9 @@ export {
 	checkCompatibility,
 	eraseSchemaDetails,
 	eraseSchemaDetailsSubclassable,
+	type ErasedSchema,
+	type ErasedNode,
+	type ErasedSchemaSubclassable,
 	snapshotSchemaCompatibility,
 	type SnapshotFileSystem,
 	type SnapshotSchemaCompatibilityOptions,
@@ -241,6 +256,7 @@ export {
 export { tryGetTreeNodeForField } from "./getTreeNodeForField.js";
 export {
 	type ArrayNodeCustomizableSchema,
+	type ArrayNodeCustomizableSchemaAlpha,
 	type ArrayNodePojoEmulationSchema,
 	ArrayNodeSchema,
 	asIndex,
@@ -248,6 +264,7 @@ export {
 	IterableTreeArrayContent,
 	type ReadonlyArrayNode,
 	TreeArrayNode,
+	type TreeArrayNodeAlpha,
 	type MapNodeCustomizableSchema,
 	type MapNodePojoEmulationSchema,
 	MapNodeSchema,
@@ -255,9 +272,12 @@ export {
 	type TreeMapNode,
 	type MapNodeInsertableData,
 	type FieldHasDefault,
+	type FieldHasDefaultAlpha,
 	type InsertableObjectFromSchemaRecord,
+	type InsertableObjectFromSchemaRecordAlpha,
 	type ObjectFromSchemaRecord,
 	ObjectNodeSchema,
+	type ObjectNodeSchemaWorkaround,
 	type ObjectNodeSchemaPrivate,
 	objectSchema,
 	isObjectNodeSchema,

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -447,6 +447,35 @@ export interface TreeArrayNode<
 	values(): IterableIterator<T>;
 }
 
+/**
+ * {@link (TreeArrayNode:interface)} with additional alpha APIs.
+ * @alpha @sealed
+ */
+export interface TreeArrayNodeAlpha<
+	TAllowedTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe = ImplicitAllowedTypes,
+	out T = [TAllowedTypes] extends [ImplicitAllowedTypes]
+		? TreeNodeFromImplicitAllowedTypes<TAllowedTypes>
+		: TreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>,
+	in TNew = [TAllowedTypes] extends [ImplicitAllowedTypes]
+		? InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes>
+		: InsertableTreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>,
+> extends TreeArrayNode<TAllowedTypes, T, TNew> {
+	/**
+	 * Removes existing item(s) and/or adds new item(s).
+	 * @param start - The index at which to start changing the array. If negative, it is treated as `array.length + start`.
+	 * Must be a positive in bounds index or a negative index such that `array.length + start` is a positive in bounds index.
+	 * @param deleteCount - The number of item(s) to remove. If not provided, it defaults to the end of the array.
+	 * Must be a non-negative integer no greater than the number of items from `start` to the end of the array.
+	 * @param items - The item(s) to insert at `start`.
+	 * @returns An array containing the item(s) that were removed.
+	 */
+	splice(
+		start: number,
+		deleteCount?: number,
+		...items: readonly (TNew | IterableTreeArrayContent<TNew>)[]
+	): T[];
+}
+
 /**
  * A {@link TreeNode} which implements 'readonly T[]' and the array mutation APIs.
  * @public
@@ -997,6 +1026,41 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 
 		editor.remove(removeStart, removeEnd - removeStart);
 	}
+	public splice(
+		start: number,
+		deleteCount?: number,
+		...items: Insertable<T>
+	): TreeNodeFromImplicitAllowedTypes<T>[] {
+		const length = this.length;
+		const actualStart = start < 0 ? Math.max(length + start, 0) : Math.min(start, length);
+		const actualDeleteCount =
+			deleteCount === undefined
+				? length - actualStart
+				: Math.min(Math.max(deleteCount, 0), length - actualStart);
+		validateIndexRange(
+			actualStart,
+			actualStart + actualDeleteCount,
+			getSequenceField(this),
+			"TreeArrayNode.splice",
+		);
+		const removed: TreeNodeFromImplicitAllowedTypes<T>[] = [];
+		for (let index = actualStart; index < actualStart + actualDeleteCount; index++) {
+			removed.push(this.at(index) ?? oob());
+		}
+
+		const innerNode = getInnerNode(this);
+		const transaction = innerNode.isHydrated()
+			? innerNode.context.checkout.transaction
+			: undefined;
+		transaction?.start();
+		this.removeRange(actualStart, actualStart + actualDeleteCount);
+		if (items.length > 0) {
+			this.insertAt(actualStart, ...items);
+		}
+		transaction?.commit();
+		return removed;
+	}
+
 	public moveToStart(sourceIndex: number, source?: ReadonlyArrayNode): void {
 		const sourceArray = source ?? this;
 		const sourceField = getSequenceField(sourceArray);

package/src/simple-tree/node-kinds/array/arrayNodeTypes.ts

@@ -14,7 +14,7 @@ import type {
 } from "../../core/index.js";
 import type { SchemaType, SimpleArrayNodeSchema } from "../../simpleSchema.js";
 
-import type { TreeArrayNode } from "./arrayNode.js";
+import type { TreeArrayNode, TreeArrayNodeAlpha } from "./arrayNode.js";
 
 /**
  * A schema for customizable {@link (TreeArrayNode:interface)}s.
@@ -37,6 +37,30 @@ export interface ArrayNodeCustomizableSchema<
 		>,
 		SimpleArrayNodeSchema<SchemaType.View, TCustomMetadata> {}
 
+/**
+ * A Schema for customizable {@link (TreeArrayNode:interface)}s with additional alpha APIs.
+ * @remarks
+ * Duplicates {@link ArrayNodeCustomizableSchema} with {@link TreeArrayNodeAlpha} as the node type,
+ * adding support for the alpha APIs on those nodes.
+ * @system @sealed @alpha
+ */
+export interface ArrayNodeCustomizableSchemaAlpha<
+	out TName extends string = string,
+	in out T extends ImplicitAllowedTypes = ImplicitAllowedTypes,
+	out ImplicitlyConstructable extends boolean = true,
+	out TCustomMetadata = unknown,
+> extends TreeNodeSchemaClass<
+			TName,
+			NodeKind.Array,
+			TreeArrayNodeAlpha<T> & WithType<TName, NodeKind.Array, T>,
+			Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
+			ImplicitlyConstructable,
+			T,
+			undefined,
+			TCustomMetadata
+		>,
+		SimpleArrayNodeSchema<SchemaType.View, TCustomMetadata> {}
+
 /**
  * A schema for POJO emulation mode {@link (TreeArrayNode:interface)}s.
  * @system @sealed @alpha

package/src/simple-tree/node-kinds/array/index.ts

@@ -10,10 +10,12 @@ export {
 	TreeArrayNode,
 	type ReadonlyArrayNode,
 	type ArrayPlaceAnchor,
+	type TreeArrayNodeAlpha,
 	createArrayInsertionAnchor,
 } from "./arrayNode.js";
 export {
 	type ArrayNodeCustomizableSchema,
+	type ArrayNodeCustomizableSchemaAlpha,
 	type ArrayNodePojoEmulationSchema,
 	ArrayNodeSchema,
 	isArrayNodeSchema,

package/src/simple-tree/node-kinds/index.ts

@@ -5,6 +5,7 @@
 
 export {
 	type ArrayNodeCustomizableSchema,
+	type ArrayNodeCustomizableSchemaAlpha,
 	type ArrayNodePojoEmulationSchema,
 	ArrayNodeSchema,
 	arraySchema,
@@ -12,6 +13,7 @@ export {
 	isArrayNodeSchema,
 	IterableTreeArrayContent,
 	TreeArrayNode,
+	type TreeArrayNodeAlpha,
 	type ReadonlyArrayNode,
 	type ArrayPlaceAnchor,
 	createArrayInsertionAnchor,
@@ -29,10 +31,13 @@ export {
 
 export {
 	type FieldHasDefault,
+	type FieldHasDefaultAlpha,
 	type InsertableObjectFromSchemaRecord,
+	type InsertableObjectFromSchemaRecordAlpha,
 	isObjectNodeSchema,
 	type ObjectFromSchemaRecord,
 	ObjectNodeSchema,
+	type ObjectNodeSchemaWorkaround,
 	type ObjectNodeSchemaPrivate,
 	objectSchema,
 	setField,

package/src/simple-tree/node-kinds/object/index.ts

@@ -5,7 +5,9 @@
 
 export {
 	type FieldHasDefault,
+	type FieldHasDefaultAlpha,
 	type InsertableObjectFromSchemaRecord,
+	type InsertableObjectFromSchemaRecordAlpha,
 	type ObjectFromSchemaRecord,
 	objectSchema,
 	setField,
@@ -15,5 +17,6 @@ export {
 export {
 	isObjectNodeSchema,
 	ObjectNodeSchema,
+	type ObjectNodeSchemaWorkaround,
 	type ObjectNodeSchemaPrivate,
 } from "./objectNodeTypes.js";

package/src/simple-tree/node-kinds/object/objectNode.ts

@@ -70,6 +70,7 @@ import {
 	type ContextualFieldProvider,
 	extractFieldProvider,
 	isConstant,
+	type DefaultProvider,
 } from "../../fieldSchema.js";
 import { tryGetTreeNodeForField } from "../../getTreeNodeForField.js";
 import { prepareForInsertion } from "../../prepareForInsertion.js";
@@ -99,8 +100,7 @@ import type {
  */
 export type ObjectFromSchemaRecord<T extends RestrictiveStringRecord<ImplicitFieldSchema>> =
 	RestrictiveStringRecord<ImplicitFieldSchema> extends T
-		? // eslint-disable-next-line @typescript-eslint/no-empty-object-type
-			{}
+		? {}
 		: {
 				-readonly [Property in keyof T]: Property extends string
 					? TreeFieldFromImplicitField<T[Property]>
@@ -149,8 +149,11 @@ export type TreeObjectNode<
  * @remarks Yields `false` when unknown.
  *
  * @privateRemarks
- * TODO: Account for field schemas with default value providers.
- * For now, this only captures field kinds that we know always have defaults - optional fields and identifier fields.
+ * This checks for:
+ * 1. Optional fields (which have an implicit undefined default)
+ * 2. Identifier fields (which have auto-generated defaults)
+ *
+ * Note that this cannot tell if required fields have defaults. Use `FieldHasDefaultAlpha` for alpha schemas if you need to check for required field defaults.
  *
  * @system @public
  */
@@ -160,6 +163,33 @@ export type FieldHasDefault<T extends ImplicitFieldSchema> = [T] extends [
 	? true
 	: false;
 
+/**
+ * Type utility for determining if an implicit field schema is known to have a default value.
+ * Supports alpha field schemas with explicit default providers.
+ *
+ * @remarks Yields `false` when unknown.
+ *
+ * @privateRemarks
+ * This checks for:
+ * 1. Fields with explicit default providers (computed from the props type)
+ * 2. Optional fields (which have an implicit undefined default)
+ * 3. Identifier fields (which have auto-generated defaults)
+ *
+ * @system @alpha
+ */
+export type FieldHasDefaultAlpha<T extends ImplicitFieldSchema> =
+	// Extract Kind and TProps from FieldSchemaAlpha and compute whether it has a default
+	[T] extends [FieldSchemaAlpha<infer Kind, infer _Types, infer _Meta, infer TProps>]
+		? // Optional and Identifier kinds always have defaults
+			Kind extends FieldKind.Optional | FieldKind.Identifier
+			? true
+			: // Check if props has defaultProvider
+				TProps extends { defaultProvider: DefaultProvider }
+				? true
+				: false
+		: // Fallback to base FieldHasDefault for non-Alpha schemas
+			FieldHasDefault<T>;
+
 /**
  * Helper used to produce types for:
  *
@@ -209,6 +239,35 @@ export type InsertableObjectFromSchemaRecord<
 				}
 			>;
 
+/**
+ * Alpha version of InsertableObjectFromSchemaRecord that supports field defaults.
+ *
+ * @system @alpha
+ */
+export type InsertableObjectFromSchemaRecordAlpha<
+	T extends RestrictiveStringRecord<ImplicitFieldSchema>,
+> =
+	RestrictiveStringRecord<ImplicitFieldSchema> extends T
+		? { arbitraryKey: "arbitraryValue" } extends T
+			? // {} case
+				Record<string, never>
+			: // RestrictiveStringRecord<ImplicitFieldSchema> case
+				never
+		: FlattenKeys<
+				{
+					readonly [Property in keyof T]?: InsertableTreeFieldFromImplicitField<
+						T[Property & string]
+					>;
+				} & {
+					// Field does not have a known default, make it required:
+					readonly [Property in keyof T as FieldHasDefaultAlpha<
+						T[Property & string]
+					> extends false
+						? Property
+						: never]: InsertableTreeFieldFromImplicitField<T[Property & string]>;
+				}
+			>;
+
 /**
  * Maps from simple field keys ("property" keys) to information about the field.
  *
@@ -387,17 +446,16 @@ export class ObjectFieldSchema<
 		Kind extends FieldKind,
 		Types extends ImplicitAllowedTypes,
 		TCustomMetadata = unknown,
+		TProps extends FieldProps<TCustomMetadata> & {
+			readonly key: string;
+		} = FieldProps<TCustomMetadata> & { readonly key: string },
 	>
-	extends FieldSchemaAlpha<Kind, Types, TCustomMetadata>
+	extends FieldSchemaAlpha<Kind, Types, TCustomMetadata, TProps>
 	implements SimpleObjectFieldSchema
 {
 	public readonly storedKey: string;
 
-	public constructor(
-		kind: Kind,
-		allowedTypes: Types,
-		props: FieldProps<TCustomMetadata> & { readonly key: string },
-	) {
+	public constructor(kind: Kind, allowedTypes: Types, props: TProps) {
 		super(kind, allowedTypes, props);
 		this.storedKey = props.key;
 	}
@@ -592,7 +650,7 @@ export function objectSchema<
 	}
 	type Output = typeof CustomObjectNode &
 		(new (
-			input: InsertableObjectFromSchemaRecord<T> | InternalTreeNode,
+			input: InsertableObjectFromSchemaRecordAlpha<T> | InternalTreeNode,
 		) => TreeObjectNode<T, TName>);
 	return CustomObjectNode as Output;
 }

package/src/simple-tree/node-kinds/object/objectNodeTypes.ts

@@ -21,9 +21,40 @@ import type {
 import type {
 	TreeObjectNode,
 	SimpleKeyMap,
-	InsertableObjectFromSchemaRecord,
+	InsertableObjectFromSchemaRecordAlpha,
 } from "./objectNode.js";
 
+/**
+ * {@link (ObjectNodeSchema:interface)} with a workaround to avoid a specific known TypeScript issue which causes it to not be assignable to itself in some cases.
+ * @remarks
+ * If dealing with a schema whose inferred type includes this workaround (because it was produced by a schema factory API which uses it),
+ * if you need to explicitly state that type (for example when using {@link https://www.typescriptlang.org/tsconfig/#isolatedDeclarations | isolatedDeclarations}), it is best to keep this workaround.
+ * No other case should need to refer to this workaround type directly.
+ * See {@link ObjectNodeSchemaWorkaround.createFromInsertable} for details.
+ * @sealed
+ * @alpha
+ */
+export type ObjectNodeSchemaWorkaround<
+	TName extends string = string,
+	T extends
+		RestrictiveStringRecord<ImplicitFieldSchema> = RestrictiveStringRecord<ImplicitFieldSchema>,
+	ImplicitlyConstructable extends boolean = boolean,
+	TCustomMetadata = unknown,
+> = ObjectNodeSchema<TName, T, ImplicitlyConstructable, TCustomMetadata> & {
+	/**
+	 * Typing checking workaround: not for for actual use.
+	 * @remarks
+	 * This API collides with {@link TreeNodeSchemaCore.createFromInsertable} to disable a type checking optimization which produces different and undesired results.
+	 * See {@link https://github.com/microsoft/TypeScript/issues/59049#issuecomment-2773459693} for more details.
+	 *
+	 * The specific issue here is non-empty POJO mode object schema not being assignable to `ObjectNodeSchema`,
+	 * @privateRemarks
+	 * See the above link and the tests in objectNode.spec.ts which reference it.
+	 * @system
+	 */
+	readonly createFromInsertable: unknown;
+};
+
 /**
  * A schema for {@link TreeObjectNode}s.
  * @sealed
@@ -39,7 +70,7 @@ export interface ObjectNodeSchema<
 			TName,
 			NodeKind.Object,
 			TreeObjectNode<T, TName>,
-			InsertableObjectFromSchemaRecord<T>,
+			object & InsertableObjectFromSchemaRecordAlpha<T>,
 			ImplicitlyConstructable,
 			T,
 			never,