IFluidContainer Interface

Provides an entrypoint into the client side of collaborative Fluid data. Provides access to the data as well as status on the collaboration session.

Signature

/** @sealed */
export interface IFluidContainer<TContainerSchema extends ContainerSchema = ContainerSchema> extends IEventProvider<IFluidContainerEvents>

Extends: IEventProvider<IFluidContainerEvents>

Type Parameters

Parameter	Constraint	Default	Description
TContainerSchema	ContainerSchema	ContainerSchema	Used to determine the type of 'initialObjects'.

Remarks

Note: external implementations of this interface are not supported.

Properties

Property	Modifiers	Type	Description
attachState	readonly	AttachState	The current attachment state of the container.
connectionState	readonly	ConnectionState	Provides the current connected state of the container
disposed	readonly	boolean	Whether or not the container is disposed, which permanently disables it.
initialObjects	readonly	InitialObjects<TContainerSchema>	The collection of data objects and Distributed Data Stores (DDSes) that were specified by the schema.
isDirty	readonly	boolean	A container is considered **dirty** if it has local changes that have not yet been acknowledged by the service.

Methods

Method	Return Type	Description
attach(props)	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.
connect()	void	Attempts to connect the container to the delta stream and process operations.
create(objectClass)	Promise<T>	Create a new data object or Distributed Data Store (DDS) of the specified type.
disconnect()	void	Disconnects the container from the delta stream and stops processing operations.
dispose()	void	Dispose of the container instance, permanently disabling it.

Property Details

attachState

The current attachment state of the container.

Signature

readonly attachState: AttachState;

Type: AttachState

Remarks

Once a container has been attached, it remains attached. When loading an existing container, it will already be attached.

connectionState

Provides the current connected state of the container

Signature

readonly connectionState: ConnectionState;

Type: ConnectionState

disposed

Whether or not the container is disposed, which permanently disables it.

Signature

readonly disposed: boolean;

Type: boolean

initialObjects

The collection of data objects and Distributed Data Stores (DDSes) that were specified by the schema.

Signature

readonly initialObjects: InitialObjects<TContainerSchema>;

Type: InitialObjects<TContainerSchema>

Remarks

These data objects and DDSes exist for the lifetime of the container.

isDirty

A container is considered **dirty** if it has local changes that have not yet been acknowledged by the service.

Signature

readonly isDirty: boolean;

Type: boolean

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.

Method Details

attach

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.

Signature

attach(props?: ContainerAttachProps): Promise<string>;

Remarks

This should only be called when the container is in the Detached state.

This can be determined by observing attachState.

Parameters

Parameter	Modifiers	Type	Description
props	optional	ContainerAttachProps

Returns

A promise which resolves when the attach is complete, with the string identifier of the container.

Return type: Promise<string>

connect

Attempts to connect the container to the delta stream and process operations.

Signature

connect(): void;

Remarks

This should only be called when the container is in the Disconnected state.

This can be determined by observing connectionState.

Error Handling

Will throw an error if connection is unsuccessful.

create

Create a new data object or Distributed Data Store (DDS) of the specified type.

Signature

create<T extends IFluidLoadable>(objectClass: SharedObjectKind<T>): Promise<T>;

Type Parameters

Parameter	Constraint	Description
T	IFluidLoadable	The class of the DataObject or SharedObject.

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. It's typically a good idea to set any initial state on the object before doing so, as it is both more efficient and helpful to maintain domain model invariants (e.g. this approach easily allows state to only be set once).

Example

const existingDirectory = container.initialObjects.myDirectory;
const map = await container.create(SharedMap);
map.set("initialState", "someValue");
existingDirectory.set("myMap", map.handle);

Parameters

Parameter	Type	Description
objectClass	SharedObjectKind<T>	The class of the DataObject or SharedObject to create.

Returns

Return type: Promise<T>

disconnect

Disconnects the container from the delta stream and stops processing operations.

Signature

disconnect(): void;

Remarks

This should only be called when the container is in the Connected state.

This can be determined by observing connectionState.

dispose

Dispose of the container instance, permanently disabling it.

Signature

dispose(): void;