@fluidframework/fluid-static 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.225277

package/src/fluidContainer.ts

@@ -2,295 +2,361 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { TypedEventEmitter } from "@fluidframework/common-utils";
-import { IFluidLoadable } from "@fluidframework/core-interfaces";
-import { IEvent, IEventProvider } from "@fluidframework/common-definitions";
+import { TypedEventEmitter } from "@fluid-internal/client-utils";
+import { IEvent, IEventProvider, IFluidLoadable } from "@fluidframework/core-interfaces";
 import {
-    AttachState,
-    ConnectionState,
-    IContainer,
-    ICriticalContainerError,
+	AttachState,
+	IContainer,
+	ICriticalContainerError,
+	ConnectionState,
 } from "@fluidframework/container-definitions";
-import { LoadableObjectClass, LoadableObjectRecord } from "./types";
-import { RootDataObject } from "./rootDataObject";
+import type { ContainerSchema, IRootDataObject, LoadableObjectClass } from "./types";
+
+/**
+ * Extract the type of 'initialObjects' from the given {@link ContainerSchema} type.
+ * @public
+ */
+export type InitialObjects<T extends ContainerSchema> = {
+	// Construct a LoadableObjectRecord type by enumerating the keys of
+	// 'ContainerSchema.initialObjects' and infering the value type of each key.
+	//
+	// The '? TChannel : never' is required because infer can only be used in
+	// a conditional 'extends' expression.
+	[K in keyof T["initialObjects"]]: T["initialObjects"][K] extends LoadableObjectClass<
+		infer TChannel
+	>
+		? TChannel
+		: never;
+};
 
 /**
  * Events emitted from {@link IFluidContainer}.
  *
- *  @remarks
- *
- * The following is the list of events emitted.
- *
- * ### "connected"
- *
- * The "connected" event is emitted when the `IFluidContainer` completes connecting to the Fluid service.
- *
- * #### Listener signature
- *
- * ```typescript
- * () => void;
- * ```
- *
- * ### "disposed"
- *
- * The "disposed" event is emitted when the `IFluidContainer` is disposed, which permanently disables it.
- *
- * #### Listener signature
- *
- * ```typescript
- * () => void;
- * ```
- *
- * ### "disconnected"
- *
- * The "disconnected" event is emitted when the `IFluidContainer` becomes disconnected from the Fluid service.
- *
- * #### Listener signature
- *
- * ```typescript
- * () => void;
- * ```
- *
- * ### "saved"
- *
- * The "saved" event is emitted when the `IFluidContainer` has local changes acknowledged by the service.
- *
- * #### Listener signature
- *
- * ```typescript
- * () => void
- * ```
- *
- * ### "dirty"
- *
- * The "dirty" event is emitted when the `IFluidContainer` has local changes that have not yet
- * been acknowledged by the service.
- *
- * #### Listener signature
- *
- * ```typescript
- * () => void
- * ```
+ * @remarks Note: external implementations of this interface are not supported.
+ * @sealed
+ * @public
  */
 export interface IFluidContainerEvents extends IEvent {
-    /**
-     * **connected** & **disconnected** events reflect connection state changes against the (delta)
-     * service acknowledging ops/edits.
-     */
-    (event: "connected" | "disconnected", listener: () => void): void;
-    /**
-     * **saved** event is raised when all local changes/edits have been acknowledged by the service.
-     * **dirty** event is raised when first local change has been made, following a "saved" state.
-     */
-    // eslint-disable-next-line @typescript-eslint/unified-signatures
-    (event: "saved" | "dirty", listener: () => void): void;
-    /**
-     * Disposed event is raised when container is closed. If container was closed due to error
-     * (vs explicit **dispose** action), optional argument contains further details about the error.
-     */
-    (event: "disposed", listener: (error?: ICriticalContainerError) => void);
+	/**
+	 * Emitted when the {@link IFluidContainer} completes connecting to the Fluid service.
+	 *
+	 * @remarks Reflects connection state changes against the (delta) service acknowledging ops/edits.
+	 *
+	 * @see
+	 *
+	 * - {@link IFluidContainer.connectionState}
+	 *
+	 * - {@link IFluidContainer.connect}
+	 */
+	(event: "connected", listener: () => void): void;
+
+	/**
+	 * Emitted when the {@link IFluidContainer} becomes disconnected from the Fluid service.
+	 *
+	 * @remarks Reflects connection state changes against the (delta) service acknowledging ops/edits.
+	 *
+	 * @see
+	 *
+	 * - {@link IFluidContainer.connectionState}
+	 *
+	 * - {@link IFluidContainer.disconnect}
+	 */
+	(event: "disconnected", listener: () => void): void;
+
+	/**
+	 * Emitted when all local changes/edits have been acknowledged by the service.
+	 *
+	 * @remarks "dirty" event will be emitted when the next local change has been made.
+	 *
+	 * @see {@link IFluidContainer.isDirty}
+	 */
+	(event: "saved", listener: () => void): void;
+
+	/**
+	 * Emitted when the first local change has been made, following a "saved" event.
+	 *
+	 * @remarks "saved" event will be emitted once all local changes have been acknowledged by the service.
+	 *
+	 * @see {@link IFluidContainer.isDirty}
+	 */
+	(event: "dirty", listener: () => void): void;
+
+	/**
+	 * Emitted when the {@link IFluidContainer} is closed, which permanently disables it.
+	 *
+	 * @remarks Listener parameters:
+	 *
+	 * - `error`: If the container was closed due to error (as opposed to an explicit call to
+	 * {@link IFluidContainer.dispose}), this will contain details about the error that caused it.
+	 */
+	(event: "disposed", listener: (error?: ICriticalContainerError) => void);
 }
 
 /**
  * Provides an entrypoint into the client side of collaborative Fluid data.
  * Provides access to the data as well as status on the collaboration session.
+ *
+ * @typeparam TContainerSchema - Used to determine the type of 'initialObjects'.
+ *
+ * @remarks Note: external implementations of this interface are not supported.
+ * @sealed
+ * @public
  */
-export interface IFluidContainer extends IEventProvider<IFluidContainerEvents> {
-    /**
-     * Provides the current connected state of the container
-     */
-    readonly connectionState: ConnectionState;
+export interface IFluidContainer<TContainerSchema extends ContainerSchema = ContainerSchema>
+	extends IEventProvider<IFluidContainerEvents> {
+	/**
+	 * Provides the current connected state of the container
+	 */
+	readonly connectionState: ConnectionState;
 
-    /**
-     * A container is considered **dirty** if it has local changes that have not yet been acknowledged by the service.
-     * You should always check the `isDirty` flag before closing the container or navigating away from the page.
-     * Closing the container while `isDirty === true` may result in the loss of operations that have not yet been
-     * acknowledged by the service.
-     *
-     * A container is considered dirty in the following cases:
-     *
-     * 1. The container has been created in the detached state, and either it has not been attached yet or it is
-     * in the process of being attached (container is in `attaching` state). If container is closed prior to being
-     * attached, host may never know if the file was created or not.
-     *
-     * 2. The container was attached, but it has local changes that have not yet been saved to service endpoint.
-     * This occurs as part of normal op flow where pending operation (changes) are awaiting acknowledgement from the
-     * service. In some cases this can be due to lack of network connection. If the network connection is down,
-     * it needs to be restored for the pending changes to be acknowledged.
-     */
-    readonly isDirty: boolean;
+	/**
+	 * A container is considered **dirty** if it has local changes that have not yet been acknowledged by the service.
+	 *
+	 * @remarks
+	 *
+	 * You should always check the `isDirty` flag before closing the container or navigating away from the page.
+	 * Closing the container while `isDirty === true` may result in the loss of operations that have not yet been
+	 * acknowledged by the service.
+	 *
+	 * A container is considered dirty in the following cases:
+	 *
+	 * 1. The container has been created in the detached state, and either it has not been attached yet or it is
+	 * in the process of being attached (container is in `attaching` state). If container is closed prior to being
+	 * attached, host may never know if the file was created or not.
+	 *
+	 * 2. The container was attached, but it has local changes that have not yet been saved to service endpoint.
+	 * This occurs as part of normal op flow where pending operation (changes) are awaiting acknowledgement from the
+	 * service. In some cases this can be due to lack of network connection. If the network connection is down,
+	 * it needs to be restored for the pending changes to be acknowledged.
+	 */
+	readonly isDirty: boolean;
 
-    /**
-     * Whether the container is disposed, which permanently disables it.
-     */
-    readonly disposed: boolean;
+	/**
+	 * Whether or not the container is disposed, which permanently disables it.
+	 */
+	readonly disposed: boolean;
 
-    /**
-     * The collection of data objects and Distributed Data Stores (DDSes) that were specified by the schema.
-     * These data objects and DDSes exist for the lifetime of the container.
-     */
-    readonly initialObjects: LoadableObjectRecord;
+	/**
+	 * The collection of data objects and Distributed Data Stores (DDSes) that were specified by the schema.
+	 *
+	 * @remarks These data objects and DDSes exist for the lifetime of the container.
+	 */
+	readonly initialObjects: InitialObjects<TContainerSchema>;
 
-    /**
-     * The current attachment state of the container.  Once a container has been attached, it remains attached.
-     * When loading an existing container, it will already be attached.
-     */
-    readonly attachState: AttachState;
+	/**
+	 * The current attachment state of the container.
+	 *
+	 * @remarks
+	 *
+	 * Once a container has been attached, it remains attached.
+	 * When loading an existing container, it will already be attached.
+	 */
+	readonly attachState: AttachState;
 
-    /**
-     * A newly created container starts detached from the collaborative service.
-     * Calling `attach()` uploads the new container to the service and connects to the collaborative service.
-     *
-     * @remarks This should only be called when the container is in the
-     * {@link @fluidframework/container-definitions#AttachState.Detatched} state.
-     *
-     * This can be determined by observing {@link IFluidContainer.attachState}.
-     *
-     * @returns A promise which resolves when the attach is complete, with the string identifier of the container.
-     */
-    attach(): Promise<string>;
+	/**
+	 * A newly created container starts detached from the collaborative service.
+	 * Calling `attach()` uploads the new container to the service and connects to the collaborative service.
+	 *
+	 * @remarks
+	 *
+	 * This should only be called when the container is in the
+	 * {@link @fluidframework/container-definitions#AttachState.Detatched} state.
+	 *
+	 * This can be determined by observing {@link IFluidContainer.attachState}.
+	 *
+	 * @returns A promise which resolves when the attach is complete, with the string identifier of the container.
+	 */
+	attach(): Promise<string>;
 
-    /**
-     * Attempts to connect the container to the delta stream and process operations.
-     * Will throw an error if unsuccessful.
-     *
-     * @remarks This should only be called when the container is in the
-     * {@link @fluidframework/container-definitions#ConnectionState.Disconnected} state.
-     *
-     * This can be determined by observing {@link IFluidContainer.connectionState}.
-     */
-    connect(): void;
+	/**
+	 * Attempts to connect the container to the delta stream and process operations.
+	 *
+	 * @throws Will throw an error if connection is unsuccessful.
+	 *
+	 * @remarks
+	 *
+	 * This should only be called when the container is in the
+	 * {@link @fluidframework/container-definitions#ConnectionState.Disconnected} state.
+	 *
+	 * This can be determined by observing {@link IFluidContainer.connectionState}.
+	 */
+	connect(): void;
 
-    /**
-     * Disconnects the container from the delta stream and stops processing operations.
-     *
-     * @remarks This should only be called when the container is in the
-     * {@link @fluidframework/container-definitions#ConnectionState.Connected} state.
-     *
-     * This can be determined by observing {@link IFluidContainer.connectionState}.
-     */
-    disconnect(): void;
+	/**
+	 * Disconnects the container from the delta stream and stops processing operations.
+	 *
+	 * @remarks
+	 *
+	 * This should only be called when the container is in the
+	 * {@link @fluidframework/container-definitions#ConnectionState.Connected} state.
+	 *
+	 * This can be determined by observing {@link IFluidContainer.connectionState}.
+	 */
+	disconnect(): void;
 
-    /**
-     * Create a new data object or Distributed Data Store (DDS) of the specified type.
-     *
-     * @remarks In order to share the data object or DDS with other
-     * collaborators and retrieve it later, store its handle in a collection like a SharedDirectory from your
-     * initialObjects.
-     *
-     * @param objectClass - The class of data object or DDS to create
-     */
-    create<T extends IFluidLoadable>(objectClass: LoadableObjectClass<T>): Promise<T>;
+	/**
+	 * Create a new data object or Distributed Data Store (DDS) of the specified type.
+	 *
+	 * @remarks
+	 *
+	 * In order to share the data object or DDS with other
+	 * collaborators and retrieve it later, store its handle in a collection like a SharedDirectory from your
+	 * initialObjects.
+	 *
+	 * @param objectClass - The class of the `DataObject` or `SharedObject` to create.
+	 *
+	 * @typeParam T - The class of the `DataObject` or `SharedObject`.
+	 */
+	create<T extends IFluidLoadable>(objectClass: LoadableObjectClass<T>): Promise<T>;
 
-    /**
-     * Dispose of the container instance, permanently disabling it.
-     */
-    dispose(): void;
+	/**
+	 * Dispose of the container instance, permanently disabling it.
+	 */
+	dispose(): void;
+}
+
+/**
+ * @internal
+ */
+export function createFluidContainer<
+	TContainerSchema extends ContainerSchema = ContainerSchema,
+>(props: {
+	container: IContainer;
+	rootDataObject: IRootDataObject;
+}): IFluidContainer<TContainerSchema> {
+	return new FluidContainer<TContainerSchema>(props.container, props.rootDataObject);
 }
 
 /**
  * Base {@link IFluidContainer} implementation.
  *
- * @remarks Note: this implementation is not complete. Consumers who rely on {@link IFluidContainer.attach}
+ * @typeparam TContainerSchema - Used to determine the type of 'initialObjects'.
+ * @remarks
+ *
+ * Note: this implementation is not complete. Consumers who rely on {@link IFluidContainer.attach}
  * will need to utilize or provide a service-specific implementation of this type that implements that method.
+ * @deprecated use {@link createFluidContainer} and {@link IFluidContainer} instead
+ * @internal
  */
-export class FluidContainer extends TypedEventEmitter<IFluidContainerEvents> implements IFluidContainer {
-    private readonly connectedHandler = () => this.emit("connected");
-    private readonly disconnectedHandler = () => this.emit("disconnected");
-    private readonly disposedHandler = (error?: ICriticalContainerError) => this.emit("disposed", error);
-    private readonly savedHandler = () => this.emit("saved");
-    private readonly dirtyHandler = () => this.emit("dirty");
+class FluidContainer<TContainerSchema extends ContainerSchema = ContainerSchema>
+	extends TypedEventEmitter<IFluidContainerEvents>
+	implements IFluidContainer<TContainerSchema>
+{
+	private readonly connectedHandler = () => this.emit("connected");
+	private readonly disconnectedHandler = () => this.emit("disconnected");
+	private readonly disposedHandler = (error?: ICriticalContainerError) =>
+		this.emit("disposed", error);
+	private readonly savedHandler = () => this.emit("saved");
+	private readonly dirtyHandler = () => this.emit("dirty");
+
+	public constructor(
+		private readonly container: IContainer,
+		private readonly rootDataObject: IRootDataObject,
+	) {
+		super();
+		container.on("connected", this.connectedHandler);
+		container.on("closed", this.disposedHandler);
+		container.on("disconnected", this.disconnectedHandler);
+		container.on("saved", this.savedHandler);
+		container.on("dirty", this.dirtyHandler);
+	}
 
-    public constructor(
-        private readonly container: IContainer,
-        private readonly rootDataObject: RootDataObject,
-    ) {
-        super();
-        container.on("connected", this.connectedHandler);
-        container.on("closed", this.disposedHandler);
-        container.on("disconnected", this.disconnectedHandler);
-        container.on("saved", this.savedHandler);
-        container.on("dirty", this.dirtyHandler);
-    }
+	/**
+	 * {@inheritDoc IFluidContainer.isDirty}
+	 */
+	public get isDirty(): boolean {
+		return this.container.isDirty;
+	}
 
-    /**
-     * {@inheritDoc IFluidContainer.isDirty}
-     */
-     public get isDirty(): boolean {
-        return this.container.isDirty;
-    }
+	/**
+	 * {@inheritDoc IFluidContainer.attachState}
+	 */
+	public get attachState(): AttachState {
+		return this.container.attachState;
+	}
 
-    /**
-     * {@inheritDoc IFluidContainer.attachState}
-     */
-    public get attachState(): AttachState {
-        return this.container.attachState;
-    }
+	/**
+	 * {@inheritDoc IFluidContainer.disposed}
+	 */
+	public get disposed() {
+		return this.container.closed;
+	}
 
-    /**
-     * {@inheritDoc IFluidContainer.disposed}
-     */
-    public get disposed() {
-        return this.container.closed;
-    }
+	/**
+	 * {@inheritDoc IFluidContainer.connectionState}
+	 */
+	public get connectionState(): ConnectionState {
+		return this.container.connectionState;
+	}
 
-    /**
-     * {@inheritDoc IFluidContainer.connectionState}
-     */
-     public get connectionState(): ConnectionState {
-        return this.container.connectionState;
-    }
+	/**
+	 * {@inheritDoc IFluidContainer.initialObjects}
+	 */
+	public get initialObjects(): InitialObjects<TContainerSchema> {
+		return this.rootDataObject.initialObjects as InitialObjects<TContainerSchema>;
+	}
 
-    /**
-     * {@inheritDoc IFluidContainer.initialObjects}
-     */
-    public get initialObjects() {
-        return this.rootDataObject.initialObjects;
-    }
+	/**
+	 * Incomplete base implementation of {@link IFluidContainer.attach}.
+	 *
+	 * @remarks
+	 *
+	 * Note: this implementation will unconditionally throw.
+	 * Consumers who rely on this will need to utilize or provide a service specific implementation of this base type
+	 * that provides an implementation of this method.
+	 *
+	 * The reason is because externally we are presenting a separation between the service and the `FluidContainer`,
+	 * but internally this separation is not there.
+	 */
+	public async attach(): Promise<string> {
+		if (this.container.attachState !== AttachState.Detached) {
+			throw new Error("Cannot attach container. Container is not in detached state.");
+		}
+		throw new Error("Cannot attach container. Attach method not provided.");
+	}
 
-    /**
-     * Incomplete base implementation of {@link IFluidContainer.attach}.
-     * @remarks Note: this implementation will unconditionally throw.
-     * Consumers who rely on this will need to utilize or provide a service specific implementation of this base type
-     * that provides an implementation of this method.
-     *
-     * The reason is because externally we are presenting a separation between the service and the `FluidContainer`,
-     * but internally this separation is not there.
-     */
-    public async attach(): Promise<string> {
-        throw new Error("Cannot attach container. Container is not in detached state");
-    }
+	/**
+	 * {@inheritDoc IFluidContainer.connect}
+	 */
+	public async connect(): Promise<void> {
+		this.container.connect?.();
+	}
 
-    /**
-     * {@inheritDoc IFluidContainer.connect}
-     */
-    public async connect(): Promise<void> {
-        this.container.connect?.();
-    }
+	/**
+	 * {@inheritDoc IFluidContainer.connect}
+	 */
+	public async disconnect(): Promise<void> {
+		this.container.disconnect?.();
+	}
 
-    /**
-     * {@inheritDoc IFluidContainer.connect}
-     */
-    public async disconnect(): Promise<void> {
-        this.container.disconnect?.();
-    }
+	/**
+	 * {@inheritDoc IFluidContainer.create}
+	 */
+	public async create<T extends IFluidLoadable>(objectClass: LoadableObjectClass<T>): Promise<T> {
+		return this.rootDataObject.create(objectClass);
+	}
 
-    /**
-     * {@inheritDoc IFluidContainer.create}
-     */
-    public async create<T extends IFluidLoadable>(objectClass: LoadableObjectClass<T>): Promise<T> {
-        return this.rootDataObject.create(objectClass);
-    }
+	/**
+	 * {@inheritDoc IFluidContainer.dispose}
+	 */
+	public dispose() {
+		this.container.close();
+		this.container.off("connected", this.connectedHandler);
+		this.container.off("closed", this.disposedHandler);
+		this.container.off("disconnected", this.disconnectedHandler);
+		this.container.off("saved", this.savedHandler);
+		this.container.off("dirty", this.dirtyHandler);
+	}
 
-    /**
-     * {@inheritDoc IFluidContainer.dispose}
-     */
-    public dispose() {
-        this.container.close();
-        this.container.off("connected", this.connectedHandler);
-        this.container.off("closed", this.disposedHandler);
-        this.container.off("disconnected", this.disconnectedHandler);
-        this.container.off("saved", this.savedHandler);
-        this.container.off("dirty", this.dirtyHandler);
-    }
+	/**
+	 * FOR INTERNAL USE ONLY. NOT FOR EXTERNAL USE.
+	 * We make no stability guarantees here whatsoever.
+	 *
+	 * Gets the underlying {@link @fluidframework/container-definitions#IContainer}.
+	 *
+	 * @remarks Used to power debug tooling.
+	 */
+	public readonly INTERNAL_CONTAINER_DO_NOT_USE?: () => IContainer = () => {
+		return this.container;
+	};
 }

package/src/index.ts

@@ -9,7 +9,28 @@
  * @packageDocumentation
  */
 
-export * from "./fluidContainer";
-export * from "./rootDataObject";
-export * from "./serviceAudience";
-export * from "./types";
+export {
+	createFluidContainer,
+	IFluidContainer,
+	IFluidContainerEvents,
+	InitialObjects,
+} from "./fluidContainer";
+export { createDOProviderContainerRuntimeFactory } from "./rootDataObject";
+export { createServiceAudience } from "./serviceAudience";
+export {
+	ContainerSchema,
+	DataObjectClass,
+	IConnection,
+	IMember,
+	IRootDataObject,
+	IServiceAudience,
+	IServiceAudienceEvents,
+	LoadableObjectClass,
+	LoadableObjectClassRecord,
+	LoadableObjectCtor,
+	LoadableObjectRecord,
+	MemberChangedListener,
+	Myself,
+	SharedObjectClass,
+	IProvideRootDataObject,
+} from "./types";