@cendarsoss/pusher-js 8.4.11

package/IMPORT_GUIDE.md

@@ -0,0 +1,638 @@
+# Import Guide for Pusher-JS (Sockudo Edition)
+
+This guide explains how to import and use the Pusher-JS library with delta compression and tag filtering features.
+
+## Table of Contents
+
+- [Basic Import (Pusher Only)](#basic-import-pusher-only)
+- [With Filter Support](#with-filter-support)
+- [Framework Examples](#framework-examples)
+  - [Vue 3](#vue-3)
+  - [React](#react)
+  - [Angular](#angular)
+  - [Vanilla JavaScript](#vanilla-javascript)
+- [TypeScript Support](#typescript-support)
+- [Delta Compression](#delta-compression)
+- [Tag Filtering](#tag-filtering)
+
+---
+
+## Basic Import (Pusher Only)
+
+When you only need the Pusher client without filters:
+
+```javascript
+import Pusher from 'pusher-js';
+
+const pusher = new Pusher('your-app-key', {
+  cluster: 'mt1',
+  wsHost: 'localhost',
+  wsPort: 6001,
+  forceTLS: false,
+});
+
+const channel = pusher.subscribe('my-channel');
+channel.bind('my-event', (data) => {
+  console.log('Received:', data);
+});
+```
+
+---
+
+## With Filter Support
+
+When you need tag filtering capabilities, import Filter separately:
+
+```javascript
+import Pusher from 'pusher-js';
+import { Filter, FilterExamples } from 'pusher-js/filter';
+
+const pusher = new Pusher('your-app-key', {
+  cluster: 'mt1',
+  wsHost: 'localhost',
+  wsPort: 6001,
+});
+
+// Subscribe with a filter
+const channel = pusher.subscribe(
+  'events-channel',
+  Filter.eq('event_type', 'goal')
+);
+```
+
+---
+
+## Framework Examples
+
+### Vue 3
+
+#### Composition API
+
+```vue
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue';
+import Pusher from 'pusher-js';
+import { Filter } from 'pusher-js/filter';
+
+const messages = ref([]);
+let pusher = null;
+let channel = null;
+
+onMounted(() => {
+  // Initialize Pusher
+  pusher = new Pusher('your-app-key', {
+    cluster: 'mt1',
+    wsHost: 'localhost',
+    wsPort: 6001,
+    forceTLS: false,
+    
+    // Enable delta compression
+    deltaCompression: {
+      enabled: true,
+      algorithms: ['fossil', 'xdelta3'],
+      debug: false,
+      onStats: (stats) => {
+        console.log('Bandwidth saved:', stats.bandwidthSavedPercent + '%');
+      }
+    }
+  });
+
+  // Subscribe to a channel
+  channel = pusher.subscribe('chat-room');
+  
+  channel.bind('message', (data) => {
+    messages.value.push(data);
+  });
+
+  // Subscribe with tag filter
+  const filteredChannel = pusher.subscribe(
+    'sports-events',
+    Filter.or(
+      Filter.eq('event_type', 'goal'),
+      Filter.eq('event_type', 'red_card')
+    )
+  );
+  
+  filteredChannel.bind('event', (data) => {
+    console.log('Important event:', data);
+  });
+});
+
+onUnmounted(() => {
+  if (channel) {
+    channel.unbind_all();
+    pusher.unsubscribe(channel.name);
+  }
+  if (pusher) {
+    pusher.disconnect();
+  }
+});
+</script>
+
+<template>
+  <div>
+    <h1>Chat Messages</h1>
+    <div v-for="msg in messages" :key="msg.id">
+      {{ msg.text }}
+    </div>
+  </div>
+</template>
+```
+
+#### Options API
+
+```vue
+<script>
+import Pusher from 'pusher-js';
+import { Filter } from 'pusher-js/filter';
+
+export default {
+  data() {
+    return {
+      pusher: null,
+      channel: null,
+      messages: []
+    };
+  },
+  
+  mounted() {
+    this.pusher = new Pusher('your-app-key', {
+      cluster: 'mt1',
+      wsHost: 'localhost',
+      wsPort: 6001,
+      forceTLS: false,
+    });
+
+    this.channel = this.pusher.subscribe('my-channel');
+    this.channel.bind('message', this.handleMessage);
+  },
+  
+  methods: {
+    handleMessage(data) {
+      this.messages.push(data);
+    }
+  },
+  
+  beforeUnmount() {
+    if (this.channel) {
+      this.channel.unbind_all();
+      this.pusher.unsubscribe(this.channel.name);
+    }
+    if (this.pusher) {
+      this.pusher.disconnect();
+    }
+  }
+};
+</script>
+```
+
+### React
+
+```jsx
+import { useEffect, useState } from 'react';
+import Pusher from 'pusher-js';
+import { Filter } from 'pusher-js/filter';
+
+function ChatComponent() {
+  const [messages, setMessages] = useState([]);
+  const [pusher, setPusher] = useState(null);
+
+  useEffect(() => {
+    // Initialize Pusher
+    const pusherInstance = new Pusher('your-app-key', {
+      cluster: 'mt1',
+      wsHost: 'localhost',
+      wsPort: 6001,
+      forceTLS: false,
+      
+      // Enable delta compression
+      deltaCompression: {
+        enabled: true,
+        algorithms: ['fossil', 'xdelta3']
+      }
+    });
+
+    setPusher(pusherInstance);
+
+    // Subscribe to channel
+    const channel = pusherInstance.subscribe('chat-room');
+    
+    channel.bind('message', (data) => {
+      setMessages(prev => [...prev, data]);
+    });
+
+    // Subscribe with filter
+    const filteredChannel = pusherInstance.subscribe(
+      'notifications',
+      Filter.eq('priority', 'high')
+    );
+    
+    filteredChannel.bind('notification', (data) => {
+      console.log('High priority notification:', data);
+    });
+
+    // Cleanup
+    return () => {
+      channel.unbind_all();
+      filteredChannel.unbind_all();
+      pusherInstance.unsubscribe('chat-room');
+      pusherInstance.unsubscribe('notifications');
+      pusherInstance.disconnect();
+    };
+  }, []);
+
+  return (
+    <div>
+      <h1>Chat Messages</h1>
+      {messages.map((msg, idx) => (
+        <div key={idx}>{msg.text}</div>
+      ))}
+    </div>
+  );
+}
+
+export default ChatComponent;
+```
+
+### Angular
+
+```typescript
+import { Component, OnInit, OnDestroy } from '@angular/core';
+import Pusher from 'pusher-js';
+import { Filter } from 'pusher-js/filter';
+
+@Component({
+  selector: 'app-chat',
+  templateUrl: './chat.component.html'
+})
+export class ChatComponent implements OnInit, OnDestroy {
+  messages: any[] = [];
+  private pusher: any;
+  private channel: any;
+
+  ngOnInit() {
+    this.pusher = new Pusher('your-app-key', {
+      cluster: 'mt1',
+      wsHost: 'localhost',
+      wsPort: 6001,
+      forceTLS: false,
+      
+      deltaCompression: {
+        enabled: true,
+        algorithms: ['fossil', 'xdelta3']
+      }
+    });
+
+    this.channel = this.pusher.subscribe('chat-room');
+    
+    this.channel.bind('message', (data: any) => {
+      this.messages.push(data);
+    });
+
+    // Subscribe with filter
+    const filteredChannel = this.pusher.subscribe(
+      'events',
+      Filter.in('type', ['goal', 'assist'])
+    );
+    
+    filteredChannel.bind('event', (data: any) => {
+      console.log('Sports event:', data);
+    });
+  }
+
+  ngOnDestroy() {
+    if (this.channel) {
+      this.channel.unbind_all();
+      this.pusher.unsubscribe(this.channel.name);
+    }
+    if (this.pusher) {
+      this.pusher.disconnect();
+    }
+  }
+}
+```
+
+### Vanilla JavaScript
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Pusher Example</title>
+</head>
+<body>
+  <div id="messages"></div>
+
+  <script type="module">
+    import Pusher from './node_modules/pusher-js/dist/web/pusher.mjs';
+    import { Filter } from './node_modules/pusher-js/dist/web/filter.mjs';
+
+    const pusher = new Pusher('your-app-key', {
+      cluster: 'mt1',
+      wsHost: 'localhost',
+      wsPort: 6001,
+      forceTLS: false,
+    });
+
+    const channel = pusher.subscribe('my-channel');
+    
+    channel.bind('message', (data) => {
+      const div = document.createElement('div');
+      div.textContent = data.text;
+      document.getElementById('messages').appendChild(div);
+    });
+
+    // With filter
+    const filteredChannel = pusher.subscribe(
+      'notifications',
+      Filter.eq('urgent', 'true')
+    );
+    
+    filteredChannel.bind('alert', (data) => {
+      alert('Urgent: ' + data.message);
+    });
+  </script>
+</body>
+</html>
+```
+
+---
+
+## TypeScript Support
+
+Full TypeScript definitions are included:
+
+```typescript
+import Pusher from 'pusher-js';
+import { Filter, FilterNode, FilterExamples } from 'pusher-js/filter';
+import type { Channel, PresenceChannel } from 'pusher-js';
+
+// Type-safe Pusher initialization
+const pusher = new Pusher('your-app-key', {
+  cluster: 'mt1',
+  wsHost: 'localhost',
+  wsPort: 6001,
+  forceTLS: false,
+});
+
+// Type-safe channel
+const channel: Channel = pusher.subscribe('my-channel');
+
+// Type-safe filter
+const filter: FilterNode = Filter.and(
+  Filter.eq('type', 'order'),
+  Filter.gte('amount', '100')
+);
+
+const filteredChannel = pusher.subscribe('orders', filter);
+```
+
+---
+
+## Delta Compression
+
+Enable delta compression to save up to 60-90% bandwidth on similar consecutive messages:
+
+```javascript
+import Pusher from 'pusher-js';
+
+const pusher = new Pusher('your-app-key', {
+  cluster: 'mt1',
+  wsHost: 'localhost',
+  wsPort: 6001,
+  
+  // Delta compression configuration
+  deltaCompression: {
+    enabled: true,
+    algorithms: ['fossil', 'xdelta3'], // Supported algorithms
+    debug: true, // Enable debug logging
+    onStats: (stats) => {
+      console.log('Delta Compression Stats:', {
+        totalMessages: stats.totalMessages,
+        deltaMessages: stats.deltaMessages,
+        fullMessages: stats.fullMessages,
+        bandwidthSaved: stats.bandwidthSavedPercent.toFixed(1) + '%'
+      });
+    },
+    onError: (error) => {
+      console.error('Delta compression error:', error);
+    }
+  }
+});
+
+// Get delta statistics
+const stats = pusher.getDeltaStats();
+console.log('Bandwidth saved:', stats.bandwidthSavedPercent);
+
+// Reset statistics
+pusher.resetDeltaStats();
+```
+
+### Delta Compression Notes
+
+- **Automatic**: Once enabled, delta compression works transparently
+- **Server-side**: Must be enabled on the server (Sockudo) as well
+- **Algorithms**: Supports `fossil` (fast) and `xdelta3` (better compression)
+- **Fallback**: Automatically falls back to full messages if decoding fails
+
+---
+
+## Tag Filtering
+
+Subscribe to channels with server-side filtering to reduce bandwidth:
+
+```javascript
+import Pusher from 'pusher-js';
+import { Filter, FilterExamples } from 'pusher-js/filter';
+
+const pusher = new Pusher('your-app-key', {
+  cluster: 'mt1',
+  wsHost: 'localhost',
+  wsPort: 6001,
+});
+
+// Simple equality filter
+const goalsChannel = pusher.subscribe(
+  'match:123',
+  Filter.eq('event_type', 'goal')
+);
+
+// Complex filter with AND/OR
+const importantEvents = pusher.subscribe(
+  'match:123',
+  Filter.or(
+    Filter.eq('event_type', 'goal'),
+    Filter.and(
+      Filter.eq('event_type', 'shot'),
+      Filter.gte('xG', '0.8') // High expected goals
+    )
+  )
+);
+
+// Range filter
+const highValueOrders = pusher.subscribe(
+  'orders',
+  Filter.and(
+    Filter.gte('amount', '100'),
+    Filter.lte('amount', '1000')
+  )
+);
+
+// IN filter (multiple values)
+const selectedTypes = pusher.subscribe(
+  'events',
+  Filter.in('type', ['goal', 'assist', 'penalty'])
+);
+
+// String filters
+const userEvents = pusher.subscribe(
+  'activity',
+  Filter.startsWith('user_id', 'premium_')
+);
+
+// Existence filter
+const hasLocation = pusher.subscribe(
+  'updates',
+  Filter.exists('location')
+);
+```
+
+### Available Filter Operators
+
+```javascript
+// Comparison
+Filter.eq(key, value)           // Equal
+Filter.neq(key, value)          // Not equal
+Filter.gt(key, value)           // Greater than
+Filter.gte(key, value)          // Greater than or equal
+Filter.lt(key, value)           // Less than
+Filter.lte(key, value)          // Less than or equal
+
+// Set operations
+Filter.in(key, values)          // In array
+Filter.nin(key, values)         // Not in array
+
+// String operations
+Filter.startsWith(key, value)   // Starts with
+Filter.endsWith(key, value)     // Ends with
+Filter.contains(key, value)     // Contains substring
+
+// Existence
+Filter.exists(key)              // Key exists
+Filter.notExists(key)           // Key does not exist
+
+// Logical operators
+Filter.and(...filters)          // All filters must match
+Filter.or(...filters)           // Any filter must match
+Filter.not(filter)              // Negate filter
+```
+
+### Filter Examples
+
+```javascript
+import { FilterExamples } from 'pusher-js/filter';
+
+// Pre-built filter examples
+const goalEvents = FilterExamples.eventType('goal');
+const multipleTypes = FilterExamples.eventTypes(['goal', 'shot', 'save']);
+const rangeFilter = FilterExamples.range('price', '10', '100');
+const importantEvents = FilterExamples.importantEvents('0.7'); // xG threshold
+```
+
+### Server-Side Requirements
+
+For tag filtering to work:
+
+1. **Server must support it**: Ensure Sockudo has tag filtering enabled
+2. **Tags in publications**: Server must include tags when publishing events:
+
+```javascript
+// Server-side (Node.js example)
+pusher.trigger('match:123', 'event', {
+  player: 'Messi',
+  minute: 34
+}, {
+  tags: {
+    event_type: 'goal',
+    priority: 'high'
+  }
+});
+```
+
+---
+
+## Migration from Previous Versions
+
+If you were using the old import style:
+
+### ❌ Old Way (No Longer Works)
+```javascript
+import Pusher, { Filter } from 'pusher-js';
+```
+
+### ✅ New Way (Clean Separation)
+```javascript
+import Pusher from 'pusher-js';
+import { Filter } from 'pusher-js/filter';
+```
+
+### Why the Change?
+
+This change provides:
+- **Better bundling**: Works consistently across all bundlers (Webpack, Vite, Bun, Rollup)
+- **Smaller bundles**: Only import Filter if you need it
+- **Clearer API**: Separate concerns (connection vs. filtering)
+- **TypeScript friendly**: Better type inference and IDE support
+
+---
+
+## Troubleshooting
+
+### Module Not Found: 'pusher-js/filter'
+
+Make sure your bundler supports package.json `exports` field. Most modern bundlers do:
+- ✅ Webpack 5+
+- ✅ Vite
+- ✅ Bun
+- ✅ Rollup with `@rollup/plugin-node-resolve`
+- ⚠️ Webpack 4: May need configuration updates
+
+### Delta Compression Not Working
+
+1. Check server has delta compression enabled
+2. Ensure delta libraries are loaded (fossil-delta, vcdiff-decoder)
+3. Check browser console for errors
+4. Try enabling debug mode: `deltaCompression: { debug: true }`
+
+### Tag Filtering Not Working
+
+1. Verify server has tag filtering enabled
+2. Check that server includes tags when publishing events
+3. Use `validateFilter` to check filter syntax:
+
+```javascript
+import { validateFilter } from 'pusher-js/filter';
+
+const filter = Filter.eq('type', 'goal');
+const error = validateFilter(filter);
+if (error) {
+  console.error('Invalid filter:', error);
+}
+```
+
+---
+
+## Additional Resources
+
+- [Delta Compression Documentation](./DELTA_COMPRESSION.md)
+- [Tag Filtering Documentation](./TAG_FILTERING_CLIENT.md)
+- [Main README](./README.md)
+- [Sockudo Server Documentation](../../README.md)
+
+---
+
+## Support
+
+For issues, questions, or contributions:
+- GitHub Issues: [Sockudo Issues](https://github.com/Cendars/sockudo-cendars/issues)
+- Pusher-JS Issues: [Pusher-JS Issues](https://github.com/Cendars/sockudo-js/issues)