@fluidframework/tree 2.1.0 → 2.3.0-288113

package/src/simple-tree/schemaTypes.ts

@@ -14,149 +14,29 @@ import {
 	type FlexListToUnion,
 } from "../feature-libraries/index.js";
 import { type MakeNominal, brand, isReadonlyArray } from "../util/index.js";
-import type { InternalTreeNode, Unhydrated } from "./types.js";
+import type {
+	Unhydrated,
+	NodeKind,
+	TreeNodeSchema,
+	TreeNodeSchemaClass,
+} from "./core/index.js";
 import type { FieldKey } from "../core/index.js";
 import type { InsertableContent } from "./proxies.js";
 
 /**
- * Schema for a tree node.
- * @typeParam Name - The full (including scope) name/identifier for the schema.
- * @typeParam Kind - Which kind of node this schema is for.
- * @typeParam TNode - API for nodes that use this schema.
- * @typeParam TBuild - Data which can be used to construct an {@link Unhydrated} node of this type.
- * @typeParam Info - Data used when defining this schema.
- * @remarks
- * Captures the schema both as runtime data and compile time type information.
- * @sealed @public
- */
-export type TreeNodeSchema<
-	Name extends string = string,
-	Kind extends NodeKind = NodeKind,
-	TNode = unknown,
-	TBuild = never,
-	ImplicitlyConstructable extends boolean = boolean,
-	Info = unknown,
-> =
-	| TreeNodeSchemaClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>
-	| TreeNodeSchemaNonClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>;
-
-/**
- * Schema which is not a class.
- * @remarks
- * This is used for schema which cannot have their instances constructed using constructors, like leaf schema.
- * @privateRemarks
- * Non-class based schema can have issues with recursive types due to https://github.com/microsoft/TypeScript/issues/55832.
- * @sealed @public
+ * Returns true if the given schema is a {@link TreeNodeSchemaClass}, or otherwise false if it is a {@link TreeNodeSchemaNonClass}.
  */
-export interface TreeNodeSchemaNonClass<
-	out Name extends string = string,
-	out Kind extends NodeKind = NodeKind,
-	out TNode = unknown,
-	in TInsertable = never,
-	out ImplicitlyConstructable extends boolean = boolean,
-	out Info = unknown,
-> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {
-	create(data: TInsertable): TNode;
-}
-
-/**
- * Tree node schema which is implemented using a class.
- * @remarks
- * Instances of this class are nodes in the tree.
- * This is also a constructor so that it can be subclassed.
- *
- * Using classes in this way allows introducing a named type and a named value at the same time, helping keep the runtime and compile time information together and easy to refer to un a uniform way.
- * Additionally, this works around https://github.com/microsoft/TypeScript/issues/55832 which causes similar patterns with less explicit types to infer "any" in the d.ts file.
- *
- * When sub-classing a a `TreeNodeSchemaClass`, some extra rules must be followed:
- *
- * - Only ever use a single class from the schema's class hierarchy within a document and its schema.
- * For example, if using {@link SchemaFactory.object} you can do:
- * ```typescript
- * // Recommended "customizable" object schema pattern.
- * class Good extends schemaFactory.object("A", {
- * 	exampleField: schemaFactory.number,
- * }) {
- * 	public exampleCustomMethod(): void {
- * 		this.exampleField++;
- * 	}
- * }
- * ```
- * But should avoid:
- * ```typescript
- * // This by itself is ok, and opts into "POJO mode".
- * const base = schemaFactory.object("A", {});
- * // This is a bad pattern since it leaves two classes in scope which derive from the same SchemaFactory defined class.
- * // If both get used, its an error!
- * class Invalid extends base {}
- * ```
- * - Do not modify the constructor input parameter types or values:
- * ```typescript
- * class Invalid extends schemaFactory.object("A", {
- * 	exampleField: schemaFactory.number,
- * }) {
- * 	// This Modifies the type of the constructor input.
- * 	// This is unsupported due to programmatic access to the constructor being used internally.
- * 	public constructor(a: number) {
- * 		super({ exampleField: a });
- * 	}
- * }
- * ```
- * @sealed @public
- */
-export interface TreeNodeSchemaClass<
-	out Name extends string = string,
-	out Kind extends NodeKind = NodeKind,
-	out TNode = unknown,
-	in TInsertable = never,
-	out ImplicitlyConstructable extends boolean = boolean,
-	out Info = unknown,
-> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {
-	/**
-	 * Constructs an {@link Unhydrated} node with this schema.
-	 * @remarks
-	 * This constructor is also used internally to construct hydrated nodes with a different parameter type.
-	 * Therefore, overriding this constructor with different argument types is not type-safe and is not supported.
-	 * @sealed
-	 */
-	new (data: TInsertable | InternalTreeNode): Unhydrated<TNode>;
-}
-
-/**
- * Data common to all tree node schema.
- * @remarks
- * Implementation detail of {@link TreeNodeSchema} which should be accessed instead of referring to this type directly.
- * @sealed @public
- */
-export interface TreeNodeSchemaCore<
-	out Name extends string,
-	out Kind extends NodeKind,
-	out ImplicitlyConstructable extends boolean,
-	out Info = unknown,
-> {
-	readonly identifier: Name;
-	readonly kind: Kind;
-
-	/**
-	 * Data used to define this schema.
-	 *
-	 * @remarks
-	 * The format depends on the kind of node it is for.
-	 * For example, the "object" node kind could store the field schema here.
-	 */
-	readonly info: Info;
-
-	/**
-	 * When constructing insertable content,
-	 * data that could be passed to the node's constructor can be used instead of an {@link Unhydrated} node
-	 * iff implicitlyConstructable is true.
-	 * @privateRemarks
-	 * Currently the logic for traversing insertable content,
-	 * both to build trees and to hydrate them does not defer to the schema classes to handle the policy,
-	 * so if their constructors differ from what is supported, some cases will not work.
-	 * Setting this to false adjusts the insertable types to disallow cases which could be impacted by these inconsistencies.
-	 */
-	readonly implicitlyConstructable: ImplicitlyConstructable;
+export function isTreeNodeSchemaClass<
+	Name extends string,
+	Kind extends NodeKind,
+	TNode,
+	TBuild,
+	ImplicitlyConstructable extends boolean,
+	Info,
+>(
+	schema: TreeNodeSchema<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>,
+): schema is TreeNodeSchemaClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info> {
+	return schema.constructor !== undefined;
 }
 
 /**
@@ -195,33 +75,6 @@ export enum FieldKind {
 	Identifier,
 }
 
-/**
- * Kind of tree node.
- * @remarks
- * More kinds may be added over time, so do not assume this is an exhaustive set.
- * @public
- */
-export enum NodeKind {
-	/**
-	 * A node which serves as a map, storing children under string keys.
-	 */
-	Map,
-	/**
-	 * A node which serves as an array, storing children in an ordered sequence.
-	 */
-	Array,
-	/**
-	 * A node which stores a heterogenous collection of children in named fields.
-	 * @remarks
-	 * Each field gets its own schema.
-	 */
-	Object,
-	/**
-	 * A node which stores a single leaf value.
-	 */
-	Leaf,
-}
-
 /**
  * Maps from a view key to its corresponding {@link FieldProps.key | stored key} for the provided
  * {@link ImplicitFieldSchema | field schema}.
@@ -387,7 +240,7 @@ export class FieldSchema<
 	 * This class is used with instanceof, and therefore should have nominal typing.
 	 * This field enforces that.
 	 */
-	protected _typeCheck?: MakeNominal;
+	protected _typeCheck!: MakeNominal;
 
 	private readonly lazyTypes: Lazy<ReadonlySet<TreeNodeSchema>>;
 
@@ -399,6 +252,11 @@ export class FieldSchema<
 		return this.lazyTypes.value;
 	}
 
+	/**
+	 * True if and only if, when constructing a node with this field, a value must be provided for it.
+	 */
+	public readonly requiresValue: boolean;
+
 	private constructor(
 		/**
 		 * The {@link https://en.wikipedia.org/wiki/Kind_(type_theory) | kind } of this field.
@@ -415,6 +273,9 @@ export class FieldSchema<
 		public readonly props?: FieldProps,
 	) {
 		this.lazyTypes = new Lazy(() => normalizeAllowedTypes(this.allowedTypes));
+		// TODO: optional fields should (by default) get a default provider that returns undefined, removing the need to special case them here:
+		this.requiresValue =
+			this.props?.defaultProvider === undefined && this.kind !== FieldKind.Optional;
 	}
 }
 
@@ -572,35 +433,9 @@ export type NodeBuilderData<T extends TreeNodeSchema> = T extends TreeNodeSchema
 
 /**
  * Value that may be stored as a leaf node.
+ * @remarks
+ * Some limitations apply, see the documentation for {@link SchemaFactory.number} and {@link SchemaFactory.string} for those restrictions.
  * @public
  */
 // eslint-disable-next-line @rushstack/no-new-null
 export type TreeLeafValue = number | string | boolean | IFluidHandle | null;
-
-/**
- * The type of a {@link TreeNode}.
- * For more information about the type, use `Tree.schema(theNode)` instead.
- * @remarks
- * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.
- * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.
- *
- * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where nodes are expected.
- * Instead construct a real node of the desired type using its constructor.
- * @privateRemarks
- * This prevents non-nodes from being accidentally used as nodes, as well as allows the type checker to distinguish different node types.
- * @public
- */
-export const typeNameSymbol: unique symbol = Symbol("TreeNode Type");
-
-/**
- * Adds a type symbol to a type for stronger typing.
- * @remarks
- * An implementation detail of {@link TreeNode}'s strong typing setup: not intended for direct use outside of this package.
- * @sealed @public
- */
-export interface WithType<TName extends string = string> {
-	/**
-	 * Type symbol, marking a type in a way to increase type safety via strong type checking.
-	 */
-	get [typeNameSymbol](): TName;
-}

package/src/simple-tree/simpleSchema.ts

@@ -0,0 +1,138 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * 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";
+
+/**
+ * Base interface for all {@link SimpleNodeSchema} implementations.
+ *
+ * @sealed
+ */
+export interface SimpleNodeSchemaBase<TNodeKind extends NodeKind> {
+	/**
+	 * The kind of {@link SimpleNodeSchema}.
+	 *
+	 * @remarks can be used to type-switch between implementations.
+	 */
+	readonly kind: TNodeKind;
+}
+
+/**
+ * A {@link SimpleNodeSchema} for an object node.
+ *
+ * @sealed
+ */
+export interface SimpleObjectNodeSchema extends SimpleNodeSchemaBase<NodeKind.Object> {
+	/**
+	 * Schemas for each of the object's fields, keyed off of schema's view keys.
+	 */
+	readonly fields: Record<string, SimpleFieldSchema>;
+}
+
+/**
+ * A {@link SimpleNodeSchema} for an array node.
+ *
+ * @sealed
+ */
+export interface SimpleArrayNodeSchema extends SimpleNodeSchemaBase<NodeKind.Array> {
+	/**
+	 * The types allowed in the array.
+	 *
+	 * @remarks Refers to the types by identifier.
+	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
+	 */
+	readonly allowedTypes: ReadonlySet<string>;
+}
+
+/**
+ * A {@link SimpleNodeSchema} for a map node.
+ *
+ * @sealed
+ */
+export interface SimpleMapNodeSchema extends SimpleNodeSchemaBase<NodeKind.Map> {
+	/**
+	 * The types allowed as values in the map.
+	 *
+	 * @remarks Refers to the types by identifier.
+	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
+	 */
+	readonly allowedTypes: ReadonlySet<string>;
+}
+
+/**
+ * A {@link SimpleNodeSchema} for a leaf node.
+ *
+ * @sealed
+ */
+export interface SimpleLeafNodeSchema extends SimpleNodeSchemaBase<NodeKind.Leaf> {
+	/**
+	 * The kind of leaf node.
+	 */
+	readonly leafKind: ValueSchema;
+}
+
+/**
+ * A simple, shallow representation of a schema for a node.
+ *
+ * @remarks This definition is incomplete, and references child types by identifiers.
+ * To be useful, this generally needs to be used as a part of a complete {@link SimpleTreeSchema}, which
+ * contains backing {@link SimpleTreeSchema.definitions} for each referenced identifier.
+ */
+export type SimpleNodeSchema =
+	| SimpleLeafNodeSchema
+	| SimpleMapNodeSchema
+	| SimpleArrayNodeSchema
+	| SimpleObjectNodeSchema;
+
+/**
+ * A simple, shallow representation of a schema for a field.
+ *
+ * @remarks This definition is incomplete, and references child types by identifiers.
+ * To be useful, this generally needs to be used as a part of a complete {@link SimpleTreeSchema}, which
+ * contains backing {@link SimpleTreeSchema.definitions} for each referenced identifier.
+ *
+ * @sealed
+ */
+export interface SimpleFieldSchema {
+	/**
+	 * The kind of object field.
+	 */
+	readonly kind: FieldKind;
+
+	/**
+	 * The types allowed under the field.
+	 *
+	 * @remarks Refers to the types by identifier.
+	 * A {@link SimpleTreeSchema} is needed to resolve these identifiers to their schema {@link SimpleTreeSchema.definitions}.
+	 */
+	readonly allowedTypes: ReadonlySet<string>;
+}
+
+/**
+ * A simplified representation of a schema for a tree.
+ *
+ * @remarks Contains the complete set of schema {@link SimpleTreeSchema.definitions} required to resolve references
+ * by schema identifier.
+ *
+ * @sealed
+ */
+export interface SimpleTreeSchema {
+	/**
+	 * The complete set of node schema definitions recursively referenced by the tree's {@link SimpleTreeSchema.allowedTypes}.
+	 *
+	 * @remarks the keys are the schemas' {@link TreeNodeSchemaCore.identifier | identifiers}.
+	 */
+	readonly definitions: ReadonlyMap<string, SimpleNodeSchema>;
+
+	/**
+	 * The types allowed under the root of the tree.
+	 *
+	 * @remarks Refers to the types by identifier.
+	 * {@link SimpleTreeSchema.definitions} can be used to resolve these identifiers to their associated schema definition.
+	 */
+	readonly allowedTypes: ReadonlySet<string>;
+}

package/src/simple-tree/simpleSchemaToJsonSchema.ts

@@ -0,0 +1,178 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { 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 type {
+	JsonArrayNodeSchema,
+	JsonFieldSchema,
+	JsonSchemaRef,
+	JsonRefPath,
+	JsonLeafNodeSchema,
+	JsonMapNodeSchema,
+	JsonNodeSchema,
+	JsonObjectNodeSchema,
+	JsonTreeSchema,
+	JsonLeafSchemaType,
+} from "./jsonSchema.js";
+import { FieldKind } from "./schemaTypes.js";
+import type {
+	SimpleArrayNodeSchema,
+	SimpleLeafNodeSchema,
+	SimpleMapNodeSchema,
+	SimpleNodeSchema,
+	SimpleObjectNodeSchema,
+	SimpleTreeSchema,
+} from "./simpleSchema.js";
+import { NodeKind } from "./core/index.js";
+
+/**
+ * Generates a JSON Schema representation from a simple tree schema.
+ * @internal
+ */
+export function toJsonSchema(schema: SimpleTreeSchema): JsonTreeSchema {
+	const definitions = convertDefinitions(schema.definitions);
+
+	const anyOf: JsonSchemaRef[] = [];
+	for (const allowedType of schema.allowedTypes) {
+		anyOf.push(createSchemaRef(allowedType));
+	}
+
+	return {
+		$defs: definitions,
+		anyOf,
+	};
+}
+
+function convertDefinitions(
+	definitions: ReadonlyMap<string, SimpleNodeSchema>,
+): Record<string, JsonNodeSchema> {
+	const result: Record<string, JsonNodeSchema> = {};
+	for (const [key, value] of definitions) {
+		result[key] = convertNodeSchema(value);
+	}
+	return result;
+}
+
+/**
+ * Private symbol under which the results of {@link convertNodeSchema} are cached on an input {@link SimpleNodeSchema}.
+ */
+const nodeJsonSchemaCache = new WeakMap<SimpleNodeSchema, JsonNodeSchema>();
+
+/**
+ * Converts an input {@link SimpleNodeSchema} to a {@link JsonNodeSchema}.
+ *
+ * @remarks Caches the result on the input schema for future calls.
+ */
+function convertNodeSchema(schema: SimpleNodeSchema): JsonNodeSchema {
+	return getOrCreate(nodeJsonSchemaCache, schema, () => {
+		switch (schema.kind) {
+			case NodeKind.Array:
+				return convertArrayNodeSchema(schema);
+			case NodeKind.Leaf:
+				return convertLeafNodeSchema(schema);
+			case NodeKind.Map:
+				return convertMapNodeSchema(schema);
+			case NodeKind.Object:
+				return convertObjectNodeSchema(schema);
+			default:
+				throw new TypeError(`Unknown node schema kind: ${(schema as SimpleNodeSchema).kind}`);
+		}
+	});
+}
+
+function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSchema {
+	const allowedTypes: JsonSchemaRef[] = [];
+	schema.allowedTypes.forEach((type) => {
+		allowedTypes.push(createSchemaRef(type));
+	});
+	return {
+		type: "array",
+		_treeNodeSchemaKind: NodeKind.Array,
+		items: {
+			anyOf: allowedTypes,
+		},
+	};
+}
+
+function convertLeafNodeSchema(schema: SimpleLeafNodeSchema): JsonLeafNodeSchema {
+	let type: JsonLeafSchemaType;
+	switch (schema.leafKind) {
+		case ValueSchema.String:
+			type = "string";
+			break;
+		case ValueSchema.Number:
+			type = "number";
+			break;
+		case ValueSchema.Boolean:
+			type = "boolean";
+			break;
+		case ValueSchema.Null:
+			type = "null";
+			break;
+		case ValueSchema.FluidHandle:
+			throw new UsageError("Fluid handles are not supported via JSON Schema.");
+		default:
+			unreachableCase(schema.leafKind);
+	}
+
+	return {
+		type,
+		_treeNodeSchemaKind: NodeKind.Leaf,
+	};
+}
+
+function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNodeSchema {
+	const properties: Record<string, JsonFieldSchema> = {};
+	const required: string[] = [];
+	for (const [key, value] of Object.entries(schema.fields)) {
+		const anyOf: JsonSchemaRef[] = [];
+		for (const allowedType of value.allowedTypes) {
+			anyOf.push(createSchemaRef(allowedType));
+		}
+
+		properties[key] = {
+			anyOf,
+		};
+		if (value.kind === FieldKind.Required) {
+			required.push(key);
+		}
+	}
+	return {
+		type: "object",
+		_treeNodeSchemaKind: NodeKind.Object,
+		properties,
+		required,
+		additionalProperties: false,
+	};
+}
+
+function convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {
+	const allowedTypes: JsonSchemaRef[] = [];
+	schema.allowedTypes.forEach((type) => {
+		allowedTypes.push(createSchemaRef(type));
+	});
+	return {
+		type: "object",
+		_treeNodeSchemaKind: NodeKind.Map,
+		patternProperties: {
+			"^.*$": {
+				anyOf: allowedTypes,
+			},
+		},
+	};
+}
+
+function createSchemaRef(schemaId: string): JsonSchemaRef {
+	return {
+		"$ref": createRefPath(schemaId),
+	};
+}
+
+function createRefPath(schemaId: string): JsonRefPath {
+	return `#/$defs/${schemaId}`;
+}

package/src/simple-tree/toFlexSchema.ts

@@ -7,73 +7,36 @@
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import type {
-	ITreeCursorSynchronous,
-	TreeNodeSchemaIdentifier,
-	SchemaAndPolicy,
-} from "../core/index.js";
+import { EmptyKey, type TreeNodeSchemaIdentifier } from "../core/index.js";
 import {
 	FieldKinds,
 	type FlexAllowedTypes,
 	type FlexFieldKind,
-	FlexFieldNodeSchema,
 	FlexFieldSchema,
 	FlexMapNodeSchema,
 	FlexObjectNodeSchema,
 	type FlexTreeNodeSchema,
 	type FlexTreeSchema,
-	type NodeKeyManager,
 	TreeNodeSchemaBase,
 	defaultSchemaPolicy,
 	schemaIsLeaf,
 } from "../feature-libraries/index.js";
 import { normalizeFlexListEager } from "../feature-libraries/typed-schema/flexList.js";
 import { brand, fail, isReadonlyArray, mapIterable } from "../util/index.js";
-
-import type { InsertableContent } from "./proxies.js";
 import {
 	cachedFlexSchemaFromClassSchema,
 	setFlexSchemaFromClassSchema,
 	tryGetSimpleNodeSchema,
-} from "./schemaCaching.js";
+	NodeKind,
+	type TreeNodeSchema,
+} from "./core/index.js";
 import {
 	FieldKind,
 	FieldSchema,
 	type ImplicitAllowedTypes,
 	type ImplicitFieldSchema,
-	type InsertableTreeNodeFromImplicitAllowedTypes,
-	NodeKind,
-	type TreeNodeSchema,
-	normalizeFieldSchema,
 	getStoredKey,
 } from "./schemaTypes.js";
-import { cursorFromNodeData } from "./toMapTree.js";
-
-/**
- * Returns a cursor (in nodes mode) for the root node.
- *
- * @privateRemarks
- * Ideally this would work on any node, not just the root,
- * and the schema would come from the unhydrated node.
- * For now though, this is the only case that's needed, and we do have the data to make it work, so this is fine.
- */
-export function cursorFromUnhydratedRoot(
-	schema: ImplicitFieldSchema,
-	tree: InsertableTreeNodeFromImplicitAllowedTypes,
-	nodeKeyManager: NodeKeyManager,
-	schemaValidationPolicy: SchemaAndPolicy | undefined = undefined,
-): ITreeCursorSynchronous {
-	const data = tree as InsertableContent;
-	const normalizedFieldSchema = normalizeFieldSchema(schema);
-	return (
-		cursorFromNodeData(
-			data,
-			normalizedFieldSchema.allowedTypes,
-			nodeKeyManager,
-			schemaValidationPolicy,
-		) ?? fail("failed to decode tree")
-	);
-}
 
 interface SchemaInfo {
 	readonly toFlex: () => FlexTreeNodeSchema;
@@ -219,7 +182,11 @@ export function convertNodeSchema(
 					convertAllowedTypes(schemaMap, fieldInfo),
 				);
 				const cached = cachedFlexSchemaFromClassSchema(schema);
-				out = cached ?? FlexFieldNodeSchema.create(builder, brand(schema.identifier), field);
+				out =
+					cached ??
+					FlexObjectNodeSchema.create(builder, brand(schema.identifier), {
+						[EmptyKey]: field,
+					});
 				break;
 			}
 			case NodeKind.Object: {