@fluidframework/tree 2.116.1 → 2.118.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/transactionTypes.ts

@@ -6,6 +6,7 @@
 import type { ErasedType } from "@fluidframework/core-interfaces";
 
 import type { TreeNode } from "../core/index.js";
+import type { JsonCompatibleReadOnlyObject } from "../../util/index.js";
 
 /**
  * A special object that signifies when a SharedTree {@link RunTransaction | transaction} should "roll back".
@@ -103,7 +104,7 @@ export type TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue> =
 	};
 
 /**
- * The result of a {@link TreeBranchAlpha.(runTransaction:2) | transaction} that doesn't return a value.
+ * The result of a {@link UntypedTreeViewAlpha.(runTransaction:2) | transaction} that doesn't return a value.
  * @input
  * @alpha
  */
@@ -181,7 +182,7 @@ export interface RunTransactionParamsBeta {
 	/**
 	 * A label for this transaction that allows it to be correlated with later edits (e.g. for controlling undo/redo grouping).
 	 * @remarks
-	 * If this transaction is applied to a {@link TreeBranchAlpha | branch}, the label will be available in the {@link LocalChangeMetadata.label | metadata} of the {@link TreeBranchEvents.changed | `changed`} event.
+	 * If this transaction is applied to an {@link UntypedTreeViewAlpha | untyped view}, the label will be available in the {@link LocalChangeMetadata.label | metadata} of the {@link TreeBranchEvents.changed | `changed`} event.
 	 *
 	 * If there is a nested transaction, only the outermost transaction label will be used.
 	 */
@@ -218,4 +219,30 @@ export interface RunTransactionParamsAlpha extends RunTransactionParamsBeta {
 	 * reserving the behavior; a real post-processor will be provided in a future change.
 	 */
 	readonly postProcessor?: TransactionPostProcessor;
+
+	/**
+	 * Arbitrary, application-defined metadata to persist alongside the commit that this transaction produces.
+	 * @remarks
+	 * The metadata is replicated to all collaborating clients and persisted in the document, and is readable
+	 * via {@link TreeBranchCommitMetadata.custom} while walking the branch's
+	 * {@link UntypedTreeViewAlpha.branchHistory | history}. It shares the lifetime of the commit it is attached
+	 * to: once that commit is trimmed from the trunk, the metadata goes with it. If the transaction produces no
+	 * commit — because its body made no changes, or because it was rolled back — the metadata is discarded.
+	 *
+	 * Nested transactions all contribute to the single commit they produce, and their metadata is available
+	 * both flattened via {@link TreeBranchCommitMetadata.custom} and structurally via
+	 * {@link TreeBranchCommitMetadata.customTree}.
+	 *
+	 * To attach metadata to the commit produced by
+	 * {@link RevertibleAlpha.(revert:3) | reverting}, use {@link RevertOptionsAlpha.customMetadata} instead.
+	 *
+	 * The value is snapshotted when the transaction starts and normalized as `JSON.stringify` would. An error is
+	 * thrown if it cannot be represented as a JSON object at all, such as when it contains a cycle or a
+	 * `bigint`. Because it is persisted, it should be kept small; it is also bounded by the runtime's maximum
+	 * op size.
+	 *
+	 * Metadata is only written to the document when `minVersionForCollab` is set to `"2.117.0"` or later.
+	 * Otherwise it is retained in memory for the local session but not persisted or replicated.
+	 */
+	readonly customMetadata?: JsonCompatibleReadOnlyObject;
 }