@fluidframework/tree 2.80.0 → 2.81.0

package/lib/simple-tree/api/snapshotCompatibilityChecker.js

@@ -2,9 +2,13 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
+import { assert, transformMapValues } from "@fluidframework/core-utils/internal";
+import { selectVersionRoundedDown } from "@fluidframework/runtime-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import * as semver from "semver-ts";
 import { toInitialSchema } from "../toStoredSchema.js";
-import { TreeViewConfigurationAlpha, TreeViewConfiguration } from "./configuration.js";
 import { createTreeSchema } from "../treeSchema.js";
+import { TreeViewConfigurationAlpha, TreeViewConfiguration } from "./configuration.js";
 import { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
 import { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";
 import { decodeSchemaCompatibilitySnapshot, encodeSchemaCompatibilitySnapshot, } from "./simpleSchemaCodec.js";
@@ -124,4 +128,270 @@ export function importCompatibilitySchemaSnapshot(config) {
     // a schema produced by `generateSchemaFromSimpleSchema`.
     return new TreeViewConfiguration({ schema: viewSchema.root });
 }
+/**
+ * Check `currentViewSchema` for compatibility with a collection of historical schema snapshots stored in `snapshotDirectory`.
+ *
+ * @throws Throws errors if the input version strings (including those in snapshot file names) are not valid semver versions.
+ * @throws Throws errors if the input version strings (including those in snapshot file names) are not ordered as expected (current being the highest, and `minVersionForCollaboration` corresponding to the current version or a lower snapshotted version).
+ * @throws In `test` mode, throws an error if there is not an up to date snapshot for the current version.
+ * @throws Throws an error if any snapshotted schema cannot be upgraded to the current schema.
+ * @throws Throws an error if any snapshotted schema with a version greater than or equal to `minVersionForCollaboration` cannot view documents created with the current schema.
+ * @remarks
+ * This is intended for use in snapshot-based schema compatibility tests.
+ * Every SharedTree-based component or application with a schema is recommended to use this to verify schema compatibility across versions.
+ *
+ * Schema snapshots should be added to `snapshotDirectory` using this function in "update" mode whenever the schema changes in a compatibility impacting way
+ * (or when `snapshotUnchangedVersions` is true and a new version about to be released is getting prepared for release (and thus `version` changed)).
+ *
+ * This will throw an exception if any snapshotted schema would result in documents that cannot be viewed (after using {@link TreeView.upgradeSchema}), or if any schema with a version greater than or equal to `minVersionForCollaboration` cannot view documents created with the `currentViewSchema`.
+ * See {@link TreeView.compatibility} for more information.
+ *
+ * Proper use of this utility should do a good job at detecting schema compatibility issues,
+ * however it currently does not do a good job of explaining exactly what change to the schema is causing the compatibility issues.
+ * This is a known limitation that will be improved in future releases.
+ * These improvements, as well as other changes, may change the exact messages produced by this function in the error cases: no stability of these messages should be assumed.
+ *
+ * For now, locating what change broke compatibility is likely best discovered by making small schema changes one at a time and updating the snapshot and reviewing the diffs.
+ * Details for what kinds of changes are breaking and in which ways can be found in the documentation for {@link TreeView.compatibility} and
+ * {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution/ | schema-evolution}.
+ *
+ * This utility does not enforce anything with respect to API compatibility, or special semantics for major, minor, or patch versions.
+ * Libraries which export schema for use by others will need to take special care to ensure the stability contract they offer their users aligns which what is validated by this utility.
+ *
+ * This utility only tests compatibility of the historical snapshots against the current schema; it does not test them against each-other.
+ * Generally any historical schema should have been tested against the ones before them at the time they were current.
+ * If for some reason a version of a schema made it into production that was not compatible with a previous version,
+ * that can still be represented here (but may require manually generating a snapshot for that version)
+ * and this will still allow testing that all historical version can be upgraded to the current one.
+ * If a sufficiently incompatible historical schema were used in production, it may be impossible to make a single schema which can accommodate all of them:
+ * this utility can be used to confirm that is the case, as well as to avoid the problem in the first place by testing schema before each one is deployed.
+ *
+ * @example Mocha test which validates the current `config` can collaborate with all historical version back to 2.0.0, and load and update any versions older than that.
+ * ```typescript
+ * it("schema compatibility", () => {
+ * 	checkSchemaCompatibilitySnapshots({
+ * 		version: pkgVersion,
+ * 		schema: config,
+ * 		fileSystem: { ...fs, ...path },
+ * 		minVersionForCollaboration: "2.0.0",
+ * 		mode: process.argv.includes("--snapshot") ? "update" : "test",
+ * 		snapshotDirectory,
+ * 	});
+ * });
+ * ```
+ * @privateRemarks
+ * Use of this function within this package (for schema libraries released as part of this package) should use {@link testSchemaCompatibilitySnapshots} instead.
+ *
+ * TODO: this uses the format defined in simpleSchemaCodec.ts.
+ * Currently this does not include any versioning information in the snapshot format itself.
+ * This would make it hard to do things like upgrade to a new format (perhaps for better diffs, or to support new features) in the future.
+ * That code should probably be migrated to a proper versioned codec with a schema and validation.
+ * This utility can directly depend on the typebox-validator and inject that as this code should not be bundle size sensitive.
+ * This should be addressed before this reached beta stability.
+ * @alpha
+ */
+export function checkSchemaCompatibilitySnapshots(options) {
+    const checker = new SnapshotCompatibilityChecker(options.snapshotDirectory, options.fileSystem);
+    const { version: currentVersion, schema: currentViewSchema, mode, minVersionForCollaboration, snapshotUnchangedVersions, } = options;
+    if (semver.valid(currentVersion) === null) {
+        throw new UsageError(`Invalid version: ${JSON.stringify(currentVersion)}. Must be a valid semver version.`);
+    }
+    if (semver.valid(minVersionForCollaboration) === null) {
+        throw new UsageError(`Invalid minVersionForCollaboration: ${JSON.stringify(minVersionForCollaboration)}. Must be a valid semver version.`);
+    }
+    if (!semver.lte(minVersionForCollaboration, currentVersion)) {
+        throw new UsageError(`Invalid minVersionForCollaboration: ${JSON.stringify(minVersionForCollaboration)}. Must be less than or equal to current version ${JSON.stringify(currentVersion)}.`);
+    }
+    if (mode !== "test" && mode !== "update") {
+        throw new UsageError(`Invalid mode: ${JSON.stringify(mode)}. Must be either "test" or "update".`);
+    }
+    const currentEncodedForSnapshotting = exportCompatibilitySchemaSnapshot(currentViewSchema);
+    const snapshots = checker.readAllSchemaSnapshots();
+    const compatibilityErrors = [];
+    function updatableError(message) {
+        assert(mode === "test", 0xcc6 /* updatableError should only be called in test mode */);
+        compatibilityErrors.push(`${message} If this is expected, checkSchemaCompatibilitySnapshots can be rerun in "update" mode to update the snapshot.`);
+    }
+    if (snapshotUnchangedVersions === true) {
+        if (mode === "update") {
+            checker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);
+            snapshots.set(currentVersion, currentViewSchema);
+        }
+        else {
+            const currentRead = snapshots.get(currentVersion);
+            if (currentRead === undefined) {
+                updatableError(`No snapshot found for version ${JSON.stringify(currentVersion)}: snapshotUnchangedVersions is true, so every version must be snapshotted.`);
+            }
+            else if (JSON.stringify(exportCompatibilitySchemaSnapshot(currentRead)) !==
+                JSON.stringify(currentEncodedForSnapshotting)) {
+                updatableError(`Snapshot for current version ${JSON.stringify(currentVersion)} is out of date.`);
+            }
+        }
+    }
+    else {
+        const entries = [...snapshots];
+        const latestSnapshot = entries[entries.length - 1];
+        if (latestSnapshot === undefined) {
+            if (mode === "update") {
+                checker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);
+                snapshots.set(currentVersion, currentViewSchema);
+            }
+            else {
+                updatableError(`No snapshots found.`);
+            }
+        }
+        else {
+            if (semver.lte(latestSnapshot[0], currentVersion)) {
+                // Check to see if schema in snapshot is the same as the latest existing snapshot.
+                const oldString = JSON.stringify(exportCompatibilitySchemaSnapshot(latestSnapshot[1]));
+                const currentString = JSON.stringify(currentEncodedForSnapshotting);
+                if (oldString !== currentString) {
+                    // Schema has changed: must create new snapshot.
+                    if (mode === "update") {
+                        checker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);
+                        snapshots.set(currentVersion, currentViewSchema);
+                    }
+                    else {
+                        updatableError(`Snapshot for current version ${JSON.stringify(currentVersion)} is out of date: schema has changed since latest existing snapshot version ${JSON.stringify(latestSnapshot[0])}.`);
+                    }
+                }
+            }
+            else {
+                throw new UsageError(`Current version ${JSON.stringify(currentVersion)} is less than latest existing snapshot version ${JSON.stringify(latestSnapshot[0])}: version is expected to increase monotonically.`);
+            }
+        }
+    }
+    const compatibilityMap = transformMapValues(snapshots, (snapshot) => getCompatibility(currentViewSchema, snapshot));
+    let selectedMinVersionForCollaborationSnapshot;
+    if (snapshotUnchangedVersions === true) {
+        const minSnapshot = compatibilityMap.get(minVersionForCollaboration);
+        if (minSnapshot === undefined) {
+            compatibilityErrors.push(`Using snapshotUnchangedVersions: a snapshot of the exact minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)} is required. No snapshot found.`);
+        }
+        else {
+            selectedMinVersionForCollaborationSnapshot = [minVersionForCollaboration, minSnapshot];
+        }
+    }
+    else {
+        selectedMinVersionForCollaborationSnapshot = selectVersionRoundedDown(minVersionForCollaboration, compatibilityMap);
+        if (selectedMinVersionForCollaborationSnapshot === undefined) {
+            compatibilityErrors.push(`No snapshot found with version less than or equal to minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)}.`);
+        }
+    }
+    for (const [snapshotVersion, compatibility] of compatibilityMap) {
+        // Current should be able to view all versions.
+        if (!compatibility.currentViewOfSnapshotDocument.canUpgrade) {
+            compatibilityErrors.push(`Current version ${JSON.stringify(currentVersion)} cannot upgrade documents from ${JSON.stringify(snapshotVersion)}.`);
+        }
+        if (semver.eq(snapshotVersion, currentVersion)) {
+            if (currentVersion !== snapshotVersion) {
+                throw new UsageError(`Snapshot version ${JSON.stringify(snapshotVersion)} is semantically equal but not string equal to current version ${JSON.stringify(currentVersion)}: this is not supported.`);
+            }
+            if (compatibility.currentViewOfSnapshotDocument.isEquivalent === false ||
+                compatibility.snapshotViewOfCurrentDocument.isEquivalent === false) {
+                compatibilityErrors.push(`Current version ${JSON.stringify(snapshotVersion)} expected to be equivalent to its snapshot.`);
+            }
+        }
+        else if (semver.lt(snapshotVersion, currentVersion)) {
+            if (selectedMinVersionForCollaborationSnapshot === undefined) {
+                assert(compatibilityErrors.length > 0, 0xcc7 /* expected compatibility errors for missing min collab version snapshot */);
+            }
+            else {
+                // Collaboration with this version is expected to work.
+                if (semver.gte(snapshotVersion, selectedMinVersionForCollaborationSnapshot[0])) {
+                    // Check that the historical version can view documents from the current version, since collaboration with this one is expected to work.
+                    if (!compatibility.snapshotViewOfCurrentDocument.canView) {
+                        const message = `Historical version ${JSON.stringify(snapshotVersion)} cannot view documents from ${JSON.stringify(currentVersion)}: these versions are expected to be able to collaborate due to the selected minVersionForCollaboration snapshot version being ${JSON.stringify(selectedMinVersionForCollaborationSnapshot[0])}.`;
+                        compatibilityErrors.push(selectedMinVersionForCollaborationSnapshot[0] === minVersionForCollaboration
+                            ? message
+                            : `${message} The specified minVersionForCollaboration is ${JSON.stringify(minVersionForCollaboration)} which was rounded down to an existing snapshot.`);
+                    }
+                }
+                else {
+                    // This is the case where the historical version is less than the minimum version for collaboration.
+                    // No additional validation is needed here currently, since forwards document compat from these versions is already tested above (since it applies to all snapshots).
+                }
+            }
+        }
+        else {
+            throw new UsageError(`Unexpected semver comparison result between snapshot version ${JSON.stringify(snapshotVersion)} and app version ${JSON.stringify(currentVersion)}.`);
+        }
+    }
+    if (compatibilityErrors.length > 0) {
+        throw new Error(`Schema compatibility check failed:\n${compatibilityErrors
+            .map((e) => ` - ${e}`)
+            .join("\n")}`);
+    }
+}
+/**
+ * The high-level API for checking snapshot compatibility and generating new snapshots.
+ */
+export class SnapshotCompatibilityChecker {
+    constructor(
+    /**
+     * Directory where historical schema snapshots are stored.
+     */
+    snapshotDirectory, 
+    /**
+     * How the `snapshotDirectory` is accessed.
+     */
+    fileSystemMethods) {
+        this.snapshotDirectory = snapshotDirectory;
+        this.fileSystemMethods = fileSystemMethods;
+    }
+    writeSchemaSnapshot(snapshotName, snapshot) {
+        const fullPath = this.fileSystemMethods.join(this.snapshotDirectory, `${snapshotName}.json`);
+        this.ensureSnapshotDirectoryExists();
+        this.fileSystemMethods.writeFileSync(fullPath, JSON.stringify(snapshot, undefined, 2), {
+            encoding: "utf8",
+        });
+    }
+    readSchemaSnapshot(snapshotName) {
+        const snapshot = this.readSchemaSnapshotRaw(snapshotName);
+        return importCompatibilitySchemaSnapshot(snapshot);
+    }
+    readSchemaSnapshotRaw(snapshotName) {
+        const fullPath = this.fileSystemMethods.join(this.snapshotDirectory, `${snapshotName}.json`);
+        const snapshot = JSON.parse(this.fileSystemMethods.readFileSync(fullPath, "utf8"));
+        return snapshot;
+    }
+    /**
+     * Returns all schema snapshots stored in the snapshot directory, sorted in order of increasing version.
+     */
+    readAllSchemaSnapshots() {
+        this.ensureSnapshotDirectoryExists();
+        const files = this.fileSystemMethods.readdirSync(this.snapshotDirectory);
+        const versions = [];
+        for (const file of files) {
+            if (file.endsWith(".json")) {
+                const snapshotName = file.slice(0, ".json".length * -1);
+                versions.push(snapshotName);
+            }
+        }
+        // Ensures that errors are in a consistent and friendly order, independent of file system order.
+        versions.sort((a, b) => semver.compare(a, b));
+        const snapshots = new Map();
+        for (const version of versions) {
+            snapshots.set(version, this.readSchemaSnapshot(version));
+        }
+        return snapshots;
+    }
+    ensureSnapshotDirectoryExists() {
+        this.fileSystemMethods.mkdirSync(this.snapshotDirectory, { recursive: true });
+    }
+}
+/**
+ * Gets the compatibility of the current view schema against a historical snapshot.
+ * @param currentViewSchema - The current view schema.
+ * @param previousViewSchema - The historical view schema.
+ * @returns The combined compatibility status.
+ */
+export function getCompatibility(currentViewSchema, previousViewSchema) {
+    const backwardsCompatibilityStatus = checkCompatibility(previousViewSchema, currentViewSchema);
+    const forwardsCompatibilityStatus = checkCompatibility(currentViewSchema, previousViewSchema);
+    return {
+        currentViewOfSnapshotDocument: backwardsCompatibilityStatus,
+        snapshotViewOfCurrentDocument: forwardsCompatibilityStatus,
+    };
+}
 //# sourceMappingURL=snapshotCompatibilityChecker.js.map

package/lib/simple-tree/api/snapshotCompatibilityChecker.js.map

@@ -1 +1 @@
-{"version":3,"file":"snapshotCompatibilityChecker.js","sourceRoot":"","sources":["../../../src/simple-tree/api/snapshotCompatibilityChecker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,8BAA8B,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EACN,iCAAiC,EACjC,iCAAiC,GACjC,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,UAAU,kBAAkB,CACjC,4BAAmD,EACnD,IAA2B;IAE3B,MAAM,WAAW,GAAG,IAAI,0BAA0B,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,MAAM,MAAM,GAAG,eAAe,CAAC,4BAA4B,CAAC,MAAM,CAAC,CAAC;IACpE,MAAM,MAAM,GAAG,IAAI,yBAAyB,CAAC,WAAW,CAAC,CAAC;IAC1D,OAAO,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,iCAAiC,CAChD,MAA6C;IAE7C,MAAM,UAAU,GAAG,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACnD,OAAO,iCAAiC,CAAC,UAAU,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iCAAiC,CAChD,MAA8B;IAE9B,MAAM,YAAY,GAAG,iCAAiC,CAAC,MAAM,CAAC,CAAC;IAC/D,MAAM,UAAU,GAAG,8BAA8B,CAAC,YAAY,CAAC,CAAC;IAEhE,+HAA+H;IAC/H,yDAAyD;IACzD,OAAO,IAAI,qBAAqB,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;AAC/D,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { JsonCompatibleReadOnly } from \"../../util/index.js\";\nimport { toInitialSchema } from \"../toStoredSchema.js\";\nimport { TreeViewConfigurationAlpha, TreeViewConfiguration } from \"./configuration.js\";\nimport { createTreeSchema } from \"../treeSchema.js\";\nimport { SchemaCompatibilityTester } from \"./schemaCompatibilityTester.js\";\nimport { generateSchemaFromSimpleSchema } from \"./schemaFromSimple.js\";\nimport {\n\tdecodeSchemaCompatibilitySnapshot,\n\tencodeSchemaCompatibilitySnapshot,\n} from \"./simpleSchemaCodec.js\";\nimport type { SchemaCompatibilityStatus } from \"./tree.js\";\n\n/**\n * 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}.\n *\n * @remarks See {@link SchemaCompatibilityStatus} for details on the compatibility results.\n *\n * @example This example demonstrates checking the compatibility of a historical schema against a current schema.\n * In this case, the historical schema is a Point2D object with x and y fields, while the current schema is a Point3D object\n * that adds an optional z field.\n *\n * ```ts\n * // This snapshot is assumed to be the same as Point3D, except missing `z`.\n * const encodedSchema = JSON.parse(fs.readFileSync(\"PointSchema.json\", \"utf8\"));\n * const oldViewSchema = importCompatibilitySchemaSnapshot(encodedSchema);\n *\n * // Build the current view schema\n * class Point3D extends factory.object(\"Point\", {\n * \tx: factory.number,\n * \ty: factory.number,\n *\n * \t// The current schema has a new optional field that was not present on Point2D\n * \tz: factory.optional(factory.number),\n * }) {}\n * const currentViewSchema = new TreeViewConfiguration({ schema: Point3D });\n *\n * // Check to see if the document created by the historical view schema can be opened with the current view schema\n * const backwardsCompatibilityStatus = checkCompatibility(oldViewSchema, currentViewSchema);\n *\n * // z is not present in Point2D, so the schema must be upgraded\n * assert.equal(backwardsCompatibilityStatus.canView, false);\n *\n * // The schema can be upgraded to add the new optional field\n * assert.equal(backwardsCompatibilityStatus.canUpgrade, true);\n *\n * // Test what the old version of the application would do with a tree using the new schema:\n * const forwardsCompatibilityStatus = checkCompatibility(currentViewSchema, oldViewSchema);\n *\n * // If the old schema set allowUnknownOptionalFields, this would be true, but since it did not,\n * // this assert will fail, detecting the forwards compatibility break:\n * // this means these two versions of the application cannot collaborate on content using these schema.\n * assert.equal(forwardsCompatibilityStatus.canView, true);\n * ```\n *\n * @param viewWhichCreatedStoredSchema - From which to derive the stored schema, as if it initialized or upgraded a tree via {@link TreeView}.\n * @param view - The view being tested to see if it could view tree created or initialized using `viewWhichCreatedStoredSchema`.\n * @returns The compatibility status.\n *\n * @privateRemarks\n * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.\n *\n * @alpha\n */\nexport function checkCompatibility(\n\tviewWhichCreatedStoredSchema: TreeViewConfiguration,\n\tview: TreeViewConfiguration,\n): Omit<SchemaCompatibilityStatus, \"canInitialize\"> {\n\tconst viewAsAlpha = new TreeViewConfigurationAlpha({ schema: view.schema });\n\tconst stored = toInitialSchema(viewWhichCreatedStoredSchema.schema);\n\tconst tester = new SchemaCompatibilityTester(viewAsAlpha);\n\treturn tester.checkCompatibility(stored);\n}\n\n/**\n * Returns a JSON compatible representation of the tree schema for snapshot compatibility checking.\n *\n * Snapshots can be loaded by the same or newer package versions, but not necessarily older versions.\n *\n * @see {@link importCompatibilitySchemaSnapshot} which loads these snapshots.\n *\n * @param config - The schema to snapshot. Only the schema field of the `TreeViewConfiguration` is used.\n * @returns The JSON representation of the schema.\n *\n * @example This example creates and persists a snapshot of a Point2D schema.\n *\n * ```ts\n * const schemaFactory = new SchemaFactory(\"test\");\n * class Point2D extends schemaFactory.object(\"Point\", {\n * \tx: factory.number,\n * \ty: factory.number,\n * }) {}\n * const viewSchema = new TreeViewConfiguration({ schema: Point2D });\n * const encodedSchema = JSON.stringify(exportCompatibilitySchemaSnapshot(viewSchema));\n * fs.writeFileSync(\"PointSchema.json\", encodedSchema);\n * ```\n *\n * @privateRemarks\n * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.\n *\n * @alpha\n */\nexport function exportCompatibilitySchemaSnapshot(\n\tconfig: Pick<TreeViewConfiguration, \"schema\">,\n): JsonCompatibleReadOnly {\n\tconst treeSchema = createTreeSchema(config.schema);\n\treturn encodeSchemaCompatibilitySnapshot(treeSchema);\n}\n\n/**\n * Parse the format exported by {@link exportCompatibilitySchemaSnapshot} into a schema.\n *\n * Can load snapshots created by the same or older package versions, but not necessarily newer versions.\n *\n * @see {@link exportCompatibilitySchemaSnapshot} which creates these snapshots.\n *\n * @param config - The JSON representation of the schema.\n * @returns The schema. Only the schema field of the {@link TreeViewConfiguration} is populated.\n * @throws Will throw a usage error if the encoded schema is not in the expected format.\n *\n * @example This example loads and parses a snapshot of a Point2D schema.\n *\n * ```ts;\n * const oldViewSchema = importCompatibilitySchemaSnapshot(fs.readFileSync(\"PointSchema.json\", \"utf8\"));\n * ```\n * @privateRemarks\n * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.\n * @alpha\n */\nexport function importCompatibilitySchemaSnapshot(\n\tconfig: JsonCompatibleReadOnly,\n): TreeViewConfiguration {\n\tconst simpleSchema = decodeSchemaCompatibilitySnapshot(config);\n\tconst viewSchema = generateSchemaFromSimpleSchema(simpleSchema);\n\n\t// We construct a TreeViewConfiguration here with the default parameters. The default set of validation parameters are fine for\n\t// a schema produced by `generateSchemaFromSimpleSchema`.\n\treturn new TreeViewConfiguration({ schema: viewSchema.root });\n}\n"]}
+{"version":3,"file":"snapshotCompatibilityChecker.js","sourceRoot":"","sources":["../../../src/simple-tree/api/snapshotCompatibilityChecker.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 { assert, transformMapValues } from \"@fluidframework/core-utils/internal\";\nimport { selectVersionRoundedDown } from \"@fluidframework/runtime-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport * as semver from \"semver-ts\";\n\nimport type { JsonCompatibleReadOnly } from \"../../util/index.js\";\nimport { toInitialSchema } from \"../toStoredSchema.js\";\nimport { createTreeSchema } from \"../treeSchema.js\";\n\nimport { TreeViewConfigurationAlpha, TreeViewConfiguration } from \"./configuration.js\";\nimport { SchemaCompatibilityTester } from \"./schemaCompatibilityTester.js\";\nimport { generateSchemaFromSimpleSchema } from \"./schemaFromSimple.js\";\nimport {\n\tdecodeSchemaCompatibilitySnapshot,\n\tencodeSchemaCompatibilitySnapshot,\n} from \"./simpleSchemaCodec.js\";\nimport type { SchemaCompatibilityStatus } from \"./tree.js\";\n\n/**\n * 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}.\n *\n * @remarks See {@link SchemaCompatibilityStatus} for details on the compatibility results.\n *\n * @example This example demonstrates checking the compatibility of a historical schema against a current schema.\n * In this case, the historical schema is a Point2D object with x and y fields, while the current schema is a Point3D object\n * that adds an optional z field.\n *\n * ```ts\n * // This snapshot is assumed to be the same as Point3D, except missing `z`.\n * const encodedSchema = JSON.parse(fs.readFileSync(\"PointSchema.json\", \"utf8\"));\n * const oldViewSchema = importCompatibilitySchemaSnapshot(encodedSchema);\n *\n * // Build the current view schema\n * class Point3D extends factory.object(\"Point\", {\n * \tx: factory.number,\n * \ty: factory.number,\n *\n * \t// The current schema has a new optional field that was not present on Point2D\n * \tz: factory.optional(factory.number),\n * }) {}\n * const currentViewSchema = new TreeViewConfiguration({ schema: Point3D });\n *\n * // Check to see if the document created by the historical view schema can be opened with the current view schema\n * const backwardsCompatibilityStatus = checkCompatibility(oldViewSchema, currentViewSchema);\n *\n * // z is not present in Point2D, so the schema must be upgraded\n * assert.equal(backwardsCompatibilityStatus.canView, false);\n *\n * // The schema can be upgraded to add the new optional field\n * assert.equal(backwardsCompatibilityStatus.canUpgrade, true);\n *\n * // Test what the old version of the application would do with a tree using the new schema:\n * const forwardsCompatibilityStatus = checkCompatibility(currentViewSchema, oldViewSchema);\n *\n * // If the old schema set allowUnknownOptionalFields, this would be true, but since it did not,\n * // this assert will fail, detecting the forwards compatibility break:\n * // this means these two versions of the application cannot collaborate on content using these schema.\n * assert.equal(forwardsCompatibilityStatus.canView, true);\n * ```\n *\n * @param viewWhichCreatedStoredSchema - From which to derive the stored schema, as if it initialized or upgraded a tree via {@link TreeView}.\n * @param view - The view being tested to see if it could view tree created or initialized using `viewWhichCreatedStoredSchema`.\n * @returns The compatibility status.\n *\n * @privateRemarks\n * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.\n *\n * @alpha\n */\nexport function checkCompatibility(\n\tviewWhichCreatedStoredSchema: TreeViewConfiguration,\n\tview: TreeViewConfiguration,\n): Omit<SchemaCompatibilityStatus, \"canInitialize\"> {\n\tconst viewAsAlpha = new TreeViewConfigurationAlpha({ schema: view.schema });\n\tconst stored = toInitialSchema(viewWhichCreatedStoredSchema.schema);\n\tconst tester = new SchemaCompatibilityTester(viewAsAlpha);\n\treturn tester.checkCompatibility(stored);\n}\n\n/**\n * Returns a JSON compatible representation of the tree schema for snapshot compatibility checking.\n *\n * Snapshots can be loaded by the same or newer package versions, but not necessarily older versions.\n *\n * @see {@link importCompatibilitySchemaSnapshot} which loads these snapshots.\n *\n * @param config - The schema to snapshot. Only the schema field of the `TreeViewConfiguration` is used.\n * @returns The JSON representation of the schema.\n *\n * @example This example creates and persists a snapshot of a Point2D schema.\n *\n * ```ts\n * const schemaFactory = new SchemaFactory(\"test\");\n * class Point2D extends schemaFactory.object(\"Point\", {\n * \tx: factory.number,\n * \ty: factory.number,\n * }) {}\n * const viewSchema = new TreeViewConfiguration({ schema: Point2D });\n * const encodedSchema = JSON.stringify(exportCompatibilitySchemaSnapshot(viewSchema));\n * fs.writeFileSync(\"PointSchema.json\", encodedSchema);\n * ```\n *\n * @privateRemarks\n * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.\n *\n * @alpha\n */\nexport function exportCompatibilitySchemaSnapshot(\n\tconfig: Pick<TreeViewConfiguration, \"schema\">,\n): JsonCompatibleReadOnly {\n\tconst treeSchema = createTreeSchema(config.schema);\n\treturn encodeSchemaCompatibilitySnapshot(treeSchema);\n}\n\n/**\n * Parse the format exported by {@link exportCompatibilitySchemaSnapshot} into a schema.\n *\n * Can load snapshots created by the same or older package versions, but not necessarily newer versions.\n *\n * @see {@link exportCompatibilitySchemaSnapshot} which creates these snapshots.\n *\n * @param config - The JSON representation of the schema.\n * @returns The schema. Only the schema field of the {@link TreeViewConfiguration} is populated.\n * @throws Will throw a usage error if the encoded schema is not in the expected format.\n *\n * @example This example loads and parses a snapshot of a Point2D schema.\n *\n * ```ts;\n * const oldViewSchema = importCompatibilitySchemaSnapshot(fs.readFileSync(\"PointSchema.json\", \"utf8\"));\n * ```\n * @privateRemarks\n * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.\n * @alpha\n */\nexport function importCompatibilitySchemaSnapshot(\n\tconfig: JsonCompatibleReadOnly,\n): TreeViewConfiguration {\n\tconst simpleSchema = decodeSchemaCompatibilitySnapshot(config);\n\tconst viewSchema = generateSchemaFromSimpleSchema(simpleSchema);\n\n\t// We construct a TreeViewConfiguration here with the default parameters. The default set of validation parameters are fine for\n\t// a schema produced by `generateSchemaFromSimpleSchema`.\n\treturn new TreeViewConfiguration({ schema: viewSchema.root });\n}\n\n/**\n * The file system methods required by {@link checkSchemaCompatibilitySnapshots}.\n * @remarks\n * Implemented by both Node.js `fs` and `path` modules, but other implementations can be provided as needed.\n *\n * @example\n * ```typescript\n * import path from \"node:path\";\n * import fs from \"node:fs\";\n *\n * const nodeFileSystem: SnapshotFileSystem = { ...fs, ...path };\n * ```\n *\n * @privateRemarks\n * This interface is designed to be compatible with Node.js `fs` and `path` modules.\n * It is needed to avoid direct dependencies on Node.js APIs in the core library code,\n * allowing for greater portability and easier testing.\n *\n * @input\n * @alpha\n */\nexport interface SnapshotFileSystem {\n\t/**\n\t * Writes a UTF-8 encoded file to disk, replacing the file if it already exists.\n\t *\n\t * @param file - Path to the file to write.\n\t * @param data - String data to be written.\n\t * @param options - Options specifying that the encoding is UTF-8.\n\t */\n\twriteFileSync(file: string, data: string, options: { encoding: \"utf8\" }): void;\n\n\t/**\n\t * Reads a UTF-8 encoded file from disk and returns its contents as a string.\n\t *\n\t * @param file - Path to the file to read.\n\t * @param encoding - The text encoding to use when reading the file. Must be `\"utf8\"`.\n\t * @returns The contents of the file as a string.\n\t */\n\t// We include the encoding here to match the function overload for readFileSync that returns a string.\n\treadFileSync(file: string, encoding: \"utf8\"): string;\n\n\t/**\n\t * How a {@link TreeView} using the snapshotted schema would report its compatibility with a document created with the current schema.\n\t *\n\t * @param dir - Path of the directory to create.\n\t * @param options - Options indicating that creation should be recursive.\n\t */\n\tmkdirSync(dir: string, options: { recursive: true }): void;\n\n\t/**\n\t * Reads the contents of a directory.\n\t *\n\t * @param dir - Path of the directory to read.\n\t * @returns An array of names of the directory entries.\n\t */\n\treaddirSync(dir: string): readonly string[];\n\n\t/**\n\t * Joins two path segments into a single path string.\n\t *\n\t * @param parentPath - The directory path.\n\t * @param childPath - Filename within `parentPath` directory.\n\t * @returns The combined path string.\n\t */\n\tjoin(parentPath: string, childPath: string): string;\n}\n\n/**\n * The combined compatibility status for both backwards and forwards compatibility checks.\n */\nexport interface CombinedSchemaCompatibilityStatus {\n\t/**\n\t * How a {@link TreeView} using the current schema would report its compatibility with the historical snapshot.\n\t */\n\treadonly currentViewOfSnapshotDocument: Omit<SchemaCompatibilityStatus, \"canInitialize\">;\n\t/**\n\t * How a {@link TreeView} using the snapshotted schema would report its compatibility with a document created with the current schema.\n\t */\n\treadonly snapshotViewOfCurrentDocument: Omit<SchemaCompatibilityStatus, \"canInitialize\">;\n}\n\n/**\n * The options for {@link checkSchemaCompatibilitySnapshots}.\n * @input\n * @alpha\n */\nexport interface SchemaCompatibilitySnapshotsOptions {\n\t/**\n\t * Directory where historical schema snapshots are stored.\n\t */\n\treadonly snapshotDirectory: string;\n\t/**\n\t * How the `snapshotDirectory` is accessed.\n\t */\n\treadonly fileSystem: SnapshotFileSystem;\n\t/**\n\t * The current application or library version.\n\t * @remarks\n\t * This uses the {@link https://semver.org/#spec-item-11|ordering defined by semver}.\n\t * It is only compared against the version from previous snapshots (taken from this version when they were created by setting `mode` to \"update\") and the `minVersionForCollaboration`.\n\t */\n\treadonly version: string;\n\t/**\n\t * The current view schema.\n\t */\n\treadonly schema: TreeViewConfiguration;\n\t/**\n\t * The minimum version that the current version is expected to be able to collaborate with.\n\t * @remarks\n\t * This defines a range of versions whose schema must be forwards compatible with trees using the current schema:\n\t * Any schema from snapshots with a version greater than or equal to this must be able to view documents created with the current schema.\n\t * This means that if the current `schema` is used to create a {@link TreeView}, then {@link TreeView.upgradeSchema} is used, the older clients,\n\t * all the way back to this `minVersionForCollaboration` will be able to view and edit the tree using their schema and thus collaborate.\n\t *\n\t * Typically applications will attempt to manage their deployment/update schedule such that all versions concurrently deployed can\n\t * collaborate to avoid users losing access to documents when other users upgrade the schema.\n\t * Such applications can set this to the oldest version currently deployed,\n\t * then rely on {@link checkSchemaCompatibilitySnapshots} to verify that no schema changes are made which would break collaboration with that (or newer) versions.\n\t *\n\t * This is the same approach used by {@link @fluidframework/runtime-definitions#MinimumVersionForCollab}\n\t * except that type is specifically for use with the version of the Fluid Framework client packages,\n\t * and this corresponds to the version of the application or library defining the schema.\n\t */\n\treadonly minVersionForCollaboration: string;\n\t/**\n\t * When true, every version must be snapshotted, and an increased version number will require a new snapshot.\n\t * @remarks\n\t * If this is true, it is assumed there is a snapshot for every release, and thus it is required that the `minVersionForCollaboration` refer to a version which has a snapshot.\n\t * When this is not true, versions without snapshots are assumed to have the same schema as the latest previous version which has a snapshot, and thus `minVersionForCollaboration`\n\t * can refer to versions between snapshots and will get its schema from the preceding version.\n\t */\n\treadonly snapshotUnchangedVersions?: true;\n\t/**\n\t * The mode of operation, either \"test\" or \"update\".\n\t * @remarks\n\t * In \"update\" mode, a new snapshot is created if the current schema differs from the latest existing snapshot.\n\t * Note: {@link SchemaCompatibilitySnapshotsOptions.snapshotUnchangedVersions} impacts this behavior.\n\t *\n\t * In \"test\" mode, an error is thrown if running in \"update\" mode would have made any changes.\n\t *\n\t * Both modes will throw errors if any compatibility issues are detected (but after updating snapshots in \"update\" mode so the diff can be used to help debug).\n\t *\n\t * It is recommended that \"test\" mode be used in automated tests to verify schema compatibility,\n\t * and \"update\" mode only be used manually to update snapshots when making schema changes (or version changes if `snapshotUnchangedVersions` is true).\n\t */\n\treadonly mode: \"test\" | \"update\";\n}\n\n/**\n * Check `currentViewSchema` for compatibility with a collection of historical schema snapshots stored in `snapshotDirectory`.\n *\n * @throws Throws errors if the input version strings (including those in snapshot file names) are not valid semver versions.\n * @throws Throws errors if the input version strings (including those in snapshot file names) are not ordered as expected (current being the highest, and `minVersionForCollaboration` corresponding to the current version or a lower snapshotted version).\n * @throws In `test` mode, throws an error if there is not an up to date snapshot for the current version.\n * @throws Throws an error if any snapshotted schema cannot be upgraded to the current schema.\n * @throws Throws an error if any snapshotted schema with a version greater than or equal to `minVersionForCollaboration` cannot view documents created with the current schema.\n * @remarks\n * This is intended for use in snapshot-based schema compatibility tests.\n * Every SharedTree-based component or application with a schema is recommended to use this to verify schema compatibility across versions.\n *\n * Schema snapshots should be added to `snapshotDirectory` using this function in \"update\" mode whenever the schema changes in a compatibility impacting way\n * (or when `snapshotUnchangedVersions` is true and a new version about to be released is getting prepared for release (and thus `version` changed)).\n *\n * This will throw an exception if any snapshotted schema would result in documents that cannot be viewed (after using {@link TreeView.upgradeSchema}), or if any schema with a version greater than or equal to `minVersionForCollaboration` cannot view documents created with the `currentViewSchema`.\n * See {@link TreeView.compatibility} for more information.\n *\n * Proper use of this utility should do a good job at detecting schema compatibility issues,\n * however it currently does not do a good job of explaining exactly what change to the schema is causing the compatibility issues.\n * This is a known limitation that will be improved in future releases.\n * These improvements, as well as other changes, may change the exact messages produced by this function in the error cases: no stability of these messages should be assumed.\n *\n * For now, locating what change broke compatibility is likely best discovered by making small schema changes one at a time and updating the snapshot and reviewing the diffs.\n * Details for what kinds of changes are breaking and in which ways can be found in the documentation for {@link TreeView.compatibility} and\n * {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution/ | schema-evolution}.\n *\n * This utility does not enforce anything with respect to API compatibility, or special semantics for major, minor, or patch versions.\n * Libraries which export schema for use by others will need to take special care to ensure the stability contract they offer their users aligns which what is validated by this utility.\n *\n * This utility only tests compatibility of the historical snapshots against the current schema; it does not test them against each-other.\n * Generally any historical schema should have been tested against the ones before them at the time they were current.\n * If for some reason a version of a schema made it into production that was not compatible with a previous version,\n * that can still be represented here (but may require manually generating a snapshot for that version)\n * and this will still allow testing that all historical version can be upgraded to the current one.\n * If a sufficiently incompatible historical schema were used in production, it may be impossible to make a single schema which can accommodate all of them:\n * this utility can be used to confirm that is the case, as well as to avoid the problem in the first place by testing schema before each one is deployed.\n *\n * @example Mocha test which validates the current `config` can collaborate with all historical version back to 2.0.0, and load and update any versions older than that.\n * ```typescript\n * it(\"schema compatibility\", () => {\n * \tcheckSchemaCompatibilitySnapshots({\n * \t\tversion: pkgVersion,\n * \t\tschema: config,\n * \t\tfileSystem: { ...fs, ...path },\n * \t\tminVersionForCollaboration: \"2.0.0\",\n * \t\tmode: process.argv.includes(\"--snapshot\") ? \"update\" : \"test\",\n * \t\tsnapshotDirectory,\n * \t});\n * });\n * ```\n * @privateRemarks\n * Use of this function within this package (for schema libraries released as part of this package) should use {@link testSchemaCompatibilitySnapshots} instead.\n *\n * TODO: this uses the format defined in simpleSchemaCodec.ts.\n * Currently this does not include any versioning information in the snapshot format itself.\n * This would make it hard to do things like upgrade to a new format (perhaps for better diffs, or to support new features) in the future.\n * That code should probably be migrated to a proper versioned codec with a schema and validation.\n * This utility can directly depend on the typebox-validator and inject that as this code should not be bundle size sensitive.\n * This should be addressed before this reached beta stability.\n * @alpha\n */\nexport function checkSchemaCompatibilitySnapshots(\n\toptions: SchemaCompatibilitySnapshotsOptions,\n): void {\n\tconst checker = new SnapshotCompatibilityChecker(\n\t\toptions.snapshotDirectory,\n\t\toptions.fileSystem,\n\t);\n\tconst {\n\t\tversion: currentVersion,\n\t\tschema: currentViewSchema,\n\t\tmode,\n\t\tminVersionForCollaboration,\n\t\tsnapshotUnchangedVersions,\n\t} = options;\n\tif (semver.valid(currentVersion) === null) {\n\t\tthrow new UsageError(\n\t\t\t`Invalid version: ${JSON.stringify(currentVersion)}. Must be a valid semver version.`,\n\t\t);\n\t}\n\tif (semver.valid(minVersionForCollaboration) === null) {\n\t\tthrow new UsageError(\n\t\t\t`Invalid minVersionForCollaboration: ${JSON.stringify(minVersionForCollaboration)}. Must be a valid semver version.`,\n\t\t);\n\t}\n\tif (!semver.lte(minVersionForCollaboration, currentVersion)) {\n\t\tthrow new UsageError(\n\t\t\t`Invalid minVersionForCollaboration: ${JSON.stringify(minVersionForCollaboration)}. Must be less than or equal to current version ${JSON.stringify(currentVersion)}.`,\n\t\t);\n\t}\n\n\tif (mode !== \"test\" && mode !== \"update\") {\n\t\tthrow new UsageError(\n\t\t\t`Invalid mode: ${JSON.stringify(mode)}. Must be either \"test\" or \"update\".`,\n\t\t);\n\t}\n\n\tconst currentEncodedForSnapshotting = exportCompatibilitySchemaSnapshot(currentViewSchema);\n\tconst snapshots = checker.readAllSchemaSnapshots();\n\n\tconst compatibilityErrors: string[] = [];\n\n\tfunction updatableError(message: string): void {\n\t\tassert(mode === \"test\", 0xcc6 /* updatableError should only be called in test mode */);\n\t\tcompatibilityErrors.push(\n\t\t\t`${message} If this is expected, checkSchemaCompatibilitySnapshots can be rerun in \"update\" mode to update the snapshot.`,\n\t\t);\n\t}\n\n\tif (snapshotUnchangedVersions === true) {\n\t\tif (mode === \"update\") {\n\t\t\tchecker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);\n\t\t\tsnapshots.set(currentVersion, currentViewSchema);\n\t\t} else {\n\t\t\tconst currentRead = snapshots.get(currentVersion);\n\t\t\tif (currentRead === undefined) {\n\t\t\t\tupdatableError(\n\t\t\t\t\t`No snapshot found for version ${JSON.stringify(currentVersion)}: snapshotUnchangedVersions is true, so every version must be snapshotted.`,\n\t\t\t\t);\n\t\t\t} else if (\n\t\t\t\tJSON.stringify(exportCompatibilitySchemaSnapshot(currentRead)) !==\n\t\t\t\tJSON.stringify(currentEncodedForSnapshotting)\n\t\t\t) {\n\t\t\t\tupdatableError(\n\t\t\t\t\t`Snapshot for current version ${JSON.stringify(currentVersion)} is out of date.`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t} else {\n\t\tconst entries = [...snapshots];\n\t\tconst latestSnapshot = entries[entries.length - 1];\n\t\tif (latestSnapshot === undefined) {\n\t\t\tif (mode === \"update\") {\n\t\t\t\tchecker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);\n\t\t\t\tsnapshots.set(currentVersion, currentViewSchema);\n\t\t\t} else {\n\t\t\t\tupdatableError(`No snapshots found.`);\n\t\t\t}\n\t\t} else {\n\t\t\tif (semver.lte(latestSnapshot[0], currentVersion)) {\n\t\t\t\t// Check to see if schema in snapshot is the same as the latest existing snapshot.\n\t\t\t\tconst oldString = JSON.stringify(exportCompatibilitySchemaSnapshot(latestSnapshot[1]));\n\t\t\t\tconst currentString = JSON.stringify(currentEncodedForSnapshotting);\n\t\t\t\tif (oldString !== currentString) {\n\t\t\t\t\t// Schema has changed: must create new snapshot.\n\t\t\t\t\tif (mode === \"update\") {\n\t\t\t\t\t\tchecker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);\n\t\t\t\t\t\tsnapshots.set(currentVersion, currentViewSchema);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tupdatableError(\n\t\t\t\t\t\t\t`Snapshot for current version ${JSON.stringify(currentVersion)} is out of date: schema has changed since latest existing snapshot version ${JSON.stringify(latestSnapshot[0])}.`,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`Current version ${JSON.stringify(currentVersion)} is less than latest existing snapshot version ${JSON.stringify(latestSnapshot[0])}: version is expected to increase monotonically.`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\tconst compatibilityMap = transformMapValues(snapshots, (snapshot) =>\n\t\tgetCompatibility(currentViewSchema, snapshot),\n\t);\n\n\tlet selectedMinVersionForCollaborationSnapshot:\n\t\t| undefined\n\t\t| readonly [string, CombinedSchemaCompatibilityStatus];\n\n\tif (snapshotUnchangedVersions === true) {\n\t\tconst minSnapshot = compatibilityMap.get(minVersionForCollaboration);\n\t\tif (minSnapshot === undefined) {\n\t\t\tcompatibilityErrors.push(\n\t\t\t\t`Using snapshotUnchangedVersions: a snapshot of the exact minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)} is required. No snapshot found.`,\n\t\t\t);\n\t\t} else {\n\t\t\tselectedMinVersionForCollaborationSnapshot = [minVersionForCollaboration, minSnapshot];\n\t\t}\n\t} else {\n\t\tselectedMinVersionForCollaborationSnapshot = selectVersionRoundedDown(\n\t\t\tminVersionForCollaboration,\n\t\t\tcompatibilityMap,\n\t\t);\n\t\tif (selectedMinVersionForCollaborationSnapshot === undefined) {\n\t\t\tcompatibilityErrors.push(\n\t\t\t\t`No snapshot found with version less than or equal to minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)}.`,\n\t\t\t);\n\t\t}\n\t}\n\n\tfor (const [snapshotVersion, compatibility] of compatibilityMap) {\n\t\t// Current should be able to view all versions.\n\t\tif (!compatibility.currentViewOfSnapshotDocument.canUpgrade) {\n\t\t\tcompatibilityErrors.push(\n\t\t\t\t`Current version ${JSON.stringify(currentVersion)} cannot upgrade documents from ${JSON.stringify(snapshotVersion)}.`,\n\t\t\t);\n\t\t}\n\n\t\tif (semver.eq(snapshotVersion, currentVersion)) {\n\t\t\tif (currentVersion !== snapshotVersion) {\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`Snapshot version ${JSON.stringify(snapshotVersion)} is semantically equal but not string equal to current version ${JSON.stringify(currentVersion)}: this is not supported.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (\n\t\t\t\tcompatibility.currentViewOfSnapshotDocument.isEquivalent === false ||\n\t\t\t\tcompatibility.snapshotViewOfCurrentDocument.isEquivalent === false\n\t\t\t) {\n\t\t\t\tcompatibilityErrors.push(\n\t\t\t\t\t`Current version ${JSON.stringify(snapshotVersion)} expected to be equivalent to its snapshot.`,\n\t\t\t\t);\n\t\t\t}\n\t\t} else if (semver.lt(snapshotVersion, currentVersion)) {\n\t\t\tif (selectedMinVersionForCollaborationSnapshot === undefined) {\n\t\t\t\tassert(\n\t\t\t\t\tcompatibilityErrors.length > 0,\n\t\t\t\t\t0xcc7 /* expected compatibility errors for missing min collab version snapshot */,\n\t\t\t\t);\n\t\t\t} else {\n\t\t\t\t// Collaboration with this version is expected to work.\n\t\t\t\tif (semver.gte(snapshotVersion, selectedMinVersionForCollaborationSnapshot[0])) {\n\t\t\t\t\t// Check that the historical version can view documents from the current version, since collaboration with this one is expected to work.\n\t\t\t\t\tif (!compatibility.snapshotViewOfCurrentDocument.canView) {\n\t\t\t\t\t\tconst message = `Historical version ${JSON.stringify(snapshotVersion)} cannot view documents from ${JSON.stringify(currentVersion)}: these versions are expected to be able to collaborate due to the selected minVersionForCollaboration snapshot version being ${JSON.stringify(selectedMinVersionForCollaborationSnapshot[0])}.`;\n\t\t\t\t\t\tcompatibilityErrors.push(\n\t\t\t\t\t\t\tselectedMinVersionForCollaborationSnapshot[0] === minVersionForCollaboration\n\t\t\t\t\t\t\t\t? message\n\t\t\t\t\t\t\t\t: `${message} The specified minVersionForCollaboration is ${JSON.stringify(minVersionForCollaboration)} which was rounded down to an existing snapshot.`,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\t// This is the case where the historical version is less than the minimum version for collaboration.\n\t\t\t\t\t// No additional validation is needed here currently, since forwards document compat from these versions is already tested above (since it applies to all snapshots).\n\t\t\t\t}\n\t\t\t}\n\t\t} else {\n\t\t\tthrow new UsageError(\n\t\t\t\t`Unexpected semver comparison result between snapshot version ${JSON.stringify(snapshotVersion)} and app version ${JSON.stringify(currentVersion)}.`,\n\t\t\t);\n\t\t}\n\t}\n\n\tif (compatibilityErrors.length > 0) {\n\t\tthrow new Error(\n\t\t\t`Schema compatibility check failed:\\n${compatibilityErrors\n\t\t\t\t.map((e) => ` - ${e}`)\n\t\t\t\t.join(\"\\n\")}`,\n\t\t);\n\t}\n}\n\n/**\n * The high-level API for checking snapshot compatibility and generating new snapshots.\n */\nexport class SnapshotCompatibilityChecker {\n\tpublic constructor(\n\t\t/**\n\t\t * Directory where historical schema snapshots are stored.\n\t\t */\n\t\tprivate readonly snapshotDirectory: string,\n\t\t/**\n\t\t * How the `snapshotDirectory` is accessed.\n\t\t */\n\t\tprivate readonly fileSystemMethods: SnapshotFileSystem,\n\t) {}\n\n\tpublic writeSchemaSnapshot(snapshotName: string, snapshot: JsonCompatibleReadOnly): void {\n\t\tconst fullPath = this.fileSystemMethods.join(\n\t\t\tthis.snapshotDirectory,\n\t\t\t`${snapshotName}.json`,\n\t\t);\n\t\tthis.ensureSnapshotDirectoryExists();\n\t\tthis.fileSystemMethods.writeFileSync(fullPath, JSON.stringify(snapshot, undefined, 2), {\n\t\t\tencoding: \"utf8\",\n\t\t});\n\t}\n\n\tpublic readSchemaSnapshot(snapshotName: string): TreeViewConfiguration {\n\t\tconst snapshot = this.readSchemaSnapshotRaw(snapshotName);\n\t\treturn importCompatibilitySchemaSnapshot(snapshot);\n\t}\n\n\tpublic readSchemaSnapshotRaw(snapshotName: string): JsonCompatibleReadOnly {\n\t\tconst fullPath = this.fileSystemMethods.join(\n\t\t\tthis.snapshotDirectory,\n\t\t\t`${snapshotName}.json`,\n\t\t);\n\t\tconst snapshot = JSON.parse(\n\t\t\tthis.fileSystemMethods.readFileSync(fullPath, \"utf8\"),\n\t\t) as JsonCompatibleReadOnly;\n\t\treturn snapshot;\n\t}\n\n\t/**\n\t * Returns all schema snapshots stored in the snapshot directory, sorted in order of increasing version.\n\t */\n\tpublic readAllSchemaSnapshots(): Map<string, TreeViewConfiguration> {\n\t\tthis.ensureSnapshotDirectoryExists();\n\t\tconst files = this.fileSystemMethods.readdirSync(this.snapshotDirectory);\n\t\tconst versions: string[] = [];\n\t\tfor (const file of files) {\n\t\t\tif (file.endsWith(\".json\")) {\n\t\t\t\tconst snapshotName = file.slice(0, \".json\".length * -1);\n\t\t\t\tversions.push(snapshotName);\n\t\t\t}\n\t\t}\n\t\t// Ensures that errors are in a consistent and friendly order, independent of file system order.\n\t\tversions.sort((a, b) => semver.compare(a, b));\n\n\t\tconst snapshots: Map<string, TreeViewConfiguration> = new Map();\n\t\tfor (const version of versions) {\n\t\t\tsnapshots.set(version, this.readSchemaSnapshot(version));\n\t\t}\n\t\treturn snapshots;\n\t}\n\n\tpublic ensureSnapshotDirectoryExists(): void {\n\t\tthis.fileSystemMethods.mkdirSync(this.snapshotDirectory, { recursive: true });\n\t}\n}\n\n/**\n * Gets the compatibility of the current view schema against a historical snapshot.\n * @param currentViewSchema - The current view schema.\n * @param previousViewSchema - The historical view schema.\n * @returns The combined compatibility status.\n */\nexport function getCompatibility(\n\tcurrentViewSchema: TreeViewConfiguration,\n\tpreviousViewSchema: TreeViewConfiguration,\n): CombinedSchemaCompatibilityStatus {\n\tconst backwardsCompatibilityStatus = checkCompatibility(\n\t\tpreviousViewSchema,\n\t\tcurrentViewSchema,\n\t);\n\n\tconst forwardsCompatibilityStatus = checkCompatibility(\n\t\tcurrentViewSchema,\n\t\tpreviousViewSchema,\n\t);\n\n\treturn {\n\t\tcurrentViewOfSnapshotDocument: backwardsCompatibilityStatus,\n\t\tsnapshotViewOfCurrentDocument: forwardsCompatibilityStatus,\n\t};\n}\n"]}

package/lib/simple-tree/api/storedSchema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storedSchema.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/storedSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8CAA8C,CAAC;AAC5F,OAAO,EAGN,KAAK,aAAa,EAClB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAKnF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,mBAAmB,EAC3B,mBAAmB,EAAE,uBAAuB,EAC5C,aAAa,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,GAChD,cAAc,CAIhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CACrC,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,aAAa,GACpB,IAAI,CAAC,yBAAyB,EAAE,eAAe,CAAC,CAalD"}
+{"version":3,"file":"storedSchema.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/storedSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8CAA8C,CAAC;AAE5F,OAAO,EAGN,KAAK,aAAa,EAClB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAKnF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,mBAAmB,EAC3B,mBAAmB,EAAE,uBAAuB,EAC5C,aAAa,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,GAChD,cAAc,CAIhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CACrC,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,aAAa,GACpB,IAAI,CAAC,yBAAyB,EAAE,eAAe,CAAC,CAalD"}

package/lib/simple-tree/api/storedSchema.js.map

@@ -1 +1 @@
-{"version":3,"file":"storedSchema.js","sourceRoot":"","sources":["../../../src/simple-tree/api/storedSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACN,kBAAkB,EAClB,mBAAmB,GAEnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAOnE,OAAO,EAAE,oBAAoB,EAA4B,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAEhE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAG3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,sBAAsB,CACrC,MAA2B,EAC3B,mBAA4C,EAC5C,aAAkD;IAElD,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,eAAe,CAAC,EAAE,mBAAmB,EAAE,aAAa,EAAE,mBAAmB,EAAE,CAAC,CAAC;IAC3F,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,CAAmB,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,sBAAsB,CACrC,SAAyB,EACzB,IAAyB,EACzB,OAAsB;IAEtB,0DAA0D;IAC1D,2JAA2J;IAC3J,MAAM,WAAW,GAAG,eAAe,CAClC,EAAE,GAAG,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,CAAC,IAAI,EAAE,EAC5D,mBAAmB,CAAC,EAAE,CACtB,CAAC;IACF,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,SAAqB,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,0BAA0B,CAAC;QAC7C,MAAM,EAAE,oBAAoB,CAAC,IAAI,CAAC;KAClC,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,IAAI,yBAAyB,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,UAAU,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { MinimumVersionForCollab } from \"@fluidframework/runtime-definitions/internal\";\nimport {\n\tFluidClientVersion,\n\tFormatValidatorNoOp,\n\ttype ICodecOptions,\n} from \"../../codec/index.js\";\nimport { SchemaFormatVersion } from \"../../core/index.js\";\nimport { makeSchemaCodec } from \"../../feature-libraries/index.js\";\nimport type {\n\tFormatV1,\n\t// eslint-disable-next-line import-x/no-internal-modules\n} from \"../../feature-libraries/schema-index/index.js\";\nimport type { JsonCompatible } from \"../../util/index.js\";\nimport type { SchemaUpgrade } from \"../core/index.js\";\nimport { normalizeFieldSchema, type ImplicitFieldSchema } from \"../fieldSchema.js\";\nimport { toStoredSchema } from \"../toStoredSchema.js\";\nimport { TreeViewConfigurationAlpha } from \"./configuration.js\";\n\nimport { SchemaCompatibilityTester } from \"./schemaCompatibilityTester.js\";\nimport type { SchemaCompatibilityStatus } from \"./tree.js\";\n\n/**\n * Dumps the \"persisted\" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable format.\n *\n * @param schema - The schema to dump.\n * @param minVersionForCollab - The oldest client version which can read the schema: impacts the format used.\n * @param includeStaged - filter for selecting which staged allowed types to include in the output.\n *\n * @remarks\n * This can be used to help inspect schema for debugging, and to save a snapshot of schema to help detect and review changes to an applications schema.\n * This format is also compatible with {@link ViewContent.schema}, {@link comparePersistedSchema} and {@link persistedToSimpleSchema}.\n *\n * This only includes the \"persisted\" subset of schema information, which means the portion which gets included in documents.\n * It thus uses \"persisted\" keys, see {@link FieldProps.key}.\n *\n * If two schema have identical \"persisted\" schema, then they are considered {@link SchemaCompatibilityStatus.isEquivalent|equivalent}.\n *\n * See also {@link comparePersistedSchema}.\n *\n * @example\n * An application could use this API to generate a `schema.json` file when it first releases,\n * then test that the schema is sill compatible with documents from that version with a test like :\n * ```typescript\n * assert.deepEqual(extractPersistedSchema(MySchema, FluidClientVersion.v2_0), require(\"./schema.json\"));\n * ```\n *\n * @privateRemarks\n * This currently uses the schema summary format, but that could be changed to something more human readable (particularly if the encoded format becomes less human readable).\n * This intentionally does not leak the format types in the API.\n *\n * Public API surface uses \"persisted\" terminology while internally we use \"stored\".\n * @alpha\n */\nexport function extractPersistedSchema(\n\tschema: ImplicitFieldSchema,\n\tminVersionForCollab: MinimumVersionForCollab,\n\tincludeStaged: (upgrade: SchemaUpgrade) => boolean,\n): JsonCompatible {\n\tconst stored = toStoredSchema(schema, { includeStaged });\n\tconst codec = makeSchemaCodec({ minVersionForCollab, jsonValidator: FormatValidatorNoOp });\n\treturn codec.encode(stored) as JsonCompatible;\n}\n\n/**\n * Compares two schema extracted using {@link extractPersistedSchema}.\n * Reports the same compatibility that {@link TreeView.compatibility} would report if\n * opening a document that used the `persisted` schema and provided `view` to {@link ViewableTree.viewWith}.\n *\n * @param persisted - Schema persisted for a document. Typically persisted alongside the data and assumed to describe that data.\n * @param view - Schema which would be used to view persisted content.\n * @param options - {@link ICodecOptions} used when parsing the provided schema.\n * @param canInitialize - Passed through to the return value unchanged and otherwise unused.\n * @returns The {@link SchemaCompatibilityStatus} a {@link TreeView} would report for this combination of schema.\n *\n * @remarks\n * This uses the persisted formats for schema, meaning it only includes data which impacts compatibility.\n * It also uses the persisted format so that this API can be used in tests to compare against saved schema from previous versions of the application.\n *\n * @example\n * An application could use {@link extractPersistedSchema} to generate a `schema.json` file for various versions of the app,\n * then test that documents using those schema can be upgraded to work with the current schema using a test like:\n * ```typescript\n * assert(\n * \tcomparePersistedSchema(\n * \t\trequire(\"./schema.json\"),\n * \t\tMySchema,\n * \t\t{ jsonValidator: typeboxValidator },\n * \t\tfalse,\n * \t).canUpgrade,\n * );\n * ```\n * @alpha\n */\nexport function comparePersistedSchema(\n\tpersisted: JsonCompatible,\n\tview: ImplicitFieldSchema,\n\toptions: ICodecOptions,\n): Omit<SchemaCompatibilityStatus, \"canInitialize\"> {\n\t// Any version can be passed down to makeSchemaCodec here.\n\t// We only use the decode part, which always dispatches to the correct codec based on the version in the data, not the version passed to `makeSchemaCodec`.\n\tconst schemaCodec = makeSchemaCodec(\n\t\t{ ...options, minVersionForCollab: FluidClientVersion.v2_0 },\n\t\tSchemaFormatVersion.v1,\n\t);\n\tconst stored = schemaCodec.decode(persisted as FormatV1);\n\tconst config = new TreeViewConfigurationAlpha({\n\t\tschema: normalizeFieldSchema(view),\n\t});\n\tconst viewSchema = new SchemaCompatibilityTester(config);\n\treturn viewSchema.checkCompatibility(stored);\n}\n"]}
+{"version":3,"file":"storedSchema.js","sourceRoot":"","sources":["../../../src/simple-tree/api/storedSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EACN,kBAAkB,EAClB,mBAAmB,GAEnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAOnE,OAAO,EAAE,oBAAoB,EAA4B,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAG3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,sBAAsB,CACrC,MAA2B,EAC3B,mBAA4C,EAC5C,aAAkD;IAElD,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,eAAe,CAAC,EAAE,mBAAmB,EAAE,aAAa,EAAE,mBAAmB,EAAE,CAAC,CAAC;IAC3F,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,CAAmB,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,sBAAsB,CACrC,SAAyB,EACzB,IAAyB,EACzB,OAAsB;IAEtB,0DAA0D;IAC1D,2JAA2J;IAC3J,MAAM,WAAW,GAAG,eAAe,CAClC,EAAE,GAAG,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,CAAC,IAAI,EAAE,EAC5D,mBAAmB,CAAC,EAAE,CACtB,CAAC;IACF,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,SAAqB,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,0BAA0B,CAAC;QAC7C,MAAM,EAAE,oBAAoB,CAAC,IAAI,CAAC;KAClC,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,IAAI,yBAAyB,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,UAAU,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { MinimumVersionForCollab } from \"@fluidframework/runtime-definitions/internal\";\n\nimport {\n\tFluidClientVersion,\n\tFormatValidatorNoOp,\n\ttype ICodecOptions,\n} from \"../../codec/index.js\";\nimport { SchemaFormatVersion } from \"../../core/index.js\";\nimport { makeSchemaCodec } from \"../../feature-libraries/index.js\";\nimport type {\n\tFormatV1,\n\t// eslint-disable-next-line import-x/no-internal-modules\n} from \"../../feature-libraries/schema-index/index.js\";\nimport type { JsonCompatible } from \"../../util/index.js\";\nimport type { SchemaUpgrade } from \"../core/index.js\";\nimport { normalizeFieldSchema, type ImplicitFieldSchema } from \"../fieldSchema.js\";\nimport { toStoredSchema } from \"../toStoredSchema.js\";\n\nimport { TreeViewConfigurationAlpha } from \"./configuration.js\";\nimport { SchemaCompatibilityTester } from \"./schemaCompatibilityTester.js\";\nimport type { SchemaCompatibilityStatus } from \"./tree.js\";\n\n/**\n * Dumps the \"persisted\" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable format.\n *\n * @param schema - The schema to dump.\n * @param minVersionForCollab - The oldest client version which can read the schema: impacts the format used.\n * @param includeStaged - filter for selecting which staged allowed types to include in the output.\n *\n * @remarks\n * This can be used to help inspect schema for debugging, and to save a snapshot of schema to help detect and review changes to an applications schema.\n * This format is also compatible with {@link ViewContent.schema}, {@link comparePersistedSchema} and {@link persistedToSimpleSchema}.\n *\n * This only includes the \"persisted\" subset of schema information, which means the portion which gets included in documents.\n * It thus uses \"persisted\" keys, see {@link FieldProps.key}.\n *\n * If two schema have identical \"persisted\" schema, then they are considered {@link SchemaCompatibilityStatus.isEquivalent|equivalent}.\n *\n * See also {@link comparePersistedSchema}.\n *\n * @example\n * An application could use this API to generate a `schema.json` file when it first releases,\n * then test that the schema is sill compatible with documents from that version with a test like :\n * ```typescript\n * assert.deepEqual(extractPersistedSchema(MySchema, FluidClientVersion.v2_0), require(\"./schema.json\"));\n * ```\n *\n * @privateRemarks\n * This currently uses the schema summary format, but that could be changed to something more human readable (particularly if the encoded format becomes less human readable).\n * This intentionally does not leak the format types in the API.\n *\n * Public API surface uses \"persisted\" terminology while internally we use \"stored\".\n * @alpha\n */\nexport function extractPersistedSchema(\n\tschema: ImplicitFieldSchema,\n\tminVersionForCollab: MinimumVersionForCollab,\n\tincludeStaged: (upgrade: SchemaUpgrade) => boolean,\n): JsonCompatible {\n\tconst stored = toStoredSchema(schema, { includeStaged });\n\tconst codec = makeSchemaCodec({ minVersionForCollab, jsonValidator: FormatValidatorNoOp });\n\treturn codec.encode(stored) as JsonCompatible;\n}\n\n/**\n * Compares two schema extracted using {@link extractPersistedSchema}.\n * Reports the same compatibility that {@link TreeView.compatibility} would report if\n * opening a document that used the `persisted` schema and provided `view` to {@link ViewableTree.viewWith}.\n *\n * @param persisted - Schema persisted for a document. Typically persisted alongside the data and assumed to describe that data.\n * @param view - Schema which would be used to view persisted content.\n * @param options - {@link ICodecOptions} used when parsing the provided schema.\n * @param canInitialize - Passed through to the return value unchanged and otherwise unused.\n * @returns The {@link SchemaCompatibilityStatus} a {@link TreeView} would report for this combination of schema.\n *\n * @remarks\n * This uses the persisted formats for schema, meaning it only includes data which impacts compatibility.\n * It also uses the persisted format so that this API can be used in tests to compare against saved schema from previous versions of the application.\n *\n * @example\n * An application could use {@link extractPersistedSchema} to generate a `schema.json` file for various versions of the app,\n * then test that documents using those schema can be upgraded to work with the current schema using a test like:\n * ```typescript\n * assert(\n * \tcomparePersistedSchema(\n * \t\trequire(\"./schema.json\"),\n * \t\tMySchema,\n * \t\t{ jsonValidator: typeboxValidator },\n * \t\tfalse,\n * \t).canUpgrade,\n * );\n * ```\n * @alpha\n */\nexport function comparePersistedSchema(\n\tpersisted: JsonCompatible,\n\tview: ImplicitFieldSchema,\n\toptions: ICodecOptions,\n): Omit<SchemaCompatibilityStatus, \"canInitialize\"> {\n\t// Any version can be passed down to makeSchemaCodec here.\n\t// We only use the decode part, which always dispatches to the correct codec based on the version in the data, not the version passed to `makeSchemaCodec`.\n\tconst schemaCodec = makeSchemaCodec(\n\t\t{ ...options, minVersionForCollab: FluidClientVersion.v2_0 },\n\t\tSchemaFormatVersion.v1,\n\t);\n\tconst stored = schemaCodec.decode(persisted as FormatV1);\n\tconst config = new TreeViewConfigurationAlpha({\n\t\tschema: normalizeFieldSchema(view),\n\t});\n\tconst viewSchema = new SchemaCompatibilityTester(config);\n\treturn viewSchema.checkCompatibility(stored);\n}\n"]}

package/lib/simple-tree/api/tree.d.ts

@@ -4,13 +4,13 @@
  */
 import type { IFluidLoadable, IDisposable, Listenable } from "@fluidframework/core-interfaces";
 import type { CommitMetadata, ChangeMetadata, RevertibleAlphaFactory, RevertibleFactory } from "../../core/index.js";
+import type { JsonCompatibleReadOnly } from "../../util/index.js";
 import type { ImplicitFieldSchema, InsertableField, InsertableTreeFieldFromImplicitField, ReadableField, ReadSchema, TreeFieldFromImplicitField } from "../fieldSchema.js";
-import type { UnsafeUnknownSchema } from "../unsafeUnknownSchema.js";
 import type { SimpleTreeSchema } from "../simpleSchema.js";
+import type { UnsafeUnknownSchema } from "../unsafeUnknownSchema.js";
 import type { TreeViewConfiguration } from "./configuration.js";
 import type { RunTransactionParams, TransactionCallbackStatus, TransactionResult, TransactionResultExt, VoidTransactionCallbackStatus } from "./transactionTypes.js";
 import type { VerboseTree } from "./verboseTree.js";
-import type { JsonCompatibleReadOnly } from "../../util/index.js";
 /**
  * A tree from which a {@link TreeView} can be created.
  *
@@ -282,8 +282,10 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
     set root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);
     /**
      * Description of the current compatibility status between the view schema and stored schema.
-     *
+     * @remarks
      * {@link TreeViewEvents.schemaChanged} is fired when the compatibility status changes.
+     * See {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution/ | schema-evolution} for more guidance on how to change schema while maintaining compatibility.
+     * Use {@link checkSchemaCompatibilitySnapshots} to write tests to validate that this compatibility behaves as desired across schema changes.
      */
     readonly compatibility: SchemaCompatibilityStatus;
     /**

package/lib/simple-tree/api/tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/tree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAE/F,OAAO,KAAK,EACX,cAAc,EACd,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,MAAM,qBAAqB,CAAC;AAM7B,OAAO,KAAK,EACX,mBAAmB,EACnB,eAAe,EACf,oCAAoC,EACpC,aAAa,EACb,UAAU,EACV,0BAA0B,EAC1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EACX,oBAAoB,EACpB,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,6BAA6B,EAC7B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAElE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,KAAK,SAAS,mBAAmB,EACzC,MAAM,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAClC,QAAQ,CAAC,KAAK,CAAC,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,KAAM,SAAQ,YAAY,EAAE,cAAc;CAAG;AAE9D;;;GAGG;AACH,MAAM,WAAW,UAAW,SAAQ,KAAK;IACxC;;;;OAIG;IACH,aAAa,IAAI,WAAW,GAAG,SAAS,CAAC;IAEzC;;;;OAIG;IACH,kBAAkB,IAAI,gBAAgB,CAAC;IAEvC;;;OAGG;IACH,kBAAkB,IAAI,MAAM,CAAC;IAE7B;;;OAGG;IACH,kBAAkB,IAAI,MAAM,EAAE,CAAC;IAE/B;;;OAGG;IACH,oBAAoB,CAAC,KAAK,SAAS,mBAAmB,EACrD,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAClC,QAAQ,CAAC,KAAK,CAAC,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC9C;;;;OAIG;IACH,IAAI,IAAI,UAAU,CAAC;IAEnB;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAEzD;;;;;;;;;;OAUG;IACH,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAErC;;;;;;;;;OASG;IACH,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAgB,SAAQ,UAAU;IAClD;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAE9C;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,OAAO,SAAS,mBAAmB,EAChD,MAAM,EAAE,OAAO,GACb,IAAI,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;IAGlC,IAAI,IAAI,eAAe,CAAC;IAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,cAAc,CAAC,aAAa,EAAE,aAAa,EAC1C,WAAW,EAAE,MAAM,yBAAyB,CAAC,aAAa,EAAE,aAAa,CAAC,EAC1E,MAAM,CAAC,EAAE,oBAAoB,GAC3B,oBAAoB,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;IACtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,cAAc,CACb,WAAW,EAAE,MAAM,6BAA6B,GAAG,IAAI,EACvD,MAAM,CAAC,EAAE,oBAAoB,GAC3B,iBAAiB,CAAC;IAErB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;CAClD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,OAAO,SAAS,mBAAmB,CAAE,SAAQ,WAAW;IACxF;;;;;;;;;;;OAWG;IACH,IAAI,IAAI,IAAI,0BAA0B,CAAC,OAAO,CAAC,CAAC;IAEhD,IAAI,IAAI,CAAC,OAAO,EAAE,oCAAoC,CAAC,OAAO,CAAC,EAAE;IAEjE;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,yBAAyB,CAAC;IAElD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,aAAa,IAAI,IAAI,CAAC;IAEtB;;;;;;;OAOG;IACH,UAAU,CAAC,OAAO,EAAE,oCAAoC,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAEzE;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,cAAc,CAAC,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa,CAC7B,EAAE,CAAC,GAAG,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB,CAC/D,SAAQ,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,MAAM,CAAC,EAC/E,eAAe;IAChB,IAAI,IAAI,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;IAEnC,IAAI,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE;IAE5C,UAAU,CAAC,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAEpD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,cAAc,GAAG,gBAAgB,CAAC,CAAC;IAG/D,IAAI,IAAI,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;CAChE;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,OAAO,SAAS,mBAAmB,CACvE,SAAQ,QAAQ,CAAC,OAAO,CAAC,EACxB,UAAU;IAEX,IAAI,IAAI,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;CAC/D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACzC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CAKhC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC;IAC9E;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,EAAE,cAAc,EAAE,aAAa,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAE5E;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,IAAI,EAAE,cAAc,EAAE,aAAa,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAAC;CAClF;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;OAMG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB;;;;;;;OAOG;IACH,aAAa,IAAI,IAAI,CAAC;IAEtB;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,IAAI,EAAE,cAAc,EAAE,aAAa,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAC7E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS,mBAAmB,EAClE,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,GACrB,aAAa,CAAC,OAAO,CAAC,CAExB"}
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/tree.ts"],"names":[],"mappings":"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"}