npm - @fluidframework/tree - Versions diffs - 2.103.0 → 2.111.0 - Mend

@fluidframework/tree 2.103.0 → 2.111.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (530) hide show

package/lib/simple-tree/api/schemaFactory.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"schemaFactory.js","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaFactory.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, debugAssert, unreachableCase } from \"@fluidframework/core-utils/internal\";\nimport type { IIdCompressor } from \"@fluidframework/id-compressor\";\nimport { createIdCompressor } from \"@fluidframework/id-compressor/internal\";\nimport { isFluidHandle } from \"@fluidframework/runtime-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport type { TreeValue } from \"../../core/index.js\";\nimport type { FlexTreeHydratedContextMinimal } from \"../../feature-libraries/index.js\";\nimport {\n\ttype JsonCompatibleReadOnlyObject,\n\ttype RestrictiveStringRecord,\n\tcompareSets,\n\tgetOrCreate,\n\tisReadonlyArray,\n} from \"../../util/index.js\";\nimport { normalizeAllowedTypes, markSchemaMostDerived, isLazy } from \"../core/index.js\";\nimport type {\n\tNodeKind,\n\tWithType,\n\tTreeNodeSchema,\n\tTreeNodeSchemaClass,\n\tTreeNodeSchemaNonClass,\n\tTreeNodeSchemaBoth,\n\tUnhydratedFlexTreeNode,\n\tNodeSchemaMetadata,\n\tImplicitAllowedTypes,\n\tInsertableTreeNodeFromImplicitAllowedTypes,\n} from \"../core/index.js\";\nimport {\n\tFieldKind,\n\ttype FieldSchema,\n\ttype ImplicitFieldSchema,\n\t// This import prevents a large number of FieldProps references in the API reports from showing up as FieldProps_2.\n\t// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars\n\ttype FieldProps,\n\tcreateFieldSchema,\n\ttype DefaultProvider,\n\tgetDefaultProvider,\n} from \"../fieldSchema.js\";\nimport {\n\tbooleanSchema,\n\thandleSchema,\n\tnullSchema,\n\tnumberSchema,\n\tstringSchema,\n\t// This import prevents a large number of LeafSchema references in the API reports from showing up as LeafSchema_2.\n\t// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars\n\ttype LeafSchema,\n} from \"../leafNodeSchema.js\";\nimport {\n\tarraySchema,\n\ttype MapNodeInsertableData,\n\tmapSchema,\n\tobjectSchema,\n\ttype TreeArrayNode,\n\ttype InsertableObjectFromSchemaRecord,\n\ttype TreeMapNode,\n\ttype TreeObjectNode,\n} from \"../node-kinds/index.js\";\nimport { unhydratedFlexTreeFromInsertable } from \"../unhydratedFlexTreeFromInsertable.js\";\n\nimport { type SchemaStatics, schemaStatics } from \"./schemaStatics.js\";\nimport type { System_Unsafe } from \"./typesUnsafe.js\";\n\n/\n Gets the leaf domain schema compatible with a given {@link TreeValue}.\n /\nexport function schemaFromValue(value: TreeValue): TreeNodeSchema {\n\tswitch (typeof value) {\n\t\tcase \"boolean\": {\n\t\t\treturn booleanSchema;\n\t\t}\n\t\tcase \"number\": {\n\t\t\treturn numberSchema;\n\t\t}\n\t\tcase \"string\": {\n\t\t\treturn stringSchema;\n\t\t}\n\t\tcase \"object\": {\n\t\t\tif (value === null) {\n\t\t\t\treturn nullSchema;\n\t\t\t}\n\t\t\tassert(isFluidHandle(value), 0x87e / invalid TreeValue /);\n\t\t\treturn handleSchema;\n\t\t}\n\t\tdefault: {\n\t\t\tunreachableCase(value);\n\t\t}\n\t}\n}\n\n/\n Options when declaring an {@link SchemaFactory.object\|object node}'s schema.\n \n @input\n * @beta\n /\nexport interface ObjectSchemaOptions<TCustomMetadata = unknown>\n\textends NodeSchemaOptions<TCustomMetadata> {\n\t/\n\t Allow nodes typed with this object node schema to contain optional fields that are not present in the schema declaration.\n\t * Such nodes can come into existence either via import APIs (see remarks) or by way of collaboration with another client\n\t * that has upgraded the document's schema to include those optional fields.\n\t \n\t @defaultValue `false`\n\t * @remarks\n\t * The advantage of enabling this option is that it allows an application ecosystem with staged rollout to more quickly\n\t * upgrade documents to include schema for new optional features.\n\t \n\t However, it does come with trade-offs that applications should weigh carefully when it comes to interactions between\n\t * code and documents.\n\t * When opening such documents, the API presented is still determined by the view schema.\n\t * This can have implications on the behavior of edits or code which uses portions of the view schema,\n\t * since this may inadvertently drop data which is present in those optional fields in the document schema.\n\t \n\t Consider the following example:\n\t \n\t ```typescript\n\t * const sf = new SchemaFactory(\"com.example\");\n\t * class PersonView extends sf.object(\"Person\", { name: sf.string }, { allowUnknownOptionalFields: true }) {}\n\t * class PersonStored extends sf.object(\"Person\", { name: sf.string, nickname: sf.optional(sf.string) }) {}\n\t \n\t // Say we have a document which uses `PersonStored` in its schema, and application code constructs\n\t * // a tree view using `PersonView`. If the application for some reason had implemented a function like this:\n\t * function clonePerson(a: PersonView): PersonView {\n\t * \treturn new PersonView({ name: a.name });\n\t * }\n\t * // ...or even like this:\n\t * function clonePerson(a: PersonView): PersonView {\n\t * return new PersonView({ ...a})\n\t * }\n\t * // Then the alleged clone wouldn't actually clone the entire person in either case, it would drop the nickname.\n\t * ```\n\t \n\t The existing import and export APIs have similar problems.\n\t * For example currently the {@link (TreeAlpha:interface).exportVerbose\|exportVerbose} API with stored keys preserves unknown optional fields,\n\t * but {@link Unhydrated} nodes produced by {@link TreeNode} constructors, insertable content, and {@link (TreeAlpha:interface).importVerbose\|importVerbose} do not.\n\t * {@link (TreeBeta:interface).clone} however can be used to clone a node preserving unknown optional fields.\n\t \n\t Note that public API methods which operate on entire nodes (such as `moveTo`, `moveToEnd`, etc. on arrays) do not encounter\n\t * this problem as SharedTree's implementation stores the entire node in its lower layers.\n\t * It's only when application code reaches into a node\n\t * (either by accessing its fields, spreading it, or some other means) that this problem arises.\n\t /\n\treadonly allowUnknownOptionalFields?: boolean;\n}\n\n/\n Options when declaring an {@link SchemaFactory.object\|object node}'s schema\n \n @input\n * @alpha\n /\nexport interface ObjectSchemaOptionsAlpha<TCustomMetadata = unknown>\n\textends ObjectSchemaOptions<TCustomMetadata>,\n\t\tNodeSchemaOptionsAlpha<TCustomMetadata> {}\n\n/\n Default options for Object node schema creation.\n * @remarks Omits parameters that are not relevant for common use cases.\n /\nexport const defaultSchemaFactoryObjectOptions: Required<\n\tPick<ObjectSchemaOptions, \"allowUnknownOptionalFields\">\n> = {\n\tallowUnknownOptionalFields: false,\n};\n\n/\n The name of a schema produced by {@link SchemaFactory}, including its optional scope prefix.\n \n @system @public\n /\nexport type ScopedSchemaName<\n\tTScope extends string \| undefined,\n\tTName extends number \| string,\n> = TScope extends undefined ? `${TName}` : `${TScope}.${TName}`;\n// > = `${TScope extends undefined ? \"\" : `${TScope}.`}${TName}`;\n\nconst schemaStaticsPublic: SchemaStatics = schemaStatics;\n\n/\n Create a class with `Statics` as both static properties and member properties.\n * @privateRemarks\n * An attempt was made to let this take in a base class so it could be used again on SchemaFactoryAlpha.\n * This was unsuccessful, mostly due to issues with trying to manipulate constructor types.\n /\nfunction classWithStatics<Statics extends object>(\n\tstatics: Statics,\n): Statics & (new () => Statics) {\n\t// eslint-disable-next-line @typescript-eslint/no-extraneous-class\n\tclass WithStatics {}\n\n\tObject.assign(WithStatics.prototype, statics);\n\tObject.assign(WithStatics, statics);\n\treturn WithStatics as Statics & (new () => Statics);\n}\n\n/\n Base class for SchemaFactory, exposes {@link SchemaStatics} as both static properties and member properties.\n * @remarks\n * Do not use this directly, use {@link SchemaFactory} instead.\n * @privateRemarks\n * Exported only as a workaround for {@link https://github.com/microsoft/TypeScript/issues/59550} and {@link https://github.com/microsoft/rushstack/issues/4429}.\n * @system @public\n /\nexport const SchemaFactory_base = classWithStatics(schemaStaticsPublic);\n\n// TODO:\n// SchemaFactory.array references should link to the correct overloads, however the syntax for this does not seems to work currently for methods unless the they are not qualified with the class.\n// API-Extractor requires such links to be qualified with the class, so it can't work.\n// Since linking the overload set as a whole also doesn't work, these have been made non-links for now.\n/\n Creates various types of {@link TreeNodeSchema\|schema} for {@link TreeNode}s.\n \n @typeParam TScope - Scope added as a prefix to the name of every schema produced by this factory.\n * @typeParam TName - Type of names used to identify each schema produced in this factory.\n * Typically this is just `string` but it is also possible to use `string` or `number` based enums if you prefer to identify your types that way.\n \n @remarks\n * For details related to inputting data constrained by schema (including via assignment), and how non-exact schema types are handled in general refer to {@link Input}.\n * For information about recursive schema support, see methods postfixed with \"recursive\" and {@link ValidateRecursiveSchema}.\n * To apply schema defined with this factory to a tree, see {@link TreeViewConfiguration} and {@link ViewableTree.viewWith}.\n * See the {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution \| documentation on schema evolution} for how to handle changes to schema over time.\n \n All schema produced by this factory get a {@link TreeNodeSchemaCore.identifier\|unique identifier} by combining the {@link SchemaFactory.scope} with the schema's `Name`.\n * The `Name` part may be explicitly provided as a parameter, or inferred as a structural combination of the provided types.\n * The APIs which use this second approach, structural naming, also deduplicate all equivalent calls.\n * Therefore two calls to `array(allowedTypes)` with the same allowedTypes will return the same {@link TreeNodeSchema} instance.\n * On the other hand, two calls to `array(name, allowedTypes)` will always return different {@link TreeNodeSchema} instances\n * and it is an error to use both in the same tree (since their identifiers are not unique).\n \n For \"customizable\" schema (those which can be subclassed to customize them, see details below) some additional rules must be followed:\n \n 1. Only a single {@link TreeNodeSchema\|schema} can be used from the class hierarchy deriving from the base class produced by this factory.\n * It is legal to subclass the returned class, and even subclass that class,\n * but only a single class from that class hierarchy can ever be instantiated or passed to any API as a {@link TreeNodeSchema\|schema}.\n * These base classes can be used with `instanceof`, but not with schema based APIs like `Tree.is`.\n \n 2. If overriding the constructor, the constructor must accept the same argument as the base constructor `super` and forward it to `super` unchanged.\n \n 3. Properties for fields defined in the schema should not be overridden.\n \n 4. Additional static members added to schema should pick relatively unique keys to reduce the risk of colliding with implementation details what are not exposed in the API.\n \n 5. If exporting the schema from a package which uses API-Extractor, export the base class and derived class separately to work around {@link https://github.com/microsoft/rushstack/issues/4429 \| a known limitation}.\n \n Note:\n * POJO stands for Plain Old JavaScript Object.\n * This means an object that works like a `{}` style object literal.\n * In this case it means the prototype is `Object.prototype` and acts like a set of key value pairs (data, not methods).\n * The usage below generalizes this to include array and map like objects as well.\n \n There are two ways to use these APIs:\n \n Customizable Approach:\n \n 1. Declaration: `class X extends schemaFactory.object(\"x\", {}) {}`\n \n 2. Allows adding \"local\" (non-persisted) members: additional members (including methods) can be added to the class.\n \n 3. Prototype: The user-defined class.\n \n 4. Structurally named Schema: Not Supported.\n \n 5. Explicitly named Objects: Supported.\n \n 6. Explicitly named Maps and Arrays: Supported: Both declaration approaches can be used.\n \n 7. Node.js `assert.deepEqual`: Compares like class instances: equal to other nodes of the same type with the same content, including custom local fields.\n \n 8. IntelliSense: Shows and links to user-defined class by name: `X`.\n \n 9. Recursion: Supported with special declaration patterns.\n \n POJO Emulation Approach:\n \n 1. Declaration: `const X = schemaFactory.object(\"x\", {}); type X = NodeFromSchema<typeof X>;`\n \n 2. Does not allow adding \"local\" (non-persisted) members: attempting to set non-field members will result in an error.\n \n 3. Prototype: `Object.prototype`, `Map.prototype`, or `Array.prototype` depending on node kind.\n \n 4. Structurally named Schema: Supported.\n \n 5. Explicitly named Objects: Supported.\n \n 6. Explicitly named Maps and Arrays: Not Supported.\n \n 7. Node.js `assert.deepEqual`: Compares like plain objects: equal to plain JavaScript objects with the same fields, and other nodes with the same fields, even if the types are different.\n \n 8. IntelliSense: Shows internal type generation logic: `object & TreeNode & ObjectFromSchemaRecord<{}> & WithType<\"test.x\">`.\n \n 9. Recursion: Unsupported: {@link https://github.com/microsoft/TypeScript/issues/55832 \| Generated `.d.ts` files replace recursive references with `any`},\n * breaking the use of recursive schema across compilation boundaries.\n \n Note that while \"POJO Emulation\" nodes act a lot like POJO objects, they are not true POJO objects:\n \n - Adding new arbitrary fields will error, as well some cases of invalid edits.\n \n - They are implemented using proxies.\n \n - They have state that is not exposed via enumerable own properties, including a {@link TreeNodeSchema}.\n * This makes libraries like node.js `assert.deepEqual` fail to detect differences in type.\n \n - Assigning members has side effects (in this case editing the persisted/shared tree).\n \n - Not all operations implied by the prototype will work correctly: stick to the APIs explicitly declared in the TypeScript types.\n \n @privateRemarks\n * It's perfectly possible to make `POJO Emulation` mode (or even just hiding the prototype) selectable even when using the custom user class declaration syntax.\n * When doing this, it's still possible to make `instanceof` perform correctly.\n * Allowing (or banning) custom/out-of-schema properties on the class is also possible in both modes: it could be orthogonal.\n * Also for consistency, if keeping the current approach to detecting `POJO Emulation` mode it might make sense to make explicitly named Maps and Arrays do the detection the same as how object does it.\n \n Note: the comparison between the customizable and POJO modes is not done in a table because TSDoc does not currently have support for embedded markdown.\n \n @see {@link SchemaFactoryAlpha}\n * @see {@link SchemaFactoryBeta}\n * @sealed @public\n /\nexport class SchemaFactory<\n\tout TScope extends string \| undefined = string \| undefined,\n\tTName extends number \| string = string,\n> extends SchemaFactory_base {\n\t/\n\t TODO:\n\t * If users of this generate the same name because two different schema with the same identifier were used,\n\t * the second use can get a cache hit, and reference the wrong schema.\n\t * Such usage should probably return a distinct type or error but currently does not.\n\t * The use of markSchemaMostDerived in structuralName at least ensure an error in the case where the collision is from two types extending the same schema factor class.\n\t /\n\tprivate readonly structuralTypes: Map<string, TreeNodeSchema> = new Map();\n\n\t/\n\t Construct a SchemaFactory with a given {@link SchemaFactory.scope\|scope}.\n\t * @remarks\n\t * There are no restrictions on mixing schema from different schema factories.\n\t * Typically each library will create one or more SchemaFactories and use them to define its schema.\n\t /\n\tpublic constructor(\n\t\t/\n\t\t Prefix appended to the identifiers of all {@link TreeNodeSchema} produced by this builder.\n\t\t \n\t\t @remarks\n\t\t * Generally each independently developed library\n\t\t * (possibly a package, but could also be part of a package or multiple packages developed together)\n\t\t * should get its own unique `scope`.\n\t\t * Then each schema in the library get a name which is unique within the library.\n\t\t * The scope and name are joined (with a period) to form the {@link TreeNodeSchemaCore.identifier\|schema identifier}.\n\t\t * Following this pattern allows a single application to depend on multiple libraries which define their own schema, and use them together in a single tree without risk of collisions.\n\t\t * If a library logically contains sub-libraries with their own schema, they can be given a scope nested inside the parent scope, such as \"ParentScope.ChildScope\".\n\t\t \n\t\t To avoid collisions between the scopes of libraries\n\t\t * it is recommended that the libraries use {@link https://en.wikipedia.org/wiki/Reverse_domain_name_notation \| Reverse domain name notation} or a UUIDv4 for their scope.\n\t\t * If this pattern is followed, application can safely use third party libraries without risk of the schema in them colliding.\n\t\t \n\t\t You may opt out of using a scope by passing `undefined`, but note that this increases the risk of collisions.\n\t\t \n\t\t @example\n\t\t * Fluid Framework follows this pattern, placing the schema for the built in leaf types in the `com.fluidframework.leaf` scope.\n\t\t * If Fluid Framework publishes more schema in the future, they would be under some other `com.fluidframework` scope.\n\t\t * This ensures that any schema defined by any other library will not conflict with Fluid Framework's schema\n\t\t * as long as the library uses the recommended patterns for how to scope its schema..\n\t\t \n\t\t @example\n\t\t * A library could generate a random UUIDv4, like `242c4397-49ed-47e6-8dd0-d5c3bc31778b` and use that as the scope.\n\t\t * Note: do not use this UUID: a new one must be randomly generated when needed to ensure collision resistance.\n\t\t * ```typescript\n\t\t * const factory = new SchemaFactory(\"242c4397-49ed-47e6-8dd0-d5c3bc31778b\");\n\t\t * ```\n\t\t /\n\t\tpublic readonly scope: TScope,\n\t) {\n\t\tsuper();\n\t}\n\n\t/\n\t Define a {@link TreeNodeSchemaClass} for a {@link TreeObjectNode}.\n\t \n\t @param name - Unique identifier for this schema within this factory's scope.\n\t * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.\n\t /\n\tpublic object<\n\t\tconst Name extends TName,\n\t\tconst T extends RestrictiveStringRecord<ImplicitFieldSchema>,\n\t>(\n\t\tname: Name,\n\t\tfields: T,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Object,\n\t\tTreeObjectNode<T, ScopedSchemaName<TScope, Name>>,\n\t\tobject & InsertableObjectFromSchemaRecord<T>,\n\t\ttrue,\n\t\tT\n\t> {\n\t\treturn objectSchema(scoped(this, name), fields, true, {\n\t\t\t...defaultSchemaFactoryObjectOptions,\n\t\t}) as TreeNodeSchemaClass<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tNodeKind.Object,\n\t\t\tTreeObjectNode<T, ScopedSchemaName<TScope, Name>>,\n\t\t\tobject & InsertableObjectFromSchemaRecord<T>,\n\t\t\ttrue,\n\t\t\tT\n\t\t>;\n\t}\n\n\t/\n\t Define a structurally typed {@link TreeNodeSchema} for a {@link TreeMapNode}.\n\t \n\t @param allowedTypes - The types that may appear as values in the map.\n\t \n\t @remarks\n\t * The unique identifier for this Map is defined as a function of the provided types.\n\t * It is still scoped to this SchemaBuilder, but multiple calls with the same arguments will return the same schema object, providing somewhat structural typing.\n\t * This does not support recursive types.\n\t \n\t If using these structurally named maps, other types in this schema builder should avoid names of the form `Map<${string}>`.\n\t \n\t @example\n\t * The returned schema should be used as a schema directly:\n\t * ```typescript\n\t * const MyMap = factory.map(factory.number);\n\t * type MyMap = NodeFromSchema<typeof MyMap>;\n\t * ```\n\t * Or inline:\n\t * ```typescript\n\t * factory.object(\"Foo\", {myMap: factory.map(factory.number)});\n\t * ```\n\t * @privateRemarks\n\t * See note on array.\n\t /\n\tpublic map<const T extends TreeNodeSchema \| readonly TreeNodeSchema[]>(\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaNonClass<\n\t\tScopedSchemaName<TScope, `Map<${string}>`>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>, NodeKind.Map>,\n\t\tMapNodeInsertableData<T>,\n\t\ttrue,\n\t\tT,\n\t\tundefined\n\t>;\n\n\t/\n\t Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.\n\t \n\t @param name - Unique identifier for this schema within this factory's scope.\n\t * @param allowedTypes - The types that may appear as values in the map.\n\t \n\t @example\n\t * ```typescript\n\t * class NamedMap extends factory.map(\"name\", factory.number) {}\n\t * ```\n\t /\n\tpublic map<Name extends TName, const T extends ImplicitAllowedTypes>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,\n\t\tMapNodeInsertableData<T>,\n\t\ttrue,\n\t\tT,\n\t\tundefined\n\t>;\n\n\t/\n\t {@link SchemaFactory.map} implementation.\n\t \n\t @privateRemarks\n\t * This should return `TreeNodeSchemaBoth`, however TypeScript gives an error if one of the overloads implicitly up-casts the return type of the implementation.\n\t * This seems like a TypeScript bug getting variance backwards for overload return types since it's erroring when the relation between the overload\n\t * and the implementation is type safe, and forcing an unsafe typing instead.\n\t /\n\tpublic map<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(\n\t\tnameOrAllowedTypes: TName \| ((T & TreeNodeSchema) \| readonly TreeNodeSchema[]),\n\t\tallowedTypes?: T,\n\t\toptions?: NodeSchemaOptions<TCustomMetadata>,\n\t): TreeNodeSchema<string, NodeKind.Map, TreeMapNode<T>, MapNodeInsertableData<T>, true, T> {\n\t\tif (allowedTypes === undefined) {\n\t\t\tconst types = nameOrAllowedTypes as (T & TreeNodeSchema) \| readonly TreeNodeSchema[];\n\t\t\tconst fullName = structuralName(\"Map\", types);\n\t\t\tdebugAssert(() => options === undefined \|\| \"No options for structural types\");\n\t\t\treturn this.getStructuralType(fullName, types, () =>\n\t\t\t\tthis.namedMap(fullName, nameOrAllowedTypes as T, false, true, {}),\n\t\t\t) as TreeNodeSchemaBoth<\n\t\t\t\tstring,\n\t\t\t\tNodeKind.Map,\n\t\t\t\tTreeMapNode<T>,\n\t\t\t\tMapNodeInsertableData<T>,\n\t\t\t\ttrue,\n\t\t\t\tT,\n\t\t\t\tundefined,\n\t\t\t\tTCustomMetadata\n\t\t\t>;\n\t\t}\n\t\t// To actually have type safety, assign to the type this method should return before implicitly up-casting when returning.\n\t\tconst out: TreeNodeSchemaBoth<\n\t\t\tstring,\n\t\t\tNodeKind.Map,\n\t\t\tTreeMapNode<T>,\n\t\t\tMapNodeInsertableData<T>,\n\t\t\ttrue,\n\t\t\tT,\n\t\t\tundefined,\n\t\t\tTCustomMetadata\n\t\t> = this.namedMap(nameOrAllowedTypes as TName, allowedTypes, true, true, options ?? {});\n\t\treturn out;\n\t}\n\n\t/\n\t Define a {@link TreeNodeSchema} for a {@link (TreeMapNode:interface)}.\n\t \n\t @param name - Unique identifier for this schema within this factory's scope.\n\t /\n\tprivate namedMap<\n\t\tName extends TName \| string,\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst ImplicitlyConstructable extends boolean,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t\tcustomizable: boolean,\n\t\timplicitlyConstructable: ImplicitlyConstructable,\n\t\toptions: NodeSchemaOptionsAlpha<TCustomMetadata>,\n\t): TreeNodeSchemaBoth<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,\n\t\tMapNodeInsertableData<T>,\n\t\tImplicitlyConstructable,\n\t\tT,\n\t\tundefined,\n\t\tTCustomMetadata\n\t> {\n\t\treturn mapSchema(\n\t\t\tscoped(this, name),\n\t\t\tallowedTypes,\n\t\t\timplicitlyConstructable,\n\t\t\t// The current policy is customizable nodes don't get fake prototypes.\n\t\t\t!customizable,\n\t\t\toptions ?? {},\n\t\t);\n\t}\n\n\t/\n\t Define a structurally typed {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.\n\t \n\t @param allowedTypes - The types that may appear in the array.\n\t \n\t @remarks\n\t * The identifier for this Array is defined as a function of the provided types.\n\t * It is still scoped to this SchemaFactory, but multiple calls with the same arguments will return the same schema object, providing somewhat structural typing.\n\t * This does not support recursive types.\n\t \n\t If using these structurally named arrays, other types in this schema builder should avoid names of the form `Array<${string}>`.\n\t \n\t @example\n\t * The returned schema should be used as a schema directly:\n\t * ```typescript\n\t * const MyArray = factory.array(factory.number);\n\t * type MyArray = NodeFromSchema<typeof MyArray>;\n\t * ```\n\t * Or inline:\n\t * ```typescript\n\t * factory.object(\"Foo\", {myArray: factory.array(factory.number)});\n\t * ```\n\t * @privateRemarks\n\t * The name produced at the type level here is not as specific as it could be, however doing type level sorting and escaping is a real mess.\n\t * There are cases where not having this full type provided will be less than ideal, since TypeScript's structural types will allow assignment between runtime incompatible types at compile time.\n\t * For example attempts to narrow unions of structural arrays by name won't work.\n\t * Planned future changes to move to a class based schema system as well as factor function based node construction should mostly avoid these issues,\n\t * though there may still be some problematic cases even after that work is done.\n\t \n\t The return value is a class, but its the type is intentionally not specific enough to indicate it is a class.\n\t * This prevents callers of this from sub-classing it, which is unlikely to work well (due to the ease of accidentally giving two different calls o this different subclasses)\n\t * when working with structural typing.\n\t \n\t {@label STRUCTURAL}\n\t /\n\tpublic array<const T extends TreeNodeSchema \| readonly TreeNodeSchema[]>(\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaNonClass<\n\t\tScopedSchemaName<TScope, `Array<${string}>`>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, `Array<${string}>`>, NodeKind.Array>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue,\n\t\tT,\n\t\tundefined\n\t>;\n\n\t/\n\t Define a {@link TreeNodeSchemaClass} for a {@link (TreeArrayNode:interface)}.\n\t \n\t @param name - Unique identifier for this schema within this factory's scope.\n\t * @param allowedTypes - The types that may appear in the array.\n\t \n\t @example\n\t * ```typescript\n\t * class NamedArray extends factory.array(\"name\", factory.number) {}\n\t * ```\n\t \n\t {@label NAMED}\n\t /\n\tpublic array<const Name extends TName, const T extends ImplicitAllowedTypes>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue,\n\t\tT,\n\t\tundefined\n\t>;\n\n\t/\n\t {@link SchemaFactory.array} implementation.\n\t \n\t @privateRemarks\n\t * This should return TreeNodeSchemaBoth: see note on \"map\" implementation for details.\n\t /\n\tpublic array<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(\n\t\tnameOrAllowedTypes: TName \| ((T & TreeNodeSchema) \| readonly TreeNodeSchema[]),\n\t\tallowedTypes?: T,\n\t\toptions?: NodeSchemaOptions<TCustomMetadata>,\n\t): TreeNodeSchema<\n\t\tScopedSchemaName<TScope, string>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue,\n\t\tT,\n\t\tTCustomMetadata\n\t> {\n\t\tif (allowedTypes === undefined) {\n\t\t\tconst types = nameOrAllowedTypes as (T & TreeNodeSchema) \| readonly TreeNodeSchema[];\n\t\t\tconst fullName = structuralName(\"Array\", types);\n\t\t\tdebugAssert(() => options === undefined \|\| \"No options for structural types\");\n\t\t\treturn this.getStructuralType(fullName, types, () =>\n\t\t\t\tthis.namedArray(fullName, nameOrAllowedTypes as T, false, true, {}),\n\t\t\t) as TreeNodeSchemaClass<\n\t\t\t\tScopedSchemaName<TScope, string>,\n\t\t\t\tNodeKind.Array,\n\t\t\t\tTreeArrayNode<T>,\n\t\t\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\t\ttrue,\n\t\t\t\tT,\n\t\t\t\tundefined,\n\t\t\t\tTCustomMetadata\n\t\t\t>;\n\t\t}\n\n\t\tconst out: TreeNodeSchemaBoth<\n\t\t\tScopedSchemaName<TScope, string>,\n\t\t\tNodeKind.Array,\n\t\t\tTreeArrayNode<T>,\n\t\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\ttrue,\n\t\t\tT,\n\t\t\tundefined,\n\t\t\tTCustomMetadata\n\t\t> = this.namedArray(nameOrAllowedTypes as TName, allowedTypes, true, true, options ?? {});\n\t\treturn out;\n\t}\n\n\t/\n\t Retrieves or creates a structural {@link TreeNodeSchema} with the specified name and types.\n\t \n\t @param fullName - The name for the structural schema.\n\t * @param types - The input schema(s) used to define the structural schema.\n\t * @param builder - A function that builds the schema if it does not already exist.\n\t * @returns The structural {@link TreeNodeSchema} associated with the given name and types.\n\t * @throws `UsageError` if a schema structurally named schema with the same name is cached in `structuralTypes` but had different input types.\n\t /\n\tprotected getStructuralType(\n\t\tfullName: string,\n\t\ttypes: TreeNodeSchema \| readonly TreeNodeSchema[],\n\t\tbuilder: () => TreeNodeSchema,\n\t): TreeNodeSchema {\n\t\tconst structural = getOrCreate(this.structuralTypes, fullName, builder);\n\t\tconst inputTypes = new Set(normalizeAllowedTypes(types));\n\t\tconst outputTypes = new Set(\n\t\t\tnormalizeAllowedTypes(structural.info as TreeNodeSchema \| readonly TreeNodeSchema[]),\n\t\t);\n\t\t// If our cached value had a different set of types then were requested, the user must have caused a collision.\n\t\tconst same = compareSets({ a: inputTypes, b: outputTypes });\n\t\tif (!same) {\n\t\t\tthrow new UsageError(\n\t\t\t\t`Structurally named schema collision: two schema named \"${fullName}\" were defined with different input schema.`,\n\t\t\t);\n\t\t}\n\t\treturn structural;\n\t}\n\n\t/\n\t Define a {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.\n\t \n\t @param name - Unique identifier for this schema within this factory's scope.\n\t \n\t @remarks\n\t * This is not intended to be used directly, use the overload of `array` which takes a name instead.\n\t * This is only public to work around a compiler limitation.\n\t /\n\tprivate namedArray<\n\t\tName extends TName \| string,\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst ImplicitlyConstructable extends boolean,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t\tcustomizable: boolean,\n\t\timplicitlyConstructable: ImplicitlyConstructable,\n\t\toptions: NodeSchemaOptionsAlpha<TCustomMetadata>,\n\t): TreeNodeSchemaBoth<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, string>, NodeKind.Array>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\tImplicitlyConstructable,\n\t\tT,\n\t\tundefined,\n\t\tTCustomMetadata\n\t> {\n\t\treturn arraySchema(\n\t\t\tscoped(this, name),\n\t\t\tallowedTypes,\n\t\t\timplicitlyConstructable,\n\t\t\tcustomizable,\n\t\t\toptions,\n\t\t);\n\t}\n\n\t/\n\t A special readonly field which holds an identifier string for an object node.\n\t * @remarks\n\t * The value of this field, a \"node identifier\", is a string which identifies a node (or nodes) among all nodes in the tree.\n\t * Node identifiers are strings, and can therefore be used as lookup keys in maps or written to a database.\n\t * When the node is constructed, the identifier field does not need to be specified.\n\t * When an identifier is not provided, the SharedTree will generate an identifier for the node automatically.\n\t * The identifier generated by the SharedTree has the following properties:\n\t \n\t - It is a UUID which will not collide with other generated UUIDs.\n\t \n\t - It is compressed to a space-efficient representation when stored in the document.\n\t * Reading the identifier before inserting the node into a tree prevents the identifier from being stored in its compressed form,\n\t * resulting in a larger storage footprint.\n\t \n\t - A compressed form of the identifier can be accessed at runtime via the {@link TreeNodeApi.shortId\|Tree.shortId()} API.\n\t \n\t However, a user may alternatively supply their own string as the identifier if desired (for example, if importing identifiers from another system).\n\t * In that case, if the user requires it to be unique, it is up to them to ensure uniqueness.\n\t * User-supplied identifiers may be read immediately, even before insertion into the tree.\n\t \n\t A node may have more than one identifier field (though note that this precludes the use of the {@link TreeNodeApi.shortId\|Tree.shortId()} API).\n\t /\n\tpublic get identifier(): FieldSchema<FieldKind.Identifier, typeof this.string> {\n\t\tconst defaultIdentifierProvider: DefaultProvider = getDefaultProvider(\n\t\t\t(\n\t\t\t\tcontext: FlexTreeHydratedContextMinimal \| \"UseGlobalContext\",\n\t\t\t): UnhydratedFlexTreeNode[] => {\n\t\t\t\tconst id =\n\t\t\t\t\tcontext === \"UseGlobalContext\"\n\t\t\t\t\t\t? globalIdentifierAllocator.decompress(\n\t\t\t\t\t\t\t\tglobalIdentifierAllocator.generateCompressedId(),\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t: context.nodeKeyManager.stabilizeNodeIdentifier(\n\t\t\t\t\t\t\t\tcontext.nodeKeyManager.generateLocalNodeIdentifier(),\n\t\t\t\t\t\t\t);\n\n\t\t\t\treturn [unhydratedFlexTreeFromInsertable(id, this.string)];\n\t\t\t},\n\t\t);\n\t\treturn createFieldSchema(FieldKind.Identifier, this.string, {\n\t\t\tdefaultProvider: defaultIdentifierProvider,\n\t\t});\n\t}\n\n\t/\n\t {@link SchemaFactory.object} except tweaked to work better for recursive types.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * This version of {@link SchemaFactory.object} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t \n\t Additionally `ImplicitlyConstructable` is disabled (forcing use of constructor) to avoid\n\t * `error TS2589: Type instantiation is excessively deep and possibly infinite.`\n\t * which otherwise gets reported at sometimes incorrect source locations that vary based on incremental builds.\n\t /\n\tpublic objectRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>,\n\t>(\n\t\tname: Name,\n\t\tt: T,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Object,\n\t\tSystem_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,\n\t\tobject & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,\n\t\tfalse,\n\t\tT\n\t> {\n\t\ttype TScopedName = ScopedSchemaName<TScope, Name>;\n\t\treturn this.object(\n\t\t\tname,\n\t\t\tt as T & RestrictiveStringRecord<ImplicitFieldSchema>,\n\t\t) as unknown as TreeNodeSchemaClass<\n\t\t\tTScopedName,\n\t\t\tNodeKind.Object,\n\t\t\tSystem_Unsafe.TreeObjectNodeUnsafe<T, TScopedName>,\n\t\t\tobject & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,\n\t\t\tfalse,\n\t\t\tT\n\t\t>;\n\t}\n\n\t/\n\t `SchemaFactory.array` except tweaked to work better for recursive types.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * This version of `SchemaFactory.array` uses the same workarounds as {@link SchemaFactory.objectRecursive}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t * See also {@link FixRecursiveArraySchema} for additional information specific to recursive arrays schema exports.\n\t /\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic arrayRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t>(name: Name, allowedTypes: T) {\n\t\tconst RecursiveArray = this.namedArray(\n\t\t\tname,\n\t\t\tallowedTypes as T & ImplicitAllowedTypes,\n\t\t\ttrue,\n\t\t\tfalse,\n\t\t\t{},\n\t\t);\n\n\t\treturn RecursiveArray as TreeNodeSchemaClass<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tNodeKind.Array,\n\t\t\tSystem_Unsafe.TreeArrayNodeUnsafe<T> &\n\t\t\t\tWithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,\n\t\t\t{\n\t\t\t\t/\n\t\t\t\t Iterator for the iterable of content for this node.\n\t\t\t\t * @privateRemarks\n\t\t\t\t * Wrapping the constructor parameter for recursive arrays and maps in an inlined object type avoids (for unknown reasons)\n\t\t\t\t * the following compile error when declaring the recursive schema:\n\t\t\t\t * `Function implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.`\n\t\t\t\t * To benefit from this without impacting the API, the definition of `Iterable` has been inlined as such an object.\n\t\t\t\t \n\t\t\t\t If this workaround is kept, ideally this comment would be deduplicated with the other instance of it.\n\t\t\t\t * Unfortunately attempts to do this failed to avoid the compile error this was introduced to solve.\n\t\t\t\t /\n\t\t\t\t[Symbol.iterator](): Iterator<\n\t\t\t\t\tSystem_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>\n\t\t\t\t>;\n\t\t\t},\n\t\t\tfalse,\n\t\t\tT,\n\t\t\tundefined\n\t\t>;\n\t}\n\n\t/\n\t `SchemaFactory.map` except tweaked to work better for recursive types.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * This version of `SchemaFactory.map` uses the same workarounds as {@link SchemaFactory.objectRecursive}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t /\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic mapRecursive<\n\t\tName extends TName,\n\t\tconst T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t>(name: Name, allowedTypes: T) {\n\t\tconst MapSchema = this.namedMap(\n\t\t\tname,\n\t\t\tallowedTypes as T & ImplicitAllowedTypes,\n\t\t\ttrue,\n\t\t\t// Setting this (implicitlyConstructable) to true seems to work ok currently, but not for other node kinds.\n\t\t\t// Supporting this could be fragile and might break other future changes, so it's being kept as false for now.\n\t\t\tfalse,\n\t\t\t{},\n\t\t);\n\n\t\treturn MapSchema as TreeNodeSchemaClass<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tNodeKind.Map,\n\t\t\tSystem_Unsafe.TreeMapNodeUnsafe<T> &\n\t\t\t\tWithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,\n\t\t\t\| {\n\t\t\t\t\t/\n\t\t\t\t\t Iterator for the iterable of content for this node.\n\t\t\t\t\t * @privateRemarks\n\t\t\t\t\t * Wrapping the constructor parameter for recursive arrays and maps in an inlined object type avoids (for unknown reasons)\n\t\t\t\t\t * the following compile error when declaring the recursive schema:\n\t\t\t\t\t * `Function implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.`\n\t\t\t\t\t * To benefit from this without impacting the API, the definition of `Iterable` has been inlined as such an object.\n\t\t\t\t\t \n\t\t\t\t\t If this workaround is kept, ideally this comment would be deduplicated with the other instance of it.\n\t\t\t\t\t * Unfortunately attempts to do this failed to avoid the compile error this was introduced to solve.\n\t\t\t\t\t /\n\t\t\t\t\t[Symbol.iterator](): Iterator<\n\t\t\t\t\t\t[string, System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]\n\t\t\t\t\t>;\n\t\t\t }\n\t\t\t// Ideally this would be\n\t\t\t// RestrictiveStringRecord<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>,\n\t\t\t// but doing so breaks recursive types.\n\t\t\t// Instead we do a less nice version:\n\t\t\t\| {\n\t\t\t\t\treadonly [P in string]: System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;\n\t\t\t },\n\t\t\tfalse,\n\t\t\tT,\n\t\t\tundefined\n\t\t>;\n\t}\n}\n\nexport function structuralName<const T extends string>(\n\tcollectionName: T,\n\tallowedTypes: TreeNodeSchema \| readonly TreeNodeSchema[],\n): `${T}<${string}>` {\n\tlet inner: string;\n\tif (isReadonlyArray(allowedTypes)) {\n\t\tconst names = allowedTypes.map((t): string => {\n\t\t\t// Ensure that lazy types (functions) don't slip through here.\n\t\t\tassert(!isLazy(t), 0x83d / invalid type provided /);\n\t\t\tmarkSchemaMostDerived(t);\n\t\t\treturn t.identifier;\n\t\t});\n\t\t// Ensure name is order independent\n\t\tnames.sort();\n\t\t// Ensure name can't have collisions by quoting and escaping any quotes in the names of types.\n\t\t// Using JSON is a simple way to accomplish this.\n\t\t// The outer `[]` around the result were needed so that a single type name \"Any\" would not collide with the \"any\" case which used to exist.\n\t\tinner = JSON.stringify(names);\n\t} else {\n\t\treturn structuralName(collectionName, [allowedTypes]);\n\t}\n\treturn `${collectionName}<${inner}>`;\n}\n\nexport function scoped<\n\tTScope extends string \| undefined,\n\tTName extends number \| string,\n\tName extends TName \| string,\n>(factory: SchemaFactory<TScope, TName>, name: Name): ScopedSchemaName<TScope, Name> {\n\treturn (\n\t\tfactory.scope === undefined ? `${name}` : `${factory.scope}.${name}`\n\t) as ScopedSchemaName<TScope, Name>;\n}\n\n/\n Used to allocate default identifiers for unhydrated nodes when no context is available.\n * @remarks\n * The identifiers allocated by this will never be compressed to Short Ids.\n * Using this is only better than creating fully random V4 UUIDs because it reduces the entropy making it possible for things like text compression to work slightly better.\n /\nconst globalIdentifierAllocator: IIdCompressor = createIdCompressor();\n\n/\n Additional information to provide to Node Schema creation.\n \n @typeParam TCustomMetadata - Custom metadata properties to associate with the Node Schema.\n * See {@link NodeSchemaMetadata.custom}.\n \n @input\n * @public\n /\nexport interface NodeSchemaOptions<out TCustomMetadata = unknown> {\n\t/\n\t Optional metadata to associate with the Node Schema.\n\t \n\t @remarks\n\t * This specifies {@link SimpleNodeSchemaBase.metadata} which has more details about its use.\n\t /\n\treadonly metadata?: NodeSchemaMetadata<TCustomMetadata> \| undefined;\n}\n\n/\n Additional information to provide to Node Schema creation. Includes fields for alpha features.\n \n @typeParam TCustomMetadata - Custom metadata properties to associate with the Node Schema.\n * See {@link NodeSchemaMetadata.custom}.\n \n @input\n * @alpha\n /\nexport interface NodeSchemaOptionsAlpha<out TCustomMetadata = unknown>\n\textends NodeSchemaOptions<TCustomMetadata> {\n\t/\n\t The persisted metadata for this schema element.\n\t * @remarks\n\t * This gets exposed via {@link SimpleNodeSchemaBaseAlpha.persistedMetadata}.\n\t */\n\treadonly persistedMetadata?: JsonCompatibleReadOnlyObject \| undefined;\n}\n"]}
1	+ {"version":3,"file":"schemaFactory.js","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaFactory.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, debugAssert, unreachableCase } from \"@fluidframework/core-utils/internal\";\nimport type { IIdCompressor } from \"@fluidframework/id-compressor\";\nimport { createIdCompressor } from \"@fluidframework/id-compressor/internal\";\nimport { isFluidHandle } from \"@fluidframework/runtime-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport type { TreeValue } from \"../../core/index.js\";\nimport type { FlexTreeHydratedContextMinimal } from \"../../feature-libraries/index.js\";\nimport {\n\ttype JsonCompatibleReadOnlyObject,\n\ttype RestrictiveStringRecord,\n\tcompareSets,\n\tgetOrCreate,\n\tisReadonlyArray,\n} from \"../../util/index.js\";\nimport { normalizeAllowedTypes, markSchemaMostDerived, isLazy } from \"../core/index.js\";\nimport type {\n\tNodeKind,\n\tWithType,\n\tTreeNodeSchema,\n\tTreeNodeSchemaClass,\n\tTreeNodeSchemaNonClass,\n\tTreeNodeSchemaBoth,\n\tUnhydratedFlexTreeNode,\n\tNodeSchemaMetadata,\n\tImplicitAllowedTypes,\n\tInsertableTreeNodeFromImplicitAllowedTypes,\n} from \"../core/index.js\";\nimport {\n\tFieldKind,\n\ttype FieldSchema,\n\ttype ImplicitFieldSchema,\n\t// This import prevents a large number of FieldProps references in the API reports from showing up as FieldProps_2.\n\t// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars\n\ttype FieldProps,\n\tcreateFieldSchema,\n\ttype DefaultProvider,\n\tgetDefaultProvider,\n} from \"../fieldSchema.js\";\nimport {\n\tbooleanSchema,\n\thandleSchema,\n\tnullSchema,\n\tnumberSchema,\n\tstringSchema,\n\t// This import prevents a large number of LeafSchema references in the API reports from showing up as LeafSchema_2.\n\t// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars\n\ttype LeafSchema,\n} from \"../leafNodeSchema.js\";\nimport {\n\tarraySchema,\n\ttype MapNodeInsertableData,\n\tmapSchema,\n\tobjectSchema,\n\ttype TreeArrayNode,\n\ttype InsertableObjectFromSchemaRecord,\n\ttype TreeMapNode,\n\ttype TreeObjectNode,\n} from \"../node-kinds/index.js\";\nimport { unhydratedFlexTreeFromInsertable } from \"../unhydratedFlexTreeFromInsertable.js\";\n\nimport { type SchemaStatics, schemaStatics } from \"./schemaStatics.js\";\nimport type { System_Unsafe } from \"./typesUnsafe.js\";\n\n/\n Gets the leaf domain schema compatible with a given {@link TreeValue}.\n /\nexport function schemaFromValue(value: TreeValue): TreeNodeSchema {\n\tswitch (typeof value) {\n\t\tcase \"boolean\": {\n\t\t\treturn booleanSchema;\n\t\t}\n\t\tcase \"number\": {\n\t\t\treturn numberSchema;\n\t\t}\n\t\tcase \"string\": {\n\t\t\treturn stringSchema;\n\t\t}\n\t\tcase \"object\": {\n\t\t\tif (value === null) {\n\t\t\t\treturn nullSchema;\n\t\t\t}\n\t\t\tassert(isFluidHandle(value), 0x87e / invalid TreeValue /);\n\t\t\treturn handleSchema;\n\t\t}\n\t\tdefault: {\n\t\t\tunreachableCase(value);\n\t\t}\n\t}\n}\n\n/\n Options when declaring an {@link SchemaFactory.object\|object node}'s schema.\n \n @input\n * @beta\n /\nexport interface ObjectSchemaOptions<TCustomMetadata = unknown>\n\textends NodeSchemaOptions<TCustomMetadata> {\n\t/\n\t Allow nodes typed with this object node schema to contain optional fields that are not present in the schema declaration.\n\t * Such nodes can come into existence either via import APIs (see remarks) or by way of collaboration with another client\n\t * that has upgraded the document's schema to include those optional fields.\n\t \n\t @defaultValue `false`\n\t * @remarks\n\t * The advantage of enabling this option is that it allows an application ecosystem with staged rollout to more quickly\n\t * upgrade documents to include schema for new optional features.\n\t \n\t However, it does come with trade-offs that applications should weigh carefully when it comes to interactions between\n\t * code and documents.\n\t * When opening such documents, the API presented is still determined by the view schema.\n\t * This can have implications on the behavior of edits or code which uses portions of the view schema,\n\t * since this may inadvertently drop data which is present in those optional fields in the document schema.\n\t \n\t Consider the following example:\n\t \n\t ```typescript\n\t * const sf = new SchemaFactory(\"com.example\");\n\t * class PersonView extends sf.object(\"Person\", { name: sf.string }, { allowUnknownOptionalFields: true }) {}\n\t * class PersonStored extends sf.object(\"Person\", { name: sf.string, nickname: sf.optional(sf.string) }) {}\n\t \n\t // Say we have a document which uses `PersonStored` in its schema, and application code constructs\n\t * // a tree view using `PersonView`. If the application for some reason had implemented a function like this:\n\t * function clonePerson(a: PersonView): PersonView {\n\t * \treturn new PersonView({ name: a.name });\n\t * }\n\t * // ...or even like this:\n\t * function clonePerson(a: PersonView): PersonView {\n\t * return new PersonView({ ...a})\n\t * }\n\t * // Then the alleged clone wouldn't actually clone the entire person in either case, it would drop the nickname.\n\t * ```\n\t \n\t The existing import and export APIs have similar problems.\n\t * For example currently the {@link (TreeAlpha:interface).exportVerbose\|exportVerbose} API with stored keys preserves unknown optional fields,\n\t * but {@link Unhydrated} nodes produced by {@link TreeNode} constructors, insertable content, and {@link (TreeAlpha:interface).importVerbose\|importVerbose} do not.\n\t * {@link (TreeBeta:interface).clone} however can be used to clone a node preserving unknown optional fields.\n\t \n\t Note that public API methods which operate on entire nodes (such as `moveTo`, `moveToEnd`, etc. on arrays) do not encounter\n\t * this problem as SharedTree's implementation stores the entire node in its lower layers.\n\t * It's only when application code reaches into a node\n\t * (either by accessing its fields, spreading it, or some other means) that this problem arises.\n\t /\n\treadonly allowUnknownOptionalFields?: boolean;\n}\n\n/\n Options when declaring an {@link SchemaFactory.object\|object node}'s schema\n \n @input\n * @alpha\n /\nexport interface ObjectSchemaOptionsAlpha<TCustomMetadata = unknown>\n\textends ObjectSchemaOptions<TCustomMetadata>,\n\t\tNodeSchemaOptionsAlpha<TCustomMetadata> {}\n\n/\n Default options for Object node schema creation.\n * @remarks Omits parameters that are not relevant for common use cases.\n /\nexport const defaultSchemaFactoryObjectOptions: Required<\n\tPick<ObjectSchemaOptions, \"allowUnknownOptionalFields\">\n> = {\n\tallowUnknownOptionalFields: false,\n};\n\n/\n The name of a schema produced by {@link SchemaFactory}, including its optional scope prefix.\n \n @system @public\n /\nexport type ScopedSchemaName<\n\tTScope extends string \| undefined,\n\tTName extends number \| string,\n> = TScope extends undefined ? `${TName}` : `${TScope}.${TName}`;\n// > = `${TScope extends undefined ? \"\" : `${TScope}.`}${TName}`;\n\nconst schemaStaticsPublic: SchemaStatics = schemaStatics;\n\n/\n Create a class with `Statics` as both static properties and member properties.\n * @privateRemarks\n * An attempt was made to let this take in a base class so it could be used again on SchemaFactoryAlpha.\n * This was unsuccessful, mostly due to issues with trying to manipulate constructor types.\n /\nfunction classWithStatics<Statics extends object>(\n\tstatics: Statics,\n): Statics & (new () => Statics) {\n\t// eslint-disable-next-line @typescript-eslint/no-extraneous-class\n\tclass WithStatics {}\n\n\tObject.assign(WithStatics.prototype, statics);\n\tObject.assign(WithStatics, statics);\n\treturn WithStatics as Statics & (new () => Statics);\n}\n\n/\n Base class for SchemaFactory, exposes {@link SchemaStatics} as both static properties and member properties.\n * @remarks\n * Do not use this directly, use {@link SchemaFactory} instead.\n * @privateRemarks\n * Exported only as a workaround for {@link https://github.com/microsoft/TypeScript/issues/59550} and {@link https://github.com/microsoft/rushstack/issues/4429}.\n * @system @public\n /\nexport const SchemaFactory_base = classWithStatics(schemaStaticsPublic);\n\n// TODO:\n// SchemaFactory.array references should link to the correct overloads, however the syntax for this does not seems to work currently for methods unless the they are not qualified with the class.\n// API-Extractor requires such links to be qualified with the class, so it can't work.\n// Since linking the overload set as a whole also doesn't work, these have been made non-links for now.\n/\n Creates various types of {@link TreeNodeSchema\|schema} for {@link TreeNode}s.\n \n @typeParam TScope - Scope added as a prefix to the name of every schema produced by this factory.\n * @typeParam TName - Type of names used to identify each schema produced in this factory.\n * Typically this is just `string` but it is also possible to use `string` or `number` based enums if you prefer to identify your types that way.\n \n @remarks\n * For details related to inputting data constrained by schema (including via assignment), and how non-exact schema types are handled in general refer to {@link Input}.\n * For information about recursive schema support, see methods postfixed with \"recursive\" and {@link ValidateRecursiveSchema}.\n * To apply schema defined with this factory to a tree, see {@link TreeViewConfiguration} and {@link ViewableTree.viewWith}.\n * See the {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution \| documentation on schema evolution} for how to handle changes to schema over time.\n \n All schema produced by this factory get a {@link TreeNodeSchemaCore.identifier\|unique identifier} by combining the {@link SchemaFactory.scope} with the schema's `Name`.\n * The `Name` part may be explicitly provided as a parameter, or inferred as a structural combination of the provided types.\n * The APIs which use this second approach, structural naming, also deduplicate all equivalent calls.\n * Therefore two calls to `array(allowedTypes)` with the same allowedTypes will return the same {@link TreeNodeSchema} instance.\n * On the other hand, two calls to `array(name, allowedTypes)` will always return different {@link TreeNodeSchema} instances\n * and it is an error to use both in the same tree (since their identifiers are not unique).\n \n For \"customizable\" schema (those which can be subclassed to customize them, see details below) some additional rules must be followed:\n \n 1. Only a single {@link TreeNodeSchema\|schema} can be used from the class hierarchy deriving from the base class produced by this factory.\n * It is legal to subclass the returned class, and even subclass that class,\n * but only a single class from that class hierarchy can ever be instantiated or passed to any API as a {@link TreeNodeSchema\|schema}.\n * These base classes can be used with `instanceof`, but not with schema based APIs like `Tree.is`.\n \n 2. If overriding the constructor, the constructor must accept the same argument as the base constructor `super` and forward it to `super` unchanged.\n \n 3. Properties for fields defined in the schema should not be overridden.\n \n 4. Additional static members added to schema should pick relatively unique keys to reduce the risk of colliding with implementation details what are not exposed in the API.\n \n 5. If exporting the schema from a package which uses API-Extractor, export the base class and derived class separately to work around {@link https://github.com/microsoft/rushstack/issues/4429 \| a known limitation}.\n \n Note:\n * POJO stands for Plain Old JavaScript Object.\n * This means an object that works like a `{}` style object literal.\n * In this case it means the prototype is `Object.prototype` and acts like a set of key value pairs (data, not methods).\n * The usage below generalizes this to include array and map like objects as well.\n \n There are two ways to use these APIs:\n \n Customizable Approach:\n \n 1. Declaration: `class X extends schemaFactory.object(\"x\", {}) {}`\n \n 2. Allows adding \"local\" (non-persisted) members: additional members (including methods) can be added to the class.\n \n 3. Prototype: The user-defined class.\n \n 4. Structurally named Schema: Not Supported.\n \n 5. Explicitly named Objects: Supported.\n \n 6. Explicitly named Maps and Arrays: Supported: Both declaration approaches can be used.\n \n 7. Node.js `assert.deepEqual`: Compares like class instances: equal to other nodes of the same type with the same content, including custom local fields.\n \n 8. IntelliSense: Shows and links to user-defined class by name: `X`.\n \n 9. Recursion: Supported with special declaration patterns.\n \n POJO Emulation Approach:\n \n 1. Declaration: `const X = schemaFactory.object(\"x\", {}); type X = NodeFromSchema<typeof X>;`\n \n 2. Does not allow adding \"local\" (non-persisted) members: attempting to set non-field members will result in an error.\n \n 3. Prototype: `Object.prototype`, `Map.prototype`, or `Array.prototype` depending on node kind.\n \n 4. Structurally named Schema: Supported.\n \n 5. Explicitly named Objects: Supported.\n \n 6. Explicitly named Maps and Arrays: Not Supported.\n \n 7. Node.js `assert.deepEqual`: Compares like plain objects: equal to plain JavaScript objects with the same fields, and other nodes with the same fields, even if the types are different.\n \n 8. IntelliSense: Shows internal type generation logic: `object & TreeNode & ObjectFromSchemaRecord<{}> & WithType<\"test.x\">`.\n \n 9. Recursion: Unsupported: {@link https://github.com/microsoft/TypeScript/issues/55832 \| Generated `.d.ts` files replace recursive references with `any`},\n * breaking the use of recursive schema across compilation boundaries.\n \n Note that while \"POJO Emulation\" nodes act a lot like POJO objects, they are not true POJO objects:\n \n - Adding new arbitrary fields will error, as well some cases of invalid edits.\n \n - They are implemented using proxies.\n \n - They have state that is not exposed via enumerable own properties, including a {@link TreeNodeSchema}.\n * This makes libraries like node.js `assert.deepEqual` fail to detect differences in type.\n \n - Assigning members has side effects (in this case editing the persisted/shared tree).\n \n - Not all operations implied by the prototype will work correctly: stick to the APIs explicitly declared in the TypeScript types.\n \n @privateRemarks\n * It's perfectly possible to make `POJO Emulation` mode (or even just hiding the prototype) selectable even when using the custom user class declaration syntax.\n * When doing this, it's still possible to make `instanceof` perform correctly.\n * Allowing (or banning) custom/out-of-schema properties on the class is also possible in both modes: it could be orthogonal.\n * Also for consistency, if keeping the current approach to detecting `POJO Emulation` mode it might make sense to make explicitly named Maps and Arrays do the detection the same as how object does it.\n \n Note: the comparison between the customizable and POJO modes is not done in a table because TSDoc does not currently have support for embedded markdown.\n \n @see {@link SchemaFactoryAlpha}\n * @see {@link SchemaFactoryBeta}\n * @sealed @public\n /\nexport class SchemaFactory<\n\tout TScope extends string \| undefined = string \| undefined,\n\tTName extends number \| string = string,\n> extends SchemaFactory_base {\n\t/\n\t TODO:\n\t * If users of this generate the same name because two different schema with the same identifier were used,\n\t * the second use can get a cache hit, and reference the wrong schema.\n\t * Such usage should probably return a distinct type or error but currently does not.\n\t * The use of markSchemaMostDerived in structuralName at least ensure an error in the case where the collision is from two types extending the same schema factor class.\n\t /\n\tprivate readonly structuralTypes: Map<string, TreeNodeSchema> = new Map();\n\n\t/\n\t Construct a SchemaFactory with a given {@link SchemaFactory.scope\|scope}.\n\t * @remarks\n\t * There are no restrictions on mixing schemas from different schema factories.\n\t * Typically each library will create one or more SchemaFactories and use them to define its schema.\n\t /\n\tpublic constructor(\n\t\t/\n\t\t Prefix appended to the identifiers of all {@link TreeNodeSchema} produced by this builder.\n\t\t \n\t\t @remarks\n\t\t * Generally each independently developed library\n\t\t * (possibly a package, but could also be part of a package or multiple packages developed together)\n\t\t * should get its own unique `scope`.\n\t\t * Then each schema in the library get a name which is unique within the library.\n\t\t * The scope and name are joined (with a period) to form the {@link TreeNodeSchemaCore.identifier\|schema identifier}.\n\t\t * Following this pattern allows a single application to depend on multiple libraries which define their own schema, and use them together in a single tree without risk of collisions.\n\t\t * If a library logically contains sub-libraries with their own schema, they can be given a scope nested inside the parent scope, such as \"ParentScope.ChildScope\".\n\t\t \n\t\t To avoid collisions between the scopes of libraries\n\t\t * it is recommended that the libraries use {@link https://en.wikipedia.org/wiki/Reverse_domain_name_notation \| Reverse domain name notation} or a UUIDv4 for their scope.\n\t\t * If this pattern is followed, application can safely use third party libraries without risk of the schema in them colliding.\n\t\t \n\t\t You may opt out of using a scope by passing `undefined`, but note that this increases the risk of collisions.\n\t\t \n\t\t @example\n\t\t * Fluid Framework follows this pattern, placing the schema for the built in leaf types in the `com.fluidframework.leaf` scope.\n\t\t * If Fluid Framework publishes more schema in the future, they would be under some other `com.fluidframework` scope.\n\t\t * This ensures that any schema defined by any other library will not conflict with Fluid Framework's schema\n\t\t * as long as the library uses the recommended patterns for how to scope its schema..\n\t\t \n\t\t @example\n\t\t * A library could generate a random UUIDv4, like `242c4397-49ed-47e6-8dd0-d5c3bc31778b` and use that as the scope.\n\t\t * Note: do not use this UUID: a new one must be randomly generated when needed to ensure collision resistance.\n\t\t * ```typescript\n\t\t * const factory = new SchemaFactory(\"242c4397-49ed-47e6-8dd0-d5c3bc31778b\");\n\t\t * ```\n\t\t /\n\t\tpublic readonly scope: TScope,\n\t) {\n\t\tsuper();\n\t}\n\n\t/\n\t Define a {@link TreeNodeSchemaClass} for a {@link TreeObjectNode}.\n\t \n\t @param name - Unique identifier for this schema within this factory's scope.\n\t * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.\n\t /\n\tpublic object<\n\t\tconst Name extends TName,\n\t\tconst T extends RestrictiveStringRecord<ImplicitFieldSchema>,\n\t>(\n\t\tname: Name,\n\t\tfields: T,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Object,\n\t\tTreeObjectNode<T, ScopedSchemaName<TScope, Name>>,\n\t\tobject & InsertableObjectFromSchemaRecord<T>,\n\t\ttrue,\n\t\tT\n\t> {\n\t\treturn objectSchema(scoped(this, name), fields, true, {\n\t\t\t...defaultSchemaFactoryObjectOptions,\n\t\t}) as TreeNodeSchemaClass<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tNodeKind.Object,\n\t\t\tTreeObjectNode<T, ScopedSchemaName<TScope, Name>>,\n\t\t\tobject & InsertableObjectFromSchemaRecord<T>,\n\t\t\ttrue,\n\t\t\tT\n\t\t>;\n\t}\n\n\t/\n\t Define a structurally typed {@link TreeNodeSchema} for a {@link TreeMapNode}.\n\t \n\t @param allowedTypes - The types that may appear as values in the map.\n\t \n\t @remarks\n\t * The unique identifier for this Map is defined as a function of the provided types.\n\t * It is still scoped to this SchemaBuilder, but multiple calls with the same arguments will return the same schema object, providing somewhat structural typing.\n\t * This does not support recursive types.\n\t \n\t If using these structurally named maps, other types in this schema builder should avoid names of the form `Map<${string}>`.\n\t \n\t @example\n\t * The returned schema should be used as a schema directly:\n\t * ```typescript\n\t * const MyMap = factory.map(factory.number);\n\t * type MyMap = NodeFromSchema<typeof MyMap>;\n\t * ```\n\t * Or inline:\n\t * ```typescript\n\t * factory.object(\"Foo\", {myMap: factory.map(factory.number)});\n\t * ```\n\t * @privateRemarks\n\t * See note on array.\n\t /\n\tpublic map<const T extends TreeNodeSchema \| readonly TreeNodeSchema[]>(\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaNonClass<\n\t\tScopedSchemaName<TScope, `Map<${string}>`>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>, NodeKind.Map>,\n\t\tMapNodeInsertableData<T>,\n\t\ttrue,\n\t\tT,\n\t\tundefined\n\t>;\n\n\t/\n\t Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.\n\t \n\t @param name - Unique identifier for this schema within this factory's scope.\n\t * @param allowedTypes - The types that may appear as values in the map.\n\t \n\t @example\n\t * ```typescript\n\t * class NamedMap extends factory.map(\"name\", factory.number) {}\n\t * ```\n\t /\n\tpublic map<Name extends TName, const T extends ImplicitAllowedTypes>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,\n\t\tMapNodeInsertableData<T>,\n\t\ttrue,\n\t\tT,\n\t\tundefined\n\t>;\n\n\t/\n\t {@link SchemaFactory.map} implementation.\n\t \n\t @privateRemarks\n\t * This should return `TreeNodeSchemaBoth`, however TypeScript gives an error if one of the overloads implicitly up-casts the return type of the implementation.\n\t * This seems like a TypeScript bug getting variance backwards for overload return types since it's erroring when the relation between the overload\n\t * and the implementation is type safe, and forcing an unsafe typing instead.\n\t /\n\tpublic map<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(\n\t\tnameOrAllowedTypes: TName \| ((T & TreeNodeSchema) \| readonly TreeNodeSchema[]),\n\t\tallowedTypes?: T,\n\t\toptions?: NodeSchemaOptions<TCustomMetadata>,\n\t): TreeNodeSchema<string, NodeKind.Map, TreeMapNode<T>, MapNodeInsertableData<T>, true, T> {\n\t\tif (allowedTypes === undefined) {\n\t\t\tconst types = nameOrAllowedTypes as (T & TreeNodeSchema) \| readonly TreeNodeSchema[];\n\t\t\tconst fullName = structuralName(\"Map\", types);\n\t\t\tdebugAssert(() => options === undefined \|\| \"No options for structural types\");\n\t\t\treturn this.getStructuralType(fullName, types, () =>\n\t\t\t\tthis.namedMap(fullName, nameOrAllowedTypes as T, false, true, {}),\n\t\t\t) as TreeNodeSchemaBoth<\n\t\t\t\tstring,\n\t\t\t\tNodeKind.Map,\n\t\t\t\tTreeMapNode<T>,\n\t\t\t\tMapNodeInsertableData<T>,\n\t\t\t\ttrue,\n\t\t\t\tT,\n\t\t\t\tundefined,\n\t\t\t\tTCustomMetadata\n\t\t\t>;\n\t\t}\n\t\t// To actually have type safety, assign to the type this method should return before implicitly up-casting when returning.\n\t\tconst out: TreeNodeSchemaBoth<\n\t\t\tstring,\n\t\t\tNodeKind.Map,\n\t\t\tTreeMapNode<T>,\n\t\t\tMapNodeInsertableData<T>,\n\t\t\ttrue,\n\t\t\tT,\n\t\t\tundefined,\n\t\t\tTCustomMetadata\n\t\t> = this.namedMap(nameOrAllowedTypes as TName, allowedTypes, true, true, options ?? {});\n\t\treturn out;\n\t}\n\n\t/\n\t Define a {@link TreeNodeSchema} for a {@link (TreeMapNode:interface)}.\n\t \n\t @param name - Unique identifier for this schema within this factory's scope.\n\t /\n\tprivate namedMap<\n\t\tName extends TName \| string,\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst ImplicitlyConstructable extends boolean,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t\tcustomizable: boolean,\n\t\timplicitlyConstructable: ImplicitlyConstructable,\n\t\toptions: NodeSchemaOptionsAlpha<TCustomMetadata>,\n\t): TreeNodeSchemaBoth<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,\n\t\tMapNodeInsertableData<T>,\n\t\tImplicitlyConstructable,\n\t\tT,\n\t\tundefined,\n\t\tTCustomMetadata\n\t> {\n\t\treturn mapSchema(\n\t\t\tscoped(this, name),\n\t\t\tallowedTypes,\n\t\t\timplicitlyConstructable,\n\t\t\t// The current policy is customizable nodes don't get fake prototypes.\n\t\t\t!customizable,\n\t\t\toptions ?? {},\n\t\t);\n\t}\n\n\t/\n\t Define a structurally typed {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.\n\t \n\t @param allowedTypes - The types that may appear in the array.\n\t \n\t @remarks\n\t * The identifier for this Array is defined as a function of the provided types.\n\t * It is still scoped to this SchemaFactory, but multiple calls with the same arguments will return the same schema object, providing somewhat structural typing.\n\t * This does not support recursive types.\n\t \n\t If using these structurally named arrays, other types in this schema builder should avoid names of the form `Array<${string}>`.\n\t \n\t @example\n\t * The returned schema should be used as a schema directly:\n\t * ```typescript\n\t * const MyArray = factory.array(factory.number);\n\t * type MyArray = NodeFromSchema<typeof MyArray>;\n\t * ```\n\t * Or inline:\n\t * ```typescript\n\t * factory.object(\"Foo\", {myArray: factory.array(factory.number)});\n\t * ```\n\t * @privateRemarks\n\t * The name produced at the type level here is not as specific as it could be, however doing type level sorting and escaping is a real mess.\n\t * There are cases where not having this full type provided will be less than ideal, since TypeScript's structural types will allow assignment between runtime incompatible types at compile time.\n\t * For example attempts to narrow unions of structural arrays by name won't work.\n\t * Planned future changes to move to a class based schema system as well as factor function based node construction should mostly avoid these issues,\n\t * though there may still be some problematic cases even after that work is done.\n\t \n\t The return value is a class, but its the type is intentionally not specific enough to indicate it is a class.\n\t * This prevents callers of this from sub-classing it, which is unlikely to work well (due to the ease of accidentally giving two different calls o this different subclasses)\n\t * when working with structural typing.\n\t \n\t {@label STRUCTURAL}\n\t /\n\tpublic array<const T extends TreeNodeSchema \| readonly TreeNodeSchema[]>(\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaNonClass<\n\t\tScopedSchemaName<TScope, `Array<${string}>`>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, `Array<${string}>`>, NodeKind.Array>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue,\n\t\tT,\n\t\tundefined\n\t>;\n\n\t/\n\t Define a {@link TreeNodeSchemaClass} for a {@link (TreeArrayNode:interface)}.\n\t \n\t @param name - Unique identifier for this schema within this factory's scope.\n\t * @param allowedTypes - The types that may appear in the array.\n\t \n\t @example\n\t * ```typescript\n\t * class NamedArray extends factory.array(\"name\", factory.number) {}\n\t * ```\n\t \n\t {@label NAMED}\n\t /\n\tpublic array<const Name extends TName, const T extends ImplicitAllowedTypes>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue,\n\t\tT,\n\t\tundefined\n\t>;\n\n\t/\n\t {@link SchemaFactory.array} implementation.\n\t \n\t @privateRemarks\n\t * This should return TreeNodeSchemaBoth: see note on \"map\" implementation for details.\n\t /\n\tpublic array<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(\n\t\tnameOrAllowedTypes: TName \| ((T & TreeNodeSchema) \| readonly TreeNodeSchema[]),\n\t\tallowedTypes?: T,\n\t\toptions?: NodeSchemaOptions<TCustomMetadata>,\n\t): TreeNodeSchema<\n\t\tScopedSchemaName<TScope, string>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue,\n\t\tT,\n\t\tTCustomMetadata\n\t> {\n\t\tif (allowedTypes === undefined) {\n\t\t\tconst types = nameOrAllowedTypes as (T & TreeNodeSchema) \| readonly TreeNodeSchema[];\n\t\t\tconst fullName = structuralName(\"Array\", types);\n\t\t\tdebugAssert(() => options === undefined \|\| \"No options for structural types\");\n\t\t\treturn this.getStructuralType(fullName, types, () =>\n\t\t\t\tthis.namedArray(fullName, nameOrAllowedTypes as T, false, true, {}),\n\t\t\t) as TreeNodeSchemaClass<\n\t\t\t\tScopedSchemaName<TScope, string>,\n\t\t\t\tNodeKind.Array,\n\t\t\t\tTreeArrayNode<T>,\n\t\t\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\t\ttrue,\n\t\t\t\tT,\n\t\t\t\tundefined,\n\t\t\t\tTCustomMetadata\n\t\t\t>;\n\t\t}\n\n\t\tconst out: TreeNodeSchemaBoth<\n\t\t\tScopedSchemaName<TScope, string>,\n\t\t\tNodeKind.Array,\n\t\t\tTreeArrayNode<T>,\n\t\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\ttrue,\n\t\t\tT,\n\t\t\tundefined,\n\t\t\tTCustomMetadata\n\t\t> = this.namedArray(nameOrAllowedTypes as TName, allowedTypes, true, true, options ?? {});\n\t\treturn out;\n\t}\n\n\t/\n\t Retrieves or creates a structural {@link TreeNodeSchema} with the specified name and types.\n\t \n\t @param fullName - The name for the structural schema.\n\t * @param types - The input schema(s) used to define the structural schema.\n\t * @param builder - A function that builds the schema if it does not already exist.\n\t * @returns The structural {@link TreeNodeSchema} associated with the given name and types.\n\t * @throws `UsageError` if a schema structurally named schema with the same name is cached in `structuralTypes` but had different input types.\n\t /\n\tprotected getStructuralType(\n\t\tfullName: string,\n\t\ttypes: TreeNodeSchema \| readonly TreeNodeSchema[],\n\t\tbuilder: () => TreeNodeSchema,\n\t): TreeNodeSchema {\n\t\tconst structural = getOrCreate(this.structuralTypes, fullName, builder);\n\t\tconst inputTypes = new Set(normalizeAllowedTypes(types));\n\t\tconst outputTypes = new Set(\n\t\t\tnormalizeAllowedTypes(structural.info as TreeNodeSchema \| readonly TreeNodeSchema[]),\n\t\t);\n\t\t// If our cached value had a different set of types then were requested, the user must have caused a collision.\n\t\tconst same = compareSets({ a: inputTypes, b: outputTypes });\n\t\tif (!same) {\n\t\t\tthrow new UsageError(\n\t\t\t\t`Structurally named schema collision: two schemas named \"${fullName}\" were defined with different input schemas.`,\n\t\t\t);\n\t\t}\n\t\treturn structural;\n\t}\n\n\t/\n\t Define a {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.\n\t \n\t @param name - Unique identifier for this schema within this factory's scope.\n\t \n\t @remarks\n\t * This is not intended to be used directly, use the overload of `array` which takes a name instead.\n\t * This is only public to work around a compiler limitation.\n\t /\n\tprivate namedArray<\n\t\tName extends TName \| string,\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst ImplicitlyConstructable extends boolean,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t\tcustomizable: boolean,\n\t\timplicitlyConstructable: ImplicitlyConstructable,\n\t\toptions: NodeSchemaOptionsAlpha<TCustomMetadata>,\n\t): TreeNodeSchemaBoth<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, string>, NodeKind.Array>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\tImplicitlyConstructable,\n\t\tT,\n\t\tundefined,\n\t\tTCustomMetadata\n\t> {\n\t\treturn arraySchema(\n\t\t\tscoped(this, name),\n\t\t\tallowedTypes,\n\t\t\timplicitlyConstructable,\n\t\t\tcustomizable,\n\t\t\toptions,\n\t\t);\n\t}\n\n\t/\n\t A special readonly field which holds an identifier string for an object node.\n\t * @remarks\n\t * The value of this field, a \"node identifier\", is a string which identifies a node (or nodes) among all nodes in the tree.\n\t * Node identifiers are strings, and can therefore be used as lookup keys in maps or written to a database.\n\t * When the node is constructed, the identifier field does not need to be specified.\n\t * When an identifier is not provided, the SharedTree will generate an identifier for the node automatically.\n\t * The identifier generated by the SharedTree has the following properties:\n\t \n\t - It is a UUID which will not collide with other generated UUIDs.\n\t \n\t - It is compressed to a space-efficient representation when stored in the document.\n\t * Reading the identifier before inserting the node into a tree prevents the identifier from being stored in its compressed form,\n\t * resulting in a larger storage footprint.\n\t \n\t - A compressed form of the identifier can be accessed at runtime via the {@link TreeNodeApi.shortId\|Tree.shortId()} API.\n\t \n\t However, a user may alternatively supply their own string as the identifier if desired (for example, if importing identifiers from another system).\n\t * In that case, if the user requires it to be unique, it is up to them to ensure uniqueness.\n\t * User-supplied identifiers may be read immediately, even before insertion into the tree.\n\t \n\t A node may have more than one identifier field (though note that this precludes the use of the {@link TreeNodeApi.shortId\|Tree.shortId()} API).\n\t /\n\tpublic get identifier(): FieldSchema<FieldKind.Identifier, typeof this.string> {\n\t\tconst defaultIdentifierProvider: DefaultProvider = getDefaultProvider(\n\t\t\t(\n\t\t\t\tcontext: FlexTreeHydratedContextMinimal \| \"UseGlobalContext\",\n\t\t\t): UnhydratedFlexTreeNode[] => {\n\t\t\t\tconst id =\n\t\t\t\t\tcontext === \"UseGlobalContext\"\n\t\t\t\t\t\t? globalIdentifierAllocator.decompress(\n\t\t\t\t\t\t\t\tglobalIdentifierAllocator.generateCompressedId(),\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t: context.nodeKeyManager.stabilizeNodeIdentifier(\n\t\t\t\t\t\t\t\tcontext.nodeKeyManager.generateLocalNodeIdentifier(),\n\t\t\t\t\t\t\t);\n\n\t\t\t\treturn [unhydratedFlexTreeFromInsertable(id, this.string)];\n\t\t\t},\n\t\t);\n\t\treturn createFieldSchema(FieldKind.Identifier, this.string, {\n\t\t\tdefaultProvider: defaultIdentifierProvider,\n\t\t});\n\t}\n\n\t/\n\t {@link SchemaFactory.object} except tweaked to work better for recursive types.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * This version of {@link SchemaFactory.object} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t \n\t Additionally `ImplicitlyConstructable` is disabled (forcing use of constructor) to avoid\n\t * `error TS2589: Type instantiation is excessively deep and possibly infinite.`\n\t * which otherwise gets reported at sometimes incorrect source locations that vary based on incremental builds.\n\t /\n\tpublic objectRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>,\n\t>(\n\t\tname: Name,\n\t\tt: T,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Object,\n\t\tSystem_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,\n\t\tobject & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,\n\t\tfalse,\n\t\tT\n\t> {\n\t\ttype TScopedName = ScopedSchemaName<TScope, Name>;\n\t\treturn this.object(\n\t\t\tname,\n\t\t\tt as T & RestrictiveStringRecord<ImplicitFieldSchema>,\n\t\t) as unknown as TreeNodeSchemaClass<\n\t\t\tTScopedName,\n\t\t\tNodeKind.Object,\n\t\t\tSystem_Unsafe.TreeObjectNodeUnsafe<T, TScopedName>,\n\t\t\tobject & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,\n\t\t\tfalse,\n\t\t\tT\n\t\t>;\n\t}\n\n\t/\n\t `SchemaFactory.array` except tweaked to work better for recursive types.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * This version of `SchemaFactory.array` uses the same workarounds as {@link SchemaFactory.objectRecursive}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t * See also {@link FixRecursiveArraySchema} for additional information specific to recursive arrays schema exports.\n\t /\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic arrayRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t>(name: Name, allowedTypes: T) {\n\t\tconst RecursiveArray = this.namedArray(\n\t\t\tname,\n\t\t\tallowedTypes as T & ImplicitAllowedTypes,\n\t\t\ttrue,\n\t\t\tfalse,\n\t\t\t{},\n\t\t);\n\n\t\treturn RecursiveArray as TreeNodeSchemaClass<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tNodeKind.Array,\n\t\t\tSystem_Unsafe.TreeArrayNodeUnsafe<T> &\n\t\t\t\tWithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,\n\t\t\t{\n\t\t\t\t/\n\t\t\t\t Iterator for the iterable of content for this node.\n\t\t\t\t * @privateRemarks\n\t\t\t\t * Wrapping the constructor parameter for recursive arrays and maps in an inlined object type avoids (for unknown reasons)\n\t\t\t\t * the following compile error when declaring the recursive schema:\n\t\t\t\t * `Function implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.`\n\t\t\t\t * To benefit from this without impacting the API, the definition of `Iterable` has been inlined as such an object.\n\t\t\t\t \n\t\t\t\t If this workaround is kept, ideally this comment would be deduplicated with the other instance of it.\n\t\t\t\t * Unfortunately attempts to do this failed to avoid the compile error this was introduced to solve.\n\t\t\t\t /\n\t\t\t\t[Symbol.iterator](): Iterator<\n\t\t\t\t\tSystem_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>\n\t\t\t\t>;\n\t\t\t},\n\t\t\tfalse,\n\t\t\tT,\n\t\t\tundefined\n\t\t>;\n\t}\n\n\t/\n\t `SchemaFactory.map` except tweaked to work better for recursive types.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * This version of `SchemaFactory.map` uses the same workarounds as {@link SchemaFactory.objectRecursive}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t /\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic mapRecursive<\n\t\tName extends TName,\n\t\tconst T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t>(name: Name, allowedTypes: T) {\n\t\tconst MapSchema = this.namedMap(\n\t\t\tname,\n\t\t\tallowedTypes as T & ImplicitAllowedTypes,\n\t\t\ttrue,\n\t\t\t// Setting this (implicitlyConstructable) to true seems to work ok currently, but not for other node kinds.\n\t\t\t// Supporting this could be fragile and might break other future changes, so it's being kept as false for now.\n\t\t\tfalse,\n\t\t\t{},\n\t\t);\n\n\t\treturn MapSchema as TreeNodeSchemaClass<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tNodeKind.Map,\n\t\t\tSystem_Unsafe.TreeMapNodeUnsafe<T> &\n\t\t\t\tWithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,\n\t\t\t\| {\n\t\t\t\t\t/\n\t\t\t\t\t Iterator for the iterable of content for this node.\n\t\t\t\t\t * @privateRemarks\n\t\t\t\t\t * Wrapping the constructor parameter for recursive arrays and maps in an inlined object type avoids (for unknown reasons)\n\t\t\t\t\t * the following compile error when declaring the recursive schema:\n\t\t\t\t\t * `Function implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.`\n\t\t\t\t\t * To benefit from this without impacting the API, the definition of `Iterable` has been inlined as such an object.\n\t\t\t\t\t \n\t\t\t\t\t If this workaround is kept, ideally this comment would be deduplicated with the other instance of it.\n\t\t\t\t\t * Unfortunately attempts to do this failed to avoid the compile error this was introduced to solve.\n\t\t\t\t\t /\n\t\t\t\t\t[Symbol.iterator](): Iterator<\n\t\t\t\t\t\t[string, System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]\n\t\t\t\t\t>;\n\t\t\t }\n\t\t\t// Ideally this would be\n\t\t\t// RestrictiveStringRecord<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>,\n\t\t\t// but doing so breaks recursive types.\n\t\t\t// Instead we do a less nice version:\n\t\t\t\| {\n\t\t\t\t\treadonly [P in string]: System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;\n\t\t\t },\n\t\t\tfalse,\n\t\t\tT,\n\t\t\tundefined\n\t\t>;\n\t}\n}\n\nexport function structuralName<const T extends string>(\n\tcollectionName: T,\n\tallowedTypes: TreeNodeSchema \| readonly TreeNodeSchema[],\n): `${T}<${string}>` {\n\tlet inner: string;\n\tif (isReadonlyArray(allowedTypes)) {\n\t\tconst names = allowedTypes.map((t): string => {\n\t\t\t// Ensure that lazy types (functions) don't slip through here.\n\t\t\tassert(!isLazy(t), 0x83d / invalid type provided /);\n\t\t\tmarkSchemaMostDerived(t);\n\t\t\treturn t.identifier;\n\t\t});\n\t\t// Ensure name is order independent\n\t\tnames.sort();\n\t\t// Ensure name can't have collisions by quoting and escaping any quotes in the names of types.\n\t\t// Using JSON is a simple way to accomplish this.\n\t\t// The outer `[]` around the result were needed so that a single type name \"Any\" would not collide with the \"any\" case which used to exist.\n\t\tinner = JSON.stringify(names);\n\t} else {\n\t\treturn structuralName(collectionName, [allowedTypes]);\n\t}\n\treturn `${collectionName}<${inner}>`;\n}\n\nexport function scoped<\n\tTScope extends string \| undefined,\n\tTName extends number \| string,\n\tName extends TName \| string,\n>(factory: SchemaFactory<TScope, TName>, name: Name): ScopedSchemaName<TScope, Name> {\n\treturn (\n\t\tfactory.scope === undefined ? `${name}` : `${factory.scope}.${name}`\n\t) as ScopedSchemaName<TScope, Name>;\n}\n\n/\n Used to allocate default identifiers for unhydrated nodes when no context is available.\n * @remarks\n * The identifiers allocated by this will never be compressed to Short Ids.\n * Using this is only better than creating fully random V4 UUIDs because it reduces the entropy making it possible for things like text compression to work slightly better.\n /\nconst globalIdentifierAllocator: IIdCompressor = createIdCompressor();\n\n/\n Additional information to provide to Node Schema creation.\n \n @typeParam TCustomMetadata - Custom metadata properties to associate with the Node Schema.\n * See {@link NodeSchemaMetadata.custom}.\n \n @input\n * @public\n /\nexport interface NodeSchemaOptions<out TCustomMetadata = unknown> {\n\t/\n\t Optional metadata to associate with the Node Schema.\n\t \n\t @remarks\n\t * This specifies {@link SimpleNodeSchemaBase.metadata} which has more details about its use.\n\t /\n\treadonly metadata?: NodeSchemaMetadata<TCustomMetadata> \| undefined;\n}\n\n/\n Additional information to provide to Node Schema creation. Includes fields for alpha features.\n \n @typeParam TCustomMetadata - Custom metadata properties to associate with the Node Schema.\n * See {@link NodeSchemaMetadata.custom}.\n \n @input\n * @alpha\n /\nexport interface NodeSchemaOptionsAlpha<out TCustomMetadata = unknown>\n\textends NodeSchemaOptions<TCustomMetadata> {\n\t/\n\t The persisted metadata for this schema element.\n\t * @remarks\n\t * This gets exposed via {@link SimpleNodeSchemaBaseAlpha.persistedMetadata}.\n\t */\n\treadonly persistedMetadata?: JsonCompatibleReadOnlyObject \| undefined;\n}\n"]}

package/lib/simple-tree/api/snapshotCompatibilityChecker.d.ts CHANGED Viewed

@@ -367,11 +367,11 @@ export interface SnapshotSchemaCompatibilityOptions {
  * 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.
+ * Generally any historical schemas 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:
+ * If a sufficiently incompatible historical schemas 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.

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

@@ -167,11 +167,11 @@ export function importCompatibilitySchemaSnapshot(config) {
  * 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.
+ * Generally any historical schemas 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:
+ * If a sufficiently incompatible historical schemas 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.

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

	@@ -1 +1 @@
1	- {"version":3,"file":"snapshotCompatibilityChecker.js","sourceRoot":"","sources":["../../../src/simple-tree/api/snapshotCompatibilityChecker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACvF,OAAO,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AACtE,OAAO,KAAK,MAAM,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACvF,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;AA6OD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuGG;AACH,MAAM,UAAU,2BAA2B,CAC1C,OAA2C;IAE3C,MAAM,OAAO,GAAG,IAAI,4BAA4B,CAC/C,OAAO,CAAC,iBAAiB,EACzB,OAAO,CAAC,UAAU,CAClB,CAAC;IACF,MAAM,EACL,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,iBAAiB,EACzB,IAAI,EACJ,0BAA0B,EAC1B,yBAAyB,EACzB,gCAAgC,EAChC,sCAAsC,GACtC,GAAG,OAAO,CAAC;IAEZ,MAAM,eAAe,GACpB,OAAO,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC;IACzE,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,MAAM,CAAC,OAAO,CAAC;IAElE,IAAI,eAAe,CAAC,cAAc,CAAC,KAAK,IAAI,EAAE,CAAC;QAC9C,MAAM,IAAI,UAAU,CACnB,oBAAoB,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,mCAAmC,CACrF,CAAC;IACH,CAAC;IACD,IAAI,eAAe,CAAC,0BAA0B,CAAC,KAAK,IAAI,EAAE,CAAC;QAC1D,MAAM,IAAI,UAAU,CACnB,uCAAuC,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC,mCAAmC,CACpH,CAAC;IACH,CAAC;IAED,IAAI,eAAe,CAAC,0BAA0B,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,UAAU,CACnB,uCAAuC,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC,mDAAmD,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,GAAG,CACrK,CAAC;IACH,CAAC;IAED,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC5C,MAAM,IAAI,UAAU,CACnB,iBAAiB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,wCAAwC,CAC7E,CAAC;IACH,CAAC;IAED,MAAM,6BAA6B,GAAG,iCAAiC,CAAC,iBAAiB,CAAC,CAAC;IAC3F,MAAM,SAAS,GAAG,OAAO,CAAC,sBAAsB,CAAC,eAAe,CAAC,CAAC;IAElE,MAAM,mBAAmB,GAAa,EAAE,CAAC;IAEzC,MAAM,YAAY,GAAa,EAAE,CAAC;IAElC,SAAS,gBAAgB,CAAC,OAAe;QACxC,OAAO,IAAI,KAAK,CACf;YACC,oCAAoC;YACpC,OAAO;YACP,iBAAiB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE;YAC5D,iCAAiC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG;YAC1F,GAAG,YAAY;SACf,CAAC,IAAI,CAAC,IAAI,CAAC,CACZ,CAAC;IACH,CAAC;IAED,MAAM,gBAAgB,GAAG,kBAAkB,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,EAAE,CACnE,gBAAgB,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAC7C,CAAC;IAEF,UAAU;IACV,4BAA4B;IAC5B,qEAAqE;IACrE,sDAAsD;IACtD,IAAI,WAAmC,CAAC;IAExC,kBAAkB;IAClB,CAAC;QACA,MAAM,cAAc,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;QAC1D,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;YAClC,WAAW,GAAG,qBAAqB,CAAC;QACrC,CAAC;aAAM,CAAC;YACP,MAAM,mBAAmB,GACxB,gBAAgB,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;gBACvC,IAAI,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;YAElD,MAAM,YAAY,GAAG,CAAC,mBAAmB,CAAC,sBAAsB,CAAC;YACjE,MAAM,aAAa,GAAG,eAAe,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;YAE/E,IAAI,gCAAgC,KAAK,IAAI,IAAI,aAAa,IAAI,CAAC,YAAY,EAAE,CAAC;gBACjF,WAAW,GAAG,gBAAgB,CAC7B,6BAA6B,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,sDAAsD,CACzJ,CAAC;YACH,CAAC;iBAAM,IACN,sCAAsC,KAAK,IAAI;gBAC/C,YAAY;gBACZ,CAAC,aAAa,EACb,CAAC;gBACF,WAAW,GAAG,gBAAgB,CAC7B,wGAAwG,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,2DAA2D,CACpM,CAAC;YACH,CAAC;iBAAM,IAAI,yBAAyB,KAAK,IAAI,EAAE,CAAC;gBAC/C,MAAM,WAAW,GAAG,SAAS,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;gBAClD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;oBAC/B,WAAW,GAAG,iCAAiC,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,4EAA4E,CAAC;gBAC3J,CAAC;qBAAM,IACN,IAAI,CAAC,SAAS,CAAC,iCAAiC,CAAC,WAAW,CAAC,CAAC;oBAC9D,IAAI,CAAC,SAAS,CAAC,6BAA6B,CAAC,EAC5C,CAAC;oBACF,WAAW,GAAG,KAAK,CAAC;gBACrB,CAAC;qBAAM,CAAC;oBACP,WAAW,GAAG,gCAAgC,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,kBAAkB,CAAC;gBAChG,CAAC;YACF,CAAC;iBAAM,CAAC;gBACP,IAAI,eAAe,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC7D,WAAW,GAAG,YAAY;wBACzB,CAAC,CAAC,gCAAgC,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,8EAA8E,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG;wBAClL,CAAC,CAAC,KAAK,CAAC;gBACV,CAAC;qBAAM,CAAC;oBACP,WAAW,GAAG,gBAAgB,CAC7B,mBAAmB,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,kDAAkD,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,kDAAkD,CACtL,CAAC;gBACH,CAAC;YACF,CAAC;YAED,IAAI,CAAC,YAAY,IAAI,CAAC,yBAAyB,KAAK,IAAI,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;gBAC7E,gDAAgD;gBAChD,IACC,IAAI,CAAC,SAAS,CAAC,iCAAiC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;oBACpE,IAAI,CAAC,SAAS,CAAC,6BAA6B,CAAC,EAC5C,CAAC;oBACF,gGAAgG;oBAChG,kKAAkK;oBAClK,qEAAqE;oBACrE,oGAAoG;gBACrG,CAAC;YACF,CAAC;QACF,CAAC;IACF,CAAC;IAED,IAAI,WAAW,KAAK,KAAK,EAAE,CAAC;QAC3B,IAAI,WAAW,YAAY,KAAK,EAAE,CAAC;YAClC,MAAM,WAAW,CAAC;QACnB,CAAC;QACD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvB,OAAO,CAAC,mBAAmB,CAAC,cAAc,EAAE,6BAA6B,CAAC,CAAC;YAC3E,wDAAwD;YACxD,gBAAgB,CAAC,GAAG,CACnB,cAAc,EACd,gBAAgB,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,CACtD,CAAC;QACH,CAAC;aAAM,CAAC;YACP,mBAAmB,CAAC,IAAI,CACvB,GAAG,WAAW,mHAAmH,CACjI,CAAC;YAEF,uKAAuK;YACvK,uIAAuI;YACvI,qHAAqH;QACtH,CAAC;IACF,CAAC;IAED,2FAA2F;IAC3F,qHAAqH;IACrH,gGAAgG;IAChG,IAAI,0BAA0B,KAAK,cAAc,EAAE,CAAC;QACnD,IAAI,yBAAyB,KAAK,IAAI,EAAE,CAAC;YACxC,MAAM,WAAW,GAAG,gBAAgB,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;YACrE,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;gBAC/B,mBAAmB,CAAC,IAAI,CACvB,uFAAuF,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC,kCAAkC,CACnK,CAAC;YACH,CAAC;QACF,CAAC;aAAM,CAAC;YACP,MAAM,0CAA0C,GAAG,wBAAwB,CAC1E,0BAA0B,EAC1B,gBAAgB,EAChB,eAAe,CACf,CAAC;YACF,IAAI,0CAA0C,KAAK,SAAS,EAAE,CAAC;gBAC9D,mBAAmB,CAAC,IAAI,CACvB,mFAAmF,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC,GAAG,CAChI,CAAC;YACH,CAAC;iBAAM,IACN,0CAA0C,CAAC,CAAC,CAAC,KAAK,0BAA0B,EAC3E,CAAC;gBACF,oJAAoJ;gBACpJ,gBAAgB,CAAC,GAAG,CACnB,0BAA0B,EAC1B,0CAA0C,CAAC,CAAC,CAAC,CAC7C,CAAC;gBACF,YAAY,CAAC,IAAI,CAChB,gFAAgF,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC,mFAAmF,IAAI,CAAC,SAAS,CAC1N,0CAA0C,CAAC,CAAC,CAAC,CAC7C,qDAAqD,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC,GAAG,CACnG,CAAC;YACH,CAAC;QACF,CAAC;IACF,CAAC;IAED,gFAAgF;IAChF,KAAK,MAAM,CAAC,eAAe,EAAE,aAAa,CAAC,IAAI,gBAAgB,EAAE,CAAC;QACjE,+CAA+C;QAC/C,IAAI,CAAC,aAAa,CAAC,6BAA6B,CAAC,UAAU,EAAE,CAAC;YAC7D,mBAAmB,CAAC,IAAI,CACvB,mBAAmB,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,kCAAkC,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,GAAG,CACrH,CAAC;QACH,CAAC;QAED,MAAM,0BAA0B,GAAG,eAAe,CAAC,eAAe,EAAE,cAAc,CAAC,CAAC;QACpF,IAAI,0BAA0B,KAAK,CAAC,EAAE,CAAC;YACtC,IAAI,cAAc,KAAK,eAAe,EAAE,CAAC;gBACxC,MAAM,gBAAgB,CACrB,oBAAoB,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,kEAAkE,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,0BAA0B,CAC7K,CAAC;YACH,CAAC;YACD,IAAI,aAAa,CAAC,sBAAsB,KAAK,KAAK,EAAE,CAAC;gBACpD,MAAM,CACL,WAAW,KAAK,KAAK,EACrB,KAAK,CAAC,wEAAwE,CAC9E,CAAC;YACH,CAAC;QACF,CAAC;aAAM,IAAI,0BAA0B,GAAG,CAAC,EAAE,CAAC;YAC3C,uDAAuD;YACvD,IAAI,eAAe,CAAC,eAAe,EAAE,0BAA0B,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvE,wIAAwI;gBACxI,IAAI,CAAC,aAAa,CAAC,6BAA6B,CAAC,OAAO,EAAE,CAAC;oBAC1D,mBAAmB,CAAC,IAAI,CACvB,sBAAsB,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,+BAA+B,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,0GAA0G,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC,GAAG,CACzQ,CAAC;gBACH,CAAC;YACF,CAAC;iBAAM,CAAC;gBACP,oGAAoG;gBACpG,qKAAqK;YACtK,CAAC;QACF,CAAC;aAAM,CAAC;YACP,mBAAmB,CAAC,IAAI,CACvB,+BAA+B,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,8CAA8C,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,0BAA0B,CACpK,CAAC;QACH,CAAC;IACF,CAAC;IAED,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,gBAAgB,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9E,CAAC;AACF,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,4BAA4B;IACxC;IACC;;OAEG;IACc,iBAAyB;IAC1C;;OAEG;IACc,iBAAqC;QAJrC,sBAAiB,GAAjB,iBAAiB,CAAQ;QAIzB,sBAAiB,GAAjB,iBAAiB,CAAoB;IACpD,CAAC;IAEG,mBAAmB,CAAC,YAAoB,EAAE,QAAgC;QAChF,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAC3C,IAAI,CAAC,iBAAiB,EACtB,GAAG,YAAY,OAAO,CACtB,CAAC;QACF,IAAI,CAAC,6BAA6B,EAAE,CAAC;QACrC,IAAI,CAAC,iBAAiB,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE;YACzF,QAAQ,EAAE,MAAM;SAChB,CAAC,CAAC;IACJ,CAAC;IAEM,kBAAkB,CAAC,YAAoB;QAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,qBAAqB,CAAC,YAAY,CAAC,CAAC;QAC1D,OAAO,iCAAiC,CAAC,QAAQ,CAAC,CAAC;IACpD,CAAC;IAEM,qBAAqB,CAAC,YAAoB;QAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAC3C,IAAI,CAAC,iBAAiB,EACtB,GAAG,YAAY,OAAO,CACtB,CAAC;QACF,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAC1B,IAAI,CAAC,iBAAiB,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAC3B,CAAC;QAC5B,OAAO,QAAQ,CAAC;IACjB,CAAC;IAED;;OAEG;IACI,sBAAsB,CAC5B,OAAyC;QAEzC,IAAI,CAAC,6BAA6B,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,iBAAiB,CAAC,WAAW,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QACzE,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC5B,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;gBACxD,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC7B,CAAC;QACF,CAAC;QACD,gGAAgG;QAChG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEvB,MAAM,SAAS,GAAuC,IAAI,GAAG,EAAE,CAAC;QAChE,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAChC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;QAC1D,CAAC;QACD,OAAO,SAAS,CAAC;IAClB,CAAC;IAEM,6BAA6B;QACnC,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/E,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC/B,iBAAwC,EACxC,kBAAyC;IAEzC,MAAM,4BAA4B,GAAG,kBAAkB,CACtD,kBAAkB,EAClB,iBAAiB,CACjB,CAAC;IAEF,MAAM,2BAA2B,GAAG,kBAAkB,CACrD,iBAAiB,EACjB,kBAAkB,CAClB,CAAC;IAEF,MAAM,CACL,4BAA4B,CAAC,YAAY,KAAK,2BAA2B,CAAC,YAAY,EACtF,KAAK,CAAC,kCAAkC,CACxC,CAAC;IAEF,yHAAyH;IACzH,MAAM,sBAAsB,GAC3B,IAAI,CAAC,SAAS,CAAC,iCAAiC,CAAC,iBAAiB,CAAC,CAAC;QACpE,IAAI,CAAC,SAAS,CAAC,iCAAiC,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAEvE,IAAI,sBAAsB,EAAE,CAAC;QAC5B,MAAM,CACL,4BAA4B,CAAC,YAAY,EACzC,KAAK,CAAC,iEAAiE,CACvE,CAAC;IACH,CAAC;IAED,OAAO;QACN,6BAA6B,EAAE,4BAA4B;QAC3D,6BAA6B,EAAE,2BAA2B;QAC1D,sBAAsB;KACtB,CAAC;AACH,CAAC","sourcesContent":["/!\n Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n /\n\nimport { assert, fail, 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 snapshotSchemaCompatibility}.\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 * @beta\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\t/\n\t True if and only if the schema have identical compatibility.\n\t * @remarks\n\t * This includes producing the equivalent stored schema (which currentViewOfSnapshotDocument and snapshotViewOfCurrentDocument also measure)\n\t * as well as equivalent compatibility with potential future schema changes beyond just those in these two schema.\n\t \n\t This includes compatibility with all potential future schema changes.\n\t * For example two schema different only in compatibility with future optional fields via allow unknown optional fields or staged schema\n\t * would be considered non-equivalent, even though they are forwards and backwards compatible with each other, and both status above report them as equivalent\n\t * since they would produce the same stored schema upon schema upgrade.\n\t /\n\treadonly identicalCompatibility: boolean;\n}\n\n/\n The options for {@link snapshotSchemaCompatibility}.\n * @input\n * @beta\n /\nexport interface SnapshotSchemaCompatibilityOptions {\n\t/\n\t Directory where historical schema snapshots are stored.\n\t * @remarks\n\t * As the contents of this directory (specifically historical snapshots) cannot be regenerated,\n\t * a directory appropriate for test data should be used.\n\t * Generally this means that this directory should be versioned like code,\n\t * and not erased when regenerating snapshots.\n\t \n\t This directory will be created if it does not already exist.\n\t * All \".json\" files in this directory will be treated as schema snapshots.\n\t * It is recommended to use a dedicated directory for each {@link snapshotSchemaCompatibility} powered test.\n\t \n\t This can use any path syntax supported by the provided {@link SnapshotSchemaCompatibilityOptions.fileSystem}.\n\t /\n\treadonly snapshotDirectory: string;\n\n\t/\n\t How the `snapshotDirectory` is accessed.\n\t /\n\treadonly fileSystem: SnapshotFileSystem;\n\n\t/\n\t The current view schema.\n\t /\n\treadonly schema: TreeViewConfiguration;\n\n\t/\n\t The version which will be associated with this version of the schema.\n\t * @remarks\n\t * Often the easiest way to ensure this is to simply use the next version which will be released for the package or application itself, and set the `minVersionForCollaboration` based on telemetry about which versions are still in use.\n\t * To do this, it is recommended that this version be programmatically derived from the application version rather than hard coded inline.\n\t * For example, reading it from the `package.json` or some other source of truth can be done to ensure it is kept up to date, and thus snapshots always have the correct version.\n\t * The version used should typically be the _next_ production version (whose formats must be supported long term) that will be released (but is not yet released).\n\t * This usually means that the correct version to use is the same version that would be used when releasing the application or library, but with any prerelease version tags removed.\n\t * If an automated way to keep this version up to date is not used, be very careful when reviewing changes to snapshot files to ensure the version is correct.\n\t * If incorrectly versioned snapshots were committed accidentally, rename the snapshot files to have the correct version, and restore the old files from, version control.\n\t \n\t It is possible to use a different versioning scheme, for example one specific to the schema in question.\n\t * This can be done robustly as long as care is taken to ensure the version increases such that every released version has a unique `version` (and therefore unique snapshot),\n\t * and `minVersionForCollaboration` is set appropriately using the same versioning scheme.\n\t * {@link SnapshotSchemaCompatibilityOptions.rejectVersionsWithNoSchemaChange} and\n\t * {@link SnapshotSchemaCompatibilityOptions.rejectSchemaChangesWithNoVersionChange}\n\t * can be used to help enforce the expected relationship between version changes and schema changes in such cases.\n\t \n\t Can use any format supported by {@link SnapshotSchemaCompatibilityOptions.versionComparer}.\n\t * 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\t Typically `minVersionForCollaboration` should be set to the oldest version currently in use, so it's helpful to use a version which can be easily measured to tell if clients are still using it.\n\t /\n\treadonly version: string;\n\n\t/\n\t The minimum version that the current version is expected to be able to collaborate with.\n\t * @remarks\n\t * Can use any format supported by {@link SnapshotSchemaCompatibilityOptions.versionComparer}.\n\t \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 snapshotSchemaCompatibility} 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 whatever versioning scheme is used with {@link SnapshotSchemaCompatibilityOptions.version}.\n\t /\n\treadonly minVersionForCollaboration: string;\n\n\t/\n\t A comparison function for version strings.\n\t * @remarks\n\t * A comparison function like that provided to {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#comparefn \| Array.sort}.\n\t * This is used to partition snapshots into those less than `minVersionForCollaboration` and those greater than or equal to it, as well as to sanity check `version` against the versions of the snapshots.\n\t * If not provided, the ordering is defined by {@link https://semver.org/#spec-item-11\|semver}.\n\t * @returns A negative number if `a` is less than `b`, zero if they are equal, or a positive number if `a` is greater than `b`.\n\t /\n\treadonly versionComparer?: (a: string, b: string) => number;\n\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\n\t/\n\t When true, it is an error if a new a snapshot for a new version would be created, but the schema compatibility is identical to the previous snapshot.\n\t * @remarks\n\t * This prevents creating a snapshot with the same schema compatibility results as the previous one.\n\t \n\t Applications and libraries which do not have versioned releases can make up a version specific to the compatibility of the schema, and use this option to help ensure they manage that version correctly.\n\t * Such cases can also opt into {@link SnapshotSchemaCompatibilityOptions.rejectSchemaChangesWithNoVersionChange} if they want additional strictness.\n\t /\n\treadonly rejectVersionsWithNoSchemaChange?: true;\n\n\t/\n\t When true, it is an error if a schema change occurs without a corresponding version change.\n\t * @remarks\n\t * This disables overwriting existing snapshots.\n\t * This option is recommended if the {@link SnapshotSchemaCompatibilityOptions.version} is not automatically updated ahead of releasing a version which must be supported.\n\t * If updating the snapshot is still desired, the preceding one which needs to be overwritten can be manually deleted before running the update.\n\t \n\t This option does not impact the behavior of assert mode (other than impacting what error is given).\n\t * This option simply makes update mode more strict, converting cases that would overwrite a snapshot in place into errors.\n\t /\n\treadonly rejectSchemaChangesWithNoVersionChange?: true;\n\n\t/\n\t The mode of operation, either \"assert\" or \"update\".\n\t * @remarks\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 In \"assert\" mode, an error is additionally thrown if the latest snapshot is not up to date (meaning \"update\" mode would make a change).\n\t \n\t In \"update\" mode, a new snapshot is created if the current schema differs from the latest existing snapshot.\n\t * If {@link SnapshotSchemaCompatibilityOptions.rejectVersionsWithNoSchemaChange} or\n\t * {@link SnapshotSchemaCompatibilityOptions.rejectSchemaChangesWithNoVersionChange} disallows the update, an error is thrown instead.\n\t \n\t It is recommended that \"assert\" 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 or version changes.\n\t \n\t @privateRemarks\n\t * Modes we might want to add in the future:\n\t * - normalize: update the latest snapshot (or maybe all of them) to the latest encoded format.\n\t * - some mode like assert but returns information instead of throwing.\n\t /\n\treadonly mode: \"assert\" \| \"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 when using default semver version comparison.\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 Unlike some other snapshot based testing tools, this stores more than just the current snapshot: historical snapshots are retained as well.\n * Retention of these additional historical snapshots, whose content can't be regenerated from the current schema, is necessary to properly test compatibility across versions.\n * Since there is content in the snapshots which cannot be regenerated, tools which assume all snapshotted content can be regenerated cannot be used here.\n * This means that tools like Jest's built in snapshot testing are not suitable for this purpose.\n * These snapshots behave partly like test data, and partly like snapshots.\n * Typically the easiest way to manage this is to place {@link SnapshotSchemaCompatibilityOptions.snapshotDirectory} inside a directory appropriate for test data,\n * and use node to provide the filesystem access via {@link SnapshotSchemaCompatibilityOptions.fileSystem}.\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 * \tsnapshotSchemaCompatibility({\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 * @example Complete Mocha test file\n * ```typescript\n * import fs from \"node:fs\";\n * import path from \"node:path\";\n \n import { snapshotSchemaCompatibility } from \"@fluidframework/tree/beta\";\n \n // The TreeViewConfiguration the application uses, which contains the application's schema.\n * import { treeViewConfiguration } from \"./schema.js\";\n * // The next version of the application which will be released.\n * import { packageVersion } from \"./version.js\";\n \n // Provide some way to run the check in \"update\" mode when updating snapshots is intended.\n * const regenerateSnapshots = process.argv.includes(\"--snapshot\");\n \n // Setup the actual test. In this case using Mocha syntax.\n * describe(\"schema\", () => {\n * \tit(\"schema compatibility\", () => {\n * \t\t// Select a path to save the snapshots in.\n * \t\t// This will depend on how your application organizes its test data.\n * \t\tconst snapshotDirectory = path.join(\n * \t\t\timport.meta.dirname,\n * \t\t\t\"../../../src/test/schema-snapshots\",\n * \t\t);\n * \t\tsnapshotSchemaCompatibility({\n * \t\t\tschema: config,\n * \t\t\tfileSystem: { ...fs, ...path },\n * \t\t\tversion: pkgVersion,\n * \t\t\tminVersionForCollaboration: \"2.0.0\",\n * \t\t\tmode: process.argv.includes(\"--snapshot\") ? \"update\" : \"assert\",\n * \t\t\tsnapshotDirectory,\n * \t\t});\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 This uses the format defined in simpleSchemaCodec.ts.\n * This does include versioning information in the snapshot format,\n * but it would be nice to better unify how we do that versioning and format validation with our codecs.\n \n See snapshotCompatibilityChecker.example.mts for the large example included above.\n * @beta\n /\nexport function snapshotSchemaCompatibility(\n\toptions: SnapshotSchemaCompatibilityOptions,\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\trejectVersionsWithNoSchemaChange,\n\t\trejectSchemaChangesWithNoVersionChange,\n\t} = options;\n\n\tconst validateVersion =\n\t\toptions.versionComparer === undefined ? semver.valid : (v: string) => v;\n\tconst versionComparer = options.versionComparer ?? semver.compare;\n\n\tif (validateVersion(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 (validateVersion(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\n\tif (versionComparer(minVersionForCollaboration, currentVersion) > 0) {\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 !== \"assert\" && mode !== \"update\") {\n\t\tthrow new UsageError(\n\t\t\t`Invalid mode: ${JSON.stringify(mode)}. Must be either \"assert\" or \"update\".`,\n\t\t);\n\t}\n\n\tconst currentEncodedForSnapshotting = exportCompatibilitySchemaSnapshot(currentViewSchema);\n\tconst snapshots = checker.readAllSchemaSnapshots(versionComparer);\n\n\tconst compatibilityErrors: string[] = [];\n\n\tconst contextNotes: string[] = [];\n\n\tfunction errorWithContext(message: string): Error {\n\t\treturn new Error(\n\t\t\t[\n\t\t\t\t\"Schema compatibility check failed:\",\n\t\t\t\tmessage,\n\t\t\t\t`Snapshots in: ${JSON.stringify(options.snapshotDirectory)}`,\n\t\t\t\t`Snapshots exist for versions: ${JSON.stringify([...snapshots.keys()], undefined, \"\\t\")}.`,\n\t\t\t\t...contextNotes,\n\t\t\t].join(\"\\n\"),\n\t\t);\n\t}\n\n\tconst compatibilityMap = transformMapValues(snapshots, (snapshot) =>\n\t\tgetCompatibility(currentViewSchema, snapshot),\n\t);\n\n\t// Either:\n\t// - false: no update needed\n\t// - the updateError message (update in update mode, error otherwise)\n\t// - an error if the update is disallowed by the flags\n\tlet wouldUpdate: false \| string \| Error;\n\n\t// Set wouldUpdate\n\t{\n\t\tconst latestSnapshot = [...snapshots][snapshots.size - 1];\n\t\tif (latestSnapshot === undefined) {\n\t\t\twouldUpdate = `No snapshots found.`;\n\t\t} else {\n\t\t\tconst latestCompatibility =\n\t\t\t\tcompatibilityMap.get(latestSnapshot[0]) ??\n\t\t\t\tfail(0xcd1 / missing compatibilityMap entry /);\n\n\t\t\tconst schemaChange = !latestCompatibility.identicalCompatibility;\n\t\t\tconst versionChange = versionComparer(latestSnapshot[0], currentVersion) !== 0;\n\n\t\t\tif (rejectVersionsWithNoSchemaChange === true && versionChange && !schemaChange) {\n\t\t\t\twouldUpdate = errorWithContext(\n\t\t\t\t\t`Rejecting version change (${JSON.stringify(latestSnapshot[0])} to ${JSON.stringify(currentVersion)}) due to rejectVersionsWithNoSchemaChange being set.`,\n\t\t\t\t);\n\t\t\t} else if (\n\t\t\t\trejectSchemaChangesWithNoVersionChange === true &&\n\t\t\t\tschemaChange &&\n\t\t\t\t!versionChange\n\t\t\t) {\n\t\t\t\twouldUpdate = errorWithContext(\n\t\t\t\t\t`Rejecting schema change without version change due to existing non-equivalent snapshot for version (${JSON.stringify(latestSnapshot[0])} due to rejectSchemaChangesWithNoVersionChange being set.`,\n\t\t\t\t);\n\t\t\t} else if (snapshotUnchangedVersions === true) {\n\t\t\t\tconst currentRead = snapshots.get(currentVersion);\n\t\t\t\tif (currentRead === undefined) {\n\t\t\t\t\twouldUpdate = `No snapshot found for version ${JSON.stringify(currentVersion)}: snapshotUnchangedVersions is true, so every version must be snapshotted.`;\n\t\t\t\t} else if (\n\t\t\t\t\tJSON.stringify(exportCompatibilitySchemaSnapshot(currentRead)) ===\n\t\t\t\t\tJSON.stringify(currentEncodedForSnapshotting)\n\t\t\t\t) {\n\t\t\t\t\twouldUpdate = false;\n\t\t\t\t} else {\n\t\t\t\t\twouldUpdate = `Snapshot for current version ${JSON.stringify(currentVersion)} is out of date.`;\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tif (versionComparer(latestSnapshot[0], currentVersion) <= 0) {\n\t\t\t\t\twouldUpdate = schemaChange\n\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: false;\n\t\t\t\t} else {\n\t\t\t\t\twouldUpdate = errorWithContext(\n\t\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\t);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (!schemaChange && (snapshotUnchangedVersions !== true \|\| !versionChange)) {\n\t\t\t\t// eslint-disable-next-line unicorn/no-lonely-if\n\t\t\t\tif (\n\t\t\t\t\tJSON.stringify(exportCompatibilitySchemaSnapshot(latestSnapshot[1])) !==\n\t\t\t\t\tJSON.stringify(currentEncodedForSnapshotting)\n\t\t\t\t) {\n\t\t\t\t\t// Schema are compatibility wise equivalent, but differ in some way (excluding json formatting).\n\t\t\t\t\t// TODO: add a \"normalize\" mode, which do an update only in this case (or maybe even normalize json formatting as well and just always rewrite when !schemaChange)\n\t\t\t\t\t// This would be useful to minimize diffs from future schema changes.\n\t\t\t\t\t// This would be particularly useful if adding a second version of the format used in the snapshots.\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tif (wouldUpdate !== false) {\n\t\tif (wouldUpdate instanceof Error) {\n\t\t\tthrow wouldUpdate;\n\t\t}\n\t\tif (mode === \"update\") {\n\t\t\tchecker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);\n\t\t\t// Update so errors below will reflect the new snapshot.\n\t\t\tcompatibilityMap.set(\n\t\t\t\tcurrentVersion,\n\t\t\t\tgetCompatibility(currentViewSchema, currentViewSchema),\n\t\t\t);\n\t\t} else {\n\t\t\tcompatibilityErrors.push(\n\t\t\t\t`${wouldUpdate} If this is expected, snapshotSchemaCompatibility can be rerun in \"update\" mode to update or create the snapshot.`,\n\t\t\t);\n\n\t\t\t// This case could update compatibilityMap as well, but it would hide some information about how the existing snapshot might be incompatible with the proposed new one.\n\t\t\t// This lost information could be annoying if the user's intention was not to edit the schema (which is what we assume in assert mode),\n\t\t\t// especially once we produce more detailed error messages that can help users understand what changed in the schema.\n\t\t}\n\t}\n\n\t// Add compatibilityErrors and contextNotes as needed regarding minVersionForCollaboration.\n\t// This is only done when minVersionForCollaboration is not the current version to avoid extra noise in \"assert\" mode\n\t// (which is the only case that could error when minVersionForCollaboration === currentVersion).\n\tif (minVersionForCollaboration !== currentVersion) {\n\t\tif (snapshotUnchangedVersions === true) {\n\t\t\tconst minSnapshot = compatibilityMap.get(minVersionForCollaboration);\n\t\t\tif (minSnapshot === undefined) {\n\t\t\t\tcompatibilityErrors.push(\n\t\t\t\t\t`Using snapshotUnchangedVersions: a snapshot of the exact minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)} is required. No snapshot found.`,\n\t\t\t\t);\n\t\t\t}\n\t\t} else {\n\t\t\tconst selectedMinVersionForCollaborationSnapshot = selectVersionRoundedDown(\n\t\t\t\tminVersionForCollaboration,\n\t\t\t\tcompatibilityMap,\n\t\t\t\tversionComparer,\n\t\t\t);\n\t\t\tif (selectedMinVersionForCollaborationSnapshot === undefined) {\n\t\t\t\tcompatibilityErrors.push(\n\t\t\t\t\t`No snapshot found with version less than or equal to minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)}.`,\n\t\t\t\t);\n\t\t\t} else if (\n\t\t\t\tselectedMinVersionForCollaborationSnapshot[0] !== minVersionForCollaboration\n\t\t\t) {\n\t\t\t\t// Add an entry to ensure that the version which spans from before until after the cutoff for collaboration is included in the compatibility checks.\n\t\t\t\tcompatibilityMap.set(\n\t\t\t\t\tminVersionForCollaboration,\n\t\t\t\t\tselectedMinVersionForCollaborationSnapshot[1],\n\t\t\t\t);\n\t\t\t\tcontextNotes.push(\n\t\t\t\t\t`Due to snapshotUnchangedVersions being false and minVersionForCollaboration (${JSON.stringify(minVersionForCollaboration)}) not having an exact snapshot, the last snapshot before that version (which is ${JSON.stringify(\n\t\t\t\t\t\tselectedMinVersionForCollaborationSnapshot[0],\n\t\t\t\t\t)}) is being also being checked as if it is version ${JSON.stringify(minVersionForCollaboration)}.`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\t// Compare all snapshots against the current schema, using the compatibilityMap.\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\tconst versionComparisonToCurrent = versionComparer(snapshotVersion, currentVersion);\n\t\tif (versionComparisonToCurrent === 0) {\n\t\t\tif (currentVersion !== snapshotVersion) {\n\t\t\t\tthrow errorWithContext(\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 (compatibility.identicalCompatibility === false) {\n\t\t\t\tassert(\n\t\t\t\t\twouldUpdate !== false,\n\t\t\t\t\t0xcd2 / there should have been an error for the snapshot being out of date /,\n\t\t\t\t);\n\t\t\t}\n\t\t} else if (versionComparisonToCurrent < 0) {\n\t\t\t// Collaboration with this version is expected to work.\n\t\t\tif (versionComparer(snapshotVersion, minVersionForCollaboration) >= 0) {\n\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\tif (!compatibility.snapshotViewOfCurrentDocument.canView) {\n\t\t\t\t\tcompatibilityErrors.push(\n\t\t\t\t\t\t`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 ${JSON.stringify(minVersionForCollaboration)}.`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t} else {\n\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// 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}\n\t\t} else {\n\t\t\tcompatibilityErrors.push(\n\t\t\t\t`Snapshot exists for version ${JSON.stringify(snapshotVersion)} which is greater than the current version ${JSON.stringify(currentVersion)}. This is not supported.`,\n\t\t\t);\n\t\t}\n\t}\n\n\tif (compatibilityErrors.length > 0) {\n\t\tthrow errorWithContext(compatibilityErrors.map((e) => ` - ${e}`).join(\"\\n\"));\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, \"\\t\"), {\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(\n\t\tcompare: (a: string, b: string) => number,\n\t): 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(compare);\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\tassert(\n\t\tbackwardsCompatibilityStatus.isEquivalent === forwardsCompatibilityStatus.isEquivalent,\n\t\t0xcd3 / equality should be symmetric /,\n\t);\n\n\t// This relies on exportCompatibilitySchemaSnapshot being well normalized, and not differing for non-significant changes.\n\tconst identicalCompatibility =\n\t\tJSON.stringify(exportCompatibilitySchemaSnapshot(currentViewSchema)) ===\n\t\tJSON.stringify(exportCompatibilitySchemaSnapshot(previousViewSchema));\n\n\tif (identicalCompatibility) {\n\t\tassert(\n\t\t\tbackwardsCompatibilityStatus.isEquivalent,\n\t\t\t0xcd4 / identicalCompatibility should have equivalent stored schema */,\n\t\t);\n\t}\n\n\treturn {\n\t\tcurrentViewOfSnapshotDocument: backwardsCompatibilityStatus,\n\t\tsnapshotViewOfCurrentDocument: forwardsCompatibilityStatus,\n\t\tidenticalCompatibility,\n\t};\n}\n"]}
1	+ {"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, fail, 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 snapshotSchemaCompatibility}.\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 * @beta\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\t/\n\t True if and only if the schema have identical compatibility.\n\t * @remarks\n\t * This includes producing the equivalent stored schema (which currentViewOfSnapshotDocument and snapshotViewOfCurrentDocument also measure)\n\t * as well as equivalent compatibility with potential future schema changes beyond just those in these two schema.\n\t \n\t This includes compatibility with all potential future schema changes.\n\t * For example two schema different only in compatibility with future optional fields via allow unknown optional fields or staged schema\n\t * would be considered non-equivalent, even though they are forwards and backwards compatible with each other, and both status above report them as equivalent\n\t * since they would produce the same stored schema upon schema upgrade.\n\t /\n\treadonly identicalCompatibility: boolean;\n}\n\n/\n The options for {@link snapshotSchemaCompatibility}.\n * @input\n * @beta\n /\nexport interface SnapshotSchemaCompatibilityOptions {\n\t/\n\t Directory where historical schema snapshots are stored.\n\t * @remarks\n\t * As the contents of this directory (specifically historical snapshots) cannot be regenerated,\n\t * a directory appropriate for test data should be used.\n\t * Generally this means that this directory should be versioned like code,\n\t * and not erased when regenerating snapshots.\n\t \n\t This directory will be created if it does not already exist.\n\t * All \".json\" files in this directory will be treated as schema snapshots.\n\t * It is recommended to use a dedicated directory for each {@link snapshotSchemaCompatibility} powered test.\n\t \n\t This can use any path syntax supported by the provided {@link SnapshotSchemaCompatibilityOptions.fileSystem}.\n\t /\n\treadonly snapshotDirectory: string;\n\n\t/\n\t How the `snapshotDirectory` is accessed.\n\t /\n\treadonly fileSystem: SnapshotFileSystem;\n\n\t/\n\t The current view schema.\n\t /\n\treadonly schema: TreeViewConfiguration;\n\n\t/\n\t The version which will be associated with this version of the schema.\n\t * @remarks\n\t * Often the easiest way to ensure this is to simply use the next version which will be released for the package or application itself, and set the `minVersionForCollaboration` based on telemetry about which versions are still in use.\n\t * To do this, it is recommended that this version be programmatically derived from the application version rather than hard coded inline.\n\t * For example, reading it from the `package.json` or some other source of truth can be done to ensure it is kept up to date, and thus snapshots always have the correct version.\n\t * The version used should typically be the _next_ production version (whose formats must be supported long term) that will be released (but is not yet released).\n\t * This usually means that the correct version to use is the same version that would be used when releasing the application or library, but with any prerelease version tags removed.\n\t * If an automated way to keep this version up to date is not used, be very careful when reviewing changes to snapshot files to ensure the version is correct.\n\t * If incorrectly versioned snapshots were committed accidentally, rename the snapshot files to have the correct version, and restore the old files from, version control.\n\t \n\t It is possible to use a different versioning scheme, for example one specific to the schema in question.\n\t * This can be done robustly as long as care is taken to ensure the version increases such that every released version has a unique `version` (and therefore unique snapshot),\n\t * and `minVersionForCollaboration` is set appropriately using the same versioning scheme.\n\t * {@link SnapshotSchemaCompatibilityOptions.rejectVersionsWithNoSchemaChange} and\n\t * {@link SnapshotSchemaCompatibilityOptions.rejectSchemaChangesWithNoVersionChange}\n\t * can be used to help enforce the expected relationship between version changes and schema changes in such cases.\n\t \n\t Can use any format supported by {@link SnapshotSchemaCompatibilityOptions.versionComparer}.\n\t * 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\t Typically `minVersionForCollaboration` should be set to the oldest version currently in use, so it's helpful to use a version which can be easily measured to tell if clients are still using it.\n\t /\n\treadonly version: string;\n\n\t/\n\t The minimum version that the current version is expected to be able to collaborate with.\n\t * @remarks\n\t * Can use any format supported by {@link SnapshotSchemaCompatibilityOptions.versionComparer}.\n\t \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 snapshotSchemaCompatibility} 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 whatever versioning scheme is used with {@link SnapshotSchemaCompatibilityOptions.version}.\n\t /\n\treadonly minVersionForCollaboration: string;\n\n\t/\n\t A comparison function for version strings.\n\t * @remarks\n\t * A comparison function like that provided to {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#comparefn \| Array.sort}.\n\t * This is used to partition snapshots into those less than `minVersionForCollaboration` and those greater than or equal to it, as well as to sanity check `version` against the versions of the snapshots.\n\t * If not provided, the ordering is defined by {@link https://semver.org/#spec-item-11\|semver}.\n\t * @returns A negative number if `a` is less than `b`, zero if they are equal, or a positive number if `a` is greater than `b`.\n\t /\n\treadonly versionComparer?: (a: string, b: string) => number;\n\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\n\t/\n\t When true, it is an error if a new a snapshot for a new version would be created, but the schema compatibility is identical to the previous snapshot.\n\t * @remarks\n\t * This prevents creating a snapshot with the same schema compatibility results as the previous one.\n\t \n\t Applications and libraries which do not have versioned releases can make up a version specific to the compatibility of the schema, and use this option to help ensure they manage that version correctly.\n\t * Such cases can also opt into {@link SnapshotSchemaCompatibilityOptions.rejectSchemaChangesWithNoVersionChange} if they want additional strictness.\n\t /\n\treadonly rejectVersionsWithNoSchemaChange?: true;\n\n\t/\n\t When true, it is an error if a schema change occurs without a corresponding version change.\n\t * @remarks\n\t * This disables overwriting existing snapshots.\n\t * This option is recommended if the {@link SnapshotSchemaCompatibilityOptions.version} is not automatically updated ahead of releasing a version which must be supported.\n\t * If updating the snapshot is still desired, the preceding one which needs to be overwritten can be manually deleted before running the update.\n\t \n\t This option does not impact the behavior of assert mode (other than impacting what error is given).\n\t * This option simply makes update mode more strict, converting cases that would overwrite a snapshot in place into errors.\n\t /\n\treadonly rejectSchemaChangesWithNoVersionChange?: true;\n\n\t/\n\t The mode of operation, either \"assert\" or \"update\".\n\t * @remarks\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 In \"assert\" mode, an error is additionally thrown if the latest snapshot is not up to date (meaning \"update\" mode would make a change).\n\t \n\t In \"update\" mode, a new snapshot is created if the current schema differs from the latest existing snapshot.\n\t * If {@link SnapshotSchemaCompatibilityOptions.rejectVersionsWithNoSchemaChange} or\n\t * {@link SnapshotSchemaCompatibilityOptions.rejectSchemaChangesWithNoVersionChange} disallows the update, an error is thrown instead.\n\t \n\t It is recommended that \"assert\" 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 or version changes.\n\t \n\t @privateRemarks\n\t * Modes we might want to add in the future:\n\t * - normalize: update the latest snapshot (or maybe all of them) to the latest encoded format.\n\t * - some mode like assert but returns information instead of throwing.\n\t /\n\treadonly mode: \"assert\" \| \"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 when using default semver version comparison.\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 Unlike some other snapshot based testing tools, this stores more than just the current snapshot: historical snapshots are retained as well.\n * Retention of these additional historical snapshots, whose content can't be regenerated from the current schema, is necessary to properly test compatibility across versions.\n * Since there is content in the snapshots which cannot be regenerated, tools which assume all snapshotted content can be regenerated cannot be used here.\n * This means that tools like Jest's built in snapshot testing are not suitable for this purpose.\n * These snapshots behave partly like test data, and partly like snapshots.\n * Typically the easiest way to manage this is to place {@link SnapshotSchemaCompatibilityOptions.snapshotDirectory} inside a directory appropriate for test data,\n * and use node to provide the filesystem access via {@link SnapshotSchemaCompatibilityOptions.fileSystem}.\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 schemas 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 schemas 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 * \tsnapshotSchemaCompatibility({\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 * @example Complete Mocha test file\n * ```typescript\n * import fs from \"node:fs\";\n * import path from \"node:path\";\n \n import { snapshotSchemaCompatibility } from \"@fluidframework/tree/beta\";\n \n // The TreeViewConfiguration the application uses, which contains the application's schema.\n * import { treeViewConfiguration } from \"./schema.js\";\n * // The next version of the application which will be released.\n * import { packageVersion } from \"./version.js\";\n \n // Provide some way to run the check in \"update\" mode when updating snapshots is intended.\n * const regenerateSnapshots = process.argv.includes(\"--snapshot\");\n \n // Setup the actual test. In this case using Mocha syntax.\n * describe(\"schema\", () => {\n * \tit(\"schema compatibility\", () => {\n * \t\t// Select a path to save the snapshots in.\n * \t\t// This will depend on how your application organizes its test data.\n * \t\tconst snapshotDirectory = path.join(\n * \t\t\timport.meta.dirname,\n * \t\t\t\"../../../src/test/schema-snapshots\",\n * \t\t);\n * \t\tsnapshotSchemaCompatibility({\n * \t\t\tschema: config,\n * \t\t\tfileSystem: { ...fs, ...path },\n * \t\t\tversion: pkgVersion,\n * \t\t\tminVersionForCollaboration: \"2.0.0\",\n * \t\t\tmode: process.argv.includes(\"--snapshot\") ? \"update\" : \"assert\",\n * \t\t\tsnapshotDirectory,\n * \t\t});\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 This uses the format defined in simpleSchemaCodec.ts.\n * This does include versioning information in the snapshot format,\n * but it would be nice to better unify how we do that versioning and format validation with our codecs.\n \n See snapshotCompatibilityChecker.example.mts for the large example included above.\n * @beta\n /\nexport function snapshotSchemaCompatibility(\n\toptions: SnapshotSchemaCompatibilityOptions,\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\trejectVersionsWithNoSchemaChange,\n\t\trejectSchemaChangesWithNoVersionChange,\n\t} = options;\n\n\tconst validateVersion =\n\t\toptions.versionComparer === undefined ? semver.valid : (v: string) => v;\n\tconst versionComparer = options.versionComparer ?? semver.compare;\n\n\tif (validateVersion(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 (validateVersion(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\n\tif (versionComparer(minVersionForCollaboration, currentVersion) > 0) {\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 !== \"assert\" && mode !== \"update\") {\n\t\tthrow new UsageError(\n\t\t\t`Invalid mode: ${JSON.stringify(mode)}. Must be either \"assert\" or \"update\".`,\n\t\t);\n\t}\n\n\tconst currentEncodedForSnapshotting = exportCompatibilitySchemaSnapshot(currentViewSchema);\n\tconst snapshots = checker.readAllSchemaSnapshots(versionComparer);\n\n\tconst compatibilityErrors: string[] = [];\n\n\tconst contextNotes: string[] = [];\n\n\tfunction errorWithContext(message: string): Error {\n\t\treturn new Error(\n\t\t\t[\n\t\t\t\t\"Schema compatibility check failed:\",\n\t\t\t\tmessage,\n\t\t\t\t`Snapshots in: ${JSON.stringify(options.snapshotDirectory)}`,\n\t\t\t\t`Snapshots exist for versions: ${JSON.stringify([...snapshots.keys()], undefined, \"\\t\")}.`,\n\t\t\t\t...contextNotes,\n\t\t\t].join(\"\\n\"),\n\t\t);\n\t}\n\n\tconst compatibilityMap = transformMapValues(snapshots, (snapshot) =>\n\t\tgetCompatibility(currentViewSchema, snapshot),\n\t);\n\n\t// Either:\n\t// - false: no update needed\n\t// - the updateError message (update in update mode, error otherwise)\n\t// - an error if the update is disallowed by the flags\n\tlet wouldUpdate: false \| string \| Error;\n\n\t// Set wouldUpdate\n\t{\n\t\tconst latestSnapshot = [...snapshots][snapshots.size - 1];\n\t\tif (latestSnapshot === undefined) {\n\t\t\twouldUpdate = `No snapshots found.`;\n\t\t} else {\n\t\t\tconst latestCompatibility =\n\t\t\t\tcompatibilityMap.get(latestSnapshot[0]) ??\n\t\t\t\tfail(0xcd1 / missing compatibilityMap entry /);\n\n\t\t\tconst schemaChange = !latestCompatibility.identicalCompatibility;\n\t\t\tconst versionChange = versionComparer(latestSnapshot[0], currentVersion) !== 0;\n\n\t\t\tif (rejectVersionsWithNoSchemaChange === true && versionChange && !schemaChange) {\n\t\t\t\twouldUpdate = errorWithContext(\n\t\t\t\t\t`Rejecting version change (${JSON.stringify(latestSnapshot[0])} to ${JSON.stringify(currentVersion)}) due to rejectVersionsWithNoSchemaChange being set.`,\n\t\t\t\t);\n\t\t\t} else if (\n\t\t\t\trejectSchemaChangesWithNoVersionChange === true &&\n\t\t\t\tschemaChange &&\n\t\t\t\t!versionChange\n\t\t\t) {\n\t\t\t\twouldUpdate = errorWithContext(\n\t\t\t\t\t`Rejecting schema change without version change due to existing non-equivalent snapshot for version (${JSON.stringify(latestSnapshot[0])} due to rejectSchemaChangesWithNoVersionChange being set.`,\n\t\t\t\t);\n\t\t\t} else if (snapshotUnchangedVersions === true) {\n\t\t\t\tconst currentRead = snapshots.get(currentVersion);\n\t\t\t\tif (currentRead === undefined) {\n\t\t\t\t\twouldUpdate = `No snapshot found for version ${JSON.stringify(currentVersion)}: snapshotUnchangedVersions is true, so every version must be snapshotted.`;\n\t\t\t\t} else if (\n\t\t\t\t\tJSON.stringify(exportCompatibilitySchemaSnapshot(currentRead)) ===\n\t\t\t\t\tJSON.stringify(currentEncodedForSnapshotting)\n\t\t\t\t) {\n\t\t\t\t\twouldUpdate = false;\n\t\t\t\t} else {\n\t\t\t\t\twouldUpdate = `Snapshot for current version ${JSON.stringify(currentVersion)} is out of date.`;\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tif (versionComparer(latestSnapshot[0], currentVersion) <= 0) {\n\t\t\t\t\twouldUpdate = schemaChange\n\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: false;\n\t\t\t\t} else {\n\t\t\t\t\twouldUpdate = errorWithContext(\n\t\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\t);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (!schemaChange && (snapshotUnchangedVersions !== true \|\| !versionChange)) {\n\t\t\t\t// eslint-disable-next-line unicorn/no-lonely-if\n\t\t\t\tif (\n\t\t\t\t\tJSON.stringify(exportCompatibilitySchemaSnapshot(latestSnapshot[1])) !==\n\t\t\t\t\tJSON.stringify(currentEncodedForSnapshotting)\n\t\t\t\t) {\n\t\t\t\t\t// Schema are compatibility wise equivalent, but differ in some way (excluding json formatting).\n\t\t\t\t\t// TODO: add a \"normalize\" mode, which do an update only in this case (or maybe even normalize json formatting as well and just always rewrite when !schemaChange)\n\t\t\t\t\t// This would be useful to minimize diffs from future schema changes.\n\t\t\t\t\t// This would be particularly useful if adding a second version of the format used in the snapshots.\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tif (wouldUpdate !== false) {\n\t\tif (wouldUpdate instanceof Error) {\n\t\t\tthrow wouldUpdate;\n\t\t}\n\t\tif (mode === \"update\") {\n\t\t\tchecker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);\n\t\t\t// Update so errors below will reflect the new snapshot.\n\t\t\tcompatibilityMap.set(\n\t\t\t\tcurrentVersion,\n\t\t\t\tgetCompatibility(currentViewSchema, currentViewSchema),\n\t\t\t);\n\t\t} else {\n\t\t\tcompatibilityErrors.push(\n\t\t\t\t`${wouldUpdate} If this is expected, snapshotSchemaCompatibility can be rerun in \"update\" mode to update or create the snapshot.`,\n\t\t\t);\n\n\t\t\t// This case could update compatibilityMap as well, but it would hide some information about how the existing snapshot might be incompatible with the proposed new one.\n\t\t\t// This lost information could be annoying if the user's intention was not to edit the schema (which is what we assume in assert mode),\n\t\t\t// especially once we produce more detailed error messages that can help users understand what changed in the schema.\n\t\t}\n\t}\n\n\t// Add compatibilityErrors and contextNotes as needed regarding minVersionForCollaboration.\n\t// This is only done when minVersionForCollaboration is not the current version to avoid extra noise in \"assert\" mode\n\t// (which is the only case that could error when minVersionForCollaboration === currentVersion).\n\tif (minVersionForCollaboration !== currentVersion) {\n\t\tif (snapshotUnchangedVersions === true) {\n\t\t\tconst minSnapshot = compatibilityMap.get(minVersionForCollaboration);\n\t\t\tif (minSnapshot === undefined) {\n\t\t\t\tcompatibilityErrors.push(\n\t\t\t\t\t`Using snapshotUnchangedVersions: a snapshot of the exact minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)} is required. No snapshot found.`,\n\t\t\t\t);\n\t\t\t}\n\t\t} else {\n\t\t\tconst selectedMinVersionForCollaborationSnapshot = selectVersionRoundedDown(\n\t\t\t\tminVersionForCollaboration,\n\t\t\t\tcompatibilityMap,\n\t\t\t\tversionComparer,\n\t\t\t);\n\t\t\tif (selectedMinVersionForCollaborationSnapshot === undefined) {\n\t\t\t\tcompatibilityErrors.push(\n\t\t\t\t\t`No snapshot found with version less than or equal to minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)}.`,\n\t\t\t\t);\n\t\t\t} else if (\n\t\t\t\tselectedMinVersionForCollaborationSnapshot[0] !== minVersionForCollaboration\n\t\t\t) {\n\t\t\t\t// Add an entry to ensure that the version which spans from before until after the cutoff for collaboration is included in the compatibility checks.\n\t\t\t\tcompatibilityMap.set(\n\t\t\t\t\tminVersionForCollaboration,\n\t\t\t\t\tselectedMinVersionForCollaborationSnapshot[1],\n\t\t\t\t);\n\t\t\t\tcontextNotes.push(\n\t\t\t\t\t`Due to snapshotUnchangedVersions being false and minVersionForCollaboration (${JSON.stringify(minVersionForCollaboration)}) not having an exact snapshot, the last snapshot before that version (which is ${JSON.stringify(\n\t\t\t\t\t\tselectedMinVersionForCollaborationSnapshot[0],\n\t\t\t\t\t)}) is being also being checked as if it is version ${JSON.stringify(minVersionForCollaboration)}.`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\t// Compare all snapshots against the current schema, using the compatibilityMap.\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\tconst versionComparisonToCurrent = versionComparer(snapshotVersion, currentVersion);\n\t\tif (versionComparisonToCurrent === 0) {\n\t\t\tif (currentVersion !== snapshotVersion) {\n\t\t\t\tthrow errorWithContext(\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 (compatibility.identicalCompatibility === false) {\n\t\t\t\tassert(\n\t\t\t\t\twouldUpdate !== false,\n\t\t\t\t\t0xcd2 / there should have been an error for the snapshot being out of date /,\n\t\t\t\t);\n\t\t\t}\n\t\t} else if (versionComparisonToCurrent < 0) {\n\t\t\t// Collaboration with this version is expected to work.\n\t\t\tif (versionComparer(snapshotVersion, minVersionForCollaboration) >= 0) {\n\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\tif (!compatibility.snapshotViewOfCurrentDocument.canView) {\n\t\t\t\t\tcompatibilityErrors.push(\n\t\t\t\t\t\t`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 ${JSON.stringify(minVersionForCollaboration)}.`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t} else {\n\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// 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}\n\t\t} else {\n\t\t\tcompatibilityErrors.push(\n\t\t\t\t`Snapshot exists for version ${JSON.stringify(snapshotVersion)} which is greater than the current version ${JSON.stringify(currentVersion)}. This is not supported.`,\n\t\t\t);\n\t\t}\n\t}\n\n\tif (compatibilityErrors.length > 0) {\n\t\tthrow errorWithContext(compatibilityErrors.map((e) => ` - ${e}`).join(\"\\n\"));\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, \"\\t\"), {\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(\n\t\tcompare: (a: string, b: string) => number,\n\t): 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(compare);\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\tassert(\n\t\tbackwardsCompatibilityStatus.isEquivalent === forwardsCompatibilityStatus.isEquivalent,\n\t\t0xcd3 / equality should be symmetric /,\n\t);\n\n\t// This relies on exportCompatibilitySchemaSnapshot being well normalized, and not differing for non-significant changes.\n\tconst identicalCompatibility =\n\t\tJSON.stringify(exportCompatibilitySchemaSnapshot(currentViewSchema)) ===\n\t\tJSON.stringify(exportCompatibilitySchemaSnapshot(previousViewSchema));\n\n\tif (identicalCompatibility) {\n\t\tassert(\n\t\t\tbackwardsCompatibilityStatus.isEquivalent,\n\t\t\t0xcd4 / identicalCompatibility should have equivalent stored schema */,\n\t\t);\n\t}\n\n\treturn {\n\t\tcurrentViewOfSnapshotDocument: backwardsCompatibilityStatus,\n\t\tsnapshotViewOfCurrentDocument: forwardsCompatibilityStatus,\n\t\tidenticalCompatibility,\n\t};\n}\n"]}