@fluidframework/sequence 2.0.0-dev.7.4.0.217212 → 2.0.0-dev.7.4.0.221926

package/src/intervalCollection.ts

@@ -87,7 +87,7 @@ import {
  * If a SequencePlace is the endpoint of a range (e.g. start/end of an interval or search range),
  * the Side value means it is exclusive if it is nearer to the other position and inclusive if it is farther.
  * E.g. the start of a range with Side.After is exclusive of the character at the position.
- * @internal
+ * @alpha
  */
 export type SequencePlace = number | "start" | "end" | InteriorSequencePlace;
 
@@ -95,7 +95,7 @@ export type SequencePlace = number | "start" | "end" | InteriorSequencePlace;
  * A sequence place that does not refer to the special endpoint segments.
  *
  * See {@link SequencePlace} for additional context.
- * @internal
+ * @alpha
  */
 export interface InteriorSequencePlace {
 	pos: number;
@@ -106,7 +106,7 @@ export interface InteriorSequencePlace {
  * Defines a side relative to a character in a sequence.
  *
  * @remarks See {@link SequencePlace} for additional context on usage.
- * @internal
+ * @alpha
  */
 export enum Side {
 	Before = 0,
@@ -626,7 +626,7 @@ export function makeOpsMap<T extends ISerializableInterval>(): Map<
 }
 
 /**
- * @internal
+ * @alpha
  */
 export type DeserializeCallback = (properties: PropertySet) => void;
 
@@ -665,7 +665,7 @@ class IntervalCollectionIterator<TInterval extends ISerializableInterval>
 
 /**
  * Change events emitted by `IntervalCollection`s
- * @internal
+ * @alpha
  */
 export interface IIntervalCollectionEvent<TInterval extends ISerializableInterval> extends IEvent {
 	/**
@@ -733,7 +733,7 @@ const isSequencePlace = (place: any): place is SequencePlace => {
 /**
  * Collection of intervals that supports addition, modification, removal, and efficient spatial querying.
  * Changes to this collection will be incur updates on collaborating clients (i.e. they are not local-only).
- * @internal
+ * @alpha
  */
 export interface IIntervalCollection<TInterval extends ISerializableInterval>
 	extends TypedEventEmitter<IIntervalCollectionEvent<TInterval>> {
@@ -865,6 +865,7 @@ export interface IIntervalCollection<TInterval extends ISerializableInterval>
 	removeIntervalById(id: string): TInterval | undefined;
 	/**
 	 * Changes the properties on an existing interval.
+	 * @deprecated - call change with the id and and object containing the new properties
 	 * @param id - Id of the interval whose properties should be changed
 	 * @param props - Property set to apply to the interval. Shallow merging is used between any existing properties
 	 * and `prop`, i.e. the interval will end up with a property object equivalent to `{ ...oldProps, ...props }`.
@@ -872,12 +873,25 @@ export interface IIntervalCollection<TInterval extends ISerializableInterval>
 	changeProperties(id: string, props: PropertySet);
 	/**
 	 * Changes the endpoints of an existing interval.
+	 * @deprecated - call change with the start and end parameters encapsulated in an object
 	 * @param id - Id of the interval to change
 	 * @param start - New start value. To leave the endpoint unchanged, pass the current value.
 	 * @param end - New end value. To leave the endpoint unchanged, pass the current value.
 	 * @returns the interval that was changed, if it existed in the collection.
 	 */
 	change(id: string, start: SequencePlace, end: SequencePlace): TInterval | undefined;
+	/**
+	 * Changes the endpoints, properties, or both of an existing interval.
+	 * @param id - Id of the Interval to change
+	 * @returns the interval that was changed, if it existed in the collection.
+	 * Pass the desired new start position, end position, and/or properties in an object. Start and end positions must be changed
+	 * simultaneously - they must either both be specified or both undefined. To only change the properties, leave both endpoints
+	 * undefined. To only change the endpoints, leave the properties undefined.
+	 */
+	change(
+		id: string,
+		{ start, end, props }: { start?: SequencePlace; end?: SequencePlace; props?: PropertySet },
+	): TInterval | undefined;
 
 	attachDeserializer(onDeserialize: DeserializeCallback): void;
 	/**
@@ -1390,70 +1404,83 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
 
 	/**
 	 * {@inheritdoc IIntervalCollection.changeProperties}
+	 * @deprecated - call change with the id and an object containing the new props values
 	 */
 	public changeProperties(id: string, props: PropertySet) {
-		if (!this.attached) {
-			throw new LoggingError("Attach must be called before accessing intervals");
-		}
-		if (typeof id !== "string") {
-			throw new LoggingError("Change API requires an ID that is a string");
-		}
-		if (!props) {
-			throw new LoggingError("changeProperties should be called with a property set");
-		}
-		// prevent the overwriting of an interval label, it should remain unchanged
-		// once it has been inserted into the collection.
-		if (props[reservedRangeLabelsKey] !== undefined) {
-			throw new LoggingError(
-				"The label property should not be modified once inserted to the collection",
-			);
-		}
-
-		const interval = this.getIntervalById(id);
-		if (interval) {
-			const deltaProps = interval.addProperties(
-				props,
-				true,
-				this.isCollaborating ? UnassignedSequenceNumber : UniversalSequenceNumber,
-			);
-			const serializedInterval: ISerializedInterval = interval.serialize();
-
-			// Emit a change op that will only change properties. Add the ID to
-			// the property bag provided by the caller.
-			serializedInterval.start = undefined as any;
-			serializedInterval.end = undefined as any;
-
-			serializedInterval.properties = props;
-			serializedInterval.properties[reservedIntervalIdKey] = interval.getIntervalId();
-			const localSeq = this.getNextLocalSeq();
-			this.localSeqToSerializedInterval.set(localSeq, serializedInterval);
-			this.emitter.emit("change", undefined, serializedInterval, { localSeq });
-			this.emit("propertyChanged", interval, deltaProps, true, undefined);
-		}
+		this.change(id, { props });
 	}
 
+	/**
+	 * {@inheritdoc IIntervalCollection.change}
+	 * @deprecated - call change with the id and an object containing the new start, end, and/or props values
+	 */
+	public change(id: string, start: SequencePlace, end: SequencePlace): TInterval | undefined;
 	/**
 	 * {@inheritdoc IIntervalCollection.change}
 	 */
-	public change(id: string, start: SequencePlace, end: SequencePlace) {
+	public change(
+		id: string,
+		{ start, end, props }: { start?: SequencePlace; end?: SequencePlace; props?: PropertySet },
+	): TInterval | undefined;
+	public change(
+		arg1: string,
+		arg2: SequencePlace | { start?: SequencePlace; end?: SequencePlace; props?: PropertySet },
+		arg3?: SequencePlace,
+	): TInterval | undefined {
+		const id: string = arg1;
+		let start: SequencePlace | undefined;
+		let end: SequencePlace | undefined;
+		let props: PropertySet | undefined;
+		if (isSequencePlace(arg2)) {
+			start = arg2;
+			end = arg3;
+		} else {
+			start = arg2.start;
+			end = arg2.end;
+			props = arg2.props;
+		}
+
 		if (!this.localCollection) {
 			throw new LoggingError("Attach must be called before accessing intervals");
 		}
 
 		// Force id to be a string.
 		if (typeof id !== "string") {
-			throw new LoggingError("Change API requires an ID that is a string");
+			throw new UsageError("Change API requires an ID that is a string");
+		}
+
+		// Ensure that both start and end are defined or both are undefined.
+		if ((start === undefined) !== (end === undefined)) {
+			throw new UsageError(
+				"Change API requires both start and end to be defined or undefined",
+			);
+		}
+
+		// prevent the overwriting of an interval label, it should remain unchanged
+		// once it has been inserted into the collection.
+		if (props?.[reservedRangeLabelsKey] !== undefined) {
+			throw new UsageError(
+				"The label property should not be modified once inserted to the collection",
+			);
 		}
 
 		const interval = this.getIntervalById(id);
 		if (interval) {
-			const newInterval = this.localCollection.changeInterval(interval, start, end);
-			if (!newInterval) {
-				return undefined;
+			let deltaProps: PropertySet | undefined;
+			let newInterval: TInterval | undefined;
+			if (props !== undefined) {
+				deltaProps = interval.addProperties(
+					props,
+					true,
+					this.isCollaborating ? UnassignedSequenceNumber : UniversalSequenceNumber,
+				);
 			}
-			if (!this.isCollaborating && newInterval instanceof SequenceInterval) {
-				setSlideOnRemove(newInterval.start);
-				setSlideOnRemove(newInterval.end);
+			if (start !== undefined && end !== undefined) {
+				newInterval = this.localCollection.changeInterval(interval, start, end);
+				if (!this.isCollaborating && newInterval instanceof SequenceInterval) {
+					setSlideOnRemove(newInterval.start);
+					setSlideOnRemove(newInterval.end);
+				}
 			}
 			const serializedInterval: SerializedIntervalDelta = interval.serialize();
 			const { startPos, startSide, endPos, endSide } = endpointPosAndSide(start, end);
@@ -1463,15 +1490,21 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
 			serializedInterval.startSide = startSide;
 			serializedInterval.endSide = endSide;
 			serializedInterval.stickiness = stickiness;
-			// Emit a property bag containing only the ID, as we don't intend for this op to change any properties.
+			// Emit a property bag containing the ID and the other (if any) properties changed
 			serializedInterval.properties = {
 				[reservedIntervalIdKey]: interval.getIntervalId(),
+				...props,
 			};
 			const localSeq = this.getNextLocalSeq();
 			this.localSeqToSerializedInterval.set(localSeq, serializedInterval);
 			this.emitter.emit("change", undefined, serializedInterval, { localSeq });
-			this.addPendingChange(id, serializedInterval);
-			this.emitChange(newInterval, interval, true, false);
+			if (deltaProps !== undefined) {
+				this.emit("propertyChanged", interval, deltaProps, true, undefined);
+			}
+			if (newInterval) {
+				this.addPendingChange(id, serializedInterval);
+				this.emitChange(newInterval, interval, true, false);
+			}
 			return newInterval;
 		}
 		// No interval to change

package/src/intervalIndex/intervalIndex.ts

@@ -13,7 +13,7 @@ import { ISerializableInterval } from "../intervals";
  * - "find all intervals with start endpoint between these two points"
  * - "find all intervals which overlap this range"
  * etc.
- * @internal
+ * @alpha
  */
 export interface IntervalIndex<TInterval extends ISerializableInterval> {
 	/**

package/src/intervals/intervalUtils.ts

@@ -17,7 +17,7 @@ import { SequencePlace, Side } from "../intervalCollection";
 
 /**
  * Basic interval abstraction
- * @internal
+ * @alpha
  */
 export interface IInterval {
 	/**
@@ -84,7 +84,7 @@ export const IntervalOpType = {
  */
 export type IntervalOpType = (typeof IntervalOpType)[keyof typeof IntervalOpType];
 /**
- * @internal
+ * @alpha
  */
 export enum IntervalType {
 	Simple = 0x0,
@@ -111,7 +111,7 @@ export enum IntervalType {
 /**
  * Serialized object representation of an interval.
  * This representation is used for ops that create or change intervals.
- * @internal
+ * @alpha
  */
 export interface ISerializedInterval {
 	/**
@@ -139,7 +139,7 @@ export interface ISerializedInterval {
 }
 
 /**
- * @internal
+ * @alpha
  */
 export interface ISerializableInterval extends IInterval {
 	/** Serializable bag of properties associated with the interval. */
@@ -240,7 +240,7 @@ export interface IIntervalHelpers<TInterval extends ISerializableInterval> {
  * Note that interval stickiness is currently an experimental feature and must
  * be explicitly enabled with the `intervalStickinessEnabled` flag
  *
- * @internal
+ * @alpha
  */
 export const IntervalStickiness = {
 	/**
@@ -272,8 +272,7 @@ export const IntervalStickiness = {
  *
  * Note that interval stickiness is currently an experimental feature and must
  * be explicitly enabled with the `intervalStickinessEnabled` flag
- *
- * @internal
+ * @alpha
  */
 export type IntervalStickiness = (typeof IntervalStickiness)[keyof typeof IntervalStickiness];
 

package/src/intervals/sequenceInterval.ts

@@ -100,7 +100,7 @@ function maxSide(sideA: Side, sideB: Side): Side {
  * `mergeTreeReferencesCanSlideToEndpoint` feature flag set to true, the endpoints
  * of the interval that are exclusive will have the ability to slide to these
  * special endpoint segments.
- * @internal
+ * @alpha
  */
 export class SequenceInterval implements ISerializableInterval {
 	/**

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/sequence";
-export const pkgVersion = "2.0.0-dev.7.4.0.217212";
+export const pkgVersion = "2.0.0-dev.7.4.0.221926";

package/src/sequence.ts

@@ -98,7 +98,7 @@ const contentPath = "content";
  * - `event` - Various information on the segments that were modified.
  *
  * - `target` - The sequence itself.
- * @internal
+ * @alpha
  */
 export interface ISharedSegmentSequenceEvents extends ISharedObjectEvents {
 	(
@@ -116,7 +116,7 @@ export interface ISharedSegmentSequenceEvents extends ISharedObjectEvents {
 }
 
 /**
- * @internal
+ * @alpha
  */
 export abstract class SharedSegmentSequence<T extends ISegment>
 	extends SharedObject<ISharedSegmentSequenceEvents>

package/src/sequenceDeltaEvent.ts

@@ -25,7 +25,7 @@ import {
  * The properties of this object and its sub-objects represent the state of the sequence at the
  * point in time at which the operation was applied.
  * They will not take into any future modifications performed to the underlying sequence and merge tree.
- * @internal
+ * @alpha
  */
 export abstract class SequenceEvent<
 	TOperation extends MergeTreeDeltaOperationTypes = MergeTreeDeltaOperationTypes,
@@ -108,7 +108,7 @@ export abstract class SequenceEvent<
  * For group ops, each op will get its own event, and the group op property will be set on the op args.
  *
  * Ops may get multiple events. For instance, an insert-replace will get a remove then an insert event.
- * @internal
+ * @alpha
  */
 export class SequenceDeltaEvent extends SequenceEvent<MergeTreeDeltaOperationType> {
 	/**
@@ -132,7 +132,7 @@ export class SequenceDeltaEvent extends SequenceEvent<MergeTreeDeltaOperationTyp
  * The properties of this object and its sub-objects represent the state of the sequence at the
  * point in time at which the operation was applied.
  * They will not take into consideration any future modifications performed to the underlying sequence and merge tree.
- * @internal
+ * @alpha
  */
 export class SequenceMaintenanceEvent extends SequenceEvent<MergeTreeMaintenanceType> {
 	constructor(
@@ -146,7 +146,7 @@ export class SequenceMaintenanceEvent extends SequenceEvent<MergeTreeMaintenance
 
 /**
  * A range that has changed corresponding to a segment modification.
- * @internal
+ * @alpha
  */
 export interface ISequenceDeltaRange<
 	TOperation extends MergeTreeDeltaOperationTypes = MergeTreeDeltaOperationTypes,

package/src/sequenceFactory.ts

@@ -14,7 +14,7 @@ import { pkgVersion } from "./packageVersion";
 import { SharedString, SharedStringSegment } from "./sharedString";
 
 /**
- * @internal
+ * @alpha
  */
 export class SharedStringFactory implements IChannelFactory {
 	// TODO rename back to https://graph.microsoft.com/types/mergeTree/string once paparazzi is able to dynamically

package/src/sharedIntervalCollection.ts

@@ -76,7 +76,7 @@ export class SharedIntervalCollectionFactory implements IChannelFactory {
 }
 
 /**
- * @internal
+ * @alpha
  */
 export interface ISharedIntervalCollection<TInterval extends ISerializableInterval> {
 	getIntervalCollection(label: string): IIntervalCollection<TInterval>;

package/src/sharedString.ts

@@ -24,7 +24,7 @@ import { SharedStringFactory } from "./sequenceFactory";
 
 /**
  * Fluid object interface describing access methods on a SharedString
- * @internal
+ * @alpha
  */
 export interface ISharedString extends SharedSegmentSequence<SharedStringSegment> {
 	/**
@@ -54,7 +54,7 @@ export interface ISharedString extends SharedSegmentSequence<SharedStringSegment
 }
 
 /**
- * @internal
+ * @alpha
  */
 export type SharedStringSegment = TextSegment | Marker;
 
@@ -66,7 +66,7 @@ export type SharedStringSegment = TextSegment | Marker;
  * In addition to text, a Shared String can also contain markers. Markers can be
  * used to store metadata at positions within the text, like the details of an
  * image or Fluid object that should be rendered with the text.
- * @internal
+ * @alpha
  */
 export class SharedString
 	extends SharedSegmentSequence<SharedStringSegment>