@motiadev/stream-client 0.5.2-beta.104-330172

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
+
+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
+```
+
+---
+
+## 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/__tests__/stream-group.spec.d.ts

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

package/dist/__tests__/stream-group.spec.js

@@ -0,0 +1,105 @@
+import { StreamGroupSubscription } from '../src/stream-group';
+describe('StreamGroupSubscription', () => {
+    const joinMessage = {
+        streamName: 'test-stream',
+        groupId: 'test-group',
+        subscriptionId: 'sub-1',
+    };
+    function makeMessage(type, data, timestamp = Date.now()) {
+        return {
+            streamName: 'test-stream',
+            groupId: 'test-group',
+            timestamp,
+            event: { type, ...(type === 'event' ? { event: data } : { data }) },
+        };
+    }
+    it('notifies change listeners on state change', () => {
+        const sub = new StreamGroupSubscription(joinMessage);
+        const listener = jest.fn();
+        sub.addChangeListener(listener);
+        const syncData = [
+            { id: '1', name: 'A' },
+            { id: '2', name: 'B' },
+        ];
+        sub.listener(makeMessage('sync', syncData));
+        expect(listener).toHaveBeenCalledWith(syncData);
+    });
+    it('should be able to sort by a key', () => {
+        const sub = new StreamGroupSubscription(joinMessage, 'name');
+        const listener = jest.fn();
+        sub.addChangeListener(listener);
+        const syncData = [
+            { id: '1', name: 'B' },
+            { id: '2', name: 'A' },
+        ];
+        sub.listener(makeMessage('sync', syncData));
+        expect(listener).toHaveBeenCalledWith(syncData);
+        expect(sub.getState()).toEqual([
+            { id: '2', name: 'A' },
+            { id: '1', name: 'B' },
+        ]);
+    });
+    it('should discard old events', () => {
+        const sub = new StreamGroupSubscription(joinMessage);
+        const listener = jest.fn();
+        sub.addChangeListener(listener);
+        const syncData = [
+            { id: '1', name: 'A' },
+            { id: '2', name: 'B' },
+        ];
+        sub.listener(makeMessage('sync', syncData));
+        const oldSyncData = [
+            { id: '3', name: 'C' },
+            { id: '4', name: 'D' },
+        ];
+        sub.listener(makeMessage('sync', oldSyncData, Date.now() - 1000));
+        expect(sub.getState()).toEqual(syncData);
+    });
+    it('should add items', () => {
+        const sub = new StreamGroupSubscription(joinMessage);
+        const syncData = [
+            { id: '1', name: 'A' },
+            { id: '2', name: 'B' },
+        ];
+        sub.listener(makeMessage('sync', syncData));
+        sub.listener(makeMessage('create', { id: '3', name: 'C' }));
+        expect(sub.getState()).toEqual([...syncData, { id: '3', name: 'C' }]);
+    });
+    it('should update items', () => {
+        const sub = new StreamGroupSubscription(joinMessage);
+        const syncData = [
+            { id: '1', name: 'A' },
+            { id: '2', name: 'B' },
+        ];
+        sub.listener(makeMessage('sync', syncData));
+        sub.listener(makeMessage('update', { id: '1', name: 'A1' }));
+        expect(sub.getState()).toEqual([
+            { id: '1', name: 'A1' },
+            { id: '2', name: 'B' },
+        ]);
+    });
+    it('should remove items', () => {
+        const sub = new StreamGroupSubscription(joinMessage);
+        const syncData = [
+            { id: '1', name: 'A' },
+            { id: '2', name: 'B' },
+        ];
+        sub.listener(makeMessage('sync', syncData));
+        sub.listener(makeMessage('delete', { id: '1' }));
+        expect(sub.getState()).toEqual([{ id: '2', name: 'B' }]);
+    });
+    it('should discard old on event on a particular item', () => {
+        const sub = new StreamGroupSubscription(joinMessage);
+        const syncData = [
+            { id: '1', name: 'A' },
+            { id: '2', name: 'B' },
+        ];
+        sub.listener(makeMessage('sync', syncData));
+        sub.listener(makeMessage('update', { id: '1', name: 'A1' }));
+        sub.listener(makeMessage('update', { id: '1', name: 'A2' }, Date.now() - 1000));
+        expect(sub.getState()).toEqual([
+            { id: '1', name: 'A1' },
+            { id: '2', name: 'B' },
+        ]);
+    });
+});

package/dist/__tests__/stream-item.spec.d.ts

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

package/dist/__tests__/stream-item.spec.js

@@ -0,0 +1,46 @@
+import { StreamItemSubscription } from '../src/stream-item';
+describe('StreamItemSubscription', () => {
+    const joinMessage = {
+        streamName: 'test-stream',
+        groupId: 'test-group',
+        subscriptionId: 'sub-1',
+    };
+    function makeMessage(type, data, timestamp = Date.now()) {
+        return {
+            streamName: 'test-stream',
+            groupId: 'test-group',
+            timestamp,
+            event: { type, ...(type === 'event' ? { event: data } : { data }) },
+        };
+    }
+    it('notifies change listeners on state change', () => {
+        const sub = new StreamItemSubscription(joinMessage);
+        const listener = jest.fn();
+        sub.addChangeListener(listener);
+        const syncData = { id: '1', name: 'A', value: 1 };
+        sub.listener(makeMessage('sync', syncData));
+        expect(listener).toHaveBeenCalledWith(syncData);
+    });
+    it('should discard old events', () => {
+        const sub = new StreamItemSubscription(joinMessage);
+        const syncData = { id: '1', name: 'A', value: 1 };
+        const oldSyncData = { id: '1', name: 'B', value: 3 };
+        sub.listener(makeMessage('sync', syncData));
+        sub.listener(makeMessage('sync', oldSyncData, Date.now() - 1000));
+        expect(sub.getState()).toEqual(syncData);
+    });
+    it('should update item', () => {
+        const sub = new StreamItemSubscription(joinMessage);
+        const syncData = { id: '1', name: 'A', value: 1 };
+        sub.listener(makeMessage('sync', syncData));
+        sub.listener(makeMessage('update', { id: '1', name: 'A1', value: 2 }, Date.now() + 1000));
+        expect(sub.getState()).toEqual({ id: '1', name: 'A1', value: 2 });
+    });
+    it('should remove item', () => {
+        const sub = new StreamItemSubscription(joinMessage);
+        const syncData = { id: '1', name: 'A', value: 1 };
+        sub.listener(makeMessage('sync', syncData));
+        sub.listener(makeMessage('delete', { id: '1' }, Date.now() + 1000));
+        expect(sub.getState()).toEqual(null);
+    });
+});

package/dist/__tests__/stream.spec.d.ts

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

package/dist/__tests__/stream.spec.js

@@ -0,0 +1,81 @@
+import { Stream } from '../src/stream';
+class MockSocket {
+    constructor() {
+        this.listeners = {};
+    }
+    addEventListener(event, cb) {
+        if (!this.listeners[event])
+            this.listeners[event] = [];
+        this.listeners[event].push(cb);
+    }
+    connect() { }
+    isOpen() {
+        return true;
+    }
+    onMessage(callback) {
+        this.addEventListener('message', callback);
+    }
+    onOpen(callback) {
+        this.addEventListener('open', callback);
+    }
+    onClose(callback) {
+        this.addEventListener('close', callback);
+    }
+    send(data) {
+        this.listeners['message']?.forEach((cb) => cb(data));
+    }
+    close() {
+        this.listeners = {};
+    }
+}
+function getSocket(stream) {
+    return stream.ws;
+}
+function makeGroupMessage(type, data, timestamp = Date.now()) {
+    return {
+        streamName: 'test-stream',
+        groupId: 'test-group',
+        timestamp,
+        event: { type, ...(type === 'event' ? { event: data } : { data }) },
+    };
+}
+function makeItemMessage(type, data, timestamp = Date.now()) {
+    return {
+        streamName: 'test-stream',
+        groupId: 'test-group',
+        id: '1',
+        timestamp,
+        event: { type, ...(type === 'event' ? { event: data } : { data }) },
+    };
+}
+describe('Stream', () => {
+    beforeEach(() => {
+        global.WebSocket = MockSocket;
+    });
+    afterEach(() => {
+        delete global.WebSocket;
+    });
+    it('should sync group events', () => {
+        const stream = new Stream(() => new MockSocket());
+        const socket = getSocket(stream);
+        const sub = stream.subscribeGroup('test-stream', 'test-group');
+        const syncData = [
+            { id: '1', name: 'A' },
+            { id: '2', name: 'B' },
+        ];
+        socket.send(JSON.stringify(makeGroupMessage('sync', syncData)));
+        expect(sub.getState()).toEqual(syncData);
+    });
+    it('should not sync item events in group subscriptions', () => {
+        const stream = new Stream(() => new MockSocket());
+        const socket = getSocket(stream);
+        const sub = stream.subscribeGroup('test-stream', 'test-group');
+        const syncData = [
+            { id: '1', name: 'A' },
+            { id: '2', name: 'B' },
+        ];
+        socket.send(JSON.stringify(makeGroupMessage('sync', syncData)));
+        socket.send(JSON.stringify(makeItemMessage('sync', syncData[0])));
+        expect(sub.getState()).toEqual(syncData);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { Stream } from './src/stream';
+export { StreamItemSubscription } from './src/stream-item';
+export { StreamGroupSubscription } from './src/stream-group';
+export { StreamSubscription } from './src/stream-subscription';
+export { SocketAdapter } from './src/socket-adapter';
+export { SocketAdapterFactory } from './src/adapter-factory';
+export * from './src/stream.types';

package/dist/index.js

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

package/dist/src/adapter-factory.d.ts

@@ -0,0 +1,2 @@
+import { SocketAdapter } from './socket-adapter';
+export type SocketAdapterFactory = () => SocketAdapter;

package/dist/src/adapter-factory.js

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

package/dist/src/socket-adapter.d.ts

@@ -0,0 +1,9 @@
+export interface SocketAdapter {
+    connect(): void;
+    close(): void;
+    send(message: string): void;
+    isOpen(): boolean;
+    onMessage(callback: (message: string) => void): void;
+    onOpen(callback: () => void): void;
+    onClose(callback: () => void): void;
+}

package/dist/src/socket-adapter.js

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

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

@@ -0,0 +1,13 @@
+import { StreamSubscription } from './stream-subscription';
+import { GroupEventMessage, JoinMessage } from './stream.types';
+export declare class StreamGroupSubscription<TData extends {
+    id: string;
+}> extends StreamSubscription<TData[], GroupEventMessage<TData>> {
+    private sortKey?;
+    private lastTimestamp;
+    private lastTimestampMap;
+    constructor(sub: JoinMessage, sortKey?: keyof TData | undefined);
+    private sort;
+    protected setState(state: TData[]): void;
+    listener(message: GroupEventMessage<TData>): void;
+}

package/dist/src/stream-group.js

@@ -0,0 +1,65 @@
+import { StreamSubscription } from './stream-subscription';
+export class StreamGroupSubscription extends StreamSubscription {
+    constructor(sub, sortKey) {
+        super(sub, []);
+        this.sortKey = sortKey;
+        this.lastTimestamp = 0;
+        this.lastTimestampMap = new Map();
+    }
+    sort(state) {
+        const sortKey = this.sortKey;
+        if (sortKey) {
+            return state.sort((a, b) => {
+                const aValue = a[sortKey];
+                const bValue = b[sortKey];
+                if (aValue && bValue) {
+                    return aValue.toString().localeCompare(bValue.toString());
+                }
+                return 0;
+            });
+        }
+        return state;
+    }
+    setState(state) {
+        super.setState(this.sort(state));
+    }
+    listener(message) {
+        if (message.event.type === 'sync') {
+            if (message.timestamp < this.lastTimestamp) {
+                return;
+            }
+            this.lastTimestampMap = new Map();
+            this.lastTimestamp = message.timestamp;
+            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();
+            const currentItemTimestamp = this.lastTimestampMap.get(messageDataId);
+            if (currentItemTimestamp && currentItemTimestamp >= message.timestamp) {
+                return;
+            }
+            this.lastTimestamp = message.timestamp;
+            this.lastTimestampMap.set(messageDataId, message.timestamp);
+            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.lastTimestamp = message.timestamp;
+            this.lastTimestampMap.set(messageDataId, message.timestamp);
+            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,9 @@
+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>> {
+    private lastEventTimestamp;
+    constructor(sub: JoinMessage);
+    listener(message: ItemEventMessage<TData>): void;
+}

package/dist/src/stream-item.js

@@ -0,0 +1,22 @@
+import { StreamSubscription } from './stream-subscription';
+export class StreamItemSubscription extends StreamSubscription {
+    constructor(sub) {
+        super(sub, null);
+        this.lastEventTimestamp = 0;
+    }
+    listener(message) {
+        if (message.timestamp <= this.lastEventTimestamp) {
+            return;
+        }
+        this.lastEventTimestamp = message.timestamp;
+        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,38 @@
+import { StreamGroupSubscription } from './stream-group';
+import { StreamItemSubscription } from './stream-item';
+import { SocketAdapter } from './socket-adapter';
+import { SocketAdapterFactory } from './adapter-factory';
+export declare class Stream {
+    private adapterFactory;
+    private ws;
+    private listeners;
+    constructor(adapterFactory: SocketAdapterFactory);
+    createSocket(): SocketAdapter;
+    /**
+     * 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, sortKey?: keyof TData): StreamGroupSubscription<TData>;
+    close(): void;
+    private onSocketClose;
+    private onSocketOpen;
+    messageListener(event: string): void;
+    private subscribe;
+    private join;
+    private leave;
+    private roomName;
+}

package/dist/src/stream.js

@@ -0,0 +1,98 @@
+import { v4 as uuidv4 } from 'uuid';
+import { StreamGroupSubscription } from './stream-group';
+import { StreamItemSubscription } from './stream-item';
+export class Stream {
+    constructor(adapterFactory) {
+        this.adapterFactory = adapterFactory;
+        this.listeners = {};
+        this.ws = this.createSocket();
+    }
+    createSocket() {
+        this.ws = this.adapterFactory();
+        this.ws.onMessage((message) => this.messageListener(message));
+        this.ws.onOpen(() => this.onSocketOpen());
+        this.ws.onClose(() => 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, sortKey) {
+        const subscriptionId = uuidv4();
+        const sub = { streamName, groupId, subscriptionId };
+        const subscription = new StreamGroupSubscription(sub, sortKey);
+        this.subscribe(subscription);
+        return subscription;
+    }
+    close() {
+        this.listeners = {}; // clean up all listeners
+        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);
+        const room = this.roomName(message);
+        this.listeners[room]?.forEach((listener) => listener.listener(message));
+        // we need to discard sync to group subs when it's an item event
+        if (message.id && message.event.type !== 'sync') {
+            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.isOpen()) {
+            this.ws.send(JSON.stringify({ type: 'join', data: subscription.sub }));
+        }
+    }
+    leave(subscription) {
+        if (this.ws.isOpen()) {
+            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,56 @@
+export type BaseMessage = {
+    streamName: string;
+    groupId: string;
+    id?: string;
+    timestamp: number;
+};
+export type JoinMessage = Omit<BaseMessage, 'timestamp'> & {
+    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,7 @@
+export { Stream } from './src/stream'
+export { StreamItemSubscription } from './src/stream-item'
+export { StreamGroupSubscription } from './src/stream-group'
+export { StreamSubscription } from './src/stream-subscription'
+export { SocketAdapter } from './src/socket-adapter'
+export { SocketAdapterFactory } from './src/adapter-factory'
+export * from './src/stream.types'

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@motiadev/stream-client",
+  "description": "Motia Stream Client Package – Responsible for managing streams of data.",
+  "version": "0.5.2-beta.104-330172",
+  "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.3.2",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "lint": "eslint --config ../../eslint.config.js",
+    "test": "jest"
+  }
+}