@fluidframework/tree 2.74.0 → 2.81.0-374083

package/lib/text/textDomain.d.ts

@@ -0,0 +1,138 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { TreeNode, WithType } from "../simple-tree/index.js";
+/**
+ * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
+ * @privateRemarks
+ * Currently this API only supports a really minimal feature set, and has no support for more advanced features like:
+ * - Alternative character boundaries (e.g. grapheme clusters, paragraphs, tokens, etc.).
+ * We may want to provide either ways to create strings with application controlled character boundaries since there is not a clear single answer on how to break a string into atomic units.
+ * - Character attributes (e.g. bold, italic, etc):
+ * Properties that can be set on any character independently with optimizations for runs of characters with the same attributes.
+ * - Inline objects (e.g. images, embedded components, etc):
+ * These would be logically part of the text, generalizing characters to allow inline objects in character ranges.
+ * How character attributes apply to inline objects is an open question
+ * (there could be a kind of object which gets them, and one that doesn't for example).
+ * - Annotations (e.g. comments, suggestions, etc).
+ * Objects which can be associated with a range of characters but are not logically part of the text.
+ * These would need to have the logical range they apply to updated by edits.
+ * How edits which overlap annotation boundaries are handled may require hints from the application for optimal behavior (mainly inserts at the boundaries).
+ * These get a lifetime tied to the text node, not any of the characters the annotation covers,
+ * however it might be desirable to have a way for a range edit to (optionally) also remove any annotations which are fully covered by the edit.
+ * Annotations over an empty range should also be supported and behave well (for example not end up with characters inside the range after edits unless specifically structured so that makes sense).
+ * - Anchors (e.g. positions in the text which survive edits).
+ * These would be useful for ephemeral state like cursor positions, but should match the behaviors with respect to edits exhibited by the ends of Annotations.
+ *
+ * How these features will be represented in the schema and API should be determined before any of this is stabilized so the simple more limited version can neatly fit into the larger design.
+ *
+ * There are various optimizations that should be implemented to make this performant for large texts and common usage patterns.
+ * These include:
+ * - Optimized persisted format.
+ * - Optimized in memory representation (via chunked forest).
+ * - Optimized edit persisted format (e.g. combining adjacent inserts/removes into single operations as well as support for efficient attribute editing of ranges).
+ * - Optimized edit application (e.g. applying the above noted optimizable edit cases efficiently).
+ * This applies to the revision manager, the forest, and any flex or simple-tree nodes and user events.
+ *
+ * There are also additional features required for ensuring the invariants of collaborative text editing are maintained through concurrent edits.
+ * The main challenges here are related to annotations, but some policies for what to do in the case of corrupt/invalid text should also be included.
+ * There are quite a few ways invariants could break, including:
+ * - concurrent edits without proper constraints.
+ * - collaboration with clients using compatible schema with different constraints.
+ * - opening documents which contain invalid content (e.g. from older versions of the software, manual edits to the persisted format, or simply an existing corrupt case which was saved).
+ * - a user inserting/constructing/importing invalid content.
+ *
+ * These cases could break constraints causing issues like invalided characters (empty, a utf-16 surrogate pair alone, etc) or
+ * annotations which reference out of bounds character ranges.
+ * Addressing these issues mainly falls into these categories:
+ * - Handling of invalid content on import/construction of unhydrated nodes and/or insertion into the document (hydration).
+ * - Handling of invalid content which is already part of the document (live). This should ideally include both detection and repair.
+ * - Constraints on edits to prevent invalid content from being created by merges.
+ * - Optimization of the constraints to reduce cases in which edits are rejected due to conflicts.
+ *
+ * Note that these cases of invariant violations are the same cases any component should handle, so ideally there would be a general framework or pattern for documenting and enforcing such constraints.
+ *
+ * Another area for future work is improved APIs for import, export and non-schema-aware use. This includes a variety of cases, including but not limited to:
+ * - Insertable content format (taken by the constructor and import APIs).
+ * - Customizable export formats (like a way to make exportVerbose and exportConcise flatten the text nodes to strings automatically).
+ * - Customizable toJson behavior (e.g. flattening to strings, possibly via tools or patterns for custom tree stringifier).
+ * - Ensure JS object APIs (like iteration, own vs inherited properties, etc) provide a good and consistent experience with respect to other nodes.
+ * - Support in generateSchemaFromSimpleSchema for recognizing text nodes and generating the appropriate schema.
+ * - Ensure above features work well enough to support important scenarios like AI assisted editing and document indexing for search.
+ *
+ * Part of that work will be establishing and documenting those patterns so other components with complex encodings can follow them,
+ * in addition to implementing them for text.
+ * @internal
+ */
+export declare namespace TextAsTree {
+    /**
+     * Statics for text nodes.
+     * @internal
+     */
+    interface Statics {
+        /**
+         * Construct a {@link TextAsTree.(Tree:type)} from a string, where each character (as defined by iterating over the string) becomes a single character in the text node.
+         * This combines pairs of utf-16 surrogate code units into single characters as appropriate.
+         */
+        fromString(value: string): Tree;
+    }
+    /**
+     * Interface for a text node.
+     * @remarks
+     * The string is broken up into substrings which are referred to as 'characters'.
+     * Unlike with JavaScript strings, all indexes are by character, not UTF-16 code unit.
+     * This avoids the problem JavaScript where it can split UTF-16 surrogate pairs producing invalid strings,
+     * and avoids the issue where indexing a string and iterating it segment the string differently.
+     * This does NOT mean the characters correspond to user perceived characters (like grapheme clusters try to do):
+     * applications will likely want to include higher level segmentation logic
+     * which might differ between operations like delete
+     * (which often operates on something in between unicode code points and grapheme clusters)
+     * and navigation/selection (which typically uses grapheme clusters).
+     *
+     * @see {@link TextAsTree.Statics.fromString} for construction.
+     * @see {@link TextAsTree.(Tree:type)} for schema.
+     * @internal
+     */
+    interface Members {
+        /**
+         * Gets an iterable over the characters currently in the text.
+         * @remarks
+         * This iterator matches the behavior of {@link (TreeArrayNode:interface)} with respect to edits during iteration.
+         */
+        characters(): Iterable<string>;
+        /**
+         * Copy the content of this node into a string.
+         */
+        fullString(): string;
+        /**
+         * Insert a range of characters into the string based on character index.
+         * @remarks
+         * See {@link (TreeArrayNode:interface).insertAt} for more details on the behavior.
+         * See {@link TextAsTree.Statics.fromString} for how the `additionalCharacters` string is broken into characters.
+         * @privateRemarks
+         * If we provide ways to customize character boundaries, that could be handled here by taking in an Iterable<string> instead of a string.
+         * Doing this currently would enable insertion of text with different character boundaries than the existing text,
+         * which would violate the currently documented character boundary invariants.
+         *
+         * Another option would be to take an approach like Table,
+         * where the user of the API uses a factory function to generate the schema, and can inject custom logic, like a string character iterator.
+         */
+        insertAt(index: number, additionalCharacters: string): void;
+        /**
+         * Remove a range from a string based on character index.
+         * See {@link (TreeArrayNode:interface).removeRange} for more details on the behavior.
+         */
+        removeRange(index: number, length: number): void;
+    }
+    /**
+     * Schema for a text node.
+     * @remarks
+     * See {@link TextAsTree.Members} for the API.
+     * See {@link TextAsTree.Statics} for static APIs on this Schema, including construction.
+     * @internal
+     */
+    const Tree: Statics & import("../simple-tree/index.js").TreeNodeSchema<"com.fluidframework.text.Text", import("../simple-tree/index.js").NodeKind, Members & TreeNode & WithType<"com.fluidframework.text.Text", import("../simple-tree/index.js").NodeKind, unknown>, never, false>;
+    type Tree = Members & TreeNode & WithType<"com.fluidframework.text.Text">;
+}
+//# sourceMappingURL=textDomain.d.ts.map

package/lib/text/textDomain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textDomain.d.ts","sourceRoot":"","sources":["../../src/text/textDomain.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAkDlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,yBAAiB,UAAU,CAAC;IAC3B;;;OAGG;IACH,UAAiB,OAAO;QACvB;;;WAGG;QACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;KAChC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,UAAiB,OAAO;QACvB;;;;WAIG;QACH,UAAU,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;QAE/B;;WAEG;QACH,UAAU,IAAI,MAAM,CAAC;QAErB;;;;;;;;;;;;WAYG;QACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;QAE5D;;;WAGG;QACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KACjD;IAED;;;;;;OAMG;IACI,MAAM,IAAI,0QAAmD,CAAC;IACrE,KAAY,IAAI,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC,8BAA8B,CAAC,CAAC;CACjF"}

package/lib/text/textDomain.js

@@ -0,0 +1,118 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { EmptyKey } from "../core/index.js";
+import { eraseSchemaDetails, SchemaFactory, SchemaFactoryAlpha, TreeArrayNode, } from "../simple-tree/index.js";
+const sf = new SchemaFactoryAlpha("com.fluidframework.text");
+class TextNode extends sf.object("Text", {
+    content: SchemaFactory.required([() => StringArray], { key: EmptyKey }),
+}) {
+    insertAt(index, additionalCharacters) {
+        this.content.insertAt(index, TreeArrayNode.spread(charactersFromString(additionalCharacters)));
+    }
+    removeRange(index, length) {
+        this.content.removeRange(index, length);
+    }
+    characters() {
+        return this.content[Symbol.iterator]();
+    }
+    fullString() {
+        return this.content.join("");
+    }
+    static fromString(value) {
+        // Constructing an ArrayNode from an iterator is supported, so creating an array from the iterable of characters seems like its not necessary here,
+        // but to reduce the risk of incorrect data interpretation, we actually ban this in the special case where the iterable is a string directly, which is the case here.
+        // Thus the array construction here is necessary to avoid a runtime error.
+        return new TextNode({ content: [...charactersFromString(value)] });
+    }
+}
+/**
+ * Interpret a string as an iterable of characters.
+ * @remarks
+ * This mostly exists to clearly document where the code is interpreting a string as characters,
+ * and provide a centralized place where validation could be added in the future if desired.
+ * Additionally using this function consistently will make any refactors to support alternative character boundaries easier.
+ */
+function charactersFromString(value) {
+    // Uses the string as an iterable of characters, so utf-16 surrogate pairs get grouped together correctly.
+    // Might be nice to call isWellFormed or toWellFormed here (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toWellFormed)
+    // But those are not widely supported yet.
+    return value;
+}
+class StringArray extends sf.array("StringArray", SchemaFactory.string) {
+}
+/**
+ * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
+ * @privateRemarks
+ * Currently this API only supports a really minimal feature set, and has no support for more advanced features like:
+ * - Alternative character boundaries (e.g. grapheme clusters, paragraphs, tokens, etc.).
+ * We may want to provide either ways to create strings with application controlled character boundaries since there is not a clear single answer on how to break a string into atomic units.
+ * - Character attributes (e.g. bold, italic, etc):
+ * Properties that can be set on any character independently with optimizations for runs of characters with the same attributes.
+ * - Inline objects (e.g. images, embedded components, etc):
+ * These would be logically part of the text, generalizing characters to allow inline objects in character ranges.
+ * How character attributes apply to inline objects is an open question
+ * (there could be a kind of object which gets them, and one that doesn't for example).
+ * - Annotations (e.g. comments, suggestions, etc).
+ * Objects which can be associated with a range of characters but are not logically part of the text.
+ * These would need to have the logical range they apply to updated by edits.
+ * How edits which overlap annotation boundaries are handled may require hints from the application for optimal behavior (mainly inserts at the boundaries).
+ * These get a lifetime tied to the text node, not any of the characters the annotation covers,
+ * however it might be desirable to have a way for a range edit to (optionally) also remove any annotations which are fully covered by the edit.
+ * Annotations over an empty range should also be supported and behave well (for example not end up with characters inside the range after edits unless specifically structured so that makes sense).
+ * - Anchors (e.g. positions in the text which survive edits).
+ * These would be useful for ephemeral state like cursor positions, but should match the behaviors with respect to edits exhibited by the ends of Annotations.
+ *
+ * How these features will be represented in the schema and API should be determined before any of this is stabilized so the simple more limited version can neatly fit into the larger design.
+ *
+ * There are various optimizations that should be implemented to make this performant for large texts and common usage patterns.
+ * These include:
+ * - Optimized persisted format.
+ * - Optimized in memory representation (via chunked forest).
+ * - Optimized edit persisted format (e.g. combining adjacent inserts/removes into single operations as well as support for efficient attribute editing of ranges).
+ * - Optimized edit application (e.g. applying the above noted optimizable edit cases efficiently).
+ * This applies to the revision manager, the forest, and any flex or simple-tree nodes and user events.
+ *
+ * There are also additional features required for ensuring the invariants of collaborative text editing are maintained through concurrent edits.
+ * The main challenges here are related to annotations, but some policies for what to do in the case of corrupt/invalid text should also be included.
+ * There are quite a few ways invariants could break, including:
+ * - concurrent edits without proper constraints.
+ * - collaboration with clients using compatible schema with different constraints.
+ * - opening documents which contain invalid content (e.g. from older versions of the software, manual edits to the persisted format, or simply an existing corrupt case which was saved).
+ * - a user inserting/constructing/importing invalid content.
+ *
+ * These cases could break constraints causing issues like invalided characters (empty, a utf-16 surrogate pair alone, etc) or
+ * annotations which reference out of bounds character ranges.
+ * Addressing these issues mainly falls into these categories:
+ * - Handling of invalid content on import/construction of unhydrated nodes and/or insertion into the document (hydration).
+ * - Handling of invalid content which is already part of the document (live). This should ideally include both detection and repair.
+ * - Constraints on edits to prevent invalid content from being created by merges.
+ * - Optimization of the constraints to reduce cases in which edits are rejected due to conflicts.
+ *
+ * Note that these cases of invariant violations are the same cases any component should handle, so ideally there would be a general framework or pattern for documenting and enforcing such constraints.
+ *
+ * Another area for future work is improved APIs for import, export and non-schema-aware use. This includes a variety of cases, including but not limited to:
+ * - Insertable content format (taken by the constructor and import APIs).
+ * - Customizable export formats (like a way to make exportVerbose and exportConcise flatten the text nodes to strings automatically).
+ * - Customizable toJson behavior (e.g. flattening to strings, possibly via tools or patterns for custom tree stringifier).
+ * - Ensure JS object APIs (like iteration, own vs inherited properties, etc) provide a good and consistent experience with respect to other nodes.
+ * - Support in generateSchemaFromSimpleSchema for recognizing text nodes and generating the appropriate schema.
+ * - Ensure above features work well enough to support important scenarios like AI assisted editing and document indexing for search.
+ *
+ * Part of that work will be establishing and documenting those patterns so other components with complex encodings can follow them,
+ * in addition to implementing them for text.
+ * @internal
+ */
+export var TextAsTree;
+(function (TextAsTree) {
+    /**
+     * Schema for a text node.
+     * @remarks
+     * See {@link TextAsTree.Members} for the API.
+     * See {@link TextAsTree.Statics} for static APIs on this Schema, including construction.
+     * @internal
+     */
+    TextAsTree.Tree = eraseSchemaDetails()(TextNode);
+})(TextAsTree || (TextAsTree = {}));
+//# sourceMappingURL=textDomain.js.map

package/lib/text/textDomain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textDomain.js","sourceRoot":"","sources":["../../src/text/textDomain.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EACN,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,aAAa,GACb,MAAM,yBAAyB,CAAC;AAGjC,MAAM,EAAE,GAAG,IAAI,kBAAkB,CAAC,yBAAyB,CAAC,CAAC;AAE7D,MAAM,QACL,SAAQ,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE;IACzB,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;CACvE,CAAC;IAGK,QAAQ,CAAC,KAAa,EAAE,oBAA4B;QAC1D,IAAI,CAAC,OAAO,CAAC,QAAQ,CACpB,KAAK,EACL,aAAa,CAAC,MAAM,CAAC,oBAAoB,CAAC,oBAAoB,CAAC,CAAC,CAChE,CAAC;IACH,CAAC;IACM,WAAW,CAAC,KAAa,EAAE,MAAc;QAC/C,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACzC,CAAC;IACM,UAAU;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;IACxC,CAAC;IACM,UAAU;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAEM,MAAM,CAAC,UAAU,CAAC,KAAa;QACrC,mJAAmJ;QACnJ,qKAAqK;QACrK,0EAA0E;QAC1E,OAAO,IAAI,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;IACpE,CAAC;CACD;AAED;;;;;;GAMG;AACH,SAAS,oBAAoB,CAAC,KAAa;IAC1C,0GAA0G;IAC1G,iKAAiK;IACjK,0CAA0C;IAC1C,OAAO,KAAK,CAAC;AACd,CAAC;AAED,MAAM,WAAY,SAAQ,EAAE,CAAC,KAAK,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC;CAAG;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,MAAM,KAAW,UAAU,CA0E1B;AA1ED,WAAiB,UAAU;IAiE1B;;;;;;OAMG;IACU,eAAI,GAAG,kBAAkB,EAAoB,CAAC,QAAQ,CAAC,CAAC;AAEtE,CAAC,EA1EgB,UAAU,KAAV,UAAU,QA0E1B","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { EmptyKey } from \"../core/index.js\";\nimport {\n\teraseSchemaDetails,\n\tSchemaFactory,\n\tSchemaFactoryAlpha,\n\tTreeArrayNode,\n} from \"../simple-tree/index.js\";\nimport type { TreeNode, WithType } from \"../simple-tree/index.js\";\n\nconst sf = new SchemaFactoryAlpha(\"com.fluidframework.text\");\n\nclass TextNode\n\textends sf.object(\"Text\", {\n\t\tcontent: SchemaFactory.required([() => StringArray], { key: EmptyKey }),\n\t})\n\timplements TextAsTree.Members\n{\n\tpublic insertAt(index: number, additionalCharacters: string): void {\n\t\tthis.content.insertAt(\n\t\t\tindex,\n\t\t\tTreeArrayNode.spread(charactersFromString(additionalCharacters)),\n\t\t);\n\t}\n\tpublic removeRange(index: number, length: number): void {\n\t\tthis.content.removeRange(index, length);\n\t}\n\tpublic characters(): Iterable<string> {\n\t\treturn this.content[Symbol.iterator]();\n\t}\n\tpublic fullString(): string {\n\t\treturn this.content.join(\"\");\n\t}\n\n\tpublic static fromString(value: string): TextNode {\n\t\t// Constructing an ArrayNode from an iterator is supported, so creating an array from the iterable of characters seems like its not necessary here,\n\t\t// but to reduce the risk of incorrect data interpretation, we actually ban this in the special case where the iterable is a string directly, which is the case here.\n\t\t// Thus the array construction here is necessary to avoid a runtime error.\n\t\treturn new TextNode({ content: [...charactersFromString(value)] });\n\t}\n}\n\n/**\n * Interpret a string as an iterable of characters.\n * @remarks\n * This mostly exists to clearly document where the code is interpreting a string as characters,\n * and provide a centralized place where validation could be added in the future if desired.\n * Additionally using this function consistently will make any refactors to support alternative character boundaries easier.\n */\nfunction charactersFromString(value: string): Iterable<string> {\n\t// Uses the string as an iterable of characters, so utf-16 surrogate pairs get grouped together correctly.\n\t// Might be nice to call isWellFormed or toWellFormed here (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toWellFormed)\n\t// But those are not widely supported yet.\n\treturn value;\n}\n\nclass StringArray extends sf.array(\"StringArray\", SchemaFactory.string) {}\n\n/**\n * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.\n * @privateRemarks\n * Currently this API only supports a really minimal feature set, and has no support for more advanced features like:\n * - Alternative character boundaries (e.g. grapheme clusters, paragraphs, tokens, etc.).\n * We may want to provide either ways to create strings with application controlled character boundaries since there is not a clear single answer on how to break a string into atomic units.\n * - Character attributes (e.g. bold, italic, etc):\n * Properties that can be set on any character independently with optimizations for runs of characters with the same attributes.\n * - Inline objects (e.g. images, embedded components, etc):\n * These would be logically part of the text, generalizing characters to allow inline objects in character ranges.\n * How character attributes apply to inline objects is an open question\n * (there could be a kind of object which gets them, and one that doesn't for example).\n * - Annotations (e.g. comments, suggestions, etc).\n * Objects which can be associated with a range of characters but are not logically part of the text.\n * These would need to have the logical range they apply to updated by edits.\n * How edits which overlap annotation boundaries are handled may require hints from the application for optimal behavior (mainly inserts at the boundaries).\n * These get a lifetime tied to the text node, not any of the characters the annotation covers,\n * however it might be desirable to have a way for a range edit to (optionally) also remove any annotations which are fully covered by the edit.\n * Annotations over an empty range should also be supported and behave well (for example not end up with characters inside the range after edits unless specifically structured so that makes sense).\n * - Anchors (e.g. positions in the text which survive edits).\n * These would be useful for ephemeral state like cursor positions, but should match the behaviors with respect to edits exhibited by the ends of Annotations.\n *\n * How these features will be represented in the schema and API should be determined before any of this is stabilized so the simple more limited version can neatly fit into the larger design.\n *\n * There are various optimizations that should be implemented to make this performant for large texts and common usage patterns.\n * These include:\n * - Optimized persisted format.\n * - Optimized in memory representation (via chunked forest).\n * - Optimized edit persisted format (e.g. combining adjacent inserts/removes into single operations as well as support for efficient attribute editing of ranges).\n * - Optimized edit application (e.g. applying the above noted optimizable edit cases efficiently).\n * This applies to the revision manager, the forest, and any flex or simple-tree nodes and user events.\n *\n * There are also additional features required for ensuring the invariants of collaborative text editing are maintained through concurrent edits.\n * The main challenges here are related to annotations, but some policies for what to do in the case of corrupt/invalid text should also be included.\n * There are quite a few ways invariants could break, including:\n * - concurrent edits without proper constraints.\n * - collaboration with clients using compatible schema with different constraints.\n * - opening documents which contain invalid content (e.g. from older versions of the software, manual edits to the persisted format, or simply an existing corrupt case which was saved).\n * - a user inserting/constructing/importing invalid content.\n *\n * These cases could break constraints causing issues like invalided characters (empty, a utf-16 surrogate pair alone, etc) or\n * annotations which reference out of bounds character ranges.\n * Addressing these issues mainly falls into these categories:\n * - Handling of invalid content on import/construction of unhydrated nodes and/or insertion into the document (hydration).\n * - Handling of invalid content which is already part of the document (live). This should ideally include both detection and repair.\n * - Constraints on edits to prevent invalid content from being created by merges.\n * - Optimization of the constraints to reduce cases in which edits are rejected due to conflicts.\n *\n * Note that these cases of invariant violations are the same cases any component should handle, so ideally there would be a general framework or pattern for documenting and enforcing such constraints.\n *\n * Another area for future work is improved APIs for import, export and non-schema-aware use. This includes a variety of cases, including but not limited to:\n * - Insertable content format (taken by the constructor and import APIs).\n * - Customizable export formats (like a way to make exportVerbose and exportConcise flatten the text nodes to strings automatically).\n * - Customizable toJson behavior (e.g. flattening to strings, possibly via tools or patterns for custom tree stringifier).\n * - Ensure JS object APIs (like iteration, own vs inherited properties, etc) provide a good and consistent experience with respect to other nodes.\n * - Support in generateSchemaFromSimpleSchema for recognizing text nodes and generating the appropriate schema.\n * - Ensure above features work well enough to support important scenarios like AI assisted editing and document indexing for search.\n *\n * Part of that work will be establishing and documenting those patterns so other components with complex encodings can follow them,\n * in addition to implementing them for text.\n * @internal\n */\nexport namespace TextAsTree {\n\t/**\n\t * Statics for text nodes.\n\t * @internal\n\t */\n\texport interface Statics {\n\t\t/**\n\t\t * Construct a {@link TextAsTree.(Tree:type)} from a string, where each character (as defined by iterating over the string) becomes a single character in the text node.\n\t\t * This combines pairs of utf-16 surrogate code units into single characters as appropriate.\n\t\t */\n\t\tfromString(value: string): Tree;\n\t}\n\n\t/**\n\t * Interface for a text node.\n\t * @remarks\n\t * The string is broken up into substrings which are referred to as 'characters'.\n\t * Unlike with JavaScript strings, all indexes are by character, not UTF-16 code unit.\n\t * This avoids the problem JavaScript where it can split UTF-16 surrogate pairs producing invalid strings,\n\t * and avoids the issue where indexing a string and iterating it segment the string differently.\n\t * This does NOT mean the characters correspond to user perceived characters (like grapheme clusters try to do):\n\t * applications will likely want to include higher level segmentation logic\n\t * which might differ between operations like delete\n\t * (which often operates on something in between unicode code points and grapheme clusters)\n\t * and navigation/selection (which typically uses grapheme clusters).\n\t *\n\t * @see {@link TextAsTree.Statics.fromString} for construction.\n\t * @see {@link TextAsTree.(Tree:type)} for schema.\n\t * @internal\n\t */\n\texport interface Members {\n\t\t/**\n\t\t * Gets an iterable over the characters currently in the text.\n\t\t * @remarks\n\t\t * This iterator matches the behavior of {@link (TreeArrayNode:interface)} with respect to edits during iteration.\n\t\t */\n\t\tcharacters(): Iterable<string>;\n\n\t\t/**\n\t\t * Copy the content of this node into a string.\n\t\t */\n\t\tfullString(): string;\n\n\t\t/**\n\t\t * Insert a range of characters into the string based on character index.\n\t\t * @remarks\n\t\t * See {@link (TreeArrayNode:interface).insertAt} for more details on the behavior.\n\t\t * See {@link TextAsTree.Statics.fromString} for how the `additionalCharacters` string is broken into characters.\n\t\t * @privateRemarks\n\t\t * If we provide ways to customize character boundaries, that could be handled here by taking in an Iterable<string> instead of a string.\n\t\t * Doing this currently would enable insertion of text with different character boundaries than the existing text,\n\t\t * which would violate the currently documented character boundary invariants.\n\t\t *\n\t\t * Another option would be to take an approach like Table,\n\t\t * where the user of the API uses a factory function to generate the schema, and can inject custom logic, like a string character iterator.\n\t\t */\n\t\tinsertAt(index: number, additionalCharacters: string): void;\n\n\t\t/**\n\t\t * Remove a range from a string based on character index.\n\t\t * See {@link (TreeArrayNode:interface).removeRange} for more details on the behavior.\n\t\t */\n\t\tremoveRange(index: number, length: number): void;\n\t}\n\n\t/**\n\t * Schema for a text node.\n\t * @remarks\n\t * See {@link TextAsTree.Members} for the API.\n\t * See {@link TextAsTree.Statics} for static APIs on this Schema, including construction.\n\t * @internal\n\t */\n\texport const Tree = eraseSchemaDetails<Members, Statics>()(TextNode);\n\texport type Tree = Members & TreeNode & WithType<\"com.fluidframework.text.Text\">;\n}\n"]}

package/lib/treeFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"treeFactory.d.ts","sourceRoot":"","sources":["../src/treeFactory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EACN,KAAK,aAAa,EAClB,KAAK,iBAAiB,EAMtB,MAAM,6CAA6C,CAAC;AAGrD,OAAO,EAEN,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAE9B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAQpD;;;;GAIG;AACH,MAAM,WAAW,WAAY,SAAQ,aAAa,EAAE,YAAY;CAAG;AA8DnE;;;;GAIG;AACH,eAAO,MAAM,UAAU,oDAA2B,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,qBAAqB,GAC5B,gBAAgB,CAAC,KAAK,CAAC,CAEzB;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,qBAAqB,GAC5B,iBAAiB,CAAC,KAAK,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAEpD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,iBAAiB,GACxB,gBAAgB,CAAC,KAAK,CAAC,CAEzB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,iBAAiB,GACxB,iBAAiB,CAAC,KAAK,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAGpD;AAED,wBAAgB,4BAA4B,CAC3C,OAAO,EAAE,yBAAyB,GAChC,iBAAiB,CAAC,KAAK,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,CASpD;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,yBAAyB,CAQpF"}
+{"version":3,"file":"treeFactory.d.ts","sourceRoot":"","sources":["../src/treeFactory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EACN,KAAK,aAAa,EAClB,KAAK,iBAAiB,EAMtB,MAAM,6CAA6C,CAAC;AAGrD,OAAO,EAEN,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAE9B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAUpD;;;;GAIG;AACH,MAAM,WAAW,WAAY,SAAQ,aAAa,EAAE,YAAY;CAAG;AA8DnE;;;;GAIG;AACH,eAAO,MAAM,UAAU,oDAA2B,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,qBAAqB,GAC5B,gBAAgB,CAAC,KAAK,CAAC,CAEzB;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,qBAAqB,GAC5B,iBAAiB,CAAC,KAAK,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAEpD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,iBAAiB,GACxB,gBAAgB,CAAC,KAAK,CAAC,CAEzB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,iBAAiB,GACxB,iBAAiB,CAAC,KAAK,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAGpD;AAED,wBAAgB,4BAA4B,CAC3C,OAAO,EAAE,yBAAyB,GAChC,iBAAiB,CAAC,KAAK,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,CASpD;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,yBAAyB,CAQpF"}

package/lib/treeFactory.js

@@ -8,7 +8,7 @@ import { SharedTreeKernel, } from "./shared-tree/index.js";
 import { SharedTreeFactoryType, SharedTreeAttributes } from "./sharedTreeAttributes.js";
 import { Breakable, copyProperty } from "./util/index.js";
 import { FluidClientVersion } from "./codec/index.js";
-import { editManagerFormatVersionSelectorForSharedBranches, messageFormatVersionSelectorForSharedBranches, } from "./shared-tree-core/index.js";
+import { editManagerFormatVersionSelectorForDetachedRootEditing, editManagerFormatVersionSelectorForSharedBranches, messageFormatVersionSelectorForDetachedRootEditing, messageFormatVersionSelectorForSharedBranches, } from "./shared-tree-core/index.js";
 /**
  * Creates a factory for shared tree kernels with the given options.
  * @remarks
@@ -133,18 +133,32 @@ export function configuredSharedTreeInternal(options) {
 }
 export function resolveOptions(options) {
     const internal = {
-        ...resolveSharedBranchesOptions(options.enableSharedBranches),
+        ...resolveFormatOptions(options),
     };
     for (const optionName of Object.keys(options)) {
         copyProperty(options, optionName, internal);
     }
     return internal;
 }
-function resolveSharedBranchesOptions(enableSharedBranches) {
-    return enableSharedBranches === true ? sharedBranchesOptions : {};
+function resolveFormatOptions(options) {
+    if (options.enableSharedBranches === true && options.enableDetachedRootEditing === true) {
+        throw new UsageError("enableDetachRootEditing cannot be used with enableSharedBranches.");
+    }
+    if (options.enableSharedBranches === true) {
+        return sharedBranchesOptions;
+    }
+    if (options.enableDetachedRootEditing === true) {
+        return detachRootEditingOptions;
+    }
+    return {};
 }
 const sharedBranchesOptions = {
     messageFormatSelector: messageFormatVersionSelectorForSharedBranches,
     editManagerFormatSelector: editManagerFormatVersionSelectorForSharedBranches,
 };
+const detachRootEditingOptions = {
+    messageFormatSelector: messageFormatVersionSelectorForDetachedRootEditing,
+    editManagerFormatSelector: editManagerFormatVersionSelectorForDetachedRootEditing,
+    canMakeDetachedRootEdits: true,
+};
 //# sourceMappingURL=treeFactory.js.map

package/lib/treeFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"treeFactory.js","sourceRoot":"","sources":["../src/treeFactory.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 { IChannelStorageService } from \"@fluidframework/datastore-definitions/internal\";\nimport type { SharedObjectKind } from \"@fluidframework/shared-object-base\";\nimport {\n\ttype ISharedObject,\n\ttype ISharedObjectKind,\n\tmakeSharedObjectKind,\n\ttype KernelArgs,\n\ttype SharedKernelFactory,\n\ttype SharedObjectOptions,\n\ttype FactoryOut,\n} from \"@fluidframework/shared-object-base/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport {\n\tSharedTreeKernel,\n\ttype ITreePrivate,\n\ttype SharedTreeOptions,\n\ttype SharedTreeOptionsBeta,\n\ttype SharedTreeOptionsInternal,\n\ttype SharedTreeKernelView,\n} from \"./shared-tree/index.js\";\nimport { SharedTreeFactoryType, SharedTreeAttributes } from \"./sharedTreeAttributes.js\";\nimport type { ITree } from \"./simple-tree/index.js\";\nimport { Breakable, copyProperty } from \"./util/index.js\";\nimport { FluidClientVersion } from \"./codec/index.js\";\nimport {\n\teditManagerFormatVersionSelectorForSharedBranches,\n\tmessageFormatVersionSelectorForSharedBranches,\n} from \"./shared-tree-core/index.js\";\n\n/**\n * {@link ITreePrivate} extended with ISharedObject.\n * @remarks\n * This is used when integration testing this package with the Fluid runtime as it exposes the APIs the runtime consumes to manipulate the tree.\n */\nexport interface ISharedTree extends ISharedObject, ITreePrivate {}\n\n/**\n * Creates a factory for shared tree kernels with the given options.\n * @remarks\n * Exposes {@link ITreePrivate} to allow access to internals in tests without a cast.\n * Code exposing this beyond this package will need to update to a more public type.\n */\nfunction treeKernelFactory(\n\toptions: SharedTreeOptionsInternal,\n): SharedKernelFactory<SharedTreeKernelView> {\n\tfunction treeFromKernelArgs(args: KernelArgs): SharedTreeKernel {\n\t\tif (args.idCompressor === undefined) {\n\t\t\tthrow new UsageError(\"IdCompressor must be enabled to use SharedTree\");\n\t\t}\n\n\t\tconst { minVersionForCollab, ...otherOptions } = options;\n\n\t\tconst adjustedOptions = {\n\t\t\t...otherOptions,\n\t\t\t// Cases:\n\t\t\t// A. If options specifies minVersionForCollab, it takes precedence over args.minVersionForCollab.\n\t\t\t// This value is set when:\n\t\t\t// - A customer using the declarative SharedTree API specifies the setting at the Shared Tree level.\n\t\t\t//   There is currently no way to set it via the declarative API, but it could be added in the future.\n\t\t\t// - treeKernelFactory is invoked in a fuzz test with a specific minVersionForCollab\n\t\t\t// B. Otherwise, we use args.minVersionForCollab, which is propagated from the ContainerRuntime.\n\t\t\t// C. If neither specifies it, we fall back to a default value default of 2.0 since that is the oldest version that supports SharedTree.\n\t\t\tminVersionForCollab:\n\t\t\t\tminVersionForCollab ?? args.minVersionForCollab ?? FluidClientVersion.v2_0,\n\t\t};\n\n\t\treturn new SharedTreeKernel(\n\t\t\tnew Breakable(\"SharedTree\"),\n\t\t\targs.sharedObject,\n\t\t\targs.serializer,\n\t\t\targs.submitLocalMessage,\n\t\t\targs.lastSequenceNumber,\n\t\t\targs.initialSequenceNumber,\n\t\t\targs.logger,\n\t\t\targs.idCompressor,\n\t\t\tadjustedOptions,\n\t\t);\n\t}\n\n\treturn {\n\t\tcreate: (args: KernelArgs): FactoryOut<SharedTreeKernelView> => {\n\t\t\tconst k = treeFromKernelArgs(args);\n\t\t\treturn { kernel: k, view: k.view };\n\t\t},\n\n\t\tasync loadCore(\n\t\t\targs: KernelArgs,\n\t\t\tstorage: IChannelStorageService,\n\t\t): Promise<FactoryOut<SharedTreeKernelView>> {\n\t\t\tconst k = treeFromKernelArgs(args);\n\t\t\tawait k.loadCore(storage);\n\t\t\treturn { kernel: k, view: k.view };\n\t\t},\n\t};\n}\n\n/**\n * SharedTree is a hierarchical data structure for collaboratively editing strongly typed JSON-like trees\n * of objects, arrays, and other data types.\n * @legacy @beta\n */\nexport const SharedTree = configuredSharedTree({});\n\n/**\n * {@link SharedTree} but allowing a non-default configuration.\n * @remarks\n * This is useful for debugging and testing.\n * For example it can be used to opt into extra validation or see if opting out of some optimizations fixes an issue.\n *\n * With great care, and knowledge of the support and stability of the options exposed here,\n * this can also be used to opt into some features early or for performance tuning.\n *\n * @example\n * ```typescript\n * import {\n * \tconfiguredSharedTreeBeta,\n * \tForestTypeReference,\n * } from \"fluid-framework/beta\";\n * const SharedTree = configuredSharedTree({\n * \tforest: ForestTypeReference,\n * });\n * ```\n * @privateRemarks\n * The Legacy `ISharedObjectKind<ITree>` type is omitted here for simplicity.\n * @beta\n */\nexport function configuredSharedTreeBeta(\n\toptions: SharedTreeOptionsBeta,\n): SharedObjectKind<ITree> {\n\treturn configuredSharedTree(options);\n}\n\n/**\n * {@link configuredSharedTreeBeta} including the legacy `ISharedObjectKind` type.\n * @privateRemarks\n * This is given a different export name (with legacy appended) to avoid the need to do the special reexport with different types from the fluid-framework package.\n * @legacy @beta\n */\nexport function configuredSharedTreeBetaLegacy(\n\toptions: SharedTreeOptionsBeta,\n): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {\n\treturn configuredSharedTree(options);\n}\n\n/**\n * {@link configuredSharedTreeBeta} but including the alpha {@link SharedTreeOptions}.\n * @alpha\n */\nexport function configuredSharedTreeAlpha(\n\toptions: SharedTreeOptions,\n): SharedObjectKind<ITree> {\n\treturn configuredSharedTree(options);\n}\n\n/**\n * {@link configuredSharedTreeBetaLegacy} but including `@alpha` options.\n *\n * @example\n * ```typescript\n * import {\n * \tTreeCompressionStrategy,\n * \tconfiguredSharedTree,\n * \tFormatValidatorBasic,\n * \tForestTypeReference,\n * } from \"@fluidframework/tree/internal\";\n * const SharedTree = configuredSharedTree({\n * \tforest: ForestTypeReference,\n * \tjsonValidator: FormatValidatorBasic,\n * \ttreeEncodeType: TreeCompressionStrategy.Uncompressed,\n * });\n * ```\n * @privateRemarks\n * This should be legacy, but has to be internal due to no alpha+legacy being setup yet.\n *\n * This should be renamed to `configuredSharedTreeAlpha` to avoid colliding with the eventual public version which will have less options.\n * @internal\n */\nexport function configuredSharedTree(\n\toptions: SharedTreeOptions,\n): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {\n\tconst internalOptions = resolveOptions(options);\n\treturn configuredSharedTreeInternal(internalOptions);\n}\n\nexport function configuredSharedTreeInternal(\n\toptions: SharedTreeOptionsInternal,\n): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {\n\tconst sharedObjectOptions: SharedObjectOptions<ITree> = {\n\t\ttype: SharedTreeFactoryType,\n\t\tattributes: SharedTreeAttributes,\n\t\ttelemetryContextPrefix: \"fluid_sharedTree_\",\n\t\tfactory: treeKernelFactory(options),\n\t};\n\n\treturn makeSharedObjectKind<ITree>(sharedObjectOptions);\n}\n\nexport function resolveOptions(options: SharedTreeOptions): SharedTreeOptionsInternal {\n\tconst internal: SharedTreeOptionsInternal = {\n\t\t...resolveSharedBranchesOptions(options.enableSharedBranches),\n\t};\n\tfor (const optionName of Object.keys(options)) {\n\t\tcopyProperty(options, optionName, internal);\n\t}\n\treturn internal;\n}\n\nfunction resolveSharedBranchesOptions(\n\tenableSharedBranches: boolean | undefined,\n): SharedTreeOptionsInternal {\n\treturn enableSharedBranches === true ? sharedBranchesOptions : {};\n}\nconst sharedBranchesOptions: SharedTreeOptionsInternal = {\n\tmessageFormatSelector: messageFormatVersionSelectorForSharedBranches,\n\teditManagerFormatSelector: editManagerFormatVersionSelectorForSharedBranches,\n};\n"]}
+{"version":3,"file":"treeFactory.js","sourceRoot":"","sources":["../src/treeFactory.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 { IChannelStorageService } from \"@fluidframework/datastore-definitions/internal\";\nimport type { SharedObjectKind } from \"@fluidframework/shared-object-base\";\nimport {\n\ttype ISharedObject,\n\ttype ISharedObjectKind,\n\tmakeSharedObjectKind,\n\ttype KernelArgs,\n\ttype SharedKernelFactory,\n\ttype SharedObjectOptions,\n\ttype FactoryOut,\n} from \"@fluidframework/shared-object-base/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport {\n\tSharedTreeKernel,\n\ttype ITreePrivate,\n\ttype SharedTreeOptions,\n\ttype SharedTreeOptionsBeta,\n\ttype SharedTreeOptionsInternal,\n\ttype SharedTreeKernelView,\n} from \"./shared-tree/index.js\";\nimport { SharedTreeFactoryType, SharedTreeAttributes } from \"./sharedTreeAttributes.js\";\nimport type { ITree } from \"./simple-tree/index.js\";\nimport { Breakable, copyProperty } from \"./util/index.js\";\nimport { FluidClientVersion } from \"./codec/index.js\";\nimport {\n\teditManagerFormatVersionSelectorForDetachedRootEditing,\n\teditManagerFormatVersionSelectorForSharedBranches,\n\tmessageFormatVersionSelectorForDetachedRootEditing,\n\tmessageFormatVersionSelectorForSharedBranches,\n} from \"./shared-tree-core/index.js\";\n\n/**\n * {@link ITreePrivate} extended with ISharedObject.\n * @remarks\n * This is used when integration testing this package with the Fluid runtime as it exposes the APIs the runtime consumes to manipulate the tree.\n */\nexport interface ISharedTree extends ISharedObject, ITreePrivate {}\n\n/**\n * Creates a factory for shared tree kernels with the given options.\n * @remarks\n * Exposes {@link ITreePrivate} to allow access to internals in tests without a cast.\n * Code exposing this beyond this package will need to update to a more public type.\n */\nfunction treeKernelFactory(\n\toptions: SharedTreeOptionsInternal,\n): SharedKernelFactory<SharedTreeKernelView> {\n\tfunction treeFromKernelArgs(args: KernelArgs): SharedTreeKernel {\n\t\tif (args.idCompressor === undefined) {\n\t\t\tthrow new UsageError(\"IdCompressor must be enabled to use SharedTree\");\n\t\t}\n\n\t\tconst { minVersionForCollab, ...otherOptions } = options;\n\n\t\tconst adjustedOptions = {\n\t\t\t...otherOptions,\n\t\t\t// Cases:\n\t\t\t// A. If options specifies minVersionForCollab, it takes precedence over args.minVersionForCollab.\n\t\t\t// This value is set when:\n\t\t\t// - A customer using the declarative SharedTree API specifies the setting at the Shared Tree level.\n\t\t\t//   There is currently no way to set it via the declarative API, but it could be added in the future.\n\t\t\t// - treeKernelFactory is invoked in a fuzz test with a specific minVersionForCollab\n\t\t\t// B. Otherwise, we use args.minVersionForCollab, which is propagated from the ContainerRuntime.\n\t\t\t// C. If neither specifies it, we fall back to a default value default of 2.0 since that is the oldest version that supports SharedTree.\n\t\t\tminVersionForCollab:\n\t\t\t\tminVersionForCollab ?? args.minVersionForCollab ?? FluidClientVersion.v2_0,\n\t\t};\n\n\t\treturn new SharedTreeKernel(\n\t\t\tnew Breakable(\"SharedTree\"),\n\t\t\targs.sharedObject,\n\t\t\targs.serializer,\n\t\t\targs.submitLocalMessage,\n\t\t\targs.lastSequenceNumber,\n\t\t\targs.initialSequenceNumber,\n\t\t\targs.logger,\n\t\t\targs.idCompressor,\n\t\t\tadjustedOptions,\n\t\t);\n\t}\n\n\treturn {\n\t\tcreate: (args: KernelArgs): FactoryOut<SharedTreeKernelView> => {\n\t\t\tconst k = treeFromKernelArgs(args);\n\t\t\treturn { kernel: k, view: k.view };\n\t\t},\n\n\t\tasync loadCore(\n\t\t\targs: KernelArgs,\n\t\t\tstorage: IChannelStorageService,\n\t\t): Promise<FactoryOut<SharedTreeKernelView>> {\n\t\t\tconst k = treeFromKernelArgs(args);\n\t\t\tawait k.loadCore(storage);\n\t\t\treturn { kernel: k, view: k.view };\n\t\t},\n\t};\n}\n\n/**\n * SharedTree is a hierarchical data structure for collaboratively editing strongly typed JSON-like trees\n * of objects, arrays, and other data types.\n * @legacy @beta\n */\nexport const SharedTree = configuredSharedTree({});\n\n/**\n * {@link SharedTree} but allowing a non-default configuration.\n * @remarks\n * This is useful for debugging and testing.\n * For example it can be used to opt into extra validation or see if opting out of some optimizations fixes an issue.\n *\n * With great care, and knowledge of the support and stability of the options exposed here,\n * this can also be used to opt into some features early or for performance tuning.\n *\n * @example\n * ```typescript\n * import {\n * \tconfiguredSharedTreeBeta,\n * \tForestTypeReference,\n * } from \"fluid-framework/beta\";\n * const SharedTree = configuredSharedTree({\n * \tforest: ForestTypeReference,\n * });\n * ```\n * @privateRemarks\n * The Legacy `ISharedObjectKind<ITree>` type is omitted here for simplicity.\n * @beta\n */\nexport function configuredSharedTreeBeta(\n\toptions: SharedTreeOptionsBeta,\n): SharedObjectKind<ITree> {\n\treturn configuredSharedTree(options);\n}\n\n/**\n * {@link configuredSharedTreeBeta} including the legacy `ISharedObjectKind` type.\n * @privateRemarks\n * This is given a different export name (with legacy appended) to avoid the need to do the special reexport with different types from the fluid-framework package.\n * @legacy @beta\n */\nexport function configuredSharedTreeBetaLegacy(\n\toptions: SharedTreeOptionsBeta,\n): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {\n\treturn configuredSharedTree(options);\n}\n\n/**\n * {@link configuredSharedTreeBeta} but including the alpha {@link SharedTreeOptions}.\n * @alpha\n */\nexport function configuredSharedTreeAlpha(\n\toptions: SharedTreeOptions,\n): SharedObjectKind<ITree> {\n\treturn configuredSharedTree(options);\n}\n\n/**\n * {@link configuredSharedTreeBetaLegacy} but including `@alpha` options.\n *\n * @example\n * ```typescript\n * import {\n * \tTreeCompressionStrategy,\n * \tconfiguredSharedTree,\n * \tFormatValidatorBasic,\n * \tForestTypeReference,\n * } from \"@fluidframework/tree/internal\";\n * const SharedTree = configuredSharedTree({\n * \tforest: ForestTypeReference,\n * \tjsonValidator: FormatValidatorBasic,\n * \ttreeEncodeType: TreeCompressionStrategy.Uncompressed,\n * });\n * ```\n * @privateRemarks\n * This should be legacy, but has to be internal due to no alpha+legacy being setup yet.\n *\n * This should be renamed to `configuredSharedTreeAlpha` to avoid colliding with the eventual public version which will have less options.\n * @internal\n */\nexport function configuredSharedTree(\n\toptions: SharedTreeOptions,\n): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {\n\tconst internalOptions = resolveOptions(options);\n\treturn configuredSharedTreeInternal(internalOptions);\n}\n\nexport function configuredSharedTreeInternal(\n\toptions: SharedTreeOptionsInternal,\n): ISharedObjectKind<ITree> & SharedObjectKind<ITree> {\n\tconst sharedObjectOptions: SharedObjectOptions<ITree> = {\n\t\ttype: SharedTreeFactoryType,\n\t\tattributes: SharedTreeAttributes,\n\t\ttelemetryContextPrefix: \"fluid_sharedTree_\",\n\t\tfactory: treeKernelFactory(options),\n\t};\n\n\treturn makeSharedObjectKind<ITree>(sharedObjectOptions);\n}\n\nexport function resolveOptions(options: SharedTreeOptions): SharedTreeOptionsInternal {\n\tconst internal: SharedTreeOptionsInternal = {\n\t\t...resolveFormatOptions(options),\n\t};\n\tfor (const optionName of Object.keys(options)) {\n\t\tcopyProperty(options, optionName, internal);\n\t}\n\treturn internal;\n}\n\nfunction resolveFormatOptions(options: SharedTreeOptions): SharedTreeOptionsInternal {\n\tif (options.enableSharedBranches === true && options.enableDetachedRootEditing === true) {\n\t\tthrow new UsageError(\"enableDetachRootEditing cannot be used with enableSharedBranches.\");\n\t}\n\tif (options.enableSharedBranches === true) {\n\t\treturn sharedBranchesOptions;\n\t}\n\tif (options.enableDetachedRootEditing === true) {\n\t\treturn detachRootEditingOptions;\n\t}\n\treturn {};\n}\n\nconst sharedBranchesOptions: SharedTreeOptionsInternal = {\n\tmessageFormatSelector: messageFormatVersionSelectorForSharedBranches,\n\teditManagerFormatSelector: editManagerFormatVersionSelectorForSharedBranches,\n};\nconst detachRootEditingOptions: SharedTreeOptionsInternal = {\n\tmessageFormatSelector: messageFormatVersionSelectorForDetachedRootEditing,\n\teditManagerFormatSelector: editManagerFormatVersionSelectorForDetachedRootEditing,\n\tcanMakeDetachedRootEdits: true,\n};\n"]}

package/lib/util/bTreeUtils.d.ts

@@ -2,9 +2,17 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { BTree } from "@tylerbu/sorted-btree-es6";
+import { BTree, type DefaultComparable } from "@tylerbu/sorted-btree-es6";
 import { type Brand } from "./brand.js";
-export type TupleBTree<K, V> = Brand<BTree<K, V>, "TupleBTree">;
-export declare function newTupleBTree<K extends readonly unknown[], V>(entries?: [K, V][]): TupleBTree<K, V>;
-export declare function mergeTupleBTrees<K extends readonly unknown[], V>(tree1: TupleBTree<K, V> | undefined, tree2: TupleBTree<K, V> | undefined, preferLeft?: boolean): TupleBTree<K, V>;
+/**
+ * A BTree which uses tuples (arrays) as the key.
+ * @remarks
+ * All keys must be the same length.
+ */
+export type TupleBTree<K extends readonly DefaultComparable[], V> = Brand<BTree<K, V>, "TupleBTree">;
+/**
+ * Create a new {@link TupleBTree}.
+ */
+export declare function newTupleBTree<const K extends readonly DefaultComparable[], V>(entries?: [K, V][]): TupleBTree<K, V>;
+export declare function mergeTupleBTrees<K extends readonly DefaultComparable[], V>(tree1: TupleBTree<K, V> | undefined, tree2: TupleBTree<K, V> | undefined, preferLeft?: boolean): TupleBTree<K, V>;
 //# sourceMappingURL=bTreeUtils.d.ts.map

package/lib/util/bTreeUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bTreeUtils.d.ts","sourceRoot":"","sources":["../../src/util/bTreeUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAElD,OAAO,EAAS,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,MAAM,UAAU,CAAC,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;AAEhE,wBAAgB,aAAa,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,EAAE,CAAC,EAC5D,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAChB,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAElB;AA0BD,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,EAAE,CAAC,EAC/D,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS,EACnC,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS,EACnC,UAAU,UAAO,GACf,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAelB"}
+{"version":3,"file":"bTreeUtils.d.ts","sourceRoot":"","sources":["../../src/util/bTreeUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAAqB,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE7F,OAAO,EAAS,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAG/C;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,SAAS,iBAAiB,EAAE,EAAE,CAAC,IAAI,KAAK,CACxE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EACX,YAAY,CACZ,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,iBAAiB,EAAE,EAAE,CAAC,EAC5E,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAChB,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAElB;AAyBD,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,SAAS,iBAAiB,EAAE,EAAE,CAAC,EACzE,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS,EACnC,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS,EACnC,UAAU,UAAO,GACf,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAelB"}

package/lib/util/bTreeUtils.js

@@ -2,38 +2,34 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { BTree } from "@tylerbu/sorted-btree-es6";
+import { BTree, defaultComparator } from "@tylerbu/sorted-btree-es6";
 import { brand } from "./brand.js";
+import { debugAssert } from "@fluidframework/core-utils/internal";
+/**
+ * Create a new {@link TupleBTree}.
+ */
 export function newTupleBTree(entries) {
     return brand(new BTree(entries, compareTuples));
 }
-// This assumes that the arrays are the same length.
+/**
+ * Compares two tuples (arrays) element by element.
+ * @param arrayA - The first tuple to compare.
+ * @param arrayB - The second tuple to compare.
+ * @returns A negative number if arrayA \< arrayB, a positive number if arrayA \> arrayB, or 0 if they are equal.
+ */
 function compareTuples(arrayA, arrayB) {
+    debugAssert(() => arrayA.length === arrayB.length || "compareTuples requires arrays of the same length");
     for (let i = 0; i < arrayA.length; i++) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const a = arrayA[i];
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const b = arrayB[i];
-        // Less-than and greater-than always return false if either value is undefined,
-        // so we handle undefined separately, treating it as less than all other values.
-        if (a === undefined && b !== undefined) {
-            return -1;
-        }
-        else if (b === undefined && a !== undefined) {
-            return 1;
-        }
-        else if (a < b) {
-            return -1;
-        }
-        else if (a > b) {
-            return 1;
+        const result = defaultComparator(arrayA[i], arrayB[i]);
+        if (result !== 0) {
+            return result;
         }
     }
     return 0;
 }
 export function mergeTupleBTrees(tree1, tree2, preferLeft = true) {
     if (tree1 === undefined) {
-        return tree2 !== undefined ? brand(tree2.clone()) : newTupleBTree();
+        return tree2 === undefined ? newTupleBTree() : brand(tree2.clone());
     }
     const result = brand(tree1.clone());
     if (tree2 === undefined) {

package/lib/util/bTreeUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"bTreeUtils.js","sourceRoot":"","sources":["../../src/util/bTreeUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAElD,OAAO,EAAE,KAAK,EAAc,MAAM,YAAY,CAAC;AAI/C,MAAM,UAAU,aAAa,CAC5B,OAAkB;IAElB,OAAO,KAAK,CAAC,IAAI,KAAK,CAAO,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,oDAAoD;AACpD,SAAS,aAAa,CAAC,MAA0B,EAAE,MAA0B;IAC5E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,8DAA8D;QAC9D,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAQ,CAAC;QAC3B,8DAA8D;QAC9D,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAQ,CAAC;QAE3B,+EAA+E;QAC/E,gFAAgF;QAChF,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YACxC,OAAO,CAAC,CAAC,CAAC;QACX,CAAC;aAAM,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YAC/C,OAAO,CAAC,CAAC;QACV,CAAC;aAAM,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,OAAO,CAAC,CAAC,CAAC;QACX,CAAC;aAAM,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,OAAO,CAAC,CAAC;QACV,CAAC;IACF,CAAC;IAED,OAAO,CAAC,CAAC;AACV,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC/B,KAAmC,EACnC,KAAmC,EACnC,UAAU,GAAG,IAAI;IAEjB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,EAAQ,CAAC;IAC3E,CAAC;IAED,MAAM,MAAM,GAAqB,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;IACtD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC;IACf,CAAC;IAED,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { BTree } from \"@tylerbu/sorted-btree-es6\";\n\nimport { brand, type Brand } from \"./brand.js\";\n\nexport type TupleBTree<K, V> = Brand<BTree<K, V>, \"TupleBTree\">;\n\nexport function newTupleBTree<K extends readonly unknown[], V>(\n\tentries?: [K, V][],\n): TupleBTree<K, V> {\n\treturn brand(new BTree<K, V>(entries, compareTuples));\n}\n\n// This assumes that the arrays are the same length.\nfunction compareTuples(arrayA: readonly unknown[], arrayB: readonly unknown[]): number {\n\tfor (let i = 0; i < arrayA.length; i++) {\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\tconst a = arrayA[i] as any;\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\tconst b = arrayB[i] as any;\n\n\t\t// Less-than and greater-than always return false if either value is undefined,\n\t\t// so we handle undefined separately, treating it as less than all other values.\n\t\tif (a === undefined && b !== undefined) {\n\t\t\treturn -1;\n\t\t} else if (b === undefined && a !== undefined) {\n\t\t\treturn 1;\n\t\t} else if (a < b) {\n\t\t\treturn -1;\n\t\t} else if (a > b) {\n\t\t\treturn 1;\n\t\t}\n\t}\n\n\treturn 0;\n}\n\nexport function mergeTupleBTrees<K extends readonly unknown[], V>(\n\ttree1: TupleBTree<K, V> | undefined,\n\ttree2: TupleBTree<K, V> | undefined,\n\tpreferLeft = true,\n): TupleBTree<K, V> {\n\tif (tree1 === undefined) {\n\t\treturn tree2 !== undefined ? brand(tree2.clone()) : newTupleBTree<K, V>();\n\t}\n\n\tconst result: TupleBTree<K, V> = brand(tree1.clone());\n\tif (tree2 === undefined) {\n\t\treturn result;\n\t}\n\n\tfor (const [key, value] of tree2.entries()) {\n\t\tresult.set(key, value, !preferLeft);\n\t}\n\n\treturn result;\n}\n"]}
+{"version":3,"file":"bTreeUtils.js","sourceRoot":"","sources":["../../src/util/bTreeUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAA0B,MAAM,2BAA2B,CAAC;AAE7F,OAAO,EAAE,KAAK,EAAc,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAYlE;;GAEG;AACH,MAAM,UAAU,aAAa,CAC5B,OAAkB;IAElB,OAAO,KAAK,CAAC,IAAI,KAAK,CAAO,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CACrB,MAAoC,EACpC,MAAoC;IAEpC,WAAW,CACV,GAAG,EAAE,CACJ,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,IAAI,kDAAkD,CACtF,CAAC;IACF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,IAAI,MAAM,KAAK,CAAC,EAAE,CAAC;YAClB,OAAO,MAAM,CAAC;QACf,CAAC;IACF,CAAC;IACD,OAAO,CAAC,CAAC;AACV,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC/B,KAAmC,EACnC,KAAmC,EACnC,UAAU,GAAG,IAAI;IAEjB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,EAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,MAAM,GAAqB,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;IACtD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC;IACf,CAAC;IAED,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { BTree, defaultComparator, type DefaultComparable } from \"@tylerbu/sorted-btree-es6\";\n\nimport { brand, type Brand } from \"./brand.js\";\nimport { debugAssert } from \"@fluidframework/core-utils/internal\";\n\n/**\n * A BTree which uses tuples (arrays) as the key.\n * @remarks\n * All keys must be the same length.\n */\nexport type TupleBTree<K extends readonly DefaultComparable[], V> = Brand<\n\tBTree<K, V>,\n\t\"TupleBTree\"\n>;\n\n/**\n * Create a new {@link TupleBTree}.\n */\nexport function newTupleBTree<const K extends readonly DefaultComparable[], V>(\n\tentries?: [K, V][],\n): TupleBTree<K, V> {\n\treturn brand(new BTree<K, V>(entries, compareTuples));\n}\n\n/**\n * Compares two tuples (arrays) element by element.\n * @param arrayA - The first tuple to compare.\n * @param arrayB - The second tuple to compare.\n * @returns A negative number if arrayA \\< arrayB, a positive number if arrayA \\> arrayB, or 0 if they are equal.\n */\nfunction compareTuples(\n\tarrayA: readonly DefaultComparable[],\n\tarrayB: readonly DefaultComparable[],\n): number {\n\tdebugAssert(\n\t\t() =>\n\t\t\tarrayA.length === arrayB.length || \"compareTuples requires arrays of the same length\",\n\t);\n\tfor (let i = 0; i < arrayA.length; i++) {\n\t\tconst result = defaultComparator(arrayA[i], arrayB[i]);\n\t\tif (result !== 0) {\n\t\t\treturn result;\n\t\t}\n\t}\n\treturn 0;\n}\n\nexport function mergeTupleBTrees<K extends readonly DefaultComparable[], V>(\n\ttree1: TupleBTree<K, V> | undefined,\n\ttree2: TupleBTree<K, V> | undefined,\n\tpreferLeft = true,\n): TupleBTree<K, V> {\n\tif (tree1 === undefined) {\n\t\treturn tree2 === undefined ? newTupleBTree<K, V>() : brand(tree2.clone());\n\t}\n\n\tconst result: TupleBTree<K, V> = brand(tree1.clone());\n\tif (tree2 === undefined) {\n\t\treturn result;\n\t}\n\n\tfor (const [key, value] of tree2.entries()) {\n\t\tresult.set(key, value, !preferLeft);\n\t}\n\n\treturn result;\n}\n"]}

package/lib/util/breakable.js

@@ -169,15 +169,13 @@ export function breakingClass(target, context) {
             if (!doNotWrap.has(key)) {
                 doNotWrap.add(key);
                 const descriptor = Reflect.getOwnPropertyDescriptor(prototype, key);
-                if (descriptor !== undefined) {
-                    // Method
-                    if (typeof descriptor.value === "function") {
-                        if (!isBreaker(descriptor.value)) {
-                            // This does not affect the original class, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor
-                            descriptor.value = breakingMethod(descriptor.value);
-                            Object.defineProperty(DecoratedBreakable.prototype, key, descriptor);
-                        }
-                    }
+                // Method
+                if (descriptor !== undefined &&
+                    typeof descriptor.value === "function" &&
+                    !isBreaker(descriptor.value)) {
+                    // This does not affect the original class, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor
+                    descriptor.value = breakingMethod(descriptor.value);
+                    Object.defineProperty(DecoratedBreakable.prototype, key, descriptor);
                 }
             }
         }

package/lib/util/breakable.js.map

@@ -1 +1 @@
-{"version":3,"file":"breakable.js","sourceRoot":"","sources":["../../src/util/breakable.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 } from \"@fluidframework/core-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\n/**\n * An object which can enter a \"broken\" state where trying to use it is a UsageError.\n * @remarks\n * Use {@link WithBreakable} to apply this to another object.\n * @sealed\n */\nexport class Breakable {\n\tprivate brokenBy?: Error;\n\n\tpublic constructor(\n\t\t/**\n\t\t * A name for a given breakable scope.\n\t\t * @remarks\n\t\t * This is useful for documenting the semantics of a given Breakable and when inspecting things in the debugger, but is currently otherwise unused.\n\t\t */\n\t\tprivate readonly name: string,\n\t) {}\n\n\t/**\n\t * Throws if this object is in the broken state.\n\t * @remarks\n\t * Can use {@link throwIfBroken} to apply this to a method.\n\t */\n\tpublic use(): void {\n\t\tif (this.brokenBy !== undefined) {\n\t\t\tconst error = new UsageError(\n\t\t\t\t`Invalid use of ${this.name} after it was put into an invalid state by another error.\\nOriginal Error:\\n${this.brokenBy}`,\n\t\t\t);\n\n\t\t\t// This \"cause\" field is added in ES2022, but using if even without that built in support, it is still helpful.\n\t\t\t// See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause\n\t\t\t// TODO: remove this cast when targeting ES2022 lib or later.\n\t\t\t(error as { cause?: unknown }).cause =\n\t\t\t\t(this.brokenBy as { cause?: unknown }).cause ?? this.brokenBy;\n\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\t/**\n\t * Puts this object into the broken state, and throws an error.\n\t *\n\t * @throws If already broken by a different error, throws a UsageError, otherwise throws `brokenBy`.\n\t */\n\tpublic break(brokenBy: Error): never {\n\t\t// If already broken by this error, let it bubble up without rethrowing a modified version.\n\t\t// This prevents internal errors like asserts getting rethrown as different errors when wrapped with multiple call to `{@link Breakable.run}` or `{@link breakingMethod}`.\n\t\tif (this.brokenBy !== brokenBy) {\n\t\t\tthis.use();\n\t\t\tthis.brokenBy = brokenBy;\n\t\t}\n\t\tthrow brokenBy;\n\t}\n\n\t/**\n\t * {@link Breakable.break}, except tolerates `unknown` to be more easily used by catch blocks.\n\t * @privateRemarks\n\t * If there is a use-case, this should be made public.\n\t */\n\tprivate rethrowCaught(brokenBy: unknown): never {\n\t\tif (brokenBy instanceof Error) {\n\t\t\tthis.break(brokenBy);\n\t\t}\n\t\tthis.break(\n\t\t\tnew Error(`Non-error thrown breaking ${this.name}. Thrown value: \"${brokenBy}\"`),\n\t\t);\n\t}\n\n\t/**\n\t * Runs code which should break the object if it throws.\n\t * @remarks\n\t * Like {@link Breakable.use}, this also throws if already broken.\n\t * Any exceptions this catches are re-thrown.\n\t * Can use {@link breakingMethod} to apply this to a method.\n\t */\n\tpublic run<TResult>(breaker: () => TResult): TResult {\n\t\tthis.use();\n\t\ttry {\n\t\t\treturn breaker();\n\t\t} catch (error: unknown) {\n\t\t\tthis.rethrowCaught(error);\n\t\t}\n\t}\n\n\t/**\n\t * Clears the existing broken state.\n\t * @remarks\n\t * This is rarely safe to to: it is only ok when all objects using this breaker are known to not have been left in an invalid state.\n\t * This is pretty much only safe in tests which just were checking a specific error was thrown, and which know that error closepath is actually exception safe.\n\t */\n\tpublic clearError(): void {\n\t\tassert(this.brokenBy !== undefined, 0x9b6 /* No error to clear */);\n\t\tthis.brokenBy = undefined;\n\t}\n}\n\n/**\n * Marks an object as being able to be in a broken state (unknown/unspecified/broken state due to unhandled exception).\n * @remarks\n * See decorators {@link breakingMethod} and {@link throwIfBroken} for ease of use.\n */\nexport interface WithBreakable {\n\t/**\n\t * The breaker for this object.\n\t * @remarks\n\t * If this `breaker` is in the broken state, the `WithBreakable` should be considered in a broken state.\n\t */\n\treadonly breaker: Breakable;\n}\n\n/**\n * Decorator for methods which should break the object when they throw.\n * @remarks\n * This also throws if already broken like {@link throwIfBroken}.\n * See {@link Breakable.run} for details.\n *\n * This should be used on methods which modify data that could result in an unsupported/broken state if an exception is thrown while modifying.\n * It is ok for breakingMethods to call each-other.\n * @privateRemarks\n * Explicitly capturing the full `Target` type is necessary to make this work with generic methods with unknown numbers of type parameters.\n */\nexport function breakingMethod<\n\tTarget extends ((...args: any[]) => unknown) & ((this: This, ...args: Args) => Return),\n\tThis extends WithBreakable,\n\tArgs extends never[],\n\tReturn,\n>(target: Target, context?: ClassMethodDecoratorContext<This, Target>): Target {\n\tfunction replacementMethod(this: This, ...args: Args): Return {\n\t\tif (this.breaker === undefined) {\n\t\t\t// This case is necessary for when wrapping methods which are invoked inside the constructor of the base class before `breaker` is set.\n\t\t\t// Since the constructor throwing does not return an object, failing to put it into a broken state is not too bad.\n\t\t\t// However when more than just the constructed object should be broken, this can result in missing a break.\n\t\t\treturn target.call(this, ...args);\n\t\t}\n\t\treturn this.breaker.run(() => {\n\t\t\treturn target.call(this, ...args);\n\t\t});\n\t}\n\tmarkBreaker(replacementMethod);\n\tnameFunctionFrom(replacementMethod, target);\n\treturn replacementMethod as Target;\n}\n\n/**\n * Decorator for methods which should throw if the object is in a broken state.\n * @remarks\n * This should be used on methods which read data that could be invalid when the object is broken.\n * @privateRemarks\n * Explicitly capturing the full `Target` type is necessary to make this work with generic methods with unknown numbers of type parameters.\n */\nexport function throwIfBroken<\n\tTarget extends ((...args: any[]) => unknown) & ((this: This, ...args: Args) => Return),\n\tThis extends WithBreakable,\n\tArgs extends never[],\n\tReturn,\n>(target: Target, context: ClassMethodDecoratorContext<This, Target>): Target {\n\tfunction replacementMethod(this: This, ...args: Args): Return {\n\t\tthis.breaker.use();\n\t\treturn target.call(this, ...args);\n\t}\n\tmarkBreaker(replacementMethod);\n\tnameFunctionFrom(replacementMethod, target);\n\treturn replacementMethod as Target;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\ntype PossiblyNamedFunction = Function & { displayName?: undefined | string };\n\n// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\nfunction nameFunctionFrom(toName: Function, nameFrom: Function): void {\n\t(toName as PossiblyNamedFunction).displayName =\n\t\t(nameFrom as PossiblyNamedFunction).displayName ?? nameFrom.name;\n}\n\nconst isBreakerSymbol: unique symbol = Symbol(\"isBreaker\");\n\n// Accepting any function like value is desired and safe here as this does not call the provided function.\n// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\nfunction markBreaker(f: Function): void {\n\t(f as unknown as Record<typeof isBreakerSymbol, true>)[isBreakerSymbol] = true;\n}\n\n// Accepting any function like value is desired and safe here as this does not call the provided function.\n// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\nfunction isBreaker(f: Function): boolean {\n\treturn isBreakerSymbol in (f as unknown as Record<typeof isBreakerSymbol, true>);\n}\n\n/**\n * Decorator for classes which should break when their methods throw.\n * @remarks\n * Applies {@link breakingMethod} to all methods declared directly by class or its base classes.\n * Does not include those on derived classes.\n * Does not include getters or setters, or value properties.\n * Methods already marked as {@link breakingMethod} or {@link throwIfBroken} are unaffected.\n */\nexport function breakingClass<Target extends abstract new (...args: any[]) => WithBreakable>(\n\ttarget: Target,\n\tcontext: ClassDecoratorContext<Target>,\n): Target {\n\t// This could extend target, but doing so adds an extra step in the prototype chain and makes the instances just show up as \"DecoratedBreakable\" in the debugger.\n\tconst DecoratedBreakable = target;\n\n\t// Keep track of what keys we have seen (and already wrapped if needed).\n\t// Used to avoid rewrapping already wrapped properties.\n\t// Preloaded with \"constructor\" to avoid wrapping the constructor as there is no need to set the broken flag when the constructor throws and does not return an object.\n\t// Avoiding wrapping the constructor also avoids messing up the displayed name in the debugger.\n\tconst doNotWrap: Set<string | symbol> = new Set([\"constructor\"]);\n\n\tlet prototype: object | null = target.prototype;\n\twhile (prototype !== null) {\n\t\tfor (const key of Reflect.ownKeys(prototype)) {\n\t\t\tif (!doNotWrap.has(key)) {\n\t\t\t\tdoNotWrap.add(key);\n\t\t\t\tconst descriptor = Reflect.getOwnPropertyDescriptor(prototype, key);\n\t\t\t\tif (descriptor !== undefined) {\n\t\t\t\t\t// Method\n\t\t\t\t\tif (typeof descriptor.value === \"function\") {\n\t\t\t\t\t\tif (!isBreaker(descriptor.value)) {\n\t\t\t\t\t\t\t// This does not affect the original class, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor\n\t\t\t\t\t\t\tdescriptor.value = breakingMethod(descriptor.value);\n\t\t\t\t\t\t\tObject.defineProperty(DecoratedBreakable.prototype, key, descriptor);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tprototype = Reflect.getPrototypeOf(prototype);\n\t}\n\n\treturn DecoratedBreakable;\n}\n"]}
+{"version":3,"file":"breakable.js","sourceRoot":"","sources":["../../src/util/breakable.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 } from \"@fluidframework/core-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\n/**\n * An object which can enter a \"broken\" state where trying to use it is a UsageError.\n * @remarks\n * Use {@link WithBreakable} to apply this to another object.\n * @sealed\n */\nexport class Breakable {\n\tprivate brokenBy?: Error;\n\n\tpublic constructor(\n\t\t/**\n\t\t * A name for a given breakable scope.\n\t\t * @remarks\n\t\t * This is useful for documenting the semantics of a given Breakable and when inspecting things in the debugger, but is currently otherwise unused.\n\t\t */\n\t\tprivate readonly name: string,\n\t) {}\n\n\t/**\n\t * Throws if this object is in the broken state.\n\t * @remarks\n\t * Can use {@link throwIfBroken} to apply this to a method.\n\t */\n\tpublic use(): void {\n\t\tif (this.brokenBy !== undefined) {\n\t\t\tconst error = new UsageError(\n\t\t\t\t`Invalid use of ${this.name} after it was put into an invalid state by another error.\\nOriginal Error:\\n${this.brokenBy}`,\n\t\t\t);\n\n\t\t\t// This \"cause\" field is added in ES2022, but using if even without that built in support, it is still helpful.\n\t\t\t// See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause\n\t\t\t// TODO: remove this cast when targeting ES2022 lib or later.\n\t\t\t(error as { cause?: unknown }).cause =\n\t\t\t\t(this.brokenBy as { cause?: unknown }).cause ?? this.brokenBy;\n\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\t/**\n\t * Puts this object into the broken state, and throws an error.\n\t *\n\t * @throws If already broken by a different error, throws a UsageError, otherwise throws `brokenBy`.\n\t */\n\tpublic break(brokenBy: Error): never {\n\t\t// If already broken by this error, let it bubble up without rethrowing a modified version.\n\t\t// This prevents internal errors like asserts getting rethrown as different errors when wrapped with multiple call to `{@link Breakable.run}` or `{@link breakingMethod}`.\n\t\tif (this.brokenBy !== brokenBy) {\n\t\t\tthis.use();\n\t\t\tthis.brokenBy = brokenBy;\n\t\t}\n\t\tthrow brokenBy;\n\t}\n\n\t/**\n\t * {@link Breakable.break}, except tolerates `unknown` to be more easily used by catch blocks.\n\t * @privateRemarks\n\t * If there is a use-case, this should be made public.\n\t */\n\tprivate rethrowCaught(brokenBy: unknown): never {\n\t\tif (brokenBy instanceof Error) {\n\t\t\tthis.break(brokenBy);\n\t\t}\n\t\tthis.break(\n\t\t\tnew Error(`Non-error thrown breaking ${this.name}. Thrown value: \"${brokenBy}\"`),\n\t\t);\n\t}\n\n\t/**\n\t * Runs code which should break the object if it throws.\n\t * @remarks\n\t * Like {@link Breakable.use}, this also throws if already broken.\n\t * Any exceptions this catches are re-thrown.\n\t * Can use {@link breakingMethod} to apply this to a method.\n\t */\n\tpublic run<TResult>(breaker: () => TResult): TResult {\n\t\tthis.use();\n\t\ttry {\n\t\t\treturn breaker();\n\t\t} catch (error: unknown) {\n\t\t\tthis.rethrowCaught(error);\n\t\t}\n\t}\n\n\t/**\n\t * Clears the existing broken state.\n\t * @remarks\n\t * This is rarely safe to to: it is only ok when all objects using this breaker are known to not have been left in an invalid state.\n\t * This is pretty much only safe in tests which just were checking a specific error was thrown, and which know that error closepath is actually exception safe.\n\t */\n\tpublic clearError(): void {\n\t\tassert(this.brokenBy !== undefined, 0x9b6 /* No error to clear */);\n\t\tthis.brokenBy = undefined;\n\t}\n}\n\n/**\n * Marks an object as being able to be in a broken state (unknown/unspecified/broken state due to unhandled exception).\n * @remarks\n * See decorators {@link breakingMethod} and {@link throwIfBroken} for ease of use.\n */\nexport interface WithBreakable {\n\t/**\n\t * The breaker for this object.\n\t * @remarks\n\t * If this `breaker` is in the broken state, the `WithBreakable` should be considered in a broken state.\n\t */\n\treadonly breaker: Breakable;\n}\n\n/**\n * Decorator for methods which should break the object when they throw.\n * @remarks\n * This also throws if already broken like {@link throwIfBroken}.\n * See {@link Breakable.run} for details.\n *\n * This should be used on methods which modify data that could result in an unsupported/broken state if an exception is thrown while modifying.\n * It is ok for breakingMethods to call each-other.\n * @privateRemarks\n * Explicitly capturing the full `Target` type is necessary to make this work with generic methods with unknown numbers of type parameters.\n */\nexport function breakingMethod<\n\tTarget extends ((...args: any[]) => unknown) & ((this: This, ...args: Args) => Return),\n\tThis extends WithBreakable,\n\tArgs extends never[],\n\tReturn,\n>(target: Target, context?: ClassMethodDecoratorContext<This, Target>): Target {\n\tfunction replacementMethod(this: This, ...args: Args): Return {\n\t\tif (this.breaker === undefined) {\n\t\t\t// This case is necessary for when wrapping methods which are invoked inside the constructor of the base class before `breaker` is set.\n\t\t\t// Since the constructor throwing does not return an object, failing to put it into a broken state is not too bad.\n\t\t\t// However when more than just the constructed object should be broken, this can result in missing a break.\n\t\t\treturn target.call(this, ...args);\n\t\t}\n\t\treturn this.breaker.run(() => {\n\t\t\treturn target.call(this, ...args);\n\t\t});\n\t}\n\tmarkBreaker(replacementMethod);\n\tnameFunctionFrom(replacementMethod, target);\n\treturn replacementMethod as Target;\n}\n\n/**\n * Decorator for methods which should throw if the object is in a broken state.\n * @remarks\n * This should be used on methods which read data that could be invalid when the object is broken.\n * @privateRemarks\n * Explicitly capturing the full `Target` type is necessary to make this work with generic methods with unknown numbers of type parameters.\n */\nexport function throwIfBroken<\n\tTarget extends ((...args: any[]) => unknown) & ((this: This, ...args: Args) => Return),\n\tThis extends WithBreakable,\n\tArgs extends never[],\n\tReturn,\n>(target: Target, context: ClassMethodDecoratorContext<This, Target>): Target {\n\tfunction replacementMethod(this: This, ...args: Args): Return {\n\t\tthis.breaker.use();\n\t\treturn target.call(this, ...args);\n\t}\n\tmarkBreaker(replacementMethod);\n\tnameFunctionFrom(replacementMethod, target);\n\treturn replacementMethod as Target;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\ntype PossiblyNamedFunction = Function & { displayName?: undefined | string };\n\n// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\nfunction nameFunctionFrom(toName: Function, nameFrom: Function): void {\n\t(toName as PossiblyNamedFunction).displayName =\n\t\t(nameFrom as PossiblyNamedFunction).displayName ?? nameFrom.name;\n}\n\nconst isBreakerSymbol: unique symbol = Symbol(\"isBreaker\");\n\n// Accepting any function like value is desired and safe here as this does not call the provided function.\n// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\nfunction markBreaker(f: Function): void {\n\t(f as unknown as Record<typeof isBreakerSymbol, true>)[isBreakerSymbol] = true;\n}\n\n// Accepting any function like value is desired and safe here as this does not call the provided function.\n// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\nfunction isBreaker(f: Function): boolean {\n\treturn isBreakerSymbol in (f as unknown as Record<typeof isBreakerSymbol, true>);\n}\n\n/**\n * Decorator for classes which should break when their methods throw.\n * @remarks\n * Applies {@link breakingMethod} to all methods declared directly by class or its base classes.\n * Does not include those on derived classes.\n * Does not include getters or setters, or value properties.\n * Methods already marked as {@link breakingMethod} or {@link throwIfBroken} are unaffected.\n */\nexport function breakingClass<Target extends abstract new (...args: any[]) => WithBreakable>(\n\ttarget: Target,\n\tcontext: ClassDecoratorContext<Target>,\n): Target {\n\t// This could extend target, but doing so adds an extra step in the prototype chain and makes the instances just show up as \"DecoratedBreakable\" in the debugger.\n\tconst DecoratedBreakable = target;\n\n\t// Keep track of what keys we have seen (and already wrapped if needed).\n\t// Used to avoid rewrapping already wrapped properties.\n\t// Preloaded with \"constructor\" to avoid wrapping the constructor as there is no need to set the broken flag when the constructor throws and does not return an object.\n\t// Avoiding wrapping the constructor also avoids messing up the displayed name in the debugger.\n\tconst doNotWrap: Set<string | symbol> = new Set([\"constructor\"]);\n\n\tlet prototype: object | null = target.prototype;\n\twhile (prototype !== null) {\n\t\tfor (const key of Reflect.ownKeys(prototype)) {\n\t\t\tif (!doNotWrap.has(key)) {\n\t\t\t\tdoNotWrap.add(key);\n\t\t\t\tconst descriptor = Reflect.getOwnPropertyDescriptor(prototype, key);\n\t\t\t\t// Method\n\t\t\t\tif (\n\t\t\t\t\tdescriptor !== undefined &&\n\t\t\t\t\ttypeof descriptor.value === \"function\" &&\n\t\t\t\t\t!isBreaker(descriptor.value)\n\t\t\t\t) {\n\t\t\t\t\t// This does not affect the original class, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor\n\t\t\t\t\tdescriptor.value = breakingMethod(descriptor.value);\n\t\t\t\t\tObject.defineProperty(DecoratedBreakable.prototype, key, descriptor);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tprototype = Reflect.getPrototypeOf(prototype);\n\t}\n\n\treturn DecoratedBreakable;\n}\n"]}