@fluidframework/tree 2.50.0 → 2.51.0

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

@@ -4,18 +4,20 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import type { LazyItem } from "../flexList.js";
-import type {
-	AllowedTypeMetadata,
-	AllowedTypesMetadata,
-	AnnotatedAllowedTypes,
-	ImplicitAnnotatedAllowedTypes,
-	TreeLeafValue,
-} from "../schemaTypes.js";
-import type { SimpleNodeSchemaBase } from "../simpleSchema.js";
+import type { IFluidHandle } from "@fluidframework/core-interfaces";
 
+import type { SimpleNodeSchemaBase } from "../simpleSchema.js";
 import type { TreeNode } from "./treeNode.js";
 import type { InternalTreeNode, Unhydrated } from "./types.js";
+import type { UnionToIntersection } from "../../util/index.js";
+import type {
+	ImplicitAnnotatedAllowedTypes,
+	NormalizedAnnotatedAllowedTypes,
+} from "./allowedTypes.js";
+import type { Context } from "./context.js";
+import type { FieldKey, NodeData } from "../../core/index.js";
+import type { UnhydratedFlexTreeField } from "./unhydratedFlexTree.js";
+import type { FactoryContent } from "../unhydratedFlexTreeFromInsertable.js";
 
 /**
  * Schema for a {@link TreeNode} or {@link TreeLeafValue}.
@@ -70,48 +72,6 @@ export type TreeNodeSchema<
 			TCustomMetadata
 	  >;
 
-/**
- * Stores annotations for an individual allowed type.
- * @alpha
- */
-export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
-	/**
-	 * Annotations for the allowed type.
-	 */
-	readonly metadata: AllowedTypeMetadata;
-	/**
-	 * The allowed type the annotations apply to in a particular schema.
-	 */
-	readonly type: T;
-}
-
-/**
- * Stores annotations for a set of evaluated annotated allowed types.
- * @alpha
- */
-export interface NormalizedAnnotatedAllowedTypes {
-	/**
-	 * Annotations that apply to a set of allowed types.
-	 */
-	readonly metadata: AllowedTypesMetadata;
-	/**
-	 * All the evaluated allowed types that the annotations apply to. The types themselves are also individually annotated.
-	 */
-	readonly types: readonly AnnotatedAllowedType<TreeNodeSchema>[];
-}
-
-/**
- * Checks if the input is an {@link AnnotatedAllowedTypes}.
- */
-export function isAnnotatedAllowedTypes(
-	allowedTypes: ImplicitAnnotatedAllowedTypes,
-): allowedTypes is AnnotatedAllowedTypes {
-	return (
-		// Class based schema, and lazy schema references report type "function": filtering them out with typeof makes narrowing based on members mostly safe
-		typeof allowedTypes === "object" && "metadata" in allowedTypes && "types" in allowedTypes
-	);
-}
-
 /**
  * Schema which is not a class.
  * @remarks
@@ -371,6 +331,11 @@ export interface TreeNodeSchemaCore<
 	createFromInsertable(data: TInsertable): Unhydrated<TreeNode | TreeLeafValue>;
 }
 
+/**
+ * Symbol for use by {@link TreeNodeSchemaCorePrivate}.
+ */
+export const privateDataSymbol = Symbol("PrivateData");
+
 /**
  * {@link TreeNodeSchemaCore} extended with some non-exported APIs.
  */
@@ -389,6 +354,56 @@ export interface TreeNodeSchemaCorePrivate<
 		TInsertable,
 		TCustomMetadata
 	> {
+	/**
+	 * Package private data provided by all {@link TreeNodeSchema}.
+	 * @remarks
+	 * Users can add custom statics to schema classes.
+	 * To reduce the risk of such statics colliding with properties used to implement the schema,
+	 * some of the private APIs are grouped together under this symbol.
+	 *
+	 * Note that there are still some properties which are not under a symbol and thus expose some risk of name collisions.
+	 * See {@link TreeNodeValid} for some such properties.
+	 */
+	readonly [privateDataSymbol]: TreeNodeSchemaPrivateData;
+}
+
+/**
+ * Package private data provided by all {@link TreeNodeSchema}.
+ * @remarks
+ * This data needs to be available before lazy schema references are resolved.
+ * For data which is only available after lazy schema references are resolved,
+ * see {@link TreeNodeSchemaInitializedData}, which can be accessed via {@link TreeNodeSchemaPrivateData.idempotentInitialize}.
+ */
+export interface TreeNodeSchemaPrivateData {
+	/**
+	 * All possible annotated allowed types that a field under a node with this schema could have.
+	 * @remarks
+	 * In this case "field" includes anything that is a field in the internal (flex-tree) abstraction layer.
+	 * This includes the content field for arrays, and all the fields for map nodes.
+	 * If this node does not have fields (and thus is a leaf), the array will be empty.
+	 *
+	 * This set cannot be used before the schema in it have been defined:
+	 * more specifically, when using lazy schema references (for example to make foreword references to schema which have not yet been defined),
+	 * users must wait until after the schema are defined to access this array.
+	 *
+	 * @privateRemarks
+	 * If this is stabilized, it will live alongside the childTypes property on {@link TreeNodeSchemaCore}.
+	 * @system
+	 */
+	readonly childAnnotatedAllowedTypes: readonly ImplicitAnnotatedAllowedTypes[];
+
+	/**
+	 * Idempotent initialization function that pre-caches data and can dereference lazy schema references.
+	 */
+	idempotentInitialize(): TreeNodeSchemaInitializedData;
+}
+
+/**
+ * Additional data about a given schema which is private to this package.
+ * @remarks
+ * Created by {@link TreeNodeValid.oneTimeSetup} and can involve dereferencing lazy schema references.
+ */
+export interface TreeNodeSchemaInitializedData {
 	/**
 	 * All possible annotated allowed types that a field under a node with this schema could have.
 	 * @remarks
@@ -405,27 +420,77 @@ export interface TreeNodeSchemaCorePrivate<
 	 * @system
 	 */
 	readonly childAnnotatedAllowedTypes: readonly NormalizedAnnotatedAllowedTypes[];
+
+	/**
+	 * A {@link Context} which can be used for unhydrated nodes of this schema.
+	 */
+	readonly context: Context;
+
+	/**
+	 * Checks if data might be schema-compatible.
+	 *
+	 * @returns false if `data` is incompatible with `type` based on a cheap/shallow check.
+	 *
+	 * Note that this may return true for cases where data is incompatible, but it must not return false in cases where the data is compatible.
+	 */
+	shallowCompatibilityTest(data: FactoryContent): CompatibilityLevel;
+
+	/**
+	 * Convert data to a {@link FlexContent} representation.
+	 * @remarks
+	 * Data must be compatible with the schema according to {@link shallowCompatibilityTest}.
+	 *
+	 * TODO: use of `allowedTypes` is for fallbacks (for example NaN -\> null).
+	 * This behavior should be moved to shallowCompatibilityTest instead.
+	 */
+	toFlexContent(data: FactoryContent, allowedTypes: ReadonlySet<TreeNodeSchema>): FlexContent;
 }
 
+export type FlexContent = [NodeData, Map<FieldKey, UnhydratedFlexTreeField>];
+
 /**
- * Downcasts a {@link TreeNodeSchemaCore} to {@link TreeNodeSchemaCorePrivate} if it is one.
- *
+ * Indicates a compatibility level for inferring a schema to apply to insertable data.
  * @remarks
- * This function should only be used internally. The result should not be exposed publicly
- * in any exported types or API return values.
+ * Each schema allowed at a location in the tree has its compatibility level checked against the data being inserted.
+ * The compatibility is considered unambiguous if there is a single schema with a higher compatibility than all others.
+ *
+ * This approach allows adding new compatible formats as a non breaking change.
+ * If the new format was already compatible with some other schema, it can still be added as non-breaking as long as a lower compatibility level is used.
+ * For example, support for constructing maps from record like objects was added in Fluid Framework 2.2.
+ * This format (an object with fields) was already compatible with Object nodes at compatibility level Normal so the new format support for maps was added at compatibility level Low.
+ * This ensures that existing code that was using object literals as insertable content where both objects and maps were allowed will continue to work,
+ * assuming the objects are intended as ObjectNodes.
+ * However new code can now be written using record like objects to construct maps, as long as the schema does not also allow Object nodes which are compatible with the data in that location.
+ *
+ * @see {@link ITreeConfigurationOptions.preventAmbiguity} for a related setting which interacts with this in a somewhat complex way.
  */
-export function asTreeNodeSchemaCorePrivate(
+export enum CompatibilityLevel {
+	/**
+	 * Not compatible. Constructor typing indicates incompatibility.
+	 */
+	None = 0,
+	/**
+	 * Additional compatibility cases added in Fluid Framework 2.2.
+	 */
+	Low = 1,
+	/**
+	 * Compatible in Fluid Framework 2.0.
+	 */
+	Normal = 2,
+}
+
+/**
+ * Downcasts a {@link TreeNodeSchemaCore} to {@link TreeNodeSchemaCorePrivate} and get its {@link TreeNodeSchemaPrivateData}.
+ */
+export function getTreeNodeSchemaPrivateData(
 	schema: TreeNodeSchemaCore<string, NodeKind, boolean>,
-): TreeNodeSchemaCorePrivate {
+): TreeNodeSchemaPrivateData {
 	assert(
-		"childAnnotatedAllowedTypes" in schema,
+		privateDataSymbol in schema,
 		0xbc9 /* All implementations of TreeNodeSchemaCore must also implement TreeNodeSchemaCorePrivate */,
 	);
-	assert(
-		Array.isArray((schema as TreeNodeSchemaCorePrivate).childAnnotatedAllowedTypes),
-		0xbca /* All implementations of TreeNodeSchemaCore must also implement TreeNodeSchemaCorePrivate */,
-	);
-	return schema as TreeNodeSchemaCorePrivate;
+	const schemaValid = schema as TreeNodeSchemaCorePrivate;
+	return schemaValid[privateDataSymbol];
 }
 
 /**
@@ -458,3 +523,122 @@ export enum NodeKind {
 	 */
 	Record = 4,
 }
+
+/**
+ * Metadata associated with a Node Schema.
+ *
+ * @remarks Specified via {@link NodeSchemaOptions.metadata}.
+ *
+ * @sealed
+ * @public
+ */
+export interface NodeSchemaMetadata<out TCustomMetadata = unknown> {
+	/**
+	 * User-defined metadata.
+	 */
+	readonly custom?: TCustomMetadata | undefined;
+
+	/**
+	 * The description of the Node Schema.
+	 *
+	 * @remarks
+	 *
+	 * If provided, will be used by the system in scenarios where a description of the kind of node is useful.
+	 * E.g., when converting a Node Schema to {@link https://json-schema.org/ | JSON Schema}, this description will be
+	 * used as the `description` property.
+	 */
+	readonly description?: string | undefined;
+}
+
+/**
+ * Returns true if the given schema is a {@link TreeNodeSchemaClass}, or otherwise false if it is a {@link TreeNodeSchemaNonClass}.
+ * @internal
+ */
+export function isTreeNodeSchemaClass<
+	Name extends string,
+	Kind extends NodeKind,
+	TNode extends TreeNode | TreeLeafValue,
+	TBuild,
+	ImplicitlyConstructable extends boolean,
+	Info,
+>(
+	schema:
+		| TreeNodeSchema<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>
+		| TreeNodeSchemaClass<Name, Kind, TNode & TreeNode, TBuild, ImplicitlyConstructable, Info>,
+): schema is TreeNodeSchemaClass<
+	Name,
+	Kind,
+	TNode & TreeNode,
+	TBuild,
+	ImplicitlyConstructable,
+	Info
+> {
+	return schema.constructor !== undefined;
+}
+
+/**
+ * Takes in `TreeNodeSchema[]` and returns a TypedNode union.
+ * @privateRemarks
+ * If a schema is both TreeNodeSchemaClass and TreeNodeSchemaNonClass, prefer TreeNodeSchemaClass since that includes subclasses properly.
+ * @public
+ */
+export type NodeFromSchema<T extends TreeNodeSchema> = T extends TreeNodeSchemaClass<
+	string,
+	NodeKind,
+	infer TNode
+>
+	? TNode
+	: T extends TreeNodeSchemaNonClass<string, NodeKind, infer TNode>
+		? TNode
+		: never;
+
+/**
+ * Data which can be used as a node to be inserted.
+ * Either an unhydrated node, or content to build a new node.
+ *
+ * @see {@link Input}
+ *
+ * @typeparam TSchemaInput - Schema to process.
+ * @typeparam T - Do not specify: default value used as implementation detail.
+ * @privateRemarks
+ * This can't really be fully correct, since TreeNodeSchema's TNode is generally use covariantly but this code uses it contravariantly.
+ * That makes this TreeNodeSchema actually invariant with respect to TNode, but doing that would break all `extends TreeNodeSchema` clauses.
+ * As is, this works correctly in most realistic use-cases.
+ *
+ * One special case this makes is if the result of NodeFromSchema contains TreeNode, this must be an under constrained schema, so the result is set to never.
+ * Note that applying UnionToIntersection on the result of NodeFromSchema<T> does not work since it breaks booleans.
+ *
+ * @public
+ */
+export type InsertableTypedNode<
+	TSchema extends TreeNodeSchema,
+	T = UnionToIntersection<TSchema>,
+> =
+	| (T extends TreeNodeSchema<string, NodeKind, TreeNode | TreeLeafValue, never, true>
+			? NodeBuilderData<T>
+			: never)
+	| (T extends TreeNodeSchema
+			? Unhydrated<TreeNode extends NodeFromSchema<T> ? never : NodeFromSchema<T>>
+			: never);
+
+/**
+ * Given a node's schema, return the corresponding object from which the node could be built.
+ * @privateRemarks
+ * This uses TreeNodeSchemaCore, and thus depends on TreeNodeSchemaCore.createFromInsertable for the typing.
+ * This works almost the same as using TreeNodeSchema,
+ * except that the more complex typing in TreeNodeSchema case breaks for non-class schema and leaks in `undefined` from optional crete parameters.
+ * @system @public
+ */
+export type NodeBuilderData<T extends TreeNodeSchemaCore<string, NodeKind, boolean>> =
+	T extends TreeNodeSchemaCore<string, NodeKind, boolean, unknown, infer TBuild>
+		? TBuild
+		: never;
+
+/**
+ * Value that may be stored as a leaf node.
+ * @remarks
+ * Some limitations apply, see the documentation for {@link SchemaStatics.number} and {@link SchemaStatics.string} for those restrictions.
+ * @public
+ */
+// eslint-disable-next-line @rushstack/no-new-null
+export type TreeLeafValue = number | string | boolean | IFluidHandle | null;

package/src/simple-tree/{treeNodeValid.ts → core/treeNodeValid.ts}

@@ -6,23 +6,27 @@
 import { assert, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { type FlexTreeNode, isFlexTreeNode } from "../feature-libraries/index.js";
+import { type FlexTreeNode, isFlexTreeNode } from "../../feature-libraries/index.js";
 
+import { markEager } from "./flexList.js";
+import { inPrototypeChain, privateToken, TreeNode } from "./treeNode.js";
+import type { UnhydratedFlexTreeNode } from "./unhydratedFlexTree.js";
 import {
-	type TreeNodeSchema,
 	NodeKind,
+	type TreeNodeSchema,
+	type TreeNodeSchemaCore,
+	type TreeNodeSchemaInitializedData,
+	type TreeNodeSchemaPrivateData,
+} from "./treeNodeSchema.js";
+import {
+	getSimpleNodeSchemaFromInnerNode,
 	isTreeNode,
 	TreeNodeKernel,
-	privateToken,
-	TreeNode,
-	type InternalTreeNode,
-	typeSchemaSymbol,
 	type InnerNode,
-	type Context,
-	type UnhydratedFlexTreeNode,
-	getSimpleNodeSchemaFromInnerNode,
-} from "./core/index.js";
-import { markEager } from "./flexList.js";
+} from "./treeNodeKernel.js";
+import type { InternalTreeNode } from "./types.js";
+import { typeSchemaSymbol } from "./withType.js";
+import type { ImplicitAnnotatedAllowedTypes } from "./allowedTypes.js";
 
 /**
  * Class which all {@link TreeNode}s must extend.
@@ -66,7 +70,9 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 	 * @remarks
 	 * It is valid to dereference LazyItem schema references in this function (or anything that runs after it).
 	 */
-	protected static oneTimeSetup<T>(this: typeof TreeNodeValid<T>): Context {
+	protected static oneTimeSetup<T>(
+		this: typeof TreeNodeValid<T>,
+	): TreeNodeSchemaInitializedData {
 		fail(0xae5 /* Missing oneTimeSetup */);
 	}
 
@@ -165,7 +171,7 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 		const cache = this.markMostDerived();
 		cache.oneTimeInitialized ??= this.oneTimeSetup();
 		// TypeScript fails to narrow the type of `oneTimeInitialized` to `Context` here, so use a cast:
-		return cache as MostDerivedData & { oneTimeInitialized: Context };
+		return cache as MostDerivedData & { oneTimeInitialized: TreeNodeSchemaInitializedData };
 	}
 
 	public constructor(input: TInput | InternalTreeNode) {
@@ -190,7 +196,7 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 		// The TreeNodeKernel associates itself the TreeNode (result here, not node) so it can be looked up later via getKernel.
 		// If desired this could be put in a non-enumerable symbol property for lookup instead, but that gets messy going through proxies,
 		// so just relying on the WeakMap seems like the cleanest approach.
-		new TreeNodeKernel(result, schema, node, cache.oneTimeInitialized);
+		new TreeNodeKernel(result, schema, node, cache.oneTimeInitialized.context);
 
 		return result;
 	}
@@ -211,7 +217,45 @@ markEager(TreeNodeValid);
  */
 export interface MostDerivedData {
 	readonly constructor: typeof TreeNodeValid & TreeNodeSchema;
-	oneTimeInitialized?: Context;
+	oneTimeInitialized?: TreeNodeSchemaInitializedData;
+}
+
+/**
+ * Cast `schema` to a {@link TreeNodeValid}, asserting it actually extends it.
+ */
+export function schemaAsTreeNodeValid(
+	schema: TreeNodeSchemaCore<string, NodeKind, boolean>,
+): typeof TreeNodeValid & TreeNodeSchema {
+	if (!inPrototypeChain(schema, TreeNodeValid)) {
+		// Use JSON.stringify to quote and escape identifier string.
+		throw new UsageError(
+			`Schema for ${JSON.stringify(
+				schema.identifier,
+			)} does not extend a SchemaFactory generated class. This is invalid.`,
+		);
+	}
+
+	return schema as typeof TreeNodeValid & TreeNodeSchema;
+}
+
+/**
+ * Provides the {@link TreeNodeSchemaPrivateData} for class based implementations of {@link asTreeNodeSchemaCorePrivate}.
+ * @remarks
+ * Such schema must extends {@link TreeNodeValid}.
+ */
+export function createTreeNodeSchemaPrivateData(
+	schema: TreeNodeSchemaCore<string, NodeKind, boolean>,
+	childAnnotatedAllowedTypes: readonly ImplicitAnnotatedAllowedTypes[],
+): TreeNodeSchemaPrivateData {
+	const schemaValid = schemaAsTreeNodeValid(schema);
+	// Since this closes over the schema, ensure this schema is marked as most derived
+	// so if some other subclass is used later, it will error instead of giving inconsistent results.
+	schemaValid.markMostDerived();
+
+	return {
+		idempotentInitialize: () => schemaValid.oneTimeInitialize().oneTimeInitialized,
+		childAnnotatedAllowedTypes,
+	};
 }
 
 // #region NodeJS custom inspect for TreeNodes.

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

@@ -54,7 +54,7 @@ import {
 import { brand, filterIterable, getOrCreate, mapIterable } from "../../util/index.js";
 
 import type { Context } from "./context.js";
-import type { ContextualFieldProvider } from "../schemaTypes.js";
+import type { ContextualFieldProvider } from "../fieldSchema.js";
 import type { TreeNode } from "./treeNode.js";
 
 interface UnhydratedTreeSequenceFieldEditBuilder

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

@@ -4,10 +4,10 @@
  */
 
 import {
-	asTreeNodeSchemaCorePrivate,
+	normalizeAnnotatedAllowedTypes,
 	type NormalizedAnnotatedAllowedTypes,
-	type TreeNodeSchema,
-} from "./treeNodeSchema.js";
+} from "./allowedTypes.js";
+import { getTreeNodeSchemaPrivateData, type TreeNodeSchema } from "./treeNodeSchema.js";
 
 /**
  * Traverses all {@link TreeNodeSchema} schema reachable from `schema`, applying the visitor pattern.
@@ -23,10 +23,14 @@ export function walkNodeSchema(
 
 	visitedSet.add(schema);
 
-	const annotatedAllowedTypes = asTreeNodeSchemaCorePrivate(schema).childAnnotatedAllowedTypes;
+	// Since walkNodeSchema is used in the implementation of TreeNodeSchemaPrivateData.idempotentInitialize,
+	// Avoid depending on it here to avoid circular dependencies for recursive schema.
+	// Instead normalize/evaluate the allowed types as needed.
+	const annotatedAllowedTypes =
+		getTreeNodeSchemaPrivateData(schema).childAnnotatedAllowedTypes;
 
 	for (const fieldAllowedTypes of annotatedAllowedTypes) {
-		walkAllowedTypes(fieldAllowedTypes, visitor, visitedSet);
+		walkAllowedTypes(normalizeAnnotatedAllowedTypes(fieldAllowedTypes), visitor, visitedSet);
 	}
 
 	// This visit is done at the end so the traversal order is most inner types first.

package/src/simple-tree/createContext.ts

@@ -6,8 +6,15 @@
 import { defaultSchemaPolicy } from "../feature-libraries/index.js";
 import { getOrCreate } from "../util/index.js";
 
-import { Context, UnhydratedContext } from "./core/index.js";
-import { normalizeFieldSchema, type ImplicitFieldSchema } from "./schemaTypes.js";
+import {
+	Context,
+	getTreeNodeSchemaPrivateData,
+	normalizeAnnotatedAllowedTypes,
+	UnhydratedContext,
+	type TreeNodeSchema,
+	type TreeNodeSchemaInitializedData,
+} from "./core/index.js";
+import { normalizeFieldSchema, type ImplicitFieldSchema } from "./fieldSchema.js";
 import { toStoredSchema } from "./toStoredSchema.js";
 
 const contextCache: WeakMap<ImplicitFieldSchema, Context> = new WeakMap();
@@ -23,3 +30,20 @@ export function getUnhydratedContext(schema: ImplicitFieldSchema): Context {
 		return new Context(normalized.annotatedAllowedTypesNormalized, flexContext);
 	});
 }
+
+/**
+ * Utility for creating {@link TreeNodeSchemaInitializedData}.
+ */
+export function getTreeNodeSchemaInitializedData(
+	schema: TreeNodeSchema,
+	handler: Pick<TreeNodeSchemaInitializedData, "toFlexContent" | "shallowCompatibilityTest">,
+): TreeNodeSchemaInitializedData {
+	const data = getTreeNodeSchemaPrivateData(schema);
+	return {
+		...handler,
+		context: getUnhydratedContext(schema),
+		childAnnotatedAllowedTypes: data.childAnnotatedAllowedTypes.map(
+			normalizeAnnotatedAllowedTypes,
+		),
+	};
+}