@cendarsoss/pusher-js 8.4.11

package/TAG_FILTERING_CLIENT.md

@@ -0,0 +1,471 @@
+# Tag Filtering - JavaScript Client Updates
+
+## Overview
+
+The Sockudo JavaScript client has been updated to support publication filtering by tags, allowing clients to subscribe to channels with server-side filters that reduce bandwidth usage by 60-90%.
+
+## What's New
+
+### Filter API
+
+A new `Filter` builder API for creating tag filters programmatically:
+
+```typescript
+import Pusher, { Filter } from 'sockudo-js';
+
+const pusher = new Pusher('app-key', {
+  wsHost: 'localhost',
+  wsPort: 6001
+});
+
+// Subscribe with filter
+const channel = pusher.subscribe(
+  'match:123',
+  Filter.eq('event_type', 'goal')
+);
+```
+
+## Installation
+
+Update to the latest version of sockudo-js:
+
+```bash
+npm install sockudo-js@latest
+# or
+yarn add sockudo-js@latest
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import Pusher, { Filter } from 'sockudo-js';
+
+const pusher = new Pusher('app-key', { /* config */ });
+
+// Simple equality filter
+const channel = pusher.subscribe(
+  'match:123',
+  Filter.eq('event_type', 'goal')
+);
+
+channel.bind('match_event', (data) => {
+  console.log('Goal scored!', data);
+});
+```
+
+### Complex Filters
+
+```typescript
+// Goals OR dangerous shots (xG >= 0.8)
+const filter = Filter.or(
+  Filter.eq('event_type', 'goal'),
+  Filter.and(
+    Filter.eq('event_type', 'shot'),
+    Filter.gte('xG', '0.8')
+  )
+);
+
+const channel = pusher.subscribe('match:123', filter);
+```
+
+## API Reference
+
+### Filter Builder
+
+All filter builder methods return a `FilterNode` object that can be passed to `pusher.subscribe()`.
+
+#### Comparison Operators
+
+```typescript
+// Equality
+Filter.eq(key: string, val: string): FilterNode
+
+// Inequality
+Filter.neq(key: string, val: string): FilterNode
+
+// Set membership
+Filter.in(key: string, vals: string[]): FilterNode
+
+// Set non-membership
+Filter.nin(key: string, vals: string[]): FilterNode
+
+// Key existence
+Filter.exists(key: string): FilterNode
+Filter.notExists(key: string): FilterNode
+
+// String operations
+Filter.startsWith(key: string, val: string): FilterNode
+Filter.endsWith(key: string, val: string): FilterNode
+Filter.contains(key: string, val: string): FilterNode
+
+// Numeric comparisons (values as strings)
+Filter.gt(key: string, val: string): FilterNode
+Filter.gte(key: string, val: string): FilterNode
+Filter.lt(key: string, val: string): FilterNode
+Filter.lte(key: string, val: string): FilterNode
+```
+
+#### Logical Operators
+
+```typescript
+// All children must match
+Filter.and(...nodes: FilterNode[]): FilterNode
+
+// At least one child must match
+Filter.or(...nodes: FilterNode[]): FilterNode
+
+// Negates the child
+Filter.not(node: FilterNode): FilterNode
+```
+
+### Validation
+
+```typescript
+import { validateFilter } from 'sockudo-js';
+
+const filter = Filter.eq('event_type', 'goal');
+const error = validateFilter(filter);
+
+if (error) {
+  console.error('Invalid filter:', error);
+}
+```
+
+### Helper Functions
+
+Pre-built filter patterns for common use cases:
+
+```typescript
+import { FilterExamples } from 'sockudo-js';
+
+// Single event type
+FilterExamples.eventType('goal')
+
+// Multiple event types
+FilterExamples.eventTypes(['goal', 'shot'])
+
+// Numeric range
+FilterExamples.range('xG', '0.5', '0.9')
+
+// Important events pattern
+FilterExamples.importantEvents('0.8')
+```
+
+## Examples
+
+### Football Match Events
+
+```typescript
+// Only goals and penalties
+const filter = Filter.in('event_type', ['goal', 'penalty']);
+const channel = pusher.subscribe('match:123', filter);
+
+channel.bind('match_event', (data) => {
+  console.log('Important event!', data);
+});
+```
+
+### Stock Market
+
+```typescript
+// Only specific tickers above a price
+const filter = Filter.and(
+  Filter.in('ticker', ['GOOGL', 'AAPL', 'MSFT']),
+  Filter.gte('price', '100.00')
+);
+
+const channel = pusher.subscribe('stocks', filter);
+
+channel.bind('price_update', (data) => {
+  console.log('Price update:', data);
+});
+```
+
+### IoT Sensors
+
+```typescript
+// Only critical temperature alerts
+const filter = Filter.and(
+  Filter.eq('sensor_type', 'temperature'),
+  Filter.gt('value', '100')
+);
+
+const channel = pusher.subscribe('sensors', filter);
+
+channel.bind('sensor_reading', (data) => {
+  console.log('Critical temperature!', data);
+});
+```
+
+## TypeScript Support
+
+Full TypeScript definitions are included:
+
+```typescript
+import Pusher, { 
+  Filter, 
+  FilterNode, 
+  validateFilter,
+  FilterExamples 
+} from 'sockudo-js';
+
+const filter: FilterNode = Filter.eq('event_type', 'goal');
+const error: string | null = validateFilter(filter);
+```
+
+## Browser Support
+
+Works in all browsers that support ES5+:
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- IE11+ (with polyfills)
+
+## Node.js Support
+
+```javascript
+const Pusher = require('sockudo-js');
+const { Filter } = Pusher;
+
+const pusher = new Pusher('app-key', { /* config */ });
+
+const filter = Filter.eq('event_type', 'goal');
+const channel = pusher.subscribe('match:123', filter);
+```
+
+## React Native Support
+
+```javascript
+import Pusher, { Filter } from 'sockudo-js/react-native';
+
+const pusher = new Pusher('app-key', { /* config */ });
+
+const filter = Filter.eq('event_type', 'goal');
+const channel = pusher.subscribe('match:123', filter);
+```
+
+## Important Notes
+
+### Server Configuration Required
+
+Tag filtering must be enabled on the server:
+
+```bash
+# Server environment variable
+TAG_FILTERING_ENABLED=true
+```
+
+When disabled on the server:
+- Filters are ignored
+- All messages are delivered
+- No bandwidth savings
+
+### Messages Must Have Tags
+
+Only messages with tags can be filtered:
+
+```javascript
+// Server-side: Message with tags
+{
+  "name": "match_event",
+  "channel": "match:123",
+  "data": "{...}",
+  "tags": {
+    "event_type": "goal"
+  }
+}
+```
+
+Messages without tags won't match any filter.
+
+### All Values are Strings
+
+Tag values are always strings, even for numeric comparisons:
+
+```typescript
+// Correct
+Filter.gt('xG', '0.8')
+
+// Not recommended
+Filter.gt('xG', 0.8)  // Will be converted to string
+```
+
+### Updating Filters
+
+To change a filter, unsubscribe and resubscribe:
+
+```typescript
+// Initial subscription
+let channel = pusher.subscribe('match:123', Filter.eq('event_type', 'goal'));
+
+// Change filter
+pusher.unsubscribe('match:123');
+channel = pusher.subscribe('match:123', Filter.in('event_type', ['goal', 'penalty']));
+```
+
+## Performance Benefits
+
+### Bandwidth Savings
+
+Without filtering:
+```
+Server: 1000 msgs/sec → Client: 1000 msgs/sec (all processed)
+```
+
+With filtering:
+```
+Server: 1000 msgs/sec → Client: 50 msgs/sec (only matching)
+Result: 95% bandwidth saved!
+```
+
+### Mobile Benefits
+
+- Reduced data usage on cellular connections
+- Lower battery drain from less processing
+- Faster UI updates (fewer irrelevant messages)
+
+## Best Practices
+
+### 1. Keep Filters Simple
+
+```typescript
+// Good - simple and fast
+Filter.eq('type', 'goal')
+
+// Good - moderate complexity
+Filter.in('type', ['goal', 'penalty'])
+
+// Avoid - overly complex
+Filter.and(
+  Filter.or(...10 filters...),
+  Filter.or(...10 filters...)
+)
+```
+
+### 2. Use Set Operations
+
+```typescript
+// Good - use 'in' for multiple values
+Filter.in('type', ['goal', 'shot', 'penalty'])
+
+// Less efficient - multiple 'or' conditions
+Filter.or(
+  Filter.eq('type', 'goal'),
+  Filter.eq('type', 'shot'),
+  Filter.eq('type', 'penalty')
+)
+```
+
+### 3. Validate Filters
+
+```typescript
+const filter = buildFilterFromUserInput();
+const error = validateFilter(filter);
+
+if (error) {
+  console.error('Invalid filter:', error);
+  return;
+}
+
+pusher.subscribe(channelName, filter);
+```
+
+### 4. Handle Missing Tags Gracefully
+
+```typescript
+// Messages without tags won't match filters
+// Consider this when designing your data flow
+const filter = Filter.eq('priority', 'high');
+const channel = pusher.subscribe('events', filter);
+
+// Only receives messages with tags.priority === 'high'
+// Messages without tags.priority won't be received
+```
+
+## Troubleshooting
+
+### "Not receiving any messages"
+
+1. Check that tag filtering is enabled on server
+2. Verify messages have tags
+3. Test without filter to confirm channel works
+4. Validate filter syntax
+
+### "Filter not working as expected"
+
+1. All comparisons are case-sensitive
+2. Check tag values match exactly
+3. Numeric operators require numeric strings
+4. Messages without tags won't match any filter
+
+### "TypeScript errors"
+
+Update your type definitions:
+```bash
+npm install @types/sockudo-js@latest
+```
+
+## Migration Guide
+
+### From Standard Pusher Client
+
+If you're using standard Pusher subscriptions:
+
+```typescript
+// Before (no filtering)
+const channel = pusher.subscribe('match:123');
+
+// After (with filtering)
+const channel = pusher.subscribe(
+  'match:123',
+  Filter.eq('event_type', 'goal')
+);
+
+// Backward compatible - still works without filter
+const channel = pusher.subscribe('match:123');
+```
+
+### Gradual Rollout
+
+1. Update client library
+2. Test with filters in development
+3. Enable server-side filtering
+4. Monitor bandwidth savings
+5. Roll out to production
+
+## Files Modified
+
+### Source Files
+- `src/core/pusher.ts` - Added Filter exports
+- `src/core/pusher.js` - Re-export Filter utilities
+- `src/core/channels/channel.ts` - Added tagsFilter property
+- `src/core/channels/filter.ts` - New filter API (342 lines)
+
+### Type Definitions
+- `types/src/core/pusher.d.ts` - Added Filter exports
+- `types/src/core/channels/channel.d.ts` - Added tagsFilter property
+- `types/src/core/channels/filter.d.ts` - New filter type definitions (150 lines)
+
+### Entry Points
+- `index.d.ts` - Added Filter exports for top-level access
+
+## Further Reading
+
+- [Complete Documentation](../../docs/TAG_FILTERING.md)
+- [Quick Start Guide](../../docs/TAG_FILTERING_QUICKSTART.md)
+- [Server Implementation](../../TAG_FILTERING_IMPLEMENTATION.md)
+
+## Support
+
+For issues or questions:
+1. Check the [troubleshooting section](#troubleshooting)
+2. Review the [complete documentation](../../docs/TAG_FILTERING.md)
+3. Open an issue on GitHub
+
+---
+
+**Tag filtering is an opt-in feature that requires server-side configuration.**
+
+Enable it with: `TAG_FILTERING_ENABLED=true`

package/bower.json

@@ -0,0 +1,19 @@
+{
+  "name": "pusher-js",
+  "location": "git://github.com/pusher/pusher-js.git",
+  "description": "Pusher JavaScript library for browsers, React Native, NodeJS and web workers",
+  "keywords": [
+    "pusher",
+    "client",
+    "websocket",
+    "http",
+    "fallback",
+    "isomorphic",
+    "events",
+    "pubsub"
+  ],
+  "licence": "MIT",
+  "authors": ["Pusher <support@pusher.com>"],
+  "main": "./dist/web/pusher.js",
+  "ignore": ["**/*", "!/dist/**/*", "!LICENCE", "!README.markdown", "!bower.json", "!CHANGELOG.markdown"]
+}