npm - @fluidframework/tree - Versions diffs - 2.82.0 → 2.83.0 - Mend

@fluidframework/tree 2.82.0 → 2.83.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 (281) hide show

package/dist/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,kEAAiF;AACjF,qEAAkF;AAClF,uEAAsE;AACtE,kDAAoC;AAGpC,4DAAuD;AACvD,oDAAoD;AAEpD,yDAAuF;AACvF,iFAA2E;AAC3E,+DAAuE;AACvE,iEAGgC;AAGhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,SAAgB,kBAAkB,CACjC,4BAAmD,EACnD,IAA2B;IAE3B,MAAM,WAAW,GAAG,IAAI,6CAA0B,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,MAAM,MAAM,GAAG,IAAA,mCAAe,EAAC,4BAA4B,CAAC,MAAM,CAAC,CAAC;IACpE,MAAM,MAAM,GAAG,IAAI,wDAAyB,CAAC,WAAW,CAAC,CAAC;IAC1D,OAAO,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC;AARD,gDAQC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,SAAgB,iCAAiC,CAChD,MAA6C;IAE7C,MAAM,UAAU,GAAG,IAAA,gCAAgB,EAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACnD,OAAO,IAAA,wDAAiC,EAAC,UAAU,CAAC,CAAC;AACtD,CAAC;AALD,8EAKC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,iCAAiC,CAChD,MAA8B;IAE9B,MAAM,YAAY,GAAG,IAAA,wDAAiC,EAAC,MAAM,CAAC,CAAC;IAC/D,MAAM,UAAU,GAAG,IAAA,oDAA8B,EAAC,YAAY,CAAC,CAAC;IAEhE,+HAA+H;IAC/H,yDAAyD;IACzD,OAAO,IAAI,wCAAqB,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;AAC/D,CAAC;AATD,8EASC;AAsJD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,SAAgB,iCAAiC,CAChD,OAA4C;IAE5C,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,GACzB,GAAG,OAAO,CAAC;IACZ,IAAI,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,IAAI,EAAE,CAAC;QAC3C,MAAM,IAAI,qBAAU,CACnB,oBAAoB,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,mCAAmC,CACrF,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,KAAK,IAAI,EAAE,CAAC;QACvD,MAAM,IAAI,qBAAU,CACnB,uCAAuC,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC,mCAAmC,CACpH,CAAC;IACH,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,0BAA0B,EAAE,cAAc,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,qBAAU,CACnB,uCAAuC,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC,mDAAmD,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,GAAG,CACrK,CAAC;IACH,CAAC;IAED,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC1C,MAAM,IAAI,qBAAU,CACnB,iBAAiB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,sCAAsC,CAC3E,CAAC;IACH,CAAC;IAED,MAAM,6BAA6B,GAAG,iCAAiC,CAAC,iBAAiB,CAAC,CAAC;IAC3F,MAAM,SAAS,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC;IAEnD,MAAM,mBAAmB,GAAa,EAAE,CAAC;IAEzC,SAAS,cAAc,CAAC,OAAe;QACtC,IAAA,iBAAM,EAAC,IAAI,KAAK,MAAM,EAAE,KAAK,CAAC,uDAAuD,CAAC,CAAC;QACvF,mBAAmB,CAAC,IAAI,CACvB,GAAG,OAAO,+GAA+G,CACzH,CAAC;IACH,CAAC;IAED,IAAI,yBAAyB,KAAK,IAAI,EAAE,CAAC;QACxC,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvB,OAAO,CAAC,mBAAmB,CAAC,cAAc,EAAE,6BAA6B,CAAC,CAAC;YAC3E,SAAS,CAAC,GAAG,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC;QAClD,CAAC;aAAM,CAAC;YACP,MAAM,WAAW,GAAG,SAAS,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;YAClD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;gBAC/B,cAAc,CACb,iCAAiC,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,4EAA4E,CAC3I,CAAC;YACH,CAAC;iBAAM,IACN,IAAI,CAAC,SAAS,CAAC,iCAAiC,CAAC,WAAW,CAAC,CAAC;gBAC9D,IAAI,CAAC,SAAS,CAAC,6BAA6B,CAAC,EAC5C,CAAC;gBACF,cAAc,CACb,gCAAgC,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,kBAAkB,CAChF,CAAC;YACH,CAAC;QACF,CAAC;IACF,CAAC;SAAM,CAAC;QACP,MAAM,OAAO,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC;QAC/B,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACnD,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvB,OAAO,CAAC,mBAAmB,CAAC,cAAc,EAAE,6BAA6B,CAAC,CAAC;gBAC3E,SAAS,CAAC,GAAG,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC;YAClD,CAAC;iBAAM,CAAC;gBACP,cAAc,CAAC,qBAAqB,CAAC,CAAC;YACvC,CAAC;QACF,CAAC;aAAM,CAAC;YACP,IAAI,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,EAAE,CAAC;gBACnD,kFAAkF;gBAClF,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,iCAAiC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBACvF,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC,6BAA6B,CAAC,CAAC;gBACpE,IAAI,SAAS,KAAK,aAAa,EAAE,CAAC;oBACjC,gDAAgD;oBAChD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;wBACvB,OAAO,CAAC,mBAAmB,CAAC,cAAc,EAAE,6BAA6B,CAAC,CAAC;wBAC3E,SAAS,CAAC,GAAG,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC;oBAClD,CAAC;yBAAM,CAAC;wBACP,cAAc,CACb,gCAAgC,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,8EAA8E,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,CAChL,CAAC;oBACH,CAAC;gBACF,CAAC;YACF,CAAC;iBAAM,CAAC;gBACP,MAAM,IAAI,qBAAU,CACnB,mBAAmB,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,kDAAkD,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,kDAAkD,CACtL,CAAC;YACH,CAAC;QACF,CAAC;IACF,CAAC;IAED,MAAM,gBAAgB,GAAG,IAAA,6BAAkB,EAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,EAAE,CACnE,gBAAgB,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAC7C,CAAC;IAEF,IAAI,0CAEmD,CAAC;IAExD,IAAI,yBAAyB,KAAK,IAAI,EAAE,CAAC;QACxC,MAAM,WAAW,GAAG,gBAAgB,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;QACrE,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC/B,mBAAmB,CAAC,IAAI,CACvB,uFAAuF,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC,kCAAkC,CACnK,CAAC;QACH,CAAC;aAAM,CAAC;YACP,0CAA0C,GAAG,CAAC,0BAA0B,EAAE,WAAW,CAAC,CAAC;QACxF,CAAC;IACF,CAAC;SAAM,CAAC;QACP,0CAA0C,GAAG,IAAA,mCAAwB,EACpE,0BAA0B,EAC1B,gBAAgB,CAChB,CAAC;QACF,IAAI,0CAA0C,KAAK,SAAS,EAAE,CAAC;YAC9D,mBAAmB,CAAC,IAAI,CACvB,mFAAmF,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC,GAAG,CAChI,CAAC;QACH,CAAC;IACF,CAAC;IAED,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,IAAI,MAAM,CAAC,EAAE,CAAC,eAAe,EAAE,cAAc,CAAC,EAAE,CAAC;YAChD,IAAI,cAAc,KAAK,eAAe,EAAE,CAAC;gBACxC,MAAM,IAAI,qBAAU,CACnB,oBAAoB,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,kEAAkE,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,0BAA0B,CAC7K,CAAC;YACH,CAAC;YACD,IACC,aAAa,CAAC,6BAA6B,CAAC,YAAY,KAAK,KAAK;gBAClE,aAAa,CAAC,6BAA6B,CAAC,YAAY,KAAK,KAAK,EACjE,CAAC;gBACF,mBAAmB,CAAC,IAAI,CACvB,mBAAmB,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,6CAA6C,CAC/F,CAAC;YACH,CAAC;QACF,CAAC;aAAM,IAAI,MAAM,CAAC,EAAE,CAAC,eAAe,EAAE,cAAc,CAAC,EAAE,CAAC;YACvD,IAAI,0CAA0C,KAAK,SAAS,EAAE,CAAC;gBAC9D,IAAA,iBAAM,EACL,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAC9B,KAAK,CAAC,2EAA2E,CACjF,CAAC;YACH,CAAC;iBAAM,CAAC;gBACP,uDAAuD;gBACvD,IAAI,MAAM,CAAC,GAAG,CAAC,eAAe,EAAE,0CAA0C,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;oBAChF,wIAAwI;oBACxI,IAAI,CAAC,aAAa,CAAC,6BAA6B,CAAC,OAAO,EAAE,CAAC;wBAC1D,MAAM,OAAO,GAAG,sBAAsB,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,+BAA+B,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,iIAAiI,IAAI,CAAC,SAAS,CAAC,0CAA0C,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;wBACpU,mBAAmB,CAAC,IAAI,CACvB,0CAA0C,CAAC,CAAC,CAAC,KAAK,0BAA0B;4BAC3E,CAAC,CAAC,OAAO;4BACT,CAAC,CAAC,GAAG,OAAO,gDAAgD,IAAI,CAAC,SAAS,CAAC,0BAA0B,CAAC,kDAAkD,CACzJ,CAAC;oBACH,CAAC;gBACF,CAAC;qBAAM,CAAC;oBACP,oGAAoG;oBACpG,qKAAqK;gBACtK,CAAC;YACF,CAAC;QACF,CAAC;aAAM,CAAC;YACP,MAAM,IAAI,qBAAU,CACnB,gEAAgE,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,oBAAoB,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,GAAG,CACpJ,CAAC;QACH,CAAC;IACF,CAAC;IAED,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACd,uCAAuC,mBAAmB;aACxD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;aACrB,IAAI,CAAC,IAAI,CAAC,EAAE,CACd,CAAC;IACH,CAAC;AACF,CAAC;AA7LD,8EA6LC;AAED;;GAEG;AACH,MAAa,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,CAAC,CAAC,EAAE;YACtF,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;QAC5B,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,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAE9C,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;AAjED,oEAiEC;AAED;;;;;GAKG;AACH,SAAgB,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,OAAO;QACN,6BAA6B,EAAE,4BAA4B;QAC3D,6BAA6B,EAAE,2BAA2B;KAC1D,CAAC;AACH,CAAC;AAlBD,4CAkBC","sourcesContent":["/!\n Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n /\n\nimport { assert, transformMapValues } from \"@fluidframework/core-utils/internal\";\nimport { selectVersionRoundedDown } from \"@fluidframework/runtime-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport as semver from \"semver-ts\";\n\nimport type { JsonCompatibleReadOnly } from \"../../util/index.js\";\nimport { toInitialSchema } from \"../toStoredSchema.js\";\nimport { createTreeSchema } from \"../treeSchema.js\";\n\nimport { TreeViewConfigurationAlpha, TreeViewConfiguration } from \"./configuration.js\";\nimport { SchemaCompatibilityTester } from \"./schemaCompatibilityTester.js\";\nimport { generateSchemaFromSimpleSchema } from \"./schemaFromSimple.js\";\nimport {\n\tdecodeSchemaCompatibilitySnapshot,\n\tencodeSchemaCompatibilitySnapshot,\n} from \"./simpleSchemaCodec.js\";\nimport type { SchemaCompatibilityStatus } from \"./tree.js\";\n\n/*\n Compute the compatibility of using `view` to {@link ViewableTree.viewWith \| view a tree} who's {@link ITreeAlpha.exportSimpleSchema \| stored schema} could be derived from `viewWhichCreatedStoredSchema` via either {@link TreeView.initialize} or {@link TreeView.upgradeSchema}.\n \n @remarks See {@link SchemaCompatibilityStatus} for details on the compatibility results.\n \n @example This example demonstrates checking the compatibility of a historical schema against a current schema.\n * In this case, the historical schema is a Point2D object with x and y fields, while the current schema is a Point3D object\n * that adds an optional z field.\n \n ```ts\n * // This snapshot is assumed to be the same as Point3D, except missing `z`.\n * const encodedSchema = JSON.parse(fs.readFileSync(\"PointSchema.json\", \"utf8\"));\n * const oldViewSchema = importCompatibilitySchemaSnapshot(encodedSchema);\n \n // Build the current view schema\n * class Point3D extends factory.object(\"Point\", {\n * \tx: factory.number,\n * \ty: factory.number,\n \n \t// The current schema has a new optional field that was not present on Point2D\n * \tz: factory.optional(factory.number),\n * }) {}\n * const currentViewSchema = new TreeViewConfiguration({ schema: Point3D });\n \n // Check to see if the document created by the historical view schema can be opened with the current view schema\n * const backwardsCompatibilityStatus = checkCompatibility(oldViewSchema, currentViewSchema);\n \n // z is not present in Point2D, so the schema must be upgraded\n * assert.equal(backwardsCompatibilityStatus.canView, false);\n \n // The schema can be upgraded to add the new optional field\n * assert.equal(backwardsCompatibilityStatus.canUpgrade, true);\n \n // Test what the old version of the application would do with a tree using the new schema:\n * const forwardsCompatibilityStatus = checkCompatibility(currentViewSchema, oldViewSchema);\n \n // If the old schema set allowUnknownOptionalFields, this would be true, but since it did not,\n * // this assert will fail, detecting the forwards compatibility break:\n * // this means these two versions of the application cannot collaborate on content using these schema.\n * assert.equal(forwardsCompatibilityStatus.canView, true);\n * ```\n \n @param viewWhichCreatedStoredSchema - From which to derive the stored schema, as if it initialized or upgraded a tree via {@link TreeView}.\n * @param view - The view being tested to see if it could view tree created or initialized using `viewWhichCreatedStoredSchema`.\n * @returns The compatibility status.\n \n @privateRemarks\n * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.\n \n @alpha\n /\nexport function checkCompatibility(\n\tviewWhichCreatedStoredSchema: TreeViewConfiguration,\n\tview: TreeViewConfiguration,\n): Omit<SchemaCompatibilityStatus, \"canInitialize\"> {\n\tconst viewAsAlpha = new TreeViewConfigurationAlpha({ schema: view.schema });\n\tconst stored = toInitialSchema(viewWhichCreatedStoredSchema.schema);\n\tconst tester = new SchemaCompatibilityTester(viewAsAlpha);\n\treturn tester.checkCompatibility(stored);\n}\n\n/\n Returns a JSON compatible representation of the tree schema for snapshot compatibility checking.\n \n Snapshots can be loaded by the same or newer package versions, but not necessarily older versions.\n \n @see {@link importCompatibilitySchemaSnapshot} which loads these snapshots.\n \n @param config - The schema to snapshot. Only the schema field of the `TreeViewConfiguration` is used.\n * @returns The JSON representation of the schema.\n \n @example This example creates and persists a snapshot of a Point2D schema.\n \n ```ts\n * const schemaFactory = new SchemaFactory(\"test\");\n * class Point2D extends schemaFactory.object(\"Point\", {\n * \tx: factory.number,\n * \ty: factory.number,\n * }) {}\n * const viewSchema = new TreeViewConfiguration({ schema: Point2D });\n * const encodedSchema = JSON.stringify(exportCompatibilitySchemaSnapshot(viewSchema));\n * fs.writeFileSync(\"PointSchema.json\", encodedSchema);\n * ```\n \n @privateRemarks\n * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.\n \n @alpha\n /\nexport function exportCompatibilitySchemaSnapshot(\n\tconfig: Pick<TreeViewConfiguration, \"schema\">,\n): JsonCompatibleReadOnly {\n\tconst treeSchema = createTreeSchema(config.schema);\n\treturn encodeSchemaCompatibilitySnapshot(treeSchema);\n}\n\n/\n Parse the format exported by {@link exportCompatibilitySchemaSnapshot} into a schema.\n \n Can load snapshots created by the same or older package versions, but not necessarily newer versions.\n \n @see {@link exportCompatibilitySchemaSnapshot} which creates these snapshots.\n \n @param config - The JSON representation of the schema.\n * @returns The schema. Only the schema field of the {@link TreeViewConfiguration} is populated.\n * @throws Will throw a usage error if the encoded schema is not in the expected format.\n \n @example This example loads and parses a snapshot of a Point2D schema.\n \n ```ts;\n * const oldViewSchema = importCompatibilitySchemaSnapshot(fs.readFileSync(\"PointSchema.json\", \"utf8\"));\n * ```\n * @privateRemarks\n * TODO: a simple high level API for snapshot based schema compatibility checking should replace the need to export this.\n * @alpha\n /\nexport function importCompatibilitySchemaSnapshot(\n\tconfig: JsonCompatibleReadOnly,\n): TreeViewConfiguration {\n\tconst simpleSchema = decodeSchemaCompatibilitySnapshot(config);\n\tconst viewSchema = generateSchemaFromSimpleSchema(simpleSchema);\n\n\t// We construct a TreeViewConfiguration here with the default parameters. The default set of validation parameters are fine for\n\t// a schema produced by `generateSchemaFromSimpleSchema`.\n\treturn new TreeViewConfiguration({ schema: viewSchema.root });\n}\n\n/\n The file system methods required by {@link checkSchemaCompatibilitySnapshots}.\n * @remarks\n * Implemented by both Node.js `fs` and `path` modules, but other implementations can be provided as needed.\n \n @example\n * ```typescript\n * import path from \"node:path\";\n * import fs from \"node:fs\";\n \n const nodeFileSystem: SnapshotFileSystem = { ...fs, ...path };\n * ```\n \n @privateRemarks\n * This interface is designed to be compatible with Node.js `fs` and `path` modules.\n * It is needed to avoid direct dependencies on Node.js APIs in the core library code,\n * allowing for greater portability and easier testing.\n \n @input\n * @alpha\n /\nexport interface SnapshotFileSystem {\n\t/\n\t Writes a UTF-8 encoded file to disk, replacing the file if it already exists.\n\t \n\t @param file - Path to the file to write.\n\t * @param data - String data to be written.\n\t * @param options - Options specifying that the encoding is UTF-8.\n\t /\n\twriteFileSync(file: string, data: string, options: { encoding: \"utf8\" }): void;\n\n\t/\n\t Reads a UTF-8 encoded file from disk and returns its contents as a string.\n\t \n\t @param file - Path to the file to read.\n\t * @param encoding - The text encoding to use when reading the file. Must be `\"utf8\"`.\n\t * @returns The contents of the file as a string.\n\t /\n\t// We include the encoding here to match the function overload for readFileSync that returns a string.\n\treadFileSync(file: string, encoding: \"utf8\"): string;\n\n\t/\n\t How a {@link TreeView} using the snapshotted schema would report its compatibility with a document created with the current schema.\n\t \n\t @param dir - Path of the directory to create.\n\t * @param options - Options indicating that creation should be recursive.\n\t /\n\tmkdirSync(dir: string, options: { recursive: true }): void;\n\n\t/\n\t Reads the contents of a directory.\n\t \n\t @param dir - Path of the directory to read.\n\t * @returns An array of names of the directory entries.\n\t /\n\treaddirSync(dir: string): readonly string[];\n\n\t/\n\t Joins two path segments into a single path string.\n\t \n\t @param parentPath - The directory path.\n\t * @param childPath - Filename within `parentPath` directory.\n\t * @returns The combined path string.\n\t /\n\tjoin(parentPath: string, childPath: string): string;\n}\n\n/\n The combined compatibility status for both backwards and forwards compatibility checks.\n /\nexport interface CombinedSchemaCompatibilityStatus {\n\t/\n\t How a {@link TreeView} using the current schema would report its compatibility with the historical snapshot.\n\t /\n\treadonly currentViewOfSnapshotDocument: Omit<SchemaCompatibilityStatus, \"canInitialize\">;\n\t/\n\t How a {@link TreeView} using the snapshotted schema would report its compatibility with a document created with the current schema.\n\t /\n\treadonly snapshotViewOfCurrentDocument: Omit<SchemaCompatibilityStatus, \"canInitialize\">;\n}\n\n/\n The options for {@link checkSchemaCompatibilitySnapshots}.\n * @input\n * @alpha\n /\nexport interface SchemaCompatibilitySnapshotsOptions {\n\t/\n\t Directory where historical schema snapshots are stored.\n\t /\n\treadonly snapshotDirectory: string;\n\t/\n\t How the `snapshotDirectory` is accessed.\n\t /\n\treadonly fileSystem: SnapshotFileSystem;\n\t/\n\t The current application or library version.\n\t * @remarks\n\t * This uses the {@link https://semver.org/#spec-item-11\|ordering defined by semver}.\n\t * It is only compared against the version from previous snapshots (taken from this version when they were created by setting `mode` to \"update\") and the `minVersionForCollaboration`.\n\t /\n\treadonly version: string;\n\t/\n\t The current view schema.\n\t /\n\treadonly schema: TreeViewConfiguration;\n\t/\n\t The minimum version that the current version is expected to be able to collaborate with.\n\t * @remarks\n\t * This defines a range of versions whose schema must be forwards compatible with trees using the current schema:\n\t * Any schema from snapshots with a version greater than or equal to this must be able to view documents created with the current schema.\n\t * This means that if the current `schema` is used to create a {@link TreeView}, then {@link TreeView.upgradeSchema} is used, the older clients,\n\t * all the way back to this `minVersionForCollaboration` will be able to view and edit the tree using their schema and thus collaborate.\n\t \n\t Typically applications will attempt to manage their deployment/update schedule such that all versions concurrently deployed can\n\t * collaborate to avoid users losing access to documents when other users upgrade the schema.\n\t * Such applications can set this to the oldest version currently deployed,\n\t * then rely on {@link checkSchemaCompatibilitySnapshots} to verify that no schema changes are made which would break collaboration with that (or newer) versions.\n\t \n\t This is the same approach used by {@link @fluidframework/runtime-definitions#MinimumVersionForCollab}\n\t * except that type is specifically for use with the version of the Fluid Framework client packages,\n\t * and this corresponds to the version of the application or library defining the schema.\n\t /\n\treadonly minVersionForCollaboration: string;\n\t/\n\t When true, every version must be snapshotted, and an increased version number will require a new snapshot.\n\t * @remarks\n\t * If this is true, it is assumed there is a snapshot for every release, and thus it is required that the `minVersionForCollaboration` refer to a version which has a snapshot.\n\t * When this is not true, versions without snapshots are assumed to have the same schema as the latest previous version which has a snapshot, and thus `minVersionForCollaboration`\n\t * can refer to versions between snapshots and will get its schema from the preceding version.\n\t /\n\treadonly snapshotUnchangedVersions?: true;\n\t/\n\t The mode of operation, either \"test\" or \"update\".\n\t * @remarks\n\t * In \"update\" mode, a new snapshot is created if the current schema differs from the latest existing snapshot.\n\t * Note: {@link SchemaCompatibilitySnapshotsOptions.snapshotUnchangedVersions} impacts this behavior.\n\t \n\t In \"test\" mode, an error is thrown if running in \"update\" mode would have made any changes.\n\t \n\t Both modes will throw errors if any compatibility issues are detected (but after updating snapshots in \"update\" mode so the diff can be used to help debug).\n\t \n\t It is recommended that \"test\" mode be used in automated tests to verify schema compatibility,\n\t * and \"update\" mode only be used manually to update snapshots when making schema changes (or version changes if `snapshotUnchangedVersions` is true).\n\t /\n\treadonly mode: \"test\" \| \"update\";\n}\n\n/\n Check `currentViewSchema` for compatibility with a collection of historical schema snapshots stored in `snapshotDirectory`.\n \n @throws Throws errors if the input version strings (including those in snapshot file names) are not valid semver versions.\n * @throws Throws errors if the input version strings (including those in snapshot file names) are not ordered as expected (current being the highest, and `minVersionForCollaboration` corresponding to the current version or a lower snapshotted version).\n * @throws In `test` mode, throws an error if there is not an up to date snapshot for the current version.\n * @throws Throws an error if any snapshotted schema cannot be upgraded to the current schema.\n * @throws Throws an error if any snapshotted schema with a version greater than or equal to `minVersionForCollaboration` cannot view documents created with the current schema.\n * @remarks\n * This is intended for use in snapshot-based schema compatibility tests.\n * Every SharedTree-based component or application with a schema is recommended to use this to verify schema compatibility across versions.\n \n Schema snapshots should be added to `snapshotDirectory` using this function in \"update\" mode whenever the schema changes in a compatibility impacting way\n * (or when `snapshotUnchangedVersions` is true and a new version about to be released is getting prepared for release (and thus `version` changed)).\n \n This will throw an exception if any snapshotted schema would result in documents that cannot be viewed (after using {@link TreeView.upgradeSchema}), or if any schema with a version greater than or equal to `minVersionForCollaboration` cannot view documents created with the `currentViewSchema`.\n * See {@link TreeView.compatibility} for more information.\n \n Proper use of this utility should do a good job at detecting schema compatibility issues,\n * however it currently does not do a good job of explaining exactly what change to the schema is causing the compatibility issues.\n * This is a known limitation that will be improved in future releases.\n * These improvements, as well as other changes, may change the exact messages produced by this function in the error cases: no stability of these messages should be assumed.\n \n For now, locating what change broke compatibility is likely best discovered by making small schema changes one at a time and updating the snapshot and reviewing the diffs.\n * Details for what kinds of changes are breaking and in which ways can be found in the documentation for {@link TreeView.compatibility} and\n * {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution/ \| schema-evolution}.\n \n This utility does not enforce anything with respect to API compatibility, or special semantics for major, minor, or patch versions.\n * Libraries which export schema for use by others will need to take special care to ensure the stability contract they offer their users aligns which what is validated by this utility.\n \n This utility only tests compatibility of the historical snapshots against the current schema; it does not test them against each-other.\n * Generally any historical schema should have been tested against the ones before them at the time they were current.\n * If for some reason a version of a schema made it into production that was not compatible with a previous version,\n * that can still be represented here (but may require manually generating a snapshot for that version)\n * and this will still allow testing that all historical version can be upgraded to the current one.\n * If a sufficiently incompatible historical schema were used in production, it may be impossible to make a single schema which can accommodate all of them:\n * this utility can be used to confirm that is the case, as well as to avoid the problem in the first place by testing schema before each one is deployed.\n \n @example Mocha test which validates the current `config` can collaborate with all historical version back to 2.0.0, and load and update any versions older than that.\n * ```typescript\n * it(\"schema compatibility\", () => {\n * \tcheckSchemaCompatibilitySnapshots({\n * \t\tversion: pkgVersion,\n * \t\tschema: config,\n * \t\tfileSystem: { ...fs, ...path },\n * \t\tminVersionForCollaboration: \"2.0.0\",\n * \t\tmode: process.argv.includes(\"--snapshot\") ? \"update\" : \"test\",\n * \t\tsnapshotDirectory,\n * \t});\n * });\n * ```\n * @privateRemarks\n * Use of this function within this package (for schema libraries released as part of this package) should use {@link testSchemaCompatibilitySnapshots} instead.\n \n TODO: this uses the format defined in simpleSchemaCodec.ts.\n * Currently this does not include any versioning information in the snapshot format itself.\n * This would make it hard to do things like upgrade to a new format (perhaps for better diffs, or to support new features) in the future.\n * That code should probably be migrated to a proper versioned codec with a schema and validation.\n * This utility can directly depend on the typebox-validator and inject that as this code should not be bundle size sensitive.\n * This should be addressed before this reached beta stability.\n * @alpha\n /\nexport function checkSchemaCompatibilitySnapshots(\n\toptions: SchemaCompatibilitySnapshotsOptions,\n): void {\n\tconst checker = new SnapshotCompatibilityChecker(\n\t\toptions.snapshotDirectory,\n\t\toptions.fileSystem,\n\t);\n\tconst {\n\t\tversion: currentVersion,\n\t\tschema: currentViewSchema,\n\t\tmode,\n\t\tminVersionForCollaboration,\n\t\tsnapshotUnchangedVersions,\n\t} = options;\n\tif (semver.valid(currentVersion) === null) {\n\t\tthrow new UsageError(\n\t\t\t`Invalid version: ${JSON.stringify(currentVersion)}. Must be a valid semver version.`,\n\t\t);\n\t}\n\tif (semver.valid(minVersionForCollaboration) === null) {\n\t\tthrow new UsageError(\n\t\t\t`Invalid minVersionForCollaboration: ${JSON.stringify(minVersionForCollaboration)}. Must be a valid semver version.`,\n\t\t);\n\t}\n\tif (!semver.lte(minVersionForCollaboration, currentVersion)) {\n\t\tthrow new UsageError(\n\t\t\t`Invalid minVersionForCollaboration: ${JSON.stringify(minVersionForCollaboration)}. Must be less than or equal to current version ${JSON.stringify(currentVersion)}.`,\n\t\t);\n\t}\n\n\tif (mode !== \"test\" && mode !== \"update\") {\n\t\tthrow new UsageError(\n\t\t\t`Invalid mode: ${JSON.stringify(mode)}. Must be either \"test\" or \"update\".`,\n\t\t);\n\t}\n\n\tconst currentEncodedForSnapshotting = exportCompatibilitySchemaSnapshot(currentViewSchema);\n\tconst snapshots = checker.readAllSchemaSnapshots();\n\n\tconst compatibilityErrors: string[] = [];\n\n\tfunction updatableError(message: string): void {\n\t\tassert(mode === \"test\", 0xcc6 / updatableError should only be called in test mode /);\n\t\tcompatibilityErrors.push(\n\t\t\t`${message} If this is expected, checkSchemaCompatibilitySnapshots can be rerun in \"update\" mode to update the snapshot.`,\n\t\t);\n\t}\n\n\tif (snapshotUnchangedVersions === true) {\n\t\tif (mode === \"update\") {\n\t\t\tchecker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);\n\t\t\tsnapshots.set(currentVersion, currentViewSchema);\n\t\t} else {\n\t\t\tconst currentRead = snapshots.get(currentVersion);\n\t\t\tif (currentRead === undefined) {\n\t\t\t\tupdatableError(\n\t\t\t\t\t`No snapshot found for version ${JSON.stringify(currentVersion)}: snapshotUnchangedVersions is true, so every version must be snapshotted.`,\n\t\t\t\t);\n\t\t\t} else if (\n\t\t\t\tJSON.stringify(exportCompatibilitySchemaSnapshot(currentRead)) !==\n\t\t\t\tJSON.stringify(currentEncodedForSnapshotting)\n\t\t\t) {\n\t\t\t\tupdatableError(\n\t\t\t\t\t`Snapshot for current version ${JSON.stringify(currentVersion)} is out of date.`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t} else {\n\t\tconst entries = [...snapshots];\n\t\tconst latestSnapshot = entries[entries.length - 1];\n\t\tif (latestSnapshot === undefined) {\n\t\t\tif (mode === \"update\") {\n\t\t\t\tchecker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);\n\t\t\t\tsnapshots.set(currentVersion, currentViewSchema);\n\t\t\t} else {\n\t\t\t\tupdatableError(`No snapshots found.`);\n\t\t\t}\n\t\t} else {\n\t\t\tif (semver.lte(latestSnapshot[0], currentVersion)) {\n\t\t\t\t// Check to see if schema in snapshot is the same as the latest existing snapshot.\n\t\t\t\tconst oldString = JSON.stringify(exportCompatibilitySchemaSnapshot(latestSnapshot[1]));\n\t\t\t\tconst currentString = JSON.stringify(currentEncodedForSnapshotting);\n\t\t\t\tif (oldString !== currentString) {\n\t\t\t\t\t// Schema has changed: must create new snapshot.\n\t\t\t\t\tif (mode === \"update\") {\n\t\t\t\t\t\tchecker.writeSchemaSnapshot(currentVersion, currentEncodedForSnapshotting);\n\t\t\t\t\t\tsnapshots.set(currentVersion, currentViewSchema);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tupdatableError(\n\t\t\t\t\t\t\t`Snapshot for current version ${JSON.stringify(currentVersion)} is out of date: schema has changed since latest existing snapshot version ${JSON.stringify(latestSnapshot[0])}.`,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`Current version ${JSON.stringify(currentVersion)} is less than latest existing snapshot version ${JSON.stringify(latestSnapshot[0])}: version is expected to increase monotonically.`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\tconst compatibilityMap = transformMapValues(snapshots, (snapshot) =>\n\t\tgetCompatibility(currentViewSchema, snapshot),\n\t);\n\n\tlet selectedMinVersionForCollaborationSnapshot:\n\t\t\| undefined\n\t\t\| readonly [string, CombinedSchemaCompatibilityStatus];\n\n\tif (snapshotUnchangedVersions === true) {\n\t\tconst minSnapshot = compatibilityMap.get(minVersionForCollaboration);\n\t\tif (minSnapshot === undefined) {\n\t\t\tcompatibilityErrors.push(\n\t\t\t\t`Using snapshotUnchangedVersions: a snapshot of the exact minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)} is required. No snapshot found.`,\n\t\t\t);\n\t\t} else {\n\t\t\tselectedMinVersionForCollaborationSnapshot = [minVersionForCollaboration, minSnapshot];\n\t\t}\n\t} else {\n\t\tselectedMinVersionForCollaborationSnapshot = selectVersionRoundedDown(\n\t\t\tminVersionForCollaboration,\n\t\t\tcompatibilityMap,\n\t\t);\n\t\tif (selectedMinVersionForCollaborationSnapshot === undefined) {\n\t\t\tcompatibilityErrors.push(\n\t\t\t\t`No snapshot found with version less than or equal to minVersionForCollaboration ${JSON.stringify(minVersionForCollaboration)}.`,\n\t\t\t);\n\t\t}\n\t}\n\n\tfor (const [snapshotVersion, compatibility] of compatibilityMap) {\n\t\t// Current should be able to view all versions.\n\t\tif (!compatibility.currentViewOfSnapshotDocument.canUpgrade) {\n\t\t\tcompatibilityErrors.push(\n\t\t\t\t`Current version ${JSON.stringify(currentVersion)} cannot upgrade documents from ${JSON.stringify(snapshotVersion)}.`,\n\t\t\t);\n\t\t}\n\n\t\tif (semver.eq(snapshotVersion, currentVersion)) {\n\t\t\tif (currentVersion !== snapshotVersion) {\n\t\t\t\tthrow new UsageError(\n\t\t\t\t\t`Snapshot version ${JSON.stringify(snapshotVersion)} is semantically equal but not string equal to current version ${JSON.stringify(currentVersion)}: this is not supported.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (\n\t\t\t\tcompatibility.currentViewOfSnapshotDocument.isEquivalent === false \|\|\n\t\t\t\tcompatibility.snapshotViewOfCurrentDocument.isEquivalent === false\n\t\t\t) {\n\t\t\t\tcompatibilityErrors.push(\n\t\t\t\t\t`Current version ${JSON.stringify(snapshotVersion)} expected to be equivalent to its snapshot.`,\n\t\t\t\t);\n\t\t\t}\n\t\t} else if (semver.lt(snapshotVersion, currentVersion)) {\n\t\t\tif (selectedMinVersionForCollaborationSnapshot === undefined) {\n\t\t\t\tassert(\n\t\t\t\t\tcompatibilityErrors.length > 0,\n\t\t\t\t\t0xcc7 / expected compatibility errors for missing min collab version snapshot /,\n\t\t\t\t);\n\t\t\t} else {\n\t\t\t\t// Collaboration with this version is expected to work.\n\t\t\t\tif (semver.gte(snapshotVersion, selectedMinVersionForCollaborationSnapshot[0])) {\n\t\t\t\t\t// Check that the historical version can view documents from the current version, since collaboration with this one is expected to work.\n\t\t\t\t\tif (!compatibility.snapshotViewOfCurrentDocument.canView) {\n\t\t\t\t\t\tconst message = `Historical version ${JSON.stringify(snapshotVersion)} cannot view documents from ${JSON.stringify(currentVersion)}: these versions are expected to be able to collaborate due to the selected minVersionForCollaboration snapshot version being ${JSON.stringify(selectedMinVersionForCollaborationSnapshot[0])}.`;\n\t\t\t\t\t\tcompatibilityErrors.push(\n\t\t\t\t\t\t\tselectedMinVersionForCollaborationSnapshot[0] === minVersionForCollaboration\n\t\t\t\t\t\t\t\t? message\n\t\t\t\t\t\t\t\t: `${message} The specified minVersionForCollaboration is ${JSON.stringify(minVersionForCollaboration)} which was rounded down to an existing snapshot.`,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\t// This is the case where the historical version is less than the minimum version for collaboration.\n\t\t\t\t\t// No additional validation is needed here currently, since forwards document compat from these versions is already tested above (since it applies to all snapshots).\n\t\t\t\t}\n\t\t\t}\n\t\t} else {\n\t\t\tthrow new UsageError(\n\t\t\t\t`Unexpected semver comparison result between snapshot version ${JSON.stringify(snapshotVersion)} and app version ${JSON.stringify(currentVersion)}.`,\n\t\t\t);\n\t\t}\n\t}\n\n\tif (compatibilityErrors.length > 0) {\n\t\tthrow new Error(\n\t\t\t`Schema compatibility check failed:\\n${compatibilityErrors\n\t\t\t\t.map((e) => ` - ${e}`)\n\t\t\t\t.join(\"\\n\")}`,\n\t\t);\n\t}\n}\n\n/\n The high-level API for checking snapshot compatibility and generating new snapshots.\n /\nexport class SnapshotCompatibilityChecker {\n\tpublic constructor(\n\t\t/\n\t\t Directory where historical schema snapshots are stored.\n\t\t /\n\t\tprivate readonly snapshotDirectory: string,\n\t\t/\n\t\t How the `snapshotDirectory` is accessed.\n\t\t /\n\t\tprivate readonly fileSystemMethods: SnapshotFileSystem,\n\t) {}\n\n\tpublic writeSchemaSnapshot(snapshotName: string, snapshot: JsonCompatibleReadOnly): void {\n\t\tconst fullPath = this.fileSystemMethods.join(\n\t\t\tthis.snapshotDirectory,\n\t\t\t`${snapshotName}.json`,\n\t\t);\n\t\tthis.ensureSnapshotDirectoryExists();\n\t\tthis.fileSystemMethods.writeFileSync(fullPath, JSON.stringify(snapshot, undefined, 2), {\n\t\t\tencoding: \"utf8\",\n\t\t});\n\t}\n\n\tpublic readSchemaSnapshot(snapshotName: string): TreeViewConfiguration {\n\t\tconst snapshot = this.readSchemaSnapshotRaw(snapshotName);\n\t\treturn importCompatibilitySchemaSnapshot(snapshot);\n\t}\n\n\tpublic readSchemaSnapshotRaw(snapshotName: string): JsonCompatibleReadOnly {\n\t\tconst fullPath = this.fileSystemMethods.join(\n\t\t\tthis.snapshotDirectory,\n\t\t\t`${snapshotName}.json`,\n\t\t);\n\t\tconst snapshot = JSON.parse(\n\t\t\tthis.fileSystemMethods.readFileSync(fullPath, \"utf8\"),\n\t\t) as JsonCompatibleReadOnly;\n\t\treturn snapshot;\n\t}\n\n\t/\n\t Returns all schema snapshots stored in the snapshot directory, sorted in order of increasing version.\n\t /\n\tpublic readAllSchemaSnapshots(): Map<string, TreeViewConfiguration> {\n\t\tthis.ensureSnapshotDirectoryExists();\n\t\tconst files = this.fileSystemMethods.readdirSync(this.snapshotDirectory);\n\t\tconst versions: string[] = [];\n\t\tfor (const file of files) {\n\t\t\tif (file.endsWith(\".json\")) {\n\t\t\t\tconst snapshotName = file.slice(0, \".json\".length -1);\n\t\t\t\tversions.push(snapshotName);\n\t\t\t}\n\t\t}\n\t\t// Ensures that errors are in a consistent and friendly order, independent of file system order.\n\t\tversions.sort((a, b) => semver.compare(a, b));\n\n\t\tconst snapshots: Map<string, TreeViewConfiguration> = new Map();\n\t\tfor (const version of versions) {\n\t\t\tsnapshots.set(version, this.readSchemaSnapshot(version));\n\t\t}\n\t\treturn snapshots;\n\t}\n\n\tpublic ensureSnapshotDirectoryExists(): void {\n\t\tthis.fileSystemMethods.mkdirSync(this.snapshotDirectory, { recursive: true });\n\t}\n}\n\n/*\n Gets the compatibility of the current view schema against a historical snapshot.\n * @param currentViewSchema - The current view schema.\n * @param previousViewSchema - The historical view schema.\n * @returns The combined compatibility status.\n */\nexport function getCompatibility(\n\tcurrentViewSchema: TreeViewConfiguration,\n\tpreviousViewSchema: TreeViewConfiguration,\n): CombinedSchemaCompatibilityStatus {\n\tconst backwardsCompatibilityStatus = checkCompatibility(\n\t\tpreviousViewSchema,\n\t\tcurrentViewSchema,\n\t);\n\n\tconst forwardsCompatibilityStatus = checkCompatibility(\n\t\tcurrentViewSchema,\n\t\tpreviousViewSchema,\n\t);\n\n\treturn {\n\t\tcurrentViewOfSnapshotDocument: backwardsCompatibilityStatus,\n\t\tsnapshotViewOfCurrentDocument: forwardsCompatibilityStatus,\n\t};\n}\n"]}
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 * @alpha\n /\nexport interface SnapshotFileSystem {\n\t/\n\t Writes a UTF-8 encoded file to disk, replacing the file if it already exists.\n\t \n\t @param file - Path to the file to write.\n\t * @param data - String data to be written.\n\t * @param options - Options specifying that the encoding is UTF-8.\n\t /\n\twriteFileSync(file: string, data: string, options: { encoding: \"utf8\" }): void;\n\n\t/\n\t Reads a UTF-8 encoded file from disk and returns its contents as a string.\n\t \n\t @param file - Path to the file to read.\n\t * @param encoding - The text encoding to use when reading the file. Must be `\"utf8\"`.\n\t * @returns The contents of the file as a string.\n\t /\n\t// We include the encoding here to match the function overload for readFileSync that returns a string.\n\treadFileSync(file: string, encoding: \"utf8\"): string;\n\n\t/\n\t How a {@link TreeView} using the snapshotted schema would report its compatibility with a document created with the current schema.\n\t \n\t @param dir - Path of the directory to create.\n\t * @param options - Options indicating that creation should be recursive.\n\t /\n\tmkdirSync(dir: string, options: { recursive: true }): void;\n\n\t/\n\t Reads the contents of a directory.\n\t \n\t @param dir - Path of the directory to read.\n\t * @returns An array of names of the directory entries.\n\t /\n\treaddirSync(dir: string): readonly string[];\n\n\t/\n\t Joins two path segments into a single path string.\n\t \n\t @param parentPath - The directory path.\n\t * @param childPath - Filename within `parentPath` directory.\n\t * @returns The combined path string.\n\t /\n\tjoin(parentPath: string, childPath: string): string;\n}\n\n/\n The combined compatibility status for both backwards and forwards compatibility checks.\n /\nexport interface CombinedSchemaCompatibilityStatus {\n\t/\n\t How a {@link TreeView} using the current schema would report its compatibility with the historical snapshot.\n\t /\n\treadonly currentViewOfSnapshotDocument: Omit<SchemaCompatibilityStatus, \"canInitialize\">;\n\t/\n\t How a {@link TreeView} using the snapshotted schema would report its compatibility with a document created with the current schema.\n\t /\n\treadonly snapshotViewOfCurrentDocument: Omit<SchemaCompatibilityStatus, \"canInitialize\">;\n\n\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 * @alpha\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/alpha\";\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 * @alpha\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"]}

package/dist/simple-tree/api/tree.d.ts CHANGED Viewed

@@ -360,7 +360,7 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
      * @remarks
      * {@link TreeViewEvents.schemaChanged} is fired when the compatibility status changes.
      * See {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution/ | schema-evolution} for more guidance on how to change schema while maintaining compatibility.
-     * Use {@link checkSchemaCompatibilitySnapshots} to write tests to validate that this compatibility behaves as desired across schema changes.
+     * Use {@link snapshotSchemaCompatibility} to write tests to validate that this compatibility behaves as desired across schema changes.
      */
     readonly compatibility: SchemaCompatibilityStatus;
     /**

package/dist/simple-tree/api/tree.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"tree.js","sourceRoot":"","sources":["../../../src/simple-tree/api/tree.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAgqBH;;;;;GAKG;AACH,SAAgB,eAAe,CAC9B,IAAuB;IAEvB,OAAO,IAA8B,CAAC;AACvC,CAAC;AAJD,0CAIC","sourcesContent":["/!\n Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n /\n\nimport type { IFluidLoadable, IDisposable, Listenable } from \"@fluidframework/core-interfaces\";\n\nimport type {\n\tChangeMetadata,\n\tCommitMetadata,\n\tRevertibleAlphaFactory,\n\tRevertibleFactory,\n} from \"../../core/index.js\";\nimport type {\n\t// This is referenced by doc comments.\n\t// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports\n\tTreeAlpha,\n} from \"../../shared-tree/index.js\";\nimport type { JsonCompatibleReadOnly } from \"../../util/index.js\";\nimport type {\n\tImplicitFieldSchema,\n\tInsertableField,\n\tInsertableTreeFieldFromImplicitField,\n\tReadableField,\n\tReadSchema,\n\tTreeFieldFromImplicitField,\n} from \"../fieldSchema.js\";\nimport type { SimpleTreeSchema } from \"../simpleSchema.js\";\nimport type { UnsafeUnknownSchema } from \"../unsafeUnknownSchema.js\";\n\nimport type { TreeViewConfiguration } from \"./configuration.js\";\nimport type {\n\tRunTransactionParams,\n\tTransactionCallbackStatus,\n\tTransactionResult,\n\tTransactionResultExt,\n\tVoidTransactionCallbackStatus,\n} from \"./transactionTypes.js\";\nimport type { VerboseTree } from \"./verboseTree.js\";\n\n/\n A tree from which a {@link TreeView} can be created.\n \n @privateRemarks\n * TODO:\n * Add stored key versions of {@link (TreeAlpha:interface).(exportVerbose:2)}, {@link (TreeAlpha:interface).(exportConcise:2)} and {@link (TreeAlpha:interface).exportCompressed} here so tree content can be accessed without a view schema.\n * Add exportSimpleSchema and exportJsonSchema methods (which should exactly match the concise format, and match the free functions for exporting view schema).\n * Maybe rename \"exportJsonSchema\" to align on \"concise\" terminology.\n * Ensure schema exporting APIs here align and reference APIs for exporting view schema to the same formats (which should include stored vs property key choice).\n * Make sure users of independentView can use these export APIs (maybe provide a reference back to the ViewableTree from the TreeView to accomplish that).\n * @system @sealed @public\n /\nexport interface ViewableTree {\n\t/\n\t Returns a {@link TreeView} using the provided schema.\n\t * If the stored schema is compatible with the view schema specified by `config`,\n\t * the returned {@link TreeView} will expose the root with a schema-aware API based on the provided view schema.\n\t * If the provided schema is incompatible with the stored schema, the view will instead expose a status indicating the incompatibility.\n\t \n\t @remarks\n\t * If the tree is uninitialized (has no schema and no content), use {@link TreeView.initialize} on the returned view to set the schema and content together.\n\t * Using `viewWith` followed by {@link TreeView.upgradeSchema} to initialize only the schema for a document is technically valid when the schema\n\t * permits trees with no content.\n\t \n\t Note that other clients can modify the document at any time, causing the view to change its compatibility status: see {@link TreeView.events} for how to handle invalidation in these cases.\n\t \n\t Only one schematized view may exist for a given ITree at a time.\n\t * If creating a second, the first must be disposed before calling `viewWith` again.\n\t \n\t @privateRemarks\n\t * TODO: Support adapters for handling out-of-schema data.\n\t /\n\tviewWith<TRoot extends ImplicitFieldSchema>(\n\t\tconfig: TreeViewConfiguration<TRoot>,\n\t): TreeView<TRoot>;\n}\n\n/\n Channel for a Fluid Tree DDS.\n * @remarks\n * Allows storing and collaboratively editing schema-aware hierarchial data.\n * @sealed @public\n /\nexport interface ITree extends ViewableTree, IFluidLoadable {}\n\n/\n {@link ITree} extended with some alpha APIs.\n * @sealed @alpha\n /\nexport interface ITreeAlpha extends ITree {\n\t/\n\t Exports root in the same format as {@link (TreeAlpha:interface).(exportVerbose:1)} using stored keys.\n\t * @remarks\n\t * This is `undefined` if and only if the root field is empty (this can only happen if the root field is optional).\n\t /\n\texportVerbose(): VerboseTree \| undefined;\n\n\t/\n\t Exports the SimpleTreeSchema that is stored in the tree, using stored keys for object fields.\n\t * @remarks\n\t * To get the schema using property keys, use {@link getSimpleSchema} on the view schema.\n\t /\n\texportSimpleSchema(): SimpleTreeSchema;\n\n\t/\n\t Creates a fork of the current state of the main branch.\n\t * This new branch will be shared with and editable by all clients.\n\t /\n\tcreateSharedBranch(): string;\n\n\t/\n\t Returns a list of all shared branches that currently exist on this tree.\n\t * Any one of them can be checked out using {@link ITreeAlpha.viewSharedBranchWith}.\n\t /\n\tgetSharedBranchIds(): string[];\n\n\t/\n\t Returns a view of the tree on the specified shared branch, using the provided schema.\n\t * See {@link ViewableTree.viewWith}.\n\t /\n\tviewSharedBranchWith<TRoot extends ImplicitFieldSchema>(\n\t\tbranchId: string,\n\t\tconfig: TreeViewConfiguration<TRoot>,\n\t): TreeView<TRoot>;\n}\n\n/\n A collection of functionality associated with a (version-control-style) branch of a SharedTree.\n * @remarks A `TreeBranch` allows for the {@link TreeBranch.fork \| creation of branches} and for those branches to later be {@link TreeBranch.merge \| merged}.\n \n The branch associated directly with the {@link ITree \| SharedTree} is the \"main\" branch, and all other branches fork (directly or transitively) from that main branch.\n * @sealed @beta\n /\nexport interface TreeBranch extends IDisposable {\n\t/\n\t Fork a new branch off of this branch which is based off of this branch's current state.\n\t * @remarks Any changes to the tree on the new branch will not apply to this branch until the new branch is e.g. {@link TreeBranch.merge \| merged} back into this branch.\n\t * The branch should be disposed when no longer needed, either {@link TreeBranch.dispose \| explicitly} or {@link TreeBranch.merge \| implicitly when merging} into another branch.\n\t /\n\tfork(): TreeBranch;\n\n\t/\n\t Apply all the new changes on the given branch to this branch.\n\t * @param branch - a branch which was created by a call to `branch()`.\n\t * @param disposeMerged - whether or not to dispose `branch` after the merge completes.\n\t * Defaults to true.\n\t * The {@link TreeBranch \| main branch} cannot be disposed - attempting to do so will have no effect.\n\t * @remarks All ongoing transactions (if any) in `branch` will be committed before the merge.\n\t /\n\tmerge(branch: TreeBranch, disposeMerged?: boolean): void;\n\n\t/\n\t Advance this branch forward such that all new changes on the target branch become part of this branch.\n\t * @param branch - The branch to rebase onto.\n\t * @remarks After rebasing, this branch will be \"ahead\" of the target branch, that is, its unique changes will have been recreated as if they happened after all changes on the target branch.\n\t * This method may only be called on branches produced via {@link TreeBranch.fork \| branch} - attempting to rebase the main branch will throw.\n\t \n\t Rebasing long-lived branches is important to avoid consuming memory unnecessarily.\n\t * In particular, the SharedTree retains all sequenced changes made to the tree since the \"most-behind\" branch was created or last rebased.\n\t \n\t The {@link TreeBranch \| main branch} cannot be rebased onto another branch - attempting to do so will throw an error.\n\t /\n\trebaseOnto(branch: TreeBranch): void;\n\n\t/\n\t Dispose of this branch, cleaning up any resources associated with it.\n\t * @param error - Optional error indicating the reason for the disposal, if the object was disposed as the result of an error.\n\t * @remarks Branches can also be automatically disposed when {@link TreeBranch.merge \| they are merged} into another branch.\n\t \n\t Disposing branches is important to avoid consuming memory unnecessarily.\n\t * In particular, the SharedTree retains all sequenced changes made to the tree since the \"most-behind\" branch was created or last {@link TreeBranch.rebaseOnto \| rebased}.\n\t \n\t The {@link TreeBranch \| main branch} cannot be disposed - attempting to do so will have no effect.\n\t /\n\tdispose(error?: Error): void;\n}\n\n/\n {@link TreeBranch} with alpha-level APIs.\n * @remarks\n * The `TreeBranch` for a specific {@link TreeNode} may be acquired by calling `TreeAlpha.branch`.\n \n A branch does not necessarily know the schema of its SharedTree - to convert a branch to a {@link TreeViewAlpha \| view with a schema}, use {@link TreeBranchAlpha.hasRootSchema \| hasRootSchema()}.\n * @sealed @alpha\n /\nexport interface TreeBranchAlpha extends TreeBranch {\n\t/\n\t Events for the branch\n\t /\n\treadonly events: Listenable<TreeBranchEvents>;\n\n\t/\n\t Returns true if this branch has the given schema as its root schema.\n\t * @remarks This is a type guard which allows this branch to become strongly typed as a {@link TreeViewAlpha \| view} of the given schema.\n\t \n\t To succeed, the given schema must be invariant to the schema of the view - it must include exactly the same allowed types.\n\t * For example, a schema of `Foo \| Bar` will not match a view schema of `Foo`, and likewise a schema of `Foo` will not match a view schema of `Foo \| Bar`.\n\t * @example\n\t * ```typescript\n\t * if (branch.hasRootSchema(MySchema)) {\n\t * const { root } = branch; // `branch` is now a TreeViewAlpha<MySchema>\n\t * // ...\n\t * }\n\t * ```\n\t /\n\thasRootSchema<TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t): this is TreeViewAlpha<TSchema>;\n\n\t// Override the base fork method to return the alpha variant.\n\tfork(): TreeBranchAlpha;\n\n\t/\n\t Run a synchronous transaction which applies one or more edits to the tree as a single atomic unit.\n\t * @param transaction - The function to run as the body of the transaction.\n\t * It should return a status object of {@link TransactionCallbackStatus \| TransactionCallbackStatus } type.\n\t * It includes a \"rollback\" property which may be returned as true at any point during the transaction. This will\n\t * abort the transaction and discard any changes it made so far.\n\t * \"rollback\" can be set to false or left undefined to indicate that the body of the transaction has successfully run.\n\t * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.\n\t * @returns A result object of {@link TransactionResultExt \| TransactionResultExt} type. It includes the following:\n\t \n\t - A \"success\" flag indicating whether the transaction was successful or not.\n\t * - The success or failure value as returned by the transaction function.\n\t \n\t @remarks\n\t * This API will throw an error if the constraints are not met or something unexpected happens.\n\t * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.\n\t * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.\n\t * However, using a transaction has the following additional consequences:\n\t \n\t - If reverted (e.g. via an \"undo\" operation), all the changes in the transaction are reverted together.\n\t * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.\n\t \n\t Local change events will be emitted for each change as the transaction is being applied.\n\t * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.\n\t \n\t Nested transactions:\n\t * This API can be called from within the transaction callback of another `runTransaction` or `runTransactionAsync` call. That will have slightly different behavior:\n\t \n\t - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.\n\t * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated\n\t * for the outermost transaction which includes all inner transactions.\n\t * - Undo will undo the outermost transaction and all inner transactions.\n\t * - If a label is provided in the params, only the label for the outermost transaction will be used. All other labels will be ignored.\n\t /\n\trunTransaction<TSuccessValue, TFailureValue>(\n\t\ttransaction: () => TransactionCallbackStatus<TSuccessValue, TFailureValue>,\n\t\tparams?: RunTransactionParams,\n\t): TransactionResultExt<TSuccessValue, TFailureValue>;\n\t/\n\t Run a synchronous transaction which applies one or more edits to the tree as a single atomic unit.\n\t * @param transaction - The function to run as the body of the transaction. It may return the following:\n\t \n\t - Nothing to indicate that the body of the transaction has successfully run.\n\t * - A status object of {@link VoidTransactionCallbackStatus \| VoidTransactionCallbackStatus } type. It includes a \"rollback\" property which\n\t * may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so\n\t * far. \"rollback\" can be set to false or left undefined to indicate that the body of the transaction has successfully run.\n\t \n\t @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.\n\t * @returns A result object of {@link TransactionResult \| TransactionResult} type. It includes a \"success\" flag indicating whether the\n\t * transaction was successful or not.\n\t \n\t @remarks\n\t * This API will throw an error if the constraints are not met or something unexpected happens.\n\t * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.\n\t * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.\n\t * However, using a transaction has the following additional consequences:\n\t \n\t - If reverted (e.g. via an \"undo\" operation), all the changes in the transaction are reverted together.\n\t * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.\n\t \n\t Local change events will be emitted for each change as the transaction is being applied.\n\t * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.\n\t \n\t Nested transactions:\n\t * This API can be called from within the transaction callback of another `runTransaction` or `runTransactionAsync` call. That will have slightly different behavior:\n\t \n\t - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.\n\t * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated\n\t * for the outermost transaction which includes all inner transactions.\n\t * - Undo will undo the outermost transaction and all inner transactions.\n\t /\n\trunTransaction(\n\t\ttransaction: () => VoidTransactionCallbackStatus \| void,\n\t\tparams?: RunTransactionParams,\n\t): TransactionResult;\n\n\t/\n\t Run an asynchronous transaction which applies one or more edits to the tree as a single atomic unit.\n\t * @param transaction - The function to run as the body of the transaction.\n\t * It should return a promise that resolves to a status object of {@link TransactionCallbackStatus \| TransactionCallbackStatus } type.\n\t * It includes a \"rollback\" property which may be returned as true at any point during the transaction. This will\n\t * abort the transaction and discard any changes it made so far.\n\t * \"rollback\" can be set to false or left undefined to indicate that the body of the transaction has successfully run.\n\t * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.\n\t * @returns A promise that resolves to a result object of {@link TransactionResultExt \| TransactionResultExt} type. It includes the following:\n\t \n\t - A \"success\" flag indicating whether the transaction was successful or not.\n\t * - The success or failure value as returned by the transaction function.\n\t \n\t The promise will reject if the constraints are not met or something unexpected happens.\n\t \n\t @remarks\n\t * As with synchronous transactions, using an asynchronous transaction has the following consequences:\n\t * - All of the changes in the transaction are treated as a unit, therefore no other changes (either from this client or from a remote client) can be interleaved with the transaction changes.\n\t * - If reverted (e.g. via an \"undo\" operation), all the changes in the transaction are reverted together.\n\t * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.\n\t \n\t Unlike with synchronous transactions, using an asynchronous transaction has the following consequences:\n\t * - It is possible that other changes (either from this client by merging a branch or from a remote client) may be applied to the branch while this transaction is in progress.\n\t * These other changes will be not be reflected on the branch until after this transaction completes,\n\t * at which point the transaction changes will be applied after these other changes.\n\t \n\t Local change events will be emitted for each change as the transaction is being applied.\n\t * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.\n\t \n\t Nested transactions:\n\t * This API can be called from within the transaction callback of another `runTransactionAsync` call. That will have slightly different behavior:\n\t \n\t - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.\n\t * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated\n\t * for the outermost transaction which includes all inner transactions.\n\t * - Undo will undo the outermost transaction and all inner transactions.\n\t /\n\trunTransactionAsync<TSuccessValue, TFailureValue>(\n\t\ttransaction: () => Promise<TransactionCallbackStatus<TSuccessValue, TFailureValue>>,\n\t\tparams?: RunTransactionParams,\n\t): Promise<TransactionResultExt<TSuccessValue, TFailureValue>>;\n\t/\n\t Run an asynchronous transaction which applies one or more edits to the tree as a single atomic unit.\n\t * @param transaction - The function to run as the body of the transaction. It must return a promise that can resolve to any of the following:\n\t \n\t - Nothing to indicate that the body of the transaction has successfully run.\n\t * - A status object of {@link VoidTransactionCallbackStatus \| VoidTransactionCallbackStatus } type. It includes a \"rollback\" property which\n\t * may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so\n\t * far. \"rollback\" can be set to false or left undefined to indicate that the body of the transaction has successfully run.\n\t \n\t @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.\n\t * @returns A promise that resolves to a result object of {@link TransactionResult \| TransactionResult} type. It includes a \"success\" flag indicating whether the\n\t * transaction was successful or not. The promise will reject if the constraints are not met or something unexpected happens.\n\t \n\t @remarks\n\t * As with synchronous transactions, using an asynchronous transaction has the following consequences:\n\t * - All of the changes in the transaction are treated as a unit, therefore no other changes (either from this client or from a remote client) can be interleaved with the transaction changes.\n\t * - If reverted (e.g. via an \"undo\" operation), all the changes in the transaction are reverted together.\n\t * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.\n\t \n\t Unlike with synchronous transactions, using an asynchronous transaction has the following consequences:\n\t * - It is possible that other changes (either from this client by merging a branch or from a remote client) may be applied to the branch while this transaction is in progress.\n\t * These other changes will be not be reflected on the branch until after this transaction completes,\n\t * at which point the transaction changes will be applied after these other changes.\n\t \n\t Local change events will be emitted for each change as the transaction is being applied.\n\t * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.\n\t \n\t Nested transactions:\n\t * This API can be called from within the transaction callback of another `runTransactionAsync` call. That will have slightly different behavior:\n\t \n\t - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.\n\t * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated\n\t * for the outermost transaction which includes all inner transactions.\n\t * - Undo will undo the outermost transaction and all inner transactions.\n\t /\n\trunTransactionAsync(\n\t\ttransaction: () => Promise<VoidTransactionCallbackStatus \| void>,\n\t\tparams?: RunTransactionParams,\n\t): Promise<TransactionResult>;\n\n\t/\n\t Apply a serialized change to this branch.\n\t * @param change - the change to apply.\n\t * Changes are acquired via `getChange` in a branch's {@link TreeBranchEvents.changed \| \"changed\"} event.\n\t * @remarks Changes may only be applied to a SharedTree with the same IdCompressor instance and branch state from which they were generated.\n\t * They may be created by one branch and applied to another, but only if both branches share the same history at the time of creation and application.\n\t \n\t @privateRemarks\n\t * TODO: This method will support applying changes from different IdCompressor instances as long as they have the same local session ID.\n\t * Update the tests and docs to match when that is done.\n\t /\n\tapplyChange(change: JsonCompatibleReadOnly): void;\n}\n\n/\n An editable view of a (version control style) branch of a shared tree based on some schema.\n \n @remarks\n * This schema (known as the view schema) may or may not align with the stored schema of the document.\n * Information about discrepancies between the two schemas is available via {@link TreeView.compatibility \| compatibility}.\n \n Application authors are encouraged to read {@link https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/docs/user-facing/schema-evolution.md \| schema-evolution.md}\n * and choose a schema compatibility policy that aligns with their application's needs.\n \n @privateRemarks\n * From an API design perspective, `upgradeSchema` could be merged into `viewWith` and/or `viewWith` could return errors explicitly on incompatible documents.\n * Such approaches would make it discoverable that out of schema handling may need to be done.\n * Doing that would however complicate trivial \"hello world\" style example slightly, as well as be a breaking API change.\n * It also seems more complex to handle invalidation with that pattern.\n * Thus this design was chosen at the risk of apps blindly accessing `root` then breaking unexpectedly when the document is incompatible.\n \n @see {@link TreeViewAlpha}\n * @see {@link asTreeViewAlpha}\n \n @sealed @public\n /\nexport interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {\n\t/\n\t The current root of the tree.\n\t \n\t If the view schema not sufficiently compatible with the stored schema, accessing this will throw.\n\t * To handle this case, check {@link TreeView.compatibility \| compatibility}'s {@link SchemaCompatibilityStatus.canView \| canView} before using.\n\t \n\t To get notified about changes to this field,\n\t * use {@link TreeViewEvents.rootChanged} via `view.events.on(\"rootChanged\", callback)`.\n\t \n\t To get notified about changes to stored schema (which may affect compatibility between this view's schema and\n\t * the stored schema), use {@link TreeViewEvents.schemaChanged} via `view.events.on(\"schemaChanged\", callback)`.\n\t /\n\tget root(): TreeFieldFromImplicitField<TSchema>;\n\n\tset root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);\n\n\t/\n\t Description of the current compatibility status between the view schema and stored schema.\n\t * @remarks\n\t * {@link TreeViewEvents.schemaChanged} is fired when the compatibility status changes.\n\t * See {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution/ \| schema-evolution} for more guidance on how to change schema while maintaining compatibility.\n\t * Use {@link checkSchemaCompatibilitySnapshots} to write tests to validate that this compatibility behaves as desired across schema changes.\n\t /\n\treadonly compatibility: SchemaCompatibilityStatus;\n\n\t/\n\t When {@link SchemaCompatibilityStatus.canUpgrade} is true,\n\t * this can be used to modify the stored schema to make it match the view schema.\n\t * @remarks\n\t * This will update the {@link TreeView.compatibility}, allowing access to `root`.\n\t * Beware that this may impact other clients' ability to view the document: see {@link SchemaCompatibilityStatus.canView} for more information.\n\t \n\t It is an error to call this when {@link SchemaCompatibilityStatus.canUpgrade} is false.\n\t * {@link SchemaCompatibilityStatus.canUpgrade} being true does not mean that an upgrade is required, nor that an upgrade will have any effect.\n\t * @privateRemarks\n\t * In the future, more upgrade options could be provided here.\n\t * Some options that could be added:\n\t * - check the actual document contents (not just the schema) and attempt an atomic document update if the data is compatible.\n\t * - apply converters and upgrade the document.\n\t * - apply converters to lazily to adapt the document to the requested view schema (with optional lazy schema updates or transparent conversions on write).\n\t * - update only a specific change (add an optional field, or apply a staged upgrade)\n\t * - update persistedMetadata or not\n\t \n\t As persisted metadata becomes more supported, how it interacts with isEquivalent and upgradeSchema should be clarified:\n\t * for now the docs are being left somewhat vague to allow flexibility in this area.\n\t /\n\tupgradeSchema(): void;\n\n\t/\n\t Initialize the tree, setting the stored schema to match this view's schema and setting the tree content.\n\t \n\t Only valid to call when this view's {@link SchemaCompatibilityStatus.canInitialize} is true.\n\t \n\t Applications should typically call this function before attaching a `SharedTree`.\n\t * @param content - The content to initialize the tree with.\n\t /\n\tinitialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;\n\n\t/\n\t Events for the tree.\n\t /\n\treadonly events: Listenable<TreeViewEvents>;\n\n\t/\n\t The view schema used by this TreeView.\n\t /\n\treadonly schema: TSchema;\n}\n\n/\n {@link TreeView} with proposed changes to the schema aware typing to allow use with `UnsafeUnknownSchema`.\n * @sealed @alpha\n /\nexport interface TreeViewAlpha<\n\tin out TSchema extends ImplicitFieldSchema \| UnsafeUnknownSchema,\n> extends Omit<TreeViewBeta<ReadSchema<TSchema>>, \"root\" \| \"initialize\" \| \"fork\">,\n\t\tTreeBranchAlpha {\n\tget root(): ReadableField<TSchema>;\n\n\tset root(newRoot: InsertableField<TSchema>);\n\n\tinitialize(content: InsertableField<TSchema>): void;\n\n\treadonly events: Listenable<TreeViewEvents & TreeBranchEvents>;\n\n\t// Override the base fork method to return a TreeViewAlpha.\n\tfork(): ReturnType<TreeBranch[\"fork\"]> & TreeViewAlpha<TSchema>;\n}\n\n/\n {@link TreeView} with additional beta APIs.\n * @sealed @beta\n /\nexport interface TreeViewBeta<in out TSchema extends ImplicitFieldSchema>\n\textends TreeView<TSchema>,\n\t\tTreeBranch {\n\t// Override the base branch method to return a typed view rather than merely a branch.\n\tfork(): ReturnType<TreeBranch[\"fork\"]> & TreeViewBeta<TSchema>;\n}\n\n/\n Information about a view schema's compatibility with the document's stored schema.\n \n See SharedTree's README for more information about choosing a compatibility policy.\n * @privateRemarks\n * See {@link SchemaCompatibilityTester} for the implementation of this compatibility checking.\n * @sealed @public\n /\nexport interface SchemaCompatibilityStatus {\n\t/\n\t Whether the view schema allows exactly the same set of documents as the stored schema.\n\t \n\t @remarks\n\t * Equivalence here is defined in terms of allowed documents because there are some degenerate cases where schemas are not\n\t * exact matches in a strict (schema-based) sense but still allow the same documents, and the document notion is more useful to applications.\n\t \n\t Examples which are expressible where this may occur include:\n\t \n\t - schema repository `A` has extra schema which schema `B` doesn't have, but they are unused (i.e. not reachable from the root schema)\n\t \n\t - field in schema `A` has allowed field members which the corresponding field in schema `B` does not have, but those types are not constructible (for example: an object node type containing a required field with no allowed types)\n\t \n\t These cases are typically not interesting to applications.\n\t \n\t Note that other content in the stored schema that does not impact document compatibility, like {@link NodeSchemaOptionsAlpha.persistedMetadata}, does not affect this field.\n\t \n\t For the computation of this equivalence, {@link SchemaStaticsBeta.staged \| staged} schemas are not included.\n\t * If there are any unknown optional fields, even if allowed by {@link ObjectSchemaOptions.allowUnknownOptionalFields}, `isEquivalent` will be false.\n\t /\n\treadonly isEquivalent: boolean;\n\n\t/\n\t Whether the current view schema is sufficiently compatible with the stored schema to allow viewing tree data.\n\t * If false, {@link TreeView.root} will throw upon access.\n\t * @remarks\n\t * If the view schema does not opt into supporting any additional cases, then `canView` is only true when `isEquivalent` is also true.\n\t * The view schema can however opt into supporting additional cases, and thus can also view documents with stored schema which would be equivalent, except for the following discrepancies:\n\t \n\t - An object node with {@link ObjectSchemaOptions.allowUnknownOptionalFields} to set to true that has additional optional fields in the stored schema beyond those mentioned in its view schema.\n\t \n\t - An additional type allowed at a location in the stored schema where it is {@link SchemaStaticsBeta.staged \| staged} in the view schema.\n\t \n\t In these cases `canUpgrade` and `isEquivalent` will be false.\n\t \n\t When the set of documents allowed by the view schema is a strict superset of those allowed by the stored schema,\n\t * `canView` is false because writes to the document using the view schema could make the document violate its stored schema.\n\t * In this case, the stored schema could be updated to match the provided view schema, allowing read-write access to the tree.\n\t * See {@link SchemaCompatibilityStatus.canUpgrade}.\n\t \n\t Future versions of SharedTree may provide readonly access to the document in this case because that would be safe,\n\t * but this is not currently supported.\n\t \n\t @privateRemarks\n\t * A necessary condition for this to be true is that the documents allowed by the view schema are a subset of those allowed by the stored schema.\n\t * This is not sufficient: the simple-tree layer's read APIs only tolerate very specific cases beyond their schema (unknown optional fields).\n\t * For example, if the view schema for a node has a required `Point` field but the stored schema has an optional `Point` field,\n\t * read APIs on the view schema do not work correctly when the document has a node with a missing `Point` field.\n\t * Similar issues happen when the view schema has a field with less allowed types than the stored schema and the document actually leverages those types.\n\t /\n\treadonly canView: boolean;\n\n\t/\n\t True when {@link TreeView.upgradeSchema} can add support for all content required to be supported by the view schema.\n\t * @remarks\n\t * When true, it is valid to call {@link TreeView.upgradeSchema} (though if the stored schema is already an exact match, this is a no-op).\n\t \n\t When adding optional fields to schema which previously were marked with {@link ObjectSchemaOptions.allowUnknownOptionalFields}\n\t * the schema upgrade (assuming no other changes are included) will allow the previous version to view.\n\t * Even this case must still must be done with caution however as only clients with the newly added field will be able to do future upgrades.\n\t * Thus if a version of an application is shipped that adds an unknown optional field, all future versions should include it, even if its no longer used,\n\t * to ensure that documents containing it can still be upgraded.\n\t /\n\treadonly canUpgrade: boolean;\n\n\t/\n\t True iff the document is uninitialized (i.e. it has no schema and no content).\n\t \n\t To initialize the document, call {@link TreeView.initialize}.\n\t \n\t @remarks\n\t * It's not necessary to check this field before calling {@link TreeView.initialize} in most scenarios; application authors typically know from\n\t * branch that they're in a flow which creates a new `SharedTree` and would like to initialize it.\n\t /\n\treadonly canInitialize: boolean;\n\n\t// TODO: Consider extending this status to include:\n\t// - application-defined metadata about the stored schema\n\t// - details about the differences between the stored and view schema sufficient for implementing \"safe mismatch\" policies\n}\n\n/\n Events for {@link TreeBranch}.\n * @sealed @alpha\n /\nexport interface TreeBranchEvents extends Omit<TreeViewEvents, \"commitApplied\"> {\n\t/\n\t Fired when a change is made to the branch. Includes data about the change that is made which listeners\n\t * can use to filter on changes they care about (e.g. local vs. remote changes).\n\t \n\t @param data - information about the change\n\t * @param getRevertible - a function that allows users to get a revertible for the change. If not provided,\n\t * this change is not revertible.\n\t /\n\tchanged(data: ChangeMetadata, getRevertible?: RevertibleAlphaFactory): void;\n\n\t/\n\t Fired when:\n\t \n\t - a local commit is applied outside of a transaction\n\t \n\t - a local transaction is committed\n\t \n\t The event is not fired when:\n\t \n\t - a local commit is applied within a transaction\n\t \n\t - a remote commit is applied\n\t \n\t @param data - information about the commit that was applied\n\t * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,\n\t * this commit is not revertible.\n\t /\n\tcommitApplied(data: ChangeMetadata, getRevertible?: RevertibleAlphaFactory): void;\n}\n\n/\n Events for {@link TreeView}.\n * @sealed @public\n /\nexport interface TreeViewEvents {\n\t/\n\t Raised whenever {@link TreeView.root} is invalidated.\n\t \n\t This includes changes to the document schema.\n\t * It also includes changes to the field containing the root such as setting or clearing an optional root or changing which node is the root.\n\t * This does NOT include changes to the content (fields/children) of the root node: for that case subscribe to events on the root node.\n\t /\n\trootChanged(): void;\n\n\t/\n\t The stored schema for the document has changed.\n\t * This may affect the compatibility between the view schema and the stored schema, and thus the ability to use the view.\n\t \n\t @remarks\n\t * This event implies that the old {@link TreeView.root} is no longer valid, but applications need not handle that separately:\n\t * {@link TreeViewEvents.rootChanged} will be fired after this event.\n\t /\n\tschemaChanged(): void;\n\n\t/\n\t Fired when:\n\t \n\t - a local commit is applied outside of a transaction\n\t \n\t - a local transaction is committed\n\t \n\t The event is not fired when:\n\t \n\t - a local commit is applied within a transaction\n\t \n\t - a remote commit is applied\n\t \n\t @param data - information about the commit that was applied\n\t * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,\n\t * this commit is not revertible.\n\t /\n\tcommitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;\n}\n\n/\n Retrieve the {@link TreeViewAlpha \| alpha API} for a {@link TreeView}.\n * @alpha\n * @deprecated Use {@link (asAlpha:1)} instead.\n * @privateRemarks Despite being deprecated, this function should be used within the tree package (outside of tests) rather than `asAlpha` in order to avoid circular import dependencies.\n */\nexport function asTreeViewAlpha<TSchema extends ImplicitFieldSchema>(\n\tview: TreeView<TSchema>,\n): TreeViewAlpha<TSchema> {\n\treturn view as TreeViewAlpha<TSchema>;\n}\n"]}
1	+ {"version":3,"file":"tree.js","sourceRoot":"","sources":["../../../src/simple-tree/api/tree.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAgqBH;;;;;GAKG;AACH,SAAgB,eAAe,CAC9B,IAAuB;IAEvB,OAAO,IAA8B,CAAC;AACvC,CAAC;AAJD,0CAIC","sourcesContent":["/!\n Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n /\n\nimport type { IFluidLoadable, IDisposable, Listenable } from \"@fluidframework/core-interfaces\";\n\nimport type {\n\tChangeMetadata,\n\tCommitMetadata,\n\tRevertibleAlphaFactory,\n\tRevertibleFactory,\n} from \"../../core/index.js\";\nimport type {\n\t// This is referenced by doc comments.\n\t// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports\n\tTreeAlpha,\n} from \"../../shared-tree/index.js\";\nimport type { JsonCompatibleReadOnly } from \"../../util/index.js\";\nimport type {\n\tImplicitFieldSchema,\n\tInsertableField,\n\tInsertableTreeFieldFromImplicitField,\n\tReadableField,\n\tReadSchema,\n\tTreeFieldFromImplicitField,\n} from \"../fieldSchema.js\";\nimport type { SimpleTreeSchema } from \"../simpleSchema.js\";\nimport type { UnsafeUnknownSchema } from \"../unsafeUnknownSchema.js\";\n\nimport type { TreeViewConfiguration } from \"./configuration.js\";\nimport type {\n\tRunTransactionParams,\n\tTransactionCallbackStatus,\n\tTransactionResult,\n\tTransactionResultExt,\n\tVoidTransactionCallbackStatus,\n} from \"./transactionTypes.js\";\nimport type { VerboseTree } from \"./verboseTree.js\";\n\n/\n A tree from which a {@link TreeView} can be created.\n \n @privateRemarks\n * TODO:\n * Add stored key versions of {@link (TreeAlpha:interface).(exportVerbose:2)}, {@link (TreeAlpha:interface).(exportConcise:2)} and {@link (TreeAlpha:interface).exportCompressed} here so tree content can be accessed without a view schema.\n * Add exportSimpleSchema and exportJsonSchema methods (which should exactly match the concise format, and match the free functions for exporting view schema).\n * Maybe rename \"exportJsonSchema\" to align on \"concise\" terminology.\n * Ensure schema exporting APIs here align and reference APIs for exporting view schema to the same formats (which should include stored vs property key choice).\n * Make sure users of independentView can use these export APIs (maybe provide a reference back to the ViewableTree from the TreeView to accomplish that).\n * @system @sealed @public\n /\nexport interface ViewableTree {\n\t/\n\t Returns a {@link TreeView} using the provided schema.\n\t * If the stored schema is compatible with the view schema specified by `config`,\n\t * the returned {@link TreeView} will expose the root with a schema-aware API based on the provided view schema.\n\t * If the provided schema is incompatible with the stored schema, the view will instead expose a status indicating the incompatibility.\n\t \n\t @remarks\n\t * If the tree is uninitialized (has no schema and no content), use {@link TreeView.initialize} on the returned view to set the schema and content together.\n\t * Using `viewWith` followed by {@link TreeView.upgradeSchema} to initialize only the schema for a document is technically valid when the schema\n\t * permits trees with no content.\n\t \n\t Note that other clients can modify the document at any time, causing the view to change its compatibility status: see {@link TreeView.events} for how to handle invalidation in these cases.\n\t \n\t Only one schematized view may exist for a given ITree at a time.\n\t * If creating a second, the first must be disposed before calling `viewWith` again.\n\t \n\t @privateRemarks\n\t * TODO: Support adapters for handling out-of-schema data.\n\t /\n\tviewWith<TRoot extends ImplicitFieldSchema>(\n\t\tconfig: TreeViewConfiguration<TRoot>,\n\t): TreeView<TRoot>;\n}\n\n/\n Channel for a Fluid Tree DDS.\n * @remarks\n * Allows storing and collaboratively editing schema-aware hierarchial data.\n * @sealed @public\n /\nexport interface ITree extends ViewableTree, IFluidLoadable {}\n\n/\n {@link ITree} extended with some alpha APIs.\n * @sealed @alpha\n /\nexport interface ITreeAlpha extends ITree {\n\t/\n\t Exports root in the same format as {@link (TreeAlpha:interface).(exportVerbose:1)} using stored keys.\n\t * @remarks\n\t * This is `undefined` if and only if the root field is empty (this can only happen if the root field is optional).\n\t /\n\texportVerbose(): VerboseTree \| undefined;\n\n\t/\n\t Exports the SimpleTreeSchema that is stored in the tree, using stored keys for object fields.\n\t * @remarks\n\t * To get the schema using property keys, use {@link getSimpleSchema} on the view schema.\n\t /\n\texportSimpleSchema(): SimpleTreeSchema;\n\n\t/\n\t Creates a fork of the current state of the main branch.\n\t * This new branch will be shared with and editable by all clients.\n\t /\n\tcreateSharedBranch(): string;\n\n\t/\n\t Returns a list of all shared branches that currently exist on this tree.\n\t * Any one of them can be checked out using {@link ITreeAlpha.viewSharedBranchWith}.\n\t /\n\tgetSharedBranchIds(): string[];\n\n\t/\n\t Returns a view of the tree on the specified shared branch, using the provided schema.\n\t * See {@link ViewableTree.viewWith}.\n\t /\n\tviewSharedBranchWith<TRoot extends ImplicitFieldSchema>(\n\t\tbranchId: string,\n\t\tconfig: TreeViewConfiguration<TRoot>,\n\t): TreeView<TRoot>;\n}\n\n/\n A collection of functionality associated with a (version-control-style) branch of a SharedTree.\n * @remarks A `TreeBranch` allows for the {@link TreeBranch.fork \| creation of branches} and for those branches to later be {@link TreeBranch.merge \| merged}.\n \n The branch associated directly with the {@link ITree \| SharedTree} is the \"main\" branch, and all other branches fork (directly or transitively) from that main branch.\n * @sealed @beta\n /\nexport interface TreeBranch extends IDisposable {\n\t/\n\t Fork a new branch off of this branch which is based off of this branch's current state.\n\t * @remarks Any changes to the tree on the new branch will not apply to this branch until the new branch is e.g. {@link TreeBranch.merge \| merged} back into this branch.\n\t * The branch should be disposed when no longer needed, either {@link TreeBranch.dispose \| explicitly} or {@link TreeBranch.merge \| implicitly when merging} into another branch.\n\t /\n\tfork(): TreeBranch;\n\n\t/\n\t Apply all the new changes on the given branch to this branch.\n\t * @param branch - a branch which was created by a call to `branch()`.\n\t * @param disposeMerged - whether or not to dispose `branch` after the merge completes.\n\t * Defaults to true.\n\t * The {@link TreeBranch \| main branch} cannot be disposed - attempting to do so will have no effect.\n\t * @remarks All ongoing transactions (if any) in `branch` will be committed before the merge.\n\t /\n\tmerge(branch: TreeBranch, disposeMerged?: boolean): void;\n\n\t/\n\t Advance this branch forward such that all new changes on the target branch become part of this branch.\n\t * @param branch - The branch to rebase onto.\n\t * @remarks After rebasing, this branch will be \"ahead\" of the target branch, that is, its unique changes will have been recreated as if they happened after all changes on the target branch.\n\t * This method may only be called on branches produced via {@link TreeBranch.fork \| branch} - attempting to rebase the main branch will throw.\n\t \n\t Rebasing long-lived branches is important to avoid consuming memory unnecessarily.\n\t * In particular, the SharedTree retains all sequenced changes made to the tree since the \"most-behind\" branch was created or last rebased.\n\t \n\t The {@link TreeBranch \| main branch} cannot be rebased onto another branch - attempting to do so will throw an error.\n\t /\n\trebaseOnto(branch: TreeBranch): void;\n\n\t/\n\t Dispose of this branch, cleaning up any resources associated with it.\n\t * @param error - Optional error indicating the reason for the disposal, if the object was disposed as the result of an error.\n\t * @remarks Branches can also be automatically disposed when {@link TreeBranch.merge \| they are merged} into another branch.\n\t \n\t Disposing branches is important to avoid consuming memory unnecessarily.\n\t * In particular, the SharedTree retains all sequenced changes made to the tree since the \"most-behind\" branch was created or last {@link TreeBranch.rebaseOnto \| rebased}.\n\t \n\t The {@link TreeBranch \| main branch} cannot be disposed - attempting to do so will have no effect.\n\t /\n\tdispose(error?: Error): void;\n}\n\n/\n {@link TreeBranch} with alpha-level APIs.\n * @remarks\n * The `TreeBranch` for a specific {@link TreeNode} may be acquired by calling `TreeAlpha.branch`.\n \n A branch does not necessarily know the schema of its SharedTree - to convert a branch to a {@link TreeViewAlpha \| view with a schema}, use {@link TreeBranchAlpha.hasRootSchema \| hasRootSchema()}.\n * @sealed @alpha\n /\nexport interface TreeBranchAlpha extends TreeBranch {\n\t/\n\t Events for the branch\n\t /\n\treadonly events: Listenable<TreeBranchEvents>;\n\n\t/\n\t Returns true if this branch has the given schema as its root schema.\n\t * @remarks This is a type guard which allows this branch to become strongly typed as a {@link TreeViewAlpha \| view} of the given schema.\n\t \n\t To succeed, the given schema must be invariant to the schema of the view - it must include exactly the same allowed types.\n\t * For example, a schema of `Foo \| Bar` will not match a view schema of `Foo`, and likewise a schema of `Foo` will not match a view schema of `Foo \| Bar`.\n\t * @example\n\t * ```typescript\n\t * if (branch.hasRootSchema(MySchema)) {\n\t * const { root } = branch; // `branch` is now a TreeViewAlpha<MySchema>\n\t * // ...\n\t * }\n\t * ```\n\t /\n\thasRootSchema<TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t): this is TreeViewAlpha<TSchema>;\n\n\t// Override the base fork method to return the alpha variant.\n\tfork(): TreeBranchAlpha;\n\n\t/\n\t Run a synchronous transaction which applies one or more edits to the tree as a single atomic unit.\n\t * @param transaction - The function to run as the body of the transaction.\n\t * It should return a status object of {@link TransactionCallbackStatus \| TransactionCallbackStatus } type.\n\t * It includes a \"rollback\" property which may be returned as true at any point during the transaction. This will\n\t * abort the transaction and discard any changes it made so far.\n\t * \"rollback\" can be set to false or left undefined to indicate that the body of the transaction has successfully run.\n\t * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.\n\t * @returns A result object of {@link TransactionResultExt \| TransactionResultExt} type. It includes the following:\n\t \n\t - A \"success\" flag indicating whether the transaction was successful or not.\n\t * - The success or failure value as returned by the transaction function.\n\t \n\t @remarks\n\t * This API will throw an error if the constraints are not met or something unexpected happens.\n\t * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.\n\t * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.\n\t * However, using a transaction has the following additional consequences:\n\t \n\t - If reverted (e.g. via an \"undo\" operation), all the changes in the transaction are reverted together.\n\t * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.\n\t \n\t Local change events will be emitted for each change as the transaction is being applied.\n\t * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.\n\t \n\t Nested transactions:\n\t * This API can be called from within the transaction callback of another `runTransaction` or `runTransactionAsync` call. That will have slightly different behavior:\n\t \n\t - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.\n\t * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated\n\t * for the outermost transaction which includes all inner transactions.\n\t * - Undo will undo the outermost transaction and all inner transactions.\n\t * - If a label is provided in the params, only the label for the outermost transaction will be used. All other labels will be ignored.\n\t /\n\trunTransaction<TSuccessValue, TFailureValue>(\n\t\ttransaction: () => TransactionCallbackStatus<TSuccessValue, TFailureValue>,\n\t\tparams?: RunTransactionParams,\n\t): TransactionResultExt<TSuccessValue, TFailureValue>;\n\t/\n\t Run a synchronous transaction which applies one or more edits to the tree as a single atomic unit.\n\t * @param transaction - The function to run as the body of the transaction. It may return the following:\n\t \n\t - Nothing to indicate that the body of the transaction has successfully run.\n\t * - A status object of {@link VoidTransactionCallbackStatus \| VoidTransactionCallbackStatus } type. It includes a \"rollback\" property which\n\t * may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so\n\t * far. \"rollback\" can be set to false or left undefined to indicate that the body of the transaction has successfully run.\n\t \n\t @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.\n\t * @returns A result object of {@link TransactionResult \| TransactionResult} type. It includes a \"success\" flag indicating whether the\n\t * transaction was successful or not.\n\t \n\t @remarks\n\t * This API will throw an error if the constraints are not met or something unexpected happens.\n\t * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.\n\t * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.\n\t * However, using a transaction has the following additional consequences:\n\t \n\t - If reverted (e.g. via an \"undo\" operation), all the changes in the transaction are reverted together.\n\t * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.\n\t \n\t Local change events will be emitted for each change as the transaction is being applied.\n\t * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.\n\t \n\t Nested transactions:\n\t * This API can be called from within the transaction callback of another `runTransaction` or `runTransactionAsync` call. That will have slightly different behavior:\n\t \n\t - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.\n\t * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated\n\t * for the outermost transaction which includes all inner transactions.\n\t * - Undo will undo the outermost transaction and all inner transactions.\n\t /\n\trunTransaction(\n\t\ttransaction: () => VoidTransactionCallbackStatus \| void,\n\t\tparams?: RunTransactionParams,\n\t): TransactionResult;\n\n\t/\n\t Run an asynchronous transaction which applies one or more edits to the tree as a single atomic unit.\n\t * @param transaction - The function to run as the body of the transaction.\n\t * It should return a promise that resolves to a status object of {@link TransactionCallbackStatus \| TransactionCallbackStatus } type.\n\t * It includes a \"rollback\" property which may be returned as true at any point during the transaction. This will\n\t * abort the transaction and discard any changes it made so far.\n\t * \"rollback\" can be set to false or left undefined to indicate that the body of the transaction has successfully run.\n\t * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.\n\t * @returns A promise that resolves to a result object of {@link TransactionResultExt \| TransactionResultExt} type. It includes the following:\n\t \n\t - A \"success\" flag indicating whether the transaction was successful or not.\n\t * - The success or failure value as returned by the transaction function.\n\t \n\t The promise will reject if the constraints are not met or something unexpected happens.\n\t \n\t @remarks\n\t * As with synchronous transactions, using an asynchronous transaction has the following consequences:\n\t * - All of the changes in the transaction are treated as a unit, therefore no other changes (either from this client or from a remote client) can be interleaved with the transaction changes.\n\t * - If reverted (e.g. via an \"undo\" operation), all the changes in the transaction are reverted together.\n\t * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.\n\t \n\t Unlike with synchronous transactions, using an asynchronous transaction has the following consequences:\n\t * - It is possible that other changes (either from this client by merging a branch or from a remote client) may be applied to the branch while this transaction is in progress.\n\t * These other changes will be not be reflected on the branch until after this transaction completes,\n\t * at which point the transaction changes will be applied after these other changes.\n\t \n\t Local change events will be emitted for each change as the transaction is being applied.\n\t * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.\n\t \n\t Nested transactions:\n\t * This API can be called from within the transaction callback of another `runTransactionAsync` call. That will have slightly different behavior:\n\t \n\t - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.\n\t * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated\n\t * for the outermost transaction which includes all inner transactions.\n\t * - Undo will undo the outermost transaction and all inner transactions.\n\t /\n\trunTransactionAsync<TSuccessValue, TFailureValue>(\n\t\ttransaction: () => Promise<TransactionCallbackStatus<TSuccessValue, TFailureValue>>,\n\t\tparams?: RunTransactionParams,\n\t): Promise<TransactionResultExt<TSuccessValue, TFailureValue>>;\n\t/\n\t Run an asynchronous transaction which applies one or more edits to the tree as a single atomic unit.\n\t * @param transaction - The function to run as the body of the transaction. It must return a promise that can resolve to any of the following:\n\t \n\t - Nothing to indicate that the body of the transaction has successfully run.\n\t * - A status object of {@link VoidTransactionCallbackStatus \| VoidTransactionCallbackStatus } type. It includes a \"rollback\" property which\n\t * may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so\n\t * far. \"rollback\" can be set to false or left undefined to indicate that the body of the transaction has successfully run.\n\t \n\t @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.\n\t * @returns A promise that resolves to a result object of {@link TransactionResult \| TransactionResult} type. It includes a \"success\" flag indicating whether the\n\t * transaction was successful or not. The promise will reject if the constraints are not met or something unexpected happens.\n\t \n\t @remarks\n\t * As with synchronous transactions, using an asynchronous transaction has the following consequences:\n\t * - All of the changes in the transaction are treated as a unit, therefore no other changes (either from this client or from a remote client) can be interleaved with the transaction changes.\n\t * - If reverted (e.g. via an \"undo\" operation), all the changes in the transaction are reverted together.\n\t * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.\n\t \n\t Unlike with synchronous transactions, using an asynchronous transaction has the following consequences:\n\t * - It is possible that other changes (either from this client by merging a branch or from a remote client) may be applied to the branch while this transaction is in progress.\n\t * These other changes will be not be reflected on the branch until after this transaction completes,\n\t * at which point the transaction changes will be applied after these other changes.\n\t \n\t Local change events will be emitted for each change as the transaction is being applied.\n\t * If the transaction is rolled back, a corresponding change event will also be emitted for the rollback.\n\t \n\t Nested transactions:\n\t * This API can be called from within the transaction callback of another `runTransactionAsync` call. That will have slightly different behavior:\n\t \n\t - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.\n\t * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated\n\t * for the outermost transaction which includes all inner transactions.\n\t * - Undo will undo the outermost transaction and all inner transactions.\n\t /\n\trunTransactionAsync(\n\t\ttransaction: () => Promise<VoidTransactionCallbackStatus \| void>,\n\t\tparams?: RunTransactionParams,\n\t): Promise<TransactionResult>;\n\n\t/\n\t Apply a serialized change to this branch.\n\t * @param change - the change to apply.\n\t * Changes are acquired via `getChange` in a branch's {@link TreeBranchEvents.changed \| \"changed\"} event.\n\t * @remarks Changes may only be applied to a SharedTree with the same IdCompressor instance and branch state from which they were generated.\n\t * They may be created by one branch and applied to another, but only if both branches share the same history at the time of creation and application.\n\t \n\t @privateRemarks\n\t * TODO: This method will support applying changes from different IdCompressor instances as long as they have the same local session ID.\n\t * Update the tests and docs to match when that is done.\n\t /\n\tapplyChange(change: JsonCompatibleReadOnly): void;\n}\n\n/\n An editable view of a (version control style) branch of a shared tree based on some schema.\n \n @remarks\n * This schema (known as the view schema) may or may not align with the stored schema of the document.\n * Information about discrepancies between the two schemas is available via {@link TreeView.compatibility \| compatibility}.\n \n Application authors are encouraged to read {@link https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/docs/user-facing/schema-evolution.md \| schema-evolution.md}\n * and choose a schema compatibility policy that aligns with their application's needs.\n \n @privateRemarks\n * From an API design perspective, `upgradeSchema` could be merged into `viewWith` and/or `viewWith` could return errors explicitly on incompatible documents.\n * Such approaches would make it discoverable that out of schema handling may need to be done.\n * Doing that would however complicate trivial \"hello world\" style example slightly, as well as be a breaking API change.\n * It also seems more complex to handle invalidation with that pattern.\n * Thus this design was chosen at the risk of apps blindly accessing `root` then breaking unexpectedly when the document is incompatible.\n \n @see {@link TreeViewAlpha}\n * @see {@link asTreeViewAlpha}\n \n @sealed @public\n /\nexport interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {\n\t/\n\t The current root of the tree.\n\t \n\t If the view schema not sufficiently compatible with the stored schema, accessing this will throw.\n\t * To handle this case, check {@link TreeView.compatibility \| compatibility}'s {@link SchemaCompatibilityStatus.canView \| canView} before using.\n\t \n\t To get notified about changes to this field,\n\t * use {@link TreeViewEvents.rootChanged} via `view.events.on(\"rootChanged\", callback)`.\n\t \n\t To get notified about changes to stored schema (which may affect compatibility between this view's schema and\n\t * the stored schema), use {@link TreeViewEvents.schemaChanged} via `view.events.on(\"schemaChanged\", callback)`.\n\t /\n\tget root(): TreeFieldFromImplicitField<TSchema>;\n\n\tset root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);\n\n\t/\n\t Description of the current compatibility status between the view schema and stored schema.\n\t * @remarks\n\t * {@link TreeViewEvents.schemaChanged} is fired when the compatibility status changes.\n\t * See {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution/ \| schema-evolution} for more guidance on how to change schema while maintaining compatibility.\n\t * Use {@link snapshotSchemaCompatibility} to write tests to validate that this compatibility behaves as desired across schema changes.\n\t /\n\treadonly compatibility: SchemaCompatibilityStatus;\n\n\t/\n\t When {@link SchemaCompatibilityStatus.canUpgrade} is true,\n\t * this can be used to modify the stored schema to make it match the view schema.\n\t * @remarks\n\t * This will update the {@link TreeView.compatibility}, allowing access to `root`.\n\t * Beware that this may impact other clients' ability to view the document: see {@link SchemaCompatibilityStatus.canView} for more information.\n\t \n\t It is an error to call this when {@link SchemaCompatibilityStatus.canUpgrade} is false.\n\t * {@link SchemaCompatibilityStatus.canUpgrade} being true does not mean that an upgrade is required, nor that an upgrade will have any effect.\n\t * @privateRemarks\n\t * In the future, more upgrade options could be provided here.\n\t * Some options that could be added:\n\t * - check the actual document contents (not just the schema) and attempt an atomic document update if the data is compatible.\n\t * - apply converters and upgrade the document.\n\t * - apply converters to lazily to adapt the document to the requested view schema (with optional lazy schema updates or transparent conversions on write).\n\t * - update only a specific change (add an optional field, or apply a staged upgrade)\n\t * - update persistedMetadata or not\n\t \n\t As persisted metadata becomes more supported, how it interacts with isEquivalent and upgradeSchema should be clarified:\n\t * for now the docs are being left somewhat vague to allow flexibility in this area.\n\t /\n\tupgradeSchema(): void;\n\n\t/\n\t Initialize the tree, setting the stored schema to match this view's schema and setting the tree content.\n\t \n\t Only valid to call when this view's {@link SchemaCompatibilityStatus.canInitialize} is true.\n\t \n\t Applications should typically call this function before attaching a `SharedTree`.\n\t * @param content - The content to initialize the tree with.\n\t /\n\tinitialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;\n\n\t/\n\t Events for the tree.\n\t /\n\treadonly events: Listenable<TreeViewEvents>;\n\n\t/\n\t The view schema used by this TreeView.\n\t /\n\treadonly schema: TSchema;\n}\n\n/\n {@link TreeView} with proposed changes to the schema aware typing to allow use with `UnsafeUnknownSchema`.\n * @sealed @alpha\n /\nexport interface TreeViewAlpha<\n\tin out TSchema extends ImplicitFieldSchema \| UnsafeUnknownSchema,\n> extends Omit<TreeViewBeta<ReadSchema<TSchema>>, \"root\" \| \"initialize\" \| \"fork\">,\n\t\tTreeBranchAlpha {\n\tget root(): ReadableField<TSchema>;\n\n\tset root(newRoot: InsertableField<TSchema>);\n\n\tinitialize(content: InsertableField<TSchema>): void;\n\n\treadonly events: Listenable<TreeViewEvents & TreeBranchEvents>;\n\n\t// Override the base fork method to return a TreeViewAlpha.\n\tfork(): ReturnType<TreeBranch[\"fork\"]> & TreeViewAlpha<TSchema>;\n}\n\n/\n {@link TreeView} with additional beta APIs.\n * @sealed @beta\n /\nexport interface TreeViewBeta<in out TSchema extends ImplicitFieldSchema>\n\textends TreeView<TSchema>,\n\t\tTreeBranch {\n\t// Override the base branch method to return a typed view rather than merely a branch.\n\tfork(): ReturnType<TreeBranch[\"fork\"]> & TreeViewBeta<TSchema>;\n}\n\n/\n Information about a view schema's compatibility with the document's stored schema.\n \n See SharedTree's README for more information about choosing a compatibility policy.\n * @privateRemarks\n * See {@link SchemaCompatibilityTester} for the implementation of this compatibility checking.\n * @sealed @public\n /\nexport interface SchemaCompatibilityStatus {\n\t/\n\t Whether the view schema allows exactly the same set of documents as the stored schema.\n\t \n\t @remarks\n\t * Equivalence here is defined in terms of allowed documents because there are some degenerate cases where schemas are not\n\t * exact matches in a strict (schema-based) sense but still allow the same documents, and the document notion is more useful to applications.\n\t \n\t Examples which are expressible where this may occur include:\n\t \n\t - schema repository `A` has extra schema which schema `B` doesn't have, but they are unused (i.e. not reachable from the root schema)\n\t \n\t - field in schema `A` has allowed field members which the corresponding field in schema `B` does not have, but those types are not constructible (for example: an object node type containing a required field with no allowed types)\n\t \n\t These cases are typically not interesting to applications.\n\t \n\t Note that other content in the stored schema that does not impact document compatibility, like {@link NodeSchemaOptionsAlpha.persistedMetadata}, does not affect this field.\n\t \n\t For the computation of this equivalence, {@link SchemaStaticsBeta.staged \| staged} schemas are not included.\n\t * If there are any unknown optional fields, even if allowed by {@link ObjectSchemaOptions.allowUnknownOptionalFields}, `isEquivalent` will be false.\n\t /\n\treadonly isEquivalent: boolean;\n\n\t/\n\t Whether the current view schema is sufficiently compatible with the stored schema to allow viewing tree data.\n\t * If false, {@link TreeView.root} will throw upon access.\n\t * @remarks\n\t * If the view schema does not opt into supporting any additional cases, then `canView` is only true when `isEquivalent` is also true.\n\t * The view schema can however opt into supporting additional cases, and thus can also view documents with stored schema which would be equivalent, except for the following discrepancies:\n\t \n\t - An object node with {@link ObjectSchemaOptions.allowUnknownOptionalFields} to set to true that has additional optional fields in the stored schema beyond those mentioned in its view schema.\n\t \n\t - An additional type allowed at a location in the stored schema where it is {@link SchemaStaticsBeta.staged \| staged} in the view schema.\n\t \n\t In these cases `canUpgrade` and `isEquivalent` will be false.\n\t \n\t When the set of documents allowed by the view schema is a strict superset of those allowed by the stored schema,\n\t * `canView` is false because writes to the document using the view schema could make the document violate its stored schema.\n\t * In this case, the stored schema could be updated to match the provided view schema, allowing read-write access to the tree.\n\t * See {@link SchemaCompatibilityStatus.canUpgrade}.\n\t \n\t Future versions of SharedTree may provide readonly access to the document in this case because that would be safe,\n\t * but this is not currently supported.\n\t \n\t @privateRemarks\n\t * A necessary condition for this to be true is that the documents allowed by the view schema are a subset of those allowed by the stored schema.\n\t * This is not sufficient: the simple-tree layer's read APIs only tolerate very specific cases beyond their schema (unknown optional fields).\n\t * For example, if the view schema for a node has a required `Point` field but the stored schema has an optional `Point` field,\n\t * read APIs on the view schema do not work correctly when the document has a node with a missing `Point` field.\n\t * Similar issues happen when the view schema has a field with less allowed types than the stored schema and the document actually leverages those types.\n\t /\n\treadonly canView: boolean;\n\n\t/\n\t True when {@link TreeView.upgradeSchema} can add support for all content required to be supported by the view schema.\n\t * @remarks\n\t * When true, it is valid to call {@link TreeView.upgradeSchema} (though if the stored schema is already an exact match, this is a no-op).\n\t \n\t When adding optional fields to schema which previously were marked with {@link ObjectSchemaOptions.allowUnknownOptionalFields}\n\t * the schema upgrade (assuming no other changes are included) will allow the previous version to view.\n\t * Even this case must still must be done with caution however as only clients with the newly added field will be able to do future upgrades.\n\t * Thus if a version of an application is shipped that adds an unknown optional field, all future versions should include it, even if its no longer used,\n\t * to ensure that documents containing it can still be upgraded.\n\t /\n\treadonly canUpgrade: boolean;\n\n\t/\n\t True iff the document is uninitialized (i.e. it has no schema and no content).\n\t \n\t To initialize the document, call {@link TreeView.initialize}.\n\t \n\t @remarks\n\t * It's not necessary to check this field before calling {@link TreeView.initialize} in most scenarios; application authors typically know from\n\t * branch that they're in a flow which creates a new `SharedTree` and would like to initialize it.\n\t /\n\treadonly canInitialize: boolean;\n\n\t// TODO: Consider extending this status to include:\n\t// - application-defined metadata about the stored schema\n\t// - details about the differences between the stored and view schema sufficient for implementing \"safe mismatch\" policies\n}\n\n/\n Events for {@link TreeBranch}.\n * @sealed @alpha\n /\nexport interface TreeBranchEvents extends Omit<TreeViewEvents, \"commitApplied\"> {\n\t/\n\t Fired when a change is made to the branch. Includes data about the change that is made which listeners\n\t * can use to filter on changes they care about (e.g. local vs. remote changes).\n\t \n\t @param data - information about the change\n\t * @param getRevertible - a function that allows users to get a revertible for the change. If not provided,\n\t * this change is not revertible.\n\t /\n\tchanged(data: ChangeMetadata, getRevertible?: RevertibleAlphaFactory): void;\n\n\t/\n\t Fired when:\n\t \n\t - a local commit is applied outside of a transaction\n\t \n\t - a local transaction is committed\n\t \n\t The event is not fired when:\n\t \n\t - a local commit is applied within a transaction\n\t \n\t - a remote commit is applied\n\t \n\t @param data - information about the commit that was applied\n\t * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,\n\t * this commit is not revertible.\n\t /\n\tcommitApplied(data: ChangeMetadata, getRevertible?: RevertibleAlphaFactory): void;\n}\n\n/\n Events for {@link TreeView}.\n * @sealed @public\n /\nexport interface TreeViewEvents {\n\t/\n\t Raised whenever {@link TreeView.root} is invalidated.\n\t \n\t This includes changes to the document schema.\n\t * It also includes changes to the field containing the root such as setting or clearing an optional root or changing which node is the root.\n\t * This does NOT include changes to the content (fields/children) of the root node: for that case subscribe to events on the root node.\n\t /\n\trootChanged(): void;\n\n\t/\n\t The stored schema for the document has changed.\n\t * This may affect the compatibility between the view schema and the stored schema, and thus the ability to use the view.\n\t \n\t @remarks\n\t * This event implies that the old {@link TreeView.root} is no longer valid, but applications need not handle that separately:\n\t * {@link TreeViewEvents.rootChanged} will be fired after this event.\n\t /\n\tschemaChanged(): void;\n\n\t/\n\t Fired when:\n\t \n\t - a local commit is applied outside of a transaction\n\t \n\t - a local transaction is committed\n\t \n\t The event is not fired when:\n\t \n\t - a local commit is applied within a transaction\n\t \n\t - a remote commit is applied\n\t \n\t @param data - information about the commit that was applied\n\t * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,\n\t * this commit is not revertible.\n\t /\n\tcommitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;\n}\n\n/\n Retrieve the {@link TreeViewAlpha \| alpha API} for a {@link TreeView}.\n * @alpha\n * @deprecated Use {@link (asAlpha:1)} instead.\n * @privateRemarks Despite being deprecated, this function should be used within the tree package (outside of tests) rather than `asAlpha` in order to avoid circular import dependencies.\n */\nexport function asTreeViewAlpha<TSchema extends ImplicitFieldSchema>(\n\tview: TreeView<TSchema>,\n): TreeViewAlpha<TSchema> {\n\treturn view as TreeViewAlpha<TSchema>;\n}\n"]}

package/dist/simple-tree/api/treeBeta.d.ts CHANGED Viewed

@@ -71,7 +71,7 @@ export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode> extends
  * Extensions to {@link (Tree:interface)} which are not yet stable.
  * @remarks
  * Use via the {@link (TreeBeta:variable)} singleton.
- * @system @sealed @beta
+ * @sealed @beta
  */
 export interface TreeBeta {
     /**

package/dist/simple-tree/api/treeBeta.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"treeBeta.js","sourceRoot":"","sources":["../../../src/simple-tree/api/treeBeta.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 type { ITreeCursorSynchronous, TreeFieldStoredSchema } from \"../../core/index.js\";\nimport {\n\tdefaultSchemaPolicy,\n\tFieldKinds,\n\tisTreeValue,\n} from \"../../feature-libraries/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\tContext,\n\tgetKernel,\n\tgetOrCreateNodeFromInnerNode,\n\tisTreeNode,\n\tUnhydratedContext,\n\ttype NodeKind,\n\ttype TreeLeafValue,\n\ttype TreeNode,\n\ttype Unhydrated,\n\ttype WithType,\n} from \"../core/index.js\";\nimport { getUnhydratedContext } from \"../createContext.js\";\nimport type {\n\tImplicitFieldSchema,\n\tInsertableTreeFieldFromImplicitField,\n\tTreeFieldFromImplicitField,\n} from \"../fieldSchema.js\";\nimport {\n\tunhydratedFlexTreeFromInsertable,\n\ttype InsertableContent,\n} from \"../unhydratedFlexTreeFromInsertable.js\";\nimport type { InsertableField, UnsafeUnknownSchema } from \"../unsafeUnknownSchema.js\";\n\nimport { conciseFromCursor, type ConciseTree } from \"./conciseTree.js\";\nimport { createFromCursor } from \"./create.js\";\nimport type { TreeEncodingOptions } from \"./customTree.js\";\nimport type { TreeChangeEvents } from \"./treeChangeEvents.js\";\nimport { treeNodeApi } from \"./treeNodeApi.js\";\nimport { cursorFromVerbose } from \"./verboseTree.js\";\n\n// Tests for this file are grouped with those for treeNodeApi.ts as that is where this functionality will eventually land,\n// and where most of the actual implementation is for much of it.\n\n/\n Data included for {@link TreeChangeEventsBeta.nodeChanged}.\n * @sealed @beta\n /\nexport interface NodeChangedData<TNode extends TreeNode = TreeNode> {\n\t/\n\t When the node changed is an object or Map node, this lists all the properties which changed.\n\t * @remarks\n\t * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).\n\t \n\t Set to `undefined` when the {@link NodeKind} does not support this feature (currently just ArrayNodes).\n\t \n\t When defined, the set should never be empty, since `nodeChanged` will only be triggered when there is a change, and for the supported node types, the only things that can change are properties.\n\t /\n\treadonly changedProperties?: ReadonlySet<\n\t\t// For Object nodes, make changedProperties required and strongly typed with the property names from the schema:\n\t\tTNode extends WithType<string, NodeKind.Object, infer TInfo>\n\t\t\t? string & keyof TInfo\n\t\t\t: string\n\t>;\n}\n\n/\n Extensions to {@link TreeChangeEvents} which are not yet stable.\n \n @sealed @beta\n /\nexport interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>\n\textends TreeChangeEvents {\n\t/\n\t Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.\n\t \n\t - Object nodes define a change as being when the value of one of its properties changes (i.e., the property's value is set, including when set to `undefined`).\n\t \n\t - Array nodes define a change as when an element is added, removed, moved or replaced.\n\t \n\t - Map nodes define a change as when an entry is added, updated, or removed.\n\t \n\t @remarks\n\t * This event is not emitted when:\n\t \n\t - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing\n\t * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the\n\t * array/map node as one of its properties.\n\t \n\t - The node is moved to a different location in the tree or removed from the tree.\n\t * In this case the event is emitted on the _parent_ node, not the node itself.\n\t \n\t For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t \n\t When the event is emitted, the tree is guaranteed to be in-schema.\n\t \n\t @privateRemarks\n\t * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.\n\t * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the\n\t * node, or when the node has to be updated due to resolution of a merge conflict\n\t * (for example a previously applied local change might be undone, then reapplied differently or not at all).\n\t \n\t TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).\n\t \n\t This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.\n\t /\n\tnodeChanged: (\n\t\tdata: NodeChangedData<TNode> &\n\t\t\t// Make the properties of object, map, and record nodes required:\n\t\t\t(TNode extends WithType<string, NodeKind.Map \| NodeKind.Object \| NodeKind.Record>\n\t\t\t\t? Required<Pick<NodeChangedData<TNode>, \"changedProperties\">>\n\t\t\t\t: unknown),\n\t) => void;\n}\n\n/\n Extensions to {@link (Tree:interface)} which are not yet stable.\n * @remarks\n * Use via the {@link (TreeBeta:variable)} singleton.\n * @system @sealed @beta\n /\nexport interface TreeBeta {\n\t/\n\t Register an event listener on the given node.\n\t * @param node - The node whose events should be subscribed to.\n\t * @param eventName - Which event to subscribe to.\n\t * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.\n\t * @returns A callback function which will deregister the event.\n\t * This callback should be called only once.\n\t /\n\ton<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(\n\t\tnode: TNode,\n\t\teventName: K,\n\t\tlistener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,\n\t): () => void;\n\n\t/\n\t A less type-safe version of {@link (TreeAlpha:interface).create}, suitable for importing data.\n\t * @remarks\n\t * Due to {@link ConciseTree} relying on type inference from the data, its use is somewhat limited.\n\t * This does not support {@link ConciseTree\|ConciseTrees} with customized handle encodings or using persisted keys.\n\t * Use \"compressed\" or \"verbose\" formats for more flexibility.\n\t \n\t When using this function,\n\t * it is recommend to ensure your schema is unambiguous with {@link ITreeConfigurationOptions.preventAmbiguity}.\n\t * If the schema is ambiguous, consider using {@link (TreeAlpha:interface).create} and {@link Unhydrated} nodes where needed,\n\t * or using {@link (TreeAlpha:interface).(importVerbose:1)} and specify all types.\n\t \n\t Documented (and thus recoverable) error handling/reporting for this is not yet implemented,\n\t * but for now most invalid inputs will throw a recoverable error.\n\t /\n\timportConcise<const TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t\tdata: ConciseTree \| undefined,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n\n\t/\n\t Copy a snapshot of the current version of a TreeNode into a {@link ConciseTree}.\n\t /\n\texportConcise(node: TreeNode \| TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;\n\n\t/\n\t Copy a snapshot of the current version of a TreeNode into a {@link ConciseTree}, allowing undefined.\n\t /\n\texportConcise(\n\t\tnode: TreeNode \| TreeLeafValue \| undefined,\n\t\toptions?: TreeEncodingOptions,\n\t): ConciseTree \| undefined;\n\n\t/\n\t Clones the persisted data associated with a node.\n\t \n\t @param node - The node to clone.\n\t * @returns A new unhydrated node with the same persisted data as the original node.\n\t * @remarks\n\t * Some key things to note:\n\t \n\t - Local state, such as properties added to customized schema classes, will not be cloned. However, they will be\n\t * initialized to their default state just as if the node had been created via its constructor.\n\t \n\t - Value node types (i.e., numbers, strings, booleans, nulls and Fluid handles) will be returned as is.\n\t \n\t - The identifiers in the node's subtree will be preserved, i.e., they are not replaced with new values.\n\t \n\t - If the node (or any node in its subtree) contains {@link ObjectSchemaOptions.allowUnknownOptionalFields\|unknown optional fields},\n\t * those fields will be cloned just like the known fields.\n\t /\n\tclone<const TSchema extends ImplicitFieldSchema>(\n\t\tnode: TreeFieldFromImplicitField<TSchema>,\n\t): TreeFieldFromImplicitField<TSchema>;\n\n\t// TODO: support more clone options\n\t// /\n\t// Like {@link (TreeBeta:interface).create}, except deeply clones existing nodes.\n\t// * @remarks\n\t// * This only clones the persisted data associated with a node.\n\t// * Local state, such as properties added to customized schema classes, will not be cloned:\n\t// * they will be initialized however they end up after running the constructor, just like if a remote client had inserted the same nodes.\n\t// /\n\t// clone<const TSchema extends ImplicitFieldSchema>(\n\t// \toriginal: TreeFieldFromImplicitField<TSchema>,\n\t// \toptions?: {\n\t// \t\t/\n\t// \t\t If set, all identifier's in the cloned tree (See {@link SchemaFactory.identifier}) will be replaced with new ones allocated using the default identifier allocation schema.\n\t// \t\t * Otherwise any identifiers will be preserved as is.\n\t// \t\t /\n\t// \t\treplaceIdentifiers?: true;\n\t// \t},\n\t// ): TreeFieldFromImplicitField<TSchema>;\n\n\t/\n\t Construct tree content that is compatible with the field defined by the provided `schema`.\n\t * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.\n\t * @param data - The data used to construct the field content.\n\t * @remarks\n\t * When providing a {@link TreeNodeSchemaClass}, this is the same as invoking its constructor except that an unhydrated node can also be provided.\n\t * This function exists as a generalization that can be used in other cases as well,\n\t * such as when `undefined` might be allowed (for an optional field), or when the type should be inferred from the data when more than one type is possible.\n\t /\n\tcreate<const TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t\tdata: InsertableTreeFieldFromImplicitField<TSchema>,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n}\n\n/\n Borrow a cursor from a node.\n * @remarks\n * The cursor must be put back to its original location before the node is used again.\n /\nexport function borrowCursorFromTreeNodeOrValue(\n\tnode: TreeNode \| TreeLeafValue,\n): ITreeCursorSynchronous {\n\tif (isTreeValue(node)) {\n\t\treturn cursorFromVerbose(node, {});\n\t}\n\tconst kernel = getKernel(node);\n\tconst cursor = kernel.getInnerNode().borrowCursor();\n\treturn cursor;\n}\n\n/\n {@inheritDoc (TreeBeta:interface).importConcise}\n /\nexport function importConcise<TSchema extends ImplicitFieldSchema>(\n\tschema: TSchema & ImplicitFieldSchema,\n\tdata: ConciseTree \| undefined,\n): Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n/\n {@inheritDoc (TreeAlpha:interface).importConcise}\n /\nexport function importConcise<TSchema extends ImplicitFieldSchema \| UnsafeUnknownSchema>(\n\tschema: UnsafeUnknownSchema extends TSchema\n\t\t? ImplicitFieldSchema\n\t\t: TSchema & ImplicitFieldSchema,\n\tdata: ConciseTree \| undefined,\n): Unhydrated<\n\tTSchema extends ImplicitFieldSchema\n\t\t? TreeFieldFromImplicitField<TSchema>\n\t\t: TreeNode \| TreeLeafValue \| undefined\n>;\nexport function importConcise<TSchema extends ImplicitFieldSchema \| UnsafeUnknownSchema>(\n\tschema: UnsafeUnknownSchema extends TSchema\n\t\t? ImplicitFieldSchema\n\t\t: TSchema & ImplicitFieldSchema,\n\tdata: ConciseTree \| undefined,\n): Unhydrated<\n\tTSchema extends ImplicitFieldSchema\n\t\t? TreeFieldFromImplicitField<TSchema>\n\t\t: TreeNode \| TreeLeafValue \| undefined\n> {\n\t// Create the tree content from insertable data\n\tconst mapTree = unhydratedFlexTreeFromInsertable(\n\t\tdata as InsertableField<UnsafeUnknownSchema>,\n\t\tschema,\n\t);\n\tconst result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);\n\treturn result as Unhydrated<\n\t\tTSchema extends ImplicitFieldSchema\n\t\t\t? TreeFieldFromImplicitField<TSchema>\n\t\t\t: TreeNode \| TreeLeafValue \| undefined\n\t>;\n}\n\n/\n {@inheritDoc (TreeBeta:interface).(exportConcise:1)}\n /\nexport function exportConcise(\n\tnode: TreeNode \| TreeLeafValue,\n\toptions?: TreeEncodingOptions,\n): ConciseTree;\n/\n {@inheritDoc (TreeBeta:interface).(exportConcise:2)}\n /\nexport function exportConcise(\n\tnode: TreeNode \| TreeLeafValue \| undefined,\n\toptions?: TreeEncodingOptions,\n): ConciseTree \| undefined;\nexport function exportConcise(\n\tnode: TreeNode \| TreeLeafValue \| undefined,\n\toptions?: TreeEncodingOptions,\n): ConciseTree \| undefined {\n\tif (!isTreeNode(node)) {\n\t\treturn node;\n\t}\n\tconst config: TreeEncodingOptions = { ...options };\n\n\tconst kernel = getKernel(node);\n\tconst cursor = borrowCursorFromTreeNodeOrValue(node);\n\treturn conciseFromCursor(cursor, kernel.context, config);\n}\n\n/\n Extensions to {@link (Tree:variable)} which are not yet stable.\n * @see {@link (TreeBeta:interface)}.\n * @beta\n */\nexport const TreeBeta: TreeBeta = {\n\ton<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(\n\t\tnode: TNode,\n\t\teventName: K,\n\t\tlistener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,\n\t): () => void {\n\t\treturn treeNodeApi.on(node, eventName, listener);\n\t},\n\n\timportConcise,\n\texportConcise,\n\n\tclone<const TSchema extends ImplicitFieldSchema>(\n\t\tnode: TreeFieldFromImplicitField<TSchema>,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>> {\n\t\t// The only non-TreeNode cases are {@link TreeLeafValue} and `undefined` (for an empty optional field) which can be returned as is.\n\t\tif (!isTreeNode(node)) {\n\t\t\treturn node;\n\t\t}\n\n\t\tconst kernel = getKernel(node);\n\t\tconst cursor = kernel.getInnerNode().borrowCursor();\n\n\t\t// To handle when the node transitively contains unknown optional fields,\n\t\t// derive the context from the source node's stored schema which has stored schema for any such fields and their contents.\n\t\tconst flexContext = new UnhydratedContext(\n\t\t\tdefaultSchemaPolicy,\n\t\t\tkernel.context.flexContext.schema,\n\t\t);\n\t\tconst context = new Context(flexContext, getUnhydratedContext(kernel.schema).schema);\n\n\t\tconst fieldSchema: TreeFieldStoredSchema = {\n\t\t\tkind: FieldKinds.required.identifier,\n\t\t\ttypes: new Set([brand(kernel.schema.identifier)]),\n\t\t\tpersistedMetadata: undefined,\n\t\t};\n\t\treturn createFromCursor(kernel.schema, cursor, fieldSchema, context) as Unhydrated<\n\t\t\tTreeFieldFromImplicitField<TSchema>\n\t\t>;\n\t},\n\n\tcreate<const TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t\tdata: InsertableTreeFieldFromImplicitField<TSchema>,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>> {\n\t\tconst mapTree = unhydratedFlexTreeFromInsertable(\n\t\t\tdata as InsertableContent \| undefined,\n\t\t\tschema,\n\t\t);\n\t\tconst result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);\n\t\treturn result as Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n\t},\n};\n"]}
1	+ {"version":3,"file":"treeBeta.js","sourceRoot":"","sources":["../../../src/simple-tree/api/treeBeta.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 type { ITreeCursorSynchronous, TreeFieldStoredSchema } from \"../../core/index.js\";\nimport {\n\tdefaultSchemaPolicy,\n\tFieldKinds,\n\tisTreeValue,\n} from \"../../feature-libraries/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\tContext,\n\tgetKernel,\n\tgetOrCreateNodeFromInnerNode,\n\tisTreeNode,\n\tUnhydratedContext,\n\ttype NodeKind,\n\ttype TreeLeafValue,\n\ttype TreeNode,\n\ttype Unhydrated,\n\ttype WithType,\n} from \"../core/index.js\";\nimport { getUnhydratedContext } from \"../createContext.js\";\nimport type {\n\tImplicitFieldSchema,\n\tInsertableTreeFieldFromImplicitField,\n\tTreeFieldFromImplicitField,\n} from \"../fieldSchema.js\";\nimport {\n\tunhydratedFlexTreeFromInsertable,\n\ttype InsertableContent,\n} from \"../unhydratedFlexTreeFromInsertable.js\";\nimport type { InsertableField, UnsafeUnknownSchema } from \"../unsafeUnknownSchema.js\";\n\nimport { conciseFromCursor, type ConciseTree } from \"./conciseTree.js\";\nimport { createFromCursor } from \"./create.js\";\nimport type { TreeEncodingOptions } from \"./customTree.js\";\nimport type { TreeChangeEvents } from \"./treeChangeEvents.js\";\nimport { treeNodeApi } from \"./treeNodeApi.js\";\nimport { cursorFromVerbose } from \"./verboseTree.js\";\n\n// Tests for this file are grouped with those for treeNodeApi.ts as that is where this functionality will eventually land,\n// and where most of the actual implementation is for much of it.\n\n/\n Data included for {@link TreeChangeEventsBeta.nodeChanged}.\n * @sealed @beta\n /\nexport interface NodeChangedData<TNode extends TreeNode = TreeNode> {\n\t/\n\t When the node changed is an object or Map node, this lists all the properties which changed.\n\t * @remarks\n\t * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).\n\t \n\t Set to `undefined` when the {@link NodeKind} does not support this feature (currently just ArrayNodes).\n\t \n\t When defined, the set should never be empty, since `nodeChanged` will only be triggered when there is a change, and for the supported node types, the only things that can change are properties.\n\t /\n\treadonly changedProperties?: ReadonlySet<\n\t\t// For Object nodes, make changedProperties required and strongly typed with the property names from the schema:\n\t\tTNode extends WithType<string, NodeKind.Object, infer TInfo>\n\t\t\t? string & keyof TInfo\n\t\t\t: string\n\t>;\n}\n\n/\n Extensions to {@link TreeChangeEvents} which are not yet stable.\n \n @sealed @beta\n /\nexport interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>\n\textends TreeChangeEvents {\n\t/\n\t Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.\n\t \n\t - Object nodes define a change as being when the value of one of its properties changes (i.e., the property's value is set, including when set to `undefined`).\n\t \n\t - Array nodes define a change as when an element is added, removed, moved or replaced.\n\t \n\t - Map nodes define a change as when an entry is added, updated, or removed.\n\t \n\t @remarks\n\t * This event is not emitted when:\n\t \n\t - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing\n\t * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the\n\t * array/map node as one of its properties.\n\t \n\t - The node is moved to a different location in the tree or removed from the tree.\n\t * In this case the event is emitted on the _parent_ node, not the node itself.\n\t \n\t For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t \n\t When the event is emitted, the tree is guaranteed to be in-schema.\n\t \n\t @privateRemarks\n\t * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.\n\t * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the\n\t * node, or when the node has to be updated due to resolution of a merge conflict\n\t * (for example a previously applied local change might be undone, then reapplied differently or not at all).\n\t \n\t TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).\n\t \n\t This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.\n\t /\n\tnodeChanged: (\n\t\tdata: NodeChangedData<TNode> &\n\t\t\t// Make the properties of object, map, and record nodes required:\n\t\t\t(TNode extends WithType<string, NodeKind.Map \| NodeKind.Object \| NodeKind.Record>\n\t\t\t\t? Required<Pick<NodeChangedData<TNode>, \"changedProperties\">>\n\t\t\t\t: unknown),\n\t) => void;\n}\n\n/\n Extensions to {@link (Tree:interface)} which are not yet stable.\n * @remarks\n * Use via the {@link (TreeBeta:variable)} singleton.\n * @sealed @beta\n /\nexport interface TreeBeta {\n\t/\n\t Register an event listener on the given node.\n\t * @param node - The node whose events should be subscribed to.\n\t * @param eventName - Which event to subscribe to.\n\t * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.\n\t * @returns A callback function which will deregister the event.\n\t * This callback should be called only once.\n\t /\n\ton<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(\n\t\tnode: TNode,\n\t\teventName: K,\n\t\tlistener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,\n\t): () => void;\n\n\t/\n\t A less type-safe version of {@link (TreeAlpha:interface).create}, suitable for importing data.\n\t * @remarks\n\t * Due to {@link ConciseTree} relying on type inference from the data, its use is somewhat limited.\n\t * This does not support {@link ConciseTree\|ConciseTrees} with customized handle encodings or using persisted keys.\n\t * Use \"compressed\" or \"verbose\" formats for more flexibility.\n\t \n\t When using this function,\n\t * it is recommend to ensure your schema is unambiguous with {@link ITreeConfigurationOptions.preventAmbiguity}.\n\t * If the schema is ambiguous, consider using {@link (TreeAlpha:interface).create} and {@link Unhydrated} nodes where needed,\n\t * or using {@link (TreeAlpha:interface).(importVerbose:1)} and specify all types.\n\t \n\t Documented (and thus recoverable) error handling/reporting for this is not yet implemented,\n\t * but for now most invalid inputs will throw a recoverable error.\n\t /\n\timportConcise<const TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t\tdata: ConciseTree \| undefined,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n\n\t/\n\t Copy a snapshot of the current version of a TreeNode into a {@link ConciseTree}.\n\t /\n\texportConcise(node: TreeNode \| TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;\n\n\t/\n\t Copy a snapshot of the current version of a TreeNode into a {@link ConciseTree}, allowing undefined.\n\t /\n\texportConcise(\n\t\tnode: TreeNode \| TreeLeafValue \| undefined,\n\t\toptions?: TreeEncodingOptions,\n\t): ConciseTree \| undefined;\n\n\t/\n\t Clones the persisted data associated with a node.\n\t \n\t @param node - The node to clone.\n\t * @returns A new unhydrated node with the same persisted data as the original node.\n\t * @remarks\n\t * Some key things to note:\n\t \n\t - Local state, such as properties added to customized schema classes, will not be cloned. However, they will be\n\t * initialized to their default state just as if the node had been created via its constructor.\n\t \n\t - Value node types (i.e., numbers, strings, booleans, nulls and Fluid handles) will be returned as is.\n\t \n\t - The identifiers in the node's subtree will be preserved, i.e., they are not replaced with new values.\n\t \n\t - If the node (or any node in its subtree) contains {@link ObjectSchemaOptions.allowUnknownOptionalFields\|unknown optional fields},\n\t * those fields will be cloned just like the known fields.\n\t /\n\tclone<const TSchema extends ImplicitFieldSchema>(\n\t\tnode: TreeFieldFromImplicitField<TSchema>,\n\t): TreeFieldFromImplicitField<TSchema>;\n\n\t// TODO: support more clone options\n\t// /\n\t// Like {@link (TreeBeta:interface).create}, except deeply clones existing nodes.\n\t// * @remarks\n\t// * This only clones the persisted data associated with a node.\n\t// * Local state, such as properties added to customized schema classes, will not be cloned:\n\t// * they will be initialized however they end up after running the constructor, just like if a remote client had inserted the same nodes.\n\t// /\n\t// clone<const TSchema extends ImplicitFieldSchema>(\n\t// \toriginal: TreeFieldFromImplicitField<TSchema>,\n\t// \toptions?: {\n\t// \t\t/\n\t// \t\t If set, all identifier's in the cloned tree (See {@link SchemaFactory.identifier}) will be replaced with new ones allocated using the default identifier allocation schema.\n\t// \t\t * Otherwise any identifiers will be preserved as is.\n\t// \t\t /\n\t// \t\treplaceIdentifiers?: true;\n\t// \t},\n\t// ): TreeFieldFromImplicitField<TSchema>;\n\n\t/\n\t Construct tree content that is compatible with the field defined by the provided `schema`.\n\t * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.\n\t * @param data - The data used to construct the field content.\n\t * @remarks\n\t * When providing a {@link TreeNodeSchemaClass}, this is the same as invoking its constructor except that an unhydrated node can also be provided.\n\t * This function exists as a generalization that can be used in other cases as well,\n\t * such as when `undefined` might be allowed (for an optional field), or when the type should be inferred from the data when more than one type is possible.\n\t /\n\tcreate<const TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t\tdata: InsertableTreeFieldFromImplicitField<TSchema>,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n}\n\n/\n Borrow a cursor from a node.\n * @remarks\n * The cursor must be put back to its original location before the node is used again.\n /\nexport function borrowCursorFromTreeNodeOrValue(\n\tnode: TreeNode \| TreeLeafValue,\n): ITreeCursorSynchronous {\n\tif (isTreeValue(node)) {\n\t\treturn cursorFromVerbose(node, {});\n\t}\n\tconst kernel = getKernel(node);\n\tconst cursor = kernel.getInnerNode().borrowCursor();\n\treturn cursor;\n}\n\n/\n {@inheritDoc (TreeBeta:interface).importConcise}\n /\nexport function importConcise<TSchema extends ImplicitFieldSchema>(\n\tschema: TSchema & ImplicitFieldSchema,\n\tdata: ConciseTree \| undefined,\n): Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n/\n {@inheritDoc (TreeAlpha:interface).importConcise}\n /\nexport function importConcise<TSchema extends ImplicitFieldSchema \| UnsafeUnknownSchema>(\n\tschema: UnsafeUnknownSchema extends TSchema\n\t\t? ImplicitFieldSchema\n\t\t: TSchema & ImplicitFieldSchema,\n\tdata: ConciseTree \| undefined,\n): Unhydrated<\n\tTSchema extends ImplicitFieldSchema\n\t\t? TreeFieldFromImplicitField<TSchema>\n\t\t: TreeNode \| TreeLeafValue \| undefined\n>;\nexport function importConcise<TSchema extends ImplicitFieldSchema \| UnsafeUnknownSchema>(\n\tschema: UnsafeUnknownSchema extends TSchema\n\t\t? ImplicitFieldSchema\n\t\t: TSchema & ImplicitFieldSchema,\n\tdata: ConciseTree \| undefined,\n): Unhydrated<\n\tTSchema extends ImplicitFieldSchema\n\t\t? TreeFieldFromImplicitField<TSchema>\n\t\t: TreeNode \| TreeLeafValue \| undefined\n> {\n\t// Create the tree content from insertable data\n\tconst mapTree = unhydratedFlexTreeFromInsertable(\n\t\tdata as InsertableField<UnsafeUnknownSchema>,\n\t\tschema,\n\t);\n\tconst result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);\n\treturn result as Unhydrated<\n\t\tTSchema extends ImplicitFieldSchema\n\t\t\t? TreeFieldFromImplicitField<TSchema>\n\t\t\t: TreeNode \| TreeLeafValue \| undefined\n\t>;\n}\n\n/\n {@inheritDoc (TreeBeta:interface).(exportConcise:1)}\n /\nexport function exportConcise(\n\tnode: TreeNode \| TreeLeafValue,\n\toptions?: TreeEncodingOptions,\n): ConciseTree;\n/\n {@inheritDoc (TreeBeta:interface).(exportConcise:2)}\n /\nexport function exportConcise(\n\tnode: TreeNode \| TreeLeafValue \| undefined,\n\toptions?: TreeEncodingOptions,\n): ConciseTree \| undefined;\nexport function exportConcise(\n\tnode: TreeNode \| TreeLeafValue \| undefined,\n\toptions?: TreeEncodingOptions,\n): ConciseTree \| undefined {\n\tif (!isTreeNode(node)) {\n\t\treturn node;\n\t}\n\tconst config: TreeEncodingOptions = { ...options };\n\n\tconst kernel = getKernel(node);\n\tconst cursor = borrowCursorFromTreeNodeOrValue(node);\n\treturn conciseFromCursor(cursor, kernel.context, config);\n}\n\n/\n Extensions to {@link (Tree:variable)} which are not yet stable.\n * @see {@link (TreeBeta:interface)}.\n * @beta\n */\nexport const TreeBeta: TreeBeta = {\n\ton<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(\n\t\tnode: TNode,\n\t\teventName: K,\n\t\tlistener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,\n\t): () => void {\n\t\treturn treeNodeApi.on(node, eventName, listener);\n\t},\n\n\timportConcise,\n\texportConcise,\n\n\tclone<const TSchema extends ImplicitFieldSchema>(\n\t\tnode: TreeFieldFromImplicitField<TSchema>,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>> {\n\t\t// The only non-TreeNode cases are {@link TreeLeafValue} and `undefined` (for an empty optional field) which can be returned as is.\n\t\tif (!isTreeNode(node)) {\n\t\t\treturn node;\n\t\t}\n\n\t\tconst kernel = getKernel(node);\n\t\tconst cursor = kernel.getInnerNode().borrowCursor();\n\n\t\t// To handle when the node transitively contains unknown optional fields,\n\t\t// derive the context from the source node's stored schema which has stored schema for any such fields and their contents.\n\t\tconst flexContext = new UnhydratedContext(\n\t\t\tdefaultSchemaPolicy,\n\t\t\tkernel.context.flexContext.schema,\n\t\t);\n\t\tconst context = new Context(flexContext, getUnhydratedContext(kernel.schema).schema);\n\n\t\tconst fieldSchema: TreeFieldStoredSchema = {\n\t\t\tkind: FieldKinds.required.identifier,\n\t\t\ttypes: new Set([brand(kernel.schema.identifier)]),\n\t\t\tpersistedMetadata: undefined,\n\t\t};\n\t\treturn createFromCursor(kernel.schema, cursor, fieldSchema, context) as Unhydrated<\n\t\t\tTreeFieldFromImplicitField<TSchema>\n\t\t>;\n\t},\n\n\tcreate<const TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t\tdata: InsertableTreeFieldFromImplicitField<TSchema>,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>> {\n\t\tconst mapTree = unhydratedFlexTreeFromInsertable(\n\t\t\tdata as InsertableContent \| undefined,\n\t\t\tschema,\n\t\t);\n\t\tconst result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);\n\t\treturn result as Unhydrated<TreeFieldFromImplicitField<TSchema>>;\n\t},\n};\n"]}

package/dist/simple-tree/core/allowedTypes.d.ts CHANGED Viewed

@@ -319,7 +319,7 @@ export type TreeNodeFromImplicitAllowedTypes<TSchema extends ImplicitAllowedType
  * This type exists only to be linked from documentation to provide a single linkable place to document some details of
  * "Input" types and how they handle schema.
  *
- * When a schema is used to describe data which is an input into an API, the API is {@link https://en.wikipedia.org/wiki/Type_variance | contravariant}) over the schema.
+ * When a schema is used to describe data which is an input into an API, the API is {@link https://en.wikipedia.org/wiki/Type_variance | contravariant} over the schema.
  * (See also {@link https://www.typescriptlang.org/docs/handbook/2/generics.html#variance-annotations | TypeScript Variance Annotations}).
  *
  * Since these schema are expressed using TypeScript types, it is possible for the user of the API to provide non-exact values of these types which has implications that depended on the variance.