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

package/dist/presence/Presence.js

@@ -0,0 +1,245 @@
+import { EventEmitter } from "eventemitter3";
+import { DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_PEER_TTL_MS, PRESENCE_MESSAGE_MARKER, } from "./constants.js";
+import { PeerPresenceInfo } from "./PeerPresenceInfo.js";
+/**
+ * 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 class Presence extends EventEmitter {
+    #handle;
+    deviceId;
+    userId;
+    #peers;
+    #localState;
+    #heartbeatMs;
+    #handleEphemeralMessage;
+    #heartbeatInterval;
+    #pruningInterval;
+    #hellos = [];
+    #running = false;
+    /**
+     * Create a new Presence to share ephemeral state with peers.
+     *
+     * @param config see {@link PresenceConfig}
+     * @returns
+     */
+    constructor({ handle, deviceId, userId, }) {
+        super();
+        this.#handle = handle;
+        this.#peers = new PeerPresenceInfo(DEFAULT_PEER_TTL_MS);
+        this.#localState = {};
+        this.userId = userId;
+        this.deviceId = deviceId;
+    }
+    /**
+     * Start listening to ephemeral messages on the handle, broadcast initial
+     * state to peers, and start sending heartbeats.
+     */
+    start({ initialState, heartbeatMs, peerTtlMs }) {
+        if (this.#running) {
+            return;
+        }
+        this.#running = true;
+        this.#heartbeatMs = heartbeatMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+        this.#peers = new PeerPresenceInfo(peerTtlMs ?? DEFAULT_PEER_TTL_MS);
+        this.#localState = initialState;
+        // N.B.: We can't use a regular member function here since member functions
+        // of two distinct objects are identical, and we need to be able to stop
+        // listening to the handle for just this Presence instance in stop()
+        this.#handleEphemeralMessage = (e) => {
+            const peerId = e.senderId;
+            const envelope = e.message;
+            if (!(PRESENCE_MESSAGE_MARKER in envelope)) {
+                return;
+            }
+            const message = envelope[PRESENCE_MESSAGE_MARKER];
+            const { deviceId, userId } = message;
+            if (!this.#peers.has(peerId)) {
+                this.announce();
+            }
+            switch (message.type) {
+                case "heartbeat":
+                    this.#peers.markSeen(peerId);
+                    this.emit("heartbeat", { type: "heartbeat", peerId });
+                    break;
+                case "goodbye":
+                    this.#peers.delete(peerId);
+                    this.emit("goodbye", { type: "goodbye", peerId });
+                    break;
+                case "update":
+                    this.#peers.update({
+                        peerId,
+                        deviceId,
+                        userId,
+                        value: { [message.channel]: message.value },
+                    });
+                    this.emit("update", {
+                        type: "update",
+                        peerId,
+                        deviceId,
+                        userId,
+                        channel: message.channel,
+                        value: message.value,
+                    });
+                    break;
+                case "snapshot":
+                    this.#peers.update({
+                        peerId,
+                        deviceId,
+                        userId,
+                        value: message.state,
+                    });
+                    this.emit("snapshot", {
+                        type: "snapshot",
+                        peerId,
+                        deviceId,
+                        userId,
+                        state: message.state,
+                    });
+                    break;
+            }
+        };
+        this.#handle.on("ephemeral-message", this.#handleEphemeralMessage);
+        this.broadcastLocalState(); // also starts heartbeats
+        this.startPruningPeers();
+    }
+    /**
+     * Return a view of current peer states.
+     */
+    getPeerStates() {
+        return this.#peers.states;
+    }
+    /**
+     * Return a view of current local state.
+     */
+    getLocalState() {
+        return this.#localState;
+    }
+    /**
+     * Update state for the specific channel, and broadcast new state to all
+     * peers.
+     *
+     * @param channel
+     * @param value
+     */
+    broadcast(channel, value) {
+        this.#localState = Object.assign({}, this.#localState, {
+            [channel]: value,
+        });
+        this.broadcastChannelState(channel);
+    }
+    /**
+     * Whether this Presence is currently active. See
+     * {@link start} and {@link stop}.
+     */
+    get running() {
+        return this.#running;
+    }
+    /**
+     * 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() {
+        if (!this.#running) {
+            return;
+        }
+        this.#hellos.forEach(timeoutId => {
+            clearTimeout(timeoutId);
+        });
+        this.#hellos = [];
+        this.#handle.off("ephemeral-message", this.#handleEphemeralMessage);
+        this.stopHeartbeats();
+        this.stopPruningPeers();
+        this.send({ type: "goodbye" });
+        this.#running = false;
+    }
+    announce() {
+        // Broadcast our current state whenever we see new peers
+        // TODO: We currently need to wait for the peer to be ready, but waiting
+        // some arbitrary amount of time is brittle
+        const helloId = setTimeout(() => {
+            this.broadcastLocalState();
+            this.#hellos = this.#hellos.filter(id => id !== helloId);
+        }, 500);
+        this.#hellos.push(helloId);
+    }
+    broadcastLocalState() {
+        this.doBroadcast("snapshot", { state: this.#localState });
+        this.resetHeartbeats();
+    }
+    broadcastChannelState(channel) {
+        const value = this.#localState[channel];
+        this.doBroadcast("update", { channel, value });
+        this.resetHeartbeats();
+    }
+    resetHeartbeats() {
+        // Reset heartbeats every time we broadcast a message to avoid sending
+        // unnecessary heartbeats when there is plenty of actual update activity
+        // happening.
+        this.stopHeartbeats();
+        this.startHeartbeats();
+    }
+    doBroadcast(type, extra) {
+        this.send({
+            userId: this.userId,
+            deviceId: this.deviceId,
+            type,
+            ...extra,
+        });
+    }
+    send(message) {
+        if (!this.#running) {
+            return;
+        }
+        this.#handle.broadcast({
+            [PRESENCE_MESSAGE_MARKER]: message,
+        });
+    }
+    startHeartbeats() {
+        if (this.#heartbeatInterval !== undefined) {
+            return;
+        }
+        this.#heartbeatInterval = setInterval(() => {
+            this.send({ type: "heartbeat" });
+        }, this.#heartbeatMs);
+    }
+    stopHeartbeats() {
+        if (this.#heartbeatInterval === undefined) {
+            return;
+        }
+        clearInterval(this.#heartbeatInterval);
+        this.#heartbeatInterval = undefined;
+    }
+    startPruningPeers() {
+        if (this.#pruningInterval !== undefined) {
+            return;
+        }
+        // Pruning happens at the heartbeat frequency, not on a peer ttl frequency,
+        // to minimize variance between peer expiration, since the heartbeat frequency
+        // is expected to be several times higher.
+        this.#pruningInterval = setInterval(() => {
+            this.#peers.prune();
+        }, this.#heartbeatMs);
+    }
+    stopPruningPeers() {
+        if (this.#pruningInterval === undefined) {
+            return;
+        }
+        clearInterval(this.#pruningInterval);
+        this.#pruningInterval = undefined;
+    }
+}

package/dist/presence/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 15000;
+export declare const DEFAULT_PEER_TTL_MS: number;
+export declare const PRESENCE_MESSAGE_MARKER = "__presence";
+//# sourceMappingURL=constants.d.ts.map

package/dist/presence/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/presence/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,6BAA6B,QAAS,CAAA;AACnD,eAAO,MAAM,mBAAmB,QAAoC,CAAA;AACpE,eAAO,MAAM,uBAAuB,eAAe,CAAA"}

package/dist/presence/constants.js

@@ -0,0 +1,3 @@
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 15_000;
+export const DEFAULT_PEER_TTL_MS = 3 * DEFAULT_HEARTBEAT_INTERVAL_MS;
+export const PRESENCE_MESSAGE_MARKER = "__presence";

package/dist/presence/types.d.ts

@@ -0,0 +1,75 @@
+import { PeerId } from "../types.js";
+import { PRESENCE_MESSAGE_MARKER } from "./constants.js";
+export type UserId = unknown;
+export type DeviceId = unknown;
+export type PresenceState = Record<string, any>;
+export type PeerStatesValue<State extends PresenceState> = Record<PeerId, PeerState<State>>;
+export type PeerState<State extends PresenceState> = {
+    peerId: PeerId;
+    lastActiveAt: number;
+    lastUpdateAt: number;
+    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";
+};
+export type PresenceMessage = {
+    [PRESENCE_MESSAGE_MARKER]: PresenceMessageUpdate | PresenceMessageSnapshot | PresenceMessageHeartbeat | PresenceMessageGoodbye;
+};
+export type PresenceMessageType = PresenceMessage[typeof PRESENCE_MESSAGE_MARKER]["type"];
+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 type PresenceConfig<State extends PresenceState> = {
+    /** 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;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/presence/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/presence/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AAExD,MAAM,MAAM,MAAM,GAAG,OAAO,CAAA;AAC5B,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAA;AAE9B,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAE/C,MAAM,MAAM,eAAe,CAAC,KAAK,SAAS,aAAa,IAAI,MAAM,CAC/D,MAAM,EACN,SAAS,CAAC,KAAK,CAAC,CACjB,CAAA;AAED,MAAM,MAAM,SAAS,CAAC,KAAK,SAAS,aAAa,IAAI;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,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;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,CAAC,uBAAuB,CAAC,EACrB,qBAAqB,GACrB,uBAAuB,GACvB,wBAAwB,GACxB,sBAAsB,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,mBAAmB,GAC7B,eAAe,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEzD,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,MAAM,MAAM,cAAc,CAAC,KAAK,SAAS,aAAa,IAAI;IACxD,mDAAmD;IACnD,YAAY,EAAE,KAAK,CAAA;IACnB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sGAAsG;IACtG,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA"}

package/dist/presence/types.js

@@ -0,0 +1 @@
+import { PRESENCE_MESSAGE_MARKER } from "./constants.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "2.5.1",
+  "version": "2.5.2-alpha.1",
   "description": "A repository object to manage a collection of automerge documents",
   "repository": "https://github.com/automerge/automerge-repo/tree/master/packages/automerge-repo",
   "author": "Peter van Hardenberg <pvh@pvh.ca>",
@@ -59,5 +59,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "66b8457234d04468e653b85d5cf58a9a3cd4c691"
+  "gitHead": "96ab95c2e84b6bd4d8c3a2852368cb35d7ed1b52"
 }

package/src/helpers/array.ts

@@ -0,0 +1,3 @@
+export function unique<T>(items: T[]) {
+  return Array.from(new Set(items))
+}

package/src/index.ts

@@ -39,6 +39,16 @@ export {
   decodeHeads,
 } from "./AutomergeUrl.js"
 export { Repo } from "./Repo.js"
+export { Presence } from "./presence/Presence.js"
+export { PeerStateView } from "./presence/PeerStateView.js"
+export type {
+  PeerState,
+  PresenceState,
+  PresenceConfig,
+  UserId,
+  DeviceId,
+} from "./presence/types.js"
+
 export { NetworkAdapter } from "./network/NetworkAdapter.js"
 export type { NetworkAdapterInterface } from "./network/NetworkAdapterInterface.js"
 export { isRepoMessage } from "./network/messages.js"

package/src/presence/PeerPresenceInfo.ts

@@ -0,0 +1,108 @@
+import { PeerId } from "../types.js"
+import { PeerStateView } from "./PeerStateView.js"
+import { DeviceId, PresenceState, UserId } from "./types.js"
+
+export class PeerPresenceInfo<State extends PresenceState> {
+  #peerStates = new PeerStateView<State>({})
+
+  /**
+   * Build a new peer presence state.
+   *
+   * @param ttl in milliseconds - peers with no activity within this timeframe
+   * are forgotten when {@link prune} is called.
+   */
+  constructor(readonly ttl: number) {}
+
+  has(peerId: PeerId) {
+    return peerId in this.#peerStates.value
+  }
+
+  /**
+   * Record that we've seen the given peer recently.
+   *
+   * @param peerId
+   */
+  markSeen(peerId: PeerId) {
+    this.#peerStates = new PeerStateView<State>({
+      ...this.#peerStates.value,
+      [peerId]: {
+        ...this.#peerStates.value[peerId],
+        lastSeen: Date.now(),
+      },
+    })
+  }
+
+  /**
+   * Record a state update for the given peer. Note that existing state is not
+   * overwritten.
+   *
+   * @param peerId
+   * @param value
+   */
+  update({
+    peerId,
+    deviceId,
+    userId,
+    value,
+  }: {
+    peerId: PeerId
+    deviceId?: DeviceId
+    userId?: UserId
+    value: Partial<State>
+  }) {
+    const peerState = this.#peerStates.value[peerId]
+    const existingState = peerState?.value ?? ({} as State)
+    const now = Date.now()
+    this.#peerStates = new PeerStateView<State>({
+      ...this.#peerStates.value,
+      [peerId]: {
+        peerId,
+        deviceId,
+        userId,
+        lastActiveAt: now,
+        lastUpdateAt: now,
+        value: {
+          ...existingState,
+          ...value,
+        },
+      },
+    })
+  }
+
+  /**
+   * Forget the given peer.
+   *
+   * @param peerId
+   */
+  delete(peerId: PeerId) {
+    this.#peerStates = new PeerStateView<State>(
+      Object.fromEntries(
+        Object.entries(this.#peerStates.value).filter(([existingId]) => {
+          return existingId != peerId
+        })
+      )
+    )
+  }
+
+  /**
+   * Prune all peers that have not been seen since the configured ttl has
+   * elapsed.
+   */
+  prune() {
+    const threshold = Date.now() - this.ttl
+    this.#peerStates = new PeerStateView<State>(
+      Object.fromEntries(
+        Object.entries(this.#peerStates).filter(([, state]) => {
+          return state.lastActiveAt >= threshold
+        })
+      )
+    )
+  }
+
+  /**
+   * Get a snapshot of the current peer states
+   */
+  get states() {
+    return this.#peerStates
+  }
+}

package/src/presence/PeerStateView.ts

@@ -0,0 +1,154 @@
+import { unique } from "../helpers/array.js"
+import { PeerId } from "../types.js"
+import { DeviceId, PeerStatesValue, PresenceState, UserId } from "./types.js"
+
+export class PeerStateView<State extends PresenceState> {
+  readonly value
+
+  constructor(value: PeerStatesValue<State>) {
+    this.value = value
+  }
+
+  /**
+   * Get all users.
+   *
+   * @returns Array of user presence {@link State}s
+   */
+  get users() {
+    const userIds = unique(
+      Object.values(this.value).map(peerState => peerState.userId)
+    )
+    return userIds.map(u => this.getUserState(u))
+  }
+
+  /**
+   * Get all devices.
+   *
+   * @returns Array of device presence {@link State}s
+   */
+  get devices() {
+    const deviceIds = unique(
+      Object.values(this.value).map(peerState => peerState.deviceId)
+    )
+    return deviceIds.map(d => this.getDeviceState(d))
+  }
+
+  /**
+   * Get all peers.
+   *
+   * @returns Array of peer presence {@link State}s
+   */
+  get peers() {
+    return Object.values(this.value)
+  }
+
+  /**
+   * Get all peer ids for this user.
+   *
+   * @param userId
+   * @returns Array of peer ids for this user
+   */
+  getUserPeers(userId: UserId) {
+    return Object.values(this.value)
+      .filter(peerState => peerState.userId === userId)
+      .map(peerState => peerState.peerId)
+  }
+
+  /**
+   * Get all peers for this device.
+   *
+   * @param deviceId
+   * @returns Array of peer ids for this device
+   */
+  getDevicePeers(deviceId: DeviceId) {
+    return Object.values(this.value)
+      .filter(peerState => peerState.deviceId === deviceId)
+      .map(peerState => peerState.peerId)
+  }
+
+  /**
+   * Return the most-recently-seen peer from this group.
+   *
+   * @param peers
+   * @returns id of most recently seen peer
+   */
+  getLastSeenPeer(peers: PeerId[]) {
+    let freshestLastSeenAt: number
+    return peers.reduce((freshest: PeerId | undefined, curr) => {
+      const lastSeenAt = this.value[curr]?.lastActiveAt
+      if (!lastSeenAt) {
+        return freshest
+      }
+
+      if (!freshest || lastSeenAt > freshestLastSeenAt) {
+        freshestLastSeenAt = lastSeenAt
+        return curr
+      }
+
+      return freshest
+    }, undefined)
+  }
+
+  /**
+   * Return the peer from this group that sent a state update most recently
+   *
+   * @param peers
+   * @returns id of most recently seen peer
+   */
+  getLastActivePeer(peers: PeerId[]) {
+    let freshestLastActiveAt: number
+    return peers.reduce((freshest: PeerId | undefined, curr) => {
+      const lastActiveAt = this.value[curr]?.lastActiveAt
+      if (!lastActiveAt) {
+        return freshest
+      }
+
+      if (!freshest || lastActiveAt > freshestLastActiveAt) {
+        freshestLastActiveAt = lastActiveAt
+        return curr
+      }
+
+      return freshest
+    }, undefined)
+  }
+
+  /**
+   * Get current ephemeral state value for this user's most-recently-active
+   * peer.
+   *
+   * @param userId
+   * @returns user's {@link State}
+   */
+  getUserState(userId: UserId) {
+    const peers = this.getUserPeers(userId)
+    if (!peers) {
+      return undefined
+    }
+    const peer = this.getLastActivePeer(peers)
+    if (!peer) {
+      return undefined
+    }
+
+    return this.value[peer]
+  }
+
+  /**
+   * Get current ephemeral state value for this device's most-recently-active
+   * peer.
+   *
+   * @param deviceId
+   * @returns device's {@link State}
+   */
+  getDeviceState(deviceId: DeviceId) {
+    const peers = this.getDevicePeers(deviceId)
+    if (!peers) {
+      return undefined
+    }
+    const peer = this.getLastActivePeer(peers)
+    if (!peer) {
+      return undefined
+    }
+
+    return this.value[peer]
+  }
+}