@fluidframework/fluid-static 1.2.7 → 2.0.0-dev.1.3.0.96595

package/src/rootDataObject.ts

@@ -23,20 +23,20 @@ import {
 import { isDataObjectClass, isSharedObjectClass, parseDataObjectsFromSharedObjects } from "./utils";
 
 /**
- * Input props for {@link RootDataObject.initializingFirstTime}
+ * Input props for {@link RootDataObject.initializingFirstTime}.
  */
 export interface RootDataObjectProps {
     /**
      * Initial object structure with which the {@link RootDataObject} will be first-time initialized.
-     * See {@link RootDataObject.initializingFirstTime}
+     *
+     * @see {@link RootDataObject.initializingFirstTime}
      */
     initialObjects: LoadableObjectClassRecord;
 }
 
 /**
- * The entry-point/root collaborative object of the Fluid Container.
- * This class abstracts the dynamic code required to build a Fluid Container into a static representation
- * for end customers.
+ * The entry-point/root collaborative object of the {@link IFluidContainer | Fluid Container}.
+ * Abstracts the dynamic code required to build a Fluid Container into a static representation for end customers.
  */
 export class RootDataObject extends DataObject<{ InitialState: RootDataObjectProps; }> {
     private readonly initialObjectsDirKey = "initial-objects-key";
@@ -54,7 +54,7 @@ export class RootDataObject extends DataObject<{ InitialState: RootDataObjectPro
      * The first time this object is initialized, creates each object identified in
      * {@link RootDataObjectProps.initialObjects} and stores them as unique values in the root directory.
      *
-     * See {@link @fluidframework/aqueduct#PureDataObject.initializingFirstTime}
+     * @see {@link @fluidframework/aqueduct#PureDataObject.initializingFirstTime}
      */
     protected async initializingFirstTime(props: RootDataObjectProps) {
         this.root.createSubDirectory(this.initialObjectsDirKey);
@@ -76,7 +76,7 @@ export class RootDataObject extends DataObject<{ InitialState: RootDataObjectPro
      * Every time an instance is initialized, loads all of the initial objects in the root directory so they can be
      * accessed immediately.
      *
-     * See {@link @fluidframework/aqueduct#PureDataObject.hasInitialized}
+     * @see {@link @fluidframework/aqueduct#PureDataObject.hasInitialized}
      */
     protected async hasInitialized() {
         // We will always load the initial objects so they are available to the developer
@@ -94,7 +94,8 @@ export class RootDataObject extends DataObject<{ InitialState: RootDataObjectPro
 
     /**
      * Provides a record of the initial objects defined on creation.
-     * See {@link RootDataObject.initializingFirstTime}
+     *
+     * @see {@link RootDataObject.initializingFirstTime}
      */
     public get initialObjects(): LoadableObjectRecord {
         if (Object.keys(this._initialObjects).length === 0) {
@@ -105,7 +106,10 @@ export class RootDataObject extends DataObject<{ InitialState: RootDataObjectPro
 
     /**
      * Dynamically creates a new detached collaborative object (DDS/DataObject).
+     *
      * @param objectClass - Type of the collaborative object to be created.
+     *
+     * @typeParam T - The class of the `DataObject` or `SharedObject`.
      */
     public async create<T extends IFluidLoadable>(
         objectClass: LoadableObjectClass<T>,
@@ -137,8 +141,12 @@ export class RootDataObject extends DataObject<{ InitialState: RootDataObjectPro
 const rootDataStoreId = "rootDOId";
 
 /**
- * Container code that provides a single {@link RootDataObject}.  This data object is
- * dynamically customized (registry and initial objects) based on the schema provided to the container runtime factory.
+ * Container code that provides a single {@link RootDataObject}.
+ *
+ * @remarks
+ *
+ * This data object is dynamically customized (registry and initial objects) based on the schema provided.
+ * to the container runtime factory.
  */
 export class DOProviderContainerRuntimeFactory extends BaseContainerRuntimeFactory {
     private readonly rootDataObjectFactory: DataObjectFactory<RootDataObject, {

package/src/serviceAudience.ts

@@ -9,29 +9,39 @@ import { IClient } from "@fluidframework/protocol-definitions";
 import { IServiceAudience, IServiceAudienceEvents, IMember } from "./types";
 
 /**
- * Base class for providing audience information for sessions interacting with FluidContainer
+ * Base class for providing audience information for sessions interacting with {@link IFluidContainer}
+ *
+ * @remarks
+ *
  * This can be extended by different service-specific client packages to additional parameters to
- * the user and client details returned in IMember
- * @typeParam M - A service-specific member type.
+ * the user and client details returned in {@link IMember}.
+ *
+ * @typeParam M - A service-specific {@link IMember} implementation.
  */
 export abstract class ServiceAudience<M extends IMember = IMember>
   extends TypedEventEmitter<IServiceAudienceEvents<M>>
   implements IServiceAudience<M> {
   /**
-   * Audience object which includes all the existing members of the container.
+   * Audience object which includes all the existing members of the {@link IFluidContainer | container}.
    */
   protected readonly audience: IAudience;
 
   /**
-   * Retain the most recent member list.  This is so we have more information about a member
-   * leaving the audience in the removeMember event.  It allows us to match the behavior of the
-   * addMember event where it only fires on a change to the members this class exposes (and would
-   * actually produce a change in what getMembers returns).  It also allows us to provide the
-   * client details in the event which makes it easier to find that client connection in a map
-   * keyed on the userId and not clientId.
-   * This map will always be up-to-date in a removeMember event because it is set once at
-   * construction and in every addMember event.
-   * It is mapped clientId to M to be better work with what the IAudience event provides
+   * Retain the most recent member list.
+   *
+   * @remarks
+   *
+   * This is so we have more information about a member leaving the audience in the `removeMember` event.
+   *
+   * It allows us to match the behavior of the `addMember` event where it only fires on a change to the members this
+   * class exposes (and would actually produce a change in what `getMembers` returns).
+   *
+   * It also allows us to provide the client details in the event which makes it easier to find that client connection
+   * in a map keyed on the `userId` and not `clientId`.
+   *
+   * This map will always be up-to-date in a `removeMember` event because it is set once at construction and in
+   * every `addMember` event. It is mapped `clientId` to `M` to be better work with what the {@link IServiceAudience}
+   * events provide.
    */
   protected lastMembers: Map<string, M> = new Map();
 
@@ -68,6 +78,7 @@ export abstract class ServiceAudience<M extends IMember = IMember>
 
   /**
    * Provides ability for inheriting class to modify/extend the audience object.
+   *
    * @param audienceMember - Record of a specific audience member.
    */
   protected abstract createServiceMember(audienceMember: IClient): M;
@@ -127,6 +138,7 @@ export abstract class ServiceAudience<M extends IMember = IMember>
   /**
    * Provides ability for the inheriting class to include/omit specific members.
    * An example use case is omitting the summarizer client.
+   *
    * @param member - Member to be included/omitted.
    */
   protected shouldIncludeAsMember(member: IClient): boolean {

package/src/types.ts

@@ -9,60 +9,69 @@ import { IChannelFactory } from "@fluidframework/datastore-definitions";
 import { IFluidDataStoreFactory } from "@fluidframework/runtime-definitions";
 
 /**
- * A mapping of string identifiers to instantiated DataObjects or SharedObjects.
+ * A mapping of string identifiers to instantiated `DataObject`s or `SharedObject`s.
  */
 export type LoadableObjectRecord = Record<string, IFluidLoadable>;
 
 /**
- * A mapping of string identifiers to classes that will later be used to instantiate a corresponding DataObject
- * or SharedObject in a LoadableObjectRecord.
+ * A mapping of string identifiers to classes that will later be used to instantiate a corresponding `DataObject`
+ * or `SharedObject` in a {@link LoadableObjectRecord}.
  */
 export type LoadableObjectClassRecord = Record<string, LoadableObjectClass<any>>;
 
 /**
- * A LoadableObjectClass is an class object of DataObject or SharedObject
- * @typeParam T - The class of the DataObject or SharedObject
+ * A class object of `DataObject` or `SharedObject`.
+ *
+ * @typeParam T - The class of the `DataObject` or `SharedObject`.
  */
 export type LoadableObjectClass<T extends IFluidLoadable> = DataObjectClass<T> | SharedObjectClass<T>;
 
 /**
- * A DataObjectClass is a class that has a factory that can create a DataObject and a
- * constructor that will return the type of the DataObject.
- * @typeParam T - The class of the DataObject
+ * A class that has a factory that can create a `DataObject` and a
+ * constructor that will return the type of the `DataObject`.
+ *
+ * @typeParam T - The class of the `DataObject`.
  */
 export type DataObjectClass<T extends IFluidLoadable>
     = { readonly factory: IFluidDataStoreFactory; } & LoadableObjectCtor<T>;
 
 /**
- * A SharedObjectClass is a class that has a factory that can create a DDS (SharedObject) and a
- * constructor that will return the type of the DataObject.
- * @typeParam T - The class of the SharedObject
+ * A class that has a factory that can create a DDSes (`SharedObject`s) and a
+ * constructor that will return the type of the `DataObject`.
+ *
+ * @typeParam T - The class of the `SharedObject`.
  */
 export type SharedObjectClass<T extends IFluidLoadable>
     = { readonly getFactory: () => IChannelFactory; } & LoadableObjectCtor<T>;
 
 /**
- * An object with a constructor that will return an `IFluidLoadable`.
- * @typeParam T - The class of the loadable object
+ * An object with a constructor that will return an {@link @fluidframework/core-interfaces#IFluidLoadable}.
+ *
+ * @typeParam T - The class of the loadable object.
  */
 export type LoadableObjectCtor<T extends IFluidLoadable> = new(...args: any[]) => T;
 
 /**
- * The ContainerSchema declares the Fluid objects that will be available in the container.  It includes both the
- * instances of objects that are initially available upon container creation, as well as the types of objects that may
- * be dynamically created throughout the lifetime of the container.
+ * Declares the Fluid objects that will be available in the {@link IFluidContainer | Container}.
+ *
+ * @remarks
+ *
+ * It includes both the instances of objects that are initially available upon `Container` creation, as well
+ * as the types of objects that may be dynamically created throughout the lifetime of the `Container`.
  */
 export interface ContainerSchema {
     /**
-     * Defines loadable objects that will be created when the `Container` is first created.
-     * It uses the key as the id and the value as the loadable object to create.
+     * Defines loadable objects that will be created when the {@link IFluidContainer | Container} is first created.
+     *
+     * @remarks It uses the key as the id and the value as the loadable object to create.
      *
      * @example
-     * In the example below two objects will be created when the Container is first
+     *
+     * In the example below two objects will be created when the `Container` is first
      * created. One with id "map1" that will return a `SharedMap` and the other with
      * id "pair1" that will return a `KeyValueDataObject`.
      *
-     * ```
+     * ```typescript
      * {
      *   map1: SharedMap,
      *   pair1: KeyValueDataObject,
@@ -72,7 +81,9 @@ export interface ContainerSchema {
     initialObjects: LoadableObjectClassRecord;
 
     /**
-     * Dynamic objects are Loadable objects that can be created after the initial Container creation.
+     * Loadable objects that can be created after the initial {@link IFluidContainer | Container} creation.
+     *
+     * @remarks
      *
      * Types defined in `initialObjects` will always be available and are not required to be provided here.
      *
@@ -83,61 +94,59 @@ export interface ContainerSchema {
 }
 
 /**
- * Events that trigger when the roster of members in the Fluid session change.
- * Only changes that would be reflected in the returned map of {@link IServiceAudience}'s
- * {@link IServiceAudience.getMembers} method will emit events.
- *
- * @remarks
- *
- * The following is the list of events emitted.
- *
- * ### "membersChanged"
- *
- * The "membersChanged" event is emitted when a member is either added or removed.
- *
- * #### Listener signature
- *
- * ```typescript
- * () => void;
- * ```
- *
- * ### "memberAdded"
- *
- * The "memberAdded" event is emitted when a member joins the audience.
- *
- * #### Listener signature
- *
- * ```typescript
- * (clientId: string, member: M) => void;
- * ```
- * - `clientId` - A unique identifier for the client
+ * Signature for {@link IMember} change events.
  *
- * - `member` - The service-specific member object for the client
+ * @param clientId - A unique identifier for the client.
+ * @param member - The service-specific member object for the client.
  *
- * ### "memberRemoved"
- *
- * The "memberRemoved" event is emitted when a member leaves the audience.
+ * @see See {@link IServiceAudienceEvents} for usage details.
+ */
+export type MemberChangedListener<M extends IMember> = (clientId: string, member: M) => void;
+
+/**
+ * Events that trigger when the roster of members in the Fluid session change.
  *
- * #### Listener signature
+ * @remarks
  *
- * ```typescript
- * (clientId: string, member: M) => void;
- * ```
- * - `clientId` - A unique identifier for the client
+ * Only changes that would be reflected in the returned map of {@link IServiceAudience}'s
+ * {@link IServiceAudience.getMembers} method will emit events.
  *
- * - `member` - The service-specific member object for the client
- * @typeParam M - A service-specific member type.
+ * @typeParam M - A service-specific {@link IMember} implementation.
  */
 export interface IServiceAudienceEvents<M extends IMember> extends IEvent {
+    /* eslint-disable @typescript-eslint/unified-signatures */
+    /**
+     * Emitted when a {@link IMember | member}(s) are either added or removed.
+     *
+     * @eventProperty
+     */
     (event: "membersChanged", listener: () => void): void;
-    (event: "memberAdded" | "memberRemoved", listener: (clientId: string, member: M) => void): void;
+
+    /**
+     * Emitted when a {@link IMember | member} joins the audience.
+     *
+     * @eventProperty
+     */
+    (event: "memberAdded", listener: MemberChangedListener<M>): void;
+
+    /**
+     * Emitted when a {@link IMember | member} leaves the audience.
+     *
+     * @eventProperty
+     */
+    (event: "memberRemoved", listener: MemberChangedListener<M>): void;
+    /* eslint-enable @typescript-eslint/unified-signatures */
 }
 
 /**
- * Base interface to be implemented to fetch each service's audience. The generic M allows consumers to further
- * extend the client object with service-specific details about the connecting client, such as device information,
- * environment, or a username.
- * @typeParam M - A service-specific member type.
+ * Base interface to be implemented to fetch each service's audience.
+ *
+ * @remarks
+ *
+ * The type parameter `M` allows consumers to further extend the client object with service-specific
+ * details about the connecting client, such as device information, environment, or a username.
+ *
+ * @typeParam M - A service-specific {@link IMember} type.
  */
 export interface IServiceAudience<M extends IMember> extends IEventProvider<IServiceAudienceEvents<M>> {
     /**
@@ -154,8 +163,9 @@ export interface IServiceAudience<M extends IMember> extends IEventProvider<ISer
 }
 
 /**
- * Base interface for information for each connection made to the Fluid session.  This interface can be extended
- * to provide additional information specific to each service.
+ * Base interface for information for each connection made to the Fluid session.
+ *
+ * @remarks This interface can be extended to provide additional information specific to each service.
  */
 export interface IConnection {
     /**
@@ -170,8 +180,9 @@ export interface IConnection {
 }
 
 /**
- * Base interface to be implemented to fetch each service's member.  This interface can be extended by each service
- * to provide additional service-specific user metadata.
+ * Base interface to be implemented to fetch each service's member.
+ *
+ * @remarks This interface can be extended by each service to provide additional service-specific user metadata.
  */
 export interface IMember {
     /**