@fluidframework/tree 2.103.0 → 2.111.0

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

@@ -1 +1 @@
-{"version":3,"file":"arrayUtilities.d.ts","sourceRoot":"","sources":["../../src/util/arrayUtilities.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAIxE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAK1E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAClC,OAAO,EAAE,MAAM,EACf,eAAe,GAAE,OAAe,GAC9B,IAAI,CAeN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CACjC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAClC,OAAO,EAAE,MAAM,GACb,IAAI,CAQN"}
+{"version":3,"file":"arrayUtilities.d.ts","sourceRoot":"","sources":["../../src/util/arrayUtilities.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAIxE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAK1E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAClC,OAAO,EAAE,MAAM,EACf,eAAe,GAAE,OAAe,GAC9B,IAAI,CAeN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CACjC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAClC,OAAO,EAAE,MAAM,GACb,IAAI,CAQN;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4BAA4B;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACxC,KAAK,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,CAAA;CAAE,EAC/D,aAAa,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GACjC,SAAS,UAAU,EAAE,CAavB"}

package/lib/util/arrayUtilities.js

@@ -66,4 +66,26 @@ export function validateIndexRange(startIndex, endIndex, array, apiName) {
     validateIndex(startIndex, array, apiName, true);
     validateIndex(endIndex, array, apiName, true);
 }
+/**
+ * Walks `array` in order and collects the indices of every element for which `predicate` returns
+ * `true` into contiguous `[start, end)` ranges.
+ * @param array - The array (or array-like) to scan.
+ * @param shouldInclude - Returns `true` for elements whose indices should be included.
+ * @returns The collected ranges in ascending order. The returned array is empty if no elements match.
+ */
+export function collectContiguousRanges(array, shouldInclude) {
+    const ranges = [];
+    for (let i = 0; i < array.length; i++) {
+        if (shouldInclude(array[i])) {
+            const last = ranges[ranges.length - 1];
+            if (last?.end === i) {
+                last.end = i + 1;
+            }
+            else {
+                ranges.push({ start: i, end: i + 1 });
+            }
+        }
+    }
+    return ranges;
+}
 //# sourceMappingURL=arrayUtilities.js.map

package/lib/util/arrayUtilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"arrayUtilities.js","sourceRoot":"","sources":["../../src/util/arrayUtilities.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,OAAe;IACjE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,UAAU,CAAC,qCAAqC,OAAO,SAAS,KAAK,GAAG,CAAC,CAAC;IACrF,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa,EAAE,OAAe;IACnE,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACpC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACf,MAAM,IAAI,UAAU,CAAC,yCAAyC,OAAO,SAAS,KAAK,GAAG,CAAC,CAAC;IACzF,CAAC;AACF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC5B,KAAa,EACb,KAAkC,EAClC,OAAe,EACf,kBAA2B,KAAK;IAEhC,qBAAqB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACtC,IAAI,eAAe,EAAE,CAAC;QACrB,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAC1B,MAAM,IAAI,UAAU,CACnB,yBAAyB,OAAO,uCAAuC,KAAK,CAAC,MAAM,SAAS,KAAK,GAAG,CACpG,CAAC;QACH,CAAC;IACF,CAAC;SAAM,CAAC;QACP,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YAC3B,MAAM,IAAI,UAAU,CACnB,yBAAyB,OAAO,uCAAuC,KAAK,CAAC,MAAM,GAAG,CAAC,SAAS,KAAK,GAAG,CACxG,CAAC;QACH,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CACjC,UAAkB,EAClB,QAAgB,EAChB,KAAkC,EAClC,OAAe;IAEf,IAAI,UAAU,GAAG,QAAQ,EAAE,CAAC;QAC3B,MAAM,IAAI,UAAU,CACnB,6BAA6B,OAAO,iBAAiB,UAAU,8BAA8B,QAAQ,GAAG,CACxG,CAAC;IACH,CAAC;IACD,aAAa,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAChD,aAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AAC/C,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\n/**\n * Validates that the provided index is a safe integer.\n * @throws If the index is invalid.\n * @param index - The index to validate.\n * @param apiName - The name of the API performing the validation.\n * @throws If the index is invalid.\n */\nexport function validateSafeInteger(index: number, apiName: string): void {\n\tif (!Number.isSafeInteger(index)) {\n\t\tthrow new UsageError(`Expected a safe integer passed to ${apiName}, got ${index}.`);\n\t}\n}\n\n/**\n * Validates that the provided index is a 0 or greater safe integer.\n * @param index - The index to validate.\n * @param apiName - The name of the API performing the validation.\n * @throws If the index is invalid.\n */\nexport function validatePositiveIndex(index: number, apiName: string): void {\n\tvalidateSafeInteger(index, apiName);\n\tif (index < 0) {\n\t\tthrow new UsageError(`Expected non-negative index passed to ${apiName}, got ${index}.`);\n\t}\n}\n\n/**\n * Validates that the provided index is a non-negative safe integer within the bounds of the provided array (or, optionally, 1 past its end).\n * @throws If the index is invalid.\n * @param index - The index to validate.\n * @param array - The array to validate against.\n * @param apiName - The name of the API performing the validation.\n * @param allowOnePastEnd - Whether to allow the index to be one past the end of the array.\n */\nexport function validateIndex(\n\tindex: number,\n\tarray: { readonly length: number },\n\tapiName: string,\n\tallowOnePastEnd: boolean = false,\n): void {\n\tvalidatePositiveIndex(index, apiName);\n\tif (allowOnePastEnd) {\n\t\tif (index > array.length) {\n\t\t\tthrow new UsageError(\n\t\t\t\t`Index value passed to ${apiName} is out of bounds. Expected at most ${array.length}, got ${index}.`,\n\t\t\t);\n\t\t}\n\t} else {\n\t\tif (index >= array.length) {\n\t\t\tthrow new UsageError(\n\t\t\t\t`Index value passed to ${apiName} is out of bounds. Expected at most ${array.length - 1}, got ${index}.`,\n\t\t\t);\n\t\t}\n\t}\n}\n\n/**\n * Validates that the provided range `[startIndex, endIndex)` is valid and within the bounds of the provided array.\n * @remarks\n * This is intended for ranges which are inclusive for the lower bound, and exclusive for the upper bound,\n * and permits 0 length ranges, even `[array.length, array.length)`.\n * @throws If the index is invalid.\n * @param startIndex - The index that starts the range (inclusive).\n * @param endIndex - The index that ends the range (exclusive).\n * @param array - The array to validate against.\n * @param apiName - The name of the API performing the validation.\n */\nexport function validateIndexRange(\n\tstartIndex: number,\n\tendIndex: number,\n\tarray: { readonly length: number },\n\tapiName: string,\n): void {\n\tif (startIndex > endIndex) {\n\t\tthrow new UsageError(\n\t\t\t`Malformed range passed to ${apiName}. Start index ${startIndex} is greater than end index ${endIndex}.`,\n\t\t);\n\t}\n\tvalidateIndex(startIndex, array, apiName, true);\n\tvalidateIndex(endIndex, array, apiName, true);\n}\n"]}
+{"version":3,"file":"arrayUtilities.js","sourceRoot":"","sources":["../../src/util/arrayUtilities.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,OAAe;IACjE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,UAAU,CAAC,qCAAqC,OAAO,SAAS,KAAK,GAAG,CAAC,CAAC;IACrF,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa,EAAE,OAAe;IACnE,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACpC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACf,MAAM,IAAI,UAAU,CAAC,yCAAyC,OAAO,SAAS,KAAK,GAAG,CAAC,CAAC;IACzF,CAAC;AACF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC5B,KAAa,EACb,KAAkC,EAClC,OAAe,EACf,kBAA2B,KAAK;IAEhC,qBAAqB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACtC,IAAI,eAAe,EAAE,CAAC;QACrB,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAC1B,MAAM,IAAI,UAAU,CACnB,yBAAyB,OAAO,uCAAuC,KAAK,CAAC,MAAM,SAAS,KAAK,GAAG,CACpG,CAAC;QACH,CAAC;IACF,CAAC;SAAM,CAAC;QACP,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YAC3B,MAAM,IAAI,UAAU,CACnB,yBAAyB,OAAO,uCAAuC,KAAK,CAAC,MAAM,GAAG,CAAC,SAAS,KAAK,GAAG,CACxG,CAAC;QACH,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CACjC,UAAkB,EAClB,QAAgB,EAChB,KAAkC,EAClC,OAAe;IAEf,IAAI,UAAU,GAAG,QAAQ,EAAE,CAAC;QAC3B,MAAM,IAAI,UAAU,CACnB,6BAA6B,OAAO,iBAAiB,UAAU,8BAA8B,QAAQ,GAAG,CACxG,CAAC;IACH,CAAC;IACD,aAAa,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAChD,aAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AAC/C,CAAC;AAYD;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACtC,KAA+D,EAC/D,aAAmC;IAEnC,MAAM,MAAM,GAAqC,EAAE,CAAC;IACpD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC,CAAM,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACvC,IAAI,IAAI,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC;gBACrB,IAAI,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YAClB,CAAC;iBAAM,CAAC;gBACP,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACvC,CAAC;QACF,CAAC;IACF,CAAC;IACD,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 { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\n/**\n * Validates that the provided index is a safe integer.\n * @throws If the index is invalid.\n * @param index - The index to validate.\n * @param apiName - The name of the API performing the validation.\n * @throws If the index is invalid.\n */\nexport function validateSafeInteger(index: number, apiName: string): void {\n\tif (!Number.isSafeInteger(index)) {\n\t\tthrow new UsageError(`Expected a safe integer passed to ${apiName}, got ${index}.`);\n\t}\n}\n\n/**\n * Validates that the provided index is a 0 or greater safe integer.\n * @param index - The index to validate.\n * @param apiName - The name of the API performing the validation.\n * @throws If the index is invalid.\n */\nexport function validatePositiveIndex(index: number, apiName: string): void {\n\tvalidateSafeInteger(index, apiName);\n\tif (index < 0) {\n\t\tthrow new UsageError(`Expected non-negative index passed to ${apiName}, got ${index}.`);\n\t}\n}\n\n/**\n * Validates that the provided index is a non-negative safe integer within the bounds of the provided array (or, optionally, 1 past its end).\n * @throws If the index is invalid.\n * @param index - The index to validate.\n * @param array - The array to validate against.\n * @param apiName - The name of the API performing the validation.\n * @param allowOnePastEnd - Whether to allow the index to be one past the end of the array.\n */\nexport function validateIndex(\n\tindex: number,\n\tarray: { readonly length: number },\n\tapiName: string,\n\tallowOnePastEnd: boolean = false,\n): void {\n\tvalidatePositiveIndex(index, apiName);\n\tif (allowOnePastEnd) {\n\t\tif (index > array.length) {\n\t\t\tthrow new UsageError(\n\t\t\t\t`Index value passed to ${apiName} is out of bounds. Expected at most ${array.length}, got ${index}.`,\n\t\t\t);\n\t\t}\n\t} else {\n\t\tif (index >= array.length) {\n\t\t\tthrow new UsageError(\n\t\t\t\t`Index value passed to ${apiName} is out of bounds. Expected at most ${array.length - 1}, got ${index}.`,\n\t\t\t);\n\t\t}\n\t}\n}\n\n/**\n * Validates that the provided range `[startIndex, endIndex)` is valid and within the bounds of the provided array.\n * @remarks\n * This is intended for ranges which are inclusive for the lower bound, and exclusive for the upper bound,\n * and permits 0 length ranges, even `[array.length, array.length)`.\n * @throws If the index is invalid.\n * @param startIndex - The index that starts the range (inclusive).\n * @param endIndex - The index that ends the range (exclusive).\n * @param array - The array to validate against.\n * @param apiName - The name of the API performing the validation.\n */\nexport function validateIndexRange(\n\tstartIndex: number,\n\tendIndex: number,\n\tarray: { readonly length: number },\n\tapiName: string,\n): void {\n\tif (startIndex > endIndex) {\n\t\tthrow new UsageError(\n\t\t\t`Malformed range passed to ${apiName}. Start index ${startIndex} is greater than end index ${endIndex}.`,\n\t\t);\n\t}\n\tvalidateIndex(startIndex, array, apiName, true);\n\tvalidateIndex(endIndex, array, apiName, true);\n}\n\n/**\n * A half-open `[start, end)` range of array indices.\n */\nexport interface IndexRange {\n\t/** Start index, inclusive. */\n\treadonly start: number;\n\t/** End index, exclusive. */\n\treadonly end: number;\n}\n\n/**\n * Walks `array` in order and collects the indices of every element for which `predicate` returns\n * `true` into contiguous `[start, end)` ranges.\n * @param array - The array (or array-like) to scan.\n * @param shouldInclude - Returns `true` for elements whose indices should be included.\n * @returns The collected ranges in ascending order. The returned array is empty if no elements match.\n */\nexport function collectContiguousRanges<T>(\n\tarray: { readonly length: number; readonly [index: number]: T },\n\tshouldInclude: (item: T) => boolean,\n): readonly IndexRange[] {\n\tconst ranges: { start: number; end: number }[] = [];\n\tfor (let i = 0; i < array.length; i++) {\n\t\tif (shouldInclude(array[i] as T)) {\n\t\t\tconst last = ranges[ranges.length - 1];\n\t\t\tif (last?.end === i) {\n\t\t\t\tlast.end = i + 1;\n\t\t\t} else {\n\t\t\t\tranges.push({ start: i, end: i + 1 });\n\t\t\t}\n\t\t}\n\t}\n\treturn ranges;\n}\n"]}

package/lib/util/compressedIds.d.ts

@@ -0,0 +1,118 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { IIdCompressor, OpSpaceCompressedId, SessionId, SessionSpaceCompressedId } from "@fluidframework/id-compressor";
+/**
+ * An encoded identifier that can be decoded without an originator session id.
+ * A finalized compressed id — the same numeric value in op-space and session-space.
+ * @remarks
+ * These are safe to use in contexts where the encoding id compressor is available to decode them,
+ * even when the session id of the encoding id compressor is not known.
+ */
+export type OriginatorlessEncodedId = SessionSpaceCompressedId & OpSpaceCompressedId;
+/**
+ * An encoded identifier that may require an originator session id to decode.
+ * Any op-space compressed id, either finalized or session-local.
+ * @remarks
+ * These are only safe to use in contexts where the encoding id compressor is available
+ * and the session id of the encoding id compressor is known.
+ * Currently the only such case is in ops, excluding attach summary ops.
+ */
+export type OriginatorDependentEncodedId = OpSpaceCompressedId;
+/**
+ * Selects how identifiers are encoded for transport/persistence.
+ */
+export declare enum EncodedIdType {
+    /**
+     * {@link OriginatorlessEncodedId}.
+     */
+    Originatorless = 0,
+    /**
+     * {@link OriginatorDependentEncodedId}.
+     */
+    OriginatorDependent = 1
+}
+export type EncodedId<T extends EncodedIdType> = T extends EncodedIdType.Originatorless ? OriginatorlessEncodedId : T extends EncodedIdType.OriginatorDependent ? OriginatorDependentEncodedId : OriginatorlessEncodedId | OriginatorDependentEncodedId;
+/**
+ * Context for encoding identifiers.
+ * @remarks
+ * See {@link FieldBatchDecodingContext} for the decoder.
+ */
+export interface IdEncodingContext {
+    encodePossiblyCompressedId(id: string): string | EncodedId<EncodedIdType>;
+}
+/**
+ * Encode a string identifier into a possibly compressed form based on the requested mode.
+ *
+ * @param id - The string identifier to encode.
+ * @param idCompressor - The ID compressor to use for compression.
+ * @param encodedIdType - The type of encoding to use. If the context doing the decoding will have the originator {@link SessionId},
+ * then {@link EncodedIdType.OriginatorDependent} can be used.
+ * Otherwise, {@link EncodedIdType.Originatorless} must be used.
+ *
+ * @privateRemarks
+ * Performance:
+ * When trying to optimize to avoid unnecessary identifier decompression, and store identifiers compressed in memory,
+ * this will likely need to be updated to allow in SessionSpaceCompressedIds.
+ */
+export declare function encodePossiblyCompressedId<T extends EncodedIdType>(id: string, idCompressor: IIdCompressor, encodedIdType: T): string | EncodedId<T>;
+/**
+ * Decode an {@link OriginatorlessEncodedId} without needing an originator session id.
+ *
+ * The id is guaranteed to be final by the type contract; it is normalized via
+ * {@link IIdCompressor.tryNormalizeToSessionSpaceWithoutSession}, which handles the
+ * cluster-aligned-local case rather than relying on the bare numeric value.
+ */
+export declare function decodeOriginatorlessEncodedId(id: OriginatorlessEncodedId, idCompressor: IIdCompressor): SessionSpaceCompressedId;
+/**
+ * Decode an {@link OriginatorDependentEncodedId} using a known originator session id.
+ */
+export declare function decodeEncodedIdWithOriginator(id: OriginatorDependentEncodedId, originator: SessionId, idCompressor: IIdCompressor): SessionSpaceCompressedId;
+/**
+ * Decode an {@link OriginatorDependentEncodedId} without a session.
+ *
+ * Returns the session-space id if `id` is finalized (and therefore resolvable
+ * without an originator session), or `undefined` if `id` is a non-final op-space
+ * id that cannot be resolved without the originator session.
+ */
+export declare function tryDecodeEncodedIdWithoutSession(id: OriginatorDependentEncodedId, idCompressor: IIdCompressor): SessionSpaceCompressedId | undefined;
+/**
+ * Configuration for the heal-on-decode workaround. The internal counterpart of
+ * the user-facing {@link SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode}
+ * option — see that option for the user-facing rationale and trade-offs.
+ *
+ * Carried by decode-side contexts (`ChangeEncodingContext.healing`,
+ * `EditManagerEncodingContext.healing`, etc.) when the workaround is enabled.
+ * Presence enables healing; `undefined` opts out. There is no separate boolean,
+ * which makes it impossible to enable healing without supplying the namespace
+ * input.
+ */
+export interface IdentifierHealingConfig {
+    /**
+     * The SharedTree's shared-object id, used as the v5 namespace input so
+     * healed UUIDs are unique across attaches of different documents with the
+     * same session offsets.
+     */
+    readonly sharedObjectId: string;
+}
+/**
+ * Decode an op-space compressed id without a session.
+ *
+ * Finalized ids are returned as session-space ids (final ids are invariant
+ * across the two spaces). Non-final ids are healed via {@link IdentifierHealingConfig}
+ * if provided, or cause the resolver to throw otherwise. A healed result is a
+ * deterministic v5 UUID string — *not* a `StableId`, since that brand requires
+ * v4, but still a valid identifier value; the `string` arm of the return type
+ * covers this case.
+ */
+export declare function forceDecodeEncodedIdWithoutSession(id: OpSpaceCompressedId, idCompressor: IIdCompressor, healing: IdentifierHealingConfig | undefined): SessionSpaceCompressedId | string;
+/**
+ * Convert a decoded, but possibly compressed, identifier to the decompressed string format.
+ *
+ * Session-space compressed ids are decompressed to their UUID representation via the compressor.
+ * String inputs pass through unchanged — they are already in the stored form,
+ * whether a `StableId` UUID, a heal-synthesized v5 UUID or other arbitrary string identifier.
+ */
+export declare function decompressIdentifierIfNeeded(id: SessionSpaceCompressedId | string, idCompressor: Pick<IIdCompressor, "decompress">): string;
+//# sourceMappingURL=compressedIds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compressedIds.d.ts","sourceRoot":"","sources":["../../src/util/compressedIds.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACX,aAAa,EACb,mBAAmB,EACnB,SAAS,EACT,wBAAwB,EACxB,MAAM,+BAA+B,CAAC;AAIvC;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG,wBAAwB,GAAG,mBAAmB,CAAC;AAErF;;;;;;;GAOG;AACH,MAAM,MAAM,4BAA4B,GAAG,mBAAmB,CAAC;AAE/D;;GAEG;AACH,oBAAY,aAAa;IACxB;;OAEG;IACH,cAAc,IAAA;IACd;;OAEG;IACH,mBAAmB,IAAA;CACnB;AAED,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,aAAa,IAAI,CAAC,SAAS,aAAa,CAAC,cAAc,GACpF,uBAAuB,GACvB,CAAC,SAAS,aAAa,CAAC,mBAAmB,GAC1C,4BAA4B,GAC5B,uBAAuB,GAAG,4BAA4B,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,0BAA0B,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,aAAa,CAAC,CAAC;CAC1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,aAAa,EACjE,EAAE,EAAE,MAAM,EACV,YAAY,EAAE,aAAa,EAC3B,aAAa,EAAE,CAAC,GACd,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAavB;AAWD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC5C,EAAE,EAAE,uBAAuB,EAC3B,YAAY,EAAE,aAAa,GACzB,wBAAwB,CAO1B;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC5C,EAAE,EAAE,4BAA4B,EAChC,UAAU,EAAE,SAAS,EACrB,YAAY,EAAE,aAAa,GACzB,wBAAwB,CAE1B;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC/C,EAAE,EAAE,4BAA4B,EAChC,YAAY,EAAE,aAAa,GACzB,wBAAwB,GAAG,SAAS,CAEtC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kCAAkC,CACjD,EAAE,EAAE,mBAAmB,EACvB,YAAY,EAAE,aAAa,EAC3B,OAAO,EAAE,uBAAuB,GAAG,SAAS,GAC1C,wBAAwB,GAAG,MAAM,CAYnC;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC3C,EAAE,EAAE,wBAAwB,GAAG,MAAM,EACrC,YAAY,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,GAC7C,MAAM,CAQR"}

package/lib/util/compressedIds.js

@@ -0,0 +1,124 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { assert } from "@fluidframework/core-utils/internal";
+import { isFinalId, isStableId } from "@fluidframework/id-compressor/internal";
+import { v5 as uuidV5 } from "uuid";
+/**
+ * Selects how identifiers are encoded for transport/persistence.
+ */
+export var EncodedIdType;
+(function (EncodedIdType) {
+    /**
+     * {@link OriginatorlessEncodedId}.
+     */
+    EncodedIdType[EncodedIdType["Originatorless"] = 0] = "Originatorless";
+    /**
+     * {@link OriginatorDependentEncodedId}.
+     */
+    EncodedIdType[EncodedIdType["OriginatorDependent"] = 1] = "OriginatorDependent";
+})(EncodedIdType || (EncodedIdType = {}));
+/**
+ * Encode a string identifier into a possibly compressed form based on the requested mode.
+ *
+ * @param id - The string identifier to encode.
+ * @param idCompressor - The ID compressor to use for compression.
+ * @param encodedIdType - The type of encoding to use. If the context doing the decoding will have the originator {@link SessionId},
+ * then {@link EncodedIdType.OriginatorDependent} can be used.
+ * Otherwise, {@link EncodedIdType.Originatorless} must be used.
+ *
+ * @privateRemarks
+ * Performance:
+ * When trying to optimize to avoid unnecessary identifier decompression, and store identifiers compressed in memory,
+ * this will likely need to be updated to allow in SessionSpaceCompressedIds.
+ */
+export function encodePossiblyCompressedId(id, idCompressor, encodedIdType) {
+    if (!isStableId(id)) {
+        return id;
+    }
+    const sessionSpaceCompressedId = idCompressor.tryRecompress(id);
+    if (sessionSpaceCompressedId === undefined) {
+        return id;
+    }
+    const opSpaceId = idCompressor.normalizeToOpSpace(sessionSpaceCompressedId);
+    if (encodedIdType === EncodedIdType.Originatorless) {
+        return isFinalId(opSpaceId) ? opSpaceId : id;
+    }
+    return opSpaceId;
+}
+/**
+ * Namespace used for the deterministic UUIDv5 produced by the heal-on-decode workaround
+ * in {@link forceDecodeEncodedIdWithoutSession}.
+ *
+ * This scheme requires consensus across all clients to function — every client that
+ * encounters the same unresolvable id must produce the same v5 UUID.
+ */
+const healingNamespace = "f8a89df3-6882-400f-b913-4c1f6f0157bd";
+/**
+ * Decode an {@link OriginatorlessEncodedId} without needing an originator session id.
+ *
+ * The id is guaranteed to be final by the type contract; it is normalized via
+ * {@link IIdCompressor.tryNormalizeToSessionSpaceWithoutSession}, which handles the
+ * cluster-aligned-local case rather than relying on the bare numeric value.
+ */
+export function decodeOriginatorlessEncodedId(id, idCompressor) {
+    const sessionSpaceId = idCompressor.tryNormalizeToSessionSpaceWithoutSession(id);
+    assert(sessionSpaceId !== undefined, 0xd0a /* OriginatorlessEncodedId must be a finalized compressed id at runtime */);
+    return sessionSpaceId;
+}
+/**
+ * Decode an {@link OriginatorDependentEncodedId} using a known originator session id.
+ */
+export function decodeEncodedIdWithOriginator(id, originator, idCompressor) {
+    return idCompressor.normalizeToSessionSpace(id, originator);
+}
+/**
+ * Decode an {@link OriginatorDependentEncodedId} without a session.
+ *
+ * Returns the session-space id if `id` is finalized (and therefore resolvable
+ * without an originator session), or `undefined` if `id` is a non-final op-space
+ * id that cannot be resolved without the originator session.
+ */
+export function tryDecodeEncodedIdWithoutSession(id, idCompressor) {
+    return idCompressor.tryNormalizeToSessionSpaceWithoutSession(id);
+}
+/**
+ * Decode an op-space compressed id without a session.
+ *
+ * Finalized ids are returned as session-space ids (final ids are invariant
+ * across the two spaces). Non-final ids are healed via {@link IdentifierHealingConfig}
+ * if provided, or cause the resolver to throw otherwise. A healed result is a
+ * deterministic v5 UUID string — *not* a `StableId`, since that brand requires
+ * v4, but still a valid identifier value; the `string` arm of the return type
+ * covers this case.
+ */
+export function forceDecodeEncodedIdWithoutSession(id, idCompressor, healing) {
+    const decoded = tryDecodeEncodedIdWithoutSession(id, idCompressor);
+    if (decoded !== undefined) {
+        return decoded;
+    }
+    // `id` is a non-final op-space compressed id.
+    if (healing !== undefined) {
+        return uuidV5(`${healing.sharedObjectId}|${id}`, healingNamespace);
+    }
+    throw new Error("Summary could not be loaded due to an incorrectly encoded identifier. See SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode for mitigation.");
+}
+/**
+ * Convert a decoded, but possibly compressed, identifier to the decompressed string format.
+ *
+ * Session-space compressed ids are decompressed to their UUID representation via the compressor.
+ * String inputs pass through unchanged — they are already in the stored form,
+ * whether a `StableId` UUID, a heal-synthesized v5 UUID or other arbitrary string identifier.
+ */
+export function decompressIdentifierIfNeeded(id, idCompressor) {
+    if (typeof id === "string") {
+        return id;
+    }
+    else {
+        const decompressed = idCompressor.decompress(id);
+        assert(typeof decompressed === "string", 0xd0b /* Decompressed id must be a string */);
+        return decompressed;
+    }
+}
+//# sourceMappingURL=compressedIds.js.map

package/lib/util/compressedIds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compressedIds.js","sourceRoot":"","sources":["../../src/util/compressedIds.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 type {\n\tIIdCompressor,\n\tOpSpaceCompressedId,\n\tSessionId,\n\tSessionSpaceCompressedId,\n} from \"@fluidframework/id-compressor\";\nimport { isFinalId, isStableId } from \"@fluidframework/id-compressor/internal\";\nimport { v5 as uuidV5 } from \"uuid\";\n\n/**\n * An encoded identifier that can be decoded without an originator session id.\n * A finalized compressed id — the same numeric value in op-space and session-space.\n * @remarks\n * These are safe to use in contexts where the encoding id compressor is available to decode them,\n * even when the session id of the encoding id compressor is not known.\n */\nexport type OriginatorlessEncodedId = SessionSpaceCompressedId & OpSpaceCompressedId;\n\n/**\n * An encoded identifier that may require an originator session id to decode.\n * Any op-space compressed id, either finalized or session-local.\n * @remarks\n * These are only safe to use in contexts where the encoding id compressor is available\n * and the session id of the encoding id compressor is known.\n * Currently the only such case is in ops, excluding attach summary ops.\n */\nexport type OriginatorDependentEncodedId = OpSpaceCompressedId;\n\n/**\n * Selects how identifiers are encoded for transport/persistence.\n */\nexport enum EncodedIdType {\n\t/**\n\t * {@link OriginatorlessEncodedId}.\n\t */\n\tOriginatorless,\n\t/**\n\t * {@link OriginatorDependentEncodedId}.\n\t */\n\tOriginatorDependent,\n}\n\nexport type EncodedId<T extends EncodedIdType> = T extends EncodedIdType.Originatorless\n\t? OriginatorlessEncodedId\n\t: T extends EncodedIdType.OriginatorDependent\n\t\t? OriginatorDependentEncodedId\n\t\t: OriginatorlessEncodedId | OriginatorDependentEncodedId;\n\n/**\n * Context for encoding identifiers.\n * @remarks\n * See {@link FieldBatchDecodingContext} for the decoder.\n */\nexport interface IdEncodingContext {\n\tencodePossiblyCompressedId(id: string): string | EncodedId<EncodedIdType>;\n}\n\n/**\n * Encode a string identifier into a possibly compressed form based on the requested mode.\n *\n * @param id - The string identifier to encode.\n * @param idCompressor - The ID compressor to use for compression.\n * @param encodedIdType - The type of encoding to use. If the context doing the decoding will have the originator {@link SessionId},\n * then {@link EncodedIdType.OriginatorDependent} can be used.\n * Otherwise, {@link EncodedIdType.Originatorless} must be used.\n *\n * @privateRemarks\n * Performance:\n * When trying to optimize to avoid unnecessary identifier decompression, and store identifiers compressed in memory,\n * this will likely need to be updated to allow in SessionSpaceCompressedIds.\n */\nexport function encodePossiblyCompressedId<T extends EncodedIdType>(\n\tid: string,\n\tidCompressor: IIdCompressor,\n\tencodedIdType: T,\n): string | EncodedId<T> {\n\tif (!isStableId(id)) {\n\t\treturn id;\n\t}\n\tconst sessionSpaceCompressedId = idCompressor.tryRecompress(id);\n\tif (sessionSpaceCompressedId === undefined) {\n\t\treturn id;\n\t}\n\tconst opSpaceId = idCompressor.normalizeToOpSpace(sessionSpaceCompressedId);\n\tif (encodedIdType === EncodedIdType.Originatorless) {\n\t\treturn isFinalId(opSpaceId) ? (opSpaceId as unknown as EncodedId<T>) : id;\n\t}\n\treturn opSpaceId as unknown as EncodedId<T>;\n}\n\n/**\n * Namespace used for the deterministic UUIDv5 produced by the heal-on-decode workaround\n * in {@link forceDecodeEncodedIdWithoutSession}.\n *\n * This scheme requires consensus across all clients to function — every client that\n * encounters the same unresolvable id must produce the same v5 UUID.\n */\nconst healingNamespace = \"f8a89df3-6882-400f-b913-4c1f6f0157bd\";\n\n/**\n * Decode an {@link OriginatorlessEncodedId} without needing an originator session id.\n *\n * The id is guaranteed to be final by the type contract; it is normalized via\n * {@link IIdCompressor.tryNormalizeToSessionSpaceWithoutSession}, which handles the\n * cluster-aligned-local case rather than relying on the bare numeric value.\n */\nexport function decodeOriginatorlessEncodedId(\n\tid: OriginatorlessEncodedId,\n\tidCompressor: IIdCompressor,\n): SessionSpaceCompressedId {\n\tconst sessionSpaceId = idCompressor.tryNormalizeToSessionSpaceWithoutSession(id);\n\tassert(\n\t\tsessionSpaceId !== undefined,\n\t\t0xd0a /* OriginatorlessEncodedId must be a finalized compressed id at runtime */,\n\t);\n\treturn sessionSpaceId;\n}\n\n/**\n * Decode an {@link OriginatorDependentEncodedId} using a known originator session id.\n */\nexport function decodeEncodedIdWithOriginator(\n\tid: OriginatorDependentEncodedId,\n\toriginator: SessionId,\n\tidCompressor: IIdCompressor,\n): SessionSpaceCompressedId {\n\treturn idCompressor.normalizeToSessionSpace(id, originator);\n}\n\n/**\n * Decode an {@link OriginatorDependentEncodedId} without a session.\n *\n * Returns the session-space id if `id` is finalized (and therefore resolvable\n * without an originator session), or `undefined` if `id` is a non-final op-space\n * id that cannot be resolved without the originator session.\n */\nexport function tryDecodeEncodedIdWithoutSession(\n\tid: OriginatorDependentEncodedId,\n\tidCompressor: IIdCompressor,\n): SessionSpaceCompressedId | undefined {\n\treturn idCompressor.tryNormalizeToSessionSpaceWithoutSession(id);\n}\n\n/**\n * Configuration for the heal-on-decode workaround. The internal counterpart of\n * the user-facing {@link SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode}\n * option — see that option for the user-facing rationale and trade-offs.\n *\n * Carried by decode-side contexts (`ChangeEncodingContext.healing`,\n * `EditManagerEncodingContext.healing`, etc.) when the workaround is enabled.\n * Presence enables healing; `undefined` opts out. There is no separate boolean,\n * which makes it impossible to enable healing without supplying the namespace\n * input.\n */\nexport interface IdentifierHealingConfig {\n\t/**\n\t * The SharedTree's shared-object id, used as the v5 namespace input so\n\t * healed UUIDs are unique across attaches of different documents with the\n\t * same session offsets.\n\t */\n\treadonly sharedObjectId: string;\n}\n\n/**\n * Decode an op-space compressed id without a session.\n *\n * Finalized ids are returned as session-space ids (final ids are invariant\n * across the two spaces). Non-final ids are healed via {@link IdentifierHealingConfig}\n * if provided, or cause the resolver to throw otherwise. A healed result is a\n * deterministic v5 UUID string — *not* a `StableId`, since that brand requires\n * v4, but still a valid identifier value; the `string` arm of the return type\n * covers this case.\n */\nexport function forceDecodeEncodedIdWithoutSession(\n\tid: OpSpaceCompressedId,\n\tidCompressor: IIdCompressor,\n\thealing: IdentifierHealingConfig | undefined,\n): SessionSpaceCompressedId | string {\n\tconst decoded = tryDecodeEncodedIdWithoutSession(id, idCompressor);\n\tif (decoded !== undefined) {\n\t\treturn decoded;\n\t}\n\t// `id` is a non-final op-space compressed id.\n\tif (healing !== undefined) {\n\t\treturn uuidV5(`${healing.sharedObjectId}|${id}`, healingNamespace);\n\t}\n\tthrow new Error(\n\t\t\"Summary could not be loaded due to an incorrectly encoded identifier. See SharedTreeOptionsBeta.healUnresolvableIdentifiersOnDecode for mitigation.\",\n\t);\n}\n\n/**\n * Convert a decoded, but possibly compressed, identifier to the decompressed string format.\n *\n * Session-space compressed ids are decompressed to their UUID representation via the compressor.\n * String inputs pass through unchanged — they are already in the stored form,\n * whether a `StableId` UUID, a heal-synthesized v5 UUID or other arbitrary string identifier.\n */\nexport function decompressIdentifierIfNeeded(\n\tid: SessionSpaceCompressedId | string,\n\tidCompressor: Pick<IIdCompressor, \"decompress\">,\n): string {\n\tif (typeof id === \"string\") {\n\t\treturn id;\n\t} else {\n\t\tconst decompressed = idCompressor.decompress(id);\n\t\tassert(typeof decompressed === \"string\", 0xd0b /* Decompressed id must be a string */);\n\t\treturn decompressed;\n\t}\n}\n"]}

package/lib/util/index.d.ts

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-export { validateIndex, validateIndexRange, validatePositiveIndex, validateSafeInteger, } from "./arrayUtilities.js";
+export { collectContiguousRanges, type IndexRange, validateIndex, validateIndexRange, validatePositiveIndex, validateSafeInteger, } from "./arrayUtilities.js";
 export { brand, type Brand, BrandedType, type NameFromBranded, type ValueFromBranded, brandConst, type Values, strictEnum, unbrand, } from "./brand.js";
 export { brandedNumberType, brandedStringType } from "./typeboxBrand.js";
 export { brandOpaque, extractFromOpaque, type ExtractFromOpaque, type Opaque, } from "./opaque.js";
@@ -22,4 +22,5 @@ export { Breakable, type WithBreakable, breakingMethod, throwIfBroken, breakingC
 export { type TupleBTree, newTupleBTree, mergeTupleBTrees, createTupleComparator, } from "./bTreeUtils.js";
 export { cloneWithReplacements } from "./cloneWithReplacements.js";
 export { readAndParseSnapshotBlob } from "./readSnapshotBlob.js";
+export { type OriginatorlessEncodedId, type OriginatorDependentEncodedId, type IdentifierHealingConfig, EncodedIdType, encodePossiblyCompressedId, type IdEncodingContext, type EncodedId, decodeOriginatorlessEncodedId, decodeEncodedIdWithOriginator, tryDecodeEncodedIdWithoutSession, forceDecodeEncodedIdWithoutSession, decompressIdentifierIfNeeded, } from "./compressedIds.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"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"}

package/lib/util/index.js

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-export { validateIndex, validateIndexRange, validatePositiveIndex, validateSafeInteger, } from "./arrayUtilities.js";
+export { collectContiguousRanges, validateIndex, validateIndexRange, validatePositiveIndex, validateSafeInteger, } from "./arrayUtilities.js";
 export { brand, BrandedType, brandConst, strictEnum, unbrand, } from "./brand.js";
 export { brandedNumberType, brandedStringType } from "./typeboxBrand.js";
 export { brandOpaque, extractFromOpaque, } from "./opaque.js";
@@ -20,4 +20,5 @@ export { Breakable, breakingMethod, throwIfBroken, breakingClass, } from "./brea
 export { newTupleBTree, mergeTupleBTrees, createTupleComparator, } from "./bTreeUtils.js";
 export { cloneWithReplacements } from "./cloneWithReplacements.js";
 export { readAndParseSnapshotBlob } from "./readSnapshotBlob.js";
+export { EncodedIdType, encodePossiblyCompressedId, decodeOriginatorlessEncodedId, decodeEncodedIdWithOriginator, tryDecodeEncodedIdWithoutSession, forceDecodeEncodedIdWithoutSession, decompressIdentifierIfNeeded, } from "./compressedIds.js";
 //# sourceMappingURL=index.js.map

package/lib/util/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,KAAK,EAEL,WAAW,EAGX,UAAU,EAEV,UAAU,EACV,OAAO,GACP,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EACN,WAAW,EACX,iBAAiB,GAGjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAGlB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,cAAc,EAAkB,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EAAmB,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAiBrE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACN,SAAS,EACT,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,eAAe,EAKf,4BAA4B,EAC5B,SAAS,EACT,WAAW,EACX,cAAc,EAId,gBAAgB,EAChB,gBAAgB,EAChB,4BAA4B,EAC5B,WAAW,EACX,SAAS,EACT,eAAe,EACf,aAAa,EAEb,UAAU,EACV,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,qBAAqB,EACrB,IAAI,EACJ,KAAK,EACL,OAAO,EACP,OAAO,EACP,SAAS,EACT,wBAAwB,EACxB,qBAAqB,IAAI,YAAY,EACrC,aAAa,EACb,eAAe,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAAyB,MAAM,wBAAwB,CAAC;AAcrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAIN,sBAAsB,EACtB,WAAW,GACX,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACN,QAAQ,EAER,kBAAkB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAEN,oBAAoB,EACpB,oBAAoB,EAEpB,eAAe,GACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACN,SAAS,EAET,cAAc,EACd,aAAa,EACb,aAAa,GACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAEN,aAAa,EACb,gBAAgB,EAChB,qBAAqB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport {\n\tvalidateIndex,\n\tvalidateIndexRange,\n\tvalidatePositiveIndex,\n\tvalidateSafeInteger,\n} from \"./arrayUtilities.js\";\nexport {\n\tbrand,\n\ttype Brand,\n\tBrandedType,\n\ttype NameFromBranded,\n\ttype ValueFromBranded,\n\tbrandConst,\n\ttype Values,\n\tstrictEnum,\n\tunbrand,\n} from \"./brand.js\";\nexport { brandedNumberType, brandedStringType } from \"./typeboxBrand.js\";\nexport {\n\tbrandOpaque,\n\textractFromOpaque,\n\ttype ExtractFromOpaque,\n\ttype Opaque,\n} from \"./opaque.js\";\nexport {\n\tdeleteFromNestedMap,\n\tgetOrAddInNestedMap,\n\tgetOrDefaultInNestedMap,\n\tforEachInNestedMap,\n\ttype NestedMap,\n\ttype ReadonlyNestedMap,\n\tSizedNestedMap,\n\tpopulateNestedMap,\n\tsetInNestedMap,\n\ttryAddToNestedMap,\n\ttryGetFromNestedMap,\n\tmapNestedMap,\n\tnestedMapToFlatList,\n\tnestedMapFromFlatList,\n\tgetOrCreateInNestedMap,\n} from \"./nestedMap.js\";\nexport { addToNestedSet, type NestedSet, nestedSetContains } from \"./nestedSet.js\";\nexport { type OffsetList, OffsetListFactory } from \"./offsetList.js\";\nexport type {\n\tareSafelyAssignable,\n\tContravariant,\n\tCovariant,\n\teitherIsAny,\n\tEnforceTypeCheckTests,\n\tInvariant,\n\tisAny,\n\tisAssignableTo,\n\tisStrictSubset,\n\tMakeNominal,\n\trequireFalse,\n\trequireTrue,\n\trequireAssignableTo,\n\tareOnlyKeys,\n} from \"./typeCheck.js\";\nexport { StackyIterator } from \"./stackyIterator.js\";\nexport {\n\tasMutable,\n\tbalancedReduce,\n\tcompareSets,\n\tgetOrAddEmptyToMap,\n\tgetOrCreate,\n\tisJsonObject,\n\tisReadonlyArray,\n\ttype JsonCompatible,\n\ttype JsonCompatibleObject,\n\ttype JsonCompatibleReadOnly,\n\ttype JsonCompatibleReadOnlyObject,\n\tJsonCompatibleReadOnlySchema,\n\tmakeArray,\n\tmapIterable,\n\tfilterIterable,\n\ttype Mutable,\n\ttype Populated,\n\ttype RecursiveReadonly,\n\tassertValidIndex,\n\tassertValidRange,\n\tassertNonNegativeSafeInteger,\n\tobjectToMap,\n\tinvertMap,\n\toneFromIterable,\n\tdisposeSymbol,\n\ttype IDisposable,\n\tcapitalize,\n\tassertValidRangeIndices,\n\ttransformObjectMap,\n\tcompareNumbers,\n\tcomparePartialNumbers,\n\tcompareStrings,\n\tcomparePartialStrings,\n\tfind,\n\tcount,\n\tgetLast,\n\thasSome,\n\thasSingle,\n\tdefineLazyCachedProperty,\n\tcopyPropertyIfDefined as copyProperty,\n\tgetOrAddInMap,\n\titerableHasSome,\n} from \"./utils.js\";\nexport { ReferenceCountedBase, type ReferenceCounted } from \"./referenceCounting.js\";\n\nexport type {\n\t_RecursiveTrick,\n\tRestrictiveReadonlyRecord,\n\tRestrictiveStringRecord,\n\t_InlineTrick,\n\tFlattenKeys,\n\tIsUnion,\n\tUnionToIntersection,\n\tUnionToTuple,\n\tPopUnion,\n} from \"./typeUtils.js\";\n\nexport { unsafeArrayToTuple } from \"./typeUtils.js\";\n\nexport {\n\ttype BrandedKey,\n\ttype BrandedKeyContent,\n\ttype BrandedMapSubset,\n\tgetOrCreateSlotContent,\n\tbrandedSlot,\n} from \"./brandedMap.js\";\n\nexport {\n\tRangeMap,\n\ttype RangeQueryResult,\n\tnewIntegerRangeMap,\n} from \"./rangeMap.js\";\n\nexport {\n\ttype IdAllocator,\n\tidAllocatorFromMaxId,\n\tidAllocatorFromState,\n\ttype IdAllocationState,\n\tfakeIdAllocator,\n} from \"./idAllocator.js\";\n\nexport {\n\tBreakable,\n\ttype WithBreakable,\n\tbreakingMethod,\n\tthrowIfBroken,\n\tbreakingClass,\n} from \"./breakable.js\";\n\nexport {\n\ttype TupleBTree,\n\tnewTupleBTree,\n\tmergeTupleBTrees,\n\tcreateTupleComparator,\n} from \"./bTreeUtils.js\";\n\nexport { cloneWithReplacements } from \"./cloneWithReplacements.js\";\n\nexport { readAndParseSnapshotBlob } from \"./readSnapshotBlob.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,uBAAuB,EAEvB,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,KAAK,EAEL,WAAW,EAGX,UAAU,EAEV,UAAU,EACV,OAAO,GACP,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EACN,WAAW,EACX,iBAAiB,GAGjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAGlB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,cAAc,EAAkB,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EAAmB,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAiBrE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACN,SAAS,EACT,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,eAAe,EAKf,4BAA4B,EAC5B,SAAS,EACT,WAAW,EACX,cAAc,EAId,gBAAgB,EAChB,gBAAgB,EAChB,4BAA4B,EAC5B,WAAW,EACX,SAAS,EACT,eAAe,EACf,aAAa,EAEb,UAAU,EACV,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,qBAAqB,EACrB,IAAI,EACJ,KAAK,EACL,OAAO,EACP,OAAO,EACP,SAAS,EACT,wBAAwB,EACxB,qBAAqB,IAAI,YAAY,EACrC,aAAa,EACb,eAAe,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAAyB,MAAM,wBAAwB,CAAC;AAcrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAIN,sBAAsB,EACtB,WAAW,GACX,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACN,QAAQ,EAER,kBAAkB,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAEN,oBAAoB,EACpB,oBAAoB,EAEpB,eAAe,GACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACN,SAAS,EAET,cAAc,EACd,aAAa,EACb,aAAa,GACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAEN,aAAa,EACb,gBAAgB,EAChB,qBAAqB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,EAIN,aAAa,EACb,0BAA0B,EAG1B,6BAA6B,EAC7B,6BAA6B,EAC7B,gCAAgC,EAChC,kCAAkC,EAClC,4BAA4B,GAC5B,MAAM,oBAAoB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport {\n\tcollectContiguousRanges,\n\ttype IndexRange,\n\tvalidateIndex,\n\tvalidateIndexRange,\n\tvalidatePositiveIndex,\n\tvalidateSafeInteger,\n} from \"./arrayUtilities.js\";\nexport {\n\tbrand,\n\ttype Brand,\n\tBrandedType,\n\ttype NameFromBranded,\n\ttype ValueFromBranded,\n\tbrandConst,\n\ttype Values,\n\tstrictEnum,\n\tunbrand,\n} from \"./brand.js\";\nexport { brandedNumberType, brandedStringType } from \"./typeboxBrand.js\";\nexport {\n\tbrandOpaque,\n\textractFromOpaque,\n\ttype ExtractFromOpaque,\n\ttype Opaque,\n} from \"./opaque.js\";\nexport {\n\tdeleteFromNestedMap,\n\tgetOrAddInNestedMap,\n\tgetOrDefaultInNestedMap,\n\tforEachInNestedMap,\n\ttype NestedMap,\n\ttype ReadonlyNestedMap,\n\tSizedNestedMap,\n\tpopulateNestedMap,\n\tsetInNestedMap,\n\ttryAddToNestedMap,\n\ttryGetFromNestedMap,\n\tmapNestedMap,\n\tnestedMapToFlatList,\n\tnestedMapFromFlatList,\n\tgetOrCreateInNestedMap,\n} from \"./nestedMap.js\";\nexport { addToNestedSet, type NestedSet, nestedSetContains } from \"./nestedSet.js\";\nexport { type OffsetList, OffsetListFactory } from \"./offsetList.js\";\nexport type {\n\tareSafelyAssignable,\n\tContravariant,\n\tCovariant,\n\teitherIsAny,\n\tEnforceTypeCheckTests,\n\tInvariant,\n\tisAny,\n\tisAssignableTo,\n\tisStrictSubset,\n\tMakeNominal,\n\trequireFalse,\n\trequireTrue,\n\trequireAssignableTo,\n\tareOnlyKeys,\n} from \"./typeCheck.js\";\nexport { StackyIterator } from \"./stackyIterator.js\";\nexport {\n\tasMutable,\n\tbalancedReduce,\n\tcompareSets,\n\tgetOrAddEmptyToMap,\n\tgetOrCreate,\n\tisJsonObject,\n\tisReadonlyArray,\n\ttype JsonCompatible,\n\ttype JsonCompatibleObject,\n\ttype JsonCompatibleReadOnly,\n\ttype JsonCompatibleReadOnlyObject,\n\tJsonCompatibleReadOnlySchema,\n\tmakeArray,\n\tmapIterable,\n\tfilterIterable,\n\ttype Mutable,\n\ttype Populated,\n\ttype RecursiveReadonly,\n\tassertValidIndex,\n\tassertValidRange,\n\tassertNonNegativeSafeInteger,\n\tobjectToMap,\n\tinvertMap,\n\toneFromIterable,\n\tdisposeSymbol,\n\ttype IDisposable,\n\tcapitalize,\n\tassertValidRangeIndices,\n\ttransformObjectMap,\n\tcompareNumbers,\n\tcomparePartialNumbers,\n\tcompareStrings,\n\tcomparePartialStrings,\n\tfind,\n\tcount,\n\tgetLast,\n\thasSome,\n\thasSingle,\n\tdefineLazyCachedProperty,\n\tcopyPropertyIfDefined as copyProperty,\n\tgetOrAddInMap,\n\titerableHasSome,\n} from \"./utils.js\";\nexport { ReferenceCountedBase, type ReferenceCounted } from \"./referenceCounting.js\";\n\nexport type {\n\t_RecursiveTrick,\n\tRestrictiveReadonlyRecord,\n\tRestrictiveStringRecord,\n\t_InlineTrick,\n\tFlattenKeys,\n\tIsUnion,\n\tUnionToIntersection,\n\tUnionToTuple,\n\tPopUnion,\n} from \"./typeUtils.js\";\n\nexport { unsafeArrayToTuple } from \"./typeUtils.js\";\n\nexport {\n\ttype BrandedKey,\n\ttype BrandedKeyContent,\n\ttype BrandedMapSubset,\n\tgetOrCreateSlotContent,\n\tbrandedSlot,\n} from \"./brandedMap.js\";\n\nexport {\n\tRangeMap,\n\ttype RangeQueryResult,\n\tnewIntegerRangeMap,\n} from \"./rangeMap.js\";\n\nexport {\n\ttype IdAllocator,\n\tidAllocatorFromMaxId,\n\tidAllocatorFromState,\n\ttype IdAllocationState,\n\tfakeIdAllocator,\n} from \"./idAllocator.js\";\n\nexport {\n\tBreakable,\n\ttype WithBreakable,\n\tbreakingMethod,\n\tthrowIfBroken,\n\tbreakingClass,\n} from \"./breakable.js\";\n\nexport {\n\ttype TupleBTree,\n\tnewTupleBTree,\n\tmergeTupleBTrees,\n\tcreateTupleComparator,\n} from \"./bTreeUtils.js\";\n\nexport { cloneWithReplacements } from \"./cloneWithReplacements.js\";\n\nexport { readAndParseSnapshotBlob } from \"./readSnapshotBlob.js\";\n\nexport {\n\ttype OriginatorlessEncodedId,\n\ttype OriginatorDependentEncodedId,\n\ttype IdentifierHealingConfig,\n\tEncodedIdType,\n\tencodePossiblyCompressedId,\n\ttype IdEncodingContext,\n\ttype EncodedId,\n\tdecodeOriginatorlessEncodedId,\n\tdecodeEncodedIdWithOriginator,\n\ttryDecodeEncodedIdWithoutSession,\n\tforceDecodeEncodedIdWithoutSession,\n\tdecompressIdentifierIfNeeded,\n} from \"./compressedIds.js\";\n"]}

package/lib/util/rangeMap.d.ts

@@ -93,6 +93,19 @@ export declare class RangeMap<K, V> {
      * By default, `mergeFunc` chooses the value from `b`.
      */
     static union<K, V>(a: RangeMap<K, V>, b: RangeMap<K, V>, mergeFunc?: (key: K, valueA: V, valueB: V) => V): RangeMap<K, V>;
+    /**
+     * Calls provided handlers on intersecting portions of `mapA` and `mapB`.
+     * @param intersectionCallback - called once for each key range which has an entry in both `mapA` and `mapB`.
+     * @param residualCallback - called for each key range which only has an entry in one of the input maps,
+     * but which is part of a range entry that overlaps an entry in the other map.
+     * This may also be called for entries which are not part of an overlapping range.
+     */
+    private static forEachIntersection;
+    private static getOrNextEntry;
+    /**
+     * @returns a range entry representing the first defined key range greater than or equal to `key`.
+     */
+    private getOrNextEntry;
     private getIntersectingEntries;
     private gt;
     private ge;

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

@@ -1 +1 @@
-{"version":3,"file":"rangeMap.d.ts","sourceRoot":"","sources":["../../src/util/rangeMap.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;;;;GAMG;AACH,qBAAa,QAAQ,CAAC,CAAC,EAAE,CAAC;aAqBR,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC;aACxC,YAAY,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM;aACpC,WAAW,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC;IAtB7D,OAAO,CAAC,IAAI,CAA0B;IAEtC;;;;;;;;;;;;;;;;OAgBG;gBAEc,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC,EACxC,YAAY,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,EACpC,WAAW,GAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,CAAwB;IAKpF;;OAEG;IACI,OAAO,IAAI,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;IAShC,KAAK,IAAI,IAAI;IAIpB;;;;;;;;OAQG;IACI,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,wBAAwB,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE;IAclF;;;;;;;OAOG;IACI,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,GAAG,SAAS,CAAC;IAqC1E;;;;;;OAMG;IACI,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,IAAI;IAOhE;;;;;;;;;;;;;;;;;;;;OAoBG;IACI,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAgCxC,KAAK,IAAI,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;IAM9B;;;;OAIG;WACW,KAAK,CAAC,CAAC,EAAE,CAAC,EACvB,CAAC,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EACjB,CAAC,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EACjB,SAAS,GAAE,CAAC,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAA0B,GACrE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;IAuBjB,OAAO,CAAC,sBAAsB;IAkC9B,OAAO,CAAC,EAAE;IAIV,OAAO,CAAC,EAAE;IAIV,OAAO,CAAC,EAAE;IAIV,OAAO,CAAC,EAAE;CAGV;AAiBD;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAElB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB,CAAC,CAAC,CAAE,SAAQ,gBAAgB,CAAC,CAAC,CAAC;IACvE;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,KAAK,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAEjF"}
+{"version":3,"file":"rangeMap.d.ts","sourceRoot":"","sources":["../../src/util/rangeMap.ts"],"names":[],"mappings":"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"}

package/lib/util/rangeMap.js

@@ -4,6 +4,8 @@
  */
 import { assert } from "@fluidframework/core-utils/internal";
 import { BTree } from "@tylerbu/sorted-btree-es6";
+// eslint-disable-next-line import-x/no-internal-modules
+import { union } from "@tylerbu/sorted-btree-es6/extended/union";
 /**
  * RangeMap represents a mapping from keys of type K to values of type V or undefined.
  * The set of all possible keys is assumed to be fully ordered,
@@ -183,16 +185,75 @@ export class RangeMap {
         assert(a.offsetKey === b.offsetKey &&
             a.subtractKeys === b.subtractKeys &&
             a.offsetValue === b.offsetValue, 0xaae /* Maps should have the same behavior */);
-        const merged = a.clone();
-        for (const entryB of b.entries()) {
-            for (const entryA of a.getAll(entryB.start, entryB.length)) {
-                const key = b.offsetKey(entryB.start, entryA.offset);
-                const valueB = b.offsetValue(entryB.value, entryA.offset);
-                const mergedValue = entryA.value === undefined ? valueB : mergeFunc(key, entryA.value, valueB);
-                merged.set(key, entryA.length, mergedValue);
+        const merged = new RangeMap(a.offsetKey, a.subtractKeys, a.offsetValue);
+        // We first union the underlying B-trees, possibly resulting in a malformed range map.
+        merged.tree = union(a.tree, b.tree, (key, v1, v2) => v1);
+        // We split the overlapping tree entries into ranges which are either fully overlapping (intersections),
+        // or fully non-overlapping (residuals).
+        // We create an entry for each of these ranges.
+        // After this, the merged map should be well-formed.
+        RangeMap.forEachIntersection(a, b, (key, length, valueA, valueB) => merged.tree.set(key, { value: mergeFunc(key, valueA, valueB), length }), (key, length, value) => merged.tree.set(key, { value, length }));
+        return merged;
+    }
+    /**
+     * Calls provided handlers on intersecting portions of `mapA` and `mapB`.
+     * @param intersectionCallback - called once for each key range which has an entry in both `mapA` and `mapB`.
+     * @param residualCallback - called for each key range which only has an entry in one of the input maps,
+     * but which is part of a range entry that overlaps an entry in the other map.
+     * This may also be called for entries which are not part of an overlapping range.
+     */
+    static forEachIntersection(mapA, mapB, intersectionCallback, residualCallback) {
+        let [entry1, map1, map2] = this.getOrNextEntry(mapA, mapB, undefined);
+        while (entry1 !== undefined) {
+            const entry2 = map2.getOrNextEntry(entry1.start);
+            if (entry2 !== undefined) {
+                // This is the number of keys in `entry1` that come before the first key in `entry2`.
+                const offset = Math.min(mapA.subtractKeys(entry2.start, entry1.start), entry1.length);
+                if (offset > 0) {
+                    residualCallback(entry1.start, offset, entry1.value);
+                }
+                const intersectionLength = Math.min(entry1.length - offset, entry2.length);
+                if (intersectionLength > 0) {
+                    const value1Offset = mapA.offsetValue(entry1.value, offset);
+                    const [valueA, valueB] = map1 === mapA ? [value1Offset, entry2.value] : [entry2.value, value1Offset];
+                    intersectionCallback(entry2.start, intersectionLength, valueA, valueB);
+                    [entry1, map1, map2] = this.getOrNextEntry(mapA, mapB, mapA.offsetKey(entry2.start, intersectionLength));
+                    continue;
+                }
             }
+            residualCallback(entry1.start, entry1.length, entry1.value);
+            [entry1, map1, map2] = this.getOrNextEntry(mapA, mapB, mapA.offsetKey(entry1.start, entry1.length));
         }
-        return merged;
+        return;
+    }
+    static getOrNextEntry(mapA, mapB, key) {
+        const entryA = mapA.getOrNextEntry(key);
+        const entryB = mapB.getOrNextEntry(key);
+        if (entryA === undefined) {
+            return [entryB, mapB, mapA];
+        }
+        else if (entryB === undefined) {
+            return [entryA, mapA, mapB];
+        }
+        return mapA.le(entryA.start, entryB.start) ? [entryA, mapA, mapB] : [entryB, mapB, mapA];
+    }
+    /**
+     * @returns a range entry representing the first defined key range greater than or equal to `key`.
+     */
+    getOrNextEntry(minKey) {
+        const key = minKey ?? this.tree.minKey();
+        if (key === undefined) {
+            return undefined;
+        }
+        const result = this.getFirst(key, Infinity);
+        if (result.value !== undefined) {
+            return { start: key, value: result.value, length: result.length };
+        }
+        const entry = this.tree.nextHigherPair(key);
+        if (entry === undefined) {
+            return undefined;
+        }
+        return { start: entry[0], value: entry[1].value, length: entry[1].length };
     }
     getIntersectingEntries(start, length) {
         const entries = [];