Stateful WebSocket listeners for snapshot and updates

[present-g]

Hi!

I'd like to hear your thoughts on a possible approach to handling stateful WebSocket subscriptions in HyperFetch.

Some WebSocket APIs send an initial snapshot followed by incremental updates (upsert, delete, etc.). Currently, handling this requires maintaining accumulated state separately, for example using React state or Zustand.

I was wondering whether it would make sense to support optional state accumulation directly within listeners.

Here are two possible API approaches:

Option 1: Add state to existing listeners

const listener = socket.createListener<PositionEvent>()({
  topic: "positions",
  state: {
    initial: [],
    reducer: (state, event) => applyDelta(state, event),
  },
});

const { data } = useListener(listener);

// Access accumulated state outside React
const positions = listener.getState();

Option 2: Introduce createStatefulListener

const listener = socket.createStatefulListener<PositionEvent>()({
  topic: "positions",
  initial: [],
  reducer: (state, event) => applyDelta(state, event),
});

const { data } = useListener(listener);

// Access accumulated state outside React
const positions = listener.getState();

In both cases, the idea would be to accumulate state as events arrive, share it across subscribers, and expose the current snapshot through getState().

These are just rough ideas, not a concrete feature proposal. I'd be interested to hear whether you see value in something like this, and which approach (if any) would fit HyperFetch's architecture better.

Thanks!

[present-g]

@prc5, hi, what do you think about it?

By the way, it would be cool to connect it with the REST initial state as well, if the idea works out.

[prc5]

Hey! I tried to keep it rather stateless by design, because back in the time when I tried to play around the idea of state/cache for it, it turned out that there are just countless use-cases. So people want the whole log of the messages, some want only last message etc. Due to this kind of dynamic nature of websockets, I decided to just leave it as simple proxy between passing down the message and saving it to the state, so it is up to us how we want to manage that.

The other part is that usually I saw one pattern that happened for the HF:
I was using requests from the core packages together with the sockets listeners, so when message arrived, I was updating cache in the request - this synergy was working very well for me and I stopped there on the state management for sockets 👀

Let's discuss, this is quite interesting!

[present-g]

The more I think about it, the more I realize there are quite a few architectural details to consider, especially how state accumulation would interact with existing delivery strategies, multiple subscribers, and the listener lifecycle.

The public API could be pretty simple, but getting the internals right seems much trickier.
I think it's worth exploring a few approaches and experimenting with them before settling on a specific solution.

I'll consider different variants of how it could be implemented.