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

package/src/sequenceDeltaEvent.ts

@@ -3,18 +3,20 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/common-utils";
+import { assert } from "@fluidframework/core-utils";
 import {
-    Client,
-    IMergeTreeDeltaCallbackArgs,
-    IMergeTreeDeltaOpArgs,
-    IMergeTreeMaintenanceCallbackArgs,
-    ISegment,
-    MergeTreeDeltaOperationType,
-    MergeTreeDeltaOperationTypes,
-    MergeTreeMaintenanceType,
-    PropertySet,
-    SortedSegmentSet,
+	// eslint-disable-next-line import/no-deprecated
+	Client,
+	IMergeTreeDeltaCallbackArgs,
+	IMergeTreeDeltaOpArgs,
+	IMergeTreeMaintenanceCallbackArgs,
+	ISegment,
+	MergeTreeDeltaOperationType,
+	MergeTreeDeltaOperationTypes,
+	MergeTreeMaintenanceType,
+	PropertySet,
+	// eslint-disable-next-line import/no-deprecated
+	SortedSegmentSet,
 } from "@fluidframework/merge-tree";
 
 /**
@@ -23,79 +25,81 @@ 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.
+ * @alpha
  */
-export abstract class SequenceEvent<TOperation extends MergeTreeDeltaOperationTypes = MergeTreeDeltaOperationTypes> {
-    /**
-     * @deprecated - Events no longer fire when the change they correspond to had no impact (e.g. a remote delete
-     * event for a range that had already been deleted locally).
-     * Clients can therefore assume this property is false.
-     */
-    public readonly isEmpty: boolean;
-    public readonly deltaOperation: TOperation;
-    private readonly sortedRanges: Lazy<SortedSegmentSet<ISequenceDeltaRange<TOperation>>>;
-    private readonly pFirst: Lazy<ISequenceDeltaRange<TOperation>>;
-    private readonly pLast: Lazy<ISequenceDeltaRange<TOperation>>;
-
-    constructor(
-        public readonly deltaArgs: IMergeTreeDeltaCallbackArgs<TOperation>,
-        private readonly mergeTreeClient: Client,
-    ) {
-        assert(deltaArgs.deltaSegments.length > 0, 0x2d8 /* "Empty change event should not be emitted." */);
-        this.isEmpty = false;
-        this.deltaOperation = deltaArgs.operation;
-
-        this.sortedRanges = new Lazy<SortedSegmentSet<ISequenceDeltaRange<TOperation>>>(
-            () => {
-                const set = new SortedSegmentSet<ISequenceDeltaRange<TOperation>>();
-                this.deltaArgs.deltaSegments.forEach((delta) => {
-                    const newRange: ISequenceDeltaRange<TOperation> = {
-                        operation: this.deltaArgs.operation,
-                        position: this.mergeTreeClient.getPosition(delta.segment),
-                        propertyDeltas: delta.propertyDeltas,
-                        segment: delta.segment,
-                    };
-                    set.addOrUpdate(newRange);
-                });
-                return set;
-            });
-
-        this.pFirst = new Lazy<ISequenceDeltaRange<TOperation>>(
-            () => this.sortedRanges.value.items[0],
-        );
-
-        this.pLast = new Lazy<ISequenceDeltaRange<TOperation>>(
-            () => this.sortedRanges.value.items[this.sortedRanges.value.size - 1],
-        );
-    }
-
-    /**
-     * The in-order ranges affected by this delta.
-     * These may not be continuous.
-     */
-    public get ranges(): readonly Readonly<ISequenceDeltaRange<TOperation>>[] {
-        return this.sortedRanges.value.items;
-    }
-
-    /**
-     * The client id of the client that made the change which caused the delta event
-     */
-    public get clientId(): string {
-        return this.mergeTreeClient.longClientId;
-    }
-
-    /**
-     * The first of the modified ranges.
-     */
-    public get first(): Readonly<ISequenceDeltaRange<TOperation>> {
-        return this.pFirst.value;
-    }
-
-    /**
-     * The last of the modified ranges.
-     */
-    public get last(): Readonly<ISequenceDeltaRange<TOperation>> {
-        return this.pLast.value;
-    }
+export abstract class SequenceEvent<
+	TOperation extends MergeTreeDeltaOperationTypes = MergeTreeDeltaOperationTypes,
+> {
+	public readonly deltaOperation: TOperation;
+	// eslint-disable-next-line import/no-deprecated
+	private readonly sortedRanges: Lazy<SortedSegmentSet<ISequenceDeltaRange<TOperation>>>;
+	private readonly pFirst: Lazy<ISequenceDeltaRange<TOperation>>;
+	private readonly pLast: Lazy<ISequenceDeltaRange<TOperation>>;
+
+	constructor(
+		public readonly deltaArgs: IMergeTreeDeltaCallbackArgs<TOperation>,
+		// eslint-disable-next-line import/no-deprecated
+		private readonly mergeTreeClient: Client,
+	) {
+		assert(
+			deltaArgs.deltaSegments.length > 0,
+			0x2d8 /* "Empty change event should not be emitted." */,
+		);
+		this.deltaOperation = deltaArgs.operation;
+
+		// eslint-disable-next-line import/no-deprecated
+		this.sortedRanges = new Lazy<SortedSegmentSet<ISequenceDeltaRange<TOperation>>>(() => {
+			// eslint-disable-next-line import/no-deprecated
+			const set = new SortedSegmentSet<ISequenceDeltaRange<TOperation>>();
+			this.deltaArgs.deltaSegments.forEach((delta) => {
+				const newRange: ISequenceDeltaRange<TOperation> = {
+					operation: this.deltaArgs.operation,
+					position: this.mergeTreeClient.getPosition(delta.segment),
+					propertyDeltas: delta.propertyDeltas ?? {},
+					segment: delta.segment,
+				};
+				set.addOrUpdate(newRange);
+			});
+			return set;
+		});
+
+		this.pFirst = new Lazy<ISequenceDeltaRange<TOperation>>(
+			() => this.sortedRanges.value.items[0],
+		);
+
+		this.pLast = new Lazy<ISequenceDeltaRange<TOperation>>(
+			() => this.sortedRanges.value.items[this.sortedRanges.value.size - 1],
+		);
+	}
+
+	/**
+	 * The in-order ranges affected by this delta.
+	 * These may not be continuous.
+	 */
+	public get ranges(): readonly Readonly<ISequenceDeltaRange<TOperation>>[] {
+		return this.sortedRanges.value.items;
+	}
+
+	/**
+	 * The client id of the client that made the change which caused the delta event
+	 */
+	public get clientId(): string | undefined {
+		return this.mergeTreeClient.longClientId;
+	}
+
+	/**
+	 * The first of the modified ranges.
+	 */
+	public get first(): Readonly<ISequenceDeltaRange<TOperation>> {
+		return this.pFirst.value;
+	}
+
+	/**
+	 * The last of the modified ranges.
+	 */
+	public get last(): Readonly<ISequenceDeltaRange<TOperation>> {
+		return this.pLast.value;
+	}
 }
 
 /**
@@ -108,21 +112,23 @@ export abstract class SequenceEvent<TOperation extends MergeTreeDeltaOperationTy
  * 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.
+ * @alpha
  */
 export class SequenceDeltaEvent extends SequenceEvent<MergeTreeDeltaOperationType> {
-    /**
-     * Whether the event was caused by a locally-made change.
-     */
-    public readonly isLocal: boolean;
-
-    constructor(
-        public readonly opArgs: IMergeTreeDeltaOpArgs,
-        deltaArgs: IMergeTreeDeltaCallbackArgs,
-        mergeTreeClient: Client,
-    ) {
-        super(deltaArgs, mergeTreeClient);
-        this.isLocal = opArgs.sequencedMessage === undefined;
-    }
+	/**
+	 * Whether the event was caused by a locally-made change.
+	 */
+	public readonly isLocal: boolean;
+
+	constructor(
+		public readonly opArgs: IMergeTreeDeltaOpArgs,
+		deltaArgs: IMergeTreeDeltaCallbackArgs,
+		// eslint-disable-next-line import/no-deprecated
+		mergeTreeClient: Client,
+	) {
+		super(deltaArgs, mergeTreeClient);
+		this.isLocal = opArgs.sequencedMessage === undefined;
+	}
 }
 
 /**
@@ -131,49 +137,76 @@ 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.
+ * @alpha
  */
 export class SequenceMaintenanceEvent extends SequenceEvent<MergeTreeMaintenanceType> {
-    constructor(
-        public readonly opArgs: IMergeTreeDeltaOpArgs | undefined,
-        deltaArgs: IMergeTreeMaintenanceCallbackArgs,
-        mergeTreeClient: Client,
-    ) {
-        super(deltaArgs, mergeTreeClient);
-    }
+	constructor(
+		public readonly opArgs: IMergeTreeDeltaOpArgs | undefined,
+		deltaArgs: IMergeTreeMaintenanceCallbackArgs,
+		// eslint-disable-next-line import/no-deprecated
+		mergeTreeClient: Client,
+	) {
+		super(deltaArgs, mergeTreeClient);
+	}
 }
 
 /**
  * A range that has changed corresponding to a segment modification.
+ * @alpha
  */
-export interface ISequenceDeltaRange<TOperation extends MergeTreeDeltaOperationTypes = MergeTreeDeltaOperationTypes> {
-    operation: TOperation;
-    /**
-     * The index of the start of the range.
-     */
-    position: number;
-    /**
-     * The segment that corresponds to the range.
-     */
-    segment: ISegment;
-    propertyDeltas: PropertySet;
+export interface ISequenceDeltaRange<
+	TOperation extends MergeTreeDeltaOperationTypes = MergeTreeDeltaOperationTypes,
+> {
+	/**
+	 * The type of operation that changed this range.
+	 *
+	 * @remarks Consuming code should typically compare this to the enum values defined in
+	 * `MergeTreeDeltaOperationTypes`.
+	 */
+	operation: TOperation;
+
+	/**
+	 * The index of the start of the range.
+	 */
+	position: number;
+
+	/**
+	 * The segment that corresponds to the range.
+	 */
+	segment: ISegment;
+
+	/**
+	 * Deltas object which contains all modified properties with their previous values.
+	 * Since `undefined` doesn't survive a round-trip through JSON serialization, the old value being absent
+	 * is instead encoded with `null`.
+	 *
+	 * @remarks This object is motivated by undo/redo scenarios, and provides a convenient "inverse op" to apply to
+	 * undo a property change.
+	 *
+	 * @example
+	 *
+	 * If a segment initially had properties `{ foo: "1", bar: 2 }` and it was annotated with
+	 * `{ foo: 3, baz: 5 }`, the corresponding event would have a `propertyDeltas` of `{ foo: "1", baz: null }`.
+	 */
+	propertyDeltas: PropertySet;
 }
 
 class Lazy<T> {
-    private pValue: T;
-    private pEvaluated: boolean;
-    constructor(private readonly valueGenerator: () => T) {
-        this.pEvaluated = false;
-    }
-
-    public get evaluated(): boolean {
-        return this.pEvaluated;
-    }
-
-    public get value(): T {
-        if (!this.pEvaluated) {
-            this.pEvaluated = true;
-            this.pValue = this.valueGenerator();
-        }
-        return this.pValue;
-    }
+	private pValue: T | undefined;
+	private pEvaluated: boolean;
+	constructor(private readonly valueGenerator: () => T) {
+		this.pEvaluated = false;
+	}
+
+	public get evaluated(): boolean {
+		return this.pEvaluated;
+	}
+
+	public get value(): T {
+		if (!this.pEvaluated) {
+			this.pEvaluated = true;
+			this.pValue = this.valueGenerator();
+		}
+		return this.pValue as T;
+	}
 }

package/src/sequenceFactory.ts

@@ -4,224 +4,68 @@
  */
 
 import {
-    IChannelAttributes,
-    IFluidDataStoreRuntime,
-    IChannelServices,
-    IChannelFactory,
+	IChannelAttributes,
+	IFluidDataStoreRuntime,
+	IChannelServices,
+	IChannelFactory,
 } from "@fluidframework/datastore-definitions";
-import {
-    IJSONSegment,
-    Marker,
-    TextSegment,
-} from "@fluidframework/merge-tree";
-import { ISharedObject } from "@fluidframework/shared-object-base";
+import { Marker, TextSegment } from "@fluidframework/merge-tree";
 import { pkgVersion } from "./packageVersion";
-import { SharedNumberSequence } from "./sharedNumberSequence";
-import { SharedObjectSequence } from "./sharedObjectSequence";
-import { IJSONRunSegment, SubSequence } from "./sharedSequence";
 import { SharedString, SharedStringSegment } from "./sharedString";
 
-export class SharedStringFactory implements IChannelFactory {
-    // TODO rename back to https://graph.microsoft.com/types/mergeTree/string once paparazzi is able to dynamically
-    // load code
-    public static Type = "https://graph.microsoft.com/types/mergeTree";
-
-    public static readonly Attributes: IChannelAttributes = {
-        type: SharedStringFactory.Type,
-        snapshotFormatVersion: "0.1",
-        packageVersion: pkgVersion,
-    };
-
-    public static segmentFromSpec(spec: any): SharedStringSegment {
-        const maybeText = TextSegment.fromJSONObject(spec);
-        if (maybeText) { return maybeText; }
-
-        const maybeMarker = Marker.fromJSONObject(spec);
-        if (maybeMarker) { return maybeMarker; }
-    }
-
-    public get type() {
-        return SharedStringFactory.Type;
-    }
-
-    public get attributes() {
-        return SharedStringFactory.Attributes;
-    }
-
-    /**
-     * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.load}
-     */
-    public async load(
-        runtime: IFluidDataStoreRuntime,
-        id: string,
-        services: IChannelServices,
-        attributes: IChannelAttributes): Promise<SharedString> {
-        const sharedString = new SharedString(runtime, id, attributes);
-        await sharedString.load(services);
-        return sharedString;
-    }
-
-    public create(document: IFluidDataStoreRuntime, id: string): SharedString {
-        const sharedString = new SharedString(document, id, this.attributes);
-        sharedString.initializeLocal();
-        return sharedString;
-    }
-}
-
-/**
- * @deprecated SharedObjectSequence is not recommended for use and will be removed in an upcoming release.
- * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
- */
-export class SharedObjectSequenceFactory implements IChannelFactory {
-    /**
-     * @deprecated SharedObjectSequence is not recommended for use and will be removed in an upcoming release.
-     * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
-     */
-    public static Type = "https://graph.microsoft.com/types/mergeTree/object-sequence";
-
-    /**
-     * @deprecated SharedObjectSequence is not recommended for use and will be removed in an upcoming release.
-     * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
-     */
-    public static readonly Attributes: IChannelAttributes = {
-        type: SharedObjectSequenceFactory.Type,
-        snapshotFormatVersion: "0.1",
-        packageVersion: pkgVersion,
-    };
-
-    /**
-     * @deprecated SharedObjectSequence is not recommended for use and will be removed in an upcoming release.
-     * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
-     */
-    public static segmentFromSpec(segSpec: IJSONSegment) {
-        const runSegment = segSpec as IJSONRunSegment<object>;
-        if (runSegment.items) {
-            const seg = new SubSequence<object>(runSegment.items);
-            if (runSegment.props) {
-                seg.addProperties(runSegment.props);
-            }
-            return seg;
-        }
-    }
-
-    /**
-     * @deprecated SharedObjectSequence is not recommended for use and will be removed in an upcoming release.
-     * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
-     */
-    public get type() {
-        return SharedObjectSequenceFactory.Type;
-    }
-
-    /**
-     * @deprecated SharedObjectSequence is not recommended for use and will be removed in an upcoming release.
-     * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
-     */
-    public get attributes() {
-        return SharedObjectSequenceFactory.Attributes;
-    }
-
-    /**
-     * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.load}
-     *
-     * @deprecated SharedObjectSequence is not recommended for use and will be removed in an upcoming release.
-     * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
-     */
-    public async load(
-        runtime: IFluidDataStoreRuntime,
-        id: string,
-        services: IChannelServices,
-        attributes: IChannelAttributes): Promise<ISharedObject> {
-        const sharedSeq = new SharedObjectSequence<object>(runtime, id, attributes);
-        await sharedSeq.load(services);
-        return sharedSeq;
-    }
-
-    /**
-     * @deprecated SharedObjectSequence is not recommended for use and will be removed in an upcoming release.
-     * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
-     */
-    public create(document: IFluidDataStoreRuntime, id: string): ISharedObject {
-        const sharedString = new SharedObjectSequence(document, id, this.attributes);
-        sharedString.initializeLocal();
-        return sharedString;
-    }
-}
-
 /**
- * @deprecated SharedNumberSequence is not recommended for use and will be removed in an upcoming release.
- * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
+ * @alpha
  */
-export class SharedNumberSequenceFactory implements IChannelFactory {
-    /**
-     * @deprecated SharedNumberSequence is not recommended for use and will be removed in an upcoming release.
-     * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
-     */
-    public static Type = "https://graph.microsoft.com/types/mergeTree/number-sequence";
-
-    /**
-     * @deprecated SharedNumberSequence is not recommended for use and will be removed in an upcoming release.
-     * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
-     */
-    public static readonly Attributes: IChannelAttributes = {
-        type: SharedNumberSequenceFactory.Type,
-        snapshotFormatVersion: "0.1",
-        packageVersion: pkgVersion,
-    };
-
-    /**
-     * @deprecated SharedNumberSequence is not recommended for use and will be removed in an upcoming release.
-     * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
-     */
-    public static segmentFromSpec(segSpec: IJSONSegment) {
-        const runSegment = segSpec as IJSONRunSegment<number>;
-        if (runSegment.items) {
-            const seg = new SubSequence<number>(runSegment.items);
-            if (runSegment.props) {
-                seg.addProperties(runSegment.props);
-            }
-            return seg;
-        }
-    }
-
-    /**
-     * @deprecated SharedNumberSequence is not recommended for use and will be removed in an upcoming release.
-     * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
-     */
-    public get type() {
-        return SharedNumberSequenceFactory.Type;
-    }
-
-    /**
-     * @deprecated SharedNumberSequence is not recommended for use and will be removed in an upcoming release.
-     * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
-     */
-    public get attributes() {
-        return SharedNumberSequenceFactory.Attributes;
-    }
-
-    /**
-     * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.load}
-     *
-     * @deprecated SharedNumberSequence is not recommended for use and will be removed in an upcoming release.
-     * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
-     */
-    public async load(
-        runtime: IFluidDataStoreRuntime,
-        id: string,
-        services: IChannelServices,
-        attributes: IChannelAttributes): Promise<ISharedObject> {
-        const sharedSeq = new SharedNumberSequence(runtime, id, attributes);
-        await sharedSeq.load(services);
-        return sharedSeq;
-    }
-
-    /**
-     * @deprecated SharedNumberSequence is not recommended for use and will be removed in an upcoming release.
-     * For more info, please see [Github issue 8526](https://github.com/microsoft/FluidFramework/issues/8526)
-     */
-    public create(document: IFluidDataStoreRuntime, id: string): ISharedObject {
-        const sharedString = new SharedNumberSequence(document, id, this.attributes);
-        sharedString.initializeLocal();
-        return sharedString;
-    }
+export class SharedStringFactory implements IChannelFactory {
+	// TODO rename back to https://graph.microsoft.com/types/mergeTree/string once paparazzi is able to dynamically
+	// load code (UPDATE: paparazzi is gone... anything to do here?)
+	public static Type = "https://graph.microsoft.com/types/mergeTree";
+
+	public static readonly Attributes: IChannelAttributes = {
+		type: SharedStringFactory.Type,
+		snapshotFormatVersion: "0.1",
+		packageVersion: pkgVersion,
+	};
+
+	public static segmentFromSpec(spec: any): SharedStringSegment {
+		const maybeText = TextSegment.fromJSONObject(spec);
+		if (maybeText) {
+			return maybeText;
+		}
+
+		const maybeMarker = Marker.fromJSONObject(spec);
+		if (maybeMarker) {
+			return maybeMarker;
+		}
+
+		throw new Error(`Unrecognized IJSONObject`);
+	}
+
+	public get type() {
+		return SharedStringFactory.Type;
+	}
+
+	public get attributes() {
+		return SharedStringFactory.Attributes;
+	}
+
+	/**
+	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.load}
+	 */
+	public async load(
+		runtime: IFluidDataStoreRuntime,
+		id: string,
+		services: IChannelServices,
+		attributes: IChannelAttributes,
+	): Promise<SharedString> {
+		const sharedString = new SharedString(runtime, id, attributes);
+		await sharedString.load(services);
+		return sharedString;
+	}
+
+	public create(document: IFluidDataStoreRuntime, id: string): SharedString {
+		const sharedString = new SharedString(document, id, this.attributes);
+		sharedString.initializeLocal();
+		return sharedString;
+	}
 }