@fluidframework/presence Package

Experimental package for client presence within a connected session.

See README.md for an overview of the package.

Interfaces

Interface	Alerts	Modifiers	Description
IPresence	Alpha	sealed	Presence represents known clients within a session and their custom states and notifications.
ISessionClient	Alpha	sealed	A client within a Fluid session (period of container connectivity to service).
LatestMapItemRemovedClientData	Alpha	sealed	Identifier and metadata for a removed item.
LatestMapItemValueClientData	Alpha	sealed	State of a single item value, its key, and its metadata.
LatestMapValueClientData	Alpha	sealed	Collection of latest known values for a specific client.
LatestMapValueManager	Alpha	sealed	Value manager 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.
LatestMapValueManagerEvents	Alpha	sealed
LatestValueClientData	Alpha	sealed	State of a specific client's value and its metadata.
LatestValueControls	Alpha		Common controls for the Latest* Value Managers.
LatestValueData	Alpha	sealed	State of a value and its metadata.
LatestValueManager	Alpha	sealed	Value manager that provides the latest known value from this client to others and read access to their values. All participant clients must provide a value.
LatestValueManagerEvents	Alpha	sealed
LatestValueMetadata	Alpha	sealed	Metadata for the value state.
NotificationEmitter	Alpha	sealed	Interface for a notification emitter that can send typed notification to other clients.
NotificationsManager	Alpha	sealed	Value manager that provides notifications from this client to others and subscription to their notifications.
NotificationsManagerEvents	Alpha	sealed
NotificationSubscribable	Alpha	sealed	An object which allows the registration of listeners so that subscribers can be notified when a notification happens.
PresenceEvents	Alpha	sealed
PresenceNotificationsSchema	Alpha		Schema for a PresenceNotifications workspace. Keys of schema are the keys of the PresenceNotifications providing access to NotificationsManagers.
PresenceStates	Alpha	sealed	PresenceStates maintains a registry of Value Managers that all share and provide access to presence state values across client members in a session. Value Managers 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.
PresenceStatesSchema	Alpha		Schema for a PresenceStates workspace. Keys of schema are the keys of the PresenceStates providing access to Value Managers.
ValueMap	Alpha	sealed	Map of local client's values. Modifications are transmitted to all other connected clients.

Classes

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

Types

TypeAlias	Alerts	Modifiers	Description
ClientConnectionId	Alpha		A Fluid client connection identifier.
ClientSessionId	Alpha		A Fluid client session identifier.
NotificationSubscriptions	Alpha	sealed	Record of notification subscriptions.
PresenceNotifications	Alpha	sealed	PresenceNotifications maintains a registry of NotificationsManagers that facilitate messages across client members in a session.
PresenceStatesEntries	Alpha	sealed	Map of Value Managers registered with PresenceStates.
PresenceStatesEntry	Alpha		Single entry in PresenceStatesSchema.
PresenceWorkspaceAddress	Alpha		Unique address within a session.
SessionClientStatus	Alpha		Represents the connection status of an ISessionClient. This type can be either 'Connected' or 'Disconnected', indicating whether the session client 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).

Functions

Function	Alerts	Return Type	Description
acquirePresence(fluidContainer)	Alpha	IPresence	Acquire an IPresence from a Fluid Container
acquirePresenceViaDataObject(fluidLoadable)	Alpha	IPresence	Acquire IPresence from a DataStore based Presence Manager
Latest(initialValue, controls)	Alpha	InternalTypes.ManagerFactory<Key, InternalTypes.ValueRequiredState<T>, LatestValueManager<T>>	Factory for creating a LatestValueManager.
LatestMap(initialValues, controls)	Alpha	InternalTypes.ManagerFactory<RegistrationKey, InternalTypes.MapValueState<T>, LatestMapValueManager<T, Keys>>	Factory for creating a LatestMapValueManager.
Notifications(initialSubscriptions)	Alpha	InternalTypes.ManagerFactory<Key, InternalTypes.ValueRequiredState<InternalTypes.NotificationType>, NotificationsManager<T>>	Factory for creating a NotificationsManager.

Variables

Variable	Alerts	Modifiers	Type	Description
ExperimentalPresenceManager	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.
SessionClientStatus	Alpha	readonly	{ readonly Connected: "Connected"; readonly Disconnected: "Disconnected"; }	The connection status of the ISessionClient.

Function Details

acquirePresence

Acquire an IPresence 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 acquirePresence(fluidContainer: IFluidContainer): IPresence;

Parameters

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

Returns

the IPresence

Return type: IPresence

acquirePresenceViaDataObject

Acquire IPresence from a DataStore based Presence Manager

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 acquirePresenceViaDataObject(fluidLoadable: ExperimentalPresenceDO): IPresence;

Example

const containerSchema = {
	initialObjects: {
		experimentalPresence: ExperimentalPresenceDO,
	},
} satisfies ContainerSchema;

then

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

Parameters

Parameter	Type	Description
fluidLoadable	ExperimentalPresenceDO

Returns

Return type: IPresence

Latest

Factory for creating a LatestValueManager.

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 Latest<T extends object, Key extends string = string>(initialValue: JsonSerializable<T> & JsonDeserialized<T> & object, controls?: LatestValueControls): InternalTypes.ManagerFactory<Key, InternalTypes.ValueRequiredState<T>, LatestValueManager<T>>;

Type Parameters

Parameter	Constraint	Default	Description
T	object
Key	string	string

Parameters

Parameter	Modifiers	Type	Description
initialValue		JsonSerializable<T> & JsonDeserialized<T> & object
controls	optional	LatestValueControls

Returns

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

LatestMap

Factory for creating a LatestMapValueManager.

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 LatestMap<T extends object, Keys extends string | number = string | number, RegistrationKey extends string = string>(initialValues?: {
    [K in Keys]: JsonSerializable<T> & JsonDeserialized<T>;
}, controls?: LatestValueControls): InternalTypes.ManagerFactory<RegistrationKey, InternalTypes.MapValueState<T>, LatestMapValueManager<T, Keys>>;

Type Parameters

Parameter	Constraint	Default	Description
T	object
Keys	string | number	string | number
RegistrationKey	string	string

Parameters

Parameter	Modifiers	Type	Description
initialValues	optional	{ [K in Keys]: JsonSerializable<T> & JsonDeserialized<T>; }
controls	optional	LatestValueControls

Returns

Return type: InternalTypes.ManagerFactory<RegistrationKey, InternalTypes.MapValueState<T>, LatestMapValueManager<T, Keys>>

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.NotificationEvents<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.NotificationEvents<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

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 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>

SessionClientStatus

The connection status of the ISessionClient.

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

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

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