@fluidframework/tree 2.116.1 → 2.118.0

package/dist/simple-tree/api/schemaCompatibilityTester.d.ts

@@ -2,10 +2,26 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import type { TreeStoredSchema } from "../../core/index.js";
+import { type TreeStoredSchema } from "../../core/index.js";
 import type { SchemaUpgrade, StagedSchemaUpgradePolicy } from "../core/index.js";
 import type { TreeSchema } from "../treeSchema.js";
-import type { SchemaCompatibilityStatus } from "./tree.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 declare function getSchemaIncompatibilityDetails(viewSchema: TreeSchema, stored: TreeStoredSchema): readonly SchemaDiscrepancy[] | undefined;
+/**
+ * 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).
  *
@@ -18,6 +34,9 @@ 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 declare function checkSchemaCompatibility(viewSchema: TreeSchema, stored: TreeStoredSchema, stagedSchemaUpgrades?: Iterable<SchemaUpgrade> | StagedSchemaUpgradePolicy): Omit<SchemaCompatibilityStatus, "canInitialize">;
+export declare function checkSchemaCompatibility(viewSchema: TreeSchema, stored: TreeStoredSchema, stagedSchemaUpgrades?: Iterable<SchemaUpgrade> | StagedSchemaUpgradePolicy): Omit<SchemaCompatibilityStatusBeta, "canInitialize"> & {
+    enabledUpgrades: ReadonlyMap<SchemaUpgrade, StagedUpgradeStatus>;
+};
 //# sourceMappingURL=schemaCompatibilityTester.d.ts.map

package/dist/simple-tree/api/schemaCompatibilityTester.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemaCompatibilityTester.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaCompatibilityTester.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAGjF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACvC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,gBAAgB,EACxB,oBAAoB,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,yBAAyB,GACxE,IAAI,CAAC,yBAAyB,EAAE,eAAe,CAAC,CA6BlD"}
+{"version":3,"file":"schemaCompatibilityTester.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaCompatibilityTester.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAGN,KAAK,gBAAgB,EAErB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAIjF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAOnD,OAAO,KAAK,EAAE,6BAA6B,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAElF;;;GAGG;AACH,wBAAgB,+BAA+B,CAC9C,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,gBAAgB,GACtB,SAAS,iBAAiB,EAAE,GAAG,SAAS,CAO1C;AAmED;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACvC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,gBAAgB,EACxB,oBAAoB,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,yBAAyB,GACxE,IAAI,CAAC,6BAA6B,EAAE,eAAe,CAAC,GAAG;IACzD,eAAe,EAAE,WAAW,CAAC,aAAa,EAAE,mBAAmB,CAAC,CAAC;CACjE,CA4DA"}

package/dist/simple-tree/api/schemaCompatibilityTester.js

@@ -4,10 +4,86 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkSchemaCompatibility = void 0;
-const index_js_1 = require("../../feature-libraries/index.js");
+exports.checkSchemaCompatibility = exports.getSchemaIncompatibilityDetails = void 0;
+const internal_1 = require("@fluidframework/core-utils/internal");
+const index_js_1 = require("../../core/index.js");
+const index_js_2 = require("../core/index.js");
+const index_js_3 = require("../../feature-libraries/index.js");
 const toStoredSchema_js_1 = require("../toStoredSchema.js");
 const discrepancies_js_1 = require("./discrepancies.js");
+/**
+ * Describes the discrepancies that prevent a view schema from viewing a stored schema as a
+ * readonly array.
+ */
+function getSchemaIncompatibilityDetails(viewSchema, stored) {
+    const discrepancies = [...(0, discrepancies_js_1.getDiscrepanciesInAllowedContent)(viewSchema, stored)];
+    if (discrepancies.length === 0) {
+        return undefined;
+    }
+    return discrepancies.map(formatSchemaDiscrepancy);
+}
+exports.getSchemaIncompatibilityDetails = getSchemaIncompatibilityDetails;
+function formatSchemaDiscrepancy(value) {
+    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 : index_js_1.ValueSchema[value.view],
+                stored: value.stored === undefined ? undefined : index_js_1.ValueSchema[value.stored],
+            };
+        }
+        case "nodeKind": {
+            const storedNodeKind = value.stored === index_js_1.ObjectNodeStoredSchema
+                ? "Object"
+                : value.stored === index_js_1.MapNodeStoredSchema
+                    ? "Map"
+                    : "Leaf";
+            return {
+                mismatch: value.mismatch,
+                nodeType: value.identifier,
+                view: index_js_2.NodeKind[value.view],
+                stored: storedNodeKind,
+            };
+        }
+        default: {
+            return (0, internal_1.unreachableCase)(value);
+        }
+    }
+}
 /**
  * Determines the compatibility of a stored document (based on its stored schema) with a viewer (based on its view schema).
  *
@@ -20,29 +96,83 @@ const discrepancies_js_1 = require("./discrepancies.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
+ *
  */
 function checkSchemaCompatibility(viewSchema, stored, stagedSchemaUpgrades) {
     // The public API surface assumes defaultSchemaPolicy
-    const policy = index_js_1.defaultSchemaPolicy;
+    const policy = index_js_3.defaultSchemaPolicy;
+    const configuredPolicy = (0, toStoredSchema_js_1.resolveStoredSchemaGenerationOptions)(stagedSchemaUpgrades);
+    const includeAlreadyEnabledUpgrades = configuredPolicy.includeAlreadyEnabledUpgrades ?? true;
+    // Collect upgrade locations during the discrepancy walk (single pass).
+    const totalLocations = new Map();
+    const enabledLocations = new Map();
+    const upgradeCollector = {
+        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 (0, discrepancies_js_1.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 = [];
+    for (const discrepancy of (0, discrepancies_js_1.getDiscrepanciesInAllowedContent)(viewSchema, stored, upgradeCollector)) {
+        discrepancies.push(formatSchemaDiscrepancy(discrepancy));
     }
-    const wouldUpgradeTo = (0, toStoredSchema_js_1.toUpgradeSchema)(viewSchema.root, stagedSchemaUpgrades);
-    const canUpgrade = (0, index_js_1.allowsRepoSuperset)(policy, stored, wouldUpgradeTo);
+    const canView = discrepancies.length === 0;
+    const enabledUpgrades = computeUpgradeStatuses(totalLocations, enabledLocations);
+    const upgradePolicy = includeAlreadyEnabledUpgrades
+        ? includeEnabledUpgrades(configuredPolicy, enabledUpgrades)
+        : configuredPolicy;
+    const wouldUpgradeTo = (0, toStoredSchema_js_1.toUpgradeSchema)(viewSchema.root, upgradePolicy);
+    const canUpgrade = (0, index_js_3.allowsRepoSuperset)(policy, stored, wouldUpgradeTo);
     // If true, then upgrading has no effect on what can be stored in the document.
     // TODO: This should likely be changed to indicate up a schema upgrade would be a no-op, including stored schema metadata.
-    const isEquivalent = canView && canUpgrade && (0, index_js_1.allowsRepoSuperset)(policy, wouldUpgradeTo, stored);
+    const isEquivalent = canView && canUpgrade && (0, index_js_3.allowsRepoSuperset)(policy, wouldUpgradeTo, stored);
     return {
         canView,
         canUpgrade,
         isEquivalent,
+        discrepancies: canView ? undefined : discrepancies,
+        enabledUpgrades,
     };
 }
 exports.checkSchemaCompatibility = checkSchemaCompatibility;
+function includeEnabledUpgrades(configuredPolicy, enabledUpgrades) {
+    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, enabledLocations) {
+    const result = new Map();
+    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;
+}
 //# sourceMappingURL=schemaCompatibilityTester.js.map

package/dist/simple-tree/api/schemaCompatibilityTester.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemaCompatibilityTester.js","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaCompatibilityTester.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAIH,+DAA2F;AAC3F,4DAAuD;AAGvD,yDAAsE;AAGtE;;;;;;;;;;;;GAYG;AACH,SAAgB,wBAAwB,CACvC,UAAsB,EACtB,MAAwB,EACxB,oBAA0E;IAE1E,qDAAqD;IACrD,MAAM,MAAM,GAAG,8BAAmB,CAAC;IAEnC,gHAAgH;IAChH,6HAA6H;IAC7H,sDAAsD;IACtD,8HAA8H;IAC9H,IAAI,OAAO,GAAG,IAAI,CAAC;IAEnB,KAAK,MAAM,YAAY,IAAI,IAAA,mDAAgC,EAAC,UAAU,EAAE,MAAM,CAAC,EAAE,CAAC;QACjF,OAAO,GAAG,KAAK,CAAC;QAChB,MAAM;IACP,CAAC;IAED,MAAM,cAAc,GAAG,IAAA,mCAAe,EAAC,UAAU,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;IAE9E,MAAM,UAAU,GAAG,IAAA,6BAAkB,EAAC,MAAM,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;IAEtE,+EAA+E;IAC/E,0HAA0H;IAC1H,MAAM,YAAY,GACjB,OAAO,IAAI,UAAU,IAAI,IAAA,6BAAkB,EAAC,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,CAAC;IAE7E,OAAO;QACN,OAAO;QACP,UAAU;QACV,YAAY;KACZ,CAAC;AACH,CAAC;AAjCD,4DAiCC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { TreeStoredSchema } from \"../../core/index.js\";\nimport type { SchemaUpgrade, StagedSchemaUpgradePolicy } from \"../core/index.js\";\nimport { allowsRepoSuperset, defaultSchemaPolicy } from \"../../feature-libraries/index.js\";\nimport { toUpgradeSchema } from \"../toStoredSchema.js\";\nimport type { TreeSchema } from \"../treeSchema.js\";\n\nimport { getDiscrepanciesInAllowedContent } from \"./discrepancies.js\";\nimport type { SchemaCompatibilityStatus } from \"./tree.js\";\n\n/**\n * Determines the compatibility of a stored document (based on its stored schema) with a viewer (based on its view schema).\n *\n * Adapters can be provided to handle differences between the two schema.\n * Adapters should only use to types in the `view` SchemaRepository.\n *\n * TODO: this API violates the parse don't validate design philosophy.\n * It should be wrapped with (or replaced by) a parse style API.\n *\n * @param viewSchema - Schema for the view\n * @param stored - The stored schema to check compatibility against\n * @param stagedSchemaUpgrades - Staged schema upgrades enabled for this view, or explicit stored-schema generation options\n */\nexport function checkSchemaCompatibility(\n\tviewSchema: TreeSchema,\n\tstored: TreeStoredSchema,\n\tstagedSchemaUpgrades?: Iterable<SchemaUpgrade> | StagedSchemaUpgradePolicy,\n): Omit<SchemaCompatibilityStatus, \"canInitialize\"> {\n\t// The public API surface assumes defaultSchemaPolicy\n\tconst policy = defaultSchemaPolicy;\n\n\t// View schema allows a subset of documents that stored schema does, and the discrepancies are allowed by policy\n\t// determined by the view schema (i.e. objects with extra optional fields in the stored schema have opted into allowing this.\n\t// In the future, this would also include things like:\n\t// - fields with more allowed types in the stored schema than in the view schema have out-of-schema \"unknown content\" adapters\n\tlet canView = true;\n\n\tfor (const _discrepancy of getDiscrepanciesInAllowedContent(viewSchema, stored)) {\n\t\tcanView = false;\n\t\tbreak;\n\t}\n\n\tconst wouldUpgradeTo = toUpgradeSchema(viewSchema.root, stagedSchemaUpgrades);\n\n\tconst canUpgrade = allowsRepoSuperset(policy, stored, wouldUpgradeTo);\n\n\t// If true, then upgrading has no effect on what can be stored in the document.\n\t// TODO: This should likely be changed to indicate up a schema upgrade would be a no-op, including stored schema metadata.\n\tconst isEquivalent =\n\t\tcanView && canUpgrade && allowsRepoSuperset(policy, wouldUpgradeTo, stored);\n\n\treturn {\n\t\tcanView,\n\t\tcanUpgrade,\n\t\tisEquivalent,\n\t};\n}\n"]}
+{"version":3,"file":"schemaCompatibilityTester.js","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaCompatibilityTester.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { unreachableCase } from \"@fluidframework/core-utils/internal\";\n\nimport {\n\tMapNodeStoredSchema,\n\tObjectNodeStoredSchema,\n\ttype TreeStoredSchema,\n\tValueSchema,\n} from \"../../core/index.js\";\nimport type { SchemaUpgrade, StagedSchemaUpgradePolicy } from \"../core/index.js\";\nimport { NodeKind } from \"../core/index.js\";\nimport { allowsRepoSuperset, defaultSchemaPolicy } from \"../../feature-libraries/index.js\";\nimport { resolveStoredSchemaGenerationOptions, toUpgradeSchema } from \"../toStoredSchema.js\";\nimport type { TreeSchema } from \"../treeSchema.js\";\n\nimport {\n\tgetDiscrepanciesInAllowedContent,\n\ttype Discrepancy,\n\ttype UpgradeLocationCollector,\n} from \"./discrepancies.js\";\nimport type { SchemaCompatibilityStatusBeta, SchemaDiscrepancy } from \"./tree.js\";\n\n/**\n * Describes the discrepancies that prevent a view schema from viewing a stored schema as a\n * readonly array.\n */\nexport function getSchemaIncompatibilityDetails(\n\tviewSchema: TreeSchema,\n\tstored: TreeStoredSchema,\n): readonly SchemaDiscrepancy[] | undefined {\n\tconst discrepancies = [...getDiscrepanciesInAllowedContent(viewSchema, stored)];\n\tif (discrepancies.length === 0) {\n\t\treturn undefined;\n\t}\n\n\treturn discrepancies.map(formatSchemaDiscrepancy);\n}\n\nfunction formatSchemaDiscrepancy(value: Discrepancy): SchemaDiscrepancy {\n\tswitch (value.mismatch) {\n\t\tcase \"allowedTypes\": {\n\t\t\treturn {\n\t\t\t\tmismatch: value.mismatch,\n\t\t\t\tlocation:\n\t\t\t\t\tvalue.identifier === undefined\n\t\t\t\t\t\t? \"root\"\n\t\t\t\t\t\t: {\n\t\t\t\t\t\t\t\tnodeType: value.identifier,\n\t\t\t\t\t\t\t\tfieldKey: value.fieldKey,\n\t\t\t\t\t\t\t},\n\t\t\t\tview: value.view.map(({ type }) => type.identifier).sort(),\n\t\t\t\t...(value.stagedView === undefined\n\t\t\t\t\t? {}\n\t\t\t\t\t: {\n\t\t\t\t\t\t\tstagedView: value.stagedView.map(({ type }) => type.identifier).sort(),\n\t\t\t\t\t\t}),\n\t\t\t\tstored: [...value.stored].sort(),\n\t\t\t\t...(value.viewIsStagedOptional === true ? { viewIsStagedOptional: true } : {}),\n\t\t\t};\n\t\t}\n\t\tcase \"fieldKind\": {\n\t\t\treturn {\n\t\t\t\tmismatch: value.mismatch,\n\t\t\t\tlocation:\n\t\t\t\t\tvalue.identifier === undefined\n\t\t\t\t\t\t? \"root\"\n\t\t\t\t\t\t: {\n\t\t\t\t\t\t\t\tnodeType: value.identifier,\n\t\t\t\t\t\t\t\tfieldKey: value.fieldKey,\n\t\t\t\t\t\t\t},\n\t\t\t\tview: value.view,\n\t\t\t\tstored: value.stored,\n\t\t\t\t...(value.viewIsStagedOptional === true ? { viewIsStagedOptional: true } : {}),\n\t\t\t};\n\t\t}\n\t\tcase \"valueSchema\": {\n\t\t\treturn {\n\t\t\t\tmismatch: value.mismatch,\n\t\t\t\tnodeType: value.identifier,\n\t\t\t\tview: value.view === undefined ? undefined : ValueSchema[value.view],\n\t\t\t\tstored: value.stored === undefined ? undefined : ValueSchema[value.stored],\n\t\t\t};\n\t\t}\n\t\tcase \"nodeKind\": {\n\t\t\tconst storedNodeKind =\n\t\t\t\tvalue.stored === ObjectNodeStoredSchema\n\t\t\t\t\t? \"Object\"\n\t\t\t\t\t: value.stored === MapNodeStoredSchema\n\t\t\t\t\t\t? \"Map\"\n\t\t\t\t\t\t: \"Leaf\";\n\t\t\treturn {\n\t\t\t\tmismatch: value.mismatch,\n\t\t\t\tnodeType: value.identifier,\n\t\t\t\tview: NodeKind[value.view],\n\t\t\t\tstored: storedNodeKind,\n\t\t\t};\n\t\t}\n\t\tdefault: {\n\t\t\treturn unreachableCase(value);\n\t\t}\n\t}\n}\n\n/**\n * The enablement status of a staged schema upgrade in a document's stored schema.\n *\n * @remarks\n * - `\"disabled\"` — no locations guarded by the upgrade are enabled in stored schema.\n * - `\"partial\"` — at least one location is enabled but not all of them.\n * - `\"enabled\"` — all locations guarded by the upgrade are enabled in stored schema.\n *\n * @alpha\n */\nexport type StagedUpgradeStatus = \"disabled\" | \"partial\" | \"enabled\";\n\n/**\n * Determines the compatibility of a stored document (based on its stored schema) with a viewer (based on its view schema).\n *\n * Adapters can be provided to handle differences between the two schema.\n * Adapters should only use to types in the `view` SchemaRepository.\n *\n * TODO: this API violates the parse don't validate design philosophy.\n * It should be wrapped with (or replaced by) a parse style API.\n *\n * @param viewSchema - Schema for the view\n * @param stored - The stored schema to check compatibility against\n * @param stagedSchemaUpgrades - Staged schema upgrades enabled for this view, or explicit stored-schema generation options\n *\n */\nexport function checkSchemaCompatibility(\n\tviewSchema: TreeSchema,\n\tstored: TreeStoredSchema,\n\tstagedSchemaUpgrades?: Iterable<SchemaUpgrade> | StagedSchemaUpgradePolicy,\n): Omit<SchemaCompatibilityStatusBeta, \"canInitialize\"> & {\n\tenabledUpgrades: ReadonlyMap<SchemaUpgrade, StagedUpgradeStatus>;\n} {\n\t// The public API surface assumes defaultSchemaPolicy\n\tconst policy = defaultSchemaPolicy;\n\tconst configuredPolicy = resolveStoredSchemaGenerationOptions(stagedSchemaUpgrades);\n\tconst includeAlreadyEnabledUpgrades = configuredPolicy.includeAlreadyEnabledUpgrades ?? true;\n\n\t// Collect upgrade locations during the discrepancy walk (single pass).\n\tconst totalLocations = new Map<SchemaUpgrade, number>();\n\tconst enabledLocations = new Map<SchemaUpgrade, number>();\n\tconst upgradeCollector: UpgradeLocationCollector = {\n\t\tallowedType(upgrade, isEnabled) {\n\t\t\ttotalLocations.set(upgrade, (totalLocations.get(upgrade) ?? 0) + 1);\n\t\t\tif (isEnabled) {\n\t\t\t\tenabledLocations.set(upgrade, (enabledLocations.get(upgrade) ?? 0) + 1);\n\t\t\t}\n\t\t},\n\t\toptionalField(upgrade, isEnabled) {\n\t\t\ttotalLocations.set(upgrade, (totalLocations.get(upgrade) ?? 0) + 1);\n\t\t\tif (isEnabled) {\n\t\t\t\tenabledLocations.set(upgrade, (enabledLocations.get(upgrade) ?? 0) + 1);\n\t\t\t}\n\t\t},\n\t};\n\n\t// View schema allows a subset of documents that stored schema does, and the discrepancies are allowed by policy\n\t// determined by the view schema (i.e. objects with extra optional fields in the stored schema have opted into allowing this.\n\t// In the future, this would also include things like:\n\t// - fields with more allowed types in the stored schema than in the view schema have out-of-schema \"unknown content\" adapters\n\t// Complete the full walk even after finding an incompatibility so discrepancy details and\n\t// staged-upgrade status contain all available information for debugging.\n\tconst discrepancies: SchemaDiscrepancy[] = [];\n\tfor (const discrepancy of getDiscrepanciesInAllowedContent(\n\t\tviewSchema,\n\t\tstored,\n\t\tupgradeCollector,\n\t)) {\n\t\tdiscrepancies.push(formatSchemaDiscrepancy(discrepancy));\n\t}\n\tconst canView = discrepancies.length === 0;\n\n\tconst enabledUpgrades = computeUpgradeStatuses(totalLocations, enabledLocations);\n\tconst upgradePolicy = includeAlreadyEnabledUpgrades\n\t\t? includeEnabledUpgrades(configuredPolicy, enabledUpgrades)\n\t\t: configuredPolicy;\n\tconst wouldUpgradeTo = toUpgradeSchema(viewSchema.root, upgradePolicy);\n\n\tconst canUpgrade = allowsRepoSuperset(policy, stored, wouldUpgradeTo);\n\n\t// If true, then upgrading has no effect on what can be stored in the document.\n\t// TODO: This should likely be changed to indicate up a schema upgrade would be a no-op, including stored schema metadata.\n\tconst isEquivalent =\n\t\tcanView && canUpgrade && allowsRepoSuperset(policy, wouldUpgradeTo, stored);\n\n\treturn {\n\t\tcanView,\n\t\tcanUpgrade,\n\t\tisEquivalent,\n\t\tdiscrepancies: canView ? undefined : discrepancies,\n\t\tenabledUpgrades,\n\t};\n}\n\nfunction includeEnabledUpgrades(\n\tconfiguredPolicy: StagedSchemaUpgradePolicy,\n\tenabledUpgrades: ReadonlyMap<SchemaUpgrade, StagedUpgradeStatus>,\n): StagedSchemaUpgradePolicy {\n\tif (enabledUpgrades.size === 0) {\n\t\treturn configuredPolicy;\n\t}\n\treturn {\n\t\tincludeStaged: (upgrade) =>\n\t\t\tconfiguredPolicy.includeStaged(upgrade) || enabledUpgrades.has(upgrade),\n\t\tincludeStagedOptional: (upgrade) =>\n\t\t\tconfiguredPolicy.includeStagedOptional(upgrade) || enabledUpgrades.has(upgrade),\n\t};\n}\n\n/**\n * Computes the {@link StagedUpgradeStatus} for each upgrade token from total and enabled location counts.\n * Only tokens with at least one enabled location are included in the returned map.\n */\nfunction computeUpgradeStatuses(\n\ttotalLocations: ReadonlyMap<SchemaUpgrade, number>,\n\tenabledLocations: ReadonlyMap<SchemaUpgrade, number>,\n): ReadonlyMap<SchemaUpgrade, StagedUpgradeStatus> {\n\tconst result = new Map<SchemaUpgrade, StagedUpgradeStatus>();\n\tfor (const [upgrade, total] of totalLocations) {\n\t\tconst enabled = enabledLocations.get(upgrade) ?? 0;\n\t\tif (enabled > 0 && enabled < total) {\n\t\t\tresult.set(upgrade, \"partial\");\n\t\t} else if (enabled >= total && enabled > 0) {\n\t\t\tresult.set(upgrade, \"enabled\");\n\t\t}\n\t}\n\treturn result;\n}\n"]}

package/dist/simple-tree/api/transactionTypes.d.ts

@@ -4,6 +4,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".
  * @public
@@ -85,7 +86,7 @@ export type TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue> = Trans
     readonly preconditionsOnRevert?: readonly TransactionConstraintAlpha[];
 };
 /**
- * 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
  */
@@ -150,7 +151,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.
      */
@@ -185,5 +186,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;
 }
 //# sourceMappingURL=transactionTypes.d.ts.map

package/dist/simple-tree/api/transactionTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transactionTypes.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/transactionTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAElE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,QAAQ,eAA4C,CAAC;AAElE;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,GAAG,wBAAwB,CAAC;AAE7D;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,qBAAqB,GAAG,kBAAkB,CAAC;AAEpF;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,MAAM;IAChC,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,6BAA6B,CAAC,aAAa,EAAE,aAAa,IACnE,CAAC,SAAS,CAAC,aAAa,CAAC,GAAG;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;CACzB,CAAC,GACF,CAAC,SAAS,CAAC,aAAa,CAAC,GAAG;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;CACvB,CAAC,CAAC;AAEN;;;;GAIG;AACH,MAAM,MAAM,iCAAiC,GAAG,IAAI,CACnD,6BAA6B,CAAC,OAAO,EAAE,OAAO,CAAC,EAC/C,OAAO,CACP,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,8BAA8B,CAAC,aAAa,EAAE,aAAa,IACtE,6BAA6B,CAAC,aAAa,EAAE,aAAa,CAAC,GAAG;IAC7D;;;;;;OAMG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;CACvE,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,kCAAkC,GAAG,IAAI,CACpD,8BAA8B,CAAC,OAAO,EAAE,OAAO,CAAC,EAChD,OAAO,CACP,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,wBAAwB,CAAC,aAAa,CAAE,SAAQ,SAAS,CAAC,aAAa,CAAC;IACxF,2HAA2H;IAC3H,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB,CAAC,aAAa,CAAE,SAAQ,SAAS,CAAC,aAAa,CAAC;IACvF,uGAAuG;IACvG,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,CAAC,aAAa,EAAE,aAAa,IAC5D,wBAAwB,CAAC,aAAa,CAAC,GACvC,uBAAuB,CAAC,aAAa,CAAC,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAC9B,IAAI,CAAC,wBAAwB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,GAChD,IAAI,CAAC,uBAAuB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;AAEnD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,wBAChB,SAAQ,UAAU,CAAC,+CAA+C,CAAC;CAAG;AAEvE;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACxC;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB;IAC1E;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAE/D;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,wBAAwB,CAAC;CAClD"}
+{"version":3,"file":"transactionTypes.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/transactionTypes.ts"],"names":[],"mappings":"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"}

package/dist/simple-tree/api/transactionTypes.js.map

@@ -1 +1 @@
-{"version":3,"file":"transactionTypes.js","sourceRoot":"","sources":["../../../src/simple-tree/api/transactionTypes.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAMH;;;GAGG;AACU,QAAA,QAAQ,GAAG,MAAM,CAAC,iCAAiC,CAAC,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ErasedType } from \"@fluidframework/core-interfaces\";\n\nimport type { TreeNode } from \"../core/index.js\";\n\n/**\n * A special object that signifies when a SharedTree {@link RunTransaction | transaction} should \"roll back\".\n * @public\n */\nexport const rollback = Symbol(\"SharedTree Transaction Rollback\");\n\n/**\n * A requirement for a SharedTree transaction to succeed.\n * @remarks Transaction constraints are useful for validating that the state of the tree meets some requirement when a transaction runs.\n * In general, when running a transaction a client can validate their tree state in whatever way they wish and decide to either proceed with the transaction or not.\n * However, they cannot know what the tree state will be when the transaction is _sequenced_.\n * There may have been any number of edits from other clients that get sequenced before the transaction is eventually sequenced.\n * Constraints provide a way to validate the tree state after the transaction has been sequenced and abort the transaction if the constraints are not met.\n * All clients will validate the constraints of a transaction when it is sequenced, so all clients will agree on whether the transaction succeeds or not.\n * @public\n */\nexport type TransactionConstraint = NodeInDocumentConstraint; // TODO: Add more constraint types here\n\n/**\n * Type for alpha version {@link TransactionConstraint | constraint}s\n * @sealed @alpha\n */\nexport type TransactionConstraintAlpha = TransactionConstraint | NoChangeConstraint; // TODO: Add more constraint types here\n\n/**\n * A transaction {@link TransactionConstraint | constraint} which requires that the given node exists in the tree.\n * @remarks The node must be in the document (its {@link TreeStatus | status} must be {@link TreeStatus.InDocument | InDocument}) to qualify as \"existing\".\n * @public\n */\nexport interface NodeInDocumentConstraint {\n\treadonly type: \"nodeInDocument\";\n\treadonly node: TreeNode;\n}\n\n/**\n * A {@link TransactionConstraintAlpha | constraint} which requires that, for this transaction to apply, the document must be in the same state immediately before the transaction is applied as it was before the transaction was authored.\n * When used as a revert precondition it requires that, for the revert to apply, the document must be in the same state immediately before the revert is applied as it was after the transaction was applied.\n * @alpha\n */\nexport interface NoChangeConstraint {\n\treadonly type: \"noChange\";\n}\n\n/**\n * Contains a value returned from a transaction.\n * @input\n * @beta\n */\nexport interface WithValue<TValue> {\n\t/** The user-supplied value. */\n\treadonly value: TValue;\n}\n\n/**\n * Contains a value and status returned from a user-supplied {@link TreeViewBeta.runTransaction | transaction callback}.\n * @input\n * @beta\n */\nexport type TransactionCallbackStatusBeta<TSuccessValue, TFailureValue> =\n\t| (WithValue<TSuccessValue> & {\n\t\t\t/** Indicates that the transaction callback ran successfully. */\n\t\t\treadonly rollback?: false;\n\t  })\n\t| (WithValue<TFailureValue> & {\n\t\t\t/** Indicates that the transaction callback failed and the transaction should be rolled back. */\n\t\t\treadonly rollback: true;\n\t  });\n\n/**\n * The result of a {@link TreeViewBeta.runTransaction | transaction} that doesn't return a value.\n * @input\n * @beta\n */\nexport type VoidTransactionCallbackStatusBeta = Omit<\n\tTransactionCallbackStatusBeta<unknown, unknown>,\n\t\"value\"\n>;\n\n/**\n * {@link TransactionCallbackStatusBeta} extended with alpha-only {@link TransactionConstraintAlpha | constraint} options.\n * @input\n * @alpha\n */\nexport type TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue> =\n\tTransactionCallbackStatusBeta<TSuccessValue, TFailureValue> & {\n\t\t/**\n\t\t * An optional list of {@link TransactionConstraintAlpha | constraints} that will be checked when the commit corresponding\n\t\t * to this transaction is reverted. If any of these constraints are not met when the revert is being applied either\n\t\t * locally or on remote clients, the revert will be ignored.\n\t\t * These constraints must also be met at the time they are first introduced. If they are not met after the transaction\n\t\t * callback returns, then `runTransaction` (which invokes the transaction callback) will throw a `UsageError`.\n\t\t */\n\t\treadonly preconditionsOnRevert?: readonly TransactionConstraintAlpha[];\n\t};\n\n/**\n * The result of a {@link TreeBranchAlpha.(runTransaction:2) | transaction} that doesn't return a value.\n * @input\n * @alpha\n */\nexport type VoidTransactionCallbackStatusAlpha = Omit<\n\tTransactionCallbackStatusAlpha<unknown, unknown>,\n\t\"value\"\n>;\n\n/**\n * The result of a {@link TreeViewBeta.(runTransaction:1) | transaction} that completed successfully.\n * @sealed\n * @beta\n */\nexport interface TransactionResultSuccess<TSuccessValue> extends WithValue<TSuccessValue> {\n\t/** The success flag for a transaction that completed without being {@link TransactionCallbackStatusBeta | rolled back}. */\n\treadonly success: true;\n}\n\n/**\n * The result of a {@link TreeViewBeta.runTransaction | transaction} that was rolled back.\n * @sealed\n * @beta\n */\nexport interface TransactionResultFailed<TFailureValue> extends WithValue<TFailureValue> {\n\t/** The failure flag for a transaction that was {@link TransactionCallbackStatusBeta | rolled back}. */\n\treadonly success: false;\n}\n\n/**\n * The result of the {@link RunTransaction | RunTransaction} API.\n * @sealed\n * @beta\n */\nexport type TransactionValueResult<TSuccessValue, TFailureValue> =\n\t| TransactionResultSuccess<TSuccessValue>\n\t| TransactionResultFailed<TFailureValue>;\n\n/**\n * The result of the {@link RunTransaction | RunTransaction} API. This is the same as {@link TransactionValueResult}\n * but with the `value` field omitted. This is useful when the transaction callback doesn't need to return a value.\n * @sealed\n * @beta\n */\nexport type TransactionVoidResult =\n\t| Omit<TransactionResultSuccess<unknown>, \"value\">\n\t| Omit<TransactionResultFailed<unknown>, \"value\">;\n\n/**\n * A type-erased function that post-processes the change produced when a transaction is committed.\n *\n * @remarks\n * Supply one via {@link RunTransactionParamsAlpha.postProcessor} to process/alter\n * the change that a transaction produces. For example a post-processor could\n * remove extraneous information, so that the resulting squashed change contains\n * no extraneous information.\n *\n * This type intentionally hides its internal representation: its concrete shape\n * is an implementation detail of `@fluidframework/tree`. Obtain a value of this\n * type from a `@fluidframework/tree` helper or constant rather than constructing\n * one directly.\n *\n * @alpha\n * @sealed\n * @system\n */\nexport interface TransactionPostProcessor\n\textends ErasedType<\"@fluidframework/tree.TransactionPostProcessor\"> {}\n\n/**\n * The parameters for the {@link RunTransaction | RunTransaction} API.\n * @input\n * @beta\n */\nexport interface RunTransactionParamsBeta {\n\t/**\n\t * A label for this transaction that allows it to be correlated with later edits (e.g. for controlling undo/redo grouping).\n\t * @remarks\n\t * 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.\n\t *\n\t * If there is a nested transaction, only the outermost transaction label will be used.\n\t */\n\treadonly label?: unknown;\n}\n\n/**\n * The parameters for the {@link RunTransaction | RunTransaction} API, extended with alpha-only {@link TransactionConstraintAlpha | constraint} options.\n * @input\n * @alpha\n */\nexport interface RunTransactionParamsAlpha extends RunTransactionParamsBeta {\n\t/**\n\t * An optional list of {@link TransactionConstraintAlpha | constraints} that are checked just before the transaction begins.\n\t * @remarks\n\t * If any of the constraints are not met when `runTransaction` is called, an error will be thrown.\n\t * If any of the constraints are not met after the transaction has been ordered by the service, it will be rolled back on this client and ignored by all other clients.\n\t */\n\treadonly preconditions?: readonly TransactionConstraintAlpha[];\n\n\t/**\n\t * An optional {@link TransactionPostProcessor | post-processor} applied to\n\t * the change produced when this transaction is committed.\n\t * @remarks\n\t * When omitted, the transaction's edits are squashed without any such processing.\n\t *\n\t * Specific post-processors are applied according to their own rules for\n\t * optimization and other post-processing tasks in a transaction stack. For\n\t * example a \"minimization\" post-processor may be applied once for the\n\t * outermost transaction in a stack as it will process all nested edits and\n\t * there is no benefit from multiple applications.\n\t *\n\t * Note: minimization is not yet implemented. Supplying a post-processor currently has no observable effect beyond\n\t * reserving the behavior; a real post-processor will be provided in a future change.\n\t */\n\treadonly postProcessor?: TransactionPostProcessor;\n}\n"]}
+{"version":3,"file":"transactionTypes.js","sourceRoot":"","sources":["../../../src/simple-tree/api/transactionTypes.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAOH;;;GAGG;AACU,QAAA,QAAQ,GAAG,MAAM,CAAC,iCAAiC,CAAC,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ErasedType } from \"@fluidframework/core-interfaces\";\n\nimport type { TreeNode } from \"../core/index.js\";\nimport type { JsonCompatibleReadOnlyObject } from \"../../util/index.js\";\n\n/**\n * A special object that signifies when a SharedTree {@link RunTransaction | transaction} should \"roll back\".\n * @public\n */\nexport const rollback = Symbol(\"SharedTree Transaction Rollback\");\n\n/**\n * A requirement for a SharedTree transaction to succeed.\n * @remarks Transaction constraints are useful for validating that the state of the tree meets some requirement when a transaction runs.\n * In general, when running a transaction a client can validate their tree state in whatever way they wish and decide to either proceed with the transaction or not.\n * However, they cannot know what the tree state will be when the transaction is _sequenced_.\n * There may have been any number of edits from other clients that get sequenced before the transaction is eventually sequenced.\n * Constraints provide a way to validate the tree state after the transaction has been sequenced and abort the transaction if the constraints are not met.\n * All clients will validate the constraints of a transaction when it is sequenced, so all clients will agree on whether the transaction succeeds or not.\n * @public\n */\nexport type TransactionConstraint = NodeInDocumentConstraint; // TODO: Add more constraint types here\n\n/**\n * Type for alpha version {@link TransactionConstraint | constraint}s\n * @sealed @alpha\n */\nexport type TransactionConstraintAlpha = TransactionConstraint | NoChangeConstraint; // TODO: Add more constraint types here\n\n/**\n * A transaction {@link TransactionConstraint | constraint} which requires that the given node exists in the tree.\n * @remarks The node must be in the document (its {@link TreeStatus | status} must be {@link TreeStatus.InDocument | InDocument}) to qualify as \"existing\".\n * @public\n */\nexport interface NodeInDocumentConstraint {\n\treadonly type: \"nodeInDocument\";\n\treadonly node: TreeNode;\n}\n\n/**\n * A {@link TransactionConstraintAlpha | constraint} which requires that, for this transaction to apply, the document must be in the same state immediately before the transaction is applied as it was before the transaction was authored.\n * When used as a revert precondition it requires that, for the revert to apply, the document must be in the same state immediately before the revert is applied as it was after the transaction was applied.\n * @alpha\n */\nexport interface NoChangeConstraint {\n\treadonly type: \"noChange\";\n}\n\n/**\n * Contains a value returned from a transaction.\n * @input\n * @beta\n */\nexport interface WithValue<TValue> {\n\t/** The user-supplied value. */\n\treadonly value: TValue;\n}\n\n/**\n * Contains a value and status returned from a user-supplied {@link TreeViewBeta.runTransaction | transaction callback}.\n * @input\n * @beta\n */\nexport type TransactionCallbackStatusBeta<TSuccessValue, TFailureValue> =\n\t| (WithValue<TSuccessValue> & {\n\t\t\t/** Indicates that the transaction callback ran successfully. */\n\t\t\treadonly rollback?: false;\n\t  })\n\t| (WithValue<TFailureValue> & {\n\t\t\t/** Indicates that the transaction callback failed and the transaction should be rolled back. */\n\t\t\treadonly rollback: true;\n\t  });\n\n/**\n * The result of a {@link TreeViewBeta.runTransaction | transaction} that doesn't return a value.\n * @input\n * @beta\n */\nexport type VoidTransactionCallbackStatusBeta = Omit<\n\tTransactionCallbackStatusBeta<unknown, unknown>,\n\t\"value\"\n>;\n\n/**\n * {@link TransactionCallbackStatusBeta} extended with alpha-only {@link TransactionConstraintAlpha | constraint} options.\n * @input\n * @alpha\n */\nexport type TransactionCallbackStatusAlpha<TSuccessValue, TFailureValue> =\n\tTransactionCallbackStatusBeta<TSuccessValue, TFailureValue> & {\n\t\t/**\n\t\t * An optional list of {@link TransactionConstraintAlpha | constraints} that will be checked when the commit corresponding\n\t\t * to this transaction is reverted. If any of these constraints are not met when the revert is being applied either\n\t\t * locally or on remote clients, the revert will be ignored.\n\t\t * These constraints must also be met at the time they are first introduced. If they are not met after the transaction\n\t\t * callback returns, then `runTransaction` (which invokes the transaction callback) will throw a `UsageError`.\n\t\t */\n\t\treadonly preconditionsOnRevert?: readonly TransactionConstraintAlpha[];\n\t};\n\n/**\n * The result of a {@link UntypedTreeViewAlpha.(runTransaction:2) | transaction} that doesn't return a value.\n * @input\n * @alpha\n */\nexport type VoidTransactionCallbackStatusAlpha = Omit<\n\tTransactionCallbackStatusAlpha<unknown, unknown>,\n\t\"value\"\n>;\n\n/**\n * The result of a {@link TreeViewBeta.(runTransaction:1) | transaction} that completed successfully.\n * @sealed\n * @beta\n */\nexport interface TransactionResultSuccess<TSuccessValue> extends WithValue<TSuccessValue> {\n\t/** The success flag for a transaction that completed without being {@link TransactionCallbackStatusBeta | rolled back}. */\n\treadonly success: true;\n}\n\n/**\n * The result of a {@link TreeViewBeta.runTransaction | transaction} that was rolled back.\n * @sealed\n * @beta\n */\nexport interface TransactionResultFailed<TFailureValue> extends WithValue<TFailureValue> {\n\t/** The failure flag for a transaction that was {@link TransactionCallbackStatusBeta | rolled back}. */\n\treadonly success: false;\n}\n\n/**\n * The result of the {@link RunTransaction | RunTransaction} API.\n * @sealed\n * @beta\n */\nexport type TransactionValueResult<TSuccessValue, TFailureValue> =\n\t| TransactionResultSuccess<TSuccessValue>\n\t| TransactionResultFailed<TFailureValue>;\n\n/**\n * The result of the {@link RunTransaction | RunTransaction} API. This is the same as {@link TransactionValueResult}\n * but with the `value` field omitted. This is useful when the transaction callback doesn't need to return a value.\n * @sealed\n * @beta\n */\nexport type TransactionVoidResult =\n\t| Omit<TransactionResultSuccess<unknown>, \"value\">\n\t| Omit<TransactionResultFailed<unknown>, \"value\">;\n\n/**\n * A type-erased function that post-processes the change produced when a transaction is committed.\n *\n * @remarks\n * Supply one via {@link RunTransactionParamsAlpha.postProcessor} to process/alter\n * the change that a transaction produces. For example a post-processor could\n * remove extraneous information, so that the resulting squashed change contains\n * no extraneous information.\n *\n * This type intentionally hides its internal representation: its concrete shape\n * is an implementation detail of `@fluidframework/tree`. Obtain a value of this\n * type from a `@fluidframework/tree` helper or constant rather than constructing\n * one directly.\n *\n * @alpha\n * @sealed\n * @system\n */\nexport interface TransactionPostProcessor\n\textends ErasedType<\"@fluidframework/tree.TransactionPostProcessor\"> {}\n\n/**\n * The parameters for the {@link RunTransaction | RunTransaction} API.\n * @input\n * @beta\n */\nexport interface RunTransactionParamsBeta {\n\t/**\n\t * A label for this transaction that allows it to be correlated with later edits (e.g. for controlling undo/redo grouping).\n\t * @remarks\n\t * 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.\n\t *\n\t * If there is a nested transaction, only the outermost transaction label will be used.\n\t */\n\treadonly label?: unknown;\n}\n\n/**\n * The parameters for the {@link RunTransaction | RunTransaction} API, extended with alpha-only {@link TransactionConstraintAlpha | constraint} options.\n * @input\n * @alpha\n */\nexport interface RunTransactionParamsAlpha extends RunTransactionParamsBeta {\n\t/**\n\t * An optional list of {@link TransactionConstraintAlpha | constraints} that are checked just before the transaction begins.\n\t * @remarks\n\t * If any of the constraints are not met when `runTransaction` is called, an error will be thrown.\n\t * If any of the constraints are not met after the transaction has been ordered by the service, it will be rolled back on this client and ignored by all other clients.\n\t */\n\treadonly preconditions?: readonly TransactionConstraintAlpha[];\n\n\t/**\n\t * An optional {@link TransactionPostProcessor | post-processor} applied to\n\t * the change produced when this transaction is committed.\n\t * @remarks\n\t * When omitted, the transaction's edits are squashed without any such processing.\n\t *\n\t * Specific post-processors are applied according to their own rules for\n\t * optimization and other post-processing tasks in a transaction stack. For\n\t * example a \"minimization\" post-processor may be applied once for the\n\t * outermost transaction in a stack as it will process all nested edits and\n\t * there is no benefit from multiple applications.\n\t *\n\t * Note: minimization is not yet implemented. Supplying a post-processor currently has no observable effect beyond\n\t * reserving the behavior; a real post-processor will be provided in a future change.\n\t */\n\treadonly postProcessor?: TransactionPostProcessor;\n\n\t/**\n\t * Arbitrary, application-defined metadata to persist alongside the commit that this transaction produces.\n\t * @remarks\n\t * The metadata is replicated to all collaborating clients and persisted in the document, and is readable\n\t * via {@link TreeBranchCommitMetadata.custom} while walking the branch's\n\t * {@link UntypedTreeViewAlpha.branchHistory | history}. It shares the lifetime of the commit it is attached\n\t * to: once that commit is trimmed from the trunk, the metadata goes with it. If the transaction produces no\n\t * commit — because its body made no changes, or because it was rolled back — the metadata is discarded.\n\t *\n\t * Nested transactions all contribute to the single commit they produce, and their metadata is available\n\t * both flattened via {@link TreeBranchCommitMetadata.custom} and structurally via\n\t * {@link TreeBranchCommitMetadata.customTree}.\n\t *\n\t * To attach metadata to the commit produced by\n\t * {@link RevertibleAlpha.(revert:3) | reverting}, use {@link RevertOptionsAlpha.customMetadata} instead.\n\t *\n\t * The value is snapshotted when the transaction starts and normalized as `JSON.stringify` would. An error is\n\t * thrown if it cannot be represented as a JSON object at all, such as when it contains a cycle or a\n\t * `bigint`. Because it is persisted, it should be kept small; it is also bounded by the runtime's maximum\n\t * op size.\n\t *\n\t * Metadata is only written to the document when `minVersionForCollab` is set to `\"2.117.0\"` or later.\n\t * Otherwise it is retained in memory for the local session but not persisted or replicated.\n\t */\n\treadonly customMetadata?: JsonCompatibleReadOnlyObject;\n}\n"]}