@fluidframework/tree 2.43.0 → 2.50.0-345060

package/src/core/schema-stored/schema.ts

@@ -185,8 +185,6 @@ export const storedEmptyFieldSchema: TreeFieldStoredSchema = {
  */
 export const identifierFieldKindIdentifier = "Identifier";
 
-/**
- */
 export abstract class TreeNodeStoredSchema {
 	protected _typeCheck!: MakeNominal;
 
@@ -213,8 +211,6 @@ export abstract class TreeNodeStoredSchema {
 	public abstract getFieldSchema(field: FieldKey): TreeFieldStoredSchema;
 }
 
-/**
- */
 export class ObjectNodeStoredSchema extends TreeNodeStoredSchema {
 	/**
 	 * @param objectNodeFields -
@@ -272,8 +268,6 @@ export class ObjectNodeStoredSchema extends TreeNodeStoredSchema {
 	}
 }
 
-/**
- */
 export class MapNodeStoredSchema extends TreeNodeStoredSchema {
 	/**
 	 * @param mapFields -
@@ -306,8 +300,6 @@ export class MapNodeStoredSchema extends TreeNodeStoredSchema {
 	}
 }
 
-/**
- */
 export class LeafNodeStoredSchema extends TreeNodeStoredSchema {
 	/**
 	 * @param leafValue -

package/src/core/schema-view/view.ts

@@ -9,8 +9,6 @@ import type { TreeNodeSchemaIdentifier, TreeStoredSchema } from "../schema-store
  * APIs for applying `view schema` to documents.
  */
 
-/**
- */
 export interface TreeAdapter {
 	readonly output: TreeNodeSchemaIdentifier;
 	readonly input: TreeNodeSchemaIdentifier;

package/src/core/tree/cursor.ts

@@ -312,8 +312,6 @@ export interface PathRootPrefix {
 	indexOffset?: number;
 }
 
-/**
- */
 export const enum CursorLocationType {
 	/**
 	 * Can iterate through nodes in a field.

package/src/core/tree/delta.ts

@@ -158,8 +158,6 @@ export interface DetachedNodeId {
 	readonly minor: number;
 }
 
-/**
- */
 export type FieldMap = ReadonlyMap<FieldKey, FieldChanges>;
 
 /**

package/src/core/tree/types.ts

@@ -18,8 +18,6 @@ import type {
 	ValueSchema,
 } from "../schema-stored/index.js";
 
-/**
- */
 export type TreeType = TreeNodeSchemaIdentifier;
 
 /**
@@ -43,8 +41,6 @@ export const EmptyKey: FieldKey = brand("");
  */
 export const rootFieldKey: FieldKey = brand("rootFieldKey");
 
-/**
- */
 export const rootField = keyAsDetachedField(rootFieldKey);
 
 /**

package/src/feature-libraries/default-schema/defaultEditBuilder.ts

@@ -410,8 +410,6 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 	}
 }
 
-/**
- */
 export interface ValueFieldEditBuilder<TContent> {
 	/**
 	 * Issues a change which replaces the current newContent of the field with `newContent`.
@@ -421,8 +419,6 @@ export interface ValueFieldEditBuilder<TContent> {
 	set(newContent: TContent): void;
 }
 
-/**
- */
 export interface OptionalFieldEditBuilder<TContent> {
 	/**
 	 * Issues a change which replaces the current newContent of the field with `newContent`

package/src/feature-libraries/default-schema/defaultFieldKinds.ts

@@ -257,20 +257,10 @@ export const fieldKinds: ReadonlyMap<FieldKindIdentifier, FieldKindWithEditor> =
 // TODO: Find a way to make docs like {@inheritDoc required} work in vscode.
 // TODO: ensure thy work in generated docs.
 // TODO: add these comments to the rest of the cases below.
-/**
- */
 export interface Required extends FlexFieldKind<"Value", Multiplicity.Single> {}
-/**
- */
 export interface Optional extends FlexFieldKind<"Optional", Multiplicity.Optional> {}
-/**
- */
 export interface Sequence extends FlexFieldKind<"Sequence", Multiplicity.Sequence> {}
-/**
- */
 export interface Identifier extends FlexFieldKind<"Identifier", Multiplicity.Single> {}
-/**
- */
 export interface Forbidden
 	extends FlexFieldKind<typeof forbiddenFieldKindIdentifier, Multiplicity.Forbidden> {}
 

package/src/feature-libraries/flex-tree/flexTreeTypes.ts

@@ -47,8 +47,6 @@ export function isFlexTreeNode(t: unknown): t is FlexTreeNode {
 	return isFlexTreeEntity(t) && t[flexTreeMarker] === FlexTreeEntityKind.Node;
 }
 
-/**
- */
 export enum FlexTreeEntityKind {
 	Node,
 	Field,

package/src/feature-libraries/modular-schema/crossFieldQueries.ts

@@ -44,8 +44,6 @@ export function getFirstFromCrossFieldMap<T>(
 	return map.getFirst({ revision, localId: id }, count);
 }
 
-/**
- */
 export enum CrossFieldTarget {
 	Source,
 	Destination,

package/src/feature-libraries/modular-schema/fieldChangeHandler.ts

@@ -216,19 +216,13 @@ export interface FieldEditor<TChangeset> {
  */
 export type ToDelta = (child: NodeId) => DeltaFieldMap;
 
-/**
- */
 export type NodeChangeInverter = (change: NodeId) => NodeId;
 
-/**
- */
 export enum NodeAttachState {
 	Attached,
 	Detached,
 }
 
-/**
- */
 export type NodeChangeRebaser = (
 	change: NodeId | undefined,
 	baseChange: NodeId | undefined,
@@ -239,15 +233,11 @@ export type NodeChangeRebaser = (
 	state?: NodeAttachState,
 ) => NodeId | undefined;
 
-/**
- */
 export type NodeChangeComposer = (
 	change1: NodeId | undefined,
 	change2: NodeId | undefined,
 ) => NodeId;
 
-/**
- */
 export type NodeChangePruner = (change: NodeId) => NodeId | undefined;
 
 /**

package/src/feature-libraries/modular-schema/modularChangeFamily.ts

@@ -2285,8 +2285,6 @@ function newCrossFieldTable<T>(): CrossFieldTable<T> {
 	};
 }
 
-/**
- */
 interface ConstraintState {
 	violationCount: number;
 }
@@ -2913,8 +2911,6 @@ function buildModularChangesetFromNode(props: {
 	});
 }
 
-/**
- */
 export interface FieldEditDescription {
 	type: "field";
 	field: FieldUpPath;
@@ -2923,16 +2919,12 @@ export interface FieldEditDescription {
 	revision: RevisionTag;
 }
 
-/**
- */
 export interface GlobalEditDescription {
 	type: "global";
 	revision: RevisionTag;
 	builds?: ChangeAtomIdBTree<TreeChunk>;
 }
 
-/**
- */
 export type EditDescription = FieldEditDescription | GlobalEditDescription;
 
 function getRevInfoFromTaggedChanges(changes: TaggedChange<ModularChangeset>[]): {

package/src/feature-libraries/modular-schema/modularChangeTypes.ts

@@ -17,8 +17,6 @@ import type { TreeChunk } from "../chunked-forest/index.js";
 
 import type { CrossFieldTarget } from "./crossFieldQueries.js";
 
-/**
- */
 export interface ModularChangeset extends HasFieldChanges {
 	/**
 	 * The numerically highest `ChangesetLocalId` used in this changeset.
@@ -110,8 +108,6 @@ export interface FieldId {
 	readonly field: FieldKey;
 }
 
-/**
- */
 export interface NodeExistsConstraint {
 	violated: boolean;
 }
@@ -128,23 +124,15 @@ export interface NodeChangeset extends HasFieldChanges {
 
 export type NodeId = ChangeAtomId;
 
-/**
- */
 export interface HasFieldChanges {
 	fieldChanges?: FieldChangeMap;
 }
 
-/**
- */
 export type FieldChangeMap = Map<FieldKey, FieldChange>;
 
-/**
- */
 export interface FieldChange {
 	fieldKind: FieldKindIdentifier;
 	change: FieldChangeset;
 }
 
-/**
- */
 export type FieldChangeset = Brand<unknown, "FieldChangeset">;

package/src/feature-libraries/sequence-field/types.ts

@@ -24,8 +24,6 @@ export interface HasMoveId {
 	id: MoveId;
 }
 
-/**
- */
 export interface CellId extends ChangeAtomId {}
 
 /**

package/src/index.ts

@@ -130,6 +130,7 @@ export {
 	type FieldSchemaAlphaUnsafe,
 	type ArrayNodeCustomizableSchemaUnsafe,
 	type MapNodeCustomizableSchemaUnsafe,
+	type TreeRecordNodeUnsafe,
 	// System types (not in Internal types for various reasons, like doc links or cannot be named errors).
 	type typeSchemaSymbol,
 	type TreeNodeSchemaNonClass,
@@ -196,6 +197,8 @@ export {
 	type JsonRefPath,
 	type JsonSchemaType,
 	type JsonLeafSchemaType,
+	type JsonRecordNodeSchema,
+	type JsonStringKeyPatternProperties,
 	getJsonSchema,
 	type LazyItem,
 	type Unenforced,
@@ -209,6 +212,7 @@ export {
 	type SimpleArrayNodeSchema,
 	type SimpleObjectNodeSchema,
 	type SimpleObjectFieldSchema,
+	type SimpleRecordNodeSchema,
 	normalizeAllowedTypes,
 	getSimpleSchema,
 	type ReadonlyArrayNode,
@@ -249,6 +253,11 @@ export {
 	type ObjectFromSchemaRecord,
 	type ValidateRecursiveSchemaTemplate,
 	type FixRecursiveRecursionLimit,
+	RecordNodeSchema,
+	type RecordNodeCustomizableSchema,
+	type RecordNodeInsertableData,
+	type RecordNodePojoEmulationSchema,
+	type TreeRecordNode,
 } from "./simple-tree/index.js";
 export {
 	SharedTree,

package/src/jsonDomainSchema.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { SchemaFactory } from "./simple-tree/index.js";
+import { SchemaFactory, SchemaFactoryAlpha } from "./simple-tree/index.js";
 import type {
 	AllowedTypes,
 	FixRecursiveArraySchema,
@@ -22,7 +22,7 @@ import type {
 	// #endregion
 } from "./simple-tree/index.js";
 
-const sf = new SchemaFactory("com.fluidframework.json");
+const sf = new SchemaFactoryAlpha("com.fluidframework.json");
 
 /**
  * Utilities for storing JSON data in {@link TreeNode}s.
@@ -80,7 +80,7 @@ export namespace JsonAsTree {
 	 * Do not use. Exists only as a workaround for {@link https://github.com/microsoft/TypeScript/issues/59550} and {@link https://github.com/microsoft/rushstack/issues/4429}.
 	 * @system @alpha
 	 */
-	export const _APIExtractorWorkaroundObjectBase = sf.mapRecursive("object", Tree);
+	export const _APIExtractorWorkaroundObjectBase = sf.recordRecursive("object", Tree);
 
 	/**
 	 * Arbitrary JSON object as a {@link TreeNode}.

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.43.0";
+export const pkgVersion = "2.50.0-345060";

package/src/shared-tree/treeAlpha.ts

@@ -592,6 +592,7 @@ export const TreeAlpha: TreeAlpha = {
 					return undefined;
 				}
 			// Fall through
+			case NodeKind.Record:
 			case NodeKind.Object: {
 				let storedKey: string | number = propertyKey;
 				if (isObjectNodeSchema(schema)) {
@@ -643,7 +644,8 @@ export const TreeAlpha: TreeAlpha = {
 				}
 				break;
 			}
-			case NodeKind.Map: {
+			case NodeKind.Map:
+			case NodeKind.Record: {
 				for (const [key, flexField] of flexNode.fields) {
 					const childTreeNode = tryGetTreeNodeForField(flexField);
 					if (childTreeNode !== undefined) {

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

@@ -3,7 +3,13 @@
  * Licensed under the MIT License.
  */
 
-import { assert, debugAssert, fail } from "@fluidframework/core-utils/internal";
+import {
+	assert,
+	debugAssert,
+	fail,
+	oob,
+	unreachableCase,
+} from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
@@ -17,8 +23,16 @@ import {
 } from "../schemaTypes.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import { toStoredSchema } from "../toStoredSchema.js";
-import { LeafNodeSchema } from "../leafNodeSchema.js";
-import { isObjectNodeSchema, type ObjectNodeSchema } from "../node-kinds/index.js";
+import {
+	isArrayNodeSchema,
+	isMapNodeSchema,
+	isObjectNodeSchema,
+	isRecordNodeSchema,
+	type ArrayNodeSchema,
+	type MapNodeSchema,
+	type ObjectNodeSchema,
+	type RecordNodeSchema,
+} from "../node-kinds/index.js";
 import { getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
@@ -293,10 +307,11 @@ export function checkUnion(
 	ambiguityErrors: string[],
 ): void {
 	const checked: Set<TreeNodeSchema> = new Set();
-	const maps: TreeNodeSchema[] = [];
-	const arrays: TreeNodeSchema[] = [];
-
+	const maps: MapNodeSchema[] = [];
+	const arrays: ArrayNodeSchema[] = [];
+	const records: RecordNodeSchema[] = [];
 	const objects: ObjectNodeSchema[] = [];
+
 	// Map from key to schema using that key
 	const allObjectKeys: Map<string, Set<TreeNodeSchema>> = new Map();
 
@@ -306,18 +321,37 @@ export function checkUnion(
 		}
 		checked.add(schema);
 
-		if (schema instanceof LeafNodeSchema) {
-			// nothing to do
-		} else if (isObjectNodeSchema(schema)) {
-			objects.push(schema);
-			for (const key of schema.fields.keys()) {
-				getOrCreate(allObjectKeys, key, () => new Set()).add(schema);
+		switch (schema.kind) {
+			case NodeKind.Leaf: {
+				// nothing to do
+				break;
+			}
+			case NodeKind.Object: {
+				assert(isObjectNodeSchema(schema), "Expected object schema.");
+				objects.push(schema);
+				for (const key of schema.fields.keys()) {
+					getOrCreate(allObjectKeys, key, () => new Set()).add(schema);
+				}
+				break;
+			}
+			case NodeKind.Array: {
+				assert(isArrayNodeSchema(schema), "Expected array schema.");
+				arrays.push(schema);
+				break;
+			}
+			case NodeKind.Map: {
+				assert(isMapNodeSchema(schema), "Expected map schema.");
+				maps.push(schema);
+				break;
+			}
+			case NodeKind.Record: {
+				assert(isRecordNodeSchema(schema), "Expected record schema.");
+				records.push(schema);
+				break;
+			}
+			default: {
+				unreachableCase(schema.kind);
 			}
-		} else if (schema.kind === NodeKind.Array) {
-			arrays.push(schema);
-		} else {
-			assert(schema.kind === NodeKind.Map, 0x9e7 /* invalid schema */);
-			maps.push(schema);
 		}
 	}
 
@@ -338,15 +372,35 @@ export function checkUnion(
 		);
 	}
 
+	if (records.length > 1) {
+		ambiguityErrors.push(
+			`More than one kind of record allowed within union (${formatTypes(records)}). This would require type disambiguation which is not supported by records during import or export.`,
+		);
+	}
+
 	if (maps.length > 0 && arrays.length > 0) {
 		ambiguityErrors.push(
 			`Both a map and an array allowed within union (${formatTypes([...arrays, ...maps])}). Both can be implicitly constructed from iterables like arrays, which are ambiguous when the array is empty.`,
 		);
 	}
 
-	if (objects.length > 0 && maps.length > 0) {
+	const nodeKindListEntries = [];
+	if (objects.length > 0) {
+		nodeKindListEntries.push("objects");
+	}
+	if (maps.length > 0) {
+		nodeKindListEntries.push("maps");
+	}
+	if (records.length > 0) {
+		nodeKindListEntries.push("records");
+	}
+	if (nodeKindListEntries.length > 1) {
+		const nodeKindListString =
+			nodeKindListEntries.length === 2
+				? `${nodeKindListEntries[0] ?? oob()} and ${nodeKindListEntries[1] ?? oob()}`
+				: `${nodeKindListEntries.slice(0, -1).join(", ")}, and ${nodeKindListEntries[nodeKindListEntries.length - 1]}`;
 		ambiguityErrors.push(
-			`Both a object and a map allowed within union (${formatTypes([...objects, ...maps])}). Both can be constructed from objects and can be ambiguous.`,
+			`A combination of ${nodeKindListString} is allowed within union (${formatTypes([...objects, ...maps, ...records])}). These can be constructed from objects and can be ambiguous.`,
 		);
 	}
 

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

@@ -22,7 +22,7 @@ import {
 } from "../../core/index.js";
 import { FieldKinds, valueSchemaAllows } from "../../feature-libraries/index.js";
 import { cloneWithReplacements } from "../../util/index.js";
-import { NodeKind, type TreeNodeSchema } from "../core/index.js";
+import type { TreeNodeSchema } from "../core/index.js";
 import {
 	booleanSchema,
 	handleSchema,
@@ -30,7 +30,7 @@ import {
 	numberSchema,
 	stringSchema,
 } from "../leafNodeSchema.js";
-import { isObjectNodeSchema } from "../node-kinds/index.js";
+import { isArrayNodeSchema, isObjectNodeSchema } from "../node-kinds/index.js";
 import type { TreeLeafValue } from "../schemaTypes.js";
 
 /**
@@ -106,7 +106,7 @@ export function customFromCursor<TChild>(
 			return reader.value;
 		default: {
 			assert(reader.value === undefined, 0xa54 /* out of schema: unexpected value */);
-			if (nodeSchema.kind === NodeKind.Array) {
+			if (isArrayNodeSchema(nodeSchema)) {
 				const fields = inCursorField(reader, EmptyKey, () =>
 					mapCursorField(reader, () => childHandler(reader, options, schema)),
 				);

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

@@ -67,6 +67,8 @@ export {
 	type JsonTreeSchema,
 	type JsonFieldSchema,
 	type JsonLeafSchemaType,
+	type JsonRecordNodeSchema,
+	type JsonStringKeyPatternProperties,
 } from "./jsonSchema.js";
 export type { TreeSchemaEncodingOptions } from "./getJsonSchema.js";
 export { getJsonSchema } from "./getJsonSchema.js";
@@ -78,6 +80,7 @@ export type {
 	ArrayNodeCustomizableSchemaUnsafe,
 	MapNodeCustomizableSchemaUnsafe,
 	System_Unsafe,
+	TreeRecordNodeUnsafe,
 } from "./typesUnsafe.js";
 
 export {

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

@@ -116,6 +116,22 @@ export interface JsonArrayNodeSchema extends JsonNodeSchemaBase<NodeKind.Array,
 	readonly items: JsonFieldSchema;
 }
 
+/**
+ * Types allowed in map / record nodes.
+ *
+ * @see {@link https://json-schema.org/draft/2020-12/json-schema-core#name-patternproperties}.
+ *
+ * @sealed
+ * @alpha
+ */
+export interface JsonStringKeyPatternProperties {
+	/**
+	 * This format allows for any string key that can appear in tree schema in a way that is JSON schema compatible,
+	 * but restricts the value to the specified allowed types of the value to only those specified.
+	 */
+	"^.*$": JsonFieldSchema;
+}
+
 /**
  * JSON Schema for a map node.
  *
@@ -131,13 +147,23 @@ export interface JsonMapNodeSchema extends JsonNodeSchemaBase<NodeKind.Map, "obj
 	 * Used to control the types of properties that can appear in the "object" representation of the map.
 	 * @see {@link https://json-schema.org/draft/2020-12/json-schema-core#name-patternproperties}.
 	 */
-	readonly patternProperties: {
-		/**
-		 * Types allowed in the map.
-		 * @remarks This format allows for any (JSON-compliant) key, but restricts the allowed types to only those specified.
-		 */
-		"^.*$": JsonFieldSchema;
-	};
+	readonly patternProperties: JsonStringKeyPatternProperties;
+}
+
+/**
+ * JSON Schema for a record node.
+ *
+ * @see {@link https://json-schema.org/draft/2020-12/json-schema-core#name-instance-data-model}.
+ *
+ * @sealed
+ * @alpha
+ */
+export interface JsonRecordNodeSchema extends JsonNodeSchemaBase<NodeKind.Record, "object"> {
+	/**
+	 * Used to control the types of properties that can appear in the "object" representation of the record.
+	 * @see {@link https://json-schema.org/draft/2020-12/json-schema-core#name-patternproperties}.
+	 */
+	readonly patternProperties: JsonStringKeyPatternProperties;
 }
 
 /**
@@ -182,7 +208,8 @@ export type JsonNodeSchema =
 	| JsonLeafNodeSchema
 	| JsonMapNodeSchema
 	| JsonArrayNodeSchema
-	| JsonObjectNodeSchema;
+	| JsonObjectNodeSchema
+	| JsonRecordNodeSchema;
 
 /**
  *{@link https://json-schema.org/draft/2020-12/json-schema-core | JSON Schema} representation of a {@link FieldSchema}.

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

@@ -776,16 +776,8 @@ export class SchemaFactory<
 		if (allowedTypes === undefined) {
 			const types = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];
 			const fullName = structuralName("Map", types);
-			return this.getStructuralType(
-				fullName,
-				types,
-				() =>
-					this.namedMap(
-						fullName as TName,
-						nameOrAllowedTypes as T,
-						false,
-						true,
-					) as TreeNodeSchema,
+			return this.getStructuralType(fullName, types, () =>
+				this.namedMap(fullName, nameOrAllowedTypes as T, false, true),
 			) as TreeNodeSchemaBoth<
 				string,
 				NodeKind.Map,
@@ -796,7 +788,7 @@ export class SchemaFactory<
 				undefined
 			>;
 		}
-		// To actually have type safety, assign to the type this method should return before implicitly upcasting when returning.
+		// To actually have type safety, assign to the type this method should return before implicitly up-casting when returning.
 		const out: TreeNodeSchemaBoth<
 			string,
 			NodeKind.Map,
@@ -895,7 +887,7 @@ export class SchemaFactory<
 	 * ```
 	 * @privateRemarks
 	 * The name produced at the type level here is not as specific as it could be, however doing type level sorting and escaping is a real mess.
-	 * There are cases where not having this full type provided will be less than ideal since TypeScript's structural types.
+	 * There are cases where not having this full type provided will be less than ideal, since TypeScript's structural types will allow assignment between runtime incompatible types at compile time.
 	 * For example attempts to narrow unions of structural arrays by name won't work.
 	 * Planned future changes to move to a class based schema system as well as factor function based node construction should mostly avoid these issues,
 	 * though there may still be some problematic cases even after that work is done.
@@ -997,7 +989,7 @@ export class SchemaFactory<
 	 * @returns The structural {@link TreeNodeSchema} associated with the given name and types.
 	 * @throws `UsageError` if a schema structurally named schema with the same name is cached in `structuralTypes` but had different input types.
 	 */
-	private getStructuralType(
+	protected getStructuralType(
 		fullName: string,
 		types: TreeNodeSchema | readonly TreeNodeSchema[],
 		builder: () => TreeNodeSchema,