@fluidframework/tree 2.117.0 → 3.0.0

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

@@ -3,14 +3,119 @@
  * Licensed under the MIT License.
  */
 
-import type { TreeStoredSchema } from "../../core/index.js";
+import { unreachableCase } from "@fluidframework/core-utils/internal";
+
+import {
+	MapNodeStoredSchema,
+	ObjectNodeStoredSchema,
+	type TreeStoredSchema,
+	ValueSchema,
+} from "../../core/index.js";
 import type { SchemaUpgrade, StagedSchemaUpgradePolicy } from "../core/index.js";
+import { NodeKind } from "../core/index.js";
 import { allowsRepoSuperset, defaultSchemaPolicy } from "../../feature-libraries/index.js";
-import { toUpgradeSchema } from "../toStoredSchema.js";
+import { resolveStoredSchemaGenerationOptions, toUpgradeSchema } from "../toStoredSchema.js";
 import type { TreeSchema } from "../treeSchema.js";
 
-import { getDiscrepanciesInAllowedContent } from "./discrepancies.js";
-import type { SchemaCompatibilityStatus } from "./tree.js";
+import {
+	getDiscrepanciesInAllowedContent,
+	type Discrepancy,
+	type UpgradeLocationCollector,
+} from "./discrepancies.js";
+import type { SchemaCompatibilityStatusBeta, SchemaDiscrepancy } from "./tree.js";
+
+/**
+ * Describes the discrepancies that prevent a view schema from viewing a stored schema as a
+ * readonly array.
+ */
+export function getSchemaIncompatibilityDetails(
+	viewSchema: TreeSchema,
+	stored: TreeStoredSchema,
+): readonly SchemaDiscrepancy[] | undefined {
+	const discrepancies = [...getDiscrepanciesInAllowedContent(viewSchema, stored)];
+	if (discrepancies.length === 0) {
+		return undefined;
+	}
+
+	return discrepancies.map(formatSchemaDiscrepancy);
+}
+
+function formatSchemaDiscrepancy(value: Discrepancy): SchemaDiscrepancy {
+	switch (value.mismatch) {
+		case "allowedTypes": {
+			return {
+				mismatch: value.mismatch,
+				location:
+					value.identifier === undefined
+						? "root"
+						: {
+								nodeType: value.identifier,
+								fieldKey: value.fieldKey,
+							},
+				view: value.view.map(({ type }) => type.identifier).sort(),
+				...(value.stagedView === undefined
+					? {}
+					: {
+							stagedView: value.stagedView.map(({ type }) => type.identifier).sort(),
+						}),
+				stored: [...value.stored].sort(),
+				...(value.viewIsStagedOptional === true ? { viewIsStagedOptional: true } : {}),
+			};
+		}
+		case "fieldKind": {
+			return {
+				mismatch: value.mismatch,
+				location:
+					value.identifier === undefined
+						? "root"
+						: {
+								nodeType: value.identifier,
+								fieldKey: value.fieldKey,
+							},
+				view: value.view,
+				stored: value.stored,
+				...(value.viewIsStagedOptional === true ? { viewIsStagedOptional: true } : {}),
+			};
+		}
+		case "valueSchema": {
+			return {
+				mismatch: value.mismatch,
+				nodeType: value.identifier,
+				view: value.view === undefined ? undefined : ValueSchema[value.view],
+				stored: value.stored === undefined ? undefined : ValueSchema[value.stored],
+			};
+		}
+		case "nodeKind": {
+			const storedNodeKind =
+				value.stored === ObjectNodeStoredSchema
+					? "Object"
+					: value.stored === MapNodeStoredSchema
+						? "Map"
+						: "Leaf";
+			return {
+				mismatch: value.mismatch,
+				nodeType: value.identifier,
+				view: NodeKind[value.view],
+				stored: storedNodeKind,
+			};
+		}
+		default: {
+			return unreachableCase(value);
+		}
+	}
+}
+
+/**
+ * The enablement status of a staged schema upgrade in a document's stored schema.
+ *
+ * @remarks
+ * - `"disabled"` — no locations guarded by the upgrade are enabled in stored schema.
+ * - `"partial"` — at least one location is enabled but not all of them.
+ * - `"enabled"` — all locations guarded by the upgrade are enabled in stored schema.
+ *
+ * @alpha
+ */
+export type StagedUpgradeStatus = "disabled" | "partial" | "enabled";
 
 /**
  * Determines the compatibility of a stored document (based on its stored schema) with a viewer (based on its view schema).
@@ -24,27 +129,59 @@ import type { SchemaCompatibilityStatus } from "./tree.js";
  * @param viewSchema - Schema for the view
  * @param stored - The stored schema to check compatibility against
  * @param stagedSchemaUpgrades - Staged schema upgrades enabled for this view, or explicit stored-schema generation options
+ *
  */
 export function checkSchemaCompatibility(
 	viewSchema: TreeSchema,
 	stored: TreeStoredSchema,
 	stagedSchemaUpgrades?: Iterable<SchemaUpgrade> | StagedSchemaUpgradePolicy,
-): Omit<SchemaCompatibilityStatus, "canInitialize"> {
+): Omit<SchemaCompatibilityStatusBeta, "canInitialize"> & {
+	enabledUpgrades: ReadonlyMap<SchemaUpgrade, StagedUpgradeStatus>;
+} {
 	// The public API surface assumes defaultSchemaPolicy
 	const policy = defaultSchemaPolicy;
+	const configuredPolicy = resolveStoredSchemaGenerationOptions(stagedSchemaUpgrades);
+	const includeAlreadyEnabledUpgrades = configuredPolicy.includeAlreadyEnabledUpgrades ?? true;
+
+	// Collect upgrade locations during the discrepancy walk (single pass).
+	const totalLocations = new Map<SchemaUpgrade, number>();
+	const enabledLocations = new Map<SchemaUpgrade, number>();
+	const upgradeCollector: UpgradeLocationCollector = {
+		allowedType(upgrade, isEnabled) {
+			totalLocations.set(upgrade, (totalLocations.get(upgrade) ?? 0) + 1);
+			if (isEnabled) {
+				enabledLocations.set(upgrade, (enabledLocations.get(upgrade) ?? 0) + 1);
+			}
+		},
+		optionalField(upgrade, isEnabled) {
+			totalLocations.set(upgrade, (totalLocations.get(upgrade) ?? 0) + 1);
+			if (isEnabled) {
+				enabledLocations.set(upgrade, (enabledLocations.get(upgrade) ?? 0) + 1);
+			}
+		},
+	};
 
 	// View schema allows a subset of documents that stored schema does, and the discrepancies are allowed by policy
 	// determined by the view schema (i.e. objects with extra optional fields in the stored schema have opted into allowing this.
 	// In the future, this would also include things like:
 	// - fields with more allowed types in the stored schema than in the view schema have out-of-schema "unknown content" adapters
-	let canView = true;
-
-	for (const _discrepancy of getDiscrepanciesInAllowedContent(viewSchema, stored)) {
-		canView = false;
-		break;
+	// Complete the full walk even after finding an incompatibility so discrepancy details and
+	// staged-upgrade status contain all available information for debugging.
+	const discrepancies: SchemaDiscrepancy[] = [];
+	for (const discrepancy of getDiscrepanciesInAllowedContent(
+		viewSchema,
+		stored,
+		upgradeCollector,
+	)) {
+		discrepancies.push(formatSchemaDiscrepancy(discrepancy));
 	}
+	const canView = discrepancies.length === 0;
 
-	const wouldUpgradeTo = toUpgradeSchema(viewSchema.root, stagedSchemaUpgrades);
+	const enabledUpgrades = computeUpgradeStatuses(totalLocations, enabledLocations);
+	const upgradePolicy = includeAlreadyEnabledUpgrades
+		? includeEnabledUpgrades(configuredPolicy, enabledUpgrades)
+		: configuredPolicy;
+	const wouldUpgradeTo = toUpgradeSchema(viewSchema.root, upgradePolicy);
 
 	const canUpgrade = allowsRepoSuperset(policy, stored, wouldUpgradeTo);
 
@@ -57,5 +194,42 @@ export function checkSchemaCompatibility(
 		canView,
 		canUpgrade,
 		isEquivalent,
+		discrepancies: canView ? undefined : discrepancies,
+		enabledUpgrades,
 	};
 }
+
+function includeEnabledUpgrades(
+	configuredPolicy: StagedSchemaUpgradePolicy,
+	enabledUpgrades: ReadonlyMap<SchemaUpgrade, StagedUpgradeStatus>,
+): StagedSchemaUpgradePolicy {
+	if (enabledUpgrades.size === 0) {
+		return configuredPolicy;
+	}
+	return {
+		includeStaged: (upgrade) =>
+			configuredPolicy.includeStaged(upgrade) || enabledUpgrades.has(upgrade),
+		includeStagedOptional: (upgrade) =>
+			configuredPolicy.includeStagedOptional(upgrade) || enabledUpgrades.has(upgrade),
+	};
+}
+
+/**
+ * Computes the {@link StagedUpgradeStatus} for each upgrade token from total and enabled location counts.
+ * Only tokens with at least one enabled location are included in the returned map.
+ */
+function computeUpgradeStatuses(
+	totalLocations: ReadonlyMap<SchemaUpgrade, number>,
+	enabledLocations: ReadonlyMap<SchemaUpgrade, number>,
+): ReadonlyMap<SchemaUpgrade, StagedUpgradeStatus> {
+	const result = new Map<SchemaUpgrade, StagedUpgradeStatus>();
+	for (const [upgrade, total] of totalLocations) {
+		const enabled = enabledLocations.get(upgrade) ?? 0;
+		if (enabled > 0 && enabled < total) {
+			result.set(upgrade, "partial");
+		} else if (enabled >= total && enabled > 0) {
+			result.set(upgrade, "enabled");
+		}
+	}
+	return result;
+}

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

@@ -53,7 +53,7 @@ import {
 } from "./schemaFactory.js";
 import { SchemaFactoryBeta } from "./schemaFactoryBeta.js";
 import { schemaStatics } from "./schemaStatics.js";
-import { TreeBeta } from "./treeBeta.js";
+import { cloneTree } from "./cloneTree.js";
 import type {
 	ArrayNodeCustomizableSchemaUnsafe,
 	FieldSchemaAlphaUnsafe,
@@ -297,7 +297,7 @@ const withDefault = <
 		// This prevents multi-parenting errors.
 		if (isTreeNode(insertableValue)) {
 			// eslint-disable-next-line @typescript-eslint/no-explicit-any
-			insertableValue = TreeBeta.clone(insertableValue as any);
+			insertableValue = cloneTree(insertableValue as any);
 		}
 
 		// For optional fields with an undefined default, return an empty array (no value).

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

@@ -256,13 +256,40 @@ export interface SnapshotSchemaCompatibilityOptions {
 	 * and not erased when regenerating snapshots.
 	 *
 	 * This directory will be created if it does not already exist.
-	 * All ".json" files in this directory will be treated as schema snapshots.
+	 * By default, all ".json" files in this directory will be treated as schema snapshots.
+	 * When {@link SnapshotSchemaCompatibilityOptions.snapshotFileNameFormat} is provided,
+	 * only JSON files matching that format will be treated as schema snapshots.
 	 * It is recommended to use a dedicated directory for each {@link snapshotSchemaCompatibility} powered test.
 	 *
 	 * This can use any path syntax supported by the provided {@link SnapshotSchemaCompatibilityOptions.fileSystem}.
 	 */
 	readonly snapshotDirectory: string;
 
+	/**
+	 * Customizes the names of schema snapshot files.
+	 * @remarks
+	 * Snapshot files are named by surrounding the version with the provided strings, followed by the ".json" extension.
+	 * For example, `{ prefix: "schema-", suffix: "-snapshot" }` produces `schema-1.0.0-snapshot.json` for version `1.0.0`.
+	 *
+	 * Only JSON files matching this format are treated as schema snapshots.
+	 * The prefix and suffix must not contain ASCII control characters or characters that are invalid in cross-platform file names.
+	 */
+	readonly snapshotFileNameFormat?: {
+		/**
+		 * Text to include before the version.
+		 *
+		 * @defaultValue `""`
+		 */
+		readonly prefix?: string;
+
+		/**
+		 * Text to include after the version and before the ".json" extension.
+		 *
+		 * @defaultValue `""`
+		 */
+		readonly suffix?: string;
+	};
+
 	/**
 	 * How the `snapshotDirectory` is accessed.
 	 */
@@ -492,6 +519,7 @@ export function snapshotSchemaCompatibility(
 	const checker = new SnapshotCompatibilityChecker(
 		options.snapshotDirectory,
 		options.fileSystem,
+		options.snapshotFileNameFormat,
 	);
 	const {
 		version: currentVersion,
@@ -743,12 +771,33 @@ export class SnapshotCompatibilityChecker {
 		 * How the `snapshotDirectory` is accessed.
 		 */
 		private readonly fileSystemMethods: SnapshotFileSystem,
-	) {}
+		/**
+		 * Text surrounding the version in snapshot file names.
+		 */
+		private readonly snapshotFileNameFormat: {
+			readonly prefix?: string;
+			readonly suffix?: string;
+		} = {},
+	) {
+		const { prefix = "", suffix = "" } = snapshotFileNameFormat;
+		// eslint-disable-next-line no-control-regex -- The control character range is intentionally invalid for cross-platform file names.
+		const invalidFileNameCharacters = /[\u0000-\u001F<>:"/\\|?*]/u;
+		for (const [property, value] of [
+			["prefix", prefix],
+			["suffix", suffix],
+		] as const) {
+			if (invalidFileNameCharacters.test(value)) {
+				throw new UsageError(
+					`Invalid snapshotFileNameFormat.${property}: ${JSON.stringify(value)}. Must not contain ASCII control characters or any of <>:"/\\|?*.`,
+				);
+			}
+		}
+	}
 
 	public writeSchemaSnapshot(snapshotName: string, snapshot: JsonCompatibleReadOnly): void {
 		const fullPath = this.fileSystemMethods.join(
 			this.snapshotDirectory,
-			`${snapshotName}.json`,
+			this.getSnapshotFileName(snapshotName),
 		);
 		this.ensureSnapshotDirectoryExists();
 		this.fileSystemMethods.writeFileSync(fullPath, JSON.stringify(snapshot, undefined, "\t"), {
@@ -764,7 +813,7 @@ export class SnapshotCompatibilityChecker {
 	public readSchemaSnapshotRaw(snapshotName: string): JsonCompatibleReadOnly {
 		const fullPath = this.fileSystemMethods.join(
 			this.snapshotDirectory,
-			`${snapshotName}.json`,
+			this.getSnapshotFileName(snapshotName),
 		);
 		const snapshot = JSON.parse(
 			this.fileSystemMethods.readFileSync(fullPath, "utf8"),
@@ -782,8 +831,8 @@ export class SnapshotCompatibilityChecker {
 		const files = this.fileSystemMethods.readdirSync(this.snapshotDirectory);
 		const versions: string[] = [];
 		for (const file of files) {
-			if (file.endsWith(".json")) {
-				const snapshotName = file.slice(0, ".json".length * -1);
+			const snapshotName = this.getSnapshotName(file);
+			if (snapshotName !== undefined) {
 				versions.push(snapshotName);
 			}
 		}
@@ -800,6 +849,38 @@ export class SnapshotCompatibilityChecker {
 	public ensureSnapshotDirectoryExists(): void {
 		this.fileSystemMethods.mkdirSync(this.snapshotDirectory, { recursive: true });
 	}
+
+	/**
+	 * Builds the file name used to read or write a snapshot with a known snapshot name.
+	 */
+	private getSnapshotFileName(snapshotName: string): string {
+		const { prefix = "", suffix = "" } = this.snapshotFileNameFormat;
+		return `${prefix}${snapshotName}${suffix}.json`;
+	}
+
+	/**
+	 * Extracts the snapshot name from a matching file found while scanning the snapshot directory.
+	 */
+	private getSnapshotName(fileName: string): string | undefined {
+		const extension = ".json";
+		if (!fileName.endsWith(extension)) {
+			return undefined;
+		}
+
+		const { prefix = "", suffix = "" } = this.snapshotFileNameFormat;
+		const fileNameWithoutExtension = fileName.slice(0, -extension.length);
+		if (
+			!fileNameWithoutExtension.startsWith(prefix) ||
+			!fileNameWithoutExtension.endsWith(suffix)
+		) {
+			return undefined;
+		}
+
+		return fileNameWithoutExtension.slice(
+			prefix.length,
+			fileNameWithoutExtension.length - suffix.length,
+		);
+	}
 }
 
 /**

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

@@ -62,7 +62,7 @@ export interface WithValue<TValue> {
 }
 
 /**
- * Contains a value and status returned from a user-supplied {@link TreeViewBeta.runTransaction | transaction callback}.
+ * Contains a value and status returned from a user-supplied {@link UntypedTreeView.(runTransaction:3) | transaction callback}.
  * @input
  * @beta
  */
@@ -77,7 +77,7 @@ export type TransactionCallbackStatusBeta<TSuccessValue, TFailureValue> =
 	  });
 
 /**
- * The result of a {@link TreeViewBeta.runTransaction | transaction} that doesn't return a value.
+ * The result of a {@link UntypedTreeView.(runTransaction:2) | transaction} that doesn't return a value.
  * @input
  * @beta
  */
@@ -114,7 +114,7 @@ export type VoidTransactionCallbackStatusAlpha = Omit<
 >;
 
 /**
- * The result of a {@link TreeViewBeta.(runTransaction:1) | transaction} that completed successfully.
+ * The result of a {@link UntypedTreeView.(runTransaction:1) | transaction} that completed successfully.
  * @sealed
  * @beta
  */
@@ -124,7 +124,7 @@ export interface TransactionResultSuccess<TSuccessValue> extends WithValue<TSucc
 }
 
 /**
- * The result of a {@link TreeViewBeta.runTransaction | transaction} that was rolled back.
+ * The result of a {@link UntypedTreeView.(runTransaction:2) | transaction} that was rolled back.
  * @sealed
  * @beta
  */