Skip to main content

@fluidframework/presence Package

Package for client presence within a connected session.

See README.md for an overview of the package.

Interfaces

Interface Alerts Modifiers Description
Attendee Beta sealed A client within a Fluid session (period of container connectivity to service).
AttendeesEvents Beta sealed Events from attendees.
BroadcastControls Beta sealed Common controls for States objects.
BroadcastControlSettings Beta Value set to configure BroadcastControls.
Latest Beta sealed State that provides the latest known value from this client to others and read access to their values. All participant clients must provide a value.
LatestArgumentsRaw Beta Arguments that are passed to the StateFactory.latest function to create a LatestRaw State object.
LatestClientData Beta sealed State of a specific Attendee's value and its metadata.
LatestData Beta sealed State of a value and its metadata.
LatestEvents Beta sealed Events from LatestRaw.
LatestFactory Beta sealed Factory for creating a LatestRaw State object.
LatestMap Beta sealed State that provides a Map of latest known values from this client to others and read access to their values. Entries in the map may vary over time and by client, but all values are expected to be of the same type, which may be a union type.
LatestMapArgumentsRaw Beta Arguments that are passed to the StateFactory.latestMap function.
LatestMapClientData Beta sealed Collection of latest known values for a specific Attendee.
LatestMapEvents Beta sealed Events from LatestMapRaw.
LatestMapFactory Beta sealed Factory for creating a LatestMapRaw State object.
LatestMapItemRemovedClientData Beta sealed Identifier and metadata for a removed item.
LatestMapItemUpdatedClientData Beta sealed State of a single item value, its key, and its metadata.
LatestMetadata Beta sealed Metadata for the value state.
NotificationEmitter Alpha sealed Interface for a notification emitter that can send typed notification to other clients.
NotificationListenable Alpha sealed An object which allows the registration of listeners so that subscribers can be notified when a notification happens.
NotificationsManager Alpha sealed Provides notifications from this client to others and subscription to their notifications.
NotificationsManagerEvents Alpha sealed
NotificationsWorkspace Alpha sealed NotificationsWorkspace maintains a registry of NotificationsManagers that facilitate messages across client members in a session.
NotificationsWorkspaceSchema Alpha

Schema for a NotificationsWorkspace workspace.

Keys of schema are the keys of the NotificationsWorkspace providing access to NotificationsManagers.

Presence Beta sealed Provides top-level access to Presence feature set including known Attendees within a session and their custom states kept under StatesWorkspaces.
PresenceEvents Beta sealed Events from Presence.
PresenceWithNotifications Alpha sealed Provides top-level access to Presence feature set including known Attendees within a session and their custom states and notifications kept under StatesWorkspaces and NotificationsWorkspaces.
ProxiedValueAccessor System Represents a value that is accessed via a function call, which may result in no value.
RawValueAccessor System Represents a value that is accessed directly.
StateMap Beta sealed Map of local client's values. Modifications are transmitted to all other connected clients.
StatesWorkspace Beta sealed

StatesWorkspace maintains a registry of State objects that all share and provide access to presence state values across client members in a session.

State objects offer variations on how to manage states, but all share same principle that each client's state is independent and may only be updated by originating client.

StatesWorkspaceSchema Beta

Schema for a StatesWorkspace workspace.

Keys of schema are the keys of the StatesWorkspace providing access to State objects.

Classes

Class Alerts Modifiers Description
ExperimentalPresenceDO Deprecated, Alpha sealed Brand for Experimental Presence Data Object.

Types

TypeAlias Alerts Modifiers Description
Accessor System Utility type that conditionally represents an accessor type based on the base accessor type.
AttendeeId Beta A Fluid client session identifier.
AttendeeStatus Beta

Represents the connection status of an Attendee.

This type can be either 'Connected' or 'Disconnected', indicating whether the attendee is currently connected to the Fluid service.

When 'Disconnected': - State changes are kept locally and communicated to others upon reconnect. - Notification requests are discarded (silently).

ClientConnectionId Beta A Fluid client connection identifier.
LatestMapRaw Beta sealed State that provides a Map of latest known values from this client to others and read access to their values. Entries in the map may vary over time and by client, but all values are expected to be of the same type, which may be a union type.
LatestMapRawEvents Beta sealed Events from LatestMapRaw.
LatestRaw Beta sealed State that provides the latest known value from this client to others and read access to their values. All participant clients must provide a value.
LatestRawEvents Beta sealed Events from LatestRaw.
NotificationSubscriptions Alpha sealed Record of notification subscriptions.
StateSchemaValidator Beta A validator function that can optionally be provided to do runtime validation of the custom data stored in a presence workspace and managed by a state object.
StatesWorkspaceEntries Beta sealed Map of State objects registered with StatesWorkspace.
StatesWorkspaceEntry Beta Single entry in StatesWorkspaceSchema or NotificationsWorkspaceSchema.
ValueAccessor System Union of possible accessor types for a value.
WorkspaceAddress Beta Unique address within a session.

Functions

Function Alerts Return Type Description
getPresence(fluidContainer) Beta Presence Acquire a Presence from a Fluid Container
getPresenceAlpha(fluidContainer) Alpha PresenceWithNotifications Acquire a PresenceWithNotifications from a Fluid Container
getPresenceViaDataObject(fluidLoadable) Deprecated, Alpha Presence Acquire Presence from a DataStore based Presence Manager
Notifications(initialSubscriptions) Alpha InternalTypes.ManagerFactory<Key, InternalTypes.ValueRequiredState<InternalTypes.NotificationType>, NotificationsManager<T>> Factory for creating a NotificationsManager.

Variables

Variable Alerts Modifiers Type Description
AttendeeStatus Beta readonly { readonly Connected: "Connected"; readonly Disconnected: "Disconnected"; } The connection status of the Attendee.
ExperimentalPresenceManager Deprecated, Alpha readonly SharedObjectKind<IFluidLoadable & ExperimentalPresenceDO> DataStore based Presence Manager that is used as fallback for preferred Container Extension based version requires registration. Export SharedObjectKind for registration.
StateFactory Beta readonly { latest: LatestFactory; latestMap: LatestMapFactory; } Factory for creating presence State objects.

Namespaces

Namespace Alerts Description
InternalTypes System Collection of value types that are not intended to be used/imported directly outside of this package.
InternalUtilityTypes System Collection of utility types that are not intended to be used/imported directly outside of this package.

Function Details

getPresence

Acquire a Presence from a Fluid Container

This API is provided as a beta preview and may change without notice.

To use, import via @fluidframework/presence/beta.

For more information about our API support guarantees, see here.

Signature
getPresence: (fluidContainer: IFluidContainer) => Presence

Parameters

Parameter Type Description
fluidContainer IFluidContainer Fluid Container to acquire the map from

Returns

the Presence

Return type: Presence

getPresenceAlpha

Acquire a PresenceWithNotifications from a Fluid Container

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/presence/alpha.

For more information about our API support guarantees, see here.

Signature
export declare function getPresenceAlpha(fluidContainer: IFluidContainer): PresenceWithNotifications;

Parameters

Parameter Type Description
fluidContainer IFluidContainer Fluid Container to acquire the map from

Returns

the PresenceWithNotifications

Return type: PresenceWithNotifications

getPresenceViaDataObject

Acquire Presence from a DataStore based Presence Manager

This API is deprecated and will be removed in a future release.
This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/presence/alpha.

For more information about our API support guarantees, see here.

Signature
export declare function getPresenceViaDataObject(fluidLoadable: ExperimentalPresenceDO): Presence;
Example
const containerSchema = {
initialObjects: {
experimentalPresence: ExperimentalPresenceDO,
},
} satisfies ContainerSchema;

then

const presence = getPresenceViaDataObject(
container.initialObjects.experimentalPresence,
);

Parameters

Parameter Type Description
fluidLoadable ExperimentalPresenceDO

Returns

Return type: Presence

Notifications

Factory for creating a NotificationsManager.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/presence/alpha.

For more information about our API support guarantees, see here.

Signature
export declare function Notifications<T extends InternalUtilityTypes.NotificationListeners<T>, Key extends string = string>(initialSubscriptions: Partial<NotificationSubscriptions<T>>): InternalTypes.ManagerFactory<Key, InternalTypes.ValueRequiredState<InternalTypes.NotificationType>, NotificationsManager<T>>;
Type Parameters
Parameter Constraint Default Description
T InternalUtilityTypes.NotificationListeners<T>
Key string string
Remarks

Typescript inference for Notifications is not working correctly yet. Explicitly specify generics to make result types usable.

Parameters

Parameter Type Description
initialSubscriptions Partial<NotificationSubscriptions<T>>

Returns

Return type: InternalTypes.ManagerFactory<Key, InternalTypes.ValueRequiredState<InternalTypes.NotificationType>, NotificationsManager<T>>

Variable Details

AttendeeStatus

The connection status of the Attendee.

This API is provided as a beta preview and may change without notice.

To use, import via @fluidframework/presence/beta.

For more information about our API support guarantees, see here.

Signature
AttendeeStatus: {
readonly Connected: "Connected";
readonly Disconnected: "Disconnected";
}

Type: { readonly Connected: "Connected"; readonly Disconnected: "Disconnected"; }

ExperimentalPresenceManager

DataStore based Presence Manager that is used as fallback for preferred Container Extension based version requires registration. Export SharedObjectKind for registration.

This API is deprecated and will be removed in a future release.
This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/presence/alpha.

For more information about our API support guarantees, see here.

Signature
ExperimentalPresenceManager: SharedObjectKind<IFluidLoadable & ExperimentalPresenceDO>

Type: SharedObjectKind<IFluidLoadable & ExperimentalPresenceDO>

StateFactory

Factory for creating presence State objects.

This API is provided as a beta preview and may change without notice.

To use, import via @fluidframework/presence/beta.

For more information about our API support guarantees, see here.

Signature
StateFactory: {
latest: LatestFactory;
latestMap: LatestMapFactory;
}

Type: { latest: LatestFactory; latestMap: LatestMapFactory; }

Remarks

Use latest to create a LatestRaw State object. Use latestMap to create a LatestMapRaw State object.