@automerge/automerge-repo 2.5.1 → 2.5.2-alpha.0

package/dist/Presence.d.ts

@@ -0,0 +1,245 @@
+import { DocHandle } from "./DocHandle.js";
+import { PeerId } from "./types.js";
+import { EventEmitter } from "eventemitter3";
+export type UserId = unknown;
+export type DeviceId = unknown;
+export declare const PRESENCE_MESSAGE_MARKER = "__presence";
+export type PeerState<State> = {
+    peerId: PeerId;
+    deviceId?: DeviceId;
+    userId?: UserId;
+    value: State;
+};
+type PresenceMessageBase = {
+    deviceId?: DeviceId;
+    userId?: UserId;
+};
+type PresenceMessageUpdate = PresenceMessageBase & {
+    type: "update";
+    channel: string;
+    value: any;
+};
+type PresenceMessageSnapshot = PresenceMessageBase & {
+    type: "snapshot";
+    state: any;
+};
+type PresenceMessageHeartbeat = PresenceMessageBase & {
+    type: "heartbeat";
+};
+type PresenceMessageGoodbye = PresenceMessageBase & {
+    type: "goodbye";
+};
+type WithPeerId = {
+    peerId: PeerId;
+};
+export type PresenceEventUpdate = PresenceMessageUpdate & WithPeerId;
+export type PresenceEventSnapshot = PresenceMessageSnapshot & WithPeerId;
+export type PresenceEventHeartbeat = PresenceMessageHeartbeat & WithPeerId;
+export type PresenceEventGoodbye = PresenceMessageGoodbye & WithPeerId;
+/**
+ * Events emitted by Presence when ephemeral messages are received from peers.
+ */
+export type PresenceEvents = {
+    /**
+     * Handle a state update broadcast by a peer.
+     */
+    update: (msg: PresenceEventUpdate) => void;
+    /**
+     * Handle a full state snapshot broadcast by a peer.
+     */
+    snapshot: (msg: PresenceEventSnapshot) => void;
+    /**
+     * Handle a heartbeat broadcast by a peer.
+     */
+    heartbeat: (msg: PresenceEventHeartbeat) => void;
+    /**
+     * Handle a disconnection broadcast by a peer.
+     */
+    goodbye: (msg: PresenceEventGoodbye) => void;
+};
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 15000;
+export declare const DEFAULT_PEER_TTL_MS: number;
+export type PresenceConfig<State> = {
+    /** The full initial state to broadcast to peers */
+    initialState: State;
+    /** How frequently to send heartbeats (default {@link DEFAULT_HEARTBEAT_INTERVAL_MS}) */
+    heartbeatMs?: number;
+    /** How long to wait until forgetting peers with no activity  (default {@link DEFAULT_PEER_TTL_MS}) */
+    peerTtlMs?: number;
+};
+/**
+ * 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 {@link PresenceEvents}).
+ *
+ * Presence starts out in an inactive state. Call {@link start} and {@link stop}
+ * to activate and deactivate it.
+ */
+export declare class Presence<State extends Record<string, any>, DocType = any> extends EventEmitter<PresenceEvents> {
+    #private;
+    readonly deviceId?: DeviceId;
+    readonly userId?: UserId;
+    /**
+     * Create a new Presence to share ephemeral state with peers.
+     *
+     * @param config see {@link PresenceConfig}
+     * @returns
+     */
+    constructor({ handle, deviceId, userId, }: {
+        handle: DocHandle<DocType>;
+        /** Our device id (like userId, this is unverified; peers can send anything) */
+        deviceId?: DeviceId;
+        /** Our user id (this is unverified; peers can send anything) */
+        userId?: UserId;
+    });
+    /**
+     * Start listening to ephemeral messages on the handle, broadcast initial
+     * state to peers, and start sending heartbeats.
+     */
+    start({ initialState, heartbeatMs, peerTtlMs }: PresenceConfig<State>): void;
+    /**
+     * Return a view of current peer states.
+     */
+    getPeerStates(): PeerPresenceView<State>;
+    /**
+     * Return a view of current local state.
+     */
+    getLocalState(): State | undefined;
+    /**
+     * Update state for the specific channel, and broadcast new state to all
+     * peers.
+     *
+     * @param channel
+     * @param value
+     */
+    broadcast<Channel extends keyof State>(channel: Channel, value: State[Channel]): void;
+    /**
+     * Whether this Presence is currently active. See
+     * {@link start} and {@link stop}.
+     */
+    get running(): boolean;
+    /**
+     * 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
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/pagehide_event | "pagehide"}
+     * or
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilitychange_event | "visibilitychange"}
+     * to stop sending and receiving updates when not active.
+     */
+    stop(): void;
+    private announce;
+    private broadcastLocalState;
+    private broadcastChannelState;
+    private resetHeartbeats;
+    private sendHeartbeat;
+    private doBroadcast;
+    private startHeartbeats;
+    private stopHeartbeats;
+    private startPruningPeers;
+    private stopPruningPeers;
+}
+/**
+ * A summary of the latest Presence information for the set of peers who have
+ * reported a Presence status to us.
+ */
+export declare class PeerPresenceView<State> {
+    #private;
+    /** @hidden */
+    constructor(peersLastSeen: Map<PeerId, number>, peerStates: Map<PeerId, PeerState<State>>, userPeers: Map<UserId, Set<PeerId>>, devicePeers: Map<DeviceId, Set<PeerId>>);
+    /**
+     * Check if peer is currently present.
+     *
+     * @param peerId
+     * @returns true if the peer has been seen recently
+     */
+    has(peerId: PeerId): boolean;
+    /**
+     * Check when the peer was last seen.
+     *
+     * @param peerId
+     * @returns last seen UNIX timestamp, or undefined for unknown peers
+     */
+    getLastSeen(peerId: PeerId): number | undefined;
+    /**
+     * Get all recently-seen peers.
+     *
+     * @returns Array of peer ids
+     */
+    getPeers(): PeerId[];
+    /**
+     * Get all recently-seen users.
+     *
+     * @returns Array of user ids
+     */
+    getUsers(): unknown[];
+    /**
+     * Get all recently-seen devices.
+     *
+     * @returns Array of device ids
+     */
+    getDevices(): unknown[];
+    /**
+     * Get all recently-seen peers for this user.
+     *
+     * @param userId
+     * @returns Array of peer ids for this user
+     */
+    getUserPeers(userId: UserId): PeerId[] | undefined;
+    /**
+     * Get all recently-seen peers for this device.
+     *
+     * @param deviceId
+     * @returns Array of peer ids for this device
+     */
+    getDevicePeers(deviceId: DeviceId): PeerId[] | undefined;
+    /**
+     * Get most-recently-seen peer from this group.
+     *
+     * @param peers
+     * @returns id of most recently seen peer
+     */
+    getFreshestPeer(peers: Set<PeerId>): PeerId | undefined;
+    /**
+     * Get current @type PeerState for given peer.
+     *
+     * @param peerId
+     * @returns details for the peer
+     */
+    getPeerInfo(peerId: PeerId): PeerState<State> | undefined;
+    /**
+     * Get current ephemeral state value for this peer. If a channel is specified,
+     * only returns the ephemeral state for that specific channel. Otherwise,
+     * returns the full ephemeral state.
+     *
+     * @param peerId
+     * @param channel
+     * @returns latest ephemeral state received
+     */
+    getPeerState<Channel extends keyof State>(peerId: PeerId, channel?: Channel): State | NonNullable<State>[Channel] | undefined;
+    /**
+     * Get current ephemeral state value for this user's most-recently-active
+     * peer. See {@link getPeerState}.
+     *
+     * @param userId
+     * @param channel
+     * @returns
+     */
+    getUserState<Channel extends keyof State>(userId: UserId, channel?: Channel): State | NonNullable<State>[Channel] | undefined;
+    /**
+     * Get current ephemeral state value for this device's most-recently-active
+     * peer. See {@link getPeerState}.
+     *
+     * @param userId
+     * @param channel
+     * @returns
+     */
+    getDeviceState<Channel extends keyof State>(deviceId: UserId, channel?: Channel): State | NonNullable<State>[Channel] | undefined;
+}
+export {};
+//# sourceMappingURL=Presence.d.ts.map

package/dist/Presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Presence.d.ts","sourceRoot":"","sources":["../src/Presence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAoC,MAAM,gBAAgB,CAAA;AAC5E,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAE5C,MAAM,MAAM,MAAM,GAAG,OAAO,CAAA;AAC5B,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAA;AAE9B,eAAO,MAAM,uBAAuB,eAAe,CAAA;AAEnD,MAAM,MAAM,SAAS,CAAC,KAAK,IAAI;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,KAAK,CAAA;CACb,CAAA;AAED,KAAK,mBAAmB,GAAG;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,KAAK,qBAAqB,GAAG,mBAAmB,GAAG;IACjD,IAAI,EAAE,QAAQ,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,GAAG,CAAA;CACX,CAAA;AAED,KAAK,uBAAuB,GAAG,mBAAmB,GAAG;IACnD,IAAI,EAAE,UAAU,CAAA;IAChB,KAAK,EAAE,GAAG,CAAA;CACX,CAAA;AAED,KAAK,wBAAwB,GAAG,mBAAmB,GAAG;IACpD,IAAI,EAAE,WAAW,CAAA;CAClB,CAAA;AAED,KAAK,sBAAsB,GAAG,mBAAmB,GAAG;IAClD,IAAI,EAAE,SAAS,CAAA;CAChB,CAAA;AAaD,KAAK,UAAU,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpC,MAAM,MAAM,mBAAmB,GAAG,qBAAqB,GAAG,UAAU,CAAA;AACpE,MAAM,MAAM,qBAAqB,GAAG,uBAAuB,GAAG,UAAU,CAAA;AACxE,MAAM,MAAM,sBAAsB,GAAG,wBAAwB,GAAG,UAAU,CAAA;AAC1E,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,GAAG,UAAU,CAAA;AAEtE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;OAEG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,IAAI,CAAA;IAC1C;;OAEG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;IAC9C;;OAEG;IACH,SAAS,EAAE,CAAC,GAAG,EAAE,sBAAsB,KAAK,IAAI,CAAA;IAChD;;OAEG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE,oBAAoB,KAAK,IAAI,CAAA;CAC7C,CAAA;AAED,eAAO,MAAM,6BAA6B,QAAS,CAAA;AACnD,eAAO,MAAM,mBAAmB,QAAoC,CAAA;AAEpE,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI;IAClC,mDAAmD;IACnD,YAAY,EAAE,KAAK,CAAA;IACnB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sGAAsG;IACtG,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;GAUG;AACH,qBAAa,QAAQ,CACnB,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,OAAO,GAAG,GAAG,CACb,SAAQ,YAAY,CAAC,cAAc,CAAC;;IAEpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IAexB;;;;;OAKG;gBACS,EACV,MAAM,EACN,QAAQ,EACR,MAAM,GACP,EAAE;QACD,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;QAC1B,+EAA+E;QAC/E,QAAQ,CAAC,EAAE,QAAQ,CAAA;QACnB,gEAAgE;QAChE,MAAM,CAAC,EAAE,MAAM,CAAA;KAChB;IAQD;;;OAGG;IACH,KAAK,CAAC,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC;IA4FrE;;OAEG;IACH,aAAa;IAIb;;OAEG;IACH,aAAa;IAIb;;;;;;OAMG;IACH,SAAS,CAAC,OAAO,SAAS,MAAM,KAAK,EACnC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC;IAQvB;;;OAGG;IACH,IAAI,OAAO,YAEV;IAED;;;;;;;;;;OAUG;IACH,IAAI;IAeJ,OAAO,CAAC,QAAQ;IAWhB,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,WAAW;IAiBnB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,gBAAgB;CAOzB;AAED;;;GAGG;AACH,qBAAa,gBAAgB,CAAC,KAAK;;IAMjC,cAAc;gBAEZ,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,EACzC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,EACnC,WAAW,EAAE,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAQzC;;;;;OAKG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM;IAIlB;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM;IAI1B;;;;OAIG;IACH,QAAQ;IAIR;;;;OAIG;IACH,QAAQ;IAIR;;;;OAIG;IACH,UAAU;IAIV;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM;IAQ3B;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,QAAQ;IAQjC;;;;;OAKG;IACH,eAAe,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC;IAiBlC;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM;IAI1B;;;;;;;;OAQG;IACH,YAAY,CAAC,OAAO,SAAS,MAAM,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;IAS3E;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,SAAS,MAAM,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;IAa3E;;;;;;;OAOG;IACH,cAAc,CAAC,OAAO,SAAS,MAAM,KAAK,EACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,OAAO;CAapB"}