@mifistix-cloud/realtime

Realtime WebSocket SDK for Mifistix Cloud - Subscribe to data changes in realtime.

License

This module is licensed for internal use within Mifistix only. See LICENSE for details.

Installation

npm install @mifistix-cloud/realtime

Quick Start

const { initializeApp } = require('@mifistix-cloud/app');
const { connectRealtime, onValue, off } = require('@mifistix-cloud/realtime');

// Initialize app
const app = initializeApp({
  apiKey: 'your-api-key',
  projectId: 'your-project-id'
});

// Connect to realtime
const rt = connectRealtime(app);

// Listen for value changes
const unsubscribe = onValue(rt, 'users/user1', (snapshot) => {
  console.log('User data changed:', snapshot.val());
});

// Stop listening
off(unsubscribe);

// Disconnect
rt.disconnect();

API Reference

connectRealtime(app, customWsUrl?)

Connect to realtime WebSocket server.

Parameters:

• app (Object, required): Initialized app instance
• customWsUrl (string, optional): Custom WebSocket URL

Returns: Realtime client instance

Example:

const rt = connectRealtime(app, 'wss://your-ws-server.com');

onValue(rt, path, callback)

Listen for value changes at a path.

Parameters:

• rt (Object): Realtime instance
• path (string, required): Database path (validated)
• callback (Function, required): Callback function receiving snapshot

Returns: Unsubscribe function

Example:

const unsubscribe = onValue(rt, 'users/user1', (snapshot) => {
  if (snapshot.exists()) {
    console.log('Current value:', snapshot.val());
  }
});

onChildAdded(rt, path, callback)

Listen for child added events (simplified implementation).

Parameters:

• rt (Object): Realtime instance
• path (string, required): Database path
• callback (Function, required): Callback function

Returns: Unsubscribe function

off(unsub)

Unsubscribe from a listener.

Parameters:

• unsub (Function): Unsubscribe function returned by onValue/onChildAdded

Realtime Client Methods

rt.disconnect()

Disconnect WebSocket and stop auto-reconnect.

Example:

rt.disconnect();

Data Snapshot

Callbacks receive a snapshot object:

snapshot.val();      // any - the data value
snapshot.exists();   // boolean - whether data exists
snapshot.key();      // string - the key

WebSocket Features

• Auto-reconnect: Automatically reconnects on connection loss
• Exponential backoff: Reconnect delay increases on failures
• Queue: Messages queued while disconnected
• Resubscribe: Automatically resubscribes on reconnect

Security Features

• Path Validation: Validates paths before subscription
• Callback Validation: Ensures callback is a function
• Project Isolation: Uses project ID in WebSocket URL
• API Key Auth: API key in WebSocket URL for authentication

Architecture

realtime/
├── src/
│   ├── core/
│   │   └── RealtimeClient.js    # Main realtime client
│   ├── services/
│   │   └── WebSocketClient.js   # WebSocket connection
│   ├── utils/
│   │   └── helpers.js          # Helper functions
│   ├── types/
│   │   └── index.js            # Type definitions
│   └── config/
│       └── constants.js        # Configuration constants
└── index.js

License

MIT