@fluidframework/sequence 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.224419

package/src/intervalIndex/startpointInRangeIndex.ts

@@ -0,0 +1,114 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/* eslint-disable import/no-deprecated */
+
+import { Client, PropertyAction, RedBlackTree } from "@fluidframework/merge-tree";
+import {
+	IIntervalHelpers,
+	ISerializableInterval,
+	IntervalType,
+	SequenceInterval,
+	sequenceIntervalHelpers,
+} from "../intervals";
+import { SharedString } from "../sharedString";
+import { IntervalIndex } from "./intervalIndex";
+import { HasComparisonOverride, compareOverrideables, forceCompare } from "./intervalIndexUtils";
+
+/**
+ * Collection of intervals.
+ *
+ * Provide additional APIs to support efficiently querying a collection of intervals whose startpoints fall within a specified range.
+ * @internal
+ */
+export interface IStartpointInRangeIndex<TInterval extends ISerializableInterval>
+	extends IntervalIndex<TInterval> {
+	/**
+	 * @returns an array of all intervals contained in this collection whose startpoints locate in the range [start, end] (includes both ends)
+	 */
+	findIntervalsWithStartpointInRange(start: number, end: number): TInterval[];
+}
+
+export class StartpointInRangeIndex<TInterval extends ISerializableInterval>
+	implements IStartpointInRangeIndex<TInterval>
+{
+	private readonly intervalTree;
+
+	constructor(
+		private readonly client: Client,
+		private readonly helpers: IIntervalHelpers<TInterval>,
+	) {
+		this.intervalTree = new RedBlackTree<TInterval, TInterval>((a: TInterval, b: TInterval) => {
+			const compareStartsResult = a.compareStart(b);
+			if (compareStartsResult !== 0) {
+				return compareStartsResult;
+			}
+
+			const overrideablesComparison = compareOverrideables(
+				a as Partial<HasComparisonOverride>,
+				b as Partial<HasComparisonOverride>,
+			);
+			if (overrideablesComparison !== 0) {
+				return overrideablesComparison;
+			}
+			const aId = a.getIntervalId();
+			const bId = b.getIntervalId();
+			if (aId !== undefined && bId !== undefined) {
+				return aId.localeCompare(bId);
+			}
+			return 0;
+		});
+	}
+
+	public add(interval: TInterval): void {
+		this.intervalTree.put(interval, interval);
+	}
+
+	public remove(interval: TInterval): void {
+		this.intervalTree.remove(interval);
+	}
+
+	public findIntervalsWithStartpointInRange(start: number, end: number): TInterval[] {
+		if (start <= 0 || start > end || this.intervalTree.isEmpty()) {
+			return [];
+		}
+		const results: TInterval[] = [];
+		const action: PropertyAction<TInterval, TInterval> = (node) => {
+			results.push(node.data);
+			return true;
+		};
+
+		const transientStartInterval = this.helpers.create(
+			"transient",
+			start,
+			start,
+			this.client,
+			IntervalType.Transient,
+		);
+
+		const transientEndInterval = this.helpers.create(
+			"transient",
+			end,
+			end,
+			this.client,
+			IntervalType.Transient,
+		);
+
+		// Add comparison overrides to the transient intervals
+		(transientStartInterval as Partial<HasComparisonOverride>)[forceCompare] = -1;
+		(transientEndInterval as Partial<HasComparisonOverride>)[forceCompare] = 1;
+
+		this.intervalTree.mapRange(action, results, transientStartInterval, transientEndInterval);
+		return results;
+	}
+}
+/**
+ * @internal
+ */
+export function createStartpointInRangeIndex(
+	sharedString: SharedString,
+): IStartpointInRangeIndex<SequenceInterval> {
+	const client = (sharedString as unknown as { client: Client }).client;
+	return new StartpointInRangeIndex<SequenceInterval>(client, sequenceIntervalHelpers);
+}

package/src/intervalTree.ts

@@ -0,0 +1,98 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+	RBNode,
+	IRBAugmentation,
+	IRBMatcher,
+	RedBlackTree,
+	RBNodeActions,
+} from "@fluidframework/merge-tree";
+import { IInterval } from "./intervals";
+
+export interface AugmentedIntervalNode {
+	minmax: IInterval;
+}
+
+const intervalComparer = (a: IInterval, b: IInterval) => a.compare(b);
+
+export type IntervalNode<T extends IInterval> = RBNode<T, AugmentedIntervalNode>;
+
+export class IntervalTree<T extends IInterval>
+	implements IRBAugmentation<T, AugmentedIntervalNode>, IRBMatcher<T, AugmentedIntervalNode>
+{
+	public intervals = new RedBlackTree<T, AugmentedIntervalNode>(intervalComparer, this);
+
+	public remove(x: T) {
+		this.intervals.remove(x);
+	}
+
+	public removeExisting(x: T) {
+		this.intervals.removeExisting(x);
+	}
+
+	public put(x: T) {
+		this.intervals.put(x, { minmax: x.clone() });
+	}
+
+	public map(fn: (x: T) => void) {
+		const actions: RBNodeActions<T, AugmentedIntervalNode> = {
+			infix: (node) => {
+				fn(node.key);
+				return true;
+			},
+			showStructure: true,
+		};
+		this.intervals.walk(actions);
+	}
+
+	public mapUntil(fn: (X: T) => boolean) {
+		const actions: RBNodeActions<T, AugmentedIntervalNode> = {
+			infix: (node) => {
+				return fn(node.key);
+			},
+			showStructure: true,
+		};
+		this.intervals.walk(actions);
+	}
+
+	public mapBackward(fn: (x: T) => void) {
+		const actions: RBNodeActions<T, AugmentedIntervalNode> = {
+			infix: (node) => {
+				fn(node.key);
+				return true;
+			},
+			showStructure: true,
+		};
+		this.intervals.walkBackward(actions);
+	}
+
+	// TODO: toString()
+	public match(x: T) {
+		return this.intervals.gather(x, this);
+	}
+
+	public matchNode(node: IntervalNode<T> | undefined, key: T) {
+		return !!node && node.key.overlaps(key);
+	}
+
+	public continueSubtree(node: IntervalNode<T> | undefined, key: T) {
+		return !!node && node.data.minmax.overlaps(key);
+	}
+
+	public update(node: IntervalNode<T>) {
+		if (node.left && node.right) {
+			node.data.minmax = node.key.union(node.left.data.minmax.union(node.right.data.minmax));
+		} else {
+			if (node.left) {
+				node.data.minmax = node.key.union(node.left.data.minmax);
+			} else if (node.right) {
+				node.data.minmax = node.key.union(node.right.data.minmax);
+			} else {
+				node.data.minmax = node.key.clone();
+			}
+		}
+	}
+}

package/src/intervals/index.ts

@@ -0,0 +1,25 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export {
+	IInterval,
+	ISerializedInterval,
+	ISerializableInterval,
+	IntervalOpType,
+	IntervalType,
+	IIntervalHelpers,
+	IntervalStickiness,
+	SerializedIntervalDelta,
+	CompressedSerializedInterval,
+	endReferenceSlidingPreference,
+	startReferenceSlidingPreference,
+} from "./intervalUtils";
+export { Interval, createInterval, intervalHelpers } from "./interval";
+export {
+	SequenceInterval,
+	createSequenceInterval,
+	createPositionReferenceFromSegoff,
+	sequenceIntervalHelpers,
+} from "./sequenceInterval";

package/src/intervals/interval.ts

@@ -0,0 +1,238 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/* eslint-disable import/no-deprecated */
+
+import {
+	PropertiesManager,
+	PropertySet,
+	createMap,
+	reservedRangeLabelsKey,
+} from "@fluidframework/merge-tree";
+import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
+import { assert } from "@fluidframework/core-utils";
+import { UsageError } from "@fluidframework/telemetry-utils";
+import { SequencePlace } from "../intervalCollection";
+import { IIntervalHelpers, ISerializableInterval, ISerializedInterval } from "./intervalUtils";
+
+const reservedIntervalIdKey = "intervalId";
+
+/**
+ * Serializable interval whose endpoints are plain-old numbers.
+ * @internal
+ */
+export class Interval implements ISerializableInterval {
+	/**
+	 * {@inheritDoc ISerializableInterval.properties}
+	 */
+	public properties: PropertySet = createMap<any>();
+
+	/***/
+	public auxProps: PropertySet[] | undefined;
+
+	/**
+	 * {@inheritDoc ISerializableInterval.propertyManager}
+	 */
+	public readonly propertyManager: PropertiesManager = new PropertiesManager();
+
+	constructor(
+		public start: number,
+		public end: number,
+		props?: PropertySet,
+	) {
+		if (props) {
+			this.addProperties(props);
+		}
+	}
+
+	/**
+	 * {@inheritDoc ISerializableInterval.getIntervalId}
+	 */
+	public getIntervalId(): string {
+		const id = this.properties?.[reservedIntervalIdKey];
+		assert(id !== undefined, 0x5e1 /* interval ID should not be undefined */);
+		return `${id}`;
+	}
+
+	/**
+	 * @returns an array containing any auxiliary property sets added with `addPropertySet`.
+	 */
+	public getAdditionalPropertySets(): PropertySet[] {
+		return this.auxProps ?? [];
+	}
+
+	/**
+	 * Adds an auxiliary set of properties to this interval.
+	 * These properties can be recovered using `getAdditionalPropertySets`
+	 * @param props - set of properties to add
+	 * @remarks This gets called as part of the default conflict resolver for `IIntervalCollection<Interval>`
+	 * (i.e. non-sequence-based interval collections). However, the additional properties don't get serialized.
+	 * This functionality seems half-baked.
+	 */
+	public addPropertySet(props: PropertySet) {
+		if (this.auxProps === undefined) {
+			this.auxProps = [];
+		}
+		this.auxProps.push(props);
+	}
+
+	/**
+	 * {@inheritDoc ISerializableInterval.serialize}
+	 */
+	public serialize(): ISerializedInterval {
+		const serializedInterval: ISerializedInterval = {
+			end: this.end,
+			intervalType: 0,
+			sequenceNumber: 0,
+			start: this.start,
+		};
+		if (this.properties) {
+			serializedInterval.properties = this.properties;
+		}
+		return serializedInterval;
+	}
+
+	/**
+	 * {@inheritDoc IInterval.clone}
+	 */
+	public clone() {
+		return new Interval(this.start, this.end, this.properties);
+	}
+
+	/**
+	 * {@inheritDoc IInterval.compare}
+	 */
+	public compare(b: Interval) {
+		const startResult = this.compareStart(b);
+		if (startResult === 0) {
+			const endResult = this.compareEnd(b);
+			if (endResult === 0) {
+				const thisId = this.getIntervalId();
+				if (thisId) {
+					const bId = b.getIntervalId();
+					if (bId) {
+						return thisId > bId ? 1 : thisId < bId ? -1 : 0;
+					}
+					return 0;
+				}
+				return 0;
+			} else {
+				return endResult;
+			}
+		} else {
+			return startResult;
+		}
+	}
+
+	/**
+	 * {@inheritDoc IInterval.compareStart}
+	 */
+	public compareStart(b: Interval) {
+		return this.start - b.start;
+	}
+
+	/**
+	 * {@inheritDoc IInterval.compareEnd}
+	 */
+	public compareEnd(b: Interval) {
+		return this.end - b.end;
+	}
+
+	/**
+	 * {@inheritDoc IInterval.overlaps}
+	 */
+	public overlaps(b: Interval) {
+		const result = this.start <= b.end && this.end >= b.start;
+		return result;
+	}
+
+	/**
+	 * {@inheritDoc IInterval.union}
+	 */
+	public union(b: Interval) {
+		return new Interval(
+			Math.min(this.start, b.start),
+			Math.max(this.end, b.end),
+			this.properties,
+		);
+	}
+
+	public getProperties() {
+		return this.properties;
+	}
+
+	/**
+	 * {@inheritDoc ISerializableInterval.addProperties}
+	 */
+	public addProperties(
+		newProps: PropertySet,
+		collaborating: boolean = false,
+		seq?: number,
+	): PropertySet | undefined {
+		if (newProps) {
+			return this.propertyManager.addProperties(
+				this.properties,
+				newProps,
+				seq,
+				collaborating,
+			);
+		}
+	}
+
+	/**
+	 * {@inheritDoc IInterval.modify}
+	 */
+	public modify(
+		label: string,
+		start?: SequencePlace,
+		end?: SequencePlace,
+		op?: ISequencedDocumentMessage,
+	) {
+		if (typeof start === "string" || typeof end === "string") {
+			throw new UsageError(
+				"The start and end positions of a plain interval may not be on the special endpoint segments.",
+			);
+		}
+
+		const startPos = typeof start === "number" ? start : start?.pos ?? this.start;
+		const endPos = typeof end === "number" ? end : end?.pos ?? this.end;
+
+		if (this.start === startPos && this.end === endPos) {
+			// Return undefined to indicate that no change is necessary.
+			return;
+		}
+		const newInterval = new Interval(startPos, endPos);
+		if (this.properties) {
+			this.propertyManager.copyTo(
+				this.properties,
+				newInterval.properties,
+				newInterval.propertyManager,
+			);
+		}
+		return newInterval;
+	}
+}
+
+export function createInterval(label: string, start: SequencePlace, end: SequencePlace): Interval {
+	if (typeof start === "string" || typeof end === "string") {
+		throw new UsageError(
+			"The start and end positions of a plain interval may not be on the special endpoint segments.",
+		);
+	}
+
+	const rangeProp: PropertySet = {};
+
+	if (label && label.length > 0) {
+		rangeProp[reservedRangeLabelsKey] = [label];
+	}
+
+	const startPos = typeof start === "number" ? start : start.pos;
+	const endPos = typeof end === "number" ? end : end.pos;
+
+	return new Interval(startPos, endPos, rangeProp);
+}
+
+export const intervalHelpers: IIntervalHelpers<Interval> = {
+	create: createInterval,
+};