@terreno/rtk 0.13.0 → 0.14.0

package/src/sync.ts

@@ -0,0 +1,310 @@
+import {DateTime} from "luxon";
+import {useEffect, useRef} from "react";
+import {useDispatch, useStore} from "react-redux";
+import type {Socket} from "socket.io-client";
+
+import {isWebsocketsDebugEnabled, logSocket} from "./constants";
+import type {RealtimeEvent} from "./realtime";
+
+interface DocumentItem {
+  _id?: string;
+  id?: string;
+  updated?: string;
+  [key: string]: unknown;
+}
+
+interface CacheEntryData {
+  data?: DocumentItem[];
+  _id?: string;
+  id?: string;
+  updated?: string;
+  total?: number;
+  [key: string]: unknown;
+}
+
+interface QueryCacheEntry {
+  status: string;
+  data?: CacheEntryData;
+  endpointName: string;
+  originalArgs: unknown;
+}
+
+interface RtkApiState {
+  queries?: Record<string, QueryCacheEntry>;
+}
+
+// noExplicitAny: RTK Query's Api type requires four generic parameters (BaseQuery, Definitions,
+// ReducerPath, TagTypes) that vary per consumer. A structural interface would lose dispatch
+// compatibility for thunk-returning util methods like updateQueryData.
+interface UseSyncConnectionOptions {
+  /** Socket.io client instance (from useSocketConnection) */
+  socket: Socket | null;
+  /** RTK Query API instance (the enhanced API with tag types) */
+  // biome-ignore lint/suspicious/noExplicitAny: noExplicitAny: RTK Query Api generic requires four app-specific type parameters
+  api: any;
+  /** Tag types to listen for (e.g. ["todos", "users"]) — these should match the collection field in events */
+  tagTypes: string[];
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * Hook that connects WebSocket sync events to RTK Query's cache.
+ *
+ * For **create** events: invalidates cache tags to trigger refetch of list queries.
+ * For **update** events: patches entities in-place in cached queries, falling back to tag invalidation.
+ * For **delete** events: removes entities from cached list queries, falling back to tag invalidation.
+ *
+ * Automatically subscribes to model rooms for each tagType when the socket connects,
+ * so models using `roomStrategy: "model"` will work without additional setup.
+ *
+ * @example
+ * ```typescript
+ * const { socket } = useSocketConnection({ ... });
+ *
+ * useSyncConnection({
+ *   socket,
+ *   api: terrenoApi,
+ *   tagTypes: ['todos', 'users'],
+ * });
+ * ```
+ */
+export const useSyncConnection = ({
+  socket,
+  api,
+  tagTypes,
+  debug = false,
+}: UseSyncConnectionOptions): void => {
+  const dispatch = useDispatch();
+  const store = useStore();
+  const tagTypesRef = useRef(tagTypes);
+  const apiRef = useRef(api);
+  tagTypesRef.current = tagTypes;
+  apiRef.current = api;
+
+  // Auto-subscribe to model rooms for each tagType when socket connects
+  useEffect(() => {
+    if (!socket) {
+      return;
+    }
+
+    const subscribeToModels = (): void => {
+      for (const tag of tagTypesRef.current) {
+        socket.emit("subscribe:model", tag);
+      }
+    };
+
+    // Subscribe on connect and when already connected
+    if (socket.connected) {
+      subscribeToModels();
+    }
+    socket.on("connect", subscribeToModels);
+
+    return (): void => {
+      socket.off("connect", subscribeToModels);
+      // Unsubscribe from model rooms on cleanup
+      if (socket.connected) {
+        for (const tag of tagTypesRef.current) {
+          socket.emit("unsubscribe:model", tag);
+        }
+      }
+    };
+  }, [socket]);
+
+  // Listen for sync events and update RTK Query cache
+  useEffect(() => {
+    if (!socket) {
+      return;
+    }
+
+    const log = (message: string): void => {
+      if (isDebug) {
+        logSocket(true, message);
+      }
+    };
+
+    const logEvent = (event: RealtimeEvent): void => {
+      if (!isDebug) {
+        return;
+      }
+      logSocket(true, `sync event: ${JSON.stringify(event)}`);
+    };
+
+    const isDebug = debug ?? isWebsocketsDebugEnabled();
+
+    const getApiQueries = (): Record<string, QueryCacheEntry> | null => {
+      try {
+        const state = store.getState() as Record<string, RtkApiState>;
+        return state?.[apiRef.current.reducerPath]?.queries ?? null;
+      } catch {
+        return null;
+      }
+    };
+
+    const handleSync = (event: RealtimeEvent): void => {
+      const {collection, method, id, data} = event;
+      const currentApi = apiRef.current;
+
+      // Only process events for collections we care about
+      if (!tagTypesRef.current.includes(collection)) {
+        log(`Ignoring event for collection: ${collection}`);
+        return;
+      }
+
+      log(`Received ${method} event for ${collection}/${id}`);
+      logEvent(event);
+
+      switch (method) {
+        case "update": {
+          if (!data) {
+            dispatch(currentApi.util.invalidateTags([collection]));
+            break;
+          }
+
+          const queries = getApiQueries();
+          if (!queries) {
+            dispatch(currentApi.util.invalidateTags([collection]));
+            break;
+          }
+
+          let patched = false;
+          for (const [_cacheKey, queryEntry] of Object.entries(queries)) {
+            const entry = queryEntry as QueryCacheEntry;
+            if (entry?.status !== "fulfilled" || !entry?.data) {
+              continue;
+            }
+
+            const {endpointName, originalArgs} = entry;
+
+            // List response: {data: [...], total, page, more}
+            if (entry.data?.data && Array.isArray(entry.data.data)) {
+              const hasEntity = entry.data.data.some(
+                (item: DocumentItem) => item._id === id || item.id === id
+              );
+              if (hasEntity) {
+                dispatch(
+                  currentApi.util.updateQueryData(
+                    endpointName,
+                    originalArgs,
+                    (draft: CacheEntryData) => {
+                      if (draft?.data && Array.isArray(draft.data)) {
+                        const index = draft.data.findIndex(
+                          (item: DocumentItem) => item._id === id || item.id === id
+                        );
+                        if (index !== -1) {
+                          // Stale event check via updated timestamp
+                          const cachedUpdated = draft.data[index].updated;
+                          if (
+                            cachedUpdated &&
+                            data.updated &&
+                            DateTime.fromISO(cachedUpdated) > DateTime.fromISO(data.updated)
+                          ) {
+                            log(`Skipping stale update for ${collection}/${id}`);
+                            return;
+                          }
+                          Object.assign(draft.data[index], data);
+                        }
+                      }
+                    }
+                  )
+                );
+                patched = true;
+              }
+            }
+            // Single entity response: {_id, ...fields}
+            else if (entry.data?._id === id || entry.data?.id === id) {
+              const cachedUpdated = entry.data.updated;
+              if (
+                cachedUpdated &&
+                data.updated &&
+                DateTime.fromISO(cachedUpdated) > DateTime.fromISO(data.updated)
+              ) {
+                log(`Skipping stale update for ${collection}/${id}`);
+                continue;
+              }
+              dispatch(
+                currentApi.util.updateQueryData(
+                  endpointName,
+                  originalArgs,
+                  (draft: CacheEntryData) => {
+                    Object.assign(draft, data);
+                  }
+                )
+              );
+              patched = true;
+            }
+          }
+
+          if (!patched) {
+            dispatch(currentApi.util.invalidateTags([collection]));
+          }
+          break;
+        }
+
+        case "delete": {
+          const queries = getApiQueries();
+          if (!queries) {
+            dispatch(currentApi.util.invalidateTags([collection]));
+            break;
+          }
+
+          let patched = false;
+          for (const [_cacheKey, queryEntry] of Object.entries(queries)) {
+            const entry = queryEntry as QueryCacheEntry;
+            if (entry?.status !== "fulfilled" || !entry?.data) {
+              continue;
+            }
+
+            const {endpointName, originalArgs} = entry;
+
+            // List response with data array
+            if (entry.data?.data && Array.isArray(entry.data.data)) {
+              const hasEntity = entry.data.data.some(
+                (item: DocumentItem) => item._id === id || item.id === id
+              );
+              if (hasEntity) {
+                dispatch(
+                  currentApi.util.updateQueryData(
+                    endpointName,
+                    originalArgs,
+                    (draft: CacheEntryData) => {
+                      if (draft?.data && Array.isArray(draft.data)) {
+                        draft.data = draft.data.filter(
+                          (item: DocumentItem) => item._id !== id && item.id !== id
+                        );
+                        if (typeof draft.total === "number") {
+                          draft.total = Math.max(0, draft.total - 1);
+                        }
+                      }
+                    }
+                  )
+                );
+                patched = true;
+              }
+            }
+          }
+
+          if (!patched) {
+            dispatch(currentApi.util.invalidateTags([collection]));
+          }
+          break;
+        }
+
+        case "create": {
+          // For creates, we can't determine filter match client-side,
+          // so invalidate tags to trigger refetch of list queries
+          dispatch(currentApi.util.invalidateTags([collection]));
+          break;
+        }
+      }
+    };
+
+    socket.on("sync", handleSync);
+    log("Listening for sync events");
+
+    return (): void => {
+      socket.off("sync", handleSync);
+      log("Stopped listening for sync events");
+    };
+  }, [socket, dispatch, store, debug]);
+};

package/src/tagGenerator.ts

@@ -1,23 +1,38 @@
-// biome-ignore-all lint/suspicious/noExplicitAny: Generics
-
 // use this with enhanceEndpoints since the code generator doesn't invalidate by individual ids,
 // only at the full collection level
 
+interface TagProviderResult {
+  data?: Array<{_id: string}>;
+  _id?: string;
+}
+
+type TagEntry = string | {type: string; id?: string};
+type TagProviderFn = (result: TagProviderResult | null | undefined) => TagEntry[];
+
+interface EndpointTagConfig {
+  providesTags: TagProviderFn;
+  invalidatesTags: TagProviderFn;
+}
+
+interface ApiWithEndpoints {
+  endpoints: Record<string, unknown>;
+}
+
 const providesIdTags =
   (path: string) =>
-  (result: any): string[] | [{type: string; id?: string}] =>
-    result ? [...(result?.data?.map(({_id}: any) => ({id: _id, type: path})) ?? []), path] : [path];
+  (result: TagProviderResult | null | undefined): TagEntry[] =>
+    result ? [...(result?.data?.map(({_id}) => ({id: _id, type: path})) ?? []), path] : [path];
 
 const providesIdTag =
   (path: string) =>
-  (result: any): string[] | [{type: string; id?: string}] => {
+  (result: TagProviderResult | null | undefined): TagEntry[] => {
     return result ? [{id: result._id, type: path}] : [path];
   };
 
 const invalidatesIdTags =
   (path: string) =>
-  (result: any): string[] | [{type: string; id?: string}] =>
-    result ? [...(result?.data?.map(({_id}: any) => ({id: _id, type: path})) ?? []), path] : [path];
+  (result: TagProviderResult | null | undefined): TagEntry[] =>
+    result ? [...(result?.data?.map(({_id}) => ({id: _id, type: path})) ?? []), path] : [path];
 
 const cleanEndpointStringToGenerateTag = (string: string): string => {
   // Define the prefixes and suffix
@@ -33,14 +48,17 @@ const cleanEndpointStringToGenerateTag = (string: string): string => {
   return string.replace(regex, "")?.toLowerCase();
 };
 
-export const generateTags = (api: any, tagTypes: string[]): any => {
+export const generateTags = (
+  api: ApiWithEndpoints,
+  tagTypes: string[]
+): Record<string, EndpointTagConfig> => {
   // take the api, and for each get and list endpoint, generate tags that invalidate the cache by id
   // and by the list endpoint
   const endpoints = api.endpoints;
-  const tags: any = {};
+  const tags: Record<string, Partial<EndpointTagConfig>> = {};
   Object.keys(endpoints).forEach((endpoint) => {
     if (endpoint === "getConversations") {
-      tags[endpoint] = {invalidatesTags: ["conversations", "messages"]};
+      tags[endpoint] = {invalidatesTags: (): TagEntry[] => ["conversations", "messages"]};
     }
     if (endpoint.toLowerCase().includes("get")) {
       // List endpoints
@@ -76,5 +94,5 @@ export const generateTags = (api: any, tagTypes: string[]): any => {
       }
     }
   });
-  return tags;
+  return tags as Record<string, EndpointTagConfig>;
 };

package/src/useOfflineStatus.test.ts

@@ -0,0 +1,157 @@
+import {beforeEach, describe, expect, it} from "bun:test";
+import {configureStore} from "@reduxjs/toolkit";
+import {act, renderHook} from "@testing-library/react-native";
+import React from "react";
+import {Provider} from "react-redux";
+
+import {
+  addConflict,
+  type ConflictRecord,
+  enqueue,
+  offlineReducer,
+  type QueuedMutation,
+  setOnlineStatus,
+  setSyncing,
+} from "./offlineSlice";
+import {useOfflineStatus} from "./useOfflineStatus";
+
+const createTestStore = () =>
+  configureStore({
+    reducer: {offline: offlineReducer},
+  });
+
+const createWrapper = (store: ReturnType<typeof createTestStore>) => {
+  const Wrapper: React.FC<{children: React.ReactNode}> = ({children}) =>
+    React.createElement(Provider, {children, store});
+  return Wrapper;
+};
+
+describe("useOfflineStatus", () => {
+  let store: ReturnType<typeof createTestStore>;
+
+  beforeEach(() => {
+    store = createTestStore();
+  });
+
+  it("returns initial online state", () => {
+    const {result} = renderHook(() => useOfflineStatus(), {
+      wrapper: createWrapper(store),
+    });
+
+    expect(result.current.isOnline).toBe(true);
+    expect(result.current.queueLength).toBe(0);
+    expect(result.current.isSyncing).toBe(false);
+    expect(result.current.conflicts).toEqual([]);
+    expect(result.current.undismissedConflicts).toEqual([]);
+  });
+
+  it("reflects offline state", () => {
+    store.dispatch(setOnlineStatus(false));
+
+    const {result} = renderHook(() => useOfflineStatus(), {
+      wrapper: createWrapper(store),
+    });
+
+    expect(result.current.isOnline).toBe(false);
+  });
+
+  it("reports queue length", () => {
+    const mutation: QueuedMutation = {
+      args: {body: {title: "Test"}},
+      endpointName: "postTodos",
+      id: "test-1",
+      timestamp: "2026-01-01T00:00:00.000Z",
+      type: "create",
+    };
+    store.dispatch(enqueue(mutation));
+
+    const {result} = renderHook(() => useOfflineStatus(), {
+      wrapper: createWrapper(store),
+    });
+
+    expect(result.current.queueLength).toBe(1);
+  });
+
+  it("reports syncing state", () => {
+    store.dispatch(setSyncing(true));
+
+    const {result} = renderHook(() => useOfflineStatus(), {
+      wrapper: createWrapper(store),
+    });
+
+    expect(result.current.isSyncing).toBe(true);
+  });
+
+  it("filters undismissed conflicts", () => {
+    const conflict: ConflictRecord = {
+      args: {id: "abc"},
+      dismissed: false,
+      endpointName: "patchTodosById",
+      id: "conflict-1",
+      serverDocument: {title: "Server"},
+      timestamp: "2026-01-01T00:00:00.000Z",
+    };
+    store.dispatch(addConflict(conflict));
+
+    const {result} = renderHook(() => useOfflineStatus(), {
+      wrapper: createWrapper(store),
+    });
+
+    expect(result.current.conflicts).toHaveLength(1);
+    expect(result.current.undismissedConflicts).toHaveLength(1);
+  });
+
+  it("dismissConflict dispatches the action", () => {
+    const conflict: ConflictRecord = {
+      args: {id: "abc"},
+      dismissed: false,
+      endpointName: "patchTodosById",
+      id: "conflict-to-dismiss",
+      serverDocument: {title: "Server"},
+      timestamp: "2026-01-01T00:00:00.000Z",
+    };
+    store.dispatch(addConflict(conflict));
+
+    const {result} = renderHook(() => useOfflineStatus(), {
+      wrapper: createWrapper(store),
+    });
+
+    act(() => {
+      result.current.dismissConflict("conflict-to-dismiss");
+    });
+
+    expect(result.current.undismissedConflicts).toHaveLength(0);
+    expect(result.current.conflicts[0].dismissed).toBe(true);
+  });
+
+  it("clearConflicts removes all conflicts", () => {
+    const conflict: ConflictRecord = {
+      args: {id: "abc"},
+      dismissed: false,
+      endpointName: "patchTodosById",
+      id: "conflict-clear",
+      serverDocument: {title: "Server"},
+      timestamp: "2026-01-01T00:00:00.000Z",
+    };
+    store.dispatch(addConflict(conflict));
+
+    const {result} = renderHook(() => useOfflineStatus(), {
+      wrapper: createWrapper(store),
+    });
+
+    act(() => {
+      result.current.clearConflicts();
+    });
+
+    expect(result.current.conflicts).toHaveLength(0);
+  });
+
+  it("isLocalOnly returns true for temp-prefixed IDs", () => {
+    const {result} = renderHook(() => useOfflineStatus(), {
+      wrapper: createWrapper(store),
+    });
+
+    expect(result.current.isLocalOnly("temp-abc123")).toBe(true);
+    expect(result.current.isLocalOnly("507f1f77bcf86cd799439011")).toBe(false);
+  });
+});

package/src/useOfflineStatus.ts

@@ -0,0 +1,82 @@
+import {useCallback} from "react";
+import {useDispatch, useSelector} from "react-redux";
+
+import {
+  type ConflictRecord,
+  clearConflicts,
+  dismissConflict,
+  type OfflineState,
+  selectConflicts,
+  selectIsOnline,
+  selectIsSyncing,
+  selectQueueLength,
+  selectUndismissedConflicts,
+} from "./offlineSlice";
+
+export interface OfflineStatus {
+  /** Whether the device currently has network connectivity */
+  isOnline: boolean;
+  /** Number of mutations waiting to be synced */
+  queueLength: number;
+  /** Whether mutations are currently being replayed to the server */
+  isSyncing: boolean;
+  /** All conflict records (including dismissed) */
+  conflicts: ConflictRecord[];
+  /** Conflict records the user hasn't dismissed yet */
+  undismissedConflicts: ConflictRecord[];
+  /** Dismiss a single conflict notification by ID */
+  dismissConflict: (id: string) => void;
+  /** Clear all conflict records */
+  clearConflicts: () => void;
+  /** Returns true if the item exists only locally (not yet synced to server) */
+  isLocalOnly: (id: string) => boolean;
+}
+
+/**
+ * Hook for consuming offline state, sync status, and conflict notifications.
+ *
+ * Usage:
+ * ```typescript
+ * const {isOnline, queueLength, isSyncing, undismissedConflicts, dismissConflict} = useOfflineStatus();
+ *
+ * if (!isOnline) {
+ *   return <Banner text={`Offline. ${queueLength} changes pending.`} />;
+ * }
+ * ```
+ */
+export const useOfflineStatus = (): OfflineStatus => {
+  const dispatch = useDispatch();
+  const isOnline = useSelector((state: {offline: OfflineState}) => selectIsOnline(state));
+  const queueLength = useSelector((state: {offline: OfflineState}) => selectQueueLength(state));
+  const isSyncing = useSelector((state: {offline: OfflineState}) => selectIsSyncing(state));
+  const conflicts = useSelector((state: {offline: OfflineState}) => selectConflicts(state));
+  const undismissedConflicts = useSelector((state: {offline: OfflineState}) =>
+    selectUndismissedConflicts(state)
+  );
+
+  const handleDismissConflict = useCallback(
+    (id: string) => {
+      dispatch(dismissConflict(id));
+    },
+    [dispatch]
+  );
+
+  const handleClearConflicts = useCallback(() => {
+    dispatch(clearConflicts());
+  }, [dispatch]);
+
+  const isLocalOnly = useCallback((id: string): boolean => {
+    return typeof id === "string" && id.startsWith("temp-");
+  }, []);
+
+  return {
+    clearConflicts: handleClearConflicts,
+    conflicts,
+    dismissConflict: handleDismissConflict,
+    isLocalOnly,
+    isOnline,
+    isSyncing,
+    queueLength,
+    undismissedConflicts,
+  };
+};

package/src/useRealtimeDebug.ts

@@ -0,0 +1,51 @@
+import {useEffect, useState} from "react";
+import {useSelector} from "react-redux";
+
+import {isWebsocketsDebugEnabled, setRealtimeDebug} from "./constants";
+import {selectIsOnlineSafe} from "./offlineSlice";
+
+interface RealtimeHealthResponse {
+  debug?: boolean;
+}
+
+/**
+ * Syncs websocket debug logging with the backend RealtimeApp debug flag.
+ * Also respects WEBSOCKETS_DEBUG from app config via isWebsocketsDebugEnabled().
+ */
+export const useRealtimeDebug = (baseUrl: string, refreshKey?: unknown): boolean => {
+  const [debugEnabled, setDebugEnabled] = useState(isWebsocketsDebugEnabled);
+  const isOnline = useSelector(selectIsOnlineSafe);
+
+  useEffect(() => {
+    if (!isOnline) {
+      return;
+    }
+
+    let cancelled = false;
+
+    const loadDebugFlag = async (): Promise<void> => {
+      try {
+        const response = await fetch(`${baseUrl}/realtime/health`);
+        if (!response.ok) {
+          return;
+        }
+        const data = (await response.json()) as RealtimeHealthResponse;
+        if (cancelled) {
+          return;
+        }
+        setRealtimeDebug(data.debug === true);
+        setDebugEnabled(isWebsocketsDebugEnabled());
+      } catch {
+        // Health endpoint unavailable — keep env-based debug only
+      }
+    };
+
+    void loadDebugFlag();
+
+    return (): void => {
+      cancelled = true;
+    };
+  }, [baseUrl, refreshKey, isOnline]);
+
+  return debugEnabled;
+};