@fluidframework/tree 2.74.0-365691 → 2.74.0-370705

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

@@ -4,12 +4,13 @@
  */
 
 import { getTreeNodeSchemaPrivateData, type AllowedTypesFull } from "../core/index.js";
-import { isObjectNodeSchema } from "../node-kinds/index.js";
-import type { TreeSchema } from "./configuration.js";
+import { isArrayNodeSchema, isObjectNodeSchema } from "../node-kinds/index.js";
+import type { TreeSchema } from "../treeSchema.js";
 import type { IncrementalEncodingPolicy } from "../../feature-libraries/index.js";
 import { oneFromIterable } from "../../util/index.js";
 import { assert } from "@fluidframework/core-utils/internal";
 import type { FieldKey } from "../../core/index.js";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 /**
  * A symbol when present in the {@link AnnotatedAllowedTypes.metadata}'s `custom` property as true, opts in the allowed
@@ -68,7 +69,7 @@ function isIncrementalSummaryHintInAllowedTypes(allowedTypes: AllowedTypesFull):
 export function incrementalEncodingPolicyForAllowedTypes(
 	rootSchema: TreeSchema,
 ): IncrementalEncodingPolicy {
-	return (targetNodeIdentifier: string | undefined, targetFieldKey: string) => {
+	return (targetNodeIdentifier: string | undefined, targetFieldKey?: string) => {
 		if (targetNodeIdentifier === undefined) {
 			// Root fields cannot be allowed types, so we don't incrementally summarize them.
 			return false;
@@ -85,6 +86,11 @@ export function incrementalEncodingPolicyForAllowedTypes(
 		}
 
 		if (isObjectNodeSchema(targetNode)) {
+			if (targetFieldKey === undefined) {
+				throw new UsageError(
+					`Field key must be provided for object or array node '${targetNodeIdentifier}'`,
+				);
+			}
 			const targetPropertyKey = targetNode.storedKeyToPropertyKey.get(
 				targetFieldKey as FieldKey,
 			);
@@ -97,6 +103,12 @@ export function incrementalEncodingPolicyForAllowedTypes(
 			return false;
 		}
 
+		if (targetFieldKey !== undefined && !isArrayNodeSchema(targetNode)) {
+			throw new UsageError(
+				`Field key must not be provided for leaf, map or record node '${targetNodeIdentifier}'`,
+			);
+		}
+
 		const allowedTypes = oneFromIterable(
 			getTreeNodeSchemaPrivateData(targetNode).childAllowedTypes,
 		);

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

@@ -4,7 +4,6 @@
  */
 
 export type {
-	TreeSchema,
 	ITreeViewConfiguration,
 	ITreeConfigurationOptions,
 } from "./configuration.js";
@@ -29,6 +28,7 @@ export { asTreeViewAlpha } from "./tree.js";
 export { type SchemaStatics, schemaStatics } from "./schemaStatics.js";
 export {
 	SchemaFactory,
+	scoped,
 	type ScopedSchemaName,
 	type ObjectSchemaOptionsAlpha,
 	type ObjectSchemaOptions,
@@ -161,15 +161,14 @@ export {
 } from "./transactionTypes.js";
 
 export { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";
-export { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 export type { TreeChangeEvents } from "./treeChangeEvents.js";
 export {
 	incrementalEncodingPolicyForAllowedTypes,
 	incrementalSummaryHint,
 } from "./incrementalAllowedTypes.js";
 export {
-	encodeSimpleSchema,
-	decodeSimpleSchema,
+	encodeSchemaCompatibilitySnapshot,
+	decodeSchemaCompatibilitySnapshot,
 } from "./simpleSchemaCodec.js";
 export {
 	exportCompatibilitySchemaSnapshot,

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

@@ -9,7 +9,7 @@ import { allowsRepoSuperset, defaultSchemaPolicy } from "../../feature-libraries
 import type { SchemaCompatibilityStatus } from "./tree.js";
 import { getDiscrepanciesInAllowedContent } from "./discrepancies.js";
 import { toUpgradeSchema } from "../toStoredSchema.js";
-import type { TreeSchema } from "./configuration.js";
+import type { TreeSchema } from "../treeSchema.js";
 
 /**
  * A collection of View information for schema

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

@@ -35,7 +35,7 @@ import type {
 	System_Unsafe,
 	TreeRecordNodeUnsafe,
 } from "./typesUnsafe.js";
-import type { SimpleObjectNodeSchema } from "../simpleSchema.js";
+import type { SchemaType, SimpleObjectNodeSchema } from "../simpleSchema.js";
 import { SchemaFactoryBeta } from "./schemaFactoryBeta.js";
 
 // These imports prevent a large number of type references in the API reports from showing up as *_2.
@@ -119,7 +119,7 @@ export class SchemaFactoryAlpha<
 		never,
 		TCustomMetadata
 	> &
-		SimpleObjectNodeSchema<TCustomMetadata> &
+		SimpleObjectNodeSchema<SchemaType.View, TCustomMetadata> &
 		// We can't just use non generic `ObjectNodeSchema` here since "Base constructors must all have the same return type".
 		// We also can't just use generic `ObjectNodeSchema` here and not `TreeNodeSchemaClass` since that doesn't work with unsafe recursive types.
 		// ObjectNodeSchema<

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

@@ -182,7 +182,6 @@ export type ValidateRecursiveSchemaTemplate<T extends TreeNodeSchemaClass> =
 		}[T["kind"]]
 	>;
 
-/* eslint-disable @fluid-internal/fluid/no-hyphen-after-jsdoc-tag -- false positive AB#50920 */
 /**
  * Workaround for "Type instantiation is excessively deep and possibly infinite.ts" errors.
  * @remarks
@@ -240,7 +239,6 @@ export type ValidateRecursiveSchemaTemplate<T extends TreeNodeSchemaClass> =
  */
 export type FixRecursiveRecursionLimit<T extends TreeNodeSchemaClass> =
 	T extends ValidateRecursiveSchemaTemplate<T> ? undefined : undefined;
-/* eslint-enable @fluid-internal/fluid/no-hyphen-after-jsdoc-tag */
 
 /**
  * Does nothing with the provided value, but appears to use it to make unused locals warnings and errors go away.

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

@@ -18,13 +18,14 @@ import {
 	type FieldProps,
 } from "../fieldSchema.js";
 import type {
+	SchemaType,
 	SimpleAllowedTypeAttributes,
 	SimpleFieldSchema,
 	SimpleNodeSchema,
 	SimpleTreeSchema,
 } from "../simpleSchema.js";
 
-import type { TreeSchema } from "./configuration.js";
+import type { TreeSchema } from "../treeSchema.js";
 import { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
 
 const factory = new SchemaFactoryAlpha(undefined);
@@ -41,12 +42,17 @@ const factory = new SchemaFactoryAlpha(undefined);
  *
  * This API bakes in some arbitrary policy choices for how to handle data that is not included in the SimpleTreeSchema API, for example the value of `allowUnknownOptionalFields`.
  * If any particular choice is required for such cases, this API should not be used.
+ *
+ * @privateRemarks
+ * TODO: Add the ability for consumers to inject custom policy.
+ * For example, allow nodes with table schema identifiers to dispatch to `TableSchema` factory APIs.
+ *
  * @alpha
  */
 export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): TreeSchema {
 	const context: Context = new Map(
 		[...simple.definitions].map(
-			([id, schema]): [string, () => TreeNodeSchema & SimpleNodeSchema] => [
+			([id, schema]): [string, () => TreeNodeSchema & SimpleNodeSchema<SchemaType.View>] => [
 				id,
 				// This relies on the caching in evaluateLazySchema so that it only runs once.
 				() => generateNode(id, schema, context),
@@ -54,7 +60,7 @@ export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): TreeSc
 		),
 	);
 	const root = generateFieldSchema(simple.root, context, undefined);
-	const definitions = new Map<string, TreeNodeSchema & SimpleNodeSchema>();
+	const definitions = new Map<string, TreeNodeSchema & SimpleNodeSchema<SchemaType.View>>();
 	for (const [id, lazy] of context) {
 		definitions.set(id, lazy());
 	}
@@ -64,7 +70,7 @@ export function generateSchemaFromSimpleSchema(simple: SimpleTreeSchema): TreeSc
 	};
 }
 
-type Context = ReadonlyMap<string, () => TreeNodeSchema & SimpleNodeSchema>;
+type Context = ReadonlyMap<string, () => TreeNodeSchema & SimpleNodeSchema<SchemaType.View>>;
 
 function generateFieldSchema(
 	simple: SimpleFieldSchema,
@@ -107,7 +113,7 @@ function generateNode(
 	id: string,
 	schema: SimpleNodeSchema,
 	context: Context,
-): TreeNodeSchema & SimpleNodeSchema {
+): TreeNodeSchema & SimpleNodeSchema<SchemaType.View> {
 	switch (schema.kind) {
 		case NodeKind.Object: {
 			const fields: Record<string, FieldSchema> = {};

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

@@ -30,15 +30,23 @@ import {
 } from "../../codec/index.js";
 
 /**
- * Encodes a simple schema (view or stored) into a serializable format.
+ * Encodes the compatibility impacting subset of simple schema (view or stored) into a serializable format.
+ *
  * @remarks The JSON-compatible schema returned from this method is only intended for use in snapshots/comparisons of schemas.
  * It is not possible to reconstruct a full schema (including metadata and persistedMetadata) from the encoded format.
  * @param treeSchema - The tree schema to convert.
  * @returns A serializable representation of the schema.
  *
+ * @privateRemarks
+ * Encodes to {@link Format.SimpleTreeSchemaFormat}.
+ *
+ * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.
+ *
  * @alpha
  */
-export function encodeSimpleSchema(simpleSchema: SimpleTreeSchema): JsonCompatibleReadOnly {
+export function encodeSchemaCompatibilitySnapshot(
+	simpleSchema: SimpleTreeSchema,
+): JsonCompatibleReadOnly {
 	// Convert types to serializable forms
 	const encodedDefinitions: Format.SimpleSchemaDefinitionsFormat = {};
 
@@ -63,9 +71,15 @@ export function encodeSimpleSchema(simpleSchema: SimpleTreeSchema): JsonCompatib
  * @returns A decoded simple schema.
  * @throws Will throw a usage error if the encoded schema is not in the expected format.
  *
+ * @privateRemarks
+ * If a validator is not provided, this implicitly performs an unsafe type conversion:
+ * this is something our user facing APIs generally avoid doing, and should be reconsidered before stabilizing.
+ *
+ * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.
+ *
  * @alpha
  */
-export function decodeSimpleSchema(
+export function decodeSchemaCompatibilitySnapshot(
 	encodedSchema: JsonCompatibleReadOnly,
 	validator?: FormatValidator,
 ): SimpleTreeSchema {

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

@@ -28,7 +28,7 @@ import type {
 	SimpleRecordNodeSchema,
 } from "../simpleSchema.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
-import type { TreeSchema } from "./configuration.js";
+import type { TreeSchema } from "../treeSchema.js";
 import type { TreeSchemaEncodingOptions } from "./getJsonSchema.js";
 import {
 	ArrayNodeSchema,

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

@@ -4,13 +4,16 @@
  */
 
 import type { JsonCompatibleReadOnly } from "../../util/index.js";
-import { toStoredSchema } from "../toStoredSchema.js";
+import { toInitialSchema } from "../toStoredSchema.js";
 import { TreeViewConfigurationAlpha, TreeViewConfiguration } from "./configuration.js";
+import { createTreeSchema } from "../treeSchema.js";
 import { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
 import { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";
-import { decodeSimpleSchema, encodeSimpleSchema } from "./simpleSchemaCodec.js";
+import {
+	decodeSchemaCompatibilitySnapshot,
+	encodeSchemaCompatibilitySnapshot,
+} from "./simpleSchemaCodec.js";
 import type { SchemaCompatibilityStatus } from "./tree.js";
-import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 
 /**
  * Compute the compatibility of using `view` to {@link ViewableTree.viewWith | view a tree} who's {@link ITreeAlpha.exportSimpleSchema | stored schema} could be derived from `viewWhichCreatedStoredSchema` via either {@link TreeView.initialize} or {@link TreeView.upgradeSchema}.
@@ -58,6 +61,9 @@ import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
  * @param view - The view being tested to see if it could view tree created or initialized using `viewWhichCreatedStoredSchema`.
  * @returns The compatibility status.
  *
+ * @privateRemarks
+ * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.
+ *
  * @alpha
  */
 export function checkCompatibility(
@@ -65,9 +71,7 @@ export function checkCompatibility(
 	view: TreeViewConfiguration,
 ): Omit<SchemaCompatibilityStatus, "canInitialize"> {
 	const viewAsAlpha = new TreeViewConfigurationAlpha({ schema: view.schema });
-	const stored = toStoredSchema(viewWhichCreatedStoredSchema.schema, {
-		includeStaged: () => true,
-	});
+	const stored = toInitialSchema(viewWhichCreatedStoredSchema.schema);
 	const tester = new SchemaCompatibilityTester(viewAsAlpha);
 	return tester.checkCompatibility(stored);
 }
@@ -95,13 +99,16 @@ export function checkCompatibility(
  * fs.writeFileSync("PointSchema.json", encodedSchema);
  * ```
  *
+ * @privateRemarks
+ * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.
+ *
  * @alpha
  */
 export function exportCompatibilitySchemaSnapshot(
 	config: Pick<TreeViewConfiguration, "schema">,
 ): JsonCompatibleReadOnly {
-	const simpleSchema = toSimpleTreeSchema(config.schema, true);
-	return encodeSimpleSchema(simpleSchema);
+	const treeSchema = createTreeSchema(config.schema);
+	return encodeSchemaCompatibilitySnapshot(treeSchema);
 }
 
 /**
@@ -120,13 +127,14 @@ export function exportCompatibilitySchemaSnapshot(
  * ```ts;
  * const oldViewSchema = importCompatibilitySchemaSnapshot(fs.readFileSync("PointSchema.json", "utf8"));
  * ```
- *
+ * @privateRemarks
+ * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.
  * @alpha
  */
 export function importCompatibilitySchemaSnapshot(
 	config: JsonCompatibleReadOnly,
 ): TreeViewConfiguration {
-	const simpleSchema = decodeSimpleSchema(config);
+	const simpleSchema = decodeSchemaCompatibilitySnapshot(config);
 	const viewSchema = generateSchemaFromSimpleSchema(simpleSchema);
 
 	// We construct a TreeViewConfiguration here with the default parameters. The default set of validation parameters are fine for

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

@@ -33,7 +33,11 @@ import type {
 	AnnotatedAllowedTypes,
 } from "../core/index.js";
 import type { TreeArrayNode } from "../node-kinds/index.js";
-import type { SimpleArrayNodeSchema, SimpleMapNodeSchema } from "../simpleSchema.js";
+import type {
+	SchemaType,
+	SimpleArrayNodeSchema,
+	SimpleMapNodeSchema,
+} from "../simpleSchema.js";
 
 /*
  * TODO:
@@ -498,7 +502,7 @@ export interface ArrayNodeCustomizableSchemaUnsafe<
 			undefined,
 			TCustomMetadata
 		>,
-		SimpleArrayNodeSchema<TCustomMetadata> {}
+		SimpleArrayNodeSchema<SchemaType.View, TCustomMetadata> {}
 
 /**
  * {@link Unenforced} version of {@link MapNodeCustomizableSchema}s.
@@ -529,7 +533,7 @@ export interface MapNodeCustomizableSchemaUnsafe<
 			undefined,
 			TCustomMetadata
 		>,
-		SimpleMapNodeSchema<TCustomMetadata> {}
+		SimpleMapNodeSchema<SchemaType.View, TCustomMetadata> {}
 
 /**
  * {@link Unenforced} version of {@link TreeRecordNode}.

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

@@ -25,7 +25,7 @@ import {
 	type TreeNodeSchema,
 } from "./treeNodeSchema.js";
 import { schemaAsTreeNodeValid } from "./treeNodeValid.js";
-import type { SimpleAllowedTypeAttributes } from "../simpleSchema.js";
+import type { SchemaType, SimpleAllowedTypeAttributes } from "../simpleSchema.js";
 
 /**
  * Schema for types allowed in some location in a tree (like a field, map entry or array).
@@ -258,8 +258,8 @@ export class AnnotatedAllowedTypesInternal<
 	 */
 	public static evaluateSimpleAllowedTypes(
 		annotatedAllowedTypes: AnnotatedAllowedTypes,
-	): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
-		const simpleAllowedTypes = new Map<string, SimpleAllowedTypeAttributes>();
+	): ReadonlyMap<string, SimpleAllowedTypeAttributes<SchemaType.View>> {
+		const simpleAllowedTypes = new Map<string, SimpleAllowedTypeAttributes<SchemaType.View>>();
 		for (const type of annotatedAllowedTypes.evaluate().types) {
 			simpleAllowedTypes.set(type.type.identifier, {
 				isStaged: type.metadata.stagedSchemaUpgrade ?? false,

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

@@ -115,8 +115,8 @@ export {
 export type { SimpleNodeSchemaBase } from "./simpleNodeSchemaBase.js";
 export {
 	type StoredSchemaGenerationOptions,
-	convertAllowedTypes,
-	allowedTypeFilter,
 	type StoredFromViewSchemaGenerationOptions,
 	ExpectStored,
+	type SimpleSchemaTransformationOptions,
+	Unchanged,
 } from "./toStored.js";

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

@@ -3,18 +3,14 @@
  * Licensed under the MIT License.
  */
 
-import { brand } from "../../util/index.js";
 import type { SchemaUpgrade } from "./allowedTypes.js";
-import type { TreeNodeSchemaIdentifier, TreeTypeSet } from "../../core/index.js";
-import type { SimpleAllowedTypeAttributes, SimpleAllowedTypes } from "../simpleSchema.js";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 /**
- * Options for generating a {@link TreeStoredSchema} from view schema.
+ * Options for transforming a view simple-schema to a stored simple-schema (See {@link TreeStoredSchema}).
  */
 export interface StoredFromViewSchemaGenerationOptions {
 	/**
-	 * Determines whether to include staged schema in the resulting stored schema.
+	 * Determines whether to include {@link SchemaStaticsBeta.staged | staged} allowed types in the resulting stored schema.
 	 * @remarks
 	 * Due to caching, the behavior of this function must be pure.
 	 */
@@ -27,58 +23,29 @@ export interface StoredFromViewSchemaGenerationOptions {
 export const ExpectStored = Symbol("ExpectStored");
 export type ExpectStored = typeof ExpectStored;
 
-export type StoredSchemaGenerationOptions =
-	| StoredFromViewSchemaGenerationOptions
-	| ExpectStored;
-
 /**
- * Filters an allowed type based on the provided options.
- * @param allowedType - The allowed type to filter.
- * @param options - The options to use for filtering.
- * @returns Whether the allowed type passes the filter.
+ * Marker type indicating that the input schema should not be transformed: data accessible from the simple schema API surface should be copied as is.
+ * @remarks
+ * The only real use-cases for this are deep-copying simple schema, and copying objects that implement more than just simple schema (such as {@link TreeSchema}) into simple object without extra prototypes and properties.
  */
-export function allowedTypeFilter(
-	data: SimpleAllowedTypeAttributes,
-	options: StoredSchemaGenerationOptions,
-): boolean {
-	if (options === ExpectStored) {
-		if (data.isStaged !== undefined) {
-			throw new UsageError(
-				"Failed to covert view schema to stored schema. The simple schema provided was indicated to be a stored schema by the use of `ExpectStored`, but view schema specific content was encountered which requires a `StoredFromViewSchemaGenerationOptions` to process.",
-			);
-		}
-		return true;
-	}
+export const Unchanged = Symbol("Unchanged");
+export type Unchanged = typeof Unchanged;
 
-	if (data.isStaged === undefined) {
-		throw new UsageError(
-			"Failed to covert view schema to stored schema. The simple schema provided as the view schema was actually a stored schema. If this was intended, use `ExpectStored` for the `StoredSchemaGenerationOptions` to indicate the input is already a stored schema and only a format conversion is required.",
-		);
-	}
-
-	// If the allowed type is staged, only include it if the options allow it.
-	if (data.isStaged === false) {
-		return true;
-	}
-
-	return options.includeStaged(data.isStaged);
-}
+/**
+ * Subset of {@link SimpleSchemaTransformationOptions} for when the output is a known to be a stored schema.
+ */
+export type StoredSchemaGenerationOptions =
+	| StoredFromViewSchemaGenerationOptions
+	| ExpectStored;
 
 /**
- * Converts a {@link SimpleAllowedTypes} to a stored schema.
- * @param schema - The schema to convert.
- * @param options - The options to use for filtering.
- * @returns The converted stored schema.
+ * Options for transforming a schema.
+ * @remarks
+ * See also {@link generateSchemaFromSimpleSchema} for a different schema transformation.
+ * Note that if we want to make `generateSchemaFromSimpleSchema` consume view simple-schema, and use these transformation APIs to generate that view simple-schema from a stored simple-schema,
+ * we will need to add a "ToView" option here.
  */
-export function convertAllowedTypes(
-	schema: SimpleAllowedTypes,
-	options: StoredSchemaGenerationOptions,
-): TreeTypeSet {
-	const filtered: TreeNodeSchemaIdentifier[] = [];
-	for (const [type, data] of schema) {
-		if (allowedTypeFilter(data, options)) {
-			filtered.push(brand<TreeNodeSchemaIdentifier>(type));
-		}
-	}
-	return new Set(filtered);
-}
+export type SimpleSchemaTransformationOptions =
+	| StoredFromViewSchemaGenerationOptions
+	| ExpectStored
+	| Unchanged;