@motiadev/stream-client-node

Motia Stream Client Package – Responsible for managing real-time Motia streams of data in node 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

npm install @motiadev/stream-client-node

Usage

1. Creating a Stream Connection

import { Stream } from '@motiadev/stream-client-node'

const stream = new Stream('wss://your-stream-server')

2. Subscribing to an Item Stream

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

const groupSubscription = stream.subscribeGroup<{ id: string; name: string }>('users', 'group-abc')

groupSubscription.addChangeListener((users) => {
  console.log('Group users updated:', users)
})

4. Cleaning Up

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(streamName: string, id: string): StreamItemSubscription
- Subscribes to a single item in a stream.
- Returns a StreamItemSubscription instance.
subscribeGroup(streamName: string, groupId: string): StreamGroupSubscription
- 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

import { Stream } from '@motiadev/stream-client-node'

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

4.0 KiB Raw Blame History Unescape Escape