@motiadev/stream-client-browser 0.2.1-beta.49 → 0.2.1-beta.51

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/src/stream-group.d.ts

@@ -9,8 +9,20 @@ export declare class StreamGroupSubscription<TData extends {
     private listeners;
     private state;
     constructor(ws: WebSocket, sub: GroupJoinMessage);
+    /**
+     * Close the subscription.
+     */
     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[];
 }

package/dist/src/stream-group.js

@@ -41,17 +41,29 @@ export class StreamGroupSubscription extends StreamSubscription {
         this.listeners.add(listenerWrapper);
         ws.send(JSON.stringify(message));
     }
+    /**
+     * Close the subscription.
+     */
     close() {
         const message = { type: 'leave', data: this.sub };
         this.ws.send(JSON.stringify(message));
         this.listeners.forEach((listener) => this.ws.removeEventListener('message', listener));
     }
+    /**
+     * 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;
     }

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

@@ -9,8 +9,20 @@ export declare class StreamItemSubscription<TData extends {
     private listeners;
     private state;
     constructor(ws: WebSocket, sub: ItemJoinMessage);
+    /**
+     * Close the subscription.
+     */
     close(): void;
+    /**
+     * Add a change listener. This listener will be called whenever the state of the item changes.
+     */
     addChangeListener(listener: Listener<TData>): void;
+    /**
+     * Remove a change listener.
+     */
     removeChangeListener(listener: Listener<TData>): void;
+    /**
+     * Get the current state of the item.
+     */
     getState(): TData | null;
 }

package/dist/src/stream-item.js

@@ -29,17 +29,29 @@ export class StreamItemSubscription extends StreamSubscription {
         this.listeners.add(listenerWrapper);
         ws.send(JSON.stringify(message));
     }
+    /**
+     * Close the subscription.
+     */
     close() {
         const message = { type: 'leave', data: this.sub };
         this.ws.send(JSON.stringify(message));
         this.listeners.forEach((listener) => this.ws.removeEventListener('message', listener));
     }
+    /**
+     * Add a change listener. This listener will be called whenever the state of the item changes.
+     */
     addChangeListener(listener) {
         this.onChangeListeners.add(listener);
     }
+    /**
+     * Remove a change listener.
+     */
     removeChangeListener(listener) {
         this.onChangeListeners.delete(listener);
     }
+    /**
+     * Get the current state of the item.
+     */
     getState() {
         return this.state;
     }

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

@@ -3,7 +3,13 @@ type CustomEventListener = (event: any) => void;
 export declare abstract class StreamSubscription {
     private customEventListeners;
     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;
 }
 export {};

package/dist/src/stream-subscription.js

@@ -9,10 +9,16 @@ export class StreamSubscription {
             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));

package/dist/src/stream.d.ts

@@ -3,9 +3,21 @@ import { StreamItemSubscription } from './stream-item';
 export declare class Stream {
     private ws;
     constructor(address: string, onReady: () => void);
+    /**
+     * Subscribe to an item in a stream.
+     *
+     * @argument streamName - The name of the stream to subscribe to.
+     * @argument id - The id of the item to subscribe to.
+     */
     subscribeItem<TData extends {
         id: string;
     }>(streamName: 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>;

package/dist/src/stream.js

@@ -6,10 +6,22 @@ export class Stream {
         this.ws = new WebSocket(address);
         this.ws.onopen = () => onReady();
     }
+    /**
+     * Subscribe to an item in a stream.
+     *
+     * @argument streamName - The name of the stream to subscribe to.
+     * @argument id - The id of the item to subscribe to.
+     */
     subscribeItem(streamName, id) {
         const subscriptionId = uuidv4();
         return new StreamItemSubscription(this.ws, { streamName, id, subscriptionId });
     }
+    /**
+     * 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();
         return new StreamGroupSubscription(this.ws, { streamName, groupId, subscriptionId });

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@motiadev/stream-client-browser",
   "description": "Motia Stream Client Package – Responsible for managing streams of data.",
-  "version": "0.2.1-beta.49",
+  "version": "0.2.1-beta.51",
+  "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {

package/src/stream-group.ts

@@ -48,20 +48,32 @@ export class StreamGroupSubscription<TData extends { id: string }> extends Strea
     ws.send(JSON.stringify(message))
   }
 
+  /**
+   * Close the subscription.
+   */
   close() {
     const message: Message = { type: 'leave', data: this.sub }
     this.ws.send(JSON.stringify(message))
     this.listeners.forEach((listener) => this.ws.removeEventListener('message', listener))
   }
 
+  /**
+   * 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
   }

package/src/stream-item.ts

@@ -36,20 +36,32 @@ export class StreamItemSubscription<TData extends { id: string }> extends Stream
     ws.send(JSON.stringify(message))
   }
 
+  /**
+   * Close the subscription.
+   */
   close() {
     const message: Message = { type: 'leave', data: this.sub }
     this.ws.send(JSON.stringify(message))
     this.listeners.forEach((listener) => this.ws.removeEventListener('message', listener))
   }
 
+  /**
+   * Add a change listener. This listener will be called whenever the state of the item 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 item.
+   */
   getState(): TData | null {
     return this.state
   }

package/src/stream-subscription.ts

@@ -15,11 +15,17 @@ export abstract class StreamSubscription {
     }
   }
 
+  /**
+   * 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(

package/src/stream.ts

@@ -10,11 +10,23 @@ export class Stream {
     this.ws.onopen = () => onReady()
   }
 
+  /**
+   * Subscribe to an item in a stream.
+   *
+   * @argument streamName - The name of the stream to subscribe to.
+   * @argument id - The id of the item to subscribe to.
+   */
   subscribeItem<TData extends { id: string }>(streamName: string, id: string): StreamItemSubscription<TData> {
     const subscriptionId = uuidv4()
     return new StreamItemSubscription<TData>(this.ws, { streamName, id, subscriptionId })
   }
 
+  /**
+   * 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()
     return new StreamGroupSubscription<TData>(this.ws, { streamName, groupId, subscriptionId })