@fluidframework/container-loader 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.225277

package/README.md

@@ -1,30 +1,55 @@
 # @fluidframework/container-loader
 
+<!-- AUTO-GENERATED-CONTENT:START (README_DEPENDENCY_GUIDELINES_SECTION:includeHeading=TRUE) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Using Fluid Framework libraries
+
+When taking a dependency on a Fluid Framework library, we recommend using a `^` (caret) version range, such as `^1.3.4`.
+While Fluid Framework libraries may use different ranges with interdependencies between other Fluid Framework libraries,
+library consumers should always prefer `^`.
+
+Note that when depending on a library version of the form `2.0.0-internal.x.y.z`, called the Fluid internal version scheme,
+you must use a `>= <` dependency range (such as `>=2.0.0-internal.x.y.z <2.0.0-internal.w.0.0` where `w` is `x+1`).
+Standard `^` and `~` ranges will not work as expected.
+See the [@fluid-tools/version-tools](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/version-tools/README.md)
+package for more information including tools to convert between version schemes.
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->
+
 **Topics covered below:**
 
-- [@fluidframework/container-loader](#fluidframeworkcontainer-loader)
-  - [Fluid Loader](#fluid-loader)
-  - [Expectations from host implementers](#expectations-from-host-implementers)
-  - [Expectations from container runtime and data store implementers](#expectations-from-container-runtime-and-data-store-implementers)
-  - [Container Lifetime](#container-lifetime)
-    - [Loading](#loading)
-    - [Connectivity](#connectivity)
-    - [Closure](#closure)
-  - [Audience](#audience)
-  - [ClientID and client identification](#clientid-and-client-identification)
-  - [Error handling](#error-handling)
-  - [Connectivity events](#connectivity-events)
-  - [Readonly states](#readonly-states)
-    - [`readonly`](#readonly)
-    - [`permissions`](#permissions)
-    - [`forced`](#forced)
-    - [`storageOnly`](#storageonly)
-  - [Dirty events](#dirty-events)
+-   [@fluidframework/container-loader](#fluidframeworkcontainer-loader)
+    -   [Using Fluid Framework libraries](#using-fluid-framework-libraries)
+    -   [Fluid Loader](#fluid-loader)
+    -   [Expectations from host implementers](#expectations-from-host-implementers)
+    -   [Expectations from container runtime and data store implementers](#expectations-from-container-runtime-and-data-store-implementers)
+    -   [Container Lifetime](#container-lifetime)
+        -   [Loading](#loading)
+        -   [Connectivity](#connectivity)
+        -   [Closure](#closure)
+            -   [`Container.close()`](#containerclose)
+            -   [`Container.dispose()`](#containerdispose)
+    -   [Audience](#audience)
+    -   [ClientID and client identification](#clientid-and-client-identification)
+    -   [Error handling](#error-handling)
+    -   [Connectivity events](#connectivity-events)
+    -   [Connection State Transitions Flow Chart](#connection-state-transitions-flow-chart)
+    -   [Readonly states](#readonly-states)
+        -   [`readonly`](#readonly)
+        -   [`permissions`](#permissions)
+        -   [`forced`](#forced)
+        -   [`storageOnly`](#storageonly)
+    -   [Dirty events](#dirty-events)
+    -   [Trademark](#trademark)
 
 **Related topics covered elsewhere:**
 
-- [Quorum and Proposals](../../../server/routerlicious/packages/protocol-base/README.md)
-
+-   [Quorum and Proposals](../../../server/routerlicious/packages/protocol-base/README.md)
 
 ## Fluid Loader
 
@@ -45,6 +70,7 @@ Please see specific sections for more details on these states and events - this
 2. ["closed"](#Closure) event: If raised with error, host is responsible for conveying error in some form to the user. Container is left in disconnected & readonly state when it is closed (because of error or not).
 3. ["readonly"](#Readonly-states) event: Host should have some indication to user that container is not editable. User permissions can change over lifetime of Container, but they can't change per connection session (in other words, change in permissions causes disconnect and reconnect). Hosts are advised to recheck this property on every reconnect.
 4. [Dirty events](#Dirty-events): Host should have some reasonable UX / workflows to ensure user does not lose edits unexpectedly. I.e. there is enough signals (potentially including blocking user from closing container) ensuring that all user edits make it to storage, unless user explicitly choses to lose such edits.
+5. [Closing or disposing containers](#containerclose): For most cases, you should use the `IContainer.dispose(...)` API to free up resources. If you intend on using the container after closure, or need to pass some critical error to the container, use the `IContainer.close(...)` API.
 
 ## Expectations from container runtime and data store implementers
 
@@ -60,42 +86,63 @@ Please see specific sections for more details on these states and events - this
 
 Container is returned as result of Loader.resolve() call. Loader can cache containers, so if same URI is requested from same loader instance, earlier created container might be returned. This is important, as some of the headers (like `pause`) might be ignored because of Container reuse.
 
-`ILoaderHeader` in [loader.ts](../../../common/lib/container-definitions/src/loader.ts) describes properties controlling container loading.
+`ILoaderHeader` in [loader.ts](../../common/container-definitions/src/loader.ts) describes properties controlling container loading.
 
 ### Connectivity
 
-Usually container is returned when state of container (and data stores) is rehydrated from snapshot. Unless `IRequest.headers.pause` is specified, connection to ordering service will be established at some point (asynchronously) and latest Ops would be processed, allowing local changes to flow form client to server. `Container.connectionState` indicates whether connection to ordering service is established, and  [Connectivity events](#Connectivity-events) are notifying about connectivity changes. While it's highly recommended for listeners to check initial state at the moment they register for connectivity events, new listeners are called on registration to propagate current state. That is, if a container is disconnected when both "connected" and "disconnected" listeners are installed, newly installed listeners for "disconnected" event will be called on registration.
+Usually container is returned when state of container (and data stores) is rehydrated from snapshot. Unless `IRequest.headers.pause` is specified, connection to ordering service will be established at some point (asynchronously) and latest Ops would be processed, allowing local changes to flow form client to server. `Container.connectionState` indicates whether connection to ordering service is established, and [Connectivity events](#Connectivity-events) are notifying about connectivity changes. While it's highly recommended for listeners to check initial state at the moment they register for connectivity events, new listeners are called on registration to propagate current state. That is, if a container is disconnected when both "connected" and "disconnected" listeners are installed, newly installed listeners for "disconnected" event will be called on registration.
 
 ### Closure
 
-Container can be closed directly by host by calling `Container.close()`. Once closed, container terminates connection to ordering service, and any local changes (former or future) do not propagate to storage.
+Container can be closed directly by host by calling `Container.close()` and/or `Container.dispose()`. If the container is expected to be used upon closure, or you need to pass your own critical error to the container, use the `close()` API. Otherwise, use the `dispose()` API. The differences between these methods are detailed in the sections below.
+
+#### `Container.close()`
 
-Container can also be closed by runtime itself as result of some critical error. Critical errors can be internal (like violation in op ordering invariants), or external (file was deleted). Please see [Error Handling](#Error-handling) for more details
+Once closed, container terminates connection to ordering service, and any local changes (former or future) do not propagate to storage. This method is to be used when the container **IS** still expected to be used and the container needs to be switched to a "safe" state for viewing. For example, allowing a user to copy the content out of a container.
+
+The "closed" state effectively means the container is disconnected forever and cannot be reconnected.
+
+If after some time a closed container is no longer needed, calling `Container.dispose()` will dispose the runtime resources.
+
+Container can also be closed and/or disposed by runtime itself as result of some critical error. Critical errors can be internal (like violation in op ordering invariants), or external (file was deleted). Please see [Error Handling](#Error-handling) for more details.
 
 When container is closed, the following is true (in no particular order):
 
 1. Container.closed property is set to true
 2. "closed" event fires on container with optional error object (indicating reason for closure; if missing - closure was due to host closing container)
-3. "readonly" event fires on DeltaManager & Container (and Container.readonly property is set to true)  indicating to all data stores that container is read-only, and data stores should not allow local edits, as they are not going to make it.
+3. "readonly" event fires on DeltaManager & Container (and Container.readonly property is set to true) indicating to all data stores that container is read-only, and data stores should not allow local edits, as they are not going to make it.
 4. "disconnected" event fires, if connection was active at the moment of container closure.
 
-`"closed"` event is available on Container for hosts. `"disposed"` event is delivered to container runtime when container is closed. But container runtime can be also disposed when new code proposal is made and new version of the code (and container runtime) is loaded in accordance with it.
+`"closed"` event is available on Container for hosts.
+
+#### `Container.dispose()`
+
+Once disposed, container terminates connection to ordering service, and any local changes (former or future) do not propagate to storage. This method is to be used when the container is **NOT** expected to be used anymore.
+
+When container is disposed, the following is true (in no particular order):
+
+1. Container.closed property is set to true
+2. "disposed" event fires on container
+3. "disconnected" event fires, if connection was active at the moment of container disposal.
+4. "dispose" event fires on container runtime
+
+`"disposed"` event is available on Container for hosts. `"dispose"` event is delivered to container runtime when container is disposed, but container runtime can be also disposed when new code proposal is made and new version of the code (and container runtime) is loaded in accordance with it.
 
 ## Audience
 
 `Container.audience` exposes an object that tracks all connected clients to same container.
 
-- `getMembers()` can be used to retrieve current set of users
-- `getMember()` can be used to get IClient information about particular client (returns undefined if such client is not connected)
-- `"addMember"` event is raised when new member joins
-- `"removeMember"` event is raised when an earlier connected member leaves (disconnects from container)
+-   `getMembers()` can be used to retrieve current set of users
+-   `getMember()` can be used to get IClient information about particular client (returns undefined if such client is not connected)
+-   `"addMember"` event is raised when new member joins
+-   `"removeMember"` event is raised when an earlier connected member leaves (disconnects from container)
 
 `getMembers()` and `"addMember"` event provide _IClient_ interface that describes type of connection, permissions and user information:
 
-- clientId is the key - it is unique ID for a session. Please see [ClientID and client identification](#ClientId-and-client-identification) for more details on it, as well as how to properly differentiate human vs. agent clients and difference between client ID & user ID.
-- IClient.mode in particular describes connectivity mode of a client:
-  - "write" means client has read/write connection, can change container contents, and participates in Quorum
-  - "read" indicates client as read connection. Such clients can't modify container and do not participate in quorum. That said, "read" does not indicate client permissions, i.e. client might have read-only permissions to a file, or maybe connected temporarily as read-only, to reduce COGS on server and not "modify" container (any read-write connection generates join & leave messages that modify container and change "last edited by" property)
+-   clientId is the key - it is unique ID for a session. Please see [ClientID and client identification](#ClientId-and-client-identification) for more details on it, as well as how to properly differentiate human vs. agent clients and difference between client ID & user ID.
+-   IClient.mode in particular describes connectivity mode of a client:
+    -   "write" means client has read/write connection, can change container contents, and participates in Quorum
+    -   "read" indicates client as read connection. Such clients can't modify container and do not participate in quorum. That said, "read" does not indicate client permissions, i.e. client might have read-only permissions to a file, or maybe connected temporarily as read-only, to reduce COGS on server and not "modify" container (any read-write connection generates join & leave messages that modify container and change "last edited by" property)
 
 Please note that if this client losses connection to ordering server, then audience information is not reset at that moment. It will become stale while client is disconnected, and will refresh the moment client connects back to container. For more details, please see [Connectivity events](#Connectivity-events) section
 
@@ -117,19 +164,20 @@ There are two ways errors are exposed:
 
 Critical errors can show up in #1 & #2 workflows. For example, data store URI may point to a deleted file, which will result in errors on container open. But file can also be deleted while container is opened, resulting in same error type being raised through "error" handler.
 
-Errors are of [ICriticalContainerError](../../../common/lib/container-definitions/src/error.ts) type, and warnings are of [ContainerWarning](../../../common/lib/container-definitions/src/error.ts) type. Both have `errorType` property, describing type of an error (and appropriate interface of error object):
+Errors are of [ICriticalContainerError](../../common/container-definitions/src/error.ts) type, and warnings are of [ContainerWarning](../../common/container-definitions/src/error.ts) type. Both have `errorType` property, describing type of an error (and appropriate interface of error object):
 
 ```ts
      readonly errorType: string;
 ```
 
-There are 3 sources of errors:
+There are 4 sources of errors:
 
-1. [ContainerErrorType](../../../common/lib/container-definitions/src/error.ts) - errors & warnings raised at loader level
-2. [OdspErrorType](../../drivers/odsp-driver/src/odspError.ts) and [R11sErrorType](../../drivers/routerlicious-driver/src/documentDeltaConnection.ts) - errors raised by ODSP and R11S drivers.
-3. Runtime errors, like `"summarizingError"`, `"dataCorruptionError"`. This class of errors is not pre-determined and depends on type of container loaded.
+1. [ContainerErrorType](../../common/container-definitions/src/error.ts) - errors & warnings raised at loader level
+2. [DriverErrorType](../../common/driver-definitions/src/driverError.ts) - errors that are likely to be raised from the driver level
+3. [OdspErrorType](../../drivers/odsp-driver/src/odspError.ts) and [RouterliciousErrorType](../../drivers/routerlicious-driver/src/documentDeltaConnection.ts) - errors raised by ODSP and R11S drivers.
+4. Runtime errors, like `"summarizingError"`, `"dataCorruptionError"`. This class of errors is not pre-determined and depends on type of container loaded.
 
-`ICriticalContainerError.errorType` is a string, which represents a union of 3 error types described above. Hosting application may package different drivers and open different types of containers, and only hosting application may have enough information to enumerate all possible error codes in such scenarios.
+`ICriticalContainerError.errorType` is a string, which represents a union of 4 error types described above. Hosting application may package different drivers and open different types of containers, and only hosting application may have enough information to enumerate all possible error codes in such scenarios.
 
 Hosts must listen to `"closed"` event. If error object is present there, container was closed due to error and this information needs to be communicated to user in some way. If there is no error object, it was closed due to host application calling Container.close() (without specifying error).
 When container is closed, it is no longer connected to ordering service. It is also in read-only state, communicating to data stores not to allow user to make changes to container.
@@ -138,53 +186,101 @@ When container is closed, it is no longer connected to ordering service. It is a
 
 Container raises two events to notify hosting application about connectivity issues and connectivity status.
 
-- `"connected"` event is raised when container is connected and is up-to-date, i.e. changes are flowing between client and server.
-- `"disconnected"` event is raised when container lost connectivity (for any reason).
+-   `"connected"` event is raised when container is connected and is up-to-date, i.e. changes are flowing between client and server.
+-   `"disconnected"` event is raised when container lost connectivity (for any reason).
 
 Container also exposes `Container.connectionState` property to indicate current state.
 
-In normal circumstances, container will attempt to reconnect back to ordering service as quickly as possible. But it will scale down retries if computer is offline.  That said, if IThrottlingWarning is raised through `"warning"` handler, then container is following storage throttling policy and will attempt to reconnect after some amount of time (`IThrottlingWarning.retryAfterSeconds`).
+In normal circumstances, container will attempt to reconnect back to ordering service as quickly as possible. But it will scale down retries if computer is offline. That said, if IThrottlingWarning is raised through `"warning"` handler, then container is following storage throttling policy and will attempt to reconnect after some amount of time (`IThrottlingWarning.retryAfterSeconds`).
 
 Container will also not attempt to reconnect on lost connection if `Container.disconnect()` was called prior to loss of connection. This can be useful if the hosting application implements "user away" type of experience to reduce cost on both client and server of maintaining connection while user is away. Calling `Container.connect()` will reenable automatic reconnections, but the host might need to allow extra time for reconnection as it likely involves token fetch and processing of a lot of Ops generated by other clients while it was not connected.
 
-Data stores should almost never listen to these events (see more on [Readonly states](#Readonly-states), and should use consensus DDSes if they need to synchronize activity across clients. DDSes listen for these events to know when to resubmit pending Ops.
+Data stores should almost never listen to these events (see more on [Readonly states](#Readonly-states)), and should use consensus DDSes if they need to synchronize activity across clients. DDSes listen for these events to know when to resubmit pending Ops.
 
-Hosting application can use these events in order to indicate to user when user changes are not propagating through the system, and thus can be lost (on browser tab being closed). It's advised to use some delay (like 5 seconds) before showing such UI, as network connectivity might be intermittent.  Also if container was offline for very long period of time due to `Container.disconnect()` being called, it might take a while to get connected and current.
+Hosting application can use these events in order to indicate to user when user changes are not propagating through the system, and thus can be lost (on browser tab being closed). It's advised to use some delay (like 5 seconds) before showing such UI, as network connectivity might be intermittent. Also if container was offline for very long period of time due to `Container.disconnect()` being called, it might take a while to get connected and current.
 
 Please note that hosts can implement various strategies on how to handle disconnections. Some may decide to show some UX letting user know about potential loss of data if container is closed while disconnected. Others can force container to disallow user edits while offline (see [Readonly states](#Readonly-states)).
 
 It's worth pointing out that being connected does not mean all user edits are preserved on container closure. There is latency in the system, and loader layer does not provide any guarantees here. Not every implementation needs a solution here (games likely do not care), and thus solving this problem is pushed to framework level (i.e. having a data store that can expose `'dirtyDocument'` signal from ContainerRuntime and request route that can return such data store).
 
+## Connection State Transitions Flow Chart
+
+```mermaid
+flowchart TD;
+    A(Disconnected)-->B{Reconnect on error if \n AutoReconnect Enabled?};
+    B--Yes-->C(Establishing Connection);
+    B--No-->D[Connection during Container \n connect call];
+    D-->C
+    C-->E{Connection Success \n including any Retry?};
+    E--No-->F[Error or container.close or container.disconnect];
+    A-->F;
+    F-->A;
+    E--Yes-->G(Catching Up);
+    G-->F;
+    G-->H{Which Connection Mode?};
+    H--Read-->I(Connected);
+    H--Write-->J[Wait for Join Op];
+    J-->I;
+    I-->F;
+```
+
 ## Readonly states
+
 User permissions can change over lifetime of Container. They can't change during single connection session (in other words, change in permissions causes disconnect and reconnect). Hosts are advised to recheck this property on every reconnect.
 
 DeltaManager will emit a `"readonly"` event when transitioning to a read-only state. Readonly events are accessible by data stores and DDSes (through ContainerRuntime.deltaManager). It's expected that data stores adhere to requirements and expose read-only (or rather 'no edit') experiences.
 
-`Container.readOnlyInfo` (and `DeltaManager.readOnlyInfo`) indicates to host if file is writable or not.
+`Container.readOnlyInfo` (and `DeltaManager.readOnlyInfo`) indicates to the host if the file is writable or not.
+It contains the following properties:
+
 ### `readonly`
-one of the following:
-- true: Container is readonly. One or more of the additional properties listed below will be true.
-- undefined: Runtime does not know yet if file is writable or not. Currently we get a signal here only when websocket connection is made to the server.
-- false: Container.forceReadonly() was never called or last call was with false, plus it's known that user has write permissions to a file.
+
+One of the following:
+
+-   `true`: Container is read-only. One or more of the additional properties listed below will be `true`.
+-   `undefined`: Runtime does not know yet if file is writable or not. Currently we get a signal here only when websocket connection is made to the server.
+-   `false`: Container.forceReadonly() was never called or last call was with false, plus it's known that user has write permissions to a file.
 
 ### `permissions`
-There are two cases when it's true:
 
-1. User has no write permissions to to modify this container (which usually maps to file in storage, and lack of write permissions by a given user)
+There are two cases when it's `true`:
+
+1. User has no write permissions to modify this container (which usually maps to file in storage, and lack of write permissions by a given user)
 2. Container was closed, either due to critical error, or due to host closing container. See [Container Lifetime](#Container-lifetime) and [Error Handling](#Error-handling) for more details.
 
 ### `forced`
-Hosts can also force readonly-mode for a container via calling `Container.forceReadonly(true)`. This can be useful in scenarios like:
 
-- Loss of connectivity, in scenarios where host chooses method of preventing user edits over (or in addition to) showing disconnected UX and warning user of potential data loss on closure of container
-- Special view-only mode in host. For example can be used by hosts for previewing container content in-place with other host content, and leveraging full-screen / separate window experience for editing.
+`true` if the Container is in read-only mode due to the host calling `Container.forceReadonly(true)`.
+This can be useful in scenarios like:
+
+-   Loss of connectivity, in scenarios where host chooses method of preventing user edits over (or in addition to) showing disconnected UX and warning user of potential data loss on closure of container.
+-   Special view-only mode in host. For example can be used by hosts for previewing container content in-place with other host content, and leveraging full-screen / separate window experience for editing.
 
 ### `storageOnly`
-Storage-only mode is a readonly mode in which the container does not connect to the delta stream and is unable to submit or recieve ops. This is useful for viewing a specific version of a document.
+
+Storage-only mode is a read-only mode in which the container does not connect to the delta stream and is unable to submit or receive ops. This is useful for viewing a specific version of a document.
 
 ## Dirty events
+
 The Container runtime can communicate with the container to get the container's current state. In response, the container will raise two events - `"dirty"` and `"saved"` events. Transitions between these two events signify presence (or lack of) user changes that were not saved to storage. In other words, if container is dirty, closing it at that moment will result in data loss from user perspective, because not all user changes made it to storage.
 This information can be used by a host to build appropriate UX that allows user to be confident in the platform. For example, a host may chose to show a dialog asking the user if they want to save their changes before closing. Instead of, or in addition to this, the host may choose to show "Saving..." and "Saved" text somewhere in UX. Coupled with lack of connectivity to ordering service (and appropriate notification to the user) that may create enough continuous notification to user not to require a blocking dialog on closing.
 Note that when an active connection is in place, it's just a matter of time before changes will be flushed to storage unless there is some source of continuous local changes being generated that prevents container from ever being fully saved. But if there is no active connection, because the user is offline, for example, then a document may stay in a dirty state for very long time.
 
 `Container.isDirty` can be used to get current state of container.
+
+<!-- AUTO-GENERATED-CONTENT:START (README_TRADEMARK_SECTION:includeHeading=TRUE) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Trademark
+
+This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
+
+Use of these trademarks or logos must follow Microsoft's [Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->

package/api-extractor-esm.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-base-esm.json"
+}

package/api-extractor-lint.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-lint.json"
+}

package/api-extractor.json

@@ -1,4 +1,4 @@
 {
-  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-  "extends": "@fluidframework/build-common/api-extractor-common-report.json"
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-base.json"
 }

package/api-report/container-loader.api.md

@@ -0,0 +1,143 @@
+## API Report File for "@fluidframework/container-loader"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { FluidObject } from '@fluidframework/core-interfaces';
+import { IAudienceOwner } from '@fluidframework/container-definitions';
+import { IClientDetails } from '@fluidframework/protocol-definitions';
+import { IConfigProviderBase } from '@fluidframework/core-interfaces';
+import { IContainer } from '@fluidframework/container-definitions';
+import { IDocumentAttributes } from '@fluidframework/protocol-definitions';
+import { IDocumentServiceFactory } from '@fluidframework/driver-definitions';
+import { IDocumentStorageService } from '@fluidframework/driver-definitions';
+import { IFluidCodeDetails } from '@fluidframework/container-definitions';
+import { IFluidModule } from '@fluidframework/container-definitions';
+import { IHostLoader } from '@fluidframework/container-definitions';
+import { ILoaderOptions as ILoaderOptions_2 } from '@fluidframework/container-definitions';
+import { ILocationRedirectionError } from '@fluidframework/driver-definitions';
+import { IProtocolHandler as IProtocolHandler_2 } from '@fluidframework/protocol-base';
+import { IProvideFluidCodeDetailsComparer } from '@fluidframework/container-definitions';
+import { IQuorumSnapshot } from '@fluidframework/protocol-base';
+import { IRequest } from '@fluidframework/core-interfaces';
+import { ISignalMessage } from '@fluidframework/protocol-definitions';
+import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
+import { ITelemetryLoggerExt } from '@fluidframework/telemetry-utils';
+import { IUrlResolver } from '@fluidframework/driver-definitions';
+
+// @alpha (undocumented)
+export enum ConnectionState {
+    CatchingUp = 1,
+    Connected = 2,
+    Disconnected = 0,
+    EstablishingConnection = 3
+}
+
+// @alpha @deprecated (undocumented)
+export interface ICodeDetailsLoader extends Partial<IProvideFluidCodeDetailsComparer> {
+    load(source: IFluidCodeDetails): Promise<IFluidModuleWithDetails>;
+}
+
+// @internal
+export interface IContainerExperimental extends IContainer {
+    closeAndGetPendingLocalState?(stopBlobAttachingSignal?: AbortSignal): Promise<string>;
+    getPendingLocalState?(): Promise<string>;
+}
+
+// @alpha
+export type IDetachedBlobStorage = Pick<IDocumentStorageService, "createBlob" | "readBlob"> & {
+    size: number;
+    getBlobIds(): string[];
+};
+
+// @alpha @deprecated (undocumented)
+export interface IFluidModuleWithDetails {
+    details: IFluidCodeDetails;
+    module: IFluidModule;
+}
+
+// @alpha (undocumented)
+export interface ILoaderOptions extends ILoaderOptions_2 {
+    // (undocumented)
+    summarizeProtocolTree?: boolean;
+}
+
+// @alpha
+export interface ILoaderProps {
+    readonly codeLoader: ICodeDetailsLoader;
+    readonly configProvider?: IConfigProviderBase;
+    readonly detachedBlobStorage?: IDetachedBlobStorage;
+    readonly documentServiceFactory: IDocumentServiceFactory;
+    readonly logger?: ITelemetryBaseLogger;
+    readonly options?: ILoaderOptions;
+    readonly protocolHandlerBuilder?: ProtocolHandlerBuilder;
+    readonly scope?: FluidObject;
+    readonly urlResolver: IUrlResolver;
+}
+
+// @alpha
+export interface ILoaderServices {
+    readonly codeLoader: ICodeDetailsLoader;
+    readonly detachedBlobStorage?: IDetachedBlobStorage;
+    readonly documentServiceFactory: IDocumentServiceFactory;
+    readonly options: ILoaderOptions;
+    readonly protocolHandlerBuilder?: ProtocolHandlerBuilder;
+    readonly scope: FluidObject;
+    readonly subLogger: ITelemetryLoggerExt;
+    readonly urlResolver: IUrlResolver;
+}
+
+// @internal
+export interface IParsedUrl {
+    id: string;
+    path: string;
+    query: string;
+    version: string | null | undefined;
+}
+
+// @alpha (undocumented)
+export interface IProtocolHandler extends IProtocolHandler_2 {
+    // (undocumented)
+    readonly audience: IAudienceOwner;
+    // (undocumented)
+    processSignal(message: ISignalMessage): any;
+}
+
+// @internal
+export function isLocationRedirectionError(error: any): error is ILocationRedirectionError;
+
+// @alpha
+export class Loader implements IHostLoader {
+    constructor(loaderProps: ILoaderProps);
+    // (undocumented)
+    createDetachedContainer(codeDetails: IFluidCodeDetails, createDetachedProps?: {
+        canReconnect?: boolean;
+        clientDetailsOverride?: IClientDetails;
+    }): Promise<IContainer>;
+    // (undocumented)
+    rehydrateDetachedContainerFromSnapshot(snapshot: string, createDetachedProps?: {
+        canReconnect?: boolean;
+        clientDetailsOverride?: IClientDetails;
+    }): Promise<IContainer>;
+    // (undocumented)
+    resolve(request: IRequest, pendingLocalState?: string): Promise<IContainer>;
+    // (undocumented)
+    readonly services: ILoaderServices;
+}
+
+// @alpha
+export type ProtocolHandlerBuilder = (attributes: IDocumentAttributes, snapshot: IQuorumSnapshot, sendProposal: (key: string, value: any) => number) => IProtocolHandler;
+
+// @alpha
+export function resolveWithLocationRedirectionHandling<T>(api: (request: IRequest) => Promise<T>, request: IRequest, urlResolver: IUrlResolver, logger?: ITelemetryBaseLogger): Promise<T>;
+
+// @internal
+export function tryParseCompatibleResolvedUrl(url: string): IParsedUrl | undefined;
+
+// @alpha
+export function waitContainerToCatchUp(container: IContainer): Promise<boolean>;
+
+// (No @packageDocumentation comment for this package)
+
+```

package/dist/{audience.js → audience.cjs}

@@ -6,13 +6,16 @@ exports.Audience = void 0;
  * Licensed under the MIT License.
  */
 const events_1 = require("events");
+const core_utils_1 = require("@fluidframework/core-utils");
 /**
  * Audience represents all clients connected to the op stream.
  */
 class Audience extends events_1.EventEmitter {
     constructor() {
-        super(...arguments);
+        super();
         this.members = new Map();
+        // We are expecting this class to have many listeners, so we suppress noisy "MaxListenersExceededWarning" logging.
+        super.setMaxListeners(0);
     }
     on(event, listener) {
         return super.on(event, listener);
@@ -21,8 +24,16 @@ class Audience extends events_1.EventEmitter {
      * Adds a new client to the audience
      */
     addMember(clientId, details) {
-        this.members.set(clientId, details);
-        this.emit("addMember", clientId, details);
+        // Given that signal delivery is unreliable process, we might observe same client being added twice
+        // In such case we should see exactly same payload (IClient), and should not raise event twice!
+        if (this.members.has(clientId)) {
+            const client = this.members.get(clientId);
+            (0, core_utils_1.assert)(JSON.stringify(client) === JSON.stringify(details), 0x4b2 /* new client has different payload from existing one */);
+        }
+        else {
+            this.members.set(clientId, details);
+            this.emit("addMember", clientId, details);
+        }
     }
     /**
      * Removes a client from the audience. Only emits an event if a client is actually removed
@@ -51,15 +62,6 @@ class Audience extends events_1.EventEmitter {
     getMember(clientId) {
         return this.members.get(clientId);
     }
-    /**
-     * Clears the audience
-     */
-    clear() {
-        const clientIds = this.members.keys();
-        for (const clientId of clientIds) {
-            this.removeMember(clientId);
-        }
-    }
 }
 exports.Audience = Audience;
-//# sourceMappingURL=audience.js.map
+//# sourceMappingURL=audience.cjs.map

package/dist/audience.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"audience.cjs","sourceRoot":"","sources":["../src/audience.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,mCAAsC;AACtC,2DAAoD;AAIpD;;GAEG;AACH,MAAa,QAAS,SAAQ,qBAAY;IAGzC;QACC,KAAK,EAAE,CAAC;QAHQ,YAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;QAIrD,kHAAkH;QAClH,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IAMM,EAAE,CAAC,KAAa,EAAE,QAAkC;QAC1D,OAAO,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACI,SAAS,CAAC,QAAgB,EAAE,OAAgB;QAClD,mGAAmG;QACnG,+FAA+F;QAC/F,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE;YAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC1C,IAAA,mBAAM,EACL,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAClD,KAAK,CAAC,wDAAwD,CAC9D,CAAC;SACF;aAAM;YACN,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACpC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;SAC1C;IACF,CAAC;IAED;;;OAGG;IACI,YAAY,CAAC,QAAgB;QACnC,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACjD,IAAI,aAAa,KAAK,SAAS,EAAE;YAChC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC9B,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;YACnD,OAAO,IAAI,CAAC;SACZ;aAAM;YACN,OAAO,KAAK,CAAC;SACb;IACF,CAAC;IAED;;OAEG;IACI,UAAU;QAChB,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAED;;OAEG;IACI,SAAS,CAAC,QAAgB;QAChC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;CACD;AA/DD,4BA+DC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\nimport { EventEmitter } from \"events\";\nimport { assert } from \"@fluidframework/core-utils\";\nimport { IAudienceOwner } from \"@fluidframework/container-definitions\";\nimport { IClient } from \"@fluidframework/protocol-definitions\";\n\n/**\n * Audience represents all clients connected to the op stream.\n */\nexport class Audience extends EventEmitter implements IAudienceOwner {\n\tprivate readonly members = new Map<string, IClient>();\n\n\tconstructor() {\n\t\tsuper();\n\t\t// We are expecting this class to have many listeners, so we suppress noisy \"MaxListenersExceededWarning\" logging.\n\t\tsuper.setMaxListeners(0);\n\t}\n\n\tpublic on(\n\t\tevent: \"addMember\" | \"removeMember\",\n\t\tlistener: (clientId: string, client: IClient) => void,\n\t): this;\n\tpublic on(event: string, listener: (...args: any[]) => void): this {\n\t\treturn super.on(event, listener);\n\t}\n\n\t/**\n\t * Adds a new client to the audience\n\t */\n\tpublic addMember(clientId: string, details: IClient) {\n\t\t// Given that signal delivery is unreliable process, we might observe same client being added twice\n\t\t// In such case we should see exactly same payload (IClient), and should not raise event twice!\n\t\tif (this.members.has(clientId)) {\n\t\t\tconst client = this.members.get(clientId);\n\t\t\tassert(\n\t\t\t\tJSON.stringify(client) === JSON.stringify(details),\n\t\t\t\t0x4b2 /* new client has different payload from existing one */,\n\t\t\t);\n\t\t} else {\n\t\t\tthis.members.set(clientId, details);\n\t\t\tthis.emit(\"addMember\", clientId, details);\n\t\t}\n\t}\n\n\t/**\n\t * Removes a client from the audience. Only emits an event if a client is actually removed\n\t * @returns if a client was removed from the audience\n\t */\n\tpublic removeMember(clientId: string): boolean {\n\t\tconst removedClient = this.members.get(clientId);\n\t\tif (removedClient !== undefined) {\n\t\t\tthis.members.delete(clientId);\n\t\t\tthis.emit(\"removeMember\", clientId, removedClient);\n\t\t\treturn true;\n\t\t} else {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/**\n\t * Retrieves all the members in the audience\n\t */\n\tpublic getMembers(): Map<string, IClient> {\n\t\treturn new Map(this.members);\n\t}\n\n\t/**\n\t * Retrieves a specific member of the audience\n\t */\n\tpublic getMember(clientId: string): IClient | undefined {\n\t\treturn this.members.get(clientId);\n\t}\n}\n"]}

package/dist/audience.d.ts

@@ -1,15 +1,17 @@
+/// <reference types="node" />
 /*!
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
 import { EventEmitter } from "events";
-import { IAudience } from "@fluidframework/container-definitions";
+import { IAudienceOwner } from "@fluidframework/container-definitions";
 import { IClient } from "@fluidframework/protocol-definitions";
 /**
  * Audience represents all clients connected to the op stream.
  */
-export declare class Audience extends EventEmitter implements IAudience {
+export declare class Audience extends EventEmitter implements IAudienceOwner {
     private readonly members;
+    constructor();
     on(event: "addMember" | "removeMember", listener: (clientId: string, client: IClient) => void): this;
     /**
      * Adds a new client to the audience
@@ -28,9 +30,5 @@ export declare class Audience extends EventEmitter implements IAudience {
      * Retrieves a specific member of the audience
      */
     getMember(clientId: string): IClient | undefined;
-    /**
-     * Clears the audience
-     */
-    clear(): void;
 }
 //# sourceMappingURL=audience.d.ts.map

package/dist/audience.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audience.d.ts","sourceRoot":"","sources":["../src/audience.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,MAAM,sCAAsC,CAAC;AAE/D;;GAEG;AACH,qBAAa,QAAS,SAAQ,YAAa,YAAW,SAAS;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IAE/C,EAAE,CAAC,KAAK,EAAE,WAAW,GAAG,cAAc,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAK3G;;OAEG;IACI,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;IAKnD;;;OAGG;IACI,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAW9C;;OAEG;IACI,UAAU,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAIzC;;OAEG;IACI,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAIvD;;OAEG;IACI,KAAK,IAAI,IAAI;CAMvB"}
+{"version":3,"file":"audience.d.ts","sourceRoot":"","sources":["../src/audience.ts"],"names":[],"mappings":";AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,EAAE,OAAO,EAAE,MAAM,sCAAsC,CAAC;AAE/D;;GAEG;AACH,qBAAa,QAAS,SAAQ,YAAa,YAAW,cAAc;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;;IAQ/C,EAAE,CACR,KAAK,EAAE,WAAW,GAAG,cAAc,EACnC,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,GACnD,IAAI;IAKP;;OAEG;IACI,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;IAenD;;;OAGG;IACI,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAW9C;;OAEG;IACI,UAAU,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAIzC;;OAEG;IACI,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;CAGvD"}

package/dist/catchUpMonitor.cjs

@@ -0,0 +1,43 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CatchUpMonitor = void 0;
+const core_utils_1 = require("@fluidframework/core-utils");
+/**
+ * Monitors a Container's DeltaManager, notifying listeners when all ops have been processed
+ * that were known at the time the monitor was created.
+ */
+class CatchUpMonitor {
+    /**
+     * Create the CatchUpMonitor, setting the target sequence number to wait for based on DeltaManager's current state.
+     */
+    constructor(deltaManager, listener) {
+        this.deltaManager = deltaManager;
+        this.listener = listener;
+        this.caughtUp = false;
+        this.opHandler = (message) => {
+            if (!this.caughtUp && message.sequenceNumber >= this.targetSeqNumber) {
+                this.caughtUp = true;
+                this.listener();
+            }
+        };
+        this.disposed = false;
+        this.targetSeqNumber = this.deltaManager.lastKnownSeqNumber;
+        (0, core_utils_1.assert)(this.targetSeqNumber >= this.deltaManager.lastSequenceNumber, 0x37c /* Cannot wait for seqNumber below last processed sequence number */);
+        this.deltaManager.on("op", this.opHandler);
+        // Simulate the last processed op to set caughtUp in case we already are
+        this.opHandler({ sequenceNumber: this.deltaManager.lastSequenceNumber });
+    }
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        this.deltaManager.off("op", this.opHandler);
+    }
+}
+exports.CatchUpMonitor = CatchUpMonitor;
+//# sourceMappingURL=catchUpMonitor.cjs.map