signaltree-realtime

Using @signaltree/realtime

Use when an Angular app holds entity collections in entityMap slices and the source of truth emits DB change events (Supabase Realtime, Firebase, custom WebSocket). Eliminates manual subscribe → map → upsertOne/removeOne → reconnect dance. For request/response CRUD or static data, skip it.

Don't apply in SSR — guard with isPlatformBrowser() or initialize in a client-only provider.

Install:

npm install @signaltree/core @signaltree/realtime
# Supabase adapter:
npm install @supabase/supabase-js

Peer: @angular/core ^20, @signaltree/core ^9. @supabase/supabase-js ^2 optional — install only for Supabase adapter.

Supabase:

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

interface Listing {
  id: number;
  title: string;
  status: string;
}
interface Message {
  id: string;
  text: string;
}

const supabase = createClient(import.meta.env['VITE_SUPABASE_URL'], import.meta.env['VITE_SUPABASE_ANON_KEY']);

const tree = signalTree({
  listings: entityMap<Listing, number>(),
  messages: entityMap<Message, string>(),
}).with(
  supabaseRealtime(supabase, {
    listings: { table: 'listings', event: '*', filter: 'status=eq.active' },
    messages: { table: 'messages', event: 'INSERT' },
  })
);

Entity mutation rules: INSERT/UPDATE → upsertOne(entity, { selectId }). DELETE → removeOne(selectId(old)). selectId defaults to (entity) => entity.id; override in subscription config for non-id PKs.

event values: 'INSERT' | 'UPDATE' | 'DELETE' | '*'. '*' = all three.

Connection state — tree.realtime.connection.status is a signal of 'DISCONNECTED' | 'CONNECTING' | 'CONNECTED' | 'RECONNECTING' | 'ERROR':

effect(() => {
  const status = tree.realtime.connection.status();
  if (status === 'ERROR') console.warn('Realtime error:', tree.realtime.connection.error());
});

const isLive = tree.realtime.connection.isConnected; // signal<boolean>

Transform rows (e.g., snake_case → camelCase):

supabaseRealtime(supabase, {
  listings: {
    table: 'listings',
    event: '*',
    transform: (row): Listing => ({ id: row['id'] as number, title: row['title'] as string /* ...more fields */ }),
  },
});

Custom adapter (non-Supabase):

import { signalTree, entityMap } from '@signaltree/core';
import { realtime } from '@signaltree/realtime';

interface Todo {
  id: string;
  title: string;
}
type RealtimeAdapter = Parameters<typeof realtime>[0];

const myAdapter: RealtimeAdapter = {
  async connect() {
    /* open socket */
  },
  disconnect() {
    /* close socket */
  },
  subscribe(_config, _callback) {
    return () => {
      /* cleanup */
    };
  },
  isConnected() {
    return true;
  },
  onConnectionChange(_cb) {
    return () => {
      /* cleanup */
    };
  },
};

const tree = signalTree({ todos: entityMap<Todo, string>() }).with(realtime(myAdapter, { todos: { table: 'todos', event: '*' } }));

Dynamic subscriptions (add after initial connect):

const cleanup = tree.realtime.subscribe('newPath', config);
tree.realtime.unsubscribe('newPath');
cleanup(); // or via returned CleanupFn

tree.realtime.reconnect() — force disconnect → fresh connect, resets reconnectAttempts to 0. Use after long background wake-up.

Reconnect options (on realtime): autoReconnect (default true), reconnectDelay (default 1000ms, exponential backoff), maxReconnectAttempts (default 10).

Gotchas:

• Only entityMap slices auto-sync. Plain signals or object paths log a dev warning and are ignored.
• Subscriptions keyed by tree path, not table. Same table → two paths = two independent channels. Two subscriptions at same tree path: second overwrites first.
• Supabase filter is passed verbatim to Supabase Realtime — not a JS filter. Use transform for JS-level cross-row filtering.
• Supabase adapter fires connection callback only after first SUBSCRIBED status. Brief CONNECTING window before data is normal.
• reconnectAttempts() climbing indefinitely = server rejecting connection (check Postgres publication or RLS).
• entityMap must exist at configured path at enhancer-apply time. Dynamic paths: use tree.realtime.subscribe(path, config) once the slice exists.