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

package/src/defaultMapInterfaces.ts

@@ -5,44 +5,82 @@
 
 import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
 import { ISharedObjectEvents } from "@fluidframework/shared-object-base";
-import { IEventThisPlaceHolder } from "@fluidframework/common-definitions";
+import { IEventThisPlaceHolder } from "@fluidframework/core-interfaces";
+import { ISerializedInterval, IntervalOpType, SerializedIntervalDelta } from "./intervals";
 
 /**
  * Type of "valueChanged" event parameter.
  */
 export interface IValueChanged {
-    /**
-     * The key storing the value that changed.
-     */
-    key: string;
-
-    /**
-     * The value that was stored at the key prior to the change.
-     */
-    previousValue: any;
+	/**
+	 * The key storing the value that changed.
+	 */
+	key: string;
+
+	/**
+	 * The value that was stored at the key prior to the change.
+	 */
+	previousValue: any;
 }
 
 /**
  * Value types are given an IValueOpEmitter to emit their ops through the container type that holds them.
  * @internal
+ * @deprecated - will be remove from public api as there is no public used of this type
  */
 export interface IValueOpEmitter {
-    /**
-     * Called by the value type to emit a value type operation through the container type holding it.
-     * @param opName - Name of the emitted operation
-     * @param previousValue - JSONable previous value as defined by the value type
-     * @param params - JSONable params for the operation as defined by the value type
-     * @param localOpMetadata - JSONable local metadata which should be submitted with the op
-     * @internal
-     */
-    emit(opName: string, previousValue: any, params: any, localOpMetadata: IMapMessageLocalMetadata): void;
+	/**
+	 * Called by the value type to emit a value type operation through the container type holding it.
+	 * @param opName - Name of the emitted operation
+	 * @param previousValue - JSONable previous value as defined by the value type @deprecated unused
+	 * @param params - JSONable params for the operation as defined by the value type
+	 * @param localOpMetadata - JSONable local metadata which should be submitted with the op
+	 */
+	emit(
+		opName: IntervalOpType,
+		previousValue: undefined,
+		params: SerializedIntervalDelta,
+		localOpMetadata: IMapMessageLocalMetadata,
+	): void;
 }
 
 /**
  * @internal
  */
 export interface IMapMessageLocalMetadata {
-    localSeq: number;
+	localSeq: number;
+}
+
+/**
+ * Optional flags that configure options for sequence DDSs
+ * @internal
+ */
+export interface SequenceOptions {
+	/**
+	 * Enable the ability to use interval APIs that rely on positions before and
+	 * after individual characters, referred to as "sides". See {@link SequencePlace}
+	 * for additional context.
+	 *
+	 * This flag must be enabled to pass instances of {@link SequencePlace} to
+	 * any IIntervalCollection API.
+	 *
+	 * Also see the feature flag `mergeTreeReferencesCanSlideToEndpoint` to allow
+	 * endpoints to slide to the special endpoint segments.
+	 *
+	 * The default value is false.
+	 */
+	intervalStickinessEnabled: boolean;
+	/**
+	 * Enable the ability for interval endpoints to slide to the special endpoint
+	 * segments that exist before and after the bounds of the string. This is
+	 * primarily useful for workflows involving interval stickiness, and it is
+	 * suggested to enable both this flag and `intervalStickinessEnabled` at the
+	 * same time.
+	 *
+	 * The default value is false.
+	 */
+	mergeTreeReferencesCanSlideToEndpoint: boolean;
+	[key: string]: boolean;
 }
 
 /**
@@ -50,24 +88,24 @@ export interface IMapMessageLocalMetadata {
  * @alpha
  */
 export interface IValueFactory<T> {
-    /**
-     * Create a new value type.  Used both in creation of new value types, as well as in loading existing ones
-     * from remote.
-     * @param emitter - Emitter object that the created value type will use to emit operations
-     * @param raw - Initialization parameters as defined by the value type
-     * @returns The new value type
-     * @alpha
-     */
-    load(emitter: IValueOpEmitter, raw: any): T;
-
-    /**
-     * Given a value type, provides a JSONable form of its data to be used for snapshotting.  This data must be
-     * loadable using the load method of its factory.
-     * @param value - The value type to serialize
-     * @returns The JSONable form of the value type
-     * @alpha
-     */
-    store(value: T): any;
+	/**
+	 * Create a new value type.  Used both in creation of new value types, as well as in loading existing ones
+	 * from remote.
+	 * @param emitter - Emitter object that the created value type will use to emit operations
+	 * @param raw - Initialization parameters as defined by the value type
+	 * @returns The new value type
+	 * @alpha
+	 */
+	load(emitter: IValueOpEmitter, raw: any, options?: Partial<SequenceOptions>): T;
+
+	/**
+	 * Given a value type, provides a JSONable form of its data to be used for snapshotting.  This data must be
+	 * loadable using the load method of its factory.
+	 * @param value - The value type to serialize
+	 * @returns The JSONable form of the value type
+	 * @alpha
+	 */
+	store(value: T): any;
 }
 
 /**
@@ -75,66 +113,68 @@ export interface IValueFactory<T> {
  * @alpha
  */
 export interface IValueOperation<T> {
-    /**
-     * Performs the actual processing on the incoming operation.
-     * @param value - The current value stored at the given key, which should be the value type
-     * @param params - The params on the incoming operation
-     * @param local - Whether the operation originated from this client
-     * @param message - The operation itself
-     * @param localOpMetadata - any local metadata submitted by `IValueOpEmitter.emit`.
-     * @alpha
-     */
-    process(
-        value: T,
-        params: any,
-        local: boolean,
-        message: ISequencedDocumentMessage | undefined,
-        localOpMetadata: IMapMessageLocalMetadata | undefined
-    );
-
-    /**
-     * Rebases an `op` on `value` from its original perspective (ref/local seq) to the current
-     * perspective. Should be invoked on reconnection.
-     * @param value - The current value stored at the given key, which should be the value type.
-     * @param op - The op to be rebased.
-     * @param localOpMetadata - Any local metadata that was originally submitted with the op.
-     * @returns A rebased version of the op and any local metadata that should be submitted with it.
-     */
-    rebase(
-        value: T,
-        op: IValueTypeOperationValue,
-        localOpMetadata: IMapMessageLocalMetadata
-    ): { rebasedOp: IValueTypeOperationValue; rebasedLocalOpMetadata: IMapMessageLocalMetadata; };
+	/**
+	 * Performs the actual processing on the incoming operation.
+	 * @param value - The current value stored at the given key, which should be the value type
+	 * @param params - The params on the incoming operation
+	 * @param local - Whether the operation originated from this client
+	 * @param message - The operation itself
+	 * @param localOpMetadata - any local metadata submitted by `IValueOpEmitter.emit`.
+	 * @alpha
+	 */
+	process(
+		value: T,
+		params: ISerializedInterval,
+		local: boolean,
+		message: ISequencedDocumentMessage | undefined,
+		localOpMetadata: IMapMessageLocalMetadata | undefined,
+	): void;
+
+	/**
+	 * Rebases an `op` on `value` from its original perspective (ref/local seq) to the current
+	 * perspective. Should be invoked on reconnection.
+	 * @param value - The current value stored at the given key, which should be the value type.
+	 * @param op - The op to be rebased.
+	 * @param localOpMetadata - Any local metadata that was originally submitted with the op.
+	 * @returns A rebased version of the op and any local metadata that should be submitted with it.
+	 */
+	rebase(
+		value: T,
+		op: IValueTypeOperationValue,
+		localOpMetadata: IMapMessageLocalMetadata,
+	):
+		| { rebasedOp: IValueTypeOperationValue; rebasedLocalOpMetadata: IMapMessageLocalMetadata }
+		| undefined;
 }
 
 /**
  * Defines a value type that can be registered on a container type.
  */
 export interface IValueType<T> {
-    /**
-     * Name of the value type.
-     * @alpha
-     */
-    name: string;
-
-    /**
-     * Factory method used to convert to/from a JSON form of the type.
-     * @alpha
-     */
-    factory: IValueFactory<T>;
-
-    /**
-     * Operations that can be applied to the value type.
-     * @alpha
-     */
-    ops: Map<string, IValueOperation<T>>;
+	/**
+	 * Name of the value type.
+	 * @alpha
+	 */
+	name: string;
+
+	/**
+	 * Factory method used to convert to/from a JSON form of the type.
+	 * @alpha
+	 */
+	factory: IValueFactory<T>;
+
+	/**
+	 * Operations that can be applied to the value type.
+	 * @alpha
+	 */
+	ops: Map<IntervalOpType, IValueOperation<T>>;
 }
 
 export interface ISharedDefaultMapEvents extends ISharedObjectEvents {
-    (event: "valueChanged" | "create", listener: (
-        changed: IValueChanged,
-        local: boolean,
-        target: IEventThisPlaceHolder) => void);
+	(
+		event: "valueChanged" | "create",
+		listener: (changed: IValueChanged, local: boolean, target: IEventThisPlaceHolder) => void,
+	): void;
 }
 
 /**
@@ -145,31 +185,31 @@ export interface ISharedDefaultMapEvents extends ISharedObjectEvents {
  * JSON.stringify and comes out of JSON.parse. This format is used both for snapshots (loadCore/populate)
  * and ops (set).
  *
- * The DefaultMap impelmentation for sequence has been specialized to only support a single ValueType, which serializes
+ * The DefaultMap implementation for sequence has been specialized to only support a single ValueType, which serializes
  * and deserializes via .store() and .load().
  */
 export interface ISerializableValue {
-    /**
-     * A type annotation to help indicate how the value serializes.
-     */
-    type: string;
-
-    /**
-     * The JSONable representation of the value.
-     */
-    value: any;
+	/**
+	 * A type annotation to help indicate how the value serializes.
+	 */
+	type: string;
+
+	/**
+	 * The JSONable representation of the value.
+	 */
+	value: any;
 }
 
 export interface ISerializedValue {
-    /**
-     * A type annotation to help indicate how the value serializes.
-     */
-    type: string;
-
-    /**
-     * String representation of the value.
-     */
-    value: string | undefined;
+	/**
+	 * A type annotation to help indicate how the value serializes.
+	 */
+	type: string;
+
+	/**
+	 * String representation of the value.
+	 */
+	value: string | undefined;
 }
 
 /**
@@ -182,13 +222,13 @@ export interface ISerializedValue {
  * @alpha
  */
 export interface IValueTypeOperationValue {
-    /**
-     * The name of the operation.
-     */
-    opName: string;
-
-    /**
-     * The payload that is submitted along with the operation.
-     */
-    value: any;
+	/**
+	 * The name of the operation.
+	 */
+	opName: IntervalOpType;
+
+	/**
+	 * The payload that is submitted along with the operation.
+	 */
+	value: SerializedIntervalDelta;
 }

package/src/index.ts

@@ -6,39 +6,99 @@
 /**
  * Supports distributed data structures which are list-like.
  *
- * This package's main export is {@link SharedSequence}, a DDS for storing and simultaneously editing a sequence of
+ * This library's main export is {@link SharedString}, a DDS for storing and simultaneously editing a sequence of
  * text.
  *
+ * See the package's README for a high-level introduction to `SharedString`'s feature set.
  * @remarks Note that SharedString is a sequence DDS but it has additional specialized features and behaviors for
  * working with text.
  *
  * @packageDocumentation
  */
-
+export { IMapMessageLocalMetadata, IValueOpEmitter, SequenceOptions } from "./defaultMapInterfaces";
+export {
+	IInterval,
+	Interval,
+	IntervalOpType,
+	IntervalType,
+	ISerializableInterval,
+	ISerializedInterval,
+	SequenceInterval,
+	SerializedIntervalDelta,
+	IntervalStickiness,
+	IIntervalHelpers,
+	sequenceIntervalHelpers,
+} from "./intervals";
 export {
-    DeserializeCallback,
-    IIntervalCollectionEvent,
-    IIntervalHelpers,
-    Interval,
-    IntervalCollection,
-    IntervalCollectionIterator,
-    IntervalType,
-    ISerializableInterval,
-    ISerializedInterval,
-    SequenceInterval,
-    ISerializedIntervalCollectionV2,
-    CompressedSerializedInterval,
+	DeserializeCallback,
+	IIntervalCollectionEvent,
+	IIntervalCollection,
+	IntervalLocator,
+	intervalLocatorFromEndpoint,
+	Side,
+	InteriorSequencePlace,
+	SequencePlace,
 } from "./intervalCollection";
 export {
-    IMapMessageLocalMetadata,
-    IValueOpEmitter,
-} from "./defaultMapInterfaces";
-export * from "./sharedString";
-export * from "./sequence";
-export * from "./sequenceFactory";
-export * from "./sequenceDeltaEvent";
-export * from "./sharedSequence";
-export * from "./sharedObjectSequence";
-export * from "./sharedNumberSequence";
-export * from "./sparsematrix";
-export * from "./sharedIntervalCollection";
+	IntervalIndex,
+	SequenceIntervalIndexes,
+	IOverlappingIntervalsIndex,
+	createOverlappingIntervalsIndex,
+	createOverlappingSequenceIntervalsIndex,
+	IEndpointInRangeIndex,
+	IStartpointInRangeIndex,
+	createEndpointInRangeIndex,
+	createStartpointInRangeIndex,
+	IIdIntervalIndex,
+	createIdIntervalIndex,
+	IEndpointIndex,
+	createEndpointIndex,
+} from "./intervalIndex";
+export {
+	appendAddIntervalToRevertibles,
+	appendChangeIntervalToRevertibles,
+	appendDeleteIntervalToRevertibles,
+	appendIntervalPropertyChangedToRevertibles,
+	appendSharedStringDeltaToRevertibles,
+	discardSharedStringRevertibles,
+	IntervalRevertible,
+	revertSharedStringRevertibles,
+	SharedStringRevertible,
+} from "./revertibles";
+export { ISharedSegmentSequenceEvents, SharedSegmentSequence } from "./sequence";
+export {
+	ISequenceDeltaRange,
+	SequenceDeltaEvent,
+	SequenceEvent,
+	SequenceMaintenanceEvent,
+} from "./sequenceDeltaEvent";
+export { SharedStringFactory } from "./sequenceFactory";
+export {
+	getTextAndMarkers,
+	ISharedString,
+	SharedString,
+	SharedStringSegment,
+} from "./sharedString";
+export {
+	ISharedIntervalCollection,
+	SharedIntervalCollection,
+	SharedIntervalCollectionFactory,
+} from "./sharedIntervalCollection";
+export { IJSONRunSegment, SharedSequence, SubSequence } from "./sharedSequence";
+
+export {
+	ISegment,
+	Marker,
+	BaseSegment,
+	ReferencePosition,
+	ReferenceType,
+	PropertySet,
+	MapLike,
+	TextSegment,
+	MergeTreeDeltaType,
+	reservedMarkerIdKey,
+	reservedTileLabelsKey,
+	reservedRangeLabelsKey,
+	TrackingGroup,
+	LocalReferencePosition,
+} from "@fluidframework/merge-tree";