@signaltree/realtime 7.3.0

package/README.md

@@ -0,0 +1,255 @@
+# @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<Listing, number>(),
+}).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
+
+### Automatic EntityMap Sync
+
+The realtime enhancer maps database events to entityMap operations:
+
+| Database Event | EntityMap Operation |
+| -------------- | ------------------- |
+| INSERT         | `upsertOne()`       |
+| UPDATE         | `upsertOne()`       |
+| DELETE         | `removeOne()`       |
+
+### Connection State
+
+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}`);
+});
+```
+
+### Manual Control
+
+```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');
+```
+
+### Filtering
+
+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()}`
+  }
+}))
+```
+
+### Data Transformation
+
+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)
+    })
+  }
+}))
+```
+
+### Custom ID Selection
+
+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<Listing, number>()
+}).with(supabaseRealtime(supabase, { ... }));
+
+// Fully typed
+tree.realtime.connection.isConnected();  // Signal<boolean>
+tree.realtime.connection.error();        // Signal<string | null>
+tree.$.listings.all();                   // Signal<Listing[]>
+```
+
+## Requirements
+
+- Angular 20+
+- @signaltree/core 7.0+
+- @supabase/supabase-js 2.0+ (for Supabase integration)
+
+## License
+
+MIT

package/dist/connection-state.js

@@ -0,0 +1,46 @@
+import { signal, computed } from '@angular/core';
+import { ConnectionStatus } from './types.js';
+
+/**
+ * Creates a writable connection state for internal use.
+ */
+function createConnectionState() {
+  const statusSignal = signal(ConnectionStatus.Disconnected);
+  const errorSignal = signal(null);
+  const lastConnectedAtSignal = signal(null);
+  const reconnectAttemptsSignal = signal(0);
+  const isConnected = computed(() => statusSignal() === ConnectionStatus.Connected);
+  return {
+    status: statusSignal.asReadonly(),
+    error: errorSignal.asReadonly(),
+    isConnected,
+    lastConnectedAt: lastConnectedAtSignal.asReadonly(),
+    reconnectAttempts: reconnectAttemptsSignal.asReadonly(),
+    // Internal setters
+    _setStatus: status => {
+      statusSignal.set(status);
+      if (status === ConnectionStatus.Connected) {
+        lastConnectedAtSignal.set(new Date());
+        reconnectAttemptsSignal.set(0);
+        errorSignal.set(null);
+      }
+    },
+    _setError: error => {
+      errorSignal.set(error);
+      if (error) {
+        statusSignal.set(ConnectionStatus.Error);
+      }
+    },
+    _incrementReconnectAttempts: () => {
+      reconnectAttemptsSignal.update(n => n + 1);
+    },
+    _resetReconnectAttempts: () => {
+      reconnectAttemptsSignal.set(0);
+    },
+    _setLastConnectedAt: date => {
+      lastConnectedAtSignal.set(date);
+    }
+  };
+}
+
+export { ConnectionStatus, createConnectionState };

package/dist/create-realtime-enhancer.js

@@ -0,0 +1,236 @@
+import { createConnectionState } from './connection-state.js';
+import { ConnectionStatus } from './types.js';
+
+/**
+ * Creates a generic real-time enhancer that works with any RealtimeAdapter.
+ *
+ * This is the base enhancer used by provider-specific enhancers like
+ * `supabaseRealtime` and `firebaseRealtime`.
+ *
+ * @param adapter - The real-time adapter implementation
+ * @param config - Configuration mapping tree paths to subscriptions
+ * @param options - Enhancer options
+ * @returns A tree enhancer that syncs entityMaps with real-time data
+ *
+ * @example
+ * ```typescript
+ * // Custom WebSocket adapter
+ * const myAdapter: RealtimeAdapter = {
+ *   connect: async () => { ... },
+ *   disconnect: () => { ... },
+ *   subscribe: (config, callback) => { ... },
+ *   isConnected: () => { ... },
+ *   onConnectionChange: (callback) => { ... }
+ * };
+ *
+ * const tree = signalTree({ ... })
+ *   .with(createRealtimeEnhancer(myAdapter, config));
+ * ```
+ */
+function createRealtimeEnhancer(adapter, config, options = {}) {
+  const {
+    autoReconnect = true,
+    reconnectDelay = 1000,
+    maxReconnectAttempts = 10,
+    debug = typeof ngDevMode === 'undefined' || ngDevMode
+  } = options;
+  return tree => {
+    const connection = createConnectionState();
+    const subscriptions = new Map();
+    let connectionCleanup = null;
+    let reconnectTimeout = null;
+    let isManuallyDisconnected = false;
+    const log = (message, ...args) => {
+      if (debug) {
+        console.log(`[SignalTree Realtime] ${message}`, ...args);
+      }
+    };
+    // Handle connection state changes
+    const handleConnectionChange = (connected, error) => {
+      if (connected) {
+        connection._setStatus(ConnectionStatus.Connected);
+        log('Connected to real-time service');
+      } else if (error) {
+        connection._setError(error.message);
+        log('Connection error:', error.message);
+        if (autoReconnect && !isManuallyDisconnected) {
+          scheduleReconnect();
+        }
+      } else {
+        connection._setStatus(ConnectionStatus.Disconnected);
+        log('Disconnected from real-time service');
+        if (autoReconnect && !isManuallyDisconnected) {
+          scheduleReconnect();
+        }
+      }
+    };
+    // Schedule a reconnection attempt
+    const scheduleReconnect = () => {
+      const attempts = connection.reconnectAttempts();
+      if (attempts >= maxReconnectAttempts) {
+        log(`Max reconnect attempts (${maxReconnectAttempts}) reached`);
+        connection._setError('Max reconnect attempts reached');
+        return;
+      }
+      const delay = reconnectDelay * Math.pow(2, Math.min(attempts, 5)); // Exponential backoff, capped
+      connection._setStatus(ConnectionStatus.Reconnecting);
+      connection._incrementReconnectAttempts();
+      log(`Scheduling reconnect attempt ${attempts + 1} in ${delay}ms`);
+      reconnectTimeout = setTimeout(async () => {
+        try {
+          await connect();
+        } catch {
+          // handleConnectionChange will schedule next attempt
+        }
+      }, delay);
+    };
+    // Connect to real-time service
+    const connect = async () => {
+      connection._setStatus(ConnectionStatus.Connecting);
+      isManuallyDisconnected = false;
+      try {
+        // Set up connection state listener
+        connectionCleanup = adapter.onConnectionChange(handleConnectionChange);
+        await adapter.connect();
+        // Subscribe to all configured paths
+        for (const [path, subConfig] of Object.entries(config)) {
+          if (subConfig) {
+            subscribeToPath(path, subConfig);
+          }
+        }
+        connection._setStatus(ConnectionStatus.Connected);
+      } catch (error) {
+        connection._setError(error.message);
+        throw error;
+      }
+    };
+    // Subscribe to a specific path
+    const subscribeToPath = (path, subConfig) => {
+      // Get the entity signal at this path
+      const pathParts = path.split('.');
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let entitySignal = tree.$;
+      for (const part of pathParts) {
+        entitySignal = entitySignal?.[part];
+      }
+      if (!entitySignal) {
+        log(`Warning: No signal found at path "${path}"`);
+        return () => {
+          /* noop */
+        };
+      }
+      // Check if it's an entityMap
+      const hasUpsertOne = typeof entitySignal.upsertOne === 'function';
+      const hasRemoveOne = typeof entitySignal.removeOne === 'function';
+      if (!hasUpsertOne || !hasRemoveOne) {
+        log(`Warning: Signal at "${path}" is not an entityMap. Realtime sync requires entityMap.`);
+        return () => {
+          /* noop */
+        };
+      }
+      const selectId = subConfig.selectId ?? (entity => entity.id);
+      const callback = event => {
+        const entity = subConfig.transform ? subConfig.transform(event.new ?? event.old) : event.new ?? event.old;
+        if (!entity) {
+          log(`Warning: Received event without entity data`, event);
+          return;
+        }
+        switch (event.eventType) {
+          case 'INSERT':
+          case 'UPDATE':
+            if (event.new) {
+              const transformed = subConfig.transform ? subConfig.transform(event.new) : event.new;
+              entitySignal.upsertOne(transformed, {
+                selectId
+              });
+              log(`${event.eventType} on ${path}:`, transformed);
+            }
+            break;
+          case 'DELETE':
+            if (event.old) {
+              const id = selectId(event.old);
+              entitySignal.removeOne(id);
+              log(`DELETE on ${path}: id=${id}`);
+            }
+            break;
+          default:
+            log(`Unknown event type: ${event.eventType}`);
+        }
+      };
+      const cleanup = adapter.subscribe(subConfig, callback);
+      subscriptions.set(path, cleanup);
+      log(`Subscribed to "${subConfig.table}" for path "${path}"`);
+      return cleanup;
+    };
+    // Disconnect from real-time service
+    const disconnect = () => {
+      isManuallyDisconnected = true;
+      if (reconnectTimeout) {
+        clearTimeout(reconnectTimeout);
+        reconnectTimeout = null;
+      }
+      // Clean up all subscriptions
+      for (const cleanup of subscriptions.values()) {
+        cleanup();
+      }
+      subscriptions.clear();
+      // Clean up connection listener
+      if (connectionCleanup) {
+        connectionCleanup();
+        connectionCleanup = null;
+      }
+      adapter.disconnect();
+      connection._setStatus(ConnectionStatus.Disconnected);
+      log('Disconnected');
+    };
+    // Manual reconnect
+    const reconnect = async () => {
+      disconnect();
+      connection._resetReconnectAttempts();
+      await connect();
+    };
+    // Dynamic subscription
+    const subscribe = (path, subConfig) => {
+      if (!adapter.isConnected()) {
+        log(`Warning: Cannot subscribe while disconnected`);
+        return () => {
+          /* noop */
+        };
+      }
+      return subscribeToPath(path, subConfig);
+    };
+    // Unsubscribe from a path
+    const unsubscribe = path => {
+      const cleanup = subscriptions.get(path);
+      if (cleanup) {
+        cleanup();
+        subscriptions.delete(path);
+        log(`Unsubscribed from "${path}"`);
+      }
+    };
+    // Auto-connect on enhancer application
+    queueMicrotask(() => {
+      connect().catch(error => {
+        log('Initial connection failed:', error);
+      });
+    });
+    // Return enhanced tree with realtime control
+    return Object.assign(tree, {
+      realtime: {
+        connection: {
+          status: connection.status,
+          error: connection.error,
+          isConnected: connection.isConnected,
+          lastConnectedAt: connection.lastConnectedAt,
+          reconnectAttempts: connection.reconnectAttempts
+        },
+        reconnect,
+        disconnect,
+        subscribe,
+        unsubscribe
+      }
+    });
+  };
+}
+
+export { createRealtimeEnhancer };

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createConnectionState, ConnectionStatus } from './connection-state.js';
+export { createRealtimeEnhancer } from './create-realtime-enhancer.js';
+export * from './types.js';

package/dist/supabase/index.js

@@ -0,0 +1 @@
+export { createSupabaseAdapter, supabaseRealtime } from './supabase-realtime.js';

package/dist/supabase/supabase-realtime.js

@@ -0,0 +1,224 @@
+import { createRealtimeEnhancer } from '../create-realtime-enhancer.js';
+
+/**
+ * Converts Supabase event type to our normalized type.
+ */
+function normalizeEventType(type) {
+  switch (type.toUpperCase()) {
+    case 'INSERT':
+      return 'INSERT';
+    case 'UPDATE':
+      return 'UPDATE';
+    case 'DELETE':
+      return 'DELETE';
+    default:
+      return '*';
+  }
+}
+/**
+ * Creates a Supabase realtime adapter.
+ *
+ * @param client - Supabase client instance
+ * @returns RealtimeAdapter for use with createRealtimeEnhancer
+ */
+function createSupabaseAdapter(client) {
+  let mainChannel = null;
+  const channels = new Map();
+  let connectionCallback = null;
+  return {
+    async connect() {
+      // Create a presence channel to track connection state
+      mainChannel = client.channel('signaltree-presence');
+      mainChannel.on('presence', {
+        event: 'sync'
+      }, () => {
+        connectionCallback?.(true);
+      }).subscribe((status, err) => {
+        if (status === 'SUBSCRIBED') {
+          connectionCallback?.(true);
+        } else if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT') {
+          connectionCallback?.(false, err ?? new Error(`Channel error: ${status}`));
+        } else if (status === 'CLOSED') {
+          connectionCallback?.(false);
+        }
+      });
+    },
+    disconnect() {
+      // Unsubscribe from all channels
+      for (const channel of channels.values()) {
+        client.removeChannel(channel);
+      }
+      channels.clear();
+      if (mainChannel) {
+        client.removeChannel(mainChannel);
+        mainChannel = null;
+      }
+    },
+    subscribe(config, callback) {
+      const {
+        table,
+        event,
+        filter,
+        schema = 'public'
+      } = config;
+      // Build channel name (unique per subscription)
+      const channelName = `signaltree:${schema}:${table}:${filter ?? 'all'}`;
+      // Check if we already have this channel
+      let channel = channels.get(channelName);
+      if (!channel) {
+        channel = client.channel(channelName);
+        channels.set(channelName, channel);
+      }
+      // Build the filter config
+      const filterConfig = {
+        event: event,
+        schema,
+        table
+      };
+      if (filter) {
+        filterConfig.filter = filter;
+      }
+      // Subscribe to postgres changes
+      // Use type assertion to work around strict Supabase generic constraints
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      channel.on('postgres_changes', filterConfig, payload => {
+        const realtimeEvent = {
+          eventType: normalizeEventType(payload.eventType),
+          new: payload.new,
+          old: payload.old,
+          table: payload.table,
+          schema: payload.schema,
+          timestamp: new Date()
+        };
+        callback(realtimeEvent);
+      });
+      // Subscribe to the channel if not already subscribed
+      if (channel.state !== 'joined' && channel.state !== 'joining') {
+        channel.subscribe();
+      }
+      // Return cleanup function
+      return () => {
+        // Note: Supabase doesn't support removing individual listeners,
+        // so we just remove the entire channel
+        const ch = channels.get(channelName);
+        if (ch) {
+          client.removeChannel(ch);
+          channels.delete(channelName);
+        }
+      };
+    },
+    isConnected() {
+      return mainChannel?.state === 'joined';
+    },
+    onConnectionChange(callback) {
+      connectionCallback = callback;
+      return () => {
+        connectionCallback = null;
+      };
+    }
+  };
+}
+/**
+ * Creates a Supabase realtime enhancer for SignalTree.
+ *
+ * This enhancer automatically syncs entityMaps in your tree with
+ * Supabase Realtime PostgreSQL changes.
+ *
+ * @param client - Supabase client instance
+ * @param config - Configuration mapping tree paths to table subscriptions
+ * @param options - Enhancer options (reconnection, logging, etc.)
+ * @returns A tree enhancer
+ *
+ * @example
+ * ```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);
+ *
+ * // Define your database types
+ * interface Listing {
+ *   id: number;
+ *   title: string;
+ *   price: number;
+ *   created_at: string;
+ * }
+ *
+ * // Create tree with realtime sync
+ * const tree = signalTree({
+ *   listings: entityMap<Listing, number>()
+ * })
+ * .with(supabaseRealtime(supabase, {
+ *   listings: {
+ *     table: 'listings',
+ *     event: '*',  // INSERT, UPDATE, DELETE
+ *     // Optional: filter to only active listings
+ *     // filter: 'status=eq.active'
+ *   }
+ * }));
+ *
+ * // The tree now has realtime property for connection control
+ * effect(() => {
+ *   if (tree.realtime.connection.isConnected()) {
+ *     console.log('Connected to Supabase Realtime!');
+ *   }
+ * });
+ *
+ * // EntityMap automatically updates when database changes
+ * // No manual refresh needed!
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With snake_case to camelCase transformation
+ * const tree = signalTree({
+ *   listings: entityMap<Listing, number>()
+ * })
+ * .with(supabaseRealtime(supabase, {
+ *   listings: {
+ *     table: 'listings',
+ *     event: '*',
+ *     transform: (row: any) => ({
+ *       id: row.id,
+ *       title: row.title,
+ *       createdAt: new Date(row.created_at),
+ *       updatedAt: new Date(row.updated_at)
+ *     })
+ *   }
+ * }));
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multiple tables with different filters
+ * const tree = signalTree({
+ *   myListings: entityMap<Listing, number>(),
+ *   allListings: entityMap<Listing, number>(),
+ *   messages: entityMap<Message, string>()
+ * })
+ * .with(supabaseRealtime(supabase, {
+ *   myListings: {
+ *     table: 'listings',
+ *     event: '*',
+ *     filter: `user_id=eq.${currentUserId}`
+ *   },
+ *   allListings: {
+ *     table: 'listings',
+ *     event: '*',
+ *     filter: 'status=eq.active'
+ *   },
+ *   messages: {
+ *     table: 'messages',
+ *     event: 'INSERT',  // Only new messages
+ *     filter: `chat_room_id=eq.${roomId}`
+ *   }
+ * }));
+ * ```
+ */
+function supabaseRealtime(client, config, options = {}) {
+  const adapter = createSupabaseAdapter(client);
+  return createRealtimeEnhancer(adapter, config, options);
+}
+
+export { createSupabaseAdapter, supabaseRealtime };

package/dist/types.js

@@ -0,0 +1,18 @@
+/**
+ * Connection status enum for real-time connections.
+ */
+var ConnectionStatus;
+(function (ConnectionStatus) {
+  /** Initial state, not yet connected */
+  ConnectionStatus["Disconnected"] = "DISCONNECTED";
+  /** Attempting to connect */
+  ConnectionStatus["Connecting"] = "CONNECTING";
+  /** Successfully connected */
+  ConnectionStatus["Connected"] = "CONNECTED";
+  /** Connection error occurred */
+  ConnectionStatus["Error"] = "ERROR";
+  /** Reconnecting after disconnect */
+  ConnectionStatus["Reconnecting"] = "RECONNECTING";
+})(ConnectionStatus || (ConnectionStatus = {}));
+
+export { ConnectionStatus };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@signaltree/realtime",
+  "version": "7.3.0",
+  "description": "Real-time data synchronization enhancers for SignalTree - Supabase, Firebase, and WebSocket support",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./index.esm.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./supabase": {
+      "types": "./src/supabase/index.d.ts",
+      "import": "./dist/supabase/index.js",
+      "default": "./dist/supabase/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@angular/core": "^20.0.0",
+    "@signaltree/core": "^7.0.0",
+    "@supabase/supabase-js": "^2.0.0",
+    "tslib": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@supabase/supabase-js": {
+      "optional": true
+    },
+    "firebase": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@supabase/supabase-js": "^2.49.0",
+    "vitest": "^3.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**/*.js",
+    "src/**/*.d.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "angular",
+    "signals",
+    "state-management",
+    "realtime",
+    "supabase",
+    "firebase",
+    "websocket"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JBorgia/signaltree.git",
+    "directory": "packages/realtime"
+  },
+  "bugs": {
+    "url": "https://github.com/JBorgia/signaltree/issues"
+  },
+  "homepage": "https://signaltree.dev"
+}

package/src/connection-state.d.ts

@@ -0,0 +1,39 @@
+import { ConnectionState, ConnectionStatus } from './types';
+/**
+ * Re-export ConnectionStatus for convenience
+ */
+export { ConnectionStatus } from './types';
+/**
+ * Creates a reactive connection state object.
+ *
+ * @returns Connection state with signals for status, error, etc.
+ *
+ * @example
+ * ```typescript
+ * const connection = createConnectionState();
+ *
+ * // Update connection status
+ * connection._setStatus(ConnectionStatus.Connected);
+ *
+ * // Read current status
+ * effect(() => {
+ *   console.log('Connected:', connection.isConnected());
+ * });
+ * ```
+ */
+export interface WritableConnectionState extends ConnectionState {
+    /** @internal Set the connection status */
+    _setStatus: (status: ConnectionStatus) => void;
+    /** @internal Set the error message */
+    _setError: (error: string | null) => void;
+    /** @internal Increment reconnect attempts */
+    _incrementReconnectAttempts: () => void;
+    /** @internal Reset reconnect attempts */
+    _resetReconnectAttempts: () => void;
+    /** @internal Set last connected time */
+    _setLastConnectedAt: (date: Date | null) => void;
+}
+/**
+ * Creates a writable connection state for internal use.
+ */
+export declare function createConnectionState(): WritableConnectionState;

package/src/create-realtime-enhancer.d.ts

@@ -0,0 +1,49 @@
+import { CleanupFn, RealtimeConfig, RealtimeEnhancerOptions, RealtimeEnhancerResult, RealtimeEvent, RealtimeSubscription } from './types';
+import type { Enhancer } from '@signaltree/core';
+/**
+ * Adapter interface for different real-time backends.
+ *
+ * Implement this interface to add support for new real-time providers
+ * (Supabase, Firebase, custom WebSocket, etc.).
+ */
+export interface RealtimeAdapter {
+    /** Connect to the real-time service */
+    connect(): Promise<void>;
+    /** Disconnect from the real-time service */
+    disconnect(): void;
+    /** Subscribe to a table/channel */
+    subscribe<T>(config: RealtimeSubscription<T>, callback: (event: RealtimeEvent<T>) => void): CleanupFn;
+    /** Check if currently connected */
+    isConnected(): boolean;
+    /** Set a callback for connection state changes */
+    onConnectionChange(callback: (connected: boolean, error?: Error) => void): CleanupFn;
+}
+/**
+ * Creates a generic real-time enhancer that works with any RealtimeAdapter.
+ *
+ * This is the base enhancer used by provider-specific enhancers like
+ * `supabaseRealtime` and `firebaseRealtime`.
+ *
+ * @param adapter - The real-time adapter implementation
+ * @param config - Configuration mapping tree paths to subscriptions
+ * @param options - Enhancer options
+ * @returns A tree enhancer that syncs entityMaps with real-time data
+ *
+ * @example
+ * ```typescript
+ * // Custom WebSocket adapter
+ * const myAdapter: RealtimeAdapter = {
+ *   connect: async () => { ... },
+ *   disconnect: () => { ... },
+ *   subscribe: (config, callback) => { ... },
+ *   isConnected: () => { ... },
+ *   onConnectionChange: (callback) => { ... }
+ * };
+ *
+ * const tree = signalTree({ ... })
+ *   .with(createRealtimeEnhancer(myAdapter, config));
+ * ```
+ */
+export declare function createRealtimeEnhancer<TState extends object>(adapter: RealtimeAdapter, config: RealtimeConfig<TState>, options?: RealtimeEnhancerOptions): Enhancer<{
+    realtime: RealtimeEnhancerResult;
+}>;

package/src/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @signaltree/realtime
+ *
+ * Real-time data synchronization enhancers for SignalTree.
+ * Provides seamless integration with Supabase, Firebase, and generic WebSocket.
+ *
+ * @example
+ * ```typescript
+ * import { signalTree } from '@signaltree/core';
+ * import { supabaseRealtime } from '@signaltree/realtime/supabase';
+ * import { createClient } from '@supabase/supabase-js';
+ *
+ * const supabase = createClient(SUPABASE_URL, SUPABASE_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'
+ *   }
+ * }));
+ *
+ * // EntityMaps automatically sync with database!
+ * // INSERT -> upsertOne
+ * // UPDATE -> upsertOne
+ * // DELETE -> removeOne
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { type RealtimeConfig, type RealtimeSubscription, type RealtimeEvent, type RealtimeEnhancerOptions, type ConnectionState, } from './types';
+export { createConnectionState, ConnectionStatus } from './connection-state';
+export { createRealtimeEnhancer } from './create-realtime-enhancer';

package/src/supabase/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Supabase Real-time integration for SignalTree.
+ *
+ * @example
+ * ```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';
+ * }
+ *
+ * const tree = signalTree({
+ *   listings: entityMap<Listing, number>(),
+ *   activeListings: entityMap<Listing, number>()
+ * })
+ * .with(supabaseRealtime(supabase, {
+ *   listings: {
+ *     table: 'listings',
+ *     event: '*'
+ *   },
+ *   activeListings: {
+ *     table: 'listings',
+ *     event: '*',
+ *     filter: 'status=eq.active'
+ *   }
+ * }));
+ *
+ * // Access connection state
+ * console.log(tree.realtime.connection.isConnected());
+ *
+ * // Manually reconnect if needed
+ * tree.realtime.reconnect();
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { supabaseRealtime, createSupabaseAdapter } from './supabase-realtime';
+export type { SupabaseRealtimeConfig, SupabaseSubscriptionConfig, } from './supabase-realtime';

package/src/supabase/supabase-realtime.d.ts

@@ -0,0 +1,125 @@
+import { RealtimeAdapter } from '../create-realtime-enhancer';
+import { RealtimeEnhancerOptions, RealtimeEnhancerResult, RealtimeSubscription } from '../types';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Enhancer } from '@signaltree/core';
+/**
+ * Supabase-specific subscription configuration.
+ */
+export interface SupabaseSubscriptionConfig<T = unknown> extends RealtimeSubscription<T> {
+    /** PostgreSQL schema (default: 'public') */
+    schema?: string;
+}
+/**
+ * Configuration for Supabase realtime subscriptions.
+ */
+export type SupabaseRealtimeConfig<TState> = {
+    [K in keyof TState]?: SupabaseSubscriptionConfig;
+};
+/**
+ * Creates a Supabase realtime adapter.
+ *
+ * @param client - Supabase client instance
+ * @returns RealtimeAdapter for use with createRealtimeEnhancer
+ */
+export declare function createSupabaseAdapter(client: SupabaseClient): RealtimeAdapter;
+/**
+ * Creates a Supabase realtime enhancer for SignalTree.
+ *
+ * This enhancer automatically syncs entityMaps in your tree with
+ * Supabase Realtime PostgreSQL changes.
+ *
+ * @param client - Supabase client instance
+ * @param config - Configuration mapping tree paths to table subscriptions
+ * @param options - Enhancer options (reconnection, logging, etc.)
+ * @returns A tree enhancer
+ *
+ * @example
+ * ```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);
+ *
+ * // Define your database types
+ * interface Listing {
+ *   id: number;
+ *   title: string;
+ *   price: number;
+ *   created_at: string;
+ * }
+ *
+ * // Create tree with realtime sync
+ * const tree = signalTree({
+ *   listings: entityMap<Listing, number>()
+ * })
+ * .with(supabaseRealtime(supabase, {
+ *   listings: {
+ *     table: 'listings',
+ *     event: '*',  // INSERT, UPDATE, DELETE
+ *     // Optional: filter to only active listings
+ *     // filter: 'status=eq.active'
+ *   }
+ * }));
+ *
+ * // The tree now has realtime property for connection control
+ * effect(() => {
+ *   if (tree.realtime.connection.isConnected()) {
+ *     console.log('Connected to Supabase Realtime!');
+ *   }
+ * });
+ *
+ * // EntityMap automatically updates when database changes
+ * // No manual refresh needed!
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With snake_case to camelCase transformation
+ * const tree = signalTree({
+ *   listings: entityMap<Listing, number>()
+ * })
+ * .with(supabaseRealtime(supabase, {
+ *   listings: {
+ *     table: 'listings',
+ *     event: '*',
+ *     transform: (row: any) => ({
+ *       id: row.id,
+ *       title: row.title,
+ *       createdAt: new Date(row.created_at),
+ *       updatedAt: new Date(row.updated_at)
+ *     })
+ *   }
+ * }));
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multiple tables with different filters
+ * const tree = signalTree({
+ *   myListings: entityMap<Listing, number>(),
+ *   allListings: entityMap<Listing, number>(),
+ *   messages: entityMap<Message, string>()
+ * })
+ * .with(supabaseRealtime(supabase, {
+ *   myListings: {
+ *     table: 'listings',
+ *     event: '*',
+ *     filter: `user_id=eq.${currentUserId}`
+ *   },
+ *   allListings: {
+ *     table: 'listings',
+ *     event: '*',
+ *     filter: 'status=eq.active'
+ *   },
+ *   messages: {
+ *     table: 'messages',
+ *     event: 'INSERT',  // Only new messages
+ *     filter: `chat_room_id=eq.${roomId}`
+ *   }
+ * }));
+ * ```
+ */
+export declare function supabaseRealtime<TState extends object>(client: SupabaseClient, config: SupabaseRealtimeConfig<TState>, options?: RealtimeEnhancerOptions): Enhancer<{
+    realtime: RealtimeEnhancerResult;
+}>;

package/src/types.d.ts

@@ -0,0 +1,111 @@
+import type { Signal } from '@angular/core';
+/**
+ * Connection status enum for real-time connections.
+ */
+export declare enum ConnectionStatus {
+    /** Initial state, not yet connected */
+    Disconnected = "DISCONNECTED",
+    /** Attempting to connect */
+    Connecting = "CONNECTING",
+    /** Successfully connected */
+    Connected = "CONNECTED",
+    /** Connection error occurred */
+    Error = "ERROR",
+    /** Reconnecting after disconnect */
+    Reconnecting = "RECONNECTING"
+}
+/**
+ * Connection state signal interface.
+ */
+export interface ConnectionState {
+    /** Current connection status */
+    status: Signal<ConnectionStatus>;
+    /** Error message if status is ERROR */
+    error: Signal<string | null>;
+    /** Whether currently connected */
+    isConnected: Signal<boolean>;
+    /** Last successful connection time */
+    lastConnectedAt: Signal<Date | null>;
+    /** Number of reconnection attempts */
+    reconnectAttempts: Signal<number>;
+}
+/**
+ * Event types for real-time subscriptions.
+ */
+export type RealtimeEventType = 'INSERT' | 'UPDATE' | 'DELETE' | '*';
+/**
+ * A real-time event payload.
+ */
+export interface RealtimeEvent<T = unknown> {
+    /** Event type */
+    eventType: RealtimeEventType;
+    /** The entity data (new for INSERT/UPDATE, old for DELETE) */
+    new?: T;
+    /** The old entity data (for UPDATE/DELETE) */
+    old?: Partial<T>;
+    /** Table/collection name */
+    table: string;
+    /** Schema (database-specific) */
+    schema?: string;
+    /** Timestamp of the event */
+    timestamp?: Date;
+}
+/**
+ * Configuration for a single entity subscription.
+ */
+export interface RealtimeSubscription<T = unknown> {
+    /** Table/collection name to subscribe to */
+    table: string;
+    /** Event types to listen for */
+    event: RealtimeEventType;
+    /** Optional filter (e.g., 'status=eq.active' for Supabase) */
+    filter?: string;
+    /** Schema name (database-specific) */
+    schema?: string;
+    /** Custom ID selector for the entity */
+    selectId?: (entity: T) => string | number;
+    /**
+     * Transform function to convert database row to entity.
+     * Useful for snake_case to camelCase conversion.
+     */
+    transform?: (row: unknown) => T;
+}
+/**
+ * Configuration for the realtime enhancer.
+ * Keys are entity paths in the tree (e.g., 'listings', 'messages').
+ */
+export type RealtimeConfig<TState = unknown> = {
+    [K in keyof TState]?: RealtimeSubscription;
+};
+/**
+ * Options for the realtime enhancer.
+ */
+export interface RealtimeEnhancerOptions {
+    /** Auto-reconnect on disconnect (default: true) */
+    autoReconnect?: boolean;
+    /** Reconnect delay in ms (default: 1000) */
+    reconnectDelay?: number;
+    /** Max reconnect attempts (default: 10) */
+    maxReconnectAttempts?: number;
+    /** Log events in dev mode (default: true) */
+    debug?: boolean;
+}
+/**
+ * Cleanup function returned by enhancer.
+ */
+export type CleanupFn = () => void;
+/**
+ * Result from the realtime enhancer for accessing connection state.
+ */
+export interface RealtimeEnhancerResult {
+    /** Connection state signals */
+    connection: ConnectionState;
+    /** Manually reconnect */
+    reconnect: () => void;
+    /** Manually disconnect */
+    disconnect: () => void;
+    /** Subscribe to a specific table dynamically */
+    subscribe: <T>(path: string, config: RealtimeSubscription<T>) => CleanupFn;
+    /** Unsubscribe from a specific table */
+    unsubscribe: (path: string) => void;
+}