@fluidframework/tree 2.80.0 → 2.81.0

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

@@ -9,8 +9,8 @@ const internal_1 = require("@fluidframework/core-utils/internal");
 const index_js_1 = require("../../feature-libraries/index.js");
 const index_js_2 = require("../../util/index.js");
 const index_js_3 = require("../core/index.js");
-const treeNodeApi_js_1 = require("./treeNodeApi.js");
 const walkFieldSchema_js_1 = require("../walkFieldSchema.js");
+const treeNodeApi_js_1 = require("./treeNodeApi.js");
 /**
  * Creates a {@link SimpleTreeIndex} with a specified indexer.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"simpleTreeIndex.js","sourceRoot":"","sources":["../../../src/simple-tree/api/simpleTreeIndex.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,kEAA2D;AAO3D,+DAQ0C;AAC1C,kDAA4C;AAE5C,+CAK0B;AAC1B,qDAA+C;AAE/C,8DAAwD;AAoGxD;;;;GAIG;AACH,SAAgB,qBAAqB,CAKpC,IAA4B,EAC5B,OAAuF,EACvF,QAEsE,EACtE,UAA8C,EAC9C,eAA2C;IAE3C,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAE,CAAC;IACrC,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;QACnC,IAAA,oCAAe,EAAC,IAAI,CAAC,MAAM,EAAE;YAC5B,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC;SACtE,CAAC,CAAC;IACJ,CAAC;SAAM,CAAC;QACP,KAAK,MAAM,OAAO,IAAI,eAAe,EAAE,CAAC;YACvC,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACrD,CAAC;IACF,CAAC;IAED,MAAM,aAAa,GAClB,eAAe,KAAK,SAAS;QAC5B,CAAC,CAAC,CAAC,gBAA0C,EAAE,EAAE;YAC/C,wEAAwE;YACxE,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;YACzD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC3B,IAAA,eAAI,EAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;YACzC,CAAC;iBAAM,CAAC;gBACP,MAAM,WAAW,GAChB,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBACzE,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;oBAC/B,OAAO,oBAAoB,CAAO,IAAA,gBAAK,EAAC,WAAW,CAAC,EAAE,UAAU,CAAC,CAAC;gBACnE,CAAC;YACF,CAAC;QACF,CAAC;QACF,CAAC,CAAC,CAAC,gBAA0C,EAAE,EAAE;YAC/C,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;YACzD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC3B,MAAM,WAAW,GAChB,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBACzE,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;oBAC/B,OAAO,oBAAoB,CAAO,IAAA,gBAAK,EAAC,WAAW,CAAC,EAAE,UAAU,CAAC,CAAC;gBACnE,CAAC;YACF,CAAC;QACF,CAAC,CAAC;IAEL,MAAM,KAAK,GAAG,IAAI,0BAAe,CAC/B,IAAiD,CAAC,QAAQ,CAAC,MAAM,EAClE,aAAa,EACb,CAAC,WAAW,EAAE,EAAE;QACf,MAAM,eAAe,GAAe,EAAE,CAAC;QACvC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;YACtC,MAAM,UAAU,GAAG,IAAA,6BAAkB,EAAC,UAAU,CAAC,CAAC;YAClD,IAAI,CAAC,IAAA,sBAAW,EAAC,UAAU,CAAC,EAAE,CAAC;gBAC9B,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAClC,CAAC;QACF,CAAC;QAED,IAAI,IAAA,qBAAU,EAAC,eAAe,CAAC,EAAE,CAAC;YACjC,OAAO,QAAQ,CAAC,eAAe,CAAC,CAAC;QAClC,CAAC;IACF,CAAC,EACD,CAAC,UAAsB,EAAE,EAAE;QAC1B,MAAM,UAAU,GAAG,IAAA,6BAAkB,EAAC,UAAU,CAAC,CAAC;QAClD,IAAI,CAAC,IAAA,sBAAW,EAAC,UAAU,CAAC,EAAE,CAAC;YAC9B,OAAO,4BAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACvC,CAAC;IACF,CAAC;IACD,+FAA+F;IAC/F,IAAI,CACJ,CAAC;IAEF,sFAAsF;IACtF,2CAA2C;IAC3C,OAAO,KAAsC,CAAC;AAC/C,CAAC;AA/ED,sDA+EC;AAED,SAAS,oBAAoB,CAC5B,QAAkB,EAClB,UAA8C;IAE9C,OAAO,CAAC,MAA+B,EAAE,EAAE;QAC1C,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC5B,MAAM,CAAC,SAAS,EAAE,CAAC;QACnB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3B,MAAM,CAAC,QAAQ,EAAE,CAAC;QAClB,MAAM,CAAC,SAAS,EAAE,CAAC;QAEnB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACzB,IAAA,eAAI,EAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;QACtD,CAAC;QAED,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,IAAA,eAAI,EAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACjD,CAAC;QAED,OAAO,KAAK,CAAC;IACd,CAAC,CAAC;AACH,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { fail } from \"@fluidframework/core-utils/internal\";\nimport type {\n\tAnchorNode,\n\tFieldKey,\n\tITreeSubscriptionCursor,\n\tTreeNodeSchemaIdentifier,\n} from \"../../core/index.js\";\nimport {\n\tAnchorTreeIndex,\n\tisTreeValue,\n\ttype TreeIndexNodes,\n\thasElement,\n\ttype TreeIndex,\n\ttype TreeIndexKey,\n\ttype KeyFinder,\n} from \"../../feature-libraries/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport type { ImplicitFieldSchema } from \"../fieldSchema.js\";\nimport {\n\ttreeNodeFromAnchor,\n\ttype TreeNode,\n\ttype TreeNodeSchema,\n\ttype NodeFromSchema,\n} from \"../core/index.js\";\nimport { treeNodeApi } from \"./treeNodeApi.js\";\nimport type { TreeView } from \"./tree.js\";\nimport { walkFieldSchema } from \"../walkFieldSchema.js\";\nimport type { SchematizingSimpleTreeView } from \"../../shared-tree/index.js\";\n\n/**\n * A {@link TreeIndex} that returns tree nodes given their associated keys.\n *\n * @alpha\n */\nexport type SimpleTreeIndex<TKey extends TreeIndexKey, TValue> = TreeIndex<TKey, TValue>;\n\n/**\n * Creates a {@link SimpleTreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema\n * should be keyed on, must be pure and functional\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n *\n * @alpha\n */\nexport function createSimpleTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: (schema: TreeNodeSchema) => string | undefined,\n\tgetValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n): SimpleTreeIndex<TKey, TValue>;\n/**\n * Creates a {@link SimpleTreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema\n * should be keyed on, must be pure and functional\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n * @param indexableSchema - a list of all the schema types that can be indexed\n *\n * @alpha\n */\nexport function createSimpleTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n\tTSchema extends TreeNodeSchema,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: (schema: TSchema) => string | undefined,\n\tgetValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n\tindexableSchema: readonly TSchema[],\n): SimpleTreeIndex<TKey, TValue>;\n/**\n * Creates a {@link SimpleTreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema\n * should be keyed on\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n *\n * @alpha\n */\nexport function createSimpleTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: Map<TreeNodeSchema, string>,\n\tgetValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n): SimpleTreeIndex<TKey, TValue>;\n/**\n * Creates a {@link SimpleTreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema\n * should be keyed on\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n * @param indexableSchema - a list of all the schema types that can be indexed\n *\n * @alpha\n */\nexport function createSimpleTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n\tTSchema extends TreeNodeSchema,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: Map<TreeNodeSchema, string>,\n\tgetValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n\tindexableSchema: readonly TSchema[],\n): SimpleTreeIndex<TKey, TValue>;\n/**\n * Creates a {@link SimpleTreeIndex} with a specified indexer.\n *\n * @alpha\n */\nexport function createSimpleTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: ((schema: TreeNodeSchema) => string | undefined) | Map<TreeNodeSchema, string>,\n\tgetValue:\n\t\t| ((nodes: TreeIndexNodes<TreeNode>) => TValue)\n\t\t| ((nodes: TreeIndexNodes<NodeFromSchema<TreeNodeSchema>>) => TValue),\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n\tindexableSchema?: readonly TreeNodeSchema[],\n): SimpleTreeIndex<TKey, TValue> {\n\tconst indexableSchemaMap = new Map();\n\tif (indexableSchema === undefined) {\n\t\twalkFieldSchema(view.schema, {\n\t\t\tnode: (schemus) => indexableSchemaMap.set(schemus.identifier, schemus),\n\t\t});\n\t} else {\n\t\tfor (const schemus of indexableSchema) {\n\t\t\tindexableSchemaMap.set(schemus.identifier, schemus);\n\t\t}\n\t}\n\n\tconst schemaIndexer =\n\t\tindexableSchema === undefined\n\t\t\t? (schemaIdentifier: TreeNodeSchemaIdentifier) => {\n\t\t\t\t\t// if indexable schema isn't provided, we check if the node is in schema\n\t\t\t\t\tconst schemus = indexableSchemaMap.get(schemaIdentifier);\n\t\t\t\t\tif (schemus === undefined) {\n\t\t\t\t\t\tfail(0xb32 /* node is out of schema */);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tconst keyLocation =\n\t\t\t\t\t\t\ttypeof indexer === \"function\" ? indexer(schemus) : indexer.get(schemus);\n\t\t\t\t\t\tif (keyLocation !== undefined) {\n\t\t\t\t\t\t\treturn makeGenericKeyFinder<TKey>(brand(keyLocation), isKeyValid);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t: (schemaIdentifier: TreeNodeSchemaIdentifier) => {\n\t\t\t\t\tconst schemus = indexableSchemaMap.get(schemaIdentifier);\n\t\t\t\t\tif (schemus !== undefined) {\n\t\t\t\t\t\tconst keyLocation =\n\t\t\t\t\t\t\ttypeof indexer === \"function\" ? indexer(schemus) : indexer.get(schemus);\n\t\t\t\t\t\tif (keyLocation !== undefined) {\n\t\t\t\t\t\t\treturn makeGenericKeyFinder<TKey>(brand(keyLocation), isKeyValid);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t};\n\n\tconst index = new AnchorTreeIndex<TKey, TValue>(\n\t\t(view as SchematizingSimpleTreeView<TFieldSchema>).checkout.forest,\n\t\tschemaIndexer,\n\t\t(anchorNodes) => {\n\t\t\tconst simpleTreeNodes: TreeNode[] = [];\n\t\t\tfor (const anchorNode of anchorNodes) {\n\t\t\t\tconst simpleTree = treeNodeFromAnchor(anchorNode);\n\t\t\t\tif (!isTreeValue(simpleTree)) {\n\t\t\t\t\tsimpleTreeNodes.push(simpleTree);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (hasElement(simpleTreeNodes)) {\n\t\t\t\treturn getValue(simpleTreeNodes);\n\t\t\t}\n\t\t},\n\t\t(anchorNode: AnchorNode) => {\n\t\t\tconst simpleTree = treeNodeFromAnchor(anchorNode);\n\t\t\tif (!isTreeValue(simpleTree)) {\n\t\t\t\treturn treeNodeApi.status(simpleTree);\n\t\t\t}\n\t\t},\n\t\t// simple tree indexes are shallow indexes, indicating so allows for a performance optimization\n\t\ttrue,\n\t);\n\n\t// all the type checking guarantees that we put nodes of the correct type in the index\n\t// but it's not captured in the type system\n\treturn index as SimpleTreeIndex<TKey, TValue>;\n}\n\nfunction makeGenericKeyFinder<TKey extends TreeIndexKey>(\n\tkeyField: FieldKey,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n): KeyFinder<TKey> {\n\treturn (cursor: ITreeSubscriptionCursor) => {\n\t\tcursor.enterField(keyField);\n\t\tcursor.firstNode();\n\t\tconst value = cursor.value;\n\t\tcursor.exitNode();\n\t\tcursor.exitField();\n\n\t\tif (value === undefined) {\n\t\t\tfail(0xb33 /* a value for the key does not exist */);\n\t\t}\n\n\t\tif (!isKeyValid(value)) {\n\t\t\tfail(0xb34 /* the key is an unexpected type */);\n\t\t}\n\n\t\treturn value;\n\t};\n}\n"]}
+{"version":3,"file":"simpleTreeIndex.js","sourceRoot":"","sources":["../../../src/simple-tree/api/simpleTreeIndex.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 { fail } from \"@fluidframework/core-utils/internal\";\n\nimport type {\n\tAnchorNode,\n\tFieldKey,\n\tITreeSubscriptionCursor,\n\tTreeNodeSchemaIdentifier,\n} from \"../../core/index.js\";\nimport {\n\tAnchorTreeIndex,\n\tisTreeValue,\n\ttype TreeIndexNodes,\n\thasElement,\n\ttype TreeIndex,\n\ttype TreeIndexKey,\n\ttype KeyFinder,\n} from \"../../feature-libraries/index.js\";\nimport type { SchematizingSimpleTreeView } from \"../../shared-tree/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\ttreeNodeFromAnchor,\n\ttype TreeNode,\n\ttype TreeNodeSchema,\n\ttype NodeFromSchema,\n} from \"../core/index.js\";\nimport type { ImplicitFieldSchema } from \"../fieldSchema.js\";\nimport { walkFieldSchema } from \"../walkFieldSchema.js\";\n\nimport type { TreeView } from \"./tree.js\";\nimport { treeNodeApi } from \"./treeNodeApi.js\";\n\n/**\n * A {@link TreeIndex} that returns tree nodes given their associated keys.\n *\n * @alpha\n */\nexport type SimpleTreeIndex<TKey extends TreeIndexKey, TValue> = TreeIndex<TKey, TValue>;\n\n/**\n * Creates a {@link SimpleTreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema\n * should be keyed on, must be pure and functional\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n *\n * @alpha\n */\nexport function createSimpleTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: (schema: TreeNodeSchema) => string | undefined,\n\tgetValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n): SimpleTreeIndex<TKey, TValue>;\n/**\n * Creates a {@link SimpleTreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema\n * should be keyed on, must be pure and functional\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n * @param indexableSchema - a list of all the schema types that can be indexed\n *\n * @alpha\n */\nexport function createSimpleTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n\tTSchema extends TreeNodeSchema,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: (schema: TSchema) => string | undefined,\n\tgetValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n\tindexableSchema: readonly TSchema[],\n): SimpleTreeIndex<TKey, TValue>;\n/**\n * Creates a {@link SimpleTreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema\n * should be keyed on\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n *\n * @alpha\n */\nexport function createSimpleTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: Map<TreeNodeSchema, string>,\n\tgetValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n): SimpleTreeIndex<TKey, TValue>;\n/**\n * Creates a {@link SimpleTreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema\n * should be keyed on\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n * @param indexableSchema - a list of all the schema types that can be indexed\n *\n * @alpha\n */\nexport function createSimpleTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n\tTSchema extends TreeNodeSchema,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: Map<TreeNodeSchema, string>,\n\tgetValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n\tindexableSchema: readonly TSchema[],\n): SimpleTreeIndex<TKey, TValue>;\n/**\n * Creates a {@link SimpleTreeIndex} with a specified indexer.\n *\n * @alpha\n */\nexport function createSimpleTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: ((schema: TreeNodeSchema) => string | undefined) | Map<TreeNodeSchema, string>,\n\tgetValue:\n\t\t| ((nodes: TreeIndexNodes<TreeNode>) => TValue)\n\t\t| ((nodes: TreeIndexNodes<NodeFromSchema<TreeNodeSchema>>) => TValue),\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n\tindexableSchema?: readonly TreeNodeSchema[],\n): SimpleTreeIndex<TKey, TValue> {\n\tconst indexableSchemaMap = new Map();\n\tif (indexableSchema === undefined) {\n\t\twalkFieldSchema(view.schema, {\n\t\t\tnode: (schemus) => indexableSchemaMap.set(schemus.identifier, schemus),\n\t\t});\n\t} else {\n\t\tfor (const schemus of indexableSchema) {\n\t\t\tindexableSchemaMap.set(schemus.identifier, schemus);\n\t\t}\n\t}\n\n\tconst schemaIndexer =\n\t\tindexableSchema === undefined\n\t\t\t? (schemaIdentifier: TreeNodeSchemaIdentifier) => {\n\t\t\t\t\t// if indexable schema isn't provided, we check if the node is in schema\n\t\t\t\t\tconst schemus = indexableSchemaMap.get(schemaIdentifier);\n\t\t\t\t\tif (schemus === undefined) {\n\t\t\t\t\t\tfail(0xb32 /* node is out of schema */);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tconst keyLocation =\n\t\t\t\t\t\t\ttypeof indexer === \"function\" ? indexer(schemus) : indexer.get(schemus);\n\t\t\t\t\t\tif (keyLocation !== undefined) {\n\t\t\t\t\t\t\treturn makeGenericKeyFinder<TKey>(brand(keyLocation), isKeyValid);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t: (schemaIdentifier: TreeNodeSchemaIdentifier) => {\n\t\t\t\t\tconst schemus = indexableSchemaMap.get(schemaIdentifier);\n\t\t\t\t\tif (schemus !== undefined) {\n\t\t\t\t\t\tconst keyLocation =\n\t\t\t\t\t\t\ttypeof indexer === \"function\" ? indexer(schemus) : indexer.get(schemus);\n\t\t\t\t\t\tif (keyLocation !== undefined) {\n\t\t\t\t\t\t\treturn makeGenericKeyFinder<TKey>(brand(keyLocation), isKeyValid);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t};\n\n\tconst index = new AnchorTreeIndex<TKey, TValue>(\n\t\t(view as SchematizingSimpleTreeView<TFieldSchema>).checkout.forest,\n\t\tschemaIndexer,\n\t\t(anchorNodes) => {\n\t\t\tconst simpleTreeNodes: TreeNode[] = [];\n\t\t\tfor (const anchorNode of anchorNodes) {\n\t\t\t\tconst simpleTree = treeNodeFromAnchor(anchorNode);\n\t\t\t\tif (!isTreeValue(simpleTree)) {\n\t\t\t\t\tsimpleTreeNodes.push(simpleTree);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (hasElement(simpleTreeNodes)) {\n\t\t\t\treturn getValue(simpleTreeNodes);\n\t\t\t}\n\t\t},\n\t\t(anchorNode: AnchorNode) => {\n\t\t\tconst simpleTree = treeNodeFromAnchor(anchorNode);\n\t\t\tif (!isTreeValue(simpleTree)) {\n\t\t\t\treturn treeNodeApi.status(simpleTree);\n\t\t\t}\n\t\t},\n\t\t// simple tree indexes are shallow indexes, indicating so allows for a performance optimization\n\t\ttrue,\n\t);\n\n\t// all the type checking guarantees that we put nodes of the correct type in the index\n\t// but it's not captured in the type system\n\treturn index as SimpleTreeIndex<TKey, TValue>;\n}\n\nfunction makeGenericKeyFinder<TKey extends TreeIndexKey>(\n\tkeyField: FieldKey,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n): KeyFinder<TKey> {\n\treturn (cursor: ITreeSubscriptionCursor) => {\n\t\tcursor.enterField(keyField);\n\t\tcursor.firstNode();\n\t\tconst value = cursor.value;\n\t\tcursor.exitNode();\n\t\tcursor.exitField();\n\n\t\tif (value === undefined) {\n\t\t\tfail(0xb33 /* a value for the key does not exist */);\n\t\t}\n\n\t\tif (!isKeyValid(value)) {\n\t\t\tfail(0xb34 /* the key is an unexpected type */);\n\t\t}\n\n\t\treturn value;\n\t};\n}\n"]}

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

@@ -107,4 +107,248 @@ export declare function exportCompatibilitySchemaSnapshot(config: Pick<TreeViewC
  * @alpha
  */
 export declare function importCompatibilitySchemaSnapshot(config: JsonCompatibleReadOnly): TreeViewConfiguration;
+/**
+ * The file system methods required by {@link checkSchemaCompatibilitySnapshots}.
+ * @remarks
+ * Implemented by both Node.js `fs` and `path` modules, but other implementations can be provided as needed.
+ *
+ * @example
+ * ```typescript
+ * import path from "node:path";
+ * import fs from "node:fs";
+ *
+ * const nodeFileSystem: SnapshotFileSystem = { ...fs, ...path };
+ * ```
+ *
+ * @privateRemarks
+ * This interface is designed to be compatible with Node.js `fs` and `path` modules.
+ * It is needed to avoid direct dependencies on Node.js APIs in the core library code,
+ * allowing for greater portability and easier testing.
+ *
+ * @input
+ * @alpha
+ */
+export interface SnapshotFileSystem {
+    /**
+     * Writes a UTF-8 encoded file to disk, replacing the file if it already exists.
+     *
+     * @param file - Path to the file to write.
+     * @param data - String data to be written.
+     * @param options - Options specifying that the encoding is UTF-8.
+     */
+    writeFileSync(file: string, data: string, options: {
+        encoding: "utf8";
+    }): void;
+    /**
+     * Reads a UTF-8 encoded file from disk and returns its contents as a string.
+     *
+     * @param file - Path to the file to read.
+     * @param encoding - The text encoding to use when reading the file. Must be `"utf8"`.
+     * @returns The contents of the file as a string.
+     */
+    readFileSync(file: string, encoding: "utf8"): string;
+    /**
+     * How a {@link TreeView} using the snapshotted schema would report its compatibility with a document created with the current schema.
+     *
+     * @param dir - Path of the directory to create.
+     * @param options - Options indicating that creation should be recursive.
+     */
+    mkdirSync(dir: string, options: {
+        recursive: true;
+    }): void;
+    /**
+     * Reads the contents of a directory.
+     *
+     * @param dir - Path of the directory to read.
+     * @returns An array of names of the directory entries.
+     */
+    readdirSync(dir: string): readonly string[];
+    /**
+     * Joins two path segments into a single path string.
+     *
+     * @param parentPath - The directory path.
+     * @param childPath - Filename within `parentPath` directory.
+     * @returns The combined path string.
+     */
+    join(parentPath: string, childPath: string): string;
+}
+/**
+ * The combined compatibility status for both backwards and forwards compatibility checks.
+ */
+export interface CombinedSchemaCompatibilityStatus {
+    /**
+     * How a {@link TreeView} using the current schema would report its compatibility with the historical snapshot.
+     */
+    readonly currentViewOfSnapshotDocument: Omit<SchemaCompatibilityStatus, "canInitialize">;
+    /**
+     * How a {@link TreeView} using the snapshotted schema would report its compatibility with a document created with the current schema.
+     */
+    readonly snapshotViewOfCurrentDocument: Omit<SchemaCompatibilityStatus, "canInitialize">;
+}
+/**
+ * The options for {@link checkSchemaCompatibilitySnapshots}.
+ * @input
+ * @alpha
+ */
+export interface SchemaCompatibilitySnapshotsOptions {
+    /**
+     * Directory where historical schema snapshots are stored.
+     */
+    readonly snapshotDirectory: string;
+    /**
+     * How the `snapshotDirectory` is accessed.
+     */
+    readonly fileSystem: SnapshotFileSystem;
+    /**
+     * The current application or library version.
+     * @remarks
+     * This uses the {@link https://semver.org/#spec-item-11|ordering defined by semver}.
+     * It is only compared against the version from previous snapshots (taken from this version when they were created by setting `mode` to "update") and the `minVersionForCollaboration`.
+     */
+    readonly version: string;
+    /**
+     * The current view schema.
+     */
+    readonly schema: TreeViewConfiguration;
+    /**
+     * The minimum version that the current version is expected to be able to collaborate with.
+     * @remarks
+     * This defines a range of versions whose schema must be forwards compatible with trees using the current schema:
+     * Any schema from snapshots with a version greater than or equal to this must be able to view documents created with the current schema.
+     * This means that if the current `schema` is used to create a {@link TreeView}, then {@link TreeView.upgradeSchema} is used, the older clients,
+     * all the way back to this `minVersionForCollaboration` will be able to view and edit the tree using their schema and thus collaborate.
+     *
+     * Typically applications will attempt to manage their deployment/update schedule such that all versions concurrently deployed can
+     * collaborate to avoid users losing access to documents when other users upgrade the schema.
+     * Such applications can set this to the oldest version currently deployed,
+     * then rely on {@link checkSchemaCompatibilitySnapshots} to verify that no schema changes are made which would break collaboration with that (or newer) versions.
+     *
+     * This is the same approach used by {@link @fluidframework/runtime-definitions#MinimumVersionForCollab}
+     * except that type is specifically for use with the version of the Fluid Framework client packages,
+     * and this corresponds to the version of the application or library defining the schema.
+     */
+    readonly minVersionForCollaboration: string;
+    /**
+     * When true, every version must be snapshotted, and an increased version number will require a new snapshot.
+     * @remarks
+     * 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.
+     * 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`
+     * can refer to versions between snapshots and will get its schema from the preceding version.
+     */
+    readonly snapshotUnchangedVersions?: true;
+    /**
+     * The mode of operation, either "test" or "update".
+     * @remarks
+     * In "update" mode, a new snapshot is created if the current schema differs from the latest existing snapshot.
+     * Note: {@link SchemaCompatibilitySnapshotsOptions.snapshotUnchangedVersions} impacts this behavior.
+     *
+     * In "test" mode, an error is thrown if running in "update" mode would have made any changes.
+     *
+     * 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).
+     *
+     * It is recommended that "test" mode be used in automated tests to verify schema compatibility,
+     * and "update" mode only be used manually to update snapshots when making schema changes (or version changes if `snapshotUnchangedVersions` is true).
+     */
+    readonly mode: "test" | "update";
+}
+/**
+ * Check `currentViewSchema` for compatibility with a collection of historical schema snapshots stored in `snapshotDirectory`.
+ *
+ * @throws Throws errors if the input version strings (including those in snapshot file names) are not valid semver versions.
+ * @throws Throws errors if the input version strings (including those in snapshot file names) are not ordered as expected (current being the highest, and `minVersionForCollaboration` corresponding to the current version or a lower snapshotted version).
+ * @throws In `test` mode, throws an error if there is not an up to date snapshot for the current version.
+ * @throws Throws an error if any snapshotted schema cannot be upgraded to the current schema.
+ * @throws Throws an error if any snapshotted schema with a version greater than or equal to `minVersionForCollaboration` cannot view documents created with the current schema.
+ * @remarks
+ * This is intended for use in snapshot-based schema compatibility tests.
+ * Every SharedTree-based component or application with a schema is recommended to use this to verify schema compatibility across versions.
+ *
+ * Schema snapshots should be added to `snapshotDirectory` using this function in "update" mode whenever the schema changes in a compatibility impacting way
+ * (or when `snapshotUnchangedVersions` is true and a new version about to be released is getting prepared for release (and thus `version` changed)).
+ *
+ * This will throw an exception if any snapshotted schema would result in documents that cannot be viewed (after using {@link TreeView.upgradeSchema}), or if any schema with a version greater than or equal to `minVersionForCollaboration` cannot view documents created with the `currentViewSchema`.
+ * See {@link TreeView.compatibility} for more information.
+ *
+ * Proper use of this utility should do a good job at detecting schema compatibility issues,
+ * however it currently does not do a good job of explaining exactly what change to the schema is causing the compatibility issues.
+ * This is a known limitation that will be improved in future releases.
+ * These improvements, as well as other changes, may change the exact messages produced by this function in the error cases: no stability of these messages should be assumed.
+ *
+ * For now, locating what change broke compatibility is likely best discovered by making small schema changes one at a time and updating the snapshot and reviewing the diffs.
+ * Details for what kinds of changes are breaking and in which ways can be found in the documentation for {@link TreeView.compatibility} and
+ * {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution/ | schema-evolution}.
+ *
+ * This utility does not enforce anything with respect to API compatibility, or special semantics for major, minor, or patch versions.
+ * Libraries which export schema for use by others will need to take special care to ensure the stability contract they offer their users aligns which what is validated by this utility.
+ *
+ * This utility only tests compatibility of the historical snapshots against the current schema; it does not test them against each-other.
+ * Generally any historical schema should have been tested against the ones before them at the time they were current.
+ * If for some reason a version of a schema made it into production that was not compatible with a previous version,
+ * that can still be represented here (but may require manually generating a snapshot for that version)
+ * and this will still allow testing that all historical version can be upgraded to the current one.
+ * If a sufficiently incompatible historical schema were used in production, it may be impossible to make a single schema which can accommodate all of them:
+ * this utility can be used to confirm that is the case, as well as to avoid the problem in the first place by testing schema before each one is deployed.
+ *
+ * @example Mocha test which validates the current `config` can collaborate with all historical version back to 2.0.0, and load and update any versions older than that.
+ * ```typescript
+ * it("schema compatibility", () => {
+ * 	checkSchemaCompatibilitySnapshots({
+ * 		version: pkgVersion,
+ * 		schema: config,
+ * 		fileSystem: { ...fs, ...path },
+ * 		minVersionForCollaboration: "2.0.0",
+ * 		mode: process.argv.includes("--snapshot") ? "update" : "test",
+ * 		snapshotDirectory,
+ * 	});
+ * });
+ * ```
+ * @privateRemarks
+ * Use of this function within this package (for schema libraries released as part of this package) should use {@link testSchemaCompatibilitySnapshots} instead.
+ *
+ * TODO: this uses the format defined in simpleSchemaCodec.ts.
+ * Currently this does not include any versioning information in the snapshot format itself.
+ * This would make it hard to do things like upgrade to a new format (perhaps for better diffs, or to support new features) in the future.
+ * That code should probably be migrated to a proper versioned codec with a schema and validation.
+ * This utility can directly depend on the typebox-validator and inject that as this code should not be bundle size sensitive.
+ * This should be addressed before this reached beta stability.
+ * @alpha
+ */
+export declare function checkSchemaCompatibilitySnapshots(options: SchemaCompatibilitySnapshotsOptions): void;
+/**
+ * The high-level API for checking snapshot compatibility and generating new snapshots.
+ */
+export declare class SnapshotCompatibilityChecker {
+    /**
+     * Directory where historical schema snapshots are stored.
+     */
+    private readonly snapshotDirectory;
+    /**
+     * How the `snapshotDirectory` is accessed.
+     */
+    private readonly fileSystemMethods;
+    constructor(
+    /**
+     * Directory where historical schema snapshots are stored.
+     */
+    snapshotDirectory: string, 
+    /**
+     * How the `snapshotDirectory` is accessed.
+     */
+    fileSystemMethods: SnapshotFileSystem);
+    writeSchemaSnapshot(snapshotName: string, snapshot: JsonCompatibleReadOnly): void;
+    readSchemaSnapshot(snapshotName: string): TreeViewConfiguration;
+    readSchemaSnapshotRaw(snapshotName: string): JsonCompatibleReadOnly;
+    /**
+     * Returns all schema snapshots stored in the snapshot directory, sorted in order of increasing version.
+     */
+    readAllSchemaSnapshots(): Map<string, TreeViewConfiguration>;
+    ensureSnapshotDirectoryExists(): void;
+}
+/**
+ * Gets the compatibility of the current view schema against a historical snapshot.
+ * @param currentViewSchema - The current view schema.
+ * @param previousViewSchema - The historical view schema.
+ * @returns The combined compatibility status.
+ */
+export declare function getCompatibility(currentViewSchema: TreeViewConfiguration, previousViewSchema: TreeViewConfiguration): CombinedSchemaCompatibilityStatus;
 //# sourceMappingURL=snapshotCompatibilityChecker.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"snapshotCompatibilityChecker.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/snapshotCompatibilityChecker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAElE,OAAO,EAA8B,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAQvF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,kBAAkB,CACjC,4BAA4B,EAAE,qBAAqB,EACnD,IAAI,EAAE,qBAAqB,GACzB,IAAI,CAAC,yBAAyB,EAAE,eAAe,CAAC,CAKlD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iCAAiC,CAChD,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAC,GAC3C,sBAAsB,CAGxB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iCAAiC,CAChD,MAAM,EAAE,sBAAsB,GAC5B,qBAAqB,CAOvB"}
+{"version":3,"file":"snapshotCompatibilityChecker.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/snapshotCompatibilityChecker.ts"],"names":[],"mappings":"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"}

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

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