Further MergeTree Client Legacy Deprecations (#22629)

In an effort the reduce exposure of the Client class in the merge-tree package this change additionally deprecates a number of types which either directly or indirectly expose the merge-tree Client class. Most of these types are not meant to be used directly, and direct use is not supported: - AttributionPolicy - IClientEvents - IMergeTreeAttributionOptions - SharedSegmentSequence - SharedStringClass Some of the deprecations are for class constructors and in those cases we plan to replace the class with an interface which has an equivalent API. Direct instantiation of these classes is not currently supported or necessary for any supported scenario, so the change to an interface should not impact usage: - SequenceInterval - SequenceEvent - SequenceDeltaEvent - SequenceMaintenanceEvent --------- Co-authored-by: jzaffiro <110866475+jzaffiro@users.noreply.github.com> Co-authored-by: Tyler Butler <tyler@tylerbutler.com>
microsoft · Sep 27, 2024 · 0b59ae8 · 0b59ae8
1 parent 4b6957e
commit 0b59ae8
Show file tree

Hide file tree

Showing 13 changed files with 69 additions and 5 deletions.
diff --git a/.changeset/shaggy-pens-occur.md b/.changeset/shaggy-pens-occur.md
@@ -0,0 +1,25 @@
+---
+"@fluidframework/merge-tree": minor
+"@fluidframework/sequence": minor
+---
+---
+"section": deprecation
+---
+
+Further MergeTree Client Legacy Deprecations
+
+To reduce exposure of the `Client` class in the merge-tree package, several types have been deprecated. These types directly or indirectly expose the merge-tree `Client` class.
+
+Most of these types are not meant to be used directly, and direct use is not supported:
+
+ - AttributionPolicy
+ - IClientEvents
+ - IMergeTreeAttributionOptions
+ - SharedSegmentSequence
+ - SharedStringClass
+
+Some of the deprecations are class constructors. In those cases, we plan to replace the class with an interface which has an equivalent API. Direct instantiation of these classes is not currently supported or necessary for any supported scenario, so the change to an interface should not impact usage. This applies to the following types:
+- SequenceInterval
+- SequenceEvent
+- SequenceDeltaEvent
+- SequenceMaintenanceEvent
diff --git a/packages/dds/merge-tree/api-report/merge-tree.legacy.alpha.api.md b/packages/dds/merge-tree/api-report/merge-tree.legacy.alpha.api.md
@@ -7,7 +7,7 @@
 // @alpha
 export function appendToMergeTreeDeltaRevertibles(deltaArgs: IMergeTreeDeltaCallbackArgs, revertibles: MergeTreeDeltaRevertible[]): void;
 
-// @alpha @sealed
+// @alpha @sealed @deprecated
 export interface AttributionPolicy {
     attach: (client: Client) => void;
     detach: () => void;
@@ -244,7 +244,7 @@ export interface IAttributionCollectionSpec<T> {
     }>;
 }
 
-// @alpha
+// @alpha @deprecated
 export interface IClientEvents {
     // (undocumented)
     (event: "normalize", listener: (target: IEventThisPlaceHolder) => void): void;
@@ -302,7 +302,7 @@ export interface IMergeTreeAnnotateMsg extends IMergeTreeDelta {
     type: typeof MergeTreeDeltaType.ANNOTATE;
 }
 
-// @alpha (undocumented)
+// @alpha @deprecated (undocumented)
 export interface IMergeTreeAttributionOptions {
     policyFactory?: () => AttributionPolicy;
     track?: boolean;

diff --git a/packages/dds/merge-tree/src/attributionPolicy.ts b/packages/dds/merge-tree/src/attributionPolicy.ts
@@ -10,6 +10,7 @@ import { AttributionKey } from "@fluidframework/runtime-definitions/internal";
 import { AttributionCollection } from "./attributionCollection.js";
 // eslint-disable-next-line import/no-deprecated
 import { Client } from "./client.js";
+// eslint-disable-next-line import/no-deprecated
 import { AttributionPolicy } from "./mergeTree.js";
 import {
 	IMergeTreeDeltaCallbackArgs,
@@ -41,6 +42,7 @@ interface AttributionCallbacks {
 function createAttributionPolicyFromCallbacks({
 	delta,
 	maintenance,
+	// eslint-disable-next-line import/no-deprecated
 }: AttributionCallbacks): AttributionPolicy {
 	let unsubscribe: undefined | (() => void);
 	return {
@@ -202,6 +204,7 @@ function combineMergeTreeCallbacks(callbacks: AttributionCallbacks[]): Attributi
  * Creates an {@link AttributionPolicy} which only tracks initial insertion of content.
  * @internal
  */
+// eslint-disable-next-line import/no-deprecated
 export function createInsertOnlyAttributionPolicy(): AttributionPolicy {
 	return createAttributionPolicyFromCallbacks(
 		combineMergeTreeCallbacks([
@@ -231,6 +234,7 @@ export function createInsertOnlyAttributionPolicy(): AttributionPolicy {
  */
 export function createPropertyTrackingAttributionPolicyFactory(
 	...propNames: string[]
+	// eslint-disable-next-line import/no-deprecated
 ): () => AttributionPolicy {
 	return () =>
 		createAttributionPolicyFromCallbacks(
@@ -249,6 +253,7 @@ export function createPropertyTrackingAttributionPolicyFactory(
  */
 export function createPropertyTrackingAndInsertionAttributionPolicyFactory(
 	...propNames: string[]
+	// eslint-disable-next-line import/no-deprecated
 ): () => AttributionPolicy {
 	return () =>
 		createAttributionPolicyFromCallbacks(

diff --git a/packages/dds/merge-tree/src/client.ts b/packages/dds/merge-tree/src/client.ts
@@ -102,6 +102,7 @@ export interface IIntegerRange {
  * they need for rebasing their ops on reconnection.
  * @legacy
  * @alpha
+ * @deprecated  This functionality was not meant to be exported and will be removed in a future release
  */
 export interface IClientEvents {
 	(event: "normalize", listener: (target: IEventThisPlaceHolder) => void): void;

diff --git a/packages/dds/merge-tree/src/mergeTree.ts b/packages/dds/merge-tree/src/mergeTree.ts
@@ -221,6 +221,7 @@ export function errorIfOptionNotTrue(
 /**
  * @legacy
  * @alpha
+ * @deprecated  This functionality was not meant to be exported and will be removed in a future release
  */
 export interface IMergeTreeAttributionOptions {
 	/**
@@ -248,6 +249,7 @@ export interface IMergeTreeAttributionOptions {
  * @sealed
  * @legacy
  * @alpha
+ * @deprecated This functionality was not meant to be exported and will be removed in a future release
  */
 export interface AttributionPolicy {
 	/**

diff --git a/packages/dds/sequence/api-report/sequence.legacy.alpha.api.md b/packages/dds/sequence/api-report/sequence.legacy.alpha.api.md
@@ -298,6 +298,7 @@ export function revertSharedStringRevertibles(sharedString: ISharedString, rever
 
 // @alpha
 export class SequenceDeltaEvent extends SequenceEvent<MergeTreeDeltaOperationType> {
+    // @deprecated
     constructor(opArgs: IMergeTreeDeltaOpArgs, deltaArgs: IMergeTreeDeltaCallbackArgs, mergeTreeClient: Client);
     readonly isLocal: boolean;
     // (undocumented)
@@ -306,6 +307,7 @@ export class SequenceDeltaEvent extends SequenceEvent<MergeTreeDeltaOperationTyp
 
 // @alpha
 export abstract class SequenceEvent<TOperation extends MergeTreeDeltaOperationTypes = MergeTreeDeltaOperationTypes> {
+    // @deprecated
     constructor(
     deltaArgs: IMergeTreeDeltaCallbackArgs<TOperation>, mergeTreeClient: Client);
     get clientId(): string | undefined;
@@ -319,6 +321,7 @@ export abstract class SequenceEvent<TOperation extends MergeTreeDeltaOperationTy
 
 // @alpha
 export class SequenceInterval implements ISerializableInterval {
+    // @deprecated
     constructor(client: Client,
     start: LocalReferencePosition,
     end: LocalReferencePosition, intervalType: IntervalType, props?: PropertySet, startSide?: Side, endSide?: Side);
@@ -357,14 +360,15 @@ export class SequenceInterval implements ISerializableInterval {
 
 // @alpha
 export class SequenceMaintenanceEvent extends SequenceEvent<MergeTreeMaintenanceType> {
+    // @deprecated
     constructor(
     opArgs: IMergeTreeDeltaOpArgs | undefined, deltaArgs: IMergeTreeMaintenanceCallbackArgs, mergeTreeClient: Client);
     readonly opArgs: IMergeTreeDeltaOpArgs | undefined;
 }
 
 export { SequencePlace }
 
-// @alpha (undocumented)
+// @alpha @deprecated (undocumented)
 export abstract class SharedSegmentSequence<T extends ISegment> extends SharedObject<ISharedSegmentSequenceEvents> implements ISharedSegmentSequence<T> {
     constructor(dataStoreRuntime: IFluidDataStoreRuntime, id: string, attributes: IChannelAttributes, segmentFromSpec: (spec: IJSONSegment) => ISegment);
     // (undocumented)
@@ -441,7 +445,7 @@ export const SharedString: ISharedObjectKind<ISharedString> & SharedObjectKind<I
 // @alpha
 export type SharedString = ISharedString;
 
-// @alpha
+// @alpha @deprecated
 export class SharedStringClass extends SharedSegmentSequence<SharedStringSegment> implements ISharedString {
     constructor(document: IFluidDataStoreRuntime, id: string, attributes: IChannelAttributes);
     annotateMarker(marker: Marker, props: PropertySet): void;

diff --git a/packages/dds/sequence/src/intervals/sequenceInterval.ts b/packages/dds/sequence/src/intervals/sequenceInterval.ts
@@ -127,6 +127,9 @@ export class SequenceInterval implements ISerializableInterval {
 		);
 	}
 
+	/**
+	 * @deprecated  This functionality was not meant to be exported and will be removed in a future release
+	 */
 	constructor(
 		private readonly client: Client,
 		/**

diff --git a/packages/dds/sequence/src/sequence.ts b/packages/dds/sequence/src/sequence.ts
@@ -345,6 +345,7 @@ export interface ISharedSegmentSequence<T extends ISegment>
 /**
  * @legacy
  * @alpha
+ * @deprecated  This functionality was not meant to be exported and will be removed in a future release
  */
 export abstract class SharedSegmentSequence<T extends ISegment>
 	extends SharedObject<ISharedSegmentSequenceEvents>

diff --git a/packages/dds/sequence/src/sequenceDeltaEvent.ts b/packages/dds/sequence/src/sequenceDeltaEvent.ts
@@ -36,6 +36,9 @@ export abstract class SequenceEvent<
 	private readonly pFirst: Lazy<ISequenceDeltaRange<TOperation>>;
 	private readonly pLast: Lazy<ISequenceDeltaRange<TOperation>>;
 
+	/**
+	 * @deprecated This functionality was not meant to be exported and will be removed in a future release
+	 */
 	constructor(
 		/**
 		 * Arguments reflecting the type of change that caused this event.
@@ -127,6 +130,9 @@ export class SequenceDeltaEvent extends SequenceEvent<MergeTreeDeltaOperationTyp
 	 */
 	public readonly isLocal: boolean;
 
+	/**
+	 * @deprecated This functionality was not meant to be exported and will be removed in a future release
+	 */
 	constructor(
 		public readonly opArgs: IMergeTreeDeltaOpArgs,
 		deltaArgs: IMergeTreeDeltaCallbackArgs,
@@ -148,6 +154,9 @@ export class SequenceDeltaEvent extends SequenceEvent<MergeTreeDeltaOperationTyp
  * @alpha
  */
 export class SequenceMaintenanceEvent extends SequenceEvent<MergeTreeMaintenanceType> {
+	/**
+	 * @deprecated This functionality was not meant to be exported and will be removed in a future release
+	 */
 	constructor(
 		/**
 		 * Defined iff `deltaArgs.operation` is {@link @fluidframework/merge-tree#MergeTreeMaintenanceType.ACKNOWLEDGED|MergeTreeMaintenanceType.ACKNOWLEDGED}.

diff --git a/packages/dds/sequence/src/sequenceFactory.ts b/packages/dds/sequence/src/sequenceFactory.ts
@@ -13,6 +13,7 @@ import { Marker, TextSegment } from "@fluidframework/merge-tree/internal";
 import { createSharedObjectKind } from "@fluidframework/shared-object-base/internal";
 
 import { pkgVersion } from "./packageVersion.js";
+// eslint-disable-next-line import/no-deprecated
 import { SharedStringClass, SharedStringSegment, type ISharedString } from "./sharedString.js";
 
 export class SharedStringFactory implements IChannelFactory<ISharedString> {
@@ -56,7 +57,9 @@ export class SharedStringFactory implements IChannelFactory<ISharedString> {
 		id: string,
 		services: IChannelServices,
 		attributes: IChannelAttributes,
+		// eslint-disable-next-line import/no-deprecated
 	): Promise<SharedStringClass> {
+		// eslint-disable-next-line import/no-deprecated
 		const sharedString = new SharedStringClass(runtime, id, attributes);
 		await sharedString.load(services);
 		return sharedString;
@@ -65,7 +68,9 @@ export class SharedStringFactory implements IChannelFactory<ISharedString> {
 	/**
 	 * {@inheritDoc @fluidframework/datastore-definitions#IChannelFactory.create}
 	 */
+	// eslint-disable-next-line import/no-deprecated
 	public create(document: IFluidDataStoreRuntime, id: string): SharedStringClass {
+		// eslint-disable-next-line import/no-deprecated
 		const sharedString = new SharedStringClass(document, id, this.attributes);
 		sharedString.initializeLocal();
 		return sharedString;

diff --git a/packages/dds/sequence/src/sharedSequence.ts b/packages/dds/sequence/src/sharedSequence.ts
@@ -16,6 +16,7 @@ import {
 	PropertySet,
 } from "@fluidframework/merge-tree/internal";
 
+// eslint-disable-next-line import/no-deprecated
 import { SharedSegmentSequence } from "./sequence.js";
 
 const MaxRun = 128;
@@ -118,6 +119,7 @@ export class SubSequence<T> extends BaseSegment {
  * @deprecated SharedSequence will be removed in a upcoming release. It has been moved to the fluid-experimental/sequence-deprecated package
  * @internal
  */
+// eslint-disable-next-line import/no-deprecated
 export class SharedSequence<T> extends SharedSegmentSequence<SubSequence<T>> {
 	constructor(
 		document: IFluidDataStoreRuntime,

diff --git a/packages/dds/sequence/src/sharedString.ts b/packages/dds/sequence/src/sharedString.ts
@@ -20,6 +20,7 @@ import {
 	refHasTileLabel,
 } from "@fluidframework/merge-tree/internal";
 
+// eslint-disable-next-line import/no-deprecated
 import { SharedSegmentSequence, type ISharedSegmentSequence } from "./sequence.js";
 import { SharedStringFactory } from "./sequenceFactory.js";
 
@@ -141,8 +142,10 @@ export type SharedStringSegment = TextSegment | Marker;
  * image or Fluid object that should be rendered with the text.
  * @legacy
  * @alpha
+ * @deprecated  This functionality was not meant to be exported and will be removed in a future release
  */
 export class SharedStringClass
+	// eslint-disable-next-line import/no-deprecated
 	extends SharedSegmentSequence<SharedStringSegment>
 	implements ISharedString
 {

diff --git a/packages/framework/fluid-framework/api-report/fluid-framework.legacy.alpha.api.md b/packages/framework/fluid-framework/api-report/fluid-framework.legacy.alpha.api.md
@@ -1025,6 +1025,7 @@ type ScopedSchemaName<TScope extends string | undefined, TName extends number |
 
 // @alpha
 export class SequenceDeltaEvent extends SequenceEvent<MergeTreeDeltaOperationType> {
+    // @deprecated
     constructor(opArgs: IMergeTreeDeltaOpArgs, deltaArgs: IMergeTreeDeltaCallbackArgs, mergeTreeClient: Client);
     readonly isLocal: boolean;
     // (undocumented)
@@ -1033,6 +1034,7 @@ export class SequenceDeltaEvent extends SequenceEvent<MergeTreeDeltaOperationTyp
 
 // @alpha
 export abstract class SequenceEvent<TOperation extends MergeTreeDeltaOperationTypes = MergeTreeDeltaOperationTypes> {
+    // @deprecated
     constructor(
     deltaArgs: IMergeTreeDeltaCallbackArgs<TOperation>, mergeTreeClient: Client);
     get clientId(): string | undefined;
@@ -1046,6 +1048,7 @@ export abstract class SequenceEvent<TOperation extends MergeTreeDeltaOperationTy
 
 // @alpha
 export class SequenceInterval implements ISerializableInterval {
+    // @deprecated
     constructor(client: Client,
     start: LocalReferencePosition,
     end: LocalReferencePosition, intervalType: IntervalType, props?: PropertySet, startSide?: Side, endSide?: Side);
@@ -1084,6 +1087,7 @@ export class SequenceInterval implements ISerializableInterval {
 
 // @alpha
 export class SequenceMaintenanceEvent extends SequenceEvent<MergeTreeMaintenanceType> {
+    // @deprecated
     constructor(
     opArgs: IMergeTreeDeltaOpArgs | undefined, deltaArgs: IMergeTreeMaintenanceCallbackArgs, mergeTreeClient: Client);
     readonly opArgs: IMergeTreeDeltaOpArgs | undefined;