@motiadev/stream-client-browser 0.0.7-build.20250529212805

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Motia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,185 @@
+# @motiadev/stream-client-browser
+
+Motia Stream Client Package – Responsible for managing real-time [Motia](https://motia.dev) streams of data in browser environments. This package provides a simple, type-safe interface for subscribing to item and group streams over WebSockets, handling live updates, and managing stream state in your web applications.
+
+## Features
+
+- **WebSocket-based streaming** for real-time data updates
+- **Item and group subscriptions** with automatic state management
+- **Change listeners** for reactive UI updates
+- **Custom event handling** for extensibility
+- **TypeScript support** for strong typing and autocompletion
+
+---
+
+## Installation
+
+```bash
+npm install @motiadev/stream-client-browser
+```
+
+---
+
+## Usage
+
+### 1. Creating a Stream Connection
+
+```typescript
+import { Stream } from '@motiadev/stream-client-browser'
+
+const stream = new Stream('wss://your-stream-server', () => {
+  console.log('WebSocket connection established!')
+})
+```
+
+### 2. Subscribing to an Item Stream
+
+```typescript
+const itemSubscription = stream.subscribeItem<{ id: string; name: string }>('users', 'user-123')
+
+itemSubscription.addChangeListener((user) => {
+  console.log('User updated:', user)
+})
+
+// Listen for custom events
+itemSubscription.onEvent('custom-event', (data) => {
+  console.log('Received custom event:', data)
+})
+```
+
+### 3. Subscribing to a Group Stream
+
+```typescript
+const groupSubscription = stream.subscribeGroup<{ id: string; name: string }>('users', 'group-abc')
+
+groupSubscription.addChangeListener((users) => {
+  console.log('Group users updated:', users)
+})
+```
+
+### 4. Cleaning Up
+
+```typescript
+itemSubscription.close()
+groupSubscription.close()
+stream.close()
+```
+
+---
+
+## API Reference
+
+### `Stream`
+
+- **constructor(address: string, onReady: () => void)**
+
+  - Establishes a WebSocket connection to the given address.
+  - Calls `onReady` when the connection is open.
+
+- **subscribeItem<T>(streamName: string, id: string): StreamItemSubscription<T>**
+
+  - Subscribes to a single item in a stream.
+  - Returns a `StreamItemSubscription` instance.
+
+- **subscribeGroup<T>(streamName: string, groupId: string): StreamGroupSubscription<T>**
+
+  - Subscribes to a group of items in a stream.
+  - Returns a `StreamGroupSubscription` instance.
+
+- **close()**
+  - Closes the WebSocket connection.
+
+---
+
+### `StreamItemSubscription<T>`
+
+- **addChangeListener(listener: (item: T | null) => void)**
+
+  - Registers a callback for when the item changes.
+
+- **removeChangeListener(listener)**
+
+  - Unregisters a change listener.
+
+- **onEvent(type: string, listener: (event: any) => void)**
+
+  - Registers a custom event listener.
+
+- **offEvent(type: string, listener)**
+
+  - Unregisters a custom event listener.
+
+- **getState(): T | null**
+
+  - Returns the current state of the item.
+
+- **close()**
+  - Unsubscribes from the item stream and cleans up listeners.
+
+---
+
+### `StreamGroupSubscription<T>`
+
+- **addChangeListener(listener: (items: T[]) => void)**
+
+  - Registers a callback for when the group changes.
+
+- **removeChangeListener(listener)**
+
+  - Unregisters a change listener.
+
+- **onEvent(type: string, listener: (event: any) => void)**
+
+  - Registers a custom event listener.
+
+- **offEvent(type: string, listener: (event: any) => void)**
+
+  - Unregisters a custom event listener.
+
+- **getState(): T[]**
+
+  - Returns the current state of the group.
+
+- **close()**
+  - Unsubscribes from the group stream and cleans up listeners.
+
+---
+
+### `StreamSubscription` (Base Class)
+
+- **onEvent(type: string, listener: (event: any) => void)**
+- **offEvent(type: string, listener: (event: any) => void)**
+
+---
+
+## Types
+
+All types are exported from `stream.types.ts` for advanced usage and type safety.
+
+---
+
+## Example
+
+```typescript
+import { Stream } from '@motiadev/stream-client-browser'
+
+const stream = new Stream('wss://example.com', () => {
+  const userSub = stream.subscribeItem<{ id: string; name: string }>('users', 'user-1')
+
+  userSub.addChangeListener((user) => {
+    // React to user changes
+  })
+
+  const groupSub = stream.subscribeGroup<{ id: string; name: string }>('users', 'group-1')
+
+  groupSub.addChangeListener((users) => {
+    // React to group changes
+  })
+})
+```
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Stream } from './src/stream';
+export { StreamItemSubscription } from './src/stream-item';
+export { StreamGroupSubscription } from './src/stream-group';
+export { StreamSubscription } from './src/stream-subscription';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Stream } from './src/stream';
+export { StreamItemSubscription } from './src/stream-item';
+export { StreamGroupSubscription } from './src/stream-group';
+export { StreamSubscription } from './src/stream-subscription';

package/dist/src/stream-group.d.ts

@@ -0,0 +1,8 @@
+import { StreamSubscription } from './stream-subscription';
+import { GroupEventMessage, JoinMessage } from './stream.types';
+export declare class StreamGroupSubscription<TData extends {
+    id: string;
+}> extends StreamSubscription<TData[], GroupEventMessage<TData>> {
+    constructor(sub: JoinMessage);
+    listener(message: GroupEventMessage<TData>): void;
+}

package/dist/src/stream-group.js

@@ -0,0 +1,32 @@
+import { StreamSubscription } from './stream-subscription';
+export class StreamGroupSubscription extends StreamSubscription {
+    constructor(sub) {
+        super(sub, []);
+    }
+    listener(message) {
+        if (message.event.type === 'sync') {
+            this.setState(message.event.data);
+        }
+        else if (message.event.type === 'create') {
+            const id = message.event.data.id;
+            const state = this.getState();
+            if (!state.find((item) => item.id === id)) {
+                this.setState([...state, message.event.data]);
+            }
+        }
+        else if (message.event.type === 'update') {
+            const messageData = message.event.data;
+            const messageDataId = messageData.id;
+            const state = this.getState();
+            this.setState(state.map((item) => (item.id === messageDataId ? messageData : item)));
+        }
+        else if (message.event.type === 'delete') {
+            const messageDataId = message.event.data.id;
+            const state = this.getState();
+            this.setState(state.filter((item) => item.id !== messageDataId));
+        }
+        else if (message.event.type === 'event') {
+            this.onEventReceived(message.event.event);
+        }
+    }
+}

package/dist/src/stream-item.d.ts

@@ -0,0 +1,8 @@
+import { StreamSubscription } from './stream-subscription';
+import { ItemEventMessage, JoinMessage } from './stream.types';
+export declare class StreamItemSubscription<TData extends {
+    id: string;
+}> extends StreamSubscription<TData | null, ItemEventMessage<TData>> {
+    constructor(sub: JoinMessage);
+    listener(message: ItemEventMessage<TData>): void;
+}

package/dist/src/stream-item.js

@@ -0,0 +1,17 @@
+import { StreamSubscription } from './stream-subscription';
+export class StreamItemSubscription extends StreamSubscription {
+    constructor(sub) {
+        super(sub, null);
+    }
+    listener(message) {
+        if (message.event.type === 'sync' || message.event.type === 'create' || message.event.type === 'update') {
+            this.setState(message.event.data);
+        }
+        else if (message.event.type === 'delete') {
+            this.setState(null);
+        }
+        else if (message.event.type === 'event') {
+            this.onEventReceived(message.event.event);
+        }
+    }
+}

package/dist/src/stream-subscription.d.ts

@@ -0,0 +1,36 @@
+import { CustomEvent, JoinMessage, Listener } from './stream.types';
+type CustomEventListener = (event: any) => void;
+export declare abstract class StreamSubscription<TData = unknown, TEventData = unknown> {
+    private customEventListeners;
+    private closeListeners;
+    private onChangeListeners;
+    private state;
+    readonly sub: JoinMessage;
+    constructor(sub: JoinMessage, state: TData);
+    abstract listener(message: TEventData): void;
+    protected onEventReceived(event: CustomEvent): void;
+    /**
+     * Add a custom event listener. This listener will be called whenever the custom event is received.
+     */
+    onEvent(type: string, listener: CustomEventListener): void;
+    /**
+     * Remove a custom event listener.
+     */
+    offEvent(type: string, listener: CustomEventListener): void;
+    onClose(listener: () => void): void;
+    close(): void;
+    /**
+     * Add a change listener. This listener will be called whenever the state of the group changes.
+     */
+    addChangeListener(listener: Listener<TData>): void;
+    /**
+     * Remove a change listener.
+     */
+    removeChangeListener(listener: Listener<TData>): void;
+    /**
+     * Get the current state of the group.
+     */
+    getState(): TData;
+    protected setState(state: TData): void;
+}
+export {};

package/dist/src/stream-subscription.js

@@ -0,0 +1,59 @@
+export class StreamSubscription {
+    constructor(sub, state) {
+        this.customEventListeners = new Map();
+        this.closeListeners = new Set();
+        this.onChangeListeners = new Set();
+        this.sub = sub;
+        this.state = state;
+    }
+    onEventReceived(event) {
+        const customEventListeners = this.customEventListeners.get(event.type);
+        if (customEventListeners) {
+            const eventData = event.data;
+            customEventListeners.forEach((listener) => listener(eventData));
+        }
+    }
+    /**
+     * Add a custom event listener. This listener will be called whenever the custom event is received.
+     */
+    onEvent(type, listener) {
+        const listeners = this.customEventListeners.get(type) || [];
+        this.customEventListeners.set(type, [...listeners, listener]);
+    }
+    /**
+     * Remove a custom event listener.
+     */
+    offEvent(type, listener) {
+        const listeners = this.customEventListeners.get(type) || [];
+        this.customEventListeners.set(type, listeners.filter((l) => l !== listener));
+    }
+    onClose(listener) {
+        this.closeListeners.add(listener);
+    }
+    close() {
+        this.closeListeners.forEach((listener) => listener());
+        this.closeListeners.clear();
+    }
+    /**
+     * Add a change listener. This listener will be called whenever the state of the group changes.
+     */
+    addChangeListener(listener) {
+        this.onChangeListeners.add(listener);
+    }
+    /**
+     * Remove a change listener.
+     */
+    removeChangeListener(listener) {
+        this.onChangeListeners.delete(listener);
+    }
+    /**
+     * Get the current state of the group.
+     */
+    getState() {
+        return this.state;
+    }
+    setState(state) {
+        this.state = state;
+        this.onChangeListeners.forEach((listener) => listener(state));
+    }
+}

package/dist/src/stream.d.ts

@@ -0,0 +1,36 @@
+import { StreamGroupSubscription } from './stream-group';
+import { StreamItemSubscription } from './stream-item';
+export declare class Stream {
+    private address;
+    private ws;
+    private listeners;
+    constructor(address: string);
+    createSocket(): WebSocket;
+    /**
+     * Subscribe to an item in a stream.
+     *
+     * @argument streamName - The name of the stream to subscribe to.
+     * @argument groupId - The id of the group to subscribe to.
+     * @argument id - The id of the item to subscribe to.
+     */
+    subscribeItem<TData extends {
+        id: string;
+    }>(streamName: string, groupId: string, id: string): StreamItemSubscription<TData>;
+    /**
+     * Subscribe to a group in a stream.
+     *
+     * @argument streamName - The name of the stream to subscribe to.
+     * @argument groupId - The id of the group to subscribe to.
+     */
+    subscribeGroup<TData extends {
+        id: string;
+    }>(streamName: string, groupId: string): StreamGroupSubscription<TData>;
+    close(): void;
+    private onSocketClose;
+    private onSocketOpen;
+    messageListener(event: MessageEvent<string>): void;
+    private subscribe;
+    private join;
+    private leave;
+    private roomName;
+}

package/dist/src/stream.js

@@ -0,0 +1,100 @@
+import { v4 as uuidv4 } from 'uuid';
+import { StreamGroupSubscription } from './stream-group';
+import { StreamItemSubscription } from './stream-item';
+export class Stream {
+    constructor(address) {
+        this.address = address;
+        this.listeners = {};
+        this.ws = this.createSocket();
+    }
+    createSocket() {
+        this.ws = new WebSocket(this.address);
+        this.ws.addEventListener('message', (message) => this.messageListener(message));
+        this.ws.addEventListener('open', () => this.onSocketOpen());
+        this.ws.addEventListener('close', () => this.onSocketClose());
+        return this.ws;
+    }
+    /**
+     * Subscribe to an item in a stream.
+     *
+     * @argument streamName - The name of the stream to subscribe to.
+     * @argument groupId - The id of the group to subscribe to.
+     * @argument id - The id of the item to subscribe to.
+     */
+    subscribeItem(streamName, groupId, id) {
+        const subscriptionId = uuidv4();
+        const sub = { streamName, groupId, id, subscriptionId };
+        const subscription = new StreamItemSubscription(sub);
+        this.subscribe(subscription);
+        return subscription;
+    }
+    /**
+     * Subscribe to a group in a stream.
+     *
+     * @argument streamName - The name of the stream to subscribe to.
+     * @argument groupId - The id of the group to subscribe to.
+     */
+    subscribeGroup(streamName, groupId) {
+        const subscriptionId = uuidv4();
+        const sub = { streamName, groupId, subscriptionId };
+        const subscription = new StreamGroupSubscription(sub);
+        this.subscribe(subscription);
+        return subscription;
+    }
+    close() {
+        this.listeners = {}; // clean up all listeners
+        this.ws.removeEventListener('message', this.messageListener);
+        this.ws.removeEventListener('open', this.onSocketOpen);
+        this.ws.removeEventListener('close', this.onSocketClose);
+        this.ws.close();
+    }
+    onSocketClose() {
+        // retry to connect
+        setTimeout(() => this.createSocket(), 2000);
+    }
+    onSocketOpen() {
+        Object.values(this.listeners).forEach((listeners) => {
+            listeners.forEach((subscription) => this.join(subscription));
+        });
+    }
+    messageListener(event) {
+        const message = JSON.parse(event.data);
+        const room = this.roomName(message);
+        this.listeners[room]?.forEach((listener) => listener.listener(message));
+        if (message.id) {
+            const groupRoom = this.roomName({
+                streamName: message.streamName,
+                groupId: message.groupId,
+            });
+            this.listeners[groupRoom]?.forEach((listener) => listener.listener(message));
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    subscribe(subscription) {
+        const room = this.roomName(subscription.sub);
+        if (!this.listeners[room]) {
+            this.listeners[room] = new Set();
+        }
+        this.listeners[room].add(subscription);
+        this.join(subscription);
+        subscription.onClose(() => {
+            this.listeners[room].delete(subscription);
+            this.leave(subscription);
+        });
+    }
+    join(subscription) {
+        if (this.ws.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify({ type: 'join', data: subscription.sub }));
+        }
+    }
+    leave(subscription) {
+        if (this.ws.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify({ type: 'leave', data: subscription.sub }));
+        }
+    }
+    roomName(message) {
+        return message.id
+            ? `${message.streamName}:group:${message.groupId}:item:${message.id}`
+            : `${message.streamName}:group:${message.groupId}`;
+    }
+}

package/dist/src/stream.types.d.ts

@@ -0,0 +1,55 @@
+export type BaseMessage = {
+    streamName: string;
+    groupId: string;
+    id?: string;
+};
+export type JoinMessage = BaseMessage & {
+    subscriptionId: string;
+};
+export type CustomEvent = {
+    type: string;
+    data: any;
+};
+export type StreamEvent<TData extends {
+    id: string;
+}> = {
+    type: 'create';
+    data: TData;
+} | {
+    type: 'update';
+    data: TData;
+} | {
+    type: 'delete';
+    data: TData;
+} | {
+    type: 'event';
+    event: CustomEvent;
+};
+export type ItemStreamEvent<TData extends {
+    id: string;
+}> = StreamEvent<TData> | {
+    type: 'sync';
+    data: TData;
+};
+export type GroupStreamEvent<TData extends {
+    id: string;
+}> = StreamEvent<TData> | {
+    type: 'sync';
+    data: TData[];
+};
+export type ItemEventMessage<TData extends {
+    id: string;
+}> = BaseMessage & {
+    event: ItemStreamEvent<TData>;
+};
+export type GroupEventMessage<TData extends {
+    id: string;
+}> = BaseMessage & {
+    event: GroupStreamEvent<TData>;
+};
+export type Message = {
+    type: 'join' | 'leave';
+    data: JoinMessage;
+};
+export type Listener<TData> = (state: TData | null) => void;
+export type CustomEventListener<TData> = (event: TData) => void;

package/dist/src/stream.types.js

@@ -0,0 +1 @@
+export {};

package/index.ts

@@ -0,0 +1,4 @@
+export { Stream } from './src/stream'
+export { StreamItemSubscription } from './src/stream-item'
+export { StreamGroupSubscription } from './src/stream-group'
+export { StreamSubscription } from './src/stream-subscription'

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@motiadev/stream-client-browser",
+  "description": "Motia Stream Client Package – Responsible for managing streams of data.",
+  "version": "0.0.7-build.20250529212805",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/ws": "^8.18.1",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "lint": "eslint --config ../../eslint.config.js"
+  }
+}

package/src/stream-group.ts

@@ -0,0 +1,37 @@
+import { StreamSubscription } from './stream-subscription'
+import { GroupEventMessage, JoinMessage } from './stream.types'
+
+export class StreamGroupSubscription<TData extends { id: string }> extends StreamSubscription<
+  TData[],
+  GroupEventMessage<TData>
+> {
+  constructor(sub: JoinMessage) {
+    super(sub, [])
+  }
+
+  listener(message: GroupEventMessage<TData>): void {
+    if (message.event.type === 'sync') {
+      this.setState(message.event.data)
+    } else if (message.event.type === 'create') {
+      const id = message.event.data.id
+      const state = this.getState()
+
+      if (!state.find((item) => item.id === id)) {
+        this.setState([...state, message.event.data])
+      }
+    } else if (message.event.type === 'update') {
+      const messageData = message.event.data
+      const messageDataId = messageData.id
+      const state = this.getState()
+
+      this.setState(state.map((item) => (item.id === messageDataId ? messageData : item)))
+    } else if (message.event.type === 'delete') {
+      const messageDataId = message.event.data.id
+      const state = this.getState()
+
+      this.setState(state.filter((item) => item.id !== messageDataId))
+    } else if (message.event.type === 'event') {
+      this.onEventReceived(message.event.event)
+    }
+  }
+}

package/src/stream-item.ts

@@ -0,0 +1,21 @@
+import { StreamSubscription } from './stream-subscription'
+import { ItemEventMessage, JoinMessage } from './stream.types'
+
+export class StreamItemSubscription<TData extends { id: string }> extends StreamSubscription<
+  TData | null,
+  ItemEventMessage<TData>
+> {
+  constructor(sub: JoinMessage) {
+    super(sub, null)
+  }
+
+  listener(message: ItemEventMessage<TData>): void {
+    if (message.event.type === 'sync' || message.event.type === 'create' || message.event.type === 'update') {
+      this.setState(message.event.data)
+    } else if (message.event.type === 'delete') {
+      this.setState(null)
+    } else if (message.event.type === 'event') {
+      this.onEventReceived(message.event.event)
+    }
+  }
+}

package/src/stream-subscription.ts

@@ -0,0 +1,84 @@
+import { CustomEvent, JoinMessage, Listener } from './stream.types'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type CustomEventListener = (event: any) => void
+
+export abstract class StreamSubscription<TData = unknown, TEventData = unknown> {
+  private customEventListeners: Map<string, CustomEventListener[]> = new Map()
+  private closeListeners: Set<() => void> = new Set()
+
+  private onChangeListeners: Set<Listener<TData>> = new Set()
+  private state: TData
+
+  readonly sub: JoinMessage
+
+  constructor(sub: JoinMessage, state: TData) {
+    this.sub = sub
+    this.state = state
+  }
+
+  abstract listener(message: TEventData): void
+
+  protected onEventReceived(event: CustomEvent) {
+    const customEventListeners = this.customEventListeners.get(event.type)
+
+    if (customEventListeners) {
+      const eventData = event.data
+      customEventListeners.forEach((listener) => listener(eventData))
+    }
+  }
+
+  /**
+   * Add a custom event listener. This listener will be called whenever the custom event is received.
+   */
+  onEvent(type: string, listener: CustomEventListener) {
+    const listeners = this.customEventListeners.get(type) || []
+    this.customEventListeners.set(type, [...listeners, listener])
+  }
+
+  /**
+   * Remove a custom event listener.
+   */
+  offEvent(type: string, listener: CustomEventListener) {
+    const listeners = this.customEventListeners.get(type) || []
+    this.customEventListeners.set(
+      type,
+      listeners.filter((l) => l !== listener),
+    )
+  }
+
+  onClose(listener: () => void) {
+    this.closeListeners.add(listener)
+  }
+
+  close() {
+    this.closeListeners.forEach((listener) => listener())
+    this.closeListeners.clear()
+  }
+
+  /**
+   * Add a change listener. This listener will be called whenever the state of the group changes.
+   */
+  addChangeListener(listener: Listener<TData>) {
+    this.onChangeListeners.add(listener)
+  }
+
+  /**
+   * Remove a change listener.
+   */
+  removeChangeListener(listener: Listener<TData>) {
+    this.onChangeListeners.delete(listener)
+  }
+
+  /**
+   * Get the current state of the group.
+   */
+  getState(): TData {
+    return this.state
+  }
+
+  protected setState(state: TData) {
+    this.state = state
+    this.onChangeListeners.forEach((listener) => listener(state))
+  }
+}

package/src/stream.ts

@@ -0,0 +1,130 @@
+import { v4 as uuidv4 } from 'uuid'
+import { StreamGroupSubscription } from './stream-group'
+import { StreamItemSubscription } from './stream-item'
+import { StreamSubscription } from './stream-subscription'
+import { BaseMessage } from './stream.types'
+
+export class Stream {
+  private ws: WebSocket
+  private listeners: { [channelId: string]: Set<StreamSubscription> } = {}
+
+  constructor(private address: string) {
+    this.ws = this.createSocket()
+  }
+
+  createSocket(): WebSocket {
+    this.ws = new WebSocket(this.address)
+    this.ws.addEventListener('message', (message) => this.messageListener(message))
+    this.ws.addEventListener('open', () => this.onSocketOpen())
+    this.ws.addEventListener('close', () => this.onSocketClose())
+
+    return this.ws
+  }
+
+  /**
+   * Subscribe to an item in a stream.
+   *
+   * @argument streamName - The name of the stream to subscribe to.
+   * @argument groupId - The id of the group to subscribe to.
+   * @argument id - The id of the item to subscribe to.
+   */
+  subscribeItem<TData extends { id: string }>(
+    streamName: string,
+    groupId: string,
+    id: string,
+  ): StreamItemSubscription<TData> {
+    const subscriptionId = uuidv4()
+    const sub = { streamName, groupId, id, subscriptionId }
+    const subscription = new StreamItemSubscription<TData>(sub)
+
+    this.subscribe(subscription)
+
+    return subscription
+  }
+
+  /**
+   * Subscribe to a group in a stream.
+   *
+   * @argument streamName - The name of the stream to subscribe to.
+   * @argument groupId - The id of the group to subscribe to.
+   */
+  subscribeGroup<TData extends { id: string }>(streamName: string, groupId: string): StreamGroupSubscription<TData> {
+    const subscriptionId = uuidv4()
+    const sub = { streamName, groupId, subscriptionId }
+    const subscription = new StreamGroupSubscription<TData>(sub)
+
+    this.subscribe(subscription)
+
+    return subscription
+  }
+
+  close() {
+    this.listeners = {} // clean up all listeners
+    this.ws.removeEventListener('message', this.messageListener)
+    this.ws.removeEventListener('open', this.onSocketOpen)
+    this.ws.removeEventListener('close', this.onSocketClose)
+    this.ws.close()
+  }
+
+  private onSocketClose(): void {
+    // retry to connect
+    setTimeout(() => this.createSocket(), 2000)
+  }
+
+  private onSocketOpen(): void {
+    Object.values(this.listeners).forEach((listeners) => {
+      listeners.forEach((subscription) => this.join(subscription))
+    })
+  }
+
+  messageListener(event: MessageEvent<string>): void {
+    const message: BaseMessage = JSON.parse(event.data)
+    const room = this.roomName(message)
+
+    this.listeners[room]?.forEach((listener) => listener.listener(message))
+
+    if (message.id) {
+      const groupRoom = this.roomName({
+        streamName: message.streamName,
+        groupId: message.groupId,
+      })
+
+      this.listeners[groupRoom]?.forEach((listener) => listener.listener(message))
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private subscribe(subscription: StreamSubscription<any, any>): void {
+    const room = this.roomName(subscription.sub)
+
+    if (!this.listeners[room]) {
+      this.listeners[room] = new Set()
+    }
+
+    this.listeners[room].add(subscription)
+    this.join(subscription)
+
+    subscription.onClose(() => {
+      this.listeners[room].delete(subscription)
+      this.leave(subscription)
+    })
+  }
+
+  private join(subscription: StreamSubscription): void {
+    if (this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({ type: 'join', data: subscription.sub }))
+    }
+  }
+
+  private leave(subscription: StreamSubscription): void {
+    if (this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({ type: 'leave', data: subscription.sub }))
+    }
+  }
+
+  private roomName(message: BaseMessage): string {
+    return message.id
+      ? `${message.streamName}:group:${message.groupId}:item:${message.id}`
+      : `${message.streamName}:group:${message.groupId}`
+  }
+}

package/src/stream.types.ts

@@ -0,0 +1,18 @@
+export type BaseMessage = { streamName: string; groupId: string; id?: string }
+export type JoinMessage = BaseMessage & { subscriptionId: string }
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type CustomEvent = { type: string; data: any }
+export type StreamEvent<TData extends { id: string }> =
+  | { type: 'create'; data: TData }
+  | { type: 'update'; data: TData }
+  | { type: 'delete'; data: TData }
+  | { type: 'event'; event: CustomEvent }
+export type ItemStreamEvent<TData extends { id: string }> = StreamEvent<TData> | { type: 'sync'; data: TData }
+export type GroupStreamEvent<TData extends { id: string }> = StreamEvent<TData> | { type: 'sync'; data: TData[] }
+export type ItemEventMessage<TData extends { id: string }> = BaseMessage & { event: ItemStreamEvent<TData> }
+export type GroupEventMessage<TData extends { id: string }> = BaseMessage & { event: GroupStreamEvent<TData> }
+
+export type Message = { type: 'join' | 'leave'; data: JoinMessage }
+
+export type Listener<TData> = (state: TData | null) => void
+export type CustomEventListener<TData> = (event: TData) => void

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "baseUrl": ".",
+    "declaration": true,
+    "lib": ["dom"]
+  },
+  "include": ["src/*.ts", "index.ts"],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}