@motiadev/stream-client-browser 0.2.1-beta.47

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/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,16 @@
+import { StreamSubscription } from './stream-subscription';
+import { GroupJoinMessage, Listener } from './stream.types';
+export declare class StreamGroupSubscription<TData extends {
+    id: string;
+}> extends StreamSubscription {
+    private readonly ws;
+    private readonly sub;
+    private onChangeListeners;
+    private listeners;
+    private state;
+    constructor(ws: WebSocket, sub: GroupJoinMessage);
+    close(): void;
+    addChangeListener(listener: Listener<TData[]>): void;
+    removeChangeListener(listener: Listener<TData[]>): void;
+    getState(): TData[];
+}

package/dist/src/stream-group.js

@@ -0,0 +1,58 @@
+import { StreamSubscription } from './stream-subscription';
+export class StreamGroupSubscription extends StreamSubscription {
+    constructor(ws, sub) {
+        super();
+        this.ws = ws;
+        this.sub = sub;
+        this.onChangeListeners = new Set();
+        this.listeners = new Set();
+        this.state = [];
+        const message = { type: 'join', data: sub };
+        const listenerWrapper = (event) => {
+            const message = JSON.parse(event.data);
+            const isStreamName = message.streamName === this.sub.streamName;
+            const isGroupId = 'groupId' in message && message.groupId === this.sub.groupId;
+            if (isStreamName && isGroupId) {
+                if (message.event.type === 'sync') {
+                    this.state = message.event.data;
+                }
+                else if (message.event.type === 'create') {
+                    const id = message.event.data.id;
+                    if (!this.state.find((item) => item.id === id)) {
+                        this.state = [...this.state, message.event.data];
+                    }
+                }
+                else if (message.event.type === 'update') {
+                    const messageData = message.event.data;
+                    const messageDataId = messageData.id;
+                    this.state = this.state.map((item) => (item.id === messageDataId ? messageData : item));
+                }
+                else if (message.event.type === 'delete') {
+                    const messageDataId = message.event.data.id;
+                    this.state = this.state.filter((item) => item.id !== messageDataId);
+                }
+                else if (message.event.type === 'event') {
+                    this.onEventReceived(message.event.event);
+                }
+                this.onChangeListeners.forEach((listener) => listener(this.state));
+            }
+        };
+        this.ws.addEventListener('message', listenerWrapper);
+        this.listeners.add(listenerWrapper);
+        ws.send(JSON.stringify(message));
+    }
+    close() {
+        const message = { type: 'leave', data: this.sub };
+        this.ws.send(JSON.stringify(message));
+        this.listeners.forEach((listener) => this.ws.removeEventListener('message', listener));
+    }
+    addChangeListener(listener) {
+        this.onChangeListeners.add(listener);
+    }
+    removeChangeListener(listener) {
+        this.onChangeListeners.delete(listener);
+    }
+    getState() {
+        return this.state;
+    }
+}

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

@@ -0,0 +1,16 @@
+import { StreamSubscription } from './stream-subscription';
+import { ItemJoinMessage, Listener } from './stream.types';
+export declare class StreamItemSubscription<TData extends {
+    id: string;
+}> extends StreamSubscription {
+    private readonly ws;
+    private readonly sub;
+    private onChangeListeners;
+    private listeners;
+    private state;
+    constructor(ws: WebSocket, sub: ItemJoinMessage);
+    close(): void;
+    addChangeListener(listener: Listener<TData>): void;
+    removeChangeListener(listener: Listener<TData>): void;
+    getState(): TData | null;
+}

package/dist/src/stream-item.js

@@ -0,0 +1,46 @@
+import { StreamSubscription } from './stream-subscription';
+export class StreamItemSubscription extends StreamSubscription {
+    constructor(ws, sub) {
+        super();
+        this.ws = ws;
+        this.sub = sub;
+        this.onChangeListeners = new Set();
+        this.listeners = new Set();
+        this.state = null;
+        const message = { type: 'join', data: sub };
+        const listenerWrapper = (event) => {
+            const message = JSON.parse(event.data);
+            const isStreamName = message.streamName === this.sub.streamName;
+            const isId = 'id' in message && message.id === this.sub.id;
+            if (isStreamName && isId) {
+                if (message.event.type === 'sync' || message.event.type === 'create' || message.event.type === 'update') {
+                    this.state = message.event.data;
+                }
+                else if (message.event.type === 'delete') {
+                    this.state = null;
+                }
+                else if (message.event.type === 'event') {
+                    this.onEventReceived(message.event.event);
+                }
+                this.onChangeListeners.forEach((listener) => listener(this.state));
+            }
+        };
+        this.ws.addEventListener('message', listenerWrapper);
+        this.listeners.add(listenerWrapper);
+        ws.send(JSON.stringify(message));
+    }
+    close() {
+        const message = { type: 'leave', data: this.sub };
+        this.ws.send(JSON.stringify(message));
+        this.listeners.forEach((listener) => this.ws.removeEventListener('message', listener));
+    }
+    addChangeListener(listener) {
+        this.onChangeListeners.add(listener);
+    }
+    removeChangeListener(listener) {
+        this.onChangeListeners.delete(listener);
+    }
+    getState() {
+        return this.state;
+    }
+}

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

@@ -0,0 +1,9 @@
+import { CustomEvent } from './stream.types';
+type CustomEventListener = (event: any) => void;
+export declare abstract class StreamSubscription {
+    private customEventListeners;
+    protected onEventReceived(event: CustomEvent): void;
+    onEvent(type: string, listener: CustomEventListener): void;
+    offEvent(type: string, listener: CustomEventListener): void;
+}
+export {};

package/dist/src/stream-subscription.js

@@ -0,0 +1,20 @@
+export class StreamSubscription {
+    constructor() {
+        this.customEventListeners = new Map();
+    }
+    onEventReceived(event) {
+        const customEventListeners = this.customEventListeners.get(event.type);
+        if (customEventListeners) {
+            const eventData = event.data;
+            customEventListeners.forEach((listener) => listener(eventData));
+        }
+    }
+    onEvent(type, listener) {
+        const listeners = this.customEventListeners.get(type) || [];
+        this.customEventListeners.set(type, [...listeners, 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

@@ -0,0 +1,13 @@
+import { StreamGroupSubscription } from './stream-group';
+import { StreamItemSubscription } from './stream-item';
+export declare class Stream {
+    private ws;
+    constructor(address: string, onReady: () => void);
+    subscribeItem<TData extends {
+        id: string;
+    }>(streamName: string, id: string): StreamItemSubscription<TData>;
+    subscribeGroup<TData extends {
+        id: string;
+    }>(streamName: string, groupId: string): StreamGroupSubscription<TData>;
+    close(): void;
+}

package/dist/src/stream.js

@@ -0,0 +1,20 @@
+import { v4 as uuidv4 } from 'uuid';
+import { StreamGroupSubscription } from './stream-group';
+import { StreamItemSubscription } from './stream-item';
+export class Stream {
+    constructor(address, onReady) {
+        this.ws = new WebSocket(address);
+        this.ws.onopen = () => onReady();
+    }
+    subscribeItem(streamName, id) {
+        const subscriptionId = uuidv4();
+        return new StreamItemSubscription(this.ws, { streamName, id, subscriptionId });
+    }
+    subscribeGroup(streamName, groupId) {
+        const subscriptionId = uuidv4();
+        return new StreamGroupSubscription(this.ws, { streamName, groupId, subscriptionId });
+    }
+    close() {
+        this.ws.close();
+    }
+}

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

@@ -0,0 +1,65 @@
+export type BaseMessage = {
+    streamName: string;
+} & ({
+    id: string;
+} | {
+    groupId: string;
+});
+export type JoinMessage = BaseMessage & {
+    subscriptionId: string;
+};
+export type ItemJoinMessage = BaseMessage & {
+    id: string;
+    subscriptionId: string;
+};
+export type GroupJoinMessage = BaseMessage & {
+    groupId: string;
+    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,21 @@
+{
+  "name": "@motiadev/stream-client-browser",
+  "description": "Motia Stream Client Package – Responsible for managing streams of data.",
+  "version": "0.2.1-beta.47",
+  "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,68 @@
+import { StreamSubscription } from './stream-subscription'
+import { GroupEventMessage, GroupJoinMessage, Listener, Message } from './stream.types'
+
+export class StreamGroupSubscription<TData extends { id: string }> extends StreamSubscription {
+  private onChangeListeners: Set<Listener<TData[]>> = new Set()
+  private listeners: Set<EventListener> = new Set()
+
+  private state: TData[] = []
+
+  constructor(
+    private readonly ws: WebSocket,
+    private readonly sub: GroupJoinMessage,
+  ) {
+    super()
+
+    const message: Message = { type: 'join', data: sub }
+    const listenerWrapper = (event: MessageEvent<string>) => {
+      const message: GroupEventMessage<TData> = JSON.parse(event.data)
+      const isStreamName = message.streamName === this.sub.streamName
+      const isGroupId = 'groupId' in message && message.groupId === this.sub.groupId
+
+      if (isStreamName && isGroupId) {
+        if (message.event.type === 'sync') {
+          this.state = message.event.data
+        } else if (message.event.type === 'create') {
+          const id = message.event.data.id
+
+          if (!this.state.find((item) => item.id === id)) {
+            this.state = [...this.state, message.event.data]
+          }
+        } else if (message.event.type === 'update') {
+          const messageData = message.event.data
+          const messageDataId = messageData.id
+          this.state = this.state.map((item) => (item.id === messageDataId ? messageData : item))
+        } else if (message.event.type === 'delete') {
+          const messageDataId = message.event.data.id
+          this.state = this.state.filter((item) => item.id !== messageDataId)
+        } else if (message.event.type === 'event') {
+          this.onEventReceived(message.event.event)
+        }
+
+        this.onChangeListeners.forEach((listener) => listener(this.state))
+      }
+    }
+    this.ws.addEventListener('message', listenerWrapper as EventListener)
+    this.listeners.add(listenerWrapper as EventListener)
+
+    ws.send(JSON.stringify(message))
+  }
+
+  close() {
+    const message: Message = { type: 'leave', data: this.sub }
+    this.ws.send(JSON.stringify(message))
+    this.listeners.forEach((listener) => this.ws.removeEventListener('message', listener))
+  }
+
+  addChangeListener(listener: Listener<TData[]>) {
+    this.onChangeListeners.add(listener)
+  }
+
+  removeChangeListener(listener: Listener<TData[]>) {
+    this.onChangeListeners.delete(listener)
+  }
+
+  getState(): TData[] {
+    return this.state
+  }
+}

package/src/stream-item.ts

@@ -0,0 +1,56 @@
+import { StreamSubscription } from './stream-subscription'
+import { ItemEventMessage, ItemJoinMessage, Listener, Message } from './stream.types'
+
+export class StreamItemSubscription<TData extends { id: string }> extends StreamSubscription {
+  private onChangeListeners: Set<Listener<TData>> = new Set()
+  private listeners: Set<EventListener> = new Set()
+  private state: TData | null = null
+
+  constructor(
+    private readonly ws: WebSocket,
+    private readonly sub: ItemJoinMessage,
+  ) {
+    super()
+
+    const message: Message = { type: 'join', data: sub }
+    const listenerWrapper = (event: MessageEvent<string>) => {
+      const message: ItemEventMessage<TData> = JSON.parse(event.data)
+      const isStreamName = message.streamName === this.sub.streamName
+      const isId = 'id' in message && message.id === this.sub.id
+
+      if (isStreamName && isId) {
+        if (message.event.type === 'sync' || message.event.type === 'create' || message.event.type === 'update') {
+          this.state = message.event.data
+        } else if (message.event.type === 'delete') {
+          this.state = null
+        } else if (message.event.type === 'event') {
+          this.onEventReceived(message.event.event)
+        }
+
+        this.onChangeListeners.forEach((listener) => listener(this.state))
+      }
+    }
+    this.ws.addEventListener('message', listenerWrapper as EventListener)
+    this.listeners.add(listenerWrapper as EventListener)
+
+    ws.send(JSON.stringify(message))
+  }
+
+  close() {
+    const message: Message = { type: 'leave', data: this.sub }
+    this.ws.send(JSON.stringify(message))
+    this.listeners.forEach((listener) => this.ws.removeEventListener('message', listener))
+  }
+
+  addChangeListener(listener: Listener<TData>) {
+    this.onChangeListeners.add(listener)
+  }
+
+  removeChangeListener(listener: Listener<TData>) {
+    this.onChangeListeners.delete(listener)
+  }
+
+  getState(): TData | null {
+    return this.state
+  }
+}

package/src/stream-subscription.ts

@@ -0,0 +1,30 @@
+import { CustomEvent } from './stream.types'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type CustomEventListener = (event: any) => void
+
+export abstract class StreamSubscription {
+  private customEventListeners: Map<string, CustomEventListener[]> = new Map()
+
+  protected onEventReceived(event: CustomEvent) {
+    const customEventListeners = this.customEventListeners.get(event.type)
+
+    if (customEventListeners) {
+      const eventData = event.data
+      customEventListeners.forEach((listener) => listener(eventData))
+    }
+  }
+
+  onEvent(type: string, listener: CustomEventListener) {
+    const listeners = this.customEventListeners.get(type) || []
+    this.customEventListeners.set(type, [...listeners, listener])
+  }
+
+  offEvent(type: string, listener: CustomEventListener) {
+    const listeners = this.customEventListeners.get(type) || []
+    this.customEventListeners.set(
+      type,
+      listeners.filter((l) => l !== listener),
+    )
+  }
+}

package/src/stream.ts

@@ -0,0 +1,26 @@
+import { v4 as uuidv4 } from 'uuid'
+import { StreamGroupSubscription } from './stream-group'
+import { StreamItemSubscription } from './stream-item'
+
+export class Stream {
+  private ws: WebSocket
+
+  constructor(address: string, onReady: () => void) {
+    this.ws = new WebSocket(address)
+    this.ws.onopen = () => onReady()
+  }
+
+  subscribeItem<TData extends { id: string }>(streamName: string, id: string): StreamItemSubscription<TData> {
+    const subscriptionId = uuidv4()
+    return new StreamItemSubscription<TData>(this.ws, { streamName, id, subscriptionId })
+  }
+
+  subscribeGroup<TData extends { id: string }>(streamName: string, groupId: string): StreamGroupSubscription<TData> {
+    const subscriptionId = uuidv4()
+    return new StreamGroupSubscription<TData>(this.ws, { streamName, groupId, subscriptionId })
+  }
+
+  close() {
+    this.ws.close()
+  }
+}

package/src/stream.types.ts

@@ -0,0 +1,20 @@
+export type BaseMessage = { streamName: string } & ({ id: string } | { groupId: string })
+export type JoinMessage = BaseMessage & { subscriptionId: string }
+export type ItemJoinMessage = BaseMessage & { id: string; subscriptionId: string }
+export type GroupJoinMessage = BaseMessage & { groupId: string; 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"
+  ]
+}