@fluidframework/tree 2.3.0-288113 → 2.4.0-294316

package/src/simple-tree/{jsonSchema.ts → api/jsonSchema.ts}

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import type { NodeKind } from "./core/index.js";
+import type { NodeKind } from "../core/index.js";
 
 /**
  * The fully-qualified {@link TreeNodeSchemaCore.identifier}.
@@ -103,18 +103,10 @@ export interface JsonObjectNodeSchema extends JsonNodeSchemaBase<NodeKind.Object
 export interface JsonArrayNodeSchema extends JsonNodeSchemaBase<NodeKind.Array, "array"> {
 	/**
 	 * The kinds of items allowed under the array.
-	 * @remarks Always represented via references to {@link JsonTreeSchema.$defs}.
 	 *
 	 * @see {@link https://json-schema.org/draft/2020-12/json-schema-core#name-items}.
 	 */
-	readonly items: {
-		/**
-		 * The kinds of items allowed under the array.
-		 * @remarks Always represented via references to {@link JsonTreeSchema.$defs}.
-		 * @see {@link https://json-schema.org/draft/2020-12/json-schema-core#name-anyof}.
-		 */
-		anyOf: JsonSchemaRef[];
-	};
+	readonly items: JsonFieldSchema;
 }
 
 /**
@@ -191,14 +183,24 @@ export type JsonNodeSchema =
  * @sealed
  * @alpha
  */
-export interface JsonFieldSchema {
+export type JsonFieldSchema = {
 	/**
-	 * The kinds of items allowed under the field.
-	 * @remarks Always represented via references to {@link JsonTreeSchema.$defs}.
-	 * @see {@link https://json-schema.org/draft/2020-12/json-schema-core#name-anyof}.
+	 * Description of the field.
+	 * @remarks Derived from {@link FieldSchemaMetadata.description}.
+	 * @see {@link https://json-schema.org/draft/2020-12/json-schema-validation#name-title-and-description}
 	 */
-	readonly anyOf: JsonSchemaRef[];
-}
+	readonly description?: string | undefined;
+} & (
+	| {
+			/**
+			 * The kinds of items allowed under the field, for polymorphic types.
+			 * @remarks Always represented via references to {@link JsonTreeSchema.$defs}.
+			 * @see {@link https://json-schema.org/draft/2020-12/json-schema-core#name-anyof}.
+			 */
+			readonly anyOf: JsonSchemaRef[];
+	  }
+	| JsonSchemaRef
+);
 
 /**
  * {@link https://json-schema.org/draft/2020-12/json-schema-core | JSON Schema} representation of a tree schema.
@@ -221,10 +223,10 @@ export interface JsonFieldSchema {
  * @sealed
  * @alpha
  */
-export interface JsonTreeSchema extends JsonFieldSchema {
+export type JsonTreeSchema = JsonFieldSchema & {
 	/**
 	 * The set of definitions reachable from this schema's root.
 	 * @see {@link https://json-schema.org/draft/2020-12/json-schema-core#name-schema-re-use-with-defs}
 	 */
 	readonly $defs: Record<JsonSchemaId, JsonNodeSchema>;
-}
+};

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

@@ -100,7 +100,7 @@ export function schemaFromValue(value: TreeValue): TreeNodeSchema {
 /**
  * The name of a schema produced by {@link SchemaFactory}, including its optional scope prefix.
  *
- * @public
+ * @system @public
  */
 export type ScopedSchemaName<
 	TScope extends string | undefined,
@@ -134,17 +134,46 @@ export type ScopedSchemaName<
  * The usage below generalizes this to include array and map like objects as well.
  *
  * There are two ways to use these APIs:
- * |                     | Customizable | POJO Emulation |
- * | ------------------- | ------------ |--------------- |
- * | Declaration         | `class X extends schemaFactory.object("x", {}) {}` | `const X = schemaFactory.object("x", {}); type X = NodeFromSchema<typeof X>; `
- * | Allows adding "local" (non-persisted) members | Yes. Members (including methods) can be added to class.        | No. Attempting to set non-field members will error. |
- * | Prototype | The user defined class | `Object.prototype`, `Map.prototype` or `Array.prototype` depending on node kind |
- * | Structurally named Schema | Not Supported | Supported |
- * | Explicitly named Objects | Supported | Supported |
- * | Explicitly named Maps and Arrays | Supported: Both declaration approaches can be used | Not Supported |
- * | node.js assert.deepEqual | Compares like class instances: equal to other nodes of the same type with the same content, including custom local fields. | Compares like plain objects: equal to plain JavaScript objects with the same fields, and other nodes with the same fields, even if the types are different. |
- * | IntelliSense | Shows and links to user defined class by name: `X` | Shows internal type generation logic: `object & TreeNode & ObjectFromSchemaRecord<{}> & WithType<"test.x">` |
- * | Recursion | Supported with special declaration patterns. | Unsupported: Generated d.ts files replace recursive references with `any`, breaking use of recursive schema across compilation boundaries |
+ *
+ * Customizable Approach:
+ *
+ * 1. Declaration: `class X extends schemaFactory.object("x", {}) {}`
+ *
+ * 2. Allows adding "local" (non-persisted) members: Yes. Members (including methods) can be added to the class.
+ *
+ * 3. Prototype: The user-defined class.
+ *
+ * 4. Structurally named Schema: Not Supported.
+ *
+ * 5. Explicitly named Objects: Supported.
+ *
+ * 6. Explicitly named Maps and Arrays: Supported: Both declaration approaches can be used.
+ *
+ * 7. Node.js `assert.deepEqual`: Compares like class instances: equal to other nodes of the same type with the same content, including custom local fields.
+ *
+ * 8. IntelliSense: Shows and links to user-defined class by name: `X`.
+ *
+ * 9. Recursion: Supported with special declaration patterns.
+ *
+ * POJO Emulation Approach:
+ *
+ * 1. Declaration: `const X = schemaFactory.object("x", {}); type X = NodeFromSchema<typeof X>;`
+ *
+ * 2. Allows adding "local" (non-persisted) members: No. Attempting to set non-field members will result in an error.
+ *
+ * 3. Prototype: `Object.prototype`, `Map.prototype`, or `Array.prototype` depending on node kind.
+ *
+ * 4. Structurally named Schema: Supported.
+ *
+ * 5. Explicitly named Objects: Supported.
+ *
+ * 6. Explicitly named Maps and Arrays: Not Supported.
+ *
+ * 7. Node.js `assert.deepEqual`: Compares like plain objects: equal to plain JavaScript objects with the same fields, and other nodes with the same fields, even if the types are different.
+ *
+ * 8. IntelliSense: Shows internal type generation logic: `object & TreeNode & ObjectFromSchemaRecord<{}> & WithType<"test.x">`.
+ *
+ * 9. Recursion: Unsupported: Generated `.d.ts` files replace recursive references with `any`, breaking the use of recursive schema across compilation boundaries.
  *
  * Note that while "POJO Emulation" nodes act a lot like POJO objects, they are not true POJO objects:
  *
@@ -165,6 +194,8 @@ export type ScopedSchemaName<
  * Allowing (or banning) custom/out-of-schema properties on the class is also possible in both modes: it could be orthogonal.
  * Also for consistency, if keeping the current approach to detecting `POJO Emulation` mode it might make sense to make explicitly named Maps and Arrays do the detection the same as how object does it.
  *
+ * Note: the comparison between the customizable and POJO modes is not done in a table because TSDoc does not currently have support for embedded markdown.
+ *
  * @sealed @public
  */
 export class SchemaFactory<
@@ -521,11 +552,14 @@ export class SchemaFactory<
 	 *
 	 * @param t - The types allowed under the field.
 	 * @param props - Optional properties to associate with the field.
+	 *
+	 * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.
+	 * See {@link FieldSchemaMetadata.custom}.
 	 */
-	public optional<const T extends ImplicitAllowedTypes>(
+	public optional<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
 		t: T,
-		props?: Omit<FieldProps, "defaultProvider">,
-	): FieldSchema<FieldKind.Optional, T> {
+		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	): FieldSchema<FieldKind.Optional, T, TCustomMetadata> {
 		const defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => {
 			return undefined;
 		});
@@ -544,11 +578,14 @@ export class SchemaFactory<
 	 * @remarks
 	 * Fields are required by default, but this API can be used to make the required nature explicit in the schema,
 	 * and allows associating custom {@link FieldProps | properties} with the field.
+	 *
+	 * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.
+	 * See {@link FieldSchemaMetadata.custom}.
 	 */
-	public required<const T extends ImplicitAllowedTypes>(
+	public required<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
 		t: T,
-		props?: Omit<FieldProps, "defaultProvider">,
-	): FieldSchema<FieldKind.Required, T> {
+		props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">,
+	): FieldSchema<FieldKind.Required, T, TCustomMetadata> {
 		return createFieldSchema(FieldKind.Required, t, props);
 	}
 
@@ -748,7 +785,7 @@ export function structuralName<const T extends string>(
 		names.sort();
 		// Ensure name can't have collisions by quoting and escaping any quotes in the names of types.
 		// Using JSON is a simple way to accomplish this.
-		// The outer `[]` around the result are also needed so that a single type name "Any" would not collide with the "any" case above.
+		// The outer `[]` around the result were needed so that a single type name "Any" would not collide with the "any" case which used to exist.
 		inner = JSON.stringify(names);
 	}
 	return `${collectionName}<${inner}>`;

package/src/simple-tree/{simpleSchema.ts → api/simpleSchema.ts}

@@ -3,9 +3,9 @@
  * Licensed under the MIT License.
  */
 
-import type { ValueSchema } from "../core/index.js";
-import type { NodeKind } from "./core/index.js";
-import type { FieldKind } from "./schemaTypes.js";
+import type { ValueSchema } from "../../core/index.js";
+import type { NodeKind } from "../core/index.js";
+import type { FieldKind } from "../schemaTypes.js";
 
 /**
  * Base interface for all {@link SimpleNodeSchema} implementations.
@@ -28,7 +28,7 @@ export interface SimpleNodeSchemaBase<TNodeKind extends NodeKind> {
  */
 export interface SimpleObjectNodeSchema extends SimpleNodeSchemaBase<NodeKind.Object> {
 	/**
-	 * Schemas for each of the object's fields, keyed off of schema's view keys.
+	 * Schemas for each of the object's fields, keyed off of schema's property keys.
 	 */
 	readonly fields: Record<string, SimpleFieldSchema>;
 }
@@ -110,6 +110,11 @@ export interface SimpleFieldSchema {
 	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
 	 */
 	readonly allowedTypes: ReadonlySet<string>;
+
+	/**
+	 * {@inheritDoc FieldSchemaMetadata.description}
+	 */
+	readonly description?: string | undefined;
 }
 
 /**

package/src/simple-tree/{simpleSchemaToJsonSchema.ts → api/simpleSchemaToJsonSchema.ts}

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { unreachableCase } from "@fluidframework/core-utils/internal";
+import { oob, unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import { ValueSchema } from "../core/index.js";
-import { getOrCreate } from "../util/index.js";
+import { ValueSchema } from "../../core/index.js";
+import { getOrCreate, type Mutable } from "../../util/index.js";
 import type {
 	JsonArrayNodeSchema,
 	JsonFieldSchema,
@@ -19,7 +19,7 @@ import type {
 	JsonTreeSchema,
 	JsonLeafSchemaType,
 } from "./jsonSchema.js";
-import { FieldKind } from "./schemaTypes.js";
+import { FieldKind } from "../schemaTypes.js";
 import type {
 	SimpleArrayNodeSchema,
 	SimpleLeafNodeSchema,
@@ -28,7 +28,7 @@ import type {
 	SimpleObjectNodeSchema,
 	SimpleTreeSchema,
 } from "./simpleSchema.js";
-import { NodeKind } from "./core/index.js";
+import { NodeKind } from "../core/index.js";
 
 /**
  * Generates a JSON Schema representation from a simple tree schema.
@@ -37,15 +37,20 @@ import { NodeKind } from "./core/index.js";
 export function toJsonSchema(schema: SimpleTreeSchema): JsonTreeSchema {
 	const definitions = convertDefinitions(schema.definitions);
 
-	const anyOf: JsonSchemaRef[] = [];
+	const allowedTypes: JsonSchemaRef[] = [];
 	for (const allowedType of schema.allowedTypes) {
-		anyOf.push(createSchemaRef(allowedType));
+		allowedTypes.push(createSchemaRef(allowedType));
 	}
 
-	return {
-		$defs: definitions,
-		anyOf,
-	};
+	return allowedTypes.length === 1
+		? {
+				...(allowedTypes[0] ?? oob()),
+				$defs: definitions,
+			}
+		: {
+				$defs: definitions,
+				anyOf: allowedTypes,
+			};
 }
 
 function convertDefinitions(
@@ -90,12 +95,14 @@ function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSch
 	schema.allowedTypes.forEach((type) => {
 		allowedTypes.push(createSchemaRef(type));
 	});
+
+	const items: JsonFieldSchema =
+		allowedTypes.length === 1 ? allowedTypes[0] ?? oob() : { anyOf: allowedTypes };
+
 	return {
 		type: "array",
 		_treeNodeSchemaKind: NodeKind.Array,
-		items: {
-			anyOf: allowedTypes,
-		},
+		items,
 	};
 }
 
@@ -130,14 +137,25 @@ function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNode
 	const properties: Record<string, JsonFieldSchema> = {};
 	const required: string[] = [];
 	for (const [key, value] of Object.entries(schema.fields)) {
-		const anyOf: JsonSchemaRef[] = [];
+		const allowedTypes: JsonSchemaRef[] = [];
 		for (const allowedType of value.allowedTypes) {
-			anyOf.push(createSchemaRef(allowedType));
+			allowedTypes.push(createSchemaRef(allowedType));
+		}
+
+		const output: Mutable<JsonFieldSchema> =
+			allowedTypes.length === 1
+				? allowedTypes[0] ?? oob()
+				: {
+						anyOf: allowedTypes,
+					};
+
+		// Don't include "description" property at all if it's not present in the input.
+		if (value.description !== undefined) {
+			output.description = value.description;
 		}
 
-		properties[key] = {
-			anyOf,
-		};
+		properties[key] = output;
+
 		if (value.kind === FieldKind.Required) {
 			required.push(key);
 		}
@@ -160,9 +178,12 @@ function convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {
 		type: "object",
 		_treeNodeSchemaKind: NodeKind.Map,
 		patternProperties: {
-			"^.*$": {
-				anyOf: allowedTypes,
-			},
+			"^.*$":
+				allowedTypes.length === 1
+					? allowedTypes[0] ?? oob()
+					: {
+							anyOf: allowedTypes,
+						},
 		},
 	};
 }

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

@@ -6,18 +6,14 @@
 import type { IFluidLoadable, IDisposable } from "@fluidframework/core-interfaces";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import type { CommitMetadata } from "../../core/index.js";
+import type { CommitMetadata, RevertibleFactory } from "../../core/index.js";
 import type { Listenable } from "../../events/index.js";
-import type { RevertibleFactory } from "../../shared-tree/index.js";
 
 import {
-	type ImplicitAllowedTypes,
-	normalizeFieldSchema,
 	type ImplicitFieldSchema,
 	type InsertableTreeFieldFromImplicitField,
 	type TreeFieldFromImplicitField,
 	FieldKind,
-	normalizeAllowedTypes,
 } from "../schemaTypes.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import { toFlexSchema } from "../toFlexSchema.js";
@@ -27,6 +23,7 @@ import { isObjectNodeSchema, type ObjectNodeSchema } from "../objectNodeTypes.js
 import { markSchemaMostDerived } from "./schemaFactory.js";
 import { fail, getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
+import { walkFieldSchema } from "../walkSchema.js";
 /**
  * Channel for a Fluid Tree DDS.
  * @remarks
@@ -343,72 +340,6 @@ export function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): v
 	}
 }
 
-export function walkNodeSchema(
-	schema: TreeNodeSchema,
-	visitor: SchemaVisitor,
-	visitedSet: Set<TreeNodeSchema>,
-): void {
-	if (visitedSet.has(schema)) {
-		return;
-	}
-	visitedSet.add(schema);
-	if (schema instanceof LeafNodeSchema) {
-		// nothing to do
-	} else if (isObjectNodeSchema(schema)) {
-		for (const field of schema.fields.values()) {
-			walkFieldSchema(field, visitor, visitedSet);
-		}
-	} else {
-		assert(
-			schema.kind === NodeKind.Array || schema.kind === NodeKind.Map,
-			0x9b3 /* invalid schema */,
-		);
-		const childTypes = schema.info as ImplicitAllowedTypes;
-		walkAllowedTypes(normalizeAllowedTypes(childTypes), visitor, visitedSet);
-	}
-	// This visit is done at the end so the traversal order is most inner types first.
-	// This was picked since when fixing errors,
-	// working from the inner types out to the types that use them will probably go better than the reverse.
-	// This does not however ensure all types referenced by a type are visited before it, since in recursive cases thats impossible.
-	visitor.node?.(schema);
-}
-
-export function walkFieldSchema(
-	schema: ImplicitFieldSchema,
-	visitor: SchemaVisitor,
-	visitedSet: Set<TreeNodeSchema> = new Set(),
-): void {
-	walkAllowedTypes(normalizeFieldSchema(schema).allowedTypeSet, visitor, visitedSet);
-}
-
-export function walkAllowedTypes(
-	allowedTypes: Iterable<TreeNodeSchema>,
-	visitor: SchemaVisitor,
-	visitedSet: Set<TreeNodeSchema>,
-): void {
-	for (const childType of allowedTypes) {
-		walkNodeSchema(childType, visitor, visitedSet);
-	}
-	visitor.allowedTypes?.(allowedTypes);
-}
-
-/**
- * Callbacks for use in {@link walkFieldSchema} / {@link walkAllowedTypes} / {@link walkNodeSchema}.
- */
-export interface SchemaVisitor {
-	/**
-	 * Called once for each node schema.
-	 */
-	node?: (schema: TreeNodeSchema) => void;
-	/**
-	 * Called once for each set of allowed types.
-	 * Includes implicit allowed types (when a single type was used instead of an array).
-	 *
-	 * This includes every field, but also the allowed types array for maps and arrays and the root if starting at {@link walkAllowedTypes}.
-	 */
-	allowedTypes?: (allowedTypes: Iterable<TreeNodeSchema>) => void;
-}
-
 /**
  * An editable view of a (version control style) branch of a shared tree based on some schema.
  *
@@ -480,6 +411,11 @@ export interface TreeView<TSchema extends ImplicitFieldSchema> extends IDisposab
 	 * Events for the tree.
 	 */
 	readonly events: Listenable<TreeViewEvents>;
+
+	/**
+	 * The view schema used by this TreeView.
+	 */
+	readonly schema: TSchema;
 }
 
 /**

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

@@ -0,0 +1,101 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { NodeKind, TreeChangeEvents, TreeNode, WithType } from "../core/index.js";
+import { treeNodeApi } from "./treeNodeApi.js";
+
+/**
+ * Data included for {@link TreeChangeEventsBeta.nodeChanged}.
+ * @sealed @beta
+ */
+export interface NodeChangedData<TNode extends TreeNode = TreeNode> {
+	/**
+	 * When the node changed is an object or Map node, this lists all the properties which changed.
+	 * @remarks
+	 * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).
+	 *
+	 * Set to `undefined` when the {@link NodeKind} does not support this feature (currently just ArrayNodes).
+	 *
+	 * When defined, the set should never be empty, since `nodeChanged` will only be triggered when there is a change, and for the supported node types, the only things that can change are properties.
+	 */
+	readonly changedProperties?: ReadonlySet<
+		// For Object nodes, make changedProperties required and strongly typed with the property names from the schema:
+		TNode extends WithType<string, NodeKind.Object, infer TInfo>
+			? string & keyof TInfo
+			: string
+	>;
+}
+
+/**
+ * Extensions to {@link TreeChangeEvents} which are not yet stable.
+ *
+ * @sealed @beta
+ */
+export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>
+	extends TreeChangeEvents {
+	/**
+	 * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.
+	 *
+	 * - Object nodes define a change as being when the value of one of its properties changes (i.e., the property's value is set, including when set to `undefined`).
+	 *
+	 * - Array nodes define a change as when an element is added, removed, moved or replaced.
+	 *
+	 * - Map nodes define a change as when an entry is added, updated, or removed.
+	 *
+	 * @remarks
+	 * This event is not emitted when:
+	 *
+	 * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing
+	 * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the
+	 * array/map node as one of its properties.
+	 *
+	 * - The node is moved to a different location in the tree or removed from the tree.
+	 * In this case the event is emitted on the _parent_ node, not the node itself.
+	 *
+	 * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
+	 * the client that made the original edit.
+	 *
+	 * When the event is emitted, the tree is guaranteed to be in-schema.
+	 *
+	 * @privateRemarks
+	 * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.
+	 * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the
+	 * node, or when the node has to be updated due to resolution of a merge conflict
+	 * (for example a previously applied local change might be undone, then reapplied differently or not at all).
+	 *
+	 * TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).
+	 *
+	 * This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.
+	 */
+	nodeChanged: (
+		data: NodeChangedData<TNode> &
+			// For object and Map nodes, make properties specific to them required instead of optional:
+			(TNode extends WithType<string, NodeKind.Map | NodeKind.Object>
+				? Required<Pick<NodeChangedData<TNode>, "changedProperties">>
+				: unknown),
+	) => void;
+}
+
+/**
+ * Extensions to {@link Tree} which are not yet stable.
+ * @sealed @beta
+ */
+export const TreeBeta = {
+	/**
+	 * Register an event listener on the given node.
+	 * @param node - The node whose events should be subscribed to.
+	 * @param eventName - Which event to subscribe to.
+	 * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.
+	 * @returns A callback function which will deregister the event.
+	 * This callback should be called only once.
+	 */
+	on<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(
+		node: TNode,
+		eventName: K,
+		listener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,
+	): () => void {
+		return treeNodeApi.on(node, eventName, listener);
+	},
+} as const;