Class Presence<State, DocType>

Presence encapsulates ephemeral state communication for a specific doc handle. It tracks caller-provided local state and broadcasts that state to all peers. It sends periodic heartbeats when there are no state updates.

It also tracks ephemeral state broadcast by peers and emits events when peers send ephemeral state updates (see PresenceEvents).

Presence starts out in an inactive state. Call start and stop to activate and deactivate it.

Type Parameters

State extends PresenceState
DocType = any

Hierarchy

EventEmitter<PresenceEvents>
- Presence

Index

Constructors

constructor

new Presence<State extends PresenceState, DocType = any>(
    config: {
        deviceId?: unknown;
        handle: DocHandle<DocType>;
        userId?: unknown;
    },
): Presence<State, DocType>
Create a new Presence to share ephemeral state with peers.
Type Parameters
- State extends PresenceState
- DocType = any
Parameters
- config: { deviceId?: unknown; handle: DocHandle<DocType>; userId?: unknown }
  see PresenceConfig
  - OptionaldeviceId?: unknown
    Our device id (like userId, this is unverified; peers can send anything)
  - handle: DocHandle<DocType>
  - OptionaluserId?: unknown
    Our user id (this is unverified; peers can send anything)
Returns Presence<State, DocType>
Overrides EventEmitter<PresenceEvents>.constructor
- Defined in packages/automerge-repo/src/presence/Presence.ts:58

Properties

`Optional` `Readonly`deviceId

deviceId?: unknown

`Optional` `Readonly`userId

userId?: unknown

`Static`prefixed

prefixed: string | boolean

Accessors

running

get running(): boolean
Whether this Presence is currently active. See start and stop.

Returns boolean
- Defined in packages/automerge-repo/src/presence/Presence.ts:194

Methods

addListener

addListener<T extends keyof PresenceEvents>(
    event: T,
    fn: (
        ...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>],
    ) => void,
    context?: any,
): this
Type Parameters
- T extends keyof PresenceEvents
Parameters
- event: T
- fn: (...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>]) => void
- Optionalcontext: any
Returns this
Inherited from EventEmitter.addListener
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:45

broadcast

broadcast<Channel extends string | number | symbol>(
channel: Channel,
value: State[Channel],
): void
Update state for the specific channel, and broadcast new state to all peers.
Type Parameters
- Channel extends string | number | symbol
Parameters
- channel: Channel
- value: State[Channel]
Returns void
- Defined in packages/automerge-repo/src/presence/Presence.ts:180

emit

emit<T extends keyof PresenceEvents>(
event: T,
...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>],
): boolean
Calls each of the listeners registered for a given event.
Type Parameters
- T extends keyof PresenceEvents
Parameters
- event: T
- ...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>]
Returns boolean
Inherited from EventEmitter.emit
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:32

eventNames

eventNames(): (keyof PresenceEvents)[]
Return an array listing the events for which the emitter has registered listeners.

Returns (keyof PresenceEvents)[]
Inherited from EventEmitter.eventNames
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:15

getLocalState

getLocalState(): State
Return a view of current local state.

Returns State
- Defined in packages/automerge-repo/src/presence/Presence.ts:169

getPeerStates

getPeerStates(): PeerStateView<State>
Return a view of current peer states.

Returns PeerStateView<State>
- Defined in packages/automerge-repo/src/presence/Presence.ts:162

listenerCount

listenerCount(event: keyof PresenceEvents): number
Return the number of listeners listening to a given event.
Parameters
- event: keyof PresenceEvents
Returns number
Inherited from EventEmitter.listenerCount
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:27

listeners

listeners<T extends keyof PresenceEvents>(
    event: T,
): (
    (
        ...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>],
    ) => void
)[]
Return the listeners registered for a given event.
Type Parameters
- T extends keyof PresenceEvents
Parameters
- event: T
Returns (
    (
        ...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>],
    ) => void
)[]
Inherited from EventEmitter.listeners
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:20

off

off<T extends keyof PresenceEvents>(
    event: T,
    fn?: (
        ...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>],
    ) => void,
    context?: any,
    once?: boolean,
): this
Type Parameters
- T extends keyof PresenceEvents
Parameters
- event: T
- Optionalfn: (...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>]) => void
- Optionalcontext: any
- Optionalonce: boolean
Returns this
Inherited from EventEmitter.off
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:69

on

on<T extends keyof PresenceEvents>(
    event: T,
    fn: (
        ...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>],
    ) => void,
    context?: any,
): this
Add a listener for a given event.
Type Parameters
- T extends keyof PresenceEvents
Parameters
- event: T
- fn: (...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>]) => void
- Optionalcontext: any
Returns this
Inherited from EventEmitter.on
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:40

once

once<T extends keyof PresenceEvents>(
    event: T,
    fn: (
        ...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>],
    ) => void,
    context?: any,
): this
Add a one-time listener for a given event.
Type Parameters
- T extends keyof PresenceEvents
Parameters
- event: T
- fn: (...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>]) => void
- Optionalcontext: any
Returns this
Inherited from EventEmitter.once
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:54

removeAllListeners

removeAllListeners(event?: keyof PresenceEvents): this
Remove all listeners, or those of the specified event.
Parameters
- Optionalevent: keyof PresenceEvents
Returns this
Inherited from EventEmitter.removeAllListeners
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:79

removeListener

removeListener<T extends keyof PresenceEvents>(
    event: T,
    fn?: (
        ...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>],
    ) => void,
    context?: any,
    once?: boolean,
): this
Remove the listeners of a given event.
Type Parameters
- T extends keyof PresenceEvents
Parameters
- event: T
- Optionalfn: (...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>]) => void
- Optionalcontext: any
- Optionalonce: boolean
Returns this
Inherited from EventEmitter.removeListener
- Defined in node_modules/.pnpm/[email protected]/node_modules/eventemitter3/index.d.ts:63

start

start(__namedParameters: PresenceConfig<State>): void
Start listening to ephemeral messages on the handle, broadcast initial state to peers, and start sending heartbeats.
Parameters
- __namedParameters: PresenceConfig<State>
Returns void
- Defined in packages/automerge-repo/src/presence/Presence.ts:81

stop

stop(): void
Stop this Presence: broadcast a "goodbye" message (when received, other peers will immediately forget the sender), stop sending heartbeats, and stop listening to ephemeral-messages broadcast from peers.

This can be used with browser events like "pagehide" or "visibilitychange" to stop sending and receiving updates when not active.

Returns void
- Defined in packages/automerge-repo/src/presence/Presence.ts:209

Class Presence<State, DocType>

Type Parameters

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

OptionaldeviceId?: unknown

handle: DocHandle<DocType>

OptionaluserId?: unknown

Returns Presence<State, DocType>

Properties

Optional ReadonlydeviceId

Optional ReadonlyuserId

Staticprefixed

Accessors

running

Returns boolean

Methods

addListener

Type Parameters

Parameters

Returns this

broadcast

Type Parameters

Parameters

Returns void

emit

Type Parameters

Parameters

Returns boolean

eventNames

Returns (keyof PresenceEvents)[]

getLocalState

Returns State

getPeerStates

Returns PeerStateView<State>

listenerCount

Parameters

Returns number

listeners

Type Parameters

Parameters

Returns ( ( ...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>], ) => void)[]

off

Type Parameters

Parameters

Returns this

on

Type Parameters

Parameters

Returns this

once

Type Parameters

Parameters

Returns this

removeAllListeners

Parameters

Returns this

removeListener

Type Parameters

Parameters

Returns this

start

Parameters

Returns void

stop

Returns void

Settings

On This Page

`Optional`deviceId?: unknown

`Optional`userId?: unknown

`Optional` `Readonly`deviceId

`Optional` `Readonly`userId

`Static`prefixed

Returns (
(
...args: ArgumentMap<PresenceEvents>[Extract<T, keyof PresenceEvents>],
) => void
)[]