@fluidframework/tree 2.71.0 → 2.73.0

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

@@ -0,0 +1,290 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeSimpleSchema = exports.encodeSimpleSchema = void 0;
+const index_js_1 = require("../../util/index.js");
+const internal_1 = require("@fluidframework/core-utils/internal");
+const index_js_2 = require("../core/index.js");
+const internal_2 = require("@fluidframework/telemetry-utils/internal");
+const Format = __importStar(require("../simpleSchemaFormatV1.js"));
+const index_js_3 = require("../../codec/index.js");
+/**
+ * Encodes a simple schema (view or stored) into a serializable format.
+ * @remarks The JSON-compatible schema returned from this method is only intended for use in snapshots/comparisons of schemas.
+ * It is not possible to reconstruct a full schema (including metadata and persistedMetadata) from the encoded format.
+ * @param treeSchema - The tree schema to convert.
+ * @returns A serializable representation of the schema.
+ *
+ * @alpha
+ */
+function encodeSimpleSchema(simpleSchema) {
+    // Convert types to serializable forms
+    const encodedDefinitions = {};
+    for (const [identifier, schema] of simpleSchema.definitions) {
+        const encodedDefinition = encodeNodeSchema(schema);
+        encodedDefinitions[identifier] = encodedDefinition;
+    }
+    const encodedSchema = {
+        version: Format.SimpleSchemaFormatVersion.v1,
+        root: encodeField(simpleSchema.root),
+        definitions: encodedDefinitions,
+    };
+    return encodedSchema;
+}
+exports.encodeSimpleSchema = encodeSimpleSchema;
+/**
+ * Decodes a JSON-compatible schema into a simple schema.
+ * @param encodedSchema - The encoded schema to decode.
+ * @param validator - The format validator to use to validate the encoded schema.
+ * @returns A decoded simple schema.
+ * @throws Will throw a usage error if the encoded schema is not in the expected format.
+ *
+ * @alpha
+ */
+function decodeSimpleSchema(encodedSchema, validator) {
+    const effectiveValidator = validator ?? index_js_3.FormatValidatorNoOp;
+    const compiledValidator = (0, index_js_3.extractJsonValidator)(effectiveValidator).compile(Format.SimpleTreeSchemaFormat);
+    if (!compiledValidator.check(encodedSchema)) {
+        throw new internal_2.UsageError("The provided simple schema is not valid according to the schema format.");
+    }
+    return {
+        root: decodeSimpleFieldSchema(encodedSchema.root),
+        definitions: new Map((0, internal_1.transformMapValues)((0, index_js_1.objectToMap)(encodedSchema.definitions), (value, key) => {
+            return decodeNodeSchema(value);
+        })),
+    };
+}
+exports.decodeSimpleSchema = decodeSimpleSchema;
+/**
+ * Encodes a node schema to a serializable object.
+ * @param schema - The node schema to convert.
+ * @returns A serializable representation of the node schema.
+ */
+function encodeNodeSchema(schema) {
+    const kind = schema.kind;
+    switch (kind) {
+        case index_js_2.NodeKind.Leaf:
+            return { leaf: encodeLeafNode(schema) };
+        case index_js_2.NodeKind.Array:
+            return { array: encodeContainerNode(schema) };
+        case index_js_2.NodeKind.Map:
+            return { map: encodeContainerNode(schema) };
+        case index_js_2.NodeKind.Record:
+            return { record: encodeContainerNode(schema) };
+        case index_js_2.NodeKind.Object:
+            return { object: encodeObjectNode(schema) };
+        default: {
+            (0, internal_1.unreachableCase)(kind);
+        }
+    }
+}
+/**
+ * Encodes a leaf node schema to a serializable object.
+ * @param schema - The leaf node schema to convert.
+ * @returns A serializable representation of the leaf node schema.
+ */
+function encodeLeafNode(schema) {
+    return {
+        kind: schema.kind,
+        leafKind: schema.leafKind,
+    };
+}
+/**
+ * Encodes a container node schema (a simple schema that is a Map, Array, or Record) to a serializable object.
+ * @param schema - The container node schema to convert.
+ * @returns A serializable representation of the container node schema. Includes the `kind` for disambiguation between different
+ * container kinds.
+ */
+function encodeContainerNode(schema) {
+    return {
+        kind: schema.kind,
+        simpleAllowedTypes: encodeSimpleAllowedTypes(schema.simpleAllowedTypes),
+    };
+}
+/**
+ * Encodes a simple allowed types map to a serializable object. Needed because JSON serialization does not support Maps.
+ * @param simpleAllowedTypes - The simple allowed types map to convert.
+ * @returns A serializable representation of the simple allowed types.
+ */
+function encodeSimpleAllowedTypes(simpleAllowedTypes) {
+    const encodedAllowedTypes = {};
+    for (const [identifier, attributes] of simpleAllowedTypes) {
+        const isStaged = attributes.isStaged instanceof index_js_2.SchemaUpgrade ? true : attributes.isStaged;
+        encodedAllowedTypes[identifier] = { isStaged };
+    }
+    return encodedAllowedTypes;
+}
+/**
+ * Encodes an object node schema to a serializable object.
+ * @param schema - The object node schema to convert.
+ * @returns A serializable representation of the object node schema.
+ */
+function encodeObjectNode(schema) {
+    const encodedFields = {};
+    for (const [fieldKey, fieldSchema] of schema.fields) {
+        encodedFields[fieldKey] = encodeObjectField(fieldSchema);
+    }
+    return {
+        kind: schema.kind,
+        fields: encodedFields,
+        allowUnknownOptionalFields: schema.allowUnknownOptionalFields,
+    };
+}
+/**
+ * Encodes an object field schema to a serializable object.
+ * @param fieldSchema - The object field schema to convert.
+ * @returns A serializable representation of the object field schema.
+ */
+function encodeObjectField(fieldSchema) {
+    const encodedField = encodeField(fieldSchema);
+    return { ...encodedField, storedKey: fieldSchema.storedKey };
+}
+/**
+ * Encodes a field schema to a serializable object.
+ * @param fieldSchema - The field schema to convert.
+ * @returns A serializable representation of the field schema.
+ */
+function encodeField(fieldSchema) {
+    return {
+        kind: fieldSchema.kind,
+        simpleAllowedTypes: encodeSimpleAllowedTypes(fieldSchema.simpleAllowedTypes),
+    };
+}
+const decodeNodeSchemaDispatcher = new index_js_3.DiscriminatedUnionDispatcher({
+    leaf: decodeLeafNode,
+    array: decodeContainerNode,
+    map: decodeContainerNode,
+    record: decodeContainerNode,
+    object: decodeObjectNode,
+});
+/**
+ * Decodes a node schema from a JSON-compatible object.
+ * @param encodedNodeSchema - The encoded node schema to decode.
+ * @returns The decoded node schema.
+ */
+function decodeNodeSchema(encodedNodeSchema) {
+    return decodeNodeSchemaDispatcher.dispatch(encodedNodeSchema);
+}
+/**
+ * Decodes a container node schema (array, map, record) from a JSON-compatible object.
+ * @param encodedContainerSchema - The encoded schema to decode.
+ * @returns The decoded container node schema.
+ */
+function decodeContainerNode(encodedContainerSchema) {
+    return {
+        kind: encodedContainerSchema.kind,
+        simpleAllowedTypes: decodeSimpleAllowedTypes(encodedContainerSchema.simpleAllowedTypes),
+        // We cannot encode persistedMetadata or metadata, so we explicitly set them to empty values.
+        persistedMetadata: undefined,
+        metadata: {},
+    };
+}
+/**
+ * Decodes a leaf node schema from a JSON-compatible object.
+ * @param encodedLeafSchema - The encoded leaf node schema.
+ * @returns The decoded leaf node schema.
+ */
+function decodeLeafNode(encodedLeafSchema) {
+    return {
+        kind: index_js_2.NodeKind.Leaf,
+        leafKind: encodedLeafSchema.leafKind,
+        // We cannot encode persistedMetadata or metadata, so we explicitly set them to empty values.
+        persistedMetadata: undefined,
+        metadata: {},
+    };
+}
+/**
+ * Decodes a object node schema from a JSON-compatible object.
+ * @param encodedObjectSchema - The encoded object node schema.
+ * @returns The decoded object node schema.
+ */
+function decodeObjectNode(encodedObjectSchema) {
+    return {
+        kind: index_js_2.NodeKind.Object,
+        fields: decodeObjectFields(encodedObjectSchema.fields),
+        // It is possible for allowUnknownOptionalFields to be undefined. This happens when serializing a Simple Schema derived
+        // from a stored schema.
+        allowUnknownOptionalFields: encodedObjectSchema.allowUnknownOptionalFields,
+        // We cannot encode persistedMetadata or metadata, so we explicitly set them to empty values when decoding.
+        persistedMetadata: undefined,
+        metadata: {},
+    };
+}
+/**
+ * Decodes a map of object fields from a JSON-compatible object.
+ * @param encodedFields - The encoded fields.
+ * @returns A map of the decoded object fields.
+ */
+function decodeObjectFields(encodedFields) {
+    const fields = new Map();
+    for (const [fieldKey, fieldSchema] of Object.entries(encodedFields)) {
+        fields.set(fieldKey, decodeObjectField(fieldSchema));
+    }
+    return fields;
+}
+/**
+ * Decodes a {@link SimpleObjectFieldSchema} from a JSON-compatible object.
+ * @param encodedField - The encoded field schema.
+ * @returns The decoded simple object field schema.
+ */
+function decodeObjectField(encodedField) {
+    const baseField = decodeSimpleFieldSchema(encodedField);
+    return {
+        ...baseField,
+        storedKey: encodedField.storedKey,
+    };
+}
+/**
+ * Decodes a {@link SimpleFieldSchema} from a JSON-compatible object.
+ * @param encodedField - The encoded field schema.
+ * @returns The decoded simple field schema.
+ */
+function decodeSimpleFieldSchema(encodedField) {
+    return {
+        kind: encodedField.kind,
+        simpleAllowedTypes: decodeSimpleAllowedTypes(encodedField.simpleAllowedTypes),
+        // We cannot encode persistedMetadata or metadata, so we explicitly set them to empty values when decoding.
+        persistedMetadata: undefined,
+        metadata: {},
+    };
+}
+/**
+ * Decodes a simple allowed types map from a JSON-compatible object.
+ * @param encodedAllowedTypes - The encoded simple allowed types.
+ * @returns A map of the decoded simple allowed types.
+ */
+function decodeSimpleAllowedTypes(encodedAllowedTypes) {
+    const untypedMap = (0, index_js_1.objectToMap)(encodedAllowedTypes);
+    const simpleAllowedTypes = (0, internal_1.transformMapValues)(untypedMap, (value) => {
+        const isStaged = value.isStaged === true ? (0, index_js_2.createSchemaUpgrade)() : value.isStaged;
+        return { isStaged };
+    });
+    return simpleAllowedTypes;
+}
+//# sourceMappingURL=simpleSchemaCodec.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"simpleSchemaCodec.js","sourceRoot":"","sources":["../../../src/simple-tree/api/simpleSchemaCodec.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 { objectToMap, type JsonCompatibleReadOnly } from \"../../util/index.js\";\nimport { unreachableCase, transformMapValues } from \"@fluidframework/core-utils/internal\";\nimport type {\n\tSimpleAllowedTypeAttributes,\n\tSimpleArrayNodeSchema,\n\tSimpleFieldSchema,\n\tSimpleLeafNodeSchema,\n\tSimpleMapNodeSchema,\n\tSimpleNodeSchema,\n\tSimpleObjectFieldSchema,\n\tSimpleObjectNodeSchema,\n\tSimpleRecordNodeSchema,\n\tSimpleTreeSchema,\n} from \"../simpleSchema.js\";\nimport { createSchemaUpgrade, NodeKind, SchemaUpgrade } from \"../core/index.js\";\nimport type { FieldKind } from \"../fieldSchema.js\";\nimport type { ValueSchema } from \"../../core/index.js\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport * as Format from \"../simpleSchemaFormatV1.js\";\nimport {\n\tDiscriminatedUnionDispatcher,\n\textractJsonValidator,\n\tFormatValidatorNoOp,\n\ttype FormatValidator,\n} from \"../../codec/index.js\";\n\n/**\n * Encodes a simple schema (view or stored) into a serializable format.\n * @remarks The JSON-compatible schema returned from this method is only intended for use in snapshots/comparisons of schemas.\n * It is not possible to reconstruct a full schema (including metadata and persistedMetadata) from the encoded format.\n * @param treeSchema - The tree schema to convert.\n * @returns A serializable representation of the schema.\n *\n * @alpha\n */\nexport function encodeSimpleSchema(simpleSchema: SimpleTreeSchema): JsonCompatibleReadOnly {\n\t// Convert types to serializable forms\n\tconst encodedDefinitions: Format.SimpleSchemaDefinitionsFormat = {};\n\n\tfor (const [identifier, schema] of simpleSchema.definitions) {\n\t\tconst encodedDefinition = encodeNodeSchema(schema);\n\t\tencodedDefinitions[identifier] = encodedDefinition;\n\t}\n\n\tconst encodedSchema: Format.SimpleTreeSchemaFormat = {\n\t\tversion: Format.SimpleSchemaFormatVersion.v1,\n\t\troot: encodeField(simpleSchema.root),\n\t\tdefinitions: encodedDefinitions,\n\t};\n\n\treturn encodedSchema;\n}\n\n/**\n * Decodes a JSON-compatible schema into a simple schema.\n * @param encodedSchema - The encoded schema to decode.\n * @param validator - The format validator to use to validate the encoded schema.\n * @returns A decoded simple schema.\n * @throws Will throw a usage error if the encoded schema is not in the expected format.\n *\n * @alpha\n */\nexport function decodeSimpleSchema(\n\tencodedSchema: JsonCompatibleReadOnly,\n\tvalidator?: FormatValidator,\n): SimpleTreeSchema {\n\tconst effectiveValidator = validator ?? FormatValidatorNoOp;\n\tconst compiledValidator = extractJsonValidator(effectiveValidator).compile(\n\t\tFormat.SimpleTreeSchemaFormat,\n\t);\n\tif (!compiledValidator.check(encodedSchema)) {\n\t\tthrow new UsageError(\n\t\t\t\"The provided simple schema is not valid according to the schema format.\",\n\t\t);\n\t}\n\n\treturn {\n\t\troot: decodeSimpleFieldSchema(encodedSchema.root),\n\t\tdefinitions: new Map(\n\t\t\ttransformMapValues(objectToMap(encodedSchema.definitions), (value, key) => {\n\t\t\t\treturn decodeNodeSchema(value);\n\t\t\t}),\n\t\t),\n\t};\n}\n\n/**\n * Encodes a node schema to a serializable object.\n * @param schema - The node schema to convert.\n * @returns A serializable representation of the node schema.\n */\nfunction encodeNodeSchema(schema: SimpleNodeSchema): Format.SimpleNodeSchemaUnionFormat {\n\tconst kind = schema.kind;\n\tswitch (kind) {\n\t\tcase NodeKind.Leaf:\n\t\t\treturn { leaf: encodeLeafNode(schema) };\n\t\tcase NodeKind.Array:\n\t\t\treturn { array: encodeContainerNode(schema) };\n\t\tcase NodeKind.Map:\n\t\t\treturn { map: encodeContainerNode(schema) };\n\t\tcase NodeKind.Record:\n\t\t\treturn { record: encodeContainerNode(schema) };\n\t\tcase NodeKind.Object:\n\t\t\treturn { object: encodeObjectNode(schema) };\n\t\tdefault: {\n\t\t\tunreachableCase(kind);\n\t\t}\n\t}\n}\n\n/**\n * Encodes a leaf node schema to a serializable object.\n * @param schema - The leaf node schema to convert.\n * @returns A serializable representation of the leaf node schema.\n */\nfunction encodeLeafNode(schema: SimpleLeafNodeSchema): Format.SimpleLeafNodeSchemaFormat {\n\treturn {\n\t\tkind: schema.kind,\n\t\tleafKind: schema.leafKind,\n\t};\n}\n\n/**\n * Encodes a container node schema (a simple schema that is a Map, Array, or Record) to a serializable object.\n * @param schema - The container node schema to convert.\n * @returns A serializable representation of the container node schema. Includes the `kind` for disambiguation between different\n * container kinds.\n */\nfunction encodeContainerNode(\n\tschema: SimpleArrayNodeSchema | SimpleMapNodeSchema | SimpleRecordNodeSchema,\n):\n\t| Format.SimpleArrayNodeSchemaFormat\n\t| Format.SimpleMapNodeSchemaFormat\n\t| Format.SimpleRecordNodeSchemaFormat {\n\treturn {\n\t\tkind: schema.kind,\n\t\tsimpleAllowedTypes: encodeSimpleAllowedTypes(schema.simpleAllowedTypes),\n\t};\n}\n\n/**\n * Encodes a simple allowed types map to a serializable object. Needed because JSON serialization does not support Maps.\n * @param simpleAllowedTypes - The simple allowed types map to convert.\n * @returns A serializable representation of the simple allowed types.\n */\nfunction encodeSimpleAllowedTypes(\n\tsimpleAllowedTypes: ReadonlyMap<string, SimpleAllowedTypeAttributes>,\n): Format.SimpleAllowedTypesFormat {\n\tconst encodedAllowedTypes: Format.SimpleAllowedTypesFormat = {};\n\tfor (const [identifier, attributes] of simpleAllowedTypes) {\n\t\tconst isStaged = attributes.isStaged instanceof SchemaUpgrade ? true : attributes.isStaged;\n\t\tencodedAllowedTypes[identifier] = { isStaged };\n\t}\n\treturn encodedAllowedTypes;\n}\n\n/**\n * Encodes an object node schema to a serializable object.\n * @param schema - The object node schema to convert.\n * @returns A serializable representation of the object node schema.\n */\nfunction encodeObjectNode(\n\tschema: SimpleObjectNodeSchema,\n): Format.SimpleObjectNodeSchemaFormat {\n\tconst encodedFields: Format.SimpleObjectFieldSchemasFormat = {};\n\tfor (const [fieldKey, fieldSchema] of schema.fields) {\n\t\tencodedFields[fieldKey] = encodeObjectField(fieldSchema);\n\t}\n\n\treturn {\n\t\tkind: schema.kind,\n\t\tfields: encodedFields,\n\t\tallowUnknownOptionalFields: schema.allowUnknownOptionalFields,\n\t};\n}\n\n/**\n * Encodes an object field schema to a serializable object.\n * @param fieldSchema - The object field schema to convert.\n * @returns A serializable representation of the object field schema.\n */\nfunction encodeObjectField(\n\tfieldSchema: SimpleObjectFieldSchema,\n): Format.SimpleObjectFieldSchemaFormat {\n\tconst encodedField = encodeField(fieldSchema);\n\treturn { ...encodedField, storedKey: fieldSchema.storedKey };\n}\n\n/**\n * Encodes a field schema to a serializable object.\n * @param fieldSchema - The field schema to convert.\n * @returns A serializable representation of the field schema.\n */\nfunction encodeField(fieldSchema: SimpleFieldSchema): Format.SimpleFieldSchemaFormat {\n\treturn {\n\t\tkind: fieldSchema.kind,\n\t\tsimpleAllowedTypes: encodeSimpleAllowedTypes(fieldSchema.simpleAllowedTypes),\n\t};\n}\n\nconst decodeNodeSchemaDispatcher: DiscriminatedUnionDispatcher<\n\tFormat.SimpleNodeSchemaUnionFormat,\n\t[],\n\t| SimpleLeafNodeSchema\n\t| SimpleArrayNodeSchema\n\t| SimpleMapNodeSchema\n\t| SimpleRecordNodeSchema\n\t| SimpleObjectNodeSchema\n> = new DiscriminatedUnionDispatcher({\n\tleaf: decodeLeafNode,\n\tarray: decodeContainerNode,\n\tmap: decodeContainerNode,\n\trecord: decodeContainerNode,\n\tobject: decodeObjectNode,\n});\n\n/**\n * Decodes a node schema from a JSON-compatible object.\n * @param encodedNodeSchema - The encoded node schema to decode.\n * @returns The decoded node schema.\n */\nfunction decodeNodeSchema(\n\tencodedNodeSchema: Format.SimpleNodeSchemaUnionFormat,\n):\n\t| SimpleLeafNodeSchema\n\t| SimpleArrayNodeSchema\n\t| SimpleMapNodeSchema\n\t| SimpleRecordNodeSchema\n\t| SimpleObjectNodeSchema {\n\treturn decodeNodeSchemaDispatcher.dispatch(encodedNodeSchema);\n}\n\n/**\n * Decodes a container node schema (array, map, record) from a JSON-compatible object.\n * @param encodedContainerSchema - The encoded schema to decode.\n * @returns The decoded container node schema.\n */\nfunction decodeContainerNode(\n\tencodedContainerSchema:\n\t\t| Format.SimpleArrayNodeSchemaFormat\n\t\t| Format.SimpleMapNodeSchemaFormat\n\t\t| Format.SimpleRecordNodeSchemaFormat,\n): SimpleArrayNodeSchema | SimpleMapNodeSchema | SimpleRecordNodeSchema {\n\treturn {\n\t\tkind: encodedContainerSchema.kind as NodeKind.Array | NodeKind.Map | NodeKind.Record,\n\t\tsimpleAllowedTypes: decodeSimpleAllowedTypes(encodedContainerSchema.simpleAllowedTypes),\n\t\t// We cannot encode persistedMetadata or metadata, so we explicitly set them to empty values.\n\t\tpersistedMetadata: undefined,\n\t\tmetadata: {},\n\t};\n}\n\n/**\n * Decodes a leaf node schema from a JSON-compatible object.\n * @param encodedLeafSchema - The encoded leaf node schema.\n * @returns The decoded leaf node schema.\n */\nfunction decodeLeafNode(\n\tencodedLeafSchema: Format.SimpleLeafNodeSchemaFormat,\n): SimpleLeafNodeSchema {\n\treturn {\n\t\tkind: NodeKind.Leaf,\n\t\tleafKind: encodedLeafSchema.leafKind as ValueSchema,\n\t\t// We cannot encode persistedMetadata or metadata, so we explicitly set them to empty values.\n\t\tpersistedMetadata: undefined,\n\t\tmetadata: {},\n\t};\n}\n\n/**\n * Decodes a object node schema from a JSON-compatible object.\n * @param encodedObjectSchema - The encoded object node schema.\n * @returns The decoded object node schema.\n */\nfunction decodeObjectNode(\n\tencodedObjectSchema: Format.SimpleObjectNodeSchemaFormat,\n): SimpleObjectNodeSchema {\n\treturn {\n\t\tkind: NodeKind.Object,\n\t\tfields: decodeObjectFields(encodedObjectSchema.fields),\n\t\t// It is possible for allowUnknownOptionalFields to be undefined. This happens when serializing a Simple Schema derived\n\t\t// from a stored schema.\n\t\tallowUnknownOptionalFields: encodedObjectSchema.allowUnknownOptionalFields,\n\t\t// We cannot encode persistedMetadata or metadata, so we explicitly set them to empty values when decoding.\n\t\tpersistedMetadata: undefined,\n\t\tmetadata: {},\n\t};\n}\n\n/**\n * Decodes a map of object fields from a JSON-compatible object.\n * @param encodedFields - The encoded fields.\n * @returns A map of the decoded object fields.\n */\nfunction decodeObjectFields(\n\tencodedFields: Format.SimpleObjectFieldSchemasFormat,\n): ReadonlyMap<string, SimpleObjectFieldSchema> {\n\tconst fields = new Map<string, SimpleObjectFieldSchema>();\n\tfor (const [fieldKey, fieldSchema] of Object.entries(encodedFields)) {\n\t\tfields.set(fieldKey, decodeObjectField(fieldSchema));\n\t}\n\treturn fields;\n}\n\n/**\n * Decodes a {@link SimpleObjectFieldSchema} from a JSON-compatible object.\n * @param encodedField - The encoded field schema.\n * @returns The decoded simple object field schema.\n */\nfunction decodeObjectField(\n\tencodedField: Format.SimpleObjectFieldSchemaFormat,\n): SimpleObjectFieldSchema {\n\tconst baseField = decodeSimpleFieldSchema(encodedField);\n\treturn {\n\t\t...baseField,\n\t\tstoredKey: encodedField.storedKey,\n\t};\n}\n\n/**\n * Decodes a {@link SimpleFieldSchema} from a JSON-compatible object.\n * @param encodedField - The encoded field schema.\n * @returns The decoded simple field schema.\n */\nfunction decodeSimpleFieldSchema(\n\tencodedField: Format.SimpleFieldSchemaFormat,\n): SimpleFieldSchema {\n\treturn {\n\t\tkind: encodedField.kind as FieldKind,\n\t\tsimpleAllowedTypes: decodeSimpleAllowedTypes(encodedField.simpleAllowedTypes),\n\t\t// We cannot encode persistedMetadata or metadata, so we explicitly set them to empty values when decoding.\n\t\tpersistedMetadata: undefined,\n\t\tmetadata: {},\n\t};\n}\n\n/**\n * Decodes a simple allowed types map from a JSON-compatible object.\n * @param encodedAllowedTypes - The encoded simple allowed types.\n * @returns A map of the decoded simple allowed types.\n */\nfunction decodeSimpleAllowedTypes(\n\tencodedAllowedTypes: Format.SimpleAllowedTypesFormat,\n): ReadonlyMap<string, SimpleAllowedTypeAttributes> {\n\tconst untypedMap = objectToMap(encodedAllowedTypes);\n\n\tconst simpleAllowedTypes = transformMapValues(\n\t\tuntypedMap,\n\t\t(value): SimpleAllowedTypeAttributes => {\n\t\t\tconst isStaged = value.isStaged === true ? createSchemaUpgrade() : value.isStaged;\n\t\t\treturn { isStaged };\n\t\t},\n\t);\n\n\treturn simpleAllowedTypes;\n}\n"]}

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

@@ -0,0 +1,103 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { JsonCompatibleReadOnly } from "../../util/index.js";
+import { TreeViewConfiguration } from "./configuration.js";
+import type { SchemaCompatibilityStatus } from "./tree.js";
+/**
+ * Compute the compatibility of using `view` to {@link ViewableTree.viewWith | view a tree} who's {@link ITreeAlpha.exportSimpleSchema | stored schema} could be derived from `viewWhichCreatedStoredSchema` via either {@link TreeView.initialize} or {@link TreeView.upgradeSchema}.
+ *
+ * @remarks See {@link SchemaCompatibilityStatus} for details on the compatibility results.
+ *
+ * @example This example demonstrates checking the compatibility of a historical schema against a current schema.
+ * In this case, the historical schema is a Point2D object with x and y fields, while the current schema is a Point3D object
+ * that adds an optional z field.
+ *
+ * ```ts
+ * // This snapshot is assumed to be the same as Point3D, except missing `z`.
+ * const encodedSchema = JSON.parse(fs.readFileSync("PointSchema.json", "utf8"));
+ * const oldViewSchema = importCompatibilitySchemaSnapshot(encodedSchema);
+ *
+ * // Build the current view schema
+ * class Point3D extends factory.object("Point", {
+ * 	x: factory.number,
+ * 	y: factory.number,
+ *
+ * 	// The current schema has a new optional field that was not present on Point2D
+ * 	z: factory.optional(factory.number),
+ * }) {}
+ * const currentViewSchema = new TreeViewConfiguration({ schema: Point3D });
+ *
+ * // Check to see if the document created by the historical view schema can be opened with the current view schema
+ * const backwardsCompatibilityStatus = checkCompatibility(oldViewSchema, currentViewSchema);
+ *
+ * // z is not present in Point2D, so the schema must be upgraded
+ * assert.equal(backwardsCompatibilityStatus.canView, false);
+ *
+ * // The schema can be upgraded to add the new optional field
+ * assert.equal(backwardsCompatibilityStatus.canUpgrade, true);
+ *
+ * // Test what the old version of the application would do with a tree using the new schema:
+ * const forwardsCompatibilityStatus = checkCompatibility(currentViewSchema, oldViewSchema);
+ *
+ * // If the old schema set allowUnknownOptionalFields, this would be true, but since it did not,
+ * // this assert will fail, detecting the forwards compatibility break:
+ * // this means these two versions of the application cannot collaborate on content using these schema.
+ * assert.equal(forwardsCompatibilityStatus.canView, true);
+ * ```
+ *
+ * @param viewWhichCreatedStoredSchema - From which to derive the stored schema, as if it initialized or upgraded a tree via {@link TreeView}.
+ * @param view - The view being tested to see if it could view tree created or initialized using `viewWhichCreatedStoredSchema`.
+ * @returns The compatibility status.
+ *
+ * @alpha
+ */
+export declare function checkCompatibility(viewWhichCreatedStoredSchema: TreeViewConfiguration, view: TreeViewConfiguration): Omit<SchemaCompatibilityStatus, "canInitialize">;
+/**
+ * Returns a JSON compatible representation of the tree schema for snapshot compatibility checking.
+ *
+ * Snapshots can be loaded by the same or newer package versions, but not necessarily older versions.
+ *
+ * @see {@link importCompatibilitySchemaSnapshot} which loads these snapshots.
+ *
+ * @param config - The schema to snapshot. Only the schema field of the `TreeViewConfiguration` is used.
+ * @returns The JSON representation of the schema.
+ *
+ * @example This example creates and persists a snapshot of a Point2D schema.
+ *
+ * ```ts
+ * const schemaFactory = new SchemaFactory("test");
+ * class Point2D extends schemaFactory.object("Point", {
+ * 	x: factory.number,
+ * 	y: factory.number,
+ * }) {}
+ * const viewSchema = new TreeViewConfiguration({ schema: Point2D });
+ * const encodedSchema = JSON.stringify(exportCompatibilitySchemaSnapshot(viewSchema));
+ * fs.writeFileSync("PointSchema.json", encodedSchema);
+ * ```
+ *
+ * @alpha
+ */
+export declare function exportCompatibilitySchemaSnapshot(config: Pick<TreeViewConfiguration, "schema">): JsonCompatibleReadOnly;
+/**
+ * Parse the format exported by {@link exportCompatibilitySchemaSnapshot} into a schema.
+ *
+ * Can load snapshots created by the same or older package versions, but not necessarily newer versions.
+ *
+ * @see {@link exportCompatibilitySchemaSnapshot} which creates these snapshots.
+ *
+ * @param config - The JSON representation of the schema.
+ * @returns The schema. Only the schema field of the {@link TreeViewConfiguration} is populated.
+ * @throws Will throw a usage error if the encoded schema is not in the expected format.
+ *
+ * @example This example loads and parses a snapshot of a Point2D schema.
+ *
+ * ```ts;
+ * const oldViewSchema = importCompatibilitySchemaSnapshot(fs.readFileSync("PointSchema.json", "utf8"));
+ * ```
+ *
+ * @alpha
+ */
+export declare function importCompatibilitySchemaSnapshot(config: JsonCompatibleReadOnly): TreeViewConfiguration;
+//# sourceMappingURL=snapshotCompatibilityChecker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotCompatibilityChecker.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/snapshotCompatibilityChecker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAElE,OAAO,EAA8B,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAIvF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAG3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,kBAAkB,CACjC,4BAA4B,EAAE,qBAAqB,EACnD,IAAI,EAAE,qBAAqB,GACzB,IAAI,CAAC,yBAAyB,EAAE,eAAe,CAAC,CAOlD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iCAAiC,CAChD,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,GAC3C,sBAAsB,CAGxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iCAAiC,CAChD,MAAM,EAAE,sBAAsB,GAC5B,qBAAqB,CAOvB"}

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

@@ -0,0 +1,128 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importCompatibilitySchemaSnapshot = exports.exportCompatibilitySchemaSnapshot = exports.checkCompatibility = void 0;
+const toStoredSchema_js_1 = require("../toStoredSchema.js");
+const configuration_js_1 = require("./configuration.js");
+const schemaCompatibilityTester_js_1 = require("./schemaCompatibilityTester.js");
+const schemaFromSimple_js_1 = require("./schemaFromSimple.js");
+const simpleSchemaCodec_js_1 = require("./simpleSchemaCodec.js");
+const viewSchemaToSimpleSchema_js_1 = require("./viewSchemaToSimpleSchema.js");
+/**
+ * Compute the compatibility of using `view` to {@link ViewableTree.viewWith | view a tree} who's {@link ITreeAlpha.exportSimpleSchema | stored schema} could be derived from `viewWhichCreatedStoredSchema` via either {@link TreeView.initialize} or {@link TreeView.upgradeSchema}.
+ *
+ * @remarks See {@link SchemaCompatibilityStatus} for details on the compatibility results.
+ *
+ * @example This example demonstrates checking the compatibility of a historical schema against a current schema.
+ * In this case, the historical schema is a Point2D object with x and y fields, while the current schema is a Point3D object
+ * that adds an optional z field.
+ *
+ * ```ts
+ * // This snapshot is assumed to be the same as Point3D, except missing `z`.
+ * const encodedSchema = JSON.parse(fs.readFileSync("PointSchema.json", "utf8"));
+ * const oldViewSchema = importCompatibilitySchemaSnapshot(encodedSchema);
+ *
+ * // Build the current view schema
+ * class Point3D extends factory.object("Point", {
+ * 	x: factory.number,
+ * 	y: factory.number,
+ *
+ * 	// The current schema has a new optional field that was not present on Point2D
+ * 	z: factory.optional(factory.number),
+ * }) {}
+ * const currentViewSchema = new TreeViewConfiguration({ schema: Point3D });
+ *
+ * // Check to see if the document created by the historical view schema can be opened with the current view schema
+ * const backwardsCompatibilityStatus = checkCompatibility(oldViewSchema, currentViewSchema);
+ *
+ * // z is not present in Point2D, so the schema must be upgraded
+ * assert.equal(backwardsCompatibilityStatus.canView, false);
+ *
+ * // The schema can be upgraded to add the new optional field
+ * assert.equal(backwardsCompatibilityStatus.canUpgrade, true);
+ *
+ * // Test what the old version of the application would do with a tree using the new schema:
+ * const forwardsCompatibilityStatus = checkCompatibility(currentViewSchema, oldViewSchema);
+ *
+ * // If the old schema set allowUnknownOptionalFields, this would be true, but since it did not,
+ * // this assert will fail, detecting the forwards compatibility break:
+ * // this means these two versions of the application cannot collaborate on content using these schema.
+ * assert.equal(forwardsCompatibilityStatus.canView, true);
+ * ```
+ *
+ * @param viewWhichCreatedStoredSchema - From which to derive the stored schema, as if it initialized or upgraded a tree via {@link TreeView}.
+ * @param view - The view being tested to see if it could view tree created or initialized using `viewWhichCreatedStoredSchema`.
+ * @returns The compatibility status.
+ *
+ * @alpha
+ */
+function checkCompatibility(viewWhichCreatedStoredSchema, view) {
+    const viewAsAlpha = new configuration_js_1.TreeViewConfigurationAlpha({ schema: view.schema });
+    const stored = (0, toStoredSchema_js_1.toStoredSchema)(viewWhichCreatedStoredSchema.schema, {
+        includeStaged: () => true,
+    });
+    const tester = new schemaCompatibilityTester_js_1.SchemaCompatibilityTester(viewAsAlpha);
+    return tester.checkCompatibility(stored);
+}
+exports.checkCompatibility = checkCompatibility;
+/**
+ * Returns a JSON compatible representation of the tree schema for snapshot compatibility checking.
+ *
+ * Snapshots can be loaded by the same or newer package versions, but not necessarily older versions.
+ *
+ * @see {@link importCompatibilitySchemaSnapshot} which loads these snapshots.
+ *
+ * @param config - The schema to snapshot. Only the schema field of the `TreeViewConfiguration` is used.
+ * @returns The JSON representation of the schema.
+ *
+ * @example This example creates and persists a snapshot of a Point2D schema.
+ *
+ * ```ts
+ * const schemaFactory = new SchemaFactory("test");
+ * class Point2D extends schemaFactory.object("Point", {
+ * 	x: factory.number,
+ * 	y: factory.number,
+ * }) {}
+ * const viewSchema = new TreeViewConfiguration({ schema: Point2D });
+ * const encodedSchema = JSON.stringify(exportCompatibilitySchemaSnapshot(viewSchema));
+ * fs.writeFileSync("PointSchema.json", encodedSchema);
+ * ```
+ *
+ * @alpha
+ */
+function exportCompatibilitySchemaSnapshot(config) {
+    const simpleSchema = (0, viewSchemaToSimpleSchema_js_1.toSimpleTreeSchema)(config.schema, true);
+    return (0, simpleSchemaCodec_js_1.encodeSimpleSchema)(simpleSchema);
+}
+exports.exportCompatibilitySchemaSnapshot = exportCompatibilitySchemaSnapshot;
+/**
+ * Parse the format exported by {@link exportCompatibilitySchemaSnapshot} into a schema.
+ *
+ * Can load snapshots created by the same or older package versions, but not necessarily newer versions.
+ *
+ * @see {@link exportCompatibilitySchemaSnapshot} which creates these snapshots.
+ *
+ * @param config - The JSON representation of the schema.
+ * @returns The schema. Only the schema field of the {@link TreeViewConfiguration} is populated.
+ * @throws Will throw a usage error if the encoded schema is not in the expected format.
+ *
+ * @example This example loads and parses a snapshot of a Point2D schema.
+ *
+ * ```ts;
+ * const oldViewSchema = importCompatibilitySchemaSnapshot(fs.readFileSync("PointSchema.json", "utf8"));
+ * ```
+ *
+ * @alpha
+ */
+function importCompatibilitySchemaSnapshot(config) {
+    const simpleSchema = (0, simpleSchemaCodec_js_1.decodeSimpleSchema)(config);
+    const viewSchema = (0, schemaFromSimple_js_1.generateSchemaFromSimpleSchema)(simpleSchema);
+    // We construct a TreeViewConfiguration here with the default parameters. The default set of validation parameters are fine for
+    // a schema produced by `generateSchemaFromSimpleSchema`.
+    return new configuration_js_1.TreeViewConfiguration({ schema: viewSchema.root });
+}
+exports.importCompatibilitySchemaSnapshot = importCompatibilitySchemaSnapshot;
+//# sourceMappingURL=snapshotCompatibilityChecker.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotCompatibilityChecker.js","sourceRoot":"","sources":["../../../src/simple-tree/api/snapshotCompatibilityChecker.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAGH,4DAAsD;AACtD,yDAAuF;AACvF,iFAA2E;AAC3E,+DAAuE;AACvE,iEAAgF;AAEhF,+EAAmE;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,SAAgB,kBAAkB,CACjC,4BAAmD,EACnD,IAA2B;IAE3B,MAAM,WAAW,GAAG,IAAI,6CAA0B,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,MAAM,MAAM,GAAG,IAAA,kCAAc,EAAC,4BAA4B,CAAC,MAAM,EAAE;QAClE,aAAa,EAAE,GAAG,EAAE,CAAC,IAAI;KACzB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,IAAI,wDAAyB,CAAC,WAAW,CAAC,CAAC;IAC1D,OAAO,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC;AAVD,gDAUC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,iCAAiC,CAChD,MAA6C;IAE7C,MAAM,YAAY,GAAG,IAAA,gDAAkB,EAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC7D,OAAO,IAAA,yCAAkB,EAAC,YAAY,CAAC,CAAC;AACzC,CAAC;AALD,8EAKC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,iCAAiC,CAChD,MAA8B;IAE9B,MAAM,YAAY,GAAG,IAAA,yCAAkB,EAAC,MAAM,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,IAAA,oDAA8B,EAAC,YAAY,CAAC,CAAC;IAEhE,+HAA+H;IAC/H,yDAAyD;IACzD,OAAO,IAAI,wCAAqB,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;AAC/D,CAAC;AATD,8EASC","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 { toStoredSchema } from \"../toStoredSchema.js\";\nimport { TreeViewConfigurationAlpha, TreeViewConfiguration } from \"./configuration.js\";\nimport { SchemaCompatibilityTester } from \"./schemaCompatibilityTester.js\";\nimport { generateSchemaFromSimpleSchema } from \"./schemaFromSimple.js\";\nimport { decodeSimpleSchema, encodeSimpleSchema } from \"./simpleSchemaCodec.js\";\nimport type { SchemaCompatibilityStatus } from \"./tree.js\";\nimport { toSimpleTreeSchema } from \"./viewSchemaToSimpleSchema.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 * @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 = toStoredSchema(viewWhichCreatedStoredSchema.schema, {\n\t\tincludeStaged: () => true,\n\t});\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 * @alpha\n */\nexport function exportCompatibilitySchemaSnapshot(\n\tconfig: Pick<TreeViewConfiguration, \"schema\">,\n): JsonCompatibleReadOnly {\n\tconst simpleSchema = toSimpleTreeSchema(config.schema, true);\n\treturn encodeSimpleSchema(simpleSchema);\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 *\n * @alpha\n */\nexport function importCompatibilitySchemaSnapshot(\n\tconfig: JsonCompatibleReadOnly,\n): TreeViewConfiguration {\n\tconst simpleSchema = decodeSimpleSchema(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"]}

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

@@ -3,8 +3,8 @@
  * Licensed under the MIT License.
  */
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
-import type { ICodecOptions } from "../../codec/index.js";
-import type { JsonCompatible } from "../../util/index.js";
+import { type ICodecOptions } from "../../codec/index.js";
+import { type JsonCompatible } from "../../util/index.js";
 import type { SchemaUpgrade } from "../core/index.js";
 import { type ImplicitFieldSchema } from "../fieldSchema.js";
 import type { SchemaCompatibilityStatus } from "./tree.js";

package/dist/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,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAQ1D,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,CAUlD"}
+{"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,EAAsB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAQ9E,OAAO,EAAS,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACjE,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/dist/simple-tree/api/storedSchema.js

@@ -5,9 +5,11 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.comparePersistedSchema = exports.extractPersistedSchema = void 0;
-const index_js_1 = require("../../core/index.js");
-const index_js_2 = require("../../feature-libraries/index.js");
-const index_js_3 = require("../../feature-libraries/schema-index/index.js");
+const index_js_1 = require("../../codec/index.js");
+const index_js_2 = require("../../core/index.js");
+const index_js_3 = require("../../feature-libraries/index.js");
+const index_js_4 = require("../../feature-libraries/schema-index/index.js");
+const index_js_5 = require("../../util/index.js");
 const fieldSchema_js_1 = require("../fieldSchema.js");
 const toStoredSchema_js_1 = require("../toStoredSchema.js");
 const configuration_js_1 = require("./configuration.js");
@@ -46,8 +48,8 @@ const schemaCompatibilityTester_js_1 = require("./schemaCompatibilityTester.js")
  */
 function extractPersistedSchema(schema, minVersionForCollab, includeStaged) {
     const stored = (0, toStoredSchema_js_1.toStoredSchema)(schema, { includeStaged });
-    const schemaWriteVersion = (0, index_js_3.clientVersionToSchemaVersion)(minVersionForCollab);
-    return (0, index_js_2.encodeTreeSchema)(stored, schemaWriteVersion);
+    const schemaWriteVersion = (0, index_js_4.clientVersionToSchemaVersion)(minVersionForCollab);
+    return (0, index_js_3.encodeTreeSchema)(stored, schemaWriteVersion);
 }
 exports.extractPersistedSchema = extractPersistedSchema;
 /**
@@ -83,7 +85,7 @@ exports.extractPersistedSchema = extractPersistedSchema;
 function comparePersistedSchema(persisted, view, options) {
     // Any version can be passed down to makeSchemaCodec here.
     // 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`.
-    const schemaCodec = (0, index_js_2.makeSchemaCodec)(options, index_js_1.SchemaVersion.v1);
+    const schemaCodec = (0, index_js_3.makeSchemaCodec)({ ...options, minVersionForCollab: index_js_1.FluidClientVersion.v2_0 }, (0, index_js_5.brand)(index_js_2.SchemaFormatVersion.v1));
     const stored = schemaCodec.decode(persisted);
     const config = new configuration_js_1.TreeViewConfigurationAlpha({
         schema: (0, fieldSchema_js_1.normalizeFieldSchema)(view),