@fluidframework/tree 2.43.0 → 2.50.0

package/src/simple-tree/unhydratedFlexTreeFromInsertable.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import type { IFluidHandle } from "@fluidframework/core-interfaces";
 import { assert, fail, unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
@@ -28,28 +29,39 @@ import {
 	type TreeLeafValue,
 	extractFieldProvider,
 	type ContextualFieldProvider,
+	unannotateImplicitAllowedTypes,
 } from "./schemaTypes.js";
 import {
+	createField,
 	getKernel,
 	isTreeNode,
 	NodeKind,
 	type TreeNode,
 	type TreeNodeSchema,
 	type Unhydrated,
+	type UnhydratedFlexTreeField,
 	UnhydratedFlexTreeNode,
 	UnhydratedSequenceField,
 } from "./core/index.js";
+import { getUnhydratedContext } from "./createContext.js";
+import { convertFieldKind } from "./toStoredSchema.js";
+
 // Required to prevent the introduction of new circular dependencies
 // TODO: Having the schema provide their own policy functions for compatibility which
-// unhydratedFlexTreeFromInsertable invokes instead of manually handling each kind would remove this bad
+// `unhydratedFlexTreeFromInsertable` invokes instead of manually handling each kind would remove this bad
 // dependency, and reduce coupling.
-// eslint-disable-next-line import/no-internal-modules
-import { isObjectNodeSchema } from "./node-kinds/object/objectNodeTypes.js";
-import type { IFluidHandle } from "@fluidframework/core-interfaces";
-// eslint-disable-next-line import/no-internal-modules
-import { createField, type UnhydratedFlexTreeField } from "./core/unhydratedFlexTree.js";
-import { convertFieldKind } from "./toStoredSchema.js";
-import { getUnhydratedContext } from "./createContext.js";
+/* eslint-disable import/no-internal-modules */
+import { isArrayNodeSchema, type ArrayNodeSchema } from "./node-kinds/array/arrayNodeTypes.js";
+import { isMapNodeSchema, type MapNodeSchema } from "./node-kinds/map/mapNodeTypes.js";
+import {
+	isObjectNodeSchema,
+	type ObjectNodeSchemaPrivate,
+} from "./node-kinds/object/objectNodeTypes.js";
+import {
+	isRecordNodeSchema,
+	type RecordNodeSchema,
+} from "./node-kinds/record/recordNodeTypes.js";
+/* eslint-enable import/no-internal-modules */
 
 /**
  * Module notes:
@@ -139,14 +151,21 @@ function unhydratedFlexTreeFromInsertableNode(
 			result = leafToFlexContent(data, schema, allowedTypes);
 			break;
 		case NodeKind.Array:
+			assert(isArrayNodeSchema(schema), 0x922 /* Expected an array schema. */);
 			result = arrayToFlexContent(data, schema);
 			break;
 		case NodeKind.Map:
+			assert(isMapNodeSchema(schema), 0x923 /* Expected a Map schema. */);
 			result = mapToFlexContent(data, schema);
 			break;
 		case NodeKind.Object:
+			assert(isObjectNodeSchema(schema), 0x924 /* Expected an Object schema. */);
 			result = objectToFlexContent(data, schema);
 			break;
+		case NodeKind.Record:
+			assert(isRecordNodeSchema(schema), 0xbdd /* Expected a Record schema. */);
+			result = recordToFlexContent(data, schema);
+			break;
 		default:
 			unreachableCase(schema.kind);
 	}
@@ -265,8 +284,7 @@ function arrayChildToFlexTree(
  * @param data - The tree data to be transformed. Must be an iterable.
  * @param schema - The schema associated with the value.
  */
-function arrayToFlexContent(data: FactoryContent, schema: TreeNodeSchema): FlexContent {
-	assert(schema.kind === NodeKind.Array, 0x922 /* Expected an array schema. */);
+function arrayToFlexContent(data: FactoryContent, schema: ArrayNodeSchema): FlexContent {
 	if (!(typeof data === "object" && data !== null && Symbol.iterator in data)) {
 		throw new UsageError(`Input data is incompatible with Array schema: ${data}`);
 	}
@@ -308,14 +326,11 @@ function arrayToFlexContent(data: FactoryContent, schema: TreeNodeSchema): FlexC
  * @param data - The tree data to be transformed. Must be an iterable.
  * @param schema - The schema associated with the value.
  */
-function mapToFlexContent(data: FactoryContent, schema: TreeNodeSchema): FlexContent {
-	assert(schema.kind === NodeKind.Map, 0x923 /* Expected a Map schema. */);
+function mapToFlexContent(data: FactoryContent, schema: MapNodeSchema): FlexContent {
 	if (!(typeof data === "object" && data !== null)) {
 		throw new UsageError(`Input data is incompatible with Map schema: ${data}`);
 	}
 
-	const allowedChildTypes = normalizeAllowedTypes(schema.info as ImplicitAllowedTypes);
-
 	const fieldsIterator = (
 		Symbol.iterator in data
 			? // Support iterables of key value pairs (including Map objects)
@@ -324,30 +339,7 @@ function mapToFlexContent(data: FactoryContent, schema: TreeNodeSchema): FlexCon
 				Object.entries(data)
 	) as Iterable<readonly [string, InsertableContent]>;
 
-	const context = getUnhydratedContext(schema).flexContext;
-
-	const transformedFields = new Map<FieldKey, UnhydratedFlexTreeField>();
-	for (const item of fieldsIterator) {
-		if (!isReadonlyArray(item) || item.length !== 2 || typeof item[0] !== "string") {
-			throw new UsageError(`Input data is incompatible with map entry: ${item}`);
-		}
-		const [key, value] = item;
-		assert(!transformedFields.has(brand(key)), 0x84c /* Keys should not be duplicated */);
-
-		// Omit undefined values - an entry with an undefined value is equivalent to one that has been removed or omitted
-		if (value !== undefined) {
-			const child = unhydratedFlexTreeFromInsertableNode(value, allowedChildTypes);
-			const field = createField(context, FieldKinds.optional.identifier, brand(key), [child]);
-			transformedFields.set(brand(key), field);
-		}
-	}
-
-	return [
-		{
-			type: brand(schema.identifier),
-		},
-		transformedFields,
-	];
+	return recordLikeDataToFlexContent(fieldsIterator, schema);
 }
 
 /**
@@ -355,8 +347,10 @@ function mapToFlexContent(data: FactoryContent, schema: TreeNodeSchema): FlexCon
  * @param data - The tree data to be transformed. Must be a Record-like object.
  * @param schema - The schema associated with the value.
  */
-function objectToFlexContent(data: FactoryContent, schema: TreeNodeSchema): FlexContent {
-	assert(isObjectNodeSchema(schema), 0x924 /* Expected an Object schema. */);
+function objectToFlexContent(
+	data: FactoryContent,
+	schema: ObjectNodeSchemaPrivate,
+): FlexContent {
 	if (
 		typeof data !== "object" ||
 		data === null ||
@@ -396,6 +390,51 @@ function objectToFlexContent(data: FactoryContent, schema: TreeNodeSchema): Flex
 	return [{ type: brand(schema.identifier) }, fields];
 }
 
+/**
+ * Transforms data under an Object schema.
+ * @param data - The tree data to be transformed. Must be a Record-like object.
+ * @param schema - The schema associated with the value.
+ */
+function recordToFlexContent(data: FactoryContent, schema: RecordNodeSchema): FlexContent {
+	if (!(typeof data === "object" && data !== null)) {
+		throw new UsageError(`Input data is incompatible with Record schema: ${data}`);
+	}
+
+	const fieldsIterator: Iterable<readonly [string, InsertableContent]> = Object.entries(data);
+	return recordLikeDataToFlexContent(fieldsIterator, schema);
+}
+
+/**
+ * Converts record-like data to a FlexContent representation for map/record schema.
+ */
+function recordLikeDataToFlexContent(
+	fieldsIterator: Iterable<readonly [string, InsertableContent]>,
+	schema: MapNodeSchema | RecordNodeSchema,
+): FlexContent {
+	const allowedChildTypes = normalizeAllowedTypes(unannotateImplicitAllowedTypes(schema.info));
+	const context = getUnhydratedContext(schema).flexContext;
+
+	const transformedFields = new Map<FieldKey, UnhydratedFlexTreeField>();
+	for (const item of fieldsIterator) {
+		const [key, value] = item;
+		assert(!transformedFields.has(brand(key)), 0x84c /* Keys should not be duplicated */);
+
+		// Omit undefined values - an entry with an undefined value is equivalent to one that has been removed or omitted
+		if (value !== undefined) {
+			const child = unhydratedFlexTreeFromInsertableNode(value, allowedChildTypes);
+			const field = createField(context, FieldKinds.optional.identifier, brand(key), [child]);
+			transformedFields.set(brand(key), field);
+		}
+	}
+
+	return [
+		{
+			type: brand(schema.identifier),
+		},
+		transformedFields,
+	];
+}
+
 /**
  * Check {@link FactoryContentObject} for a property which could be store a field.
  *
@@ -550,6 +589,10 @@ function shallowCompatibilityTest(
 
 	// At this point, it is assumed data is a record-like object since all the other cases have been eliminated.
 
+	if (schema.kind === NodeKind.Record) {
+		return CompatibilityLevel.Normal;
+	}
+
 	if (schema.kind === NodeKind.Array) {
 		return CompatibilityLevel.None;
 	}

package/src/tableSchema.ts

@@ -6,7 +6,7 @@
 import { oob } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { Tree } from "./shared-tree/index.js";
+import { Tree, TreeAlpha } from "./shared-tree/index.js";
 import {
 	type FieldHasDefault,
 	type ImplicitAllowedTypes,
@@ -28,6 +28,7 @@ import {
 	type ImplicitAnnotatedFieldSchema,
 	type UnannotateImplicitFieldSchema,
 	isArrayNodeSchema,
+	type InsertableField,
 } from "./simple-tree/index.js";
 
 // Future improvement TODOs:
@@ -352,7 +353,12 @@ export namespace System_TableSchema {
 		// See definition of `RowInsertableType` below.
 		const rowFieldsBuiltInParts = {
 			id: schemaFactory.identifier,
-			cells: schemaFactory.required(schemaFactory.map("Row.cells", cellSchema), {
+			/**
+			 * The cells of the table row, keyed by column ID.
+			 * @remarks
+			 * The table row models its cells as a record, where each key is the ID of the column it belongs to. The choice of record (as opposed to a map) is intended to make interop with common table rendering libraries in TypeScript/JavaScript easier.
+			 */
+			cells: schemaFactory.required(schemaFactory.record("Row.cells", cellSchema), {
 				metadata: {
 					description: "The cells of the table row, keyed by column ID.",
 				},
@@ -389,7 +395,8 @@ export namespace System_TableSchema {
 				columnOrId: TableSchema.Column<TCellSchema> | string,
 			): CellValueType | undefined {
 				const columnId = typeof columnOrId === "string" ? columnOrId : columnOrId.id;
-				return this.cells.get(columnId) as CellValueType | undefined;
+				// Unlike most objects, RecordNodes don't have the default inherited object properties, so this is safe
+				return this.cells[columnId];
 			}
 
 			public setCell(
@@ -398,8 +405,18 @@ export namespace System_TableSchema {
 			): void {
 				// TODO: throw if column does not exist in the owning table.
 
-				const columnId = typeof columnOrId === "string" ? columnOrId : columnOrId.id;
-				this.cells.set(columnId, value);
+				if (value === undefined) {
+					this.removeCell(columnOrId);
+				} else {
+					const columnId = typeof columnOrId === "string" ? columnOrId : columnOrId.id;
+
+					// TypeScript is unable to narrow the types correctly here, hence the casts.
+					// See: https://github.com/microsoft/TypeScript/issues/52144
+					this.cells[columnId] = TreeAlpha.create(
+						cellSchema,
+						value as InsertableField<TCellSchema>,
+					) as CellValueType;
+				}
 			}
 
 			public removeCell(
@@ -409,12 +426,14 @@ export namespace System_TableSchema {
 
 				const columnId = typeof columnOrId === "string" ? columnOrId : columnOrId.id;
 
-				const cell: CellValueType | undefined = this.cells.get(columnId);
+				const cell: CellValueType | undefined = this.getCell(columnId);
 				if (cell === undefined) {
 					return undefined;
 				}
 
-				this.cells.delete(columnId);
+				// eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- The record's values are non-optional, so setting `undefined` as a means to remove the cell is not supported.
+				delete this.cells[columnId];
+
 				return cell;
 			}
 
@@ -423,7 +442,7 @@ export namespace System_TableSchema {
 				cell: CellValueType;
 			}[] {
 				const result = [];
-				for (const [columnId, cell] of this.cells.entries()) {
+				for (const [columnId, cell] of Object.entries(this.cells)) {
 					if (cell !== undefined) {
 						result.push({
 							columnId,

package/src/util/brandedMap.ts

@@ -16,8 +16,6 @@ import { getOrCreate } from "./utils.js";
  */
 export type BrandedKey<TKey, TContent> = TKey & Invariant<TContent>;
 
-/**
- */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type BrandedKeyContent<TKey extends BrandedKey<unknown, any>> = TKey extends BrandedKey<
 	unknown,