@fluidframework/tree 2.1.1 → 2.2.1

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: {