@fluidframework/tree 2.52.0 → 2.53.0-350190

package/src/simple-tree/toStoredSchema.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
+import { unreachableCase, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
@@ -20,27 +20,81 @@ import {
 	type TreeTypeSet,
 } from "../core/index.js";
 import { FieldKinds, type FlexFieldKind } from "../feature-libraries/index.js";
-import { brand, getOrCreate } from "../util/index.js";
+import { brand, getOrCreate, type JsonCompatibleReadOnlyObject } from "../util/index.js";
 
-import { NodeKind } from "./core/index.js";
-import { FieldKind, normalizeFieldSchema, type ImplicitFieldSchema } from "./fieldSchema.js";
-import type {
-	SimpleFieldSchema,
-	SimpleNodeSchema,
-	SimpleNodeSchemaBase,
-	SimpleTreeSchema,
-} from "./simpleSchema.js";
+import {
+	allowedTypeFilter,
+	convertAllowedTypes,
+	getTreeNodeSchemaPrivateData,
+	isClassBasedSchema,
+	NodeKind,
+	type SimpleNodeSchemaBase,
+	type StoredSchemaGenerationOptions,
+} from "./core/index.js";
+import {
+	FieldKind,
+	FieldSchemaAlpha,
+	normalizeFieldSchema,
+	type ImplicitAnnotatedFieldSchema,
+	type ImplicitFieldSchema,
+} from "./fieldSchema.js";
+import type { SimpleFieldSchema, SimpleNodeSchema } from "./simpleSchema.js";
 import { walkFieldSchema } from "./walkFieldSchema.js";
 
-const viewToStoredCache = new WeakMap<ImplicitFieldSchema, TreeStoredSchema>();
+const viewToStoredCache = new WeakMap<
+	StoredSchemaGenerationOptions,
+	WeakMap<ImplicitFieldSchema, TreeStoredSchema>
+>();
+
+export const restrictiveStoredSchemaGenerationOptions: StoredSchemaGenerationOptions = {
+	includeStaged: () => false,
+};
+
+export const permissiveStoredSchemaGenerationOptions: StoredSchemaGenerationOptions = {
+	includeStaged: () => true,
+};
+
+/**
+ * Converts a {@link ImplicitAnnotatedFieldSchema} into a {@link TreeStoredSchema} for use in schema upgrades.
+ *
+ * TODO: once upgrades are more flexible, this should take in more options, including the old schema and specific upgrades to enable.
+ */
+export function toUpgradeSchema(root: ImplicitAnnotatedFieldSchema): TreeStoredSchema {
+	return toStoredSchema(root, restrictiveStoredSchemaGenerationOptions);
+}
+
+/**
+ * Converts a {@link ImplicitAnnotatedFieldSchema} into a {@link TreeStoredSchema} for use as initial document schema.
+ */
+export function toInitialSchema(root: ImplicitAnnotatedFieldSchema): TreeStoredSchema {
+	return toStoredSchema(root, restrictiveStoredSchemaGenerationOptions);
+}
+
+/**
+ * Converts a {@link ImplicitAnnotatedFieldSchema} into a {@link TreeStoredSchema} to used for unhydrated nodes.
+ * @remarks
+ * This allows as much as possible, relying on further validation when inserting the content.
+ *
+ * TODO: this should get additional options to enable support for unknown optional fields.
+ */
+export const toUnhydratedSchema = permissiveStoredSchemaGenerationOptions;
 
 /**
- * Converts a {@link ImplicitFieldSchema} into a {@link TreeStoredSchema}.
+ * Converts a {@link ImplicitAnnotatedFieldSchema} into a {@link TreeStoredSchema}.
+ *
+ * @privateRemarks
+ * TODO:#38722 When runtime schema upgrades are implemented, this will need to be updated to check if
+ * a staged allowed type has been upgraded and if so, include it in the conversion.
+ *
  * @throws
  * Throws a `UsageError` if multiple schemas are encountered with the same identifier.
  */
-export function toStoredSchema(root: ImplicitFieldSchema): TreeStoredSchema {
-	return getOrCreate(viewToStoredCache, root, () => {
+export function toStoredSchema(
+	root: ImplicitAnnotatedFieldSchema,
+	options: StoredSchemaGenerationOptions,
+): TreeStoredSchema {
+	const cache = getOrCreate(viewToStoredCache, options, () => new WeakMap());
+	return getOrCreate(cache, root, () => {
 		const normalized = normalizeFieldSchema(root);
 		const nodeSchema: Map<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> = new Map();
 		walkFieldSchema(normalized, {
@@ -55,42 +109,39 @@ export function toStoredSchema(root: ImplicitFieldSchema): TreeStoredSchema {
 				}
 				nodeSchema.set(
 					brand(schema.identifier),
-					getStoredSchema(schema as SimpleNodeSchemaBase<NodeKind> as SimpleNodeSchema),
+					getStoredSchema(
+						schema as SimpleNodeSchemaBase<NodeKind> as SimpleNodeSchema,
+						options,
+					),
 				);
 			},
+			allowedTypeFilter: (allowedType) => allowedTypeFilter(allowedType, options),
 		});
 
 		const result: TreeStoredSchema = {
 			nodeSchema,
-			rootFieldSchema: convertField(normalized),
+			rootFieldSchema: convertField(normalized, options),
 		};
 		return result;
 	});
 }
 
-/**
- * Converts a {@link SimpleTreeSchema} into a {@link TreeStoredSchema}.
- */
-export function simpleToStoredSchema(root: SimpleTreeSchema): TreeStoredSchema {
-	const nodeSchema: Map<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> = new Map();
-	for (const [identifier, schema] of root.definitions) {
-		nodeSchema.set(brand(identifier), getStoredSchema(schema));
-	}
-
-	const result: TreeStoredSchema = {
-		nodeSchema,
-		rootFieldSchema: convertField(root.root),
-	};
-	return result;
-}
-
 /**
  * Normalizes an {@link ImplicitFieldSchema} into a {@link TreeFieldSchema}.
  */
-export function convertField(schema: SimpleFieldSchema): TreeFieldStoredSchema {
+export function convertField(
+	schema: SimpleFieldSchema | FieldSchemaAlpha,
+	options: StoredSchemaGenerationOptions,
+): TreeFieldStoredSchema {
 	const kind: FieldKindIdentifier =
 		convertFieldKind.get(schema.kind)?.identifier ?? fail(0xae3 /* Invalid field kind */);
-	const types: TreeTypeSet = schema.allowedTypesIdentifiers as TreeTypeSet;
+	let types: TreeTypeSet;
+	// eslint-disable-next-line unicorn/prefer-ternary
+	if (schema instanceof FieldSchemaAlpha) {
+		types = convertAllowedTypes(schema.annotatedAllowedTypesNormalized, options);
+	} else {
+		types = schema.allowedTypesIdentifiers as TreeTypeSet;
+	}
 	return { kind, types, persistedMetadata: schema.persistedMetadata };
 }
 
@@ -114,11 +165,16 @@ export const convertFieldKind: ReadonlyMap<FieldKind, FlexFieldKind> = new Map<
  * TODO: AB#43548: Using a stored schema for unhydrated flex trees does not handle schema evolution features like "allowUnknownOptionalFields".
  * Usage of this and the conversion which wrap it should be audited and reduced.
  */
-export function getStoredSchema(schema: SimpleNodeSchema): TreeNodeStoredSchema {
+export function getStoredSchema(
+	schema: SimpleNodeSchema,
+	options: StoredSchemaGenerationOptions,
+): TreeNodeStoredSchema {
+	if (isClassBasedSchema(schema)) {
+		return getTreeNodeSchemaPrivateData(schema).toStored(options);
+	}
 	const kind = schema.kind;
 	switch (kind) {
 		case NodeKind.Leaf: {
-			assert(schema.kind === NodeKind.Leaf, 0xa4a /* invalid kind */);
 			return new LeafNodeStoredSchema(schema.leafKind);
 		}
 		case NodeKind.Map:
@@ -136,18 +192,12 @@ export function getStoredSchema(schema: SimpleNodeSchema): TreeNodeStoredSchema
 		}
 		case NodeKind.Array: {
 			const types = schema.allowedTypesIdentifiers as TreeTypeSet;
-			const field = {
-				kind: FieldKinds.sequence.identifier,
-				types,
-				persistedMetadata: schema.persistedMetadata,
-			};
-			const fields = new Map([[EmptyKey, field]]);
-			return new ObjectNodeStoredSchema(fields, schema.persistedMetadata);
+			return arrayNodeStoredSchema(types, schema.persistedMetadata);
 		}
 		case NodeKind.Object: {
 			const fields: Map<FieldKey, TreeFieldStoredSchema> = new Map();
 			for (const fieldSchema of schema.fields.values()) {
-				fields.set(brand(fieldSchema.storedKey), convertField(fieldSchema));
+				fields.set(brand(fieldSchema.storedKey), convertField(fieldSchema, options));
 			}
 			return new ObjectNodeStoredSchema(fields, schema.persistedMetadata);
 		}
@@ -156,3 +206,16 @@ export function getStoredSchema(schema: SimpleNodeSchema): TreeNodeStoredSchema
 		}
 	}
 }
+
+export function arrayNodeStoredSchema(
+	types: TreeTypeSet,
+	persistedMetadata: JsonCompatibleReadOnlyObject | undefined,
+): ObjectNodeStoredSchema {
+	const field = {
+		kind: FieldKinds.sequence.identifier,
+		types,
+		persistedMetadata,
+	};
+	const fields = new Map([[EmptyKey, field]]);
+	return new ObjectNodeStoredSchema(fields, persistedMetadata);
+}