@fluidframework/container-definitions 2.0.0-internal.2.1.2 → 2.0.0-internal.2.2.1

package/src/deltas.ts

@@ -16,7 +16,7 @@ import {
 } from "@fluidframework/protocol-definitions";
 
 /**
- * Contract representing the result of a newly established connection to the server for syncing deltas
+ * Contract representing the result of a newly established connection to the server for syncing deltas.
  */
 export interface IConnectionDetails {
     clientId: string;
@@ -26,9 +26,13 @@ export interface IConnectionDetails {
     version: string;
     initialClients: ISignalClient[];
     serviceConfiguration: IClientConfiguration;
+
     /**
-     * Last known sequence number to ordering service at the time of connection
-     * It may lap actual last sequence number (quite a bit, if container  is very active).
+     * Last known sequence number to ordering service at the time of connection.
+     *
+     * @remarks
+     *
+     * It may lap actual last sequence number (quite a bit, if container is very active).
      * But it's the best information for client to figure out how far it is behind, at least
      * for "read" connections. "write" connections may use own "join" op to similar information,
      * that is likely to be more up-to-date.
@@ -61,21 +65,88 @@ export interface IDeltaSender {
     flush(): void;
 }
 
-/** Events emitted by the Delta Manager */
+/**
+ * Events emitted by {@link IDeltaManager}.
+ */
+/* eslint-disable @typescript-eslint/unified-signatures */
 export interface IDeltaManagerEvents extends IEvent {
+    /**
+     * @deprecated No replacement API recommended.
+     */
     (event: "prepareSend", listener: (messageBuffer: any[]) => void);
+
+    /**
+     * @deprecated No replacement API recommended.
+     */
     (event: "submitOp", listener: (message: IDocumentMessage) => void);
+
+    /**
+     * Emitted immediately after processing an incoming operation (op).
+     *
+     * @remarks
+     *
+     * Note: this event is not intended for general use.
+     * Prefer to listen to events on the appropriate ultimate recipients of the ops, rather than listening to the
+     * ops directly on the {@link IDeltaManager}.
+     *
+     * Listener parameters:
+     *
+     * - `message`: The op that was processed.
+     *
+     * - `processingTime`: The amount of time it took to process the inbound operation (op), expressed in milliseconds.
+     */
     (event: "op", listener: (message: ISequencedDocumentMessage, processingTime: number) => void);
+
+    /**
+     * @deprecated No replacement API recommended.
+     */
     (event: "allSentOpsAckd", listener: () => void);
-    (event: "pong" | "processTime", listener: (latency: number) => void);
+
+    /**
+     * @deprecated No replacement API recommended.
+     */
+    (event: "pong", listener: (latency: number) => void);
+
     /**
-     * The connect event fires once we've received the connect_document_success message from the
-     * server.  This happens prior to the client's join message (if there is a join message).
+     * @deprecated No replacement API recommended.
+     */
+    (event: "processTime", listener: (latency: number) => void);
+
+    /**
+     * Emitted when the {@link IDeltaManager} completes connecting to the Fluid service.
+     *
+     * @remarks
+     * This occurs once we've received the connect_document_success message from the server,
+     * and happens prior to the client's join message (if there is a join message).
+     *
+     * Listener parameters:
+     *
+     * - `details`: Connection metadata.
+     *
+     * - `opsBehind`: An estimate of far behind the client is relative to the service in terms of ops.
+     * Will not be specified if an estimate cannot be determined.
      */
     (event: "connect", listener: (details: IConnectionDetails, opsBehind?: number) => void);
+
+    /**
+     * Emitted when the {@link IDeltaManager} becomes disconnected from the Fluid service.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `reason`: Describes the reason for which the delta manager was disconnected.
+     */
     (event: "disconnect", listener: (reason: string) => void);
+
+    /**
+     * Emitted when read/write permissions change.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `readonly`: Whether or not the delta manager is now read-only.
+     */
     (event: "readonly", listener: (readonly: boolean) => void);
 }
+/* eslint-enable @typescript-eslint/unified-signatures */
 
 /**
  * Manages the transmission of ops between the runtime and storage.
@@ -132,15 +203,49 @@ export interface IDeltaManager<T, U> extends IEventProvider<IDeltaManagerEvents>
     submitSignal(content: any): void;
 }
 
-/** Events emitted by a Delta Queue */
+/**
+ * Events emitted by {@link IDeltaQueue}.
+ */
+/* eslint-disable @typescript-eslint/unified-signatures */
 export interface IDeltaQueueEvents<T> extends IErrorEvent {
-    (event: "push" | "op", listener: (task: T) => void);
     /**
-     * @param count - number of events (T) processed before becoming idle
-     * @param duration - amount of time it took to process elements (milliseconds).
+     * Emitted when a task is enqueued.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `task`: The task being enqueued.
+     */
+    (event: "push", listener: (task: T) => void);
+
+    /**
+     * Emitted immediately after processing an enqueued task and removing it from the queue.
+     *
+     * @remarks
+     *
+     * Note: this event is not intended for general use.
+     * Prefer to listen to events on the appropriate ultimate recipients of the ops, rather than listening to the
+     * ops directly on the {@link IDeltaQueue}.
+     *
+     * Listener parameters:
+     *
+     * - `task`: The task that was processed.
+     */
+    (event: "op", listener: (task: T) => void);
+
+    /**
+     * Emitted when the queue of tasks to process is emptied.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `count`: The number of events (`T`) processed before becoming idle.
+     *
+     * - `duration`: The amount of time it took to process elements (in milliseconds).
+     *
+     * @see {@link IDeltaQueue.idle}
      */
     (event: "idle", listener: (count: number, duration: number) => void);
 }
+/* eslint-enable @typescript-eslint/unified-signatures */
 
 /**
  * Queue of ops to be sent to or processed from storage
@@ -157,12 +262,14 @@ export interface IDeltaQueue<T> extends IEventProvider<IDeltaQueueEvents<T>>, ID
     length: number;
 
     /**
-     * Flag indicating whether or not the queue is idle
+     * Flag indicating whether or not the queue is idle.
+     * I.e. there are no remaining messages to processes.
      */
     idle: boolean;
 
     /**
-     * Pauses processing on the queue
+     * Pauses processing on the queue.
+     *
      * @returns A promise which resolves when processing has been paused.
      */
     pause(): Promise<void>;

package/src/error.ts

@@ -76,7 +76,8 @@ export interface IErrorBase extends Partial<Error> {
 export interface ContainerWarning extends IErrorBase {
     /**
      * Whether this error has already been logged. Used to avoid logging errors twice.
-     * Default is false.
+     *
+     * @defaultValue `false`
      */
     logged?: boolean;
 }

package/src/loader.ts

@@ -54,7 +54,7 @@ export interface IFluidModuleWithDetails {
 export interface ICodeDetailsLoader
     extends Partial<IProvideFluidCodeDetailsComparer> {
     /**
-     * Load the code module (package) that is capable to interact with the document.
+     * Load the code module (package) that can interact with the document.
      *
      * @param source - Code proposal that articulates the current schema the document is written in.
      * @returns - Code module entry point along with the code details associated with it.
@@ -63,7 +63,7 @@ export interface ICodeDetailsLoader
 }
 
 /**
-* The interface returned from a IFluidCodeResolver which represents IFluidCodeDetails
+ * The interface returned from a IFluidCodeResolver which represents IFluidCodeDetails
  * that have been resolved and are ready to load
  */
 export interface IResolvedFluidCodeDetails extends IFluidCodeDetails {
@@ -102,23 +102,147 @@ export interface ICodeAllowList {
 }
 
 /**
- * Events emitted by the Container "upwards" to the Loader and Host
+ * Events emitted by the {@link IContainer} "upwards" to the Loader and Host.
  */
+/* eslint-disable @typescript-eslint/unified-signatures */
 export interface IContainerEvents extends IEvent {
+    /**
+     * Emitted when the readonly state of the container changes.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `readonly`: Whether or not the container is now in a readonly state.
+     *
+     * @see {@link IContainer.readOnlyInfo}
+     */
     (event: "readonly", listener: (readonly: boolean) => void): void;
+
+    /**
+     * Emitted when the {@link IContainer} completes connecting to the Fluid service.
+     *
+     * @remarks Reflects connection state changes against the (delta) service acknowledging ops/edits.
+     *
+     * @see
+     *
+     * - {@link IContainer.connectionState}
+     *
+     * - {@link IContainer.connect}
+     */
     (event: "connected", listener: (clientId: string) => void);
+
+    /**
+     * Fires when new container code details have been proposed, prior to acceptance.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `codeDetails`: The code details being proposed.
+     *
+     * - `proposal`: NOT RECOMMENDED FOR USE.
+     *
+     * @see {@link IContainer.proposeCodeDetails}
+     */
     (event: "codeDetailsProposed", listener: (codeDetails: IFluidCodeDetails, proposal: ISequencedProposal) => void);
+
+    /**
+     * @deprecated No replacement API recommended.
+     */
     (event: "contextChanged", listener: (codeDetails: IFluidCodeDetails) => void);
-    (event: "disconnected" | "attached", listener: () => void);
+
+    /**
+     * Emitted when the {@link IContainer} becomes disconnected from the Fluid service.
+     *
+     * @remarks Reflects connection state changes against the (delta) service acknowledging ops/edits.
+     *
+     * @see
+     *
+     * - {@link IContainer.connectionState}
+     *
+     * - {@link IContainer.disconnect}
+     */
+    (event: "disconnected", listener: () => void);
+
+    /**
+     * Emitted when a {@link AttachState.Detached | detached} container is
+     * {@link AttachState.Attached | attached} to the Fluid service.
+     *
+     * @see
+     *
+     * - {@link IContainer.attachState}
+     *
+     * - {@link IContainer.attach}
+     */
+    (event: "attached", listener: () => void);
+
+    /**
+     * Emitted when the {@link IContainer} is closed, which permanently disables it.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `error`: If the container was closed due to error, this will contain details about the error that caused it.
+     *
+     * @see {@link IContainer.close}
+     */
     (event: "closed", listener: (error?: ICriticalContainerError) => void);
+
+    /**
+     * Emitted when the container encounters a state which may lead to errors, which may be actionable by the consumer.
+     *
+     * @remarks
+     *
+     * Note: this event is not intended for general use.
+     * The longer-term intention is to surface warnings more directly on the APIs that produce them.
+     * For now, use of this should be avoided when possible.
+     *
+     * Listener parameters:
+     *
+     * - `error`: The warning describing the encountered state.
+     */
     (event: "warning", listener: (error: ContainerWarning) => void);
+
+    /**
+     * Emitted immediately after processing an incoming operation (op).
+     *
+     * @remarks
+     *
+     * Note: this event is not intended for general use.
+     * Prefer to listen to events on the appropriate ultimate recipients of the ops, rather than listening to the
+     * ops directly on the {@link IContainer}.
+     *
+     * Listener parameters:
+     *
+     * - `message`: The op that was processed.
+     */
     (event: "op", listener: (message: ISequencedDocumentMessage) => void);
-    (event: "dirty" | "saved", listener: (dirty: boolean) => void);
+
+    /**
+     * Emitted upon the first local change while the Container is in the "saved" state.
+     * That is, when {@link IContainer.isDirty} transitions from `true` to `false`.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `dirty`: DEPRECATED. This parameter will be removed in a future release.
+     *
+     * @see {@link IContainer.isDirty}
+     */
+    (event: "dirty", listener: (dirty: boolean) => void);
+
+    /**
+     * Emitted when all local changes/edits have been acknowledged by the service.
+     * I.e., when {@link IContainer.isDirty} transitions from `false` to `true`.
+     *
+     * @remarks Listener parameters:
+     *
+     * - `dirty`: DEPRECATED. This parameter will be removed in a future release.
+     *
+     * @see {@link IContainer.isDirty}
+     */
+    (event: "saved", listener: (dirty: boolean) => void);
 }
+/* eslint-enable @typescript-eslint/unified-signatures */
 
 /**
- * Namespace for the different connection states a container can be in
- * PLEASE NOTE: The sequence of the numerical values does no correspond to the typical connection state progression
+ * Namespace for the different connection states a container can be in.
+ * PLEASE NOTE: The sequence of the numerical values does no correspond to the typical connection state progression.
  */
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace ConnectionState {
@@ -147,7 +271,7 @@ export namespace ConnectionState {
 }
 
 /**
- * Type defining the different states of connectivity a container can be in.
+ * Type defining the different states of connectivity a Container can be in.
  */
 export type ConnectionState =
     | ConnectionState.Disconnected
@@ -156,7 +280,7 @@ export type ConnectionState =
     | ConnectionState.Connected;
 
 /**
- * The Host's view of the Container and its connection to storage
+ * The Host's view of a Container and its connection to storage
  */
 export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRouter {
 
@@ -172,7 +296,7 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
     getQuorum(): IQuorumClients;
 
     /**
-     * Represents the resolved url to the Container
+     * Represents the resolved url to the Container.
      * Will be undefined only when the container is in the {@link AttachState.Detached | detatched} state.
      */
     resolvedUrl: IResolvedUrl | undefined;
@@ -196,54 +320,57 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
     getLoadedCodeDetails(): IFluidCodeDetails | undefined;
 
     /**
-     * Returns true if the container has been closed, otherwise false
+     * Returns true if the container has been closed, otherwise false.
      */
     readonly closed: boolean;
 
     /**
-     * Returns true if the container is dirty, i.e. there are user changes that has not been saved
-     * Closing container in this state results in data loss for user.
-     * Container usually gets into this situation due to loss of connectivity.
+     * Whether or not there are any local changes that have not been saved.
      */
     readonly isDirty: boolean;
 
     /**
-     * Closes the container
+     * Closes the container.
+     *
+     * @param error - If the container is being closed due to error, this provides details about the error that
+     * resulted in closing it.
      */
     close(error?: ICriticalContainerError): void;
 
     /**
      * Closes the container and returns serialized local state intended to be
-     * given to a newly loaded container
+     * given to a newly loaded container.
      */
     closeAndGetPendingLocalState(): string;
 
     /**
-     * Propose new code details that define the code to be loaded
-     * for this container's runtime. The returned promise will
-     * be true when the proposal is accepted, and false if
-     * the proposal is rejected.
+     * Propose new code details that define the code to be loaded for this container's runtime.
+     *
+     * The returned promise will be true when the proposal is accepted, and false if the proposal is rejected.
      */
     proposeCodeDetails(codeDetails: IFluidCodeDetails): Promise<boolean>;
 
     /**
      * Attaches the Container to the Container specified by the given Request.
      *
-     * TODO - in the case of failure options should give a retry policy. Or some continuation function
-     * that allows attachment to a secondary document.
+     * @privateRemarks
+     *
+     * TODO - in the case of failure options should give a retry policy.
+     * Or some continuation function that allows attachment to a secondary document.
      */
     attach(request: IRequest): Promise<void>;
 
     /**
-     * Extract the snapshot from the detached container.
+     * Extract a snapshot of the container as long as it is in detached state. Calling this on an attached container
+     * is an error.
      */
     serialize(): string;
 
     /**
-     * Get an absolute url for a provided container-relative request url.
+     * Get an absolute URL for a provided container-relative request URL.
      * If the container is not attached, this will return undefined.
      *
-     * @param relativeUrl - A container-relative request URL
+     * @param relativeUrl - A container-relative request URL.
      */
     getAbsoluteUrl(relativeUrl: string): Promise<string | undefined>;
 
@@ -254,34 +381,50 @@ export interface IContainer extends IEventProvider<IContainerEvents>, IFluidRout
     request(request: IRequest): Promise<IResponse>;
 
     /**
-     * Provides the current state of the container's connection to the ordering service
+     * Provides the current state of the container's connection to the ordering service.
+     *
+     * @remarks Consumers can listen for state changes via the "connected" and "disconnected" events.
      */
     readonly connectionState: ConnectionState;
 
     /**
-     * Attempts to connect the container to the delta stream and process ops
+     * Attempts to connect the container to the delta stream and process ops.
+     *
+     * @remarks
+     *
+     * {@link IContainer.connectionState} will be set to {@link (ConnectionState:namespace).Connected}, and the
+     * "connected" event will be fired if/when connection succeeds.
      */
     connect(): void;
 
     /**
-     * Disconnects the container from the delta stream and stops processing ops
+     * Disconnects the container from the delta stream and stops processing ops.
+     *
+     * @remarks
+     *
+     * {@link IContainer.connectionState} will be set to {@link (ConnectionState:namespace).Disconnected}, and the
+     * "disconnected" event will be fired when disconnection completes.
      */
     disconnect(): void;
 
     /**
-     * The audience information for all clients currently associated with the document in the current session
+     * The audience information for all clients currently associated with the document in the current session.
      */
     readonly audience: IAudience;
 
     /**
      * The server provided ID of the client.
-     * Set once this.connectionState === ConnectionState.Connected is true, otherwise undefined
-     * @alpha
+     *
+     * Set once {@link IContainer.connectionState} is {@link (ConnectionState:namespace).Connected},
+     * otherwise will be `undefined`.
      */
     readonly clientId?: string | undefined;
 
     /**
      * Tells if container is in read-only mode.
+     *
+     * @remarks
+     *
      * Data stores should listen for "readonly" notifications and disallow user making changes to data stores.
      * Readonly state can be because of no storage write permission,
      * or due to host forcing readonly mode for container.
@@ -310,6 +453,8 @@ export interface ILoader extends IFluidRouter, Partial<IProvideLoader> {
      * Resolves the resource specified by the URL + headers contained in the request object
      * to the underlying container that will resolve the request.
      *
+     * @remarks
+     *
      * An analogy for this is resolve is a DNS resolve of a Fluid container. Request then executes
      * a request against the server found from the resolve step.
      */
@@ -337,27 +482,27 @@ export type ILoaderOptions = {
     [key in string | number]: any;
 } & {
     /**
-     * Set caching behavior for the loader.  If true, we will load a container from cache if one
+     * Set caching behavior for the loader. If true, we will load a container from cache if one
      * with the same id/version exists or create a new container and cache it if it does not. If
      * false, always load a new container and don't cache it. If the container has already been
-     * closed, it will not be cached.  A cache option in the LoaderHeader for an individual
+     * closed, it will not be cached. A cache option in the LoaderHeader for an individual
      * request will override the Loader's value.
      * Defaults to true.
      */
     cache?: boolean;
 
     /**
-     * Provide the current Loader through the scope object when creating Containers.  It is added
+     * Provide the current Loader through the scope object when creating Containers. It is added
      * as the `ILoader` property, and will overwrite an existing property of the same name on the
-     * scope.  Useful for when the host wants to provide the current Loader's functionality to
+     * scope. Useful for when the host wants to provide the current Loader's functionality to
      * individual Data Stores, which is typically expected when creating with a Loader.
      * Defaults to true.
      */
     provideScopeLoader?: boolean;
 
     /**
-     * Max time(in ms) container will wait for a leave message of a disconnected client.
-    */
+     * Max time (in ms) container will wait for a leave message of a disconnected client.
+     */
     maxClientLeaveWaitTime?: number;
 };
 
@@ -409,6 +554,7 @@ export interface IContainerLoadMode {
      * recommended to have some progress UX / cancellation built into loading flow when using this option.
      */
     | "all";
+
     deltaConnection?:
     /*
      * Connection to delta stream is made only when Container.connect() call is made. Op processing
@@ -449,7 +595,7 @@ export interface IProvideLoader {
 /**
  * @deprecated 0.48, This API will be removed in 0.50
  * No replacement since it is not expected anyone will depend on this outside container-loader
- * See https://github.com/microsoft/FluidFramework/issues/9711 for context
+ * See {@link https://github.com/microsoft/FluidFramework/issues/9711} for context.
  */
 export interface IPendingLocalState {
     url: string;
@@ -458,8 +604,9 @@ export interface IPendingLocalState {
 
 /**
  * This is used when we rehydrate a container from the snapshot. Here we put the blob contents
- * in separate property: blobContents. This is used as the ContainerContext's base snapshot
- * when attaching.
+ * in separate property: {@link ISnapshotTreeWithBlobContents.blobsContents}.
+ *
+ * @remarks This is used as the `ContainerContext`'s base snapshot when attaching.
  */
 export interface ISnapshotTreeWithBlobContents extends ISnapshotTree {
     blobsContents: { [path: string]: ArrayBufferLike; };

package/src/runtime.ts

@@ -108,8 +108,9 @@ export interface IRuntime extends IDisposable {
  * Payload type for IContainerContext.submitBatchFn()
  */
 export interface IBatchMessage {
-    contents: string;
+    contents?: string;
     metadata: Record<string, unknown> | undefined;
+    compression?: string;
 }
 
 /**