@fluidframework/tree 2.103.0 → 2.111.0

package/src/text/textDomainFormattedDefault.ts

@@ -0,0 +1,150 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+	enumFromStrings,
+	SchemaFactory,
+	SchemaFactoryAlpha,
+	SchemaFactoryBeta,
+} from "../simple-tree/index.js";
+import type {
+	TreeNodeFromImplicitAllowedTypes,
+	InsertableTreeNodeFromImplicitAllowedTypes,
+} from "../simple-tree/index.js";
+
+import { FormattedTextAsTree } from "./textDomainFormatted.js";
+
+/**
+ * Schema factory for default formatted text types which are not generic.
+ */
+const sf = new SchemaFactoryAlpha("com.fluidframework.text.formatted.default");
+
+const defaultFormat = {
+	bold: false,
+	italic: false,
+	underline: false,
+	size: 12,
+	font: "Arial",
+} as const;
+
+/**
+ * A collection of text related types, schema and utilities for working with text beyond the basic {@link SchemaStatics.string}.
+ * @remarks
+ * This is a default parameterization of the generic {@link FormattedTextAsTree} with hard-coded assumptions about what kind of embedded content and what kind of formatting is supported.
+ * It is unlikely this meets the needs of most users, but it can serve as an unstable example of how to use the generic {@link FormattedTextAsTree}.
+ * @internal
+ */
+export namespace FormattedTextAsTreeDefault {
+	/**
+	 * Portion of a string with formatting.
+	 * @sealed
+	 * @internal
+	 */
+	export type FormattedAtom = FormattedTextAsTree.FormattedAtom<
+		CharacterFormat,
+		StringAtomContent
+	>;
+
+	/**
+	 * Formatting options for characters.
+	 * @internal
+	 */
+	export class CharacterFormat extends sf.objectAlpha("CharacterFormat", {
+		bold: SchemaFactory.boolean,
+		italic: SchemaFactory.boolean,
+		underline: SchemaFactory.boolean,
+		size: SchemaFactory.number,
+		font: SchemaFactory.string,
+	}) {
+		public static readonly defaultFormat = new CharacterFormat(defaultFormat);
+	}
+
+	/**
+	 * Tag with which a line in text can be formatted from HTML.
+	 * @internal
+	 */
+	export const LineTag = enumFromStrings(sf.scopedFactory("lineTag"), [
+		"h1",
+		"h2",
+		"h3",
+		"h4",
+		"h5",
+		"li",
+		"ol",
+		"checked",
+		"unchecked",
+		"blockquote",
+		"codeBlock",
+	]);
+	/**
+	 * {@inheritdoc FormattedTextAsTreeDefault.(LineTag:variable)}
+	 * @internal
+	 */
+	export type LineTag = TreeNodeFromImplicitAllowedTypes<typeof LineTag.schema>;
+
+	/**
+	 * Unit in the string representing a new line character with line formatting.
+	 * @remarks
+	 * This aligns with how Quill represents line formatting.
+	 * Quill formats line attributes (headers, list, blockquote, etc... ) on the newline character
+	 * and only lines using this atom can have line-specific formatting.
+	 * The optional indent level mirrors Quill's indent attribute,
+	 * which is applies to the line before the line break.
+	 * Any tagged line can be indented independently.
+	 * @internal
+	 */
+	export class StringLineAtom extends sf.object("StringLineAtom", {
+		tag: LineTag.schema,
+		indent: SchemaFactory.number,
+	}) {
+		public readonly content = "\n";
+	}
+
+	/**
+	 * Types of "atoms" that make up the text.
+	 * @internal
+	 */
+	export const StringAtomContent = [
+		FormattedTextAsTree.StringTextAtom,
+		StringLineAtom,
+	] as const;
+	/**
+	 * {@inheritdoc FormattedTextAsTreeDefault.(StringAtomContent:variable)}
+	 * @internal
+	 */
+	export type StringAtomContent = TreeNodeFromImplicitAllowedTypes<typeof StringAtomContent>;
+
+	/**
+	 * Statics for text nodes.
+	 * @internal
+	 */
+	export type Statics<TTree = Tree> = FormattedTextAsTree.Statics<TTree>;
+
+	/**
+	 * Insertable shape for a formatted text atom used by {@link FormattedTextAsTree.Members.insertWithFormattingAt}.
+	 * @internal
+	 */
+	export type FormattedAtomInsertable = FormattedTextAsTree.FormattedAtom<
+		InsertableTreeNodeFromImplicitAllowedTypes<typeof CharacterFormat>,
+		InsertableTreeNodeFromImplicitAllowedTypes<FormattedTextAtoms>
+	>;
+
+	/**
+	 * Helper for expressing the full set of formatted text atoms for a given schema.
+	 * @privateRemarks
+	 * Eventually this should probably be given a better name and/or made a system type in a system namespace.
+	 * @internal
+	 */
+	export type FormattedTextAtoms = FormattedTextAsTree.FormattedTextAtoms<
+		[typeof StringLineAtom]
+	>;
+
+	export class Tree extends FormattedTextAsTree.createSchema(
+		new SchemaFactoryBeta("default"),
+		CharacterFormat,
+		[StringLineAtom],
+		defaultFormat,
+	) {}
+}

package/src/util/arrayUtilities.ts

@@ -86,3 +86,38 @@ export function validateIndexRange(
 	validateIndex(startIndex, array, apiName, true);
 	validateIndex(endIndex, array, apiName, true);
 }
+
+/**
+ * A half-open `[start, end)` range of array indices.
+ */
+export interface IndexRange {
+	/** Start index, inclusive. */
+	readonly start: number;
+	/** End index, exclusive. */
+	readonly end: number;
+}
+
+/**
+ * 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<T>(
+	array: { readonly length: number; readonly [index: number]: T },
+	shouldInclude: (item: T) => boolean,
+): readonly IndexRange[] {
+	const ranges: { start: number; end: number }[] = [];
+	for (let i = 0; i < array.length; i++) {
+		if (shouldInclude(array[i] as T)) {
+			const last = ranges[ranges.length - 1];
+			if (last?.end === i) {
+				last.end = i + 1;
+			} else {
+				ranges.push({ start: i, end: i + 1 });
+			}
+		}
+	}
+	return ranges;
+}

package/src/util/compressedIds.ts

@@ -0,0 +1,216 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+import type {
+	IIdCompressor,
+	OpSpaceCompressedId,
+	SessionId,
+	SessionSpaceCompressedId,
+} from "@fluidframework/id-compressor";
+import { isFinalId, isStableId } from "@fluidframework/id-compressor/internal";
+import { v5 as uuidV5 } from "uuid";
+
+/**
+ * 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 enum EncodedIdType {
+	/**
+	 * {@link OriginatorlessEncodedId}.
+	 */
+	Originatorless,
+	/**
+	 * {@link OriginatorDependentEncodedId}.
+	 */
+	OriginatorDependent,
+}
+
+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 function encodePossiblyCompressedId<T extends EncodedIdType>(
+	id: string,
+	idCompressor: IIdCompressor,
+	encodedIdType: T,
+): string | EncodedId<T> {
+	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 as unknown as EncodedId<T>) : id;
+	}
+	return opSpaceId as unknown as EncodedId<T>;
+}
+
+/**
+ * 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: OriginatorlessEncodedId,
+	idCompressor: IIdCompressor,
+): SessionSpaceCompressedId {
+	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: OriginatorDependentEncodedId,
+	originator: SessionId,
+	idCompressor: IIdCompressor,
+): SessionSpaceCompressedId {
+	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: OriginatorDependentEncodedId,
+	idCompressor: IIdCompressor,
+): SessionSpaceCompressedId | undefined {
+	return idCompressor.tryNormalizeToSessionSpaceWithoutSession(id);
+}
+
+/**
+ * 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 function forceDecodeEncodedIdWithoutSession(
+	id: OpSpaceCompressedId,
+	idCompressor: IIdCompressor,
+	healing: IdentifierHealingConfig | undefined,
+): SessionSpaceCompressedId | string {
+	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: SessionSpaceCompressedId | string,
+	idCompressor: Pick<IIdCompressor, "decompress">,
+): string {
+	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;
+	}
+}

package/src/util/index.ts

@@ -4,6 +4,8 @@
  */
 
 export {
+	collectContiguousRanges,
+	type IndexRange,
 	validateIndex,
 	validateIndexRange,
 	validatePositiveIndex,
@@ -163,3 +165,18 @@ export {
 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";

package/src/util/rangeMap.ts

@@ -5,6 +5,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.
@@ -215,19 +217,116 @@ export class RangeMap<K, V> {
 			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);
+		const merged = new RangeMap<K, V>(a.offsetKey, a.subtractKeys, a.offsetValue);
 
-				merged.set(key, entryA.length, mergedValue);
+		// We first union the underlying B-trees, possibly resulting in a malformed range map.
+		merged.tree = union<BTree<K, RangeEntry<V>>, K, RangeEntry<V>>(
+			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.
+	 */
+	private static forEachIntersection<K, V>(
+		mapA: RangeMap<K, V>,
+		mapB: RangeMap<K, V>,
+		intersectionCallback: (key: K, length: number, valueA: V, valueB: V) => void,
+		residualCallback: (key: K, length: number, value: V) => void,
+	): void {
+		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;
+	}
+
+	private static getOrNextEntry<K, V>(
+		mapA: RangeMap<K, V>,
+		mapB: RangeMap<K, V>,
+		key: K | undefined,
+	): [RangeMapEntry<K, V> | undefined, firstMap: RangeMap<K, V>, secondMap: RangeMap<K, V>] {
+		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`.
+	 */
+	private getOrNextEntry(minKey: K | undefined): RangeMapEntry<K, V> | undefined {
+		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 };
 	}
 
 	private getIntersectingEntries(start: K, length: number): RangeMapEntry<K, V>[] {

package/tsconfig.json

@@ -5,6 +5,11 @@
 	"compilerOptions": {
 		"rootDir": "./src",
 		"outDir": "./lib",
+		// Avoid emitting __classPrivateFieldGet/Set, __esDecorate, __runInitializers, etc.
+		// inline in every compiled module. Webpack's concatenateModules cannot dedupe these
+		// across modules (each gets unique scope-local var names), so without importHelpers
+		// the bundle accumulates ~17 copies of the same helpers (~1KB each).
+		"importHelpers": true,
 		"noImplicitAny": true,
 		"preserveConstEnums": true,
 		// Allow unused locals.