@fluidframework/shared-object-base 2.33.2 → 2.40.0-336023

package/src/sharedObject.ts

@@ -70,7 +70,18 @@ interface ProcessTelemetryProperties {
 }
 
 /**
- * Base class from which all shared objects derive.
+ * Base class from which all {@link ISharedObject|shared objects} derive.
+ * @remarks
+ * This class implements common behaviors that implementations of {@link ISharedObject} may want to reuse.
+ * Even more such behaviors are implemented in the {@link SharedObject} class.
+ * @privateRemarks
+ * Currently some documentation (like the above) implies that this is supposed to be the only implementation of ISharedObject, which is both package-exported and not `@sealed`.
+ * This situation should be clarified to indicate if other implementations of ISharedObject are allowed and just currently don't exist,
+ * or if the intention is that no other implementations should exist and creating some might break things.
+ * As part of this, any existing implementations of ISharedObject (via SharedObjectCore or otherwise) in use by legacy API users will need to be considered.
+ *
+ * TODO:
+ * This class should eventually be made internal, as custom subclasses of it outside this repository are intended to be made unsupported in the future.
  * @legacy
  * @alpha
  */
@@ -129,14 +140,18 @@ export abstract class SharedObjectCore<
 		return this._connected;
 	}
 
-	/**
-	 * @param id - The id of the shared object
-	 * @param runtime - The IFluidDataStoreRuntime which contains the shared object
-	 * @param attributes - Attributes of the shared object
-	 */
 	constructor(
+		/**
+		 * The ID of the shared object.
+		 */
 		public id: string,
+		/**
+		 * The runtime instance that contains the Shared Object.
+		 */
 		protected runtime: IFluidDataStoreRuntime,
+		/**
+		 * The attributes of the Shared Object.
+		 */
 		public readonly attributes: IChannelAttributes,
 	) {
 		super((event: EventEmitterEventType, e: unknown) =>
@@ -729,8 +744,14 @@ export abstract class SharedObjectCore<
 }
 
 /**
- * SharedObject with simplified, synchronous summarization and GC.
- * DDS implementations with async and incremental summarization should extend SharedObjectCore directly instead.
+ * Helper for implementing {@link ISharedObject} with simplified, synchronous summarization and garbage collection.
+ * @remarks
+ * DDS implementations with async and incremental summarization should extend {@link SharedObjectCore} directly instead.
+ * @privateRemarks
+ * TODO:
+ * This class is badly named.
+ * Once it becomes `@internal` "SharedObjectCore" should probably become "SharedObject"
+ * and this class should be renamed to something like "SharedObjectSynchronous".
  * @legacy
  * @alpha
  */
@@ -762,15 +783,13 @@ export abstract class SharedObject<
 		return this._serializer;
 	}
 
-	/**
-	 * @param id - The id of the shared object
-	 * @param runtime - The IFluidDataStoreRuntime which contains the shared object
-	 * @param attributes - Attributes of the shared object
-	 */
 	constructor(
 		id: string,
 		runtime: IFluidDataStoreRuntime,
 		attributes: IChannelAttributes,
+		/**
+		 * The prefix to use for telemetry events emitted by this object.
+		 */
 		private readonly telemetryContextPrefix: string,
 	) {
 		super(id, runtime, attributes);

package/src/types.ts

@@ -53,7 +53,19 @@ export interface ISharedObjectEvents extends IErrorEvent {
 }
 
 /**
- * Base interface for shared objects from which other interfaces derive. Implemented by SharedObject
+ * Base interface for shared objects from which other interfaces extend.
+ * @remarks
+ * This interface is not intended to be implemented outside this repository:
+ * implementers should migrate to using an existing implementation instead.
+ * @privateRemarks
+ * Implemented by {@link SharedObjectCore}.
+ *
+ * TODO:
+ * The relationship between the "shared object" abstraction and "channel" abstraction should be clarified and/or unified.
+ * Either there should be a single named abstraction or the docs here need to make it clear why adding events and bindToContext to a channel makes it a "shared object".
+ * Additionally the docs here need to define what a shared object is, not just claim this interface is for them.
+ * If the intention is that the "shared object" concept `IFluidLoadable` mentions is only ever implemented by this interface then even more concept unification should be done.
+ * If not then more clarity is needed on what this interface specifically is, what the other "shared object" concept means and how they relate.
  * @legacy
  * @alpha
  */