@fluidframework/tree 2.70.0 → 2.71.0

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

@@ -13,6 +13,7 @@ import {
 	type FieldProps,
 } from "../fieldSchema.js";
 import type {
+	SimpleAllowedTypeAttributes,
 	SimpleFieldSchema,
 	SimpleNodeSchema,
 	SimpleTreeSchema,
@@ -65,7 +66,7 @@ function generateFieldSchema(
 	context: Context,
 	storedKey: string | undefined,
 ): FieldSchemaAlpha {
-	const allowed = generateAllowedTypes(simple.allowedTypesIdentifiers, context);
+	const allowed = generateAllowedTypes(simple.simpleAllowedTypes, context);
 	const props: Omit<FieldProps, "defaultProvider"> = {
 		metadata: simple.metadata,
 		key: storedKey,
@@ -84,8 +85,14 @@ function generateFieldSchema(
 	}
 }
 
-function generateAllowedTypes(allowed: ReadonlySet<string>, context: Context): AllowedTypes {
-	return [...allowed].map((id) => context.get(id) ?? fail(0xb5a /* Missing schema */));
+function generateAllowedTypes(
+	allowed: ReadonlyMap<string, SimpleAllowedTypeAttributes>,
+	context: Context,
+): AllowedTypes {
+	return Array.from(
+		allowed.keys(),
+		(id) => context.get(id) ?? fail(0xb5a /* Missing schema */),
+	);
 }
 
 function generateNode(
@@ -104,21 +111,17 @@ function generateNode(
 			return factory.objectAlpha(id, fields, { metadata: schema.metadata });
 		}
 		case NodeKind.Array:
-			return factory.arrayAlpha(
-				id,
-				generateAllowedTypes(schema.allowedTypesIdentifiers, context),
-				{ metadata: schema.metadata },
-			);
+			return factory.arrayAlpha(id, generateAllowedTypes(schema.simpleAllowedTypes, context), {
+				metadata: schema.metadata,
+			});
 		case NodeKind.Map:
-			return factory.mapAlpha(
-				id,
-				generateAllowedTypes(schema.allowedTypesIdentifiers, context),
-				{ metadata: schema.metadata },
-			);
+			return factory.mapAlpha(id, generateAllowedTypes(schema.simpleAllowedTypes, context), {
+				metadata: schema.metadata,
+			});
 		case NodeKind.Record:
 			return factory.recordAlpha(
 				id,
-				generateAllowedTypes(schema.allowedTypesIdentifiers, context),
+				generateAllowedTypes(schema.simpleAllowedTypes, context),
 				{ metadata: schema.metadata },
 			);
 		case NodeKind.Leaf:

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

@@ -107,7 +107,10 @@ function convertNodeSchema(
 
 function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSchema {
 	const allowedTypes: JsonSchemaRef[] = [];
-	schema.allowedTypesIdentifiers.forEach((type) => {
+	const allowedTypesIdentifiers: ReadonlySet<string> = new Set(
+		schema.simpleAllowedTypes.keys(),
+	);
+	allowedTypesIdentifiers.forEach((type) => {
 		allowedTypes.push(createSchemaRef(type));
 	});
 
@@ -206,7 +209,10 @@ function convertRecordLikeNodeSchema(
 	schema: SimpleRecordNodeSchema | SimpleMapNodeSchema,
 ): JsonMapNodeSchema | JsonRecordNodeSchema {
 	const allowedTypes: JsonSchemaRef[] = [];
-	schema.allowedTypesIdentifiers.forEach((type) => {
+	const allowedTypesIdentifiers: ReadonlySet<string> = new Set(
+		schema.simpleAllowedTypes.keys(),
+	);
+	allowedTypesIdentifiers.forEach((type) => {
 		allowedTypes.push(createSchemaRef(type));
 	});
 

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

@@ -6,6 +6,7 @@
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { normalizeFieldSchema, type ImplicitFieldSchema } from "../fieldSchema.js";
 import type {
+	SimpleAllowedTypeAttributes,
 	SimpleArrayNodeSchema,
 	SimpleFieldSchema,
 	SimpleLeafNodeSchema,
@@ -31,6 +32,7 @@ import { LeafNodeSchema } from "../leafNodeSchema.js";
  *
  * @param schema - The schema to convert
  * @param copySchemaObjects - If true, TreeNodeSchema and FieldSchema are copied into plain JavaScript objects. Either way, custom metadata is referenced and not copied.
+ * @param isViewSchema - If true (default), properties used by view schema but not part of stored schema (for example, `isStaged` on allowed types) are preserved in the output.
  *
  * @remarks
  * Given that the Schema types used in {@link ImplicitFieldSchema} already implement the {@link SimpleNodeSchema} interfaces, there are limited use-cases for this function.
@@ -45,6 +47,7 @@ import { LeafNodeSchema } from "../leafNodeSchema.js";
 export function toSimpleTreeSchema(
 	schema: ImplicitFieldSchema,
 	copySchemaObjects: boolean,
+	isViewSchema: boolean = true,
 ): SimpleTreeSchema {
 	const normalizedSchema = normalizeFieldSchema(schema);
 	const definitions = new Map<string, SimpleNodeSchema>();
@@ -59,7 +62,9 @@ export function toSimpleTreeSchema(
 					nodeSchema instanceof RecordNodeSchema,
 				0xb60 /* Invalid schema */,
 			);
-			const outSchema = copySchemaObjects ? copySimpleNodeSchema(nodeSchema) : nodeSchema;
+			const outSchema = copySchemaObjects
+				? copySimpleNodeSchema(nodeSchema, isViewSchema)
+				: nodeSchema;
 			definitions.set(nodeSchema.identifier, outSchema);
 		},
 	});
@@ -67,7 +72,10 @@ export function toSimpleTreeSchema(
 	return {
 		root: copySchemaObjects
 			? ({
-					allowedTypesIdentifiers: normalizedSchema.allowedTypesIdentifiers,
+					simpleAllowedTypes: normalizeSimpleAllowedTypes(
+						normalizedSchema.simpleAllowedTypes,
+						isViewSchema,
+					),
 					kind: normalizedSchema.kind,
 					metadata: normalizedSchema.metadata,
 					persistedMetadata: normalizedSchema.persistedMetadata,
@@ -77,12 +85,36 @@ export function toSimpleTreeSchema(
 	};
 }
 
+/**
+ * Normalizes the {@link SimpleAllowedTypeAttributes} by either preserving or omitting view-specific schema properties.
+ * @param simpleAllowedTypes - The simple allowed types to normalize.
+ * @param isViewSchema - If true, properties used by view schema but not part of stored schema (for example, `isStaged` on allowed types) are preserved in the output.
+ * @returns The normalized simple allowed types.
+ */
+function normalizeSimpleAllowedTypes(
+	simpleAllowedTypes: ReadonlyMap<string, SimpleAllowedTypeAttributes>,
+	isViewSchema: boolean,
+): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
+	if (isViewSchema) {
+		return simpleAllowedTypes;
+	} else {
+		const normalized = new Map<string, SimpleAllowedTypeAttributes>();
+		for (const [identifier, attributes] of simpleAllowedTypes.entries()) {
+			normalized.set(identifier, { ...attributes, isStaged: undefined });
+		}
+		return normalized;
+	}
+}
+
 /**
  * Copies a {@link SimpleNodeSchema} into a new plain JavaScript object.
  *
  * @remarks Caches the result on the input schema for future calls.
  */
-function copySimpleNodeSchema(schema: SimpleNodeSchema): SimpleNodeSchema {
+function copySimpleNodeSchema(
+	schema: SimpleNodeSchema,
+	isViewSchema: boolean,
+): SimpleNodeSchema {
 	const kind = schema.kind;
 	switch (kind) {
 		case NodeKind.Leaf:
@@ -90,9 +122,9 @@ function copySimpleNodeSchema(schema: SimpleNodeSchema): SimpleNodeSchema {
 		case NodeKind.Array:
 		case NodeKind.Map:
 		case NodeKind.Record:
-			return copySimpleSchemaWithAllowedTypes(schema);
+			return copySimpleSchemaWithAllowedTypes(schema, isViewSchema);
 		case NodeKind.Object:
-			return copySimpleObjectSchema(schema);
+			return copySimpleObjectSchema(schema, isViewSchema);
 		default:
 			unreachableCase(kind);
 	}
@@ -109,22 +141,26 @@ function copySimpleLeafSchema(schema: SimpleLeafNodeSchema): SimpleLeafNodeSchem
 
 function copySimpleSchemaWithAllowedTypes(
 	schema: SimpleMapNodeSchema | SimpleArrayNodeSchema | SimpleRecordNodeSchema,
+	isViewSchema: boolean,
 ): SimpleMapNodeSchema | SimpleArrayNodeSchema | SimpleRecordNodeSchema {
 	return {
 		kind: schema.kind,
-		allowedTypesIdentifiers: schema.allowedTypesIdentifiers,
+		simpleAllowedTypes: normalizeSimpleAllowedTypes(schema.simpleAllowedTypes, isViewSchema),
 		metadata: schema.metadata,
 		persistedMetadata: schema.persistedMetadata,
 	};
 }
 
-function copySimpleObjectSchema(schema: SimpleObjectNodeSchema): SimpleObjectNodeSchema {
+function copySimpleObjectSchema(
+	schema: SimpleObjectNodeSchema,
+	isViewSchema: boolean,
+): SimpleObjectNodeSchema {
 	const fields: Map<string, SimpleObjectFieldSchema> = new Map();
 	for (const [propertyKey, field] of schema.fields) {
 		// field already is a SimpleObjectFieldSchema, but copy the subset of the properties needed by this interface to get a clean simple object.
 		fields.set(propertyKey, {
 			kind: field.kind,
-			allowedTypesIdentifiers: field.allowedTypesIdentifiers,
+			simpleAllowedTypes: normalizeSimpleAllowedTypes(field.simpleAllowedTypes, isViewSchema),
 			metadata: field.metadata,
 			persistedMetadata: field.persistedMetadata,
 			storedKey: field.storedKey,

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

@@ -4,7 +4,7 @@
  */
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import { assert, Lazy } from "@fluidframework/core-utils/internal";
+import { Lazy } from "@fluidframework/core-utils/internal";
 
 import {
 	type ErasedBaseType,
@@ -25,6 +25,7 @@ import {
 	type TreeNodeSchema,
 } from "./treeNodeSchema.js";
 import { schemaAsTreeNodeValid } from "./treeNodeValid.js";
+import type { SimpleAllowedTypeAttributes } from "../simpleSchema.js";
 
 /**
  * Schema for types allowed in some location in a tree (like a field, map entry or array).
@@ -252,6 +253,21 @@ export class AnnotatedAllowedTypesInternal<
 		return this.lazyEvaluate.value.identifiers;
 	}
 
+	/**
+	 * Get the {@link SimpleAllowedTypeAttributes} version of the allowed types set.
+	 */
+	public static evaluateSimpleAllowedTypes(
+		annotatedAllowedTypes: AnnotatedAllowedTypes,
+	): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
+		const simpleAllowedTypes = new Map<string, SimpleAllowedTypeAttributes>();
+		for (const type of annotatedAllowedTypes.evaluate().types) {
+			simpleAllowedTypes.set(type.type.identifier, {
+				isStaged: type.metadata.stagedSchemaUpgrade !== undefined,
+			});
+		}
+		return simpleAllowedTypes;
+	}
+
 	public static override [Symbol.hasInstance]<TThis extends { prototype: object }>(
 		this: TThis,
 		value: unknown,
@@ -332,7 +348,7 @@ export class AnnotatedAllowedTypesInternal<
 	public static create<const T extends readonly AnnotatedAllowedType[]>(
 		types: T,
 		metadata: AllowedTypesMetadata = {},
-	): AnnotatedAllowedTypesInternal<T> & AllowedTypesFull<T> {
+	): AnnotatedAllowedTypesInternal<Readonly<T>> & AllowedTypesFull<Readonly<T>> {
 		const result = new AnnotatedAllowedTypesInternal(types, metadata);
 		return result as typeof result & UnannotateAllowedTypesList<T>;
 	}
@@ -340,7 +356,8 @@ export class AnnotatedAllowedTypesInternal<
 	public static createUnannotated<const T extends AllowedTypes>(
 		types: T,
 		metadata: AllowedTypesMetadata = {},
-	): AnnotatedAllowedTypesInternal & T {
+	): AnnotatedAllowedTypesInternal & Readonly<T> {
+		Object.freeze(types);
 		const annotatedTypes: AnnotatedAllowedType[] = types.map(normalizeToAnnotatedAllowedType);
 		const result = AnnotatedAllowedTypesInternal.create(annotatedTypes, metadata);
 		return result as typeof result & T;
@@ -349,6 +366,7 @@ export class AnnotatedAllowedTypesInternal<
 	public static createMixed<
 		const T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[],
 	>(types: T, metadata: AllowedTypesMetadata = {}): AllowedTypesFullFromMixed<T> {
+		Object.freeze(types);
 		const annotatedTypes: AnnotatedAllowedType[] = types.map(normalizeToAnnotatedAllowedType);
 		const result = AnnotatedAllowedTypesInternal.create(annotatedTypes, metadata);
 		return result as AllowedTypesFullFromMixed<T>;
@@ -524,14 +542,9 @@ export function normalizeAllowedTypesInternal(
 	// Adding this cache improved the performance of the "large recursive union" test (which mostly just constructs a TreeConfiguration) by ~5 times.
 	// This cache is strictly a performance optimization: it is not required for correctness.
 	return getOrCreate(cachedNormalize, type, () => {
-		// Due to more specific internal type, the above does not narrow sufficiently, so more narrowing is needed.
-		// It is possible this will give a false error if a TreeNodeSchema which matches this check is used.
-		assert(
-			!("types" in type && "metadata" in type),
-			0xc7d /* invalid AnnotatedAllowedTypes */,
-		);
-
-		const annotatedTypes: AnnotatedAllowedType[] = (isReadonlyArray(type) ? type : [type]).map(
+		const inputArray = isReadonlyArray(type) ? type : [type];
+		Object.freeze(inputArray);
+		const annotatedTypes: AnnotatedAllowedType[] = inputArray.map(
 			normalizeToAnnotatedAllowedType,
 		);
 
@@ -637,8 +650,8 @@ export type TreeNodeFromImplicitAllowedTypes<
  * This type exists only to be linked from documentation to provide a single linkable place to document some details of
  * "Input" types and how they handle schema.
  *
- * When a schema is used to describe data which is an input into an API, the API is [contravariant](https://en.wikipedia.org/wiki/Covariance_and_contravariance_(computer_science)) over the schema.
- * (See also, [TypeScript Variance Annotations](https://www.typescriptlang.org/docs/handbook/2/generics.html#variance-annotations)).
+ * When a schema is used to describe data which is an input into an API, the API is {@link https://en.wikipedia.org/wiki/Type_variance | contravariant}) over the schema.
+ * (See also {@link https://www.typescriptlang.org/docs/handbook/2/generics.html#variance-annotations | TypeScript Variance Annotations}).
  *
  * Since these schema are expressed using TypeScript types, it is possible for the user of the API to provide non-exact values of these types which has implications that depended on the variance.
  *

package/src/simple-tree/fieldSchema.ts

@@ -31,7 +31,7 @@ import type {
 } from "./core/index.js";
 import { normalizeAllowedTypes } from "./core/index.js";
 
-import type { SimpleFieldSchema } from "./simpleSchema.js";
+import type { SimpleAllowedTypeAttributes, SimpleFieldSchema } from "./simpleSchema.js";
 import type { UnsafeUnknownSchema } from "./unsafeUnknownSchema.js";
 import type { InsertableContent } from "./unhydratedFlexTreeFromInsertable.js";
 
@@ -412,6 +412,19 @@ export class FieldSchemaAlpha<
 		return this.allowedTypesFull.evaluateIdentifiers();
 	}
 
+	public get simpleAllowedTypes(): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
+		const types = this.allowedTypesFull.evaluate().types;
+		const info = new Map<string, SimpleAllowedTypeAttributes>();
+
+		for (const type of types) {
+			info.set(type.type.identifier, {
+				isStaged: type.metadata.stagedSchemaUpgrade !== undefined,
+			});
+		}
+
+		return info;
+	}
+
 	protected constructor(
 		kind: Kind,
 		types: Types,

package/src/simple-tree/index.ts

@@ -198,6 +198,7 @@ export type {
 	SimpleNodeSchemaBaseAlpha,
 	SimpleObjectFieldSchema,
 	SimpleRecordNodeSchema,
+	SimpleAllowedTypeAttributes,
 } from "./simpleSchema.js";
 export {
 	type ImplicitFieldSchema,

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

@@ -47,6 +47,7 @@ import {
 	type TreeNodeSchemaPrivateData,
 	convertAllowedTypes,
 	withBufferedTreeEvents,
+	AnnotatedAllowedTypesInternal,
 } from "../../core/index.js";
 import {
 	type FactoryContent,
@@ -68,6 +69,7 @@ import type {
 import { brand, type JsonCompatibleReadOnlyObject } from "../../../util/index.js";
 import { nullSchema } from "../../leafNodeSchema.js";
 import { arrayNodeStoredSchema } from "../../toStoredSchema.js";
+import type { SimpleAllowedTypeAttributes } from "../../simpleSchema.js";
 
 /**
  * A covariant base type for {@link (TreeArrayNode:interface)}.
@@ -1168,6 +1170,9 @@ export function arraySchema<
 	const lazyAllowedTypesIdentifiers = new Lazy(
 		() => new Set(normalizedTypes.evaluate().map((type) => type.identifier)),
 	);
+	const lazySimpleAllowedTypes = new Lazy(() => {
+		return AnnotatedAllowedTypesInternal.evaluateSimpleAllowedTypes(normalizedTypes);
+	});
 
 	let privateData: TreeNodeSchemaPrivateData | undefined;
 
@@ -1206,6 +1211,10 @@ export function arraySchema<
 			return lazyAllowedTypesIdentifiers.value;
 		}
 
+		public static get simpleAllowedTypes(): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
+			return lazySimpleAllowedTypes.value;
+		}
+
 		protected static override constructorCached: MostDerivedData | undefined = undefined;
 
 		protected static override oneTimeSetup(): TreeNodeSchemaInitializedData {

package/src/simple-tree/node-kinds/map/mapNode.ts

@@ -43,6 +43,7 @@ import {
 	type FlexContent,
 	type TreeNodeSchemaPrivateData,
 	convertAllowedTypes,
+	AnnotatedAllowedTypesInternal,
 } from "../../core/index.js";
 import {
 	unhydratedFlexTreeFromInsertable,
@@ -66,6 +67,7 @@ import type {
 import { recordLikeDataToFlexContent } from "../common.js";
 import { MapNodeStoredSchema } from "../../../core/index.js";
 import type { NodeSchemaOptionsAlpha } from "../../api/index.js";
+import type { SimpleAllowedTypeAttributes } from "../../simpleSchema.js";
 
 /**
  * A map of string keys to tree objects.
@@ -275,6 +277,9 @@ export function mapSchema<
 	const lazyAllowedTypesIdentifiers = new Lazy(
 		() => new Set(normalizedTypes.evaluate().map((type) => type.identifier)),
 	);
+	const lazySimpleAllowedTypes = new Lazy(() => {
+		return AnnotatedAllowedTypesInternal.evaluateSimpleAllowedTypes(normalizedTypes);
+	});
 
 	let privateData: TreeNodeSchemaPrivateData | undefined;
 	const persistedMetadata = nodeOptions.persistedMetadata;
@@ -303,6 +308,10 @@ export function mapSchema<
 			return lazyAllowedTypesIdentifiers.value;
 		}
 
+		public static get simpleAllowedTypes(): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
+			return lazySimpleAllowedTypes.value;
+		}
+
 		protected static override constructorCached: MostDerivedData | undefined = undefined;
 
 		protected static override oneTimeSetup(): TreeNodeSchemaInitializedData {

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

@@ -118,6 +118,23 @@ export type ObjectFromSchemaRecord<T extends RestrictiveStringRecord<ImplicitFie
  * No other own `own` or `enumerable` properties are included on object nodes unless the user of the node manually adds custom session only state.
  * This allows a majority of general purpose JavaScript object processing operations (like `for...in`, `Reflect.ownKeys()` and `Object.entries()`) to enumerate all the children.
  *
+ * Field Assignment and Deletion
+ * Assigning to a field updates the tree value as long as it is still valid based on the schema.
+ * - For required fields, assigning `undefined` is invalid, and will throw.
+ * - For optional fields, assigning `undefined` removes the field's contents, and marks it as empty (non-enumerable and value set to undefined).
+ *
+ * Example:
+ * ```ts
+ * const Foo = schemaFactory.object("Foo", {bar: schemaFactory.optional(schemaFactory.number)});
+ * const node = new Foo({bar: 1})
+ *
+ * // This clears the field, is non-enumerable, and value is undefined.
+ * delete node.bar;
+ *
+ * // This is equivalent to the delete example.
+ * node.bar = undefined
+ * ```
+ *
  * The API for fields is defined by {@link ObjectFromSchemaRecord}.
  * @public
  */
@@ -275,27 +292,17 @@ function createProxyHandler(
 					: false;
 			}
 
-			const innerNode = getInnerNode(proxy);
-
-			const innerSchema = innerNode.context.schema.nodeSchema.get(brand(schema.identifier));
-			assert(
-				innerSchema instanceof ObjectNodeStoredSchema,
-				0xc18 /* Expected ObjectNodeStoredSchema */,
-			);
-
-			setField(
-				innerNode.getBoxed(fieldInfo.storedKey),
-				fieldInfo.schema,
-				value,
-				innerSchema.getFieldSchema(fieldInfo.storedKey),
-			);
+			applyFieldChange(schema, { kind: "proxy", node: proxy }, fieldInfo, value);
 			return true;
 		},
 		deleteProperty(target, propertyKey): boolean {
-			// TODO: supporting delete when it makes sense (custom local fields, and optional field) could be added as a feature in the future.
-			throw new UsageError(
-				`Object nodes do not support the delete operator. Optional fields can be assigned to undefined instead.`,
-			);
+			const fieldInfo = schema.flexKeyMap.get(propertyKey);
+			if (fieldInfo === undefined) {
+				return allowAdditionalProperties ? Reflect.deleteProperty(target, propertyKey) : false;
+			}
+
+			applyFieldChange(schema, { kind: "target", node: target }, fieldInfo, undefined);
+			return true;
 		},
 		has: (target, propertyKey) => {
 			return (
@@ -750,3 +757,32 @@ function getFieldProperty(
 	}
 	return undefined;
 }
+
+function applyFieldChange(
+	schema: ObjectNodeSchemaPrivate,
+	from: { kind: "proxy"; node: TreeNode } | { kind: "target"; node: object },
+	fieldInfo: { storedKey: FieldKey; schema: FieldSchema },
+	value: InsertableContent | undefined,
+): void {
+	const proxy =
+		from.kind === "proxy"
+			? from.node
+			: (targetToProxy.get(from.node) ?? fail(0xc95 /* missing proxy */));
+	const inner = getInnerNode(proxy);
+	const storedSchema = inner.context.schema.nodeSchema.get(brand(schema.identifier));
+	assert(
+		storedSchema instanceof ObjectNodeStoredSchema,
+		0xc96 /* Expected ObjectNodeStoredSchema */,
+	);
+
+	if (value === undefined && inner.tryGetField(fieldInfo.storedKey) === undefined) {
+		return;
+	}
+
+	setField(
+		inner.getBoxed(fieldInfo.storedKey),
+		fieldInfo.schema,
+		value,
+		storedSchema.getFieldSchema(fieldInfo.storedKey),
+	);
+}

package/src/simple-tree/node-kinds/record/recordNode.ts

@@ -32,6 +32,7 @@ import {
 	CompatibilityLevel,
 	type TreeNodeSchemaPrivateData,
 	convertAllowedTypes,
+	AnnotatedAllowedTypesInternal,
 } from "../../core/index.js";
 import { getTreeNodeSchemaInitializedData } from "../../createContext.js";
 import { tryGetTreeNodeForField } from "../../getTreeNodeForField.js";
@@ -58,6 +59,7 @@ import { prepareForInsertion } from "../../prepareForInsertion.js";
 import { recordLikeDataToFlexContent } from "../common.js";
 import { MapNodeStoredSchema } from "../../../core/index.js";
 import type { NodeSchemaOptionsAlpha } from "../../api/index.js";
+import type { SimpleAllowedTypeAttributes } from "../../simpleSchema.js";
 
 /**
  * Create a proxy which implements the {@link TreeRecordNode} API.
@@ -258,6 +260,9 @@ export function recordSchema<
 	const lazyAllowedTypesIdentifiers = new Lazy(
 		() => new Set(normalizedTypes.evaluate().map((type) => type.identifier)),
 	);
+	const lazySimpleAllowedTypes = new Lazy(() => {
+		return AnnotatedAllowedTypesInternal.evaluateSimpleAllowedTypes(normalizedTypes);
+	});
 
 	let privateData: TreeNodeSchemaPrivateData | undefined;
 
@@ -347,6 +352,10 @@ export function recordSchema<
 			return lazyAllowedTypesIdentifiers.value;
 		}
 
+		public static get simpleAllowedTypes(): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
+			return lazySimpleAllowedTypes.value;
+		}
+
 		protected static override constructorCached: MostDerivedData | undefined = undefined;
 
 		public static readonly identifier = identifier;

package/src/simple-tree/node-kinds/record/recordNodeTypes.ts

@@ -26,6 +26,22 @@ import type { RestrictiveStringRecord } from "../../../util/index.js";
  * Therefore code assigning to these fields must explicitly construct nodes using the schema's constructor or create method,
  * or using some other method like {@link (TreeAlpha:interface).create}.
  *
+ * Field Assignment and Deletion
+ *
+ * Unlike JavaScript's `Record` type, assigning `undefined` to a key in {@link TreeRecordNode} behaves like a `delete` operation,
+ * removing the field's contents.
+ *
+ * This is to stay consistent with {@link TreeObjectNode} behavior.
+ *
+ * Example:
+ * ```ts
+ * const Numbers = schemaFactory.record("Numbers", schemaFactory.number);
+ * const record = new Numbers({ a:1, b:2 });
+ *
+ * // This is equivalent to delete record.a, and removes the entry.
+ * record.a = undefined
+ * ```
+ *
  * @beta
  */
 export interface TreeRecordNode<

package/src/simple-tree/simpleSchema.ts

@@ -91,7 +91,7 @@ export interface SimpleArrayNodeSchema<out TCustomMetadata = unknown>
 	 * @remarks Refers to the types by identifier.
 	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
 	 */
-	readonly allowedTypesIdentifiers: ReadonlySet<string>;
+	readonly simpleAllowedTypes: ReadonlyMap<string, SimpleAllowedTypeAttributes>;
 }
 
 /**
@@ -108,7 +108,7 @@ export interface SimpleMapNodeSchema<out TCustomMetadata = unknown>
 	 * @remarks Refers to the types by identifier.
 	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
 	 */
-	readonly allowedTypesIdentifiers: ReadonlySet<string>;
+	readonly simpleAllowedTypes: ReadonlyMap<string, SimpleAllowedTypeAttributes>;
 }
 
 /**
@@ -125,7 +125,7 @@ export interface SimpleRecordNodeSchema<out TCustomMetadata = unknown>
 	 * @remarks Refers to the types by identifier.
 	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
 	 */
-	readonly allowedTypesIdentifiers: ReadonlySet<string>;
+	readonly simpleAllowedTypes: ReadonlyMap<string, SimpleAllowedTypeAttributes>;
 }
 
 /**
@@ -162,6 +162,23 @@ export type SimpleNodeSchema =
 	| SimpleObjectNodeSchema
 	| SimpleRecordNodeSchema;
 
+/**
+ * Information about allowed types.
+ *
+ * @alpha
+ * @sealed
+ */
+export interface SimpleAllowedTypeAttributes {
+	/**
+	 * True if this schema is included as a {@link SchemaStaticsAlpha.staged | staged} schema upgrade,
+	 * allowing the view schema be compatible with stored schema with (post upgrade) or without it (pre-upgrade).
+	 * New documents and schema upgrades will omit any staged schema.
+	 *
+	 * Undefined if derived from a stored schema.
+	 */
+	readonly isStaged: boolean | undefined;
+}
+
 /**
  * A simple, shallow representation of a schema for a field.
  *
@@ -179,12 +196,12 @@ export interface SimpleFieldSchema {
 	readonly kind: FieldKind;
 
 	/**
-	 * The types allowed under the field.
+	 * Information about the allowed types under this field.
 	 *
 	 * @remarks Refers to the types by identifier.
 	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
 	 */
-	readonly allowedTypesIdentifiers: ReadonlySet<string>;
+	readonly simpleAllowedTypes: ReadonlyMap<string, SimpleAllowedTypeAttributes>;
 
 	/**
 	 * {@inheritDoc FieldSchemaMetadata}

package/src/simple-tree/toStoredSchema.ts

@@ -139,7 +139,10 @@ export function convertField(
 	if (schema instanceof FieldSchemaAlpha) {
 		types = convertAllowedTypes(schema.allowedTypes, options);
 	} else {
-		types = schema.allowedTypesIdentifiers as TreeTypeSet;
+		const allowedTypesIdentifiers: ReadonlySet<string> = new Set(
+			schema.simpleAllowedTypes.keys(),
+		);
+		types = allowedTypesIdentifiers as TreeTypeSet;
 	}
 	return { kind, types, persistedMetadata: schema.persistedMetadata };
 }
@@ -175,7 +178,10 @@ export function getStoredSchema(
 		}
 		case NodeKind.Map:
 		case NodeKind.Record: {
-			const types = schema.allowedTypesIdentifiers as TreeTypeSet;
+			const allowedTypesIdentifiers: ReadonlySet<string> = new Set(
+				schema.simpleAllowedTypes.keys(),
+			);
+			const types = allowedTypesIdentifiers as TreeTypeSet;
 			return new MapNodeStoredSchema(
 				{
 					kind: FieldKinds.optional.identifier,
@@ -187,7 +193,10 @@ export function getStoredSchema(
 			);
 		}
 		case NodeKind.Array: {
-			const types = schema.allowedTypesIdentifiers as TreeTypeSet;
+			const allowedTypesIdentifiers: ReadonlySet<string> = new Set(
+				schema.simpleAllowedTypes.keys(),
+			);
+			const types = allowedTypesIdentifiers as TreeTypeSet;
 			return arrayNodeStoredSchema(types, schema.persistedMetadata);
 		}
 		case NodeKind.Object: {