@rvettori/elysia-broadcast 0.2.0

package/README.md

@@ -0,0 +1,361 @@
+# @rvettori/elysia-broadcast
+
+Broadcast and Server-Sent Events (SSE) system for Elysia with multi-channel per-user support.
+
+## 🚀 Features
+
+- ✅ **Multiple channels per user** - Each user can connect to multiple channels simultaneously
+- ✅ **Type-safe** - Fully typed with TypeScript
+- ✅ **SSE out-of-the-box** - Ready-to-use Server-Sent Events plugin with client library
+- ✅ **Alpine.js compatible** - Works seamlessly with Alpine.morph and x-sync
+- ✅ **Flexible** - Use `BroadcastManager` standalone or as an Elysia plugin
+- ✅ **Lightweight** - Zero dependencies besides Elysia
+- ✅ **Tested** - Complete test coverage
+
+## 📦 Installation
+
+```bash
+bun add @rvettori/elysia-broadcast
+```
+
+## 🎯 Basic Usage
+
+### Server Setup
+
+```typescript
+import { Elysia } from 'elysia';
+import { broadcastPlugin, streamPlugin } from '@rvettori/elysia-broadcast';
+
+const app = new Elysia()
+  .use(broadcastPlugin())
+  .use(streamPlugin({
+    authMiddleware: yourAuthMiddleware,
+    getUserId: (ctx) => ctx.store.user.userId
+  }))
+  .post('/todos', ({ store }) => {
+    // Create todo...
+    
+    // Broadcast to user's 'todos' channel
+    store.broadcast.broadcast('todos', userId, {
+      type: 'todo.created',
+      data: { id: 1, task: 'New task' },
+      html: '<div x-sync id="todo-list">...</div>' // Alpine-compatible
+    });
+    
+    return { success: true };
+  })
+  .listen(3000);
+```
+
+### Client Setup
+
+The `streamPlugin` automatically provides a client library at `/vendor/elysia-sse.js`:
+
+```html
+<!-- Load the client library -->
+<script src="/vendor/elysia-sse.js"></script>
+
+<!-- Connect to a channel -->
+<script>
+  ElysiaSSE.connect('todos');
+</script>
+
+<!-- Elements with x-sync and id will be auto-updated -->
+<div x-sync id="todo-list">
+  <!-- Content here will be updated via SSE -->
+</div>
+```
+
+### BroadcastManager Standalone
+
+```typescript
+import { BroadcastManager } from '@rvettori/elysia-broadcast';
+
+const manager = new BroadcastManager();
+
+// Subscribe
+const unsubscribe = manager.subscribe('notifications', 123, (event) => {
+  console.log('Event received:', event.type, event.data);
+});
+
+// Broadcast to specific user
+manager.broadcast('notifications', 123, {
+  type: 'notification.new',
+  data: { message: 'Hello!' }
+});
+
+// Broadcast to ALL users in channel
+manager.broadcast('notifications', {
+  type: 'system.announcement',
+  data: { message: 'System maintenance at 3pm' }
+});
+
+// Cleanup
+unsubscribe();
+```
+
+## 📚 API
+
+### `broadcastPlugin(options?)`
+
+Elysia plugin that injects `BroadcastManager` into the store.
+
+**Options:**
+- `stateName?: string` - State name (default: `'broadcast'`)
+
+**Example:**
+```typescript
+app.use(broadcastPlugin({ stateName: 'events' }));
+
+app.get('/trigger', ({ store }) => {
+  store.events.broadcast('channel', userId, { ... });
+});
+```
+
+### `streamPlugin(options?)`
+
+Plugin that creates a generic SSE route.
+
+**Options:**
+```typescript
+interface StreamPluginOptions {
+  basePath?: string;              // Default: '/stream'
+  userStoreName?: string;         // Default: 'user'
+  userIdField?: string;           // Default: 'userId'
+  getUserId?: (context) => number | string;
+  authMiddleware?: any;
+}
+```
+
+**Example:**
+```typescript
+app.use(streamPlugin({
+  basePath: '/events',
+  authMiddleware: sessionAuth,
+  getUserId: (ctx) => ctx.store.currentUser.id
+}));
+
+// Client: GET /events/todos
+```
+
+### `BroadcastManager`
+
+Main event management class.
+
+#### Methods
+
+**`subscribe(channel, userId, callback)`**
+
+Register a listener.
+
+```typescript
+const unsubscribe = manager.subscribe('todos', 123, (event) => {
+  console.log(event.type, event.data);
+});
+```
+
+**`broadcast(channel, userId, event)`** | **`broadcast(channel, event)`**
+
+Send event to all listeners on the channel/user. Omit userId to broadcast to all users in the channel.
+
+```typescript
+// Broadcast to specific user
+manager.broadcast('todos', 123, {
+  type: 'update',
+  data: { id: 1 },
+  html: '<div>...</div>' // Optional
+});
+
+// Broadcast to ALL users in channel (no userId)
+manager.broadcast('todos', {
+  type: 'system.announcement',
+  data: { message: 'New feature available!' }
+});
+```
+
+**`getConnectionCount(channel, userId)`**
+
+Returns number of active connections for channel/user.
+
+**`getTotalConnections()`**
+
+Returns total number of connections.
+
+**`getActiveChannels()`**
+
+Lists all active channels.
+
+**`clearChannel(channel, userId)`**
+
+Removes all connections from a channel.
+
+**`clearAll()`**
+
+Removes all connections.
+
+## 🎨 Frontend Integration
+
+### Alpine.js + SSE (Recommended)
+
+```html
+<!-- 1. Load libraries -->
+<script src="/vendor/elysia-sse.js"></script>
+<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>
+
+<!-- 2. Connect to SSE channel -->
+<script>
+  ElysiaSSE.connect('todos');
+</script>
+
+<!-- 3. Elements with x-sync and id will be auto-updated -->
+<div x-sync id="todo-list" x-data="{ todos: [] }">
+  <template x-for="todo in todos">
+    <div x-text="todo.task"></div>
+  </template>
+</div>
+
+<!-- Multiple elements can be updated simultaneously -->
+<div x-sync id="todo-stats">Total: 5</div>
+<div x-sync id="user-badge">👤 John</div>
+```
+
+### Vanilla JavaScript
+
+```html
+<script src="/vendor/elysia-sse.js"></script>
+<script>
+  // Basic connection
+  ElysiaSSE.connect('notifications');
+  
+  // With custom handler
+  ElysiaSSE.connect('messages', {
+    onUpdate: (data) => {
+      console.log('New message:', data);
+      // Custom DOM manipulation
+    },
+    onConnect: () => console.log('Connected!'),
+    onError: (err) => console.error('Error:', err)
+  });
+</script>
+```
+
+### HTMX + SSE
+
+```html
+<div x-data="{ todos: [] }" x-sync id="todo-list">
+  <template x-for="todo in todos">
+    <div x-text="todo.task"></div>
+  </template>
+</div>
+
+<script>
+  const eventSource = new EventSource('/stream/todos');
+  
+  eventSource.onmessage = (event) => {
+    const { type, html, data } = JSON.parse(event.data);
+    
+    // With Alpine AJAX: updates elements by ID
+    if (html) {
+      Alpine.morph(document.getElementById('todo-list'), html);
+    }
+  };
+</script>
+```
+
+### HTMX + SSE
+
+```html
+<div hx-ext="sse" sse-connect="/stream/todos">
+  <div id="todo-list" sse-swap="message">
+    <!-- Todo list -->
+  </div>
+</div>
+```
+
+## 🔧 Use Cases
+
+### Real-time Dashboard
+
+```typescript
+app.post('/analytics/track', ({ store, body }) => {
+  // Process event...
+  
+  store.broadcast.broadcast('dashboard', userId, {
+    type: 'metric.updated',
+    data: { visitors: 1234, sales: 5678 }
+  });
+});
+```
+
+### Notifications
+
+```typescript
+// Send to specific user
+app.post('/notifications/send', ({ store, body }) => {
+  store.broadcast.broadcast('notifications', recipientId, {
+    type: 'notification.new',
+    data: { 
+      title: 'New comment',
+      message: 'Someone commented on your post'
+    }
+  });
+});
+
+// Send to all users (system announcement)
+app.post('/admin/announce', ({ store, body }) => {
+  store.broadcast.broadcast('notifications', {
+    type: 'system.announcement',
+    data: { 
+      title: 'System Update',
+      message: 'New features available!'
+    }
+  });
+});
+```
+
+### Chat/Messages
+
+```typescript
+app.post('/messages', ({ store, body }) => {
+  // Save message...
+  
+  // Notify recipient
+  store.broadcast.broadcast('messages', recipientId, {
+    type: 'message.new',
+    data: { from: senderId, text: body.text }
+  });
+});
+```
+
+## 🧪 Testing
+
+```bash
+bun test
+```
+
+## 📝 Types
+
+```typescript
+interface BroadcastEvent {
+  type: string;
+  data: any;
+  html?: string;
+}
+
+type BroadcastCallback = (event: BroadcastEvent) => void;
+type UnsubscribeFunction = () => void;
+```
+
+## 🛠️ Build
+
+```bash
+bun run build
+```
+
+## 📄 License
+
+MIT
+
+## 🤝 Contributing
+
+Contributions are welcome! Open an issue or PR.

package/dist/client.js

@@ -0,0 +1,142 @@
+/**
+ * SSE (Server-Sent Events) client for elysia-broadcast
+ * 
+ * 🎯 FULL COMPATIBILITY WITH ALPINE-AJAX:
+ * Processes elements with 'x-sync' attribute and updates using Alpine.morph,
+ * maintaining parity with alpine-ajax behavior in synchronous requests.
+ * 
+ * @module elysia-broadcast/client
+ */
+
+/**
+ * Connects to an SSE channel and manages automatic DOM updates
+ * 
+ * @param {string} channel - SSE channel name
+ * @param {Object} options - Configuration options
+ * @param {string} options.basePath - SSE base path (default: '/stream')
+ * @param {Function} options.onUpdate - Custom handler for events
+ * @param {Function} options.onConnect - Callback when connected
+ * @param {Function} options.onError - Callback when error occurs
+ * @param {Function} options.onDisconnect - Callback when disconnected
+ * @returns {EventSource} EventSource instance
+ * 
+ * @example
+ * // Basic usage
+ * ElysiaSSE.connect('todos');
+ * 
+ * @example
+ * // With callbacks
+ * ElysiaSSE.connect('todos', {
+ *   onConnect: () => console.log('Connected!'),
+ *   onUpdate: (data) => console.log('Updated:', data)
+ * });
+ */
+window.ElysiaSSE = {
+  connect: function (channel, options = {}) {
+    const {
+      basePath = '/stream',
+      onUpdate = null,
+      onConnect = null,
+      onError = null,
+      onDisconnect = null
+    } = options;
+
+    const url = basePath + '/' + channel;
+    const eventSource = new EventSource(url);
+
+    eventSource.onopen = function () {
+      console.log('🔌 [SSE] Conectado ao canal:', channel);
+      if (onConnect) onConnect();
+    };
+
+    eventSource.onmessage = function (event) {
+      try {
+        const data = JSON.parse(event.data);
+
+        // Custom handler has priority
+        if (onUpdate && typeof onUpdate === 'function') {
+          onUpdate(data);
+          return;
+        }
+
+        // Default processing: multiple elements with x-sync (like alpine-ajax)
+        if (data.html) {
+          const parser = new DOMParser();
+          const doc = parser.parseFromString(data.html, 'text/html');
+
+          // Search ALL elements with x-sync attribute (alpine-ajax compatibility)
+          const elementsWithSync = doc.querySelectorAll('[x-sync]');
+
+          if (elementsWithSync.length === 0) {
+            console.error('❌ [SSE] Nenhum elemento com atributo x-sync encontrado');
+            console.error('💡 [SSE] Adicione x-sync e id="..." nos elementos');
+            console.error('💡 [SSE] Exemplo: <div x-sync id="meu-elemento">...</div>');
+            return;
+          }
+
+          let updatedCount = 0;
+          let errors = [];
+
+          // Process each element (compatible with alpine-ajax multi-target)
+          elementsWithSync.forEach(function (newElement) {
+            const targetId = newElement.getAttribute('id');
+
+            if (!targetId) {
+              errors.push('Element ' + newElement.tagName + ' without id');
+              return;
+            }
+
+            const existingElement = document.getElementById(targetId);
+
+            if (!existingElement) {
+              errors.push('ID not found: ' + targetId);
+              return;
+            }
+
+            // Use Alpine.morph to preserve reactive state
+            if (window.Alpine && window.Alpine.morph) {
+              Alpine.morph(existingElement, newElement.outerHTML);
+            } else {
+              // Fallback: direct replacement
+              existingElement.outerHTML = newElement.outerHTML;
+            }
+
+            updatedCount++;
+          });
+
+          if (updatedCount > 0) {
+            console.log('✨ [SSE] ' + updatedCount + ' element(s) updated - ' + data.type);
+          }
+
+          if (errors.length > 0) {
+            console.error('❌ [SSE] Erros:', errors.join(', '));
+          }
+        }
+      } catch (error) {
+        console.error('❌ [SSE] Erro ao processar evento:', error);
+      }
+    };
+
+    eventSource.onerror = function (error) {
+      console.error('❌ [SSE] Connection error:', error);
+
+      if (eventSource.readyState === EventSource.CLOSED) {
+        console.log('🔄 [SSE] Reconnecting in 5 seconds...');
+        setTimeout(function () {
+          window.location.reload();
+        }, 5000);
+
+        if (onError) onError(error);
+      }
+    };
+
+    // Close connection when page is unloaded
+    window.addEventListener('beforeunload', function () {
+      eventSource.close();
+      console.log('👋 [SSE] Desconectado do canal:', channel);
+      if (onDisconnect) onDisconnect();
+    });
+
+    return eventSource;
+  }
+};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * elysia-broadcast
+ *
+ * Broadcast and SSE (Server-Sent Events) system for Elysia
+ * with support for multiple channels per user
+ *
+ * @module elysia-broadcast
+ */
+export { BroadcastManager } from './manager';
+export { broadcastPlugin, broadcastManager, alpineRequest } from './plugin';
+export { streamPlugin } from './stream';
+export type { BroadcastEvent, BroadcastCallback, UnsubscribeFunction, BroadcastPluginOptions, StreamPluginOptions } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACpB,MAAM,SAAS,CAAC"}