@fluidframework/fluid-static 2.0.0-dev.1.4.6.106135 → 2.0.0-dev.2.2.0.111723

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,63 +94,82 @@ 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
- *
- * - `member` - The service-specific member object for the client
+ * Holds the collection of objects that the container was initially created with, as well as provides the ability
+ * to dynamically create further objects during usage.
+ */
+export interface IRootDataObject {
+    /**
+     * Provides a record of the initial objects defined on creation.
+     */
+    readonly initialObjects: LoadableObjectRecord;
+
+    /**
+     * 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`.
+     */
+    create<T extends IFluidLoadable>(objectClass: LoadableObjectClass<T>): Promise<T>;
+}
+
+/**
+ * Signature for {@link IMember} change events.
  *
- * ### "memberRemoved"
+ * @param clientId - A unique identifier for the client.
+ * @param member - The service-specific member object for the client.
  *
- * 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>> {
+export interface IServiceAudience<M extends IMember>
+    extends IEventProvider<IServiceAudienceEvents<M>> {
     /**
      * Returns an map of all users currently in the Fluid session where key is the userId and the value is the
      * member object.  The implementation may choose to exclude certain connections from the returned map.
@@ -150,12 +180,13 @@ export interface IServiceAudience<M extends IMember> extends IEventProvider<ISer
     /**
      * Returns the current active user on this client once they are connected. Otherwise, returns undefined.
      */
-    getMyself(): M | undefined;
+    getMyself(): Myself<M> | undefined;
 }
 
 /**
- * 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 +201,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 {
     /**
@@ -184,3 +216,8 @@ export interface IMember {
      */
     connections: IConnection[];
 }
+
+/**
+ * An extended member object that includes currentConnection
+ */
+export type Myself<M extends IMember = IMember> = M & { currentConnection: string; };