@signaltree/realtime

Real-time data synchronization enhancers for SignalTree. Provides seamless integration with Supabase Realtime, with a generic adapter pattern for Firebase and custom WebSocket implementations.

Installation

``bash
npm install @signaltree/realtime @supabase/supabase-js


or


pnpm add @signaltree/realtime @supabase/supabase-js
`

Quick Start

`typescript
import { signalTree, entityMap } from '@signaltree/core';
import { supabaseRealtime } from '@signaltree/realtime/supabase';
import { createClient } from '@supabase/supabase-js';

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);

interface Listing {
id: number;
title: string;
price: number;
status: 'active' | 'sold' | 'draft';
}

// Create tree with realtime sync
const tree = signalTree({
listings: entityMap(),
}).with(
supabaseRealtime(supabase, {
listings: {
table: 'listings',
event: '*', // Listen for INSERT, UPDATE, DELETE
},
})
);

// EntityMaps automatically sync with the database!
// When someone inserts a listing, it appears in tree.$.listings.all()
`

Features

$3

The realtime enhancer maps database events to entityMap operations:

| Database Event | EntityMap Operation |
| -------------- | ------------------- |
| INSERT | upsertOne() |
| UPDATE | upsertOne() |
| DELETE | removeOne() |

$3

Access reactive connection state:

`typescript
// Check connection status
effect(() => {
if (tree.realtime.connection.isConnected()) {
console.log('Connected to realtime!');
}
});

// Monitor errors
effect(() => {
const error = tree.realtime.connection.error();
if (error) {
console.error('Connection error:', error);
}
});

// Check reconnection attempts
effect(() => {
const attempts = tree.realtime.connection.reconnectAttempts();
console.log(Reconnect attempt: ${attempts});
});
`

$3

`typescript
// Manually disconnect
tree.realtime.disconnect();

// Reconnect
tree.realtime.reconnect();

// Dynamic subscriptions
const cleanup = tree.realtime.subscribe('newPath', {
table: 'some_table',
event: 'INSERT',
});

// Later: unsubscribe
cleanup();
// or
tree.realtime.unsubscribe('newPath');
`

$3

Use Supabase PostgREST filters:

`typescript
.with(supabaseRealtime(supabase, {
activeListings: {
table: 'listings',
event: '*',
filter: 'status=eq.active'
},
myListings: {
table: 'listings',
event: '*',
filter: user_id=eq.${currentUserId}
},
recentMessages: {
table: 'messages',
event: 'INSERT',
filter: created_at=gt.${oneDayAgo.toISOString()}
}
}))
`

$3

Transform snake_case database fields to camelCase:

`typescript
interface Listing {
id: number;
createdAt: Date;
updatedAt: Date;
}

.with(supabaseRealtime(supabase, {
listings: {
table: 'listings',
event: '*',
transform: (row: any) => ({
id: row.id,
createdAt: new Date(row.created_at),
updatedAt: new Date(row.updated_at)
})
}
}))
`

$3

If your entity ID field isn't id:

`typescript
interface Item {
itemCode: string;
name: string;
}

.with(supabaseRealtime(supabase, {
items: {
table: 'items',
event: '*',
selectId: (item: Item) => item.itemCode
}
}))
`

Configuration Options

`typescript
supabaseRealtime(supabase, config, {
// Auto-reconnect on disconnect (default: true)
autoReconnect: true,

// Initial reconnect delay in ms (default: 1000)
// Uses exponential backoff
reconnectDelay: 1000,

// Max reconnect attempts (default: 10)
maxReconnectAttempts: 10,

// Log events in dev mode (default: true in dev)
debug: true,
});
`

Custom Adapters

Create adapters for other realtime providers:

`typescript
import { createRealtimeEnhancer, RealtimeAdapter } from '@signaltree/realtime';

const customAdapter: RealtimeAdapter = {
async connect() {
// Connect to your WebSocket server
},

disconnect() {
// Clean up connections
},

subscribe(config, callback) {
// Set up subscription
// Call callback(event) when data changes
return () => {
// Cleanup function
};
},

isConnected() {
return true; // Return connection state
},

onConnectionChange(callback) {
// Set up connection state listener
return () => {
// Cleanup
};
}
};

const tree = signalTree({ ... })
.with(createRealtimeEnhancer(customAdapter, config));
`

TypeScript

Full type inference is provided:

`typescript
// The tree type includes the realtime property
const tree = signalTree({
listings: entityMap()
}).with(supabaseRealtime(supabase, { ... }));

// Fully typed
tree.realtime.connection.isConnected(); // Signal
tree.realtime.connection.error(); // Signal
tree.$.listings.all(); // Signal
``

Requirements

- Angular 20+
- @signaltree/core 7.0+
- @supabase/supabase-js 2.0+ (for Supabase integration)

License

MIT