tonka-broadcaster 1.1.0

package/README.md

@@ -0,0 +1,96 @@
+# Tonka Broadcaster 📡
+
+Bring real-time, event-driven capabilities to your frontend application.
+
+This package provides a seamless JavaScript client for the **[Tonka Framework](https://clicalmani.github.io/tonka)** broadcast system. Powered by **Mercure Hub**, it allows you to subscribe to public or private channels and listen for backend events in real-time, acting exactly like an echo system for your modern web apps.
+
+## ✨ Features
+
+* 🔄 **Real-Time Synchronization**: Instantly receive backend updates via Server-Sent Events (SSE).
+* 🔒 **Private Channels**: Built-in support for JWT-authorized private channels.
+* ⚛️ **Framework Agnostic**: Works perfectly with raw JavaScript, React, Vue, or Svelte.
+* 🧠 **Simple API**: Minimalist subscription and event-handling syntax (`.channel().listen()`).
+* ⚡ **Resource Efficient**: Light alternative to WebSockets, powered by native browser capabilities.
+
+## 📦 Installation
+
+```bash
+npm install tonka-broadcaster
+# or
+yarn add tonka-broadcaster
+
+```
+
+## ⚙️ Setup
+
+Ensure your **Tonka** backend is configured to broadcast events via your Mercure Hub (`http://localhost:3000/.well-known/mercure`).
+
+Initialize the broadcaster in your frontend entry point (e.g., `app.js` or `main.js`) :
+
+```javascript
+import TonkaBroadcaster from 'tonka-broadcaster';
+
+const broadcaster = new TonkaBroadcaster({
+    hubUrl: 'http://localhost:3000/.well-known/mercure',
+    // Required only if you intend to use private channels
+    token: () => localStorage.getItem('tonka_jwt_token') 
+});
+
+export default broadcaster;
+
+```
+
+---
+
+## 🚀 Usage
+
+### 1. Listen to Public Channels
+
+Subscribe to a public channel to listen for global real-time events.
+
+```javascript
+import broadcaster from './broadcaster';
+
+// Subscribe to a public channel
+const channel = broadcaster.channel('notifications');
+
+// Listen for a specific event
+channel.listen('NewNotification', (data) => {
+    console.log('Notification received:', data.message);
+    alert(`New Alert: ${data.title}`);
+});
+
+```
+
+### 2. Listen to Private Channels
+
+For user-specific data or protected data streams, use private channels. The package automatically attaches your JWT token to authorize the stream.
+
+```javascript
+import broadcaster from './broadcaster';
+
+// Subscribe to a secure private channel
+broadcaster
+    .private(`user.${userId}`)
+    .listen('OrderUpdated', (order) => {
+        console.log(`Order #${order.id} status is now: ${order.status}`);
+    });
+
+```
+
+### 3. Unsubscribe & Cleanup
+
+Avoid memory leaks in components (like React's `useEffect` or Vue's `onUnmounted`) by unsubscribing when the view is destroyed.
+
+```javascript
+// Leave a single channel
+broadcaster.leave('notifications');
+
+// Or leave a private channel
+broadcaster.leave(`user.${userId}`);
+
+```
+
+---
+
+> 💡 **Pro-Tip for Tonka Ecosystem:** Combine `tonka-router` and `tonka-broadcaster` to trigger dynamic redirects or fetch fresh data using named routes directly inside your event listeners!

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export interface BroadcasterConfig {
+    hubUrl: string;
+    token?: string | (() => string | null);
+}
+export type EventCallback = (data: any) => void;
+declare class TonkaChannel {
+    private hubUrl;
+    private channelName;
+    private token?;
+    private eventSource;
+    private listeners;
+    constructor(hubUrl: string, channelName: string, token?: string | undefined);
+    private connect;
+    listen(eventName: string, callback: EventCallback): this;
+    close(): void;
+}
+export default class TonkaBroadcaster {
+    private hubUrl;
+    private tokenResolver?;
+    private activeChannels;
+    constructor(config: BroadcasterConfig);
+    private resolveToken;
+    channel(channelName: string): TonkaChannel;
+    private(channelName: string): TonkaChannel;
+    leave(channelName: string): void;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,92 @@
+class TonkaChannel {
+    constructor(hubUrl, channelName, token) {
+        this.hubUrl = hubUrl;
+        this.channelName = channelName;
+        this.token = token;
+        this.eventSource = null;
+        this.listeners = new Map();
+        this.connect();
+    }
+    connect() {
+        const url = new URL(this.hubUrl);
+        const topicUrl = `https://tonka.framework/channels/${this.channelName}`;
+        url.searchParams.append('topic', topicUrl);
+        if (this.token) {
+            url.searchParams.append('authorization', `Bearer ${this.token}`);
+        }
+        this.eventSource = new EventSource(url.toString());
+        this.eventSource.onmessage = (event) => {
+            try {
+                const payload = JSON.parse(event.data);
+                const eventName = payload.event || 'default';
+                const data = payload.data || payload;
+                const callbacks = this.listeners.get(eventName);
+                if (callbacks) {
+                    callbacks.forEach(callback => callback(data));
+                }
+                const globalCallbacks = this.listeners.get('*');
+                if (globalCallbacks) {
+                    globalCallbacks.forEach(callback => callback(payload));
+                }
+            }
+            catch (error) {
+                console.error("Error parsing Mercure event:", error);
+            }
+        };
+        this.eventSource.onerror = (err) => {
+            console.error(`SSE connection error on channel [${this.channelName}]:`, err);
+        };
+    }
+    listen(eventName, callback) {
+        if (!this.listeners.has(eventName)) {
+            this.listeners.set(eventName, []);
+        }
+        this.listeners.get(eventName).push(callback);
+        return this;
+    }
+    close() {
+        if (this.eventSource) {
+            this.eventSource.close();
+            this.eventSource = null;
+        }
+        this.listeners.clear();
+    }
+}
+export default class TonkaBroadcaster {
+    constructor(config) {
+        this.activeChannels = new Map();
+        this.hubUrl = config.hubUrl;
+        this.tokenResolver = config.token;
+    }
+    resolveToken() {
+        if (typeof this.tokenResolver === 'function') {
+            return this.tokenResolver() || undefined;
+        }
+        return this.tokenResolver;
+    }
+    channel(channelName) {
+        if (!this.activeChannels.has(channelName)) {
+            const channel = new TonkaChannel(this.hubUrl, channelName);
+            this.activeChannels.set(channelName, channel);
+        }
+        return this.activeChannels.get(channelName);
+    }
+    private(channelName) {
+        const privateName = `private.${channelName}`;
+        if (!this.activeChannels.has(privateName)) {
+            const token = this.resolveToken();
+            const channel = new TonkaChannel(this.hubUrl, privateName, token);
+            this.activeChannels.set(privateName, channel);
+        }
+        return this.activeChannels.set(privateName, this.activeChannels.get(privateName)) && this.activeChannels.get(privateName);
+    }
+    leave(channelName) {
+        const targets = [channelName, `private.${channelName}`];
+        targets.forEach(target => {
+            if (this.activeChannels.has(target)) {
+                this.activeChannels.get(target).close();
+                this.activeChannels.delete(target);
+            }
+        });
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "tonka-broadcaster",
+  "version": "1.1.0",
+  "description": "A simple package to broadcast events from Tonka.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "test"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clicalmani/tonka-broadcaster.git"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0",
+    "vitest": "^4.1.8"
+  },
+  "keywords": [
+    "Tonka",
+    "Broadcast",
+    "Event"
+  ],
+  "author": "clicalmani",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/clicalmani/tonka-broadcaster/issues"
+  },
+  "homepage": "https://github.com/clicalmani/tonka-broadcaster#readme"
+}

package/test/index.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import TonkaBroadcaster from '../index';
+
+// 1. EventSource Mock Creation
+class MockEventSource {
+    url: string;
+    onmessage: ((event: any) => void) | null = null;
+    onerror: ((err: any) => void) | null = null;
+    close = vi.fn();
+
+    constructor(url: string) {
+        this.url = url;
+        // Store the instance to simulate events within the tests
+        MockEventSource.instances.push(this);
+    }
+
+    static instances: MockEventSource[] = [];
+    static emit(data: any) {
+        const lastInstance = MockEventSource.instances[MockEventSource.instances.length - 1];
+        if (lastInstance && lastInstance.onmessage) {
+            lastInstance.onmessage({ data: JSON.stringify(data) });
+        }
+    }
+    static emitError(err: any) {
+        const lastInstance = MockEventSource.instances[MockEventSource.instances.length - 1];
+        if (lastInstance && lastInstance.onerror) {
+            lastInstance.onerror(err);
+        }
+    }
+}
+
+describe('TonkaBroadcaster', () => {
+    const hubUrl = 'http://localhost:3000/.well-known/mercure';
+
+    beforeEach(() => {
+        MockEventSource.instances = [];
+        // Replace the browser's global EventSource with our Mock
+        vi.stubGlobal('EventSource', MockEventSource);
+    });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+
+    it('should initialize a public channel with the correct topic', () => {
+        const broadcaster = new TonkaBroadcaster({ hubUrl });
+        
+        // Join a channel
+        broadcaster.channel('chat');
+
+        expect(MockEventSource.instances.length).toBe(1);
+        const instantiatedUrl = new URL(MockEventSource.instances[0].url);
+        
+        // Verify the target Mercure URL and the Tonka topic
+        expect(instantiatedUrl.origin + instantiatedUrl.pathname).toBe(hubUrl);
+        expect(instantiatedUrl.searchParams.get('topic')).toBe('https://tonka.framework/channels/chat');
+    });
+
+    it('should inject the JWT token into the URL for private channels', () => {
+        const token = 'my-secret-jwt-token';
+        const broadcaster = new TonkaBroadcaster({
+            hubUrl,
+            token: () => token // Dynamic resolution
+        });
+
+        broadcaster.private('dashboard');
+
+        const instantiatedUrl = new URL(MockEventSource.instances[0].url);
+        expect(instantiatedUrl.searchParams.get('topic')).toBe('https://tonka.framework/channels/private.dashboard');
+        expect(instantiatedUrl.searchParams.get('authorization')).toBe(`Bearer ${token}`);
+    });
+
+    it('should trigger the correct listener upon receiving a message', () => {
+        const broadcaster = new TonkaBroadcaster({ hubUrl });
+        const callback = vi.fn();
+
+        broadcaster.channel('orders').listen('OrderPlaced', callback);
+
+        // Simulate a message dispatched by the Mercure Hub
+        const mockPayload = {
+            event: 'OrderPlaced',
+            data: { id: 42, total: 1500 }
+        };
+        MockEventSource.emit(mockPayload);
+
+        // Verifications
+        expect(callback).toHaveBeenCalledTimes(1);
+        expect(callback).toHaveBeenCalledWith({ id: 42, total: 1500 });
+    });
+
+    it('should reuse the same connection if subscribing twice to the same channel (Multiton pattern)', () => {
+        const broadcaster = new TonkaBroadcaster({ hubUrl });
+
+        // Two subscriptions to the same channel
+        broadcaster.channel('notifications');
+        broadcaster.channel('notifications');
+
+        // Only a single EventSource instance should be created on the network side
+        expect(MockEventSource.instances.length).toBe(1);
+    });
+
+    it('should cleanly close the network connection when calling leave()', () => {
+        const broadcaster = new TonkaBroadcaster({ hubUrl });
+        
+        broadcaster.channel('crypto');
+        expect(MockEventSource.instances.length).toBe(1);
+
+        const currentMockInstance = MockEventSource.instances[0];
+        
+        // Leave the channel
+        broadcaster.leave('crypto');
+
+        // The native close method of EventSource must have been called
+        expect(currentMockInstance.close).toHaveBeenCalledTimes(1);
+    });
+});