@terreno/rtk 0.25.0 → 0.27.0

package/src/offlineMiddleware.ts

@@ -28,6 +28,7 @@ export interface OfflineMiddlewareConfig {
   /** RTK Query mutation endpoint names to queue when offline */
   endpoints: string[];
   /** The RTK Query API instance */
+  // noExplicitAny: Generic API type
   // biome-ignore lint/suspicious/noExplicitAny: Generic API type
   api: Api<any, any, any, any>;
 }
@@ -54,6 +55,7 @@ const inferMutationType = (endpointName: string): "create" | "update" | "delete"
  * not an auth or application-level FETCH_ERROR from emptyApi.
  */
 export const isNetworkFetchError = (
+  // noExplicitAny: RTK Query error shapes vary by source
   // biome-ignore lint/suspicious/noExplicitAny: RTK Query error shapes vary by source
   source: any
 ): boolean => {
@@ -141,8 +143,10 @@ const inferGetByIdEndpointName = (endpointName: string): string => {
 const extractBaseUpdatedAt = (
   endpointName: string,
   originalArgs: unknown,
+  // noExplicitAny: Generic getState
   // biome-ignore lint/suspicious/noExplicitAny: Generic getState
   getState: () => any,
+  // noExplicitAny: Generic API type
   // biome-ignore lint/suspicious/noExplicitAny: Generic API type
   api: Api<any, any, any, any>
 ): string | undefined => {
@@ -162,6 +166,7 @@ const extractBaseUpdatedAt = (
 
   const getByIdEndpoint = inferGetByIdEndpointName(endpointName);
   const state = getState();
+  // noExplicitAny: RTK Query internal state shape
   // biome-ignore lint/suspicious/noExplicitAny: RTK Query internal state shape
   const queries: Record<string, any> = state[api.reducerPath]?.queries ?? {};
   for (const key of Object.keys(queries)) {
@@ -188,13 +193,16 @@ const extractBaseUpdatedAt = (
  * args the consumer passed to the query hook, e.g. `{}` vs `undefined`).
  */
 const getCachedQueryArgs = (
+  // noExplicitAny: Generic API state shape
   // biome-ignore lint/suspicious/noExplicitAny: Generic API state shape
   getState: () => any,
+  // noExplicitAny: Generic API type
   // biome-ignore lint/suspicious/noExplicitAny: Generic API type
   api: Api<any, any, any, any>,
   listEndpointName: string
 ): unknown[] => {
   const state = getState();
+  // noExplicitAny: RTK Query internal state shape
   // biome-ignore lint/suspicious/noExplicitAny: RTK Query internal state shape
   const queries: Record<string, any> = state[api.reducerPath]?.queries ?? {};
   const cachedArgs: unknown[] = [];
@@ -213,10 +221,13 @@ const getCachedQueryArgs = (
  * Apply an optimistic update to the RTK Query cache for a queued mutation.
  */
 const applyOptimisticUpdate = (
+  // noExplicitAny: Generic API type
   // biome-ignore lint/suspicious/noExplicitAny: Generic API type
   api: Api<any, any, any, any>,
+  // noExplicitAny: Generic dispatch
   // biome-ignore lint/suspicious/noExplicitAny: Generic dispatch
   dispatch: any,
+  // noExplicitAny: Generic getState
   // biome-ignore lint/suspicious/noExplicitAny: Generic getState
   getState: () => any,
   mutation: QueuedMutation
@@ -225,10 +236,12 @@ const applyOptimisticUpdate = (
   const listEndpointName = `get${tagType.charAt(0).toUpperCase() + tagType.slice(1)}`;
   const cachedArgs = getCachedQueryArgs(getState, api, listEndpointName);
 
+  // noExplicitAny: RTK Query cache shape varies by endpoint
   // biome-ignore lint/suspicious/noExplicitAny: RTK Query cache shape varies by endpoint
   const updateAllCacheEntries = (updater: (draft: any) => void): void => {
     for (const queryArg of cachedArgs) {
       dispatch(
+        // noExplicitAny: RTK Query cache shape varies by endpoint
         // biome-ignore lint/suspicious/noExplicitAny: RTK Query cache shape varies by endpoint
         api.util.updateQueryData(listEndpointName as any, queryArg, updater)
       );
@@ -238,6 +251,7 @@ const applyOptimisticUpdate = (
   if (mutation.type === "create") {
     const args = mutation.args as {body?: Record<string, unknown>};
     const tempItem = buildOptimisticCreateItem(mutation, args?.body);
+    // noExplicitAny: RTK Query cache shape varies by endpoint
     // biome-ignore lint/suspicious/noExplicitAny: RTK Query cache shape varies by endpoint
     updateAllCacheEntries((draft: any) => {
       if (draft?.data && Array.isArray(draft.data)) {
@@ -247,6 +261,7 @@ const applyOptimisticUpdate = (
   } else if (mutation.type === "update") {
     const args = mutation.args as {id?: string; body?: Record<string, unknown>};
     if (args?.id && args?.body) {
+      // noExplicitAny: RTK Query cache shape varies by endpoint
       // biome-ignore lint/suspicious/noExplicitAny: RTK Query cache shape varies by endpoint
       updateAllCacheEntries((draft: any) => {
         if (draft?.data && Array.isArray(draft.data)) {
@@ -262,6 +277,7 @@ const applyOptimisticUpdate = (
   } else if (mutation.type === "delete") {
     const args = mutation.args as {id?: string};
     if (args?.id) {
+      // noExplicitAny: RTK Query cache shape varies by endpoint
       // biome-ignore lint/suspicious/noExplicitAny: RTK Query cache shape varies by endpoint
       updateAllCacheEntries((draft: any) => {
         if (draft?.data && Array.isArray(draft.data)) {
@@ -278,10 +294,13 @@ const applyOptimisticUpdate = (
  * Remove optimistic temp items from the cache after they've been replayed.
  */
 const removeTempItems = (
+  // noExplicitAny: Generic API type
   // biome-ignore lint/suspicious/noExplicitAny: Generic API type
   api: Api<any, any, any, any>,
+  // noExplicitAny: Generic dispatch
   // biome-ignore lint/suspicious/noExplicitAny: Generic dispatch
   dispatch: any,
+  // noExplicitAny: Generic getState
   // biome-ignore lint/suspicious/noExplicitAny: Generic getState
   getState: () => any,
   mutations: QueuedMutation[]
@@ -295,6 +314,7 @@ const removeTempItems = (
 
     for (const queryArg of cachedArgs) {
       dispatch(
+        // noExplicitAny: RTK Query cache shape varies by endpoint
         // biome-ignore lint/suspicious/noExplicitAny: RTK Query cache shape varies by endpoint
         api.util.updateQueryData(listEndpointName as any, queryArg, (draft: any) => {
           if (draft?.data && Array.isArray(draft.data)) {
@@ -369,6 +389,7 @@ const replayMutation = async (
  * Web apps should use `useServerStatus` for server-level health checking.
  */
 const setupNativeNetworkMonitoring = (
+  // noExplicitAny: Generic dispatch
   // biome-ignore lint/suspicious/noExplicitAny: Generic dispatch
   dispatch: any
 ): (() => void) => {
@@ -438,6 +459,7 @@ export const createOfflineMiddleware = (
   // RTK Query dispatches actions with type "terreno-rtk/executeMutation/rejected"
   // when a mutation fails. Queue the mutation and apply an optimistic cache update.
   listenerMiddleware.startListening({
+    // noExplicitAny: RTK Query action types are complex
     // biome-ignore lint/suspicious/noExplicitAny: RTK Query action types are complex
     effect: async (action: any, listenerApi) => {
       const state = listenerApi.getState() as {offline: OfflineState};
@@ -464,11 +486,13 @@ export const createOfflineMiddleware = (
           const listEndpointName = `get${tagType.charAt(0).toUpperCase() + tagType.slice(1)}`;
           const cachedArgs = getCachedQueryArgs(listenerApi.getState, api, listEndpointName);
           for (const queryArg of cachedArgs) {
+            // noExplicitAny: RTK Query cache shape and endpoint types vary
             // biome-ignore lint/suspicious/noExplicitAny: RTK Query cache shape and endpoint types vary
             const endpoint = (api.endpoints as any)[listEndpointName];
             if (!endpoint?.select) {
               continue;
             }
+            // noExplicitAny: RTK Query cache shape varies
             // biome-ignore lint/suspicious/noExplicitAny: RTK Query cache shape varies
             const cacheEntry = endpoint.select(queryArg)(listenerApi.getState() as any) as any;
             const items = cacheEntry?.data?.data;
@@ -513,6 +537,7 @@ export const createOfflineMiddleware = (
         listenerApi.dispatch(setOnlineStatus(false));
       }
     },
+    // noExplicitAny: RTK Query internal action shape
     // biome-ignore lint/suspicious/noExplicitAny: RTK Query internal action shape
     predicate: (action: any) => {
       if (typeof action?.type !== "string") {
@@ -535,6 +560,7 @@ export const createOfflineMiddleware = (
         listenerApi.dispatch(setOnlineStatus(false));
       }
     },
+    // noExplicitAny: RTK Query internal action shape
     // biome-ignore lint/suspicious/noExplicitAny: RTK Query internal action shape
     predicate: (action: any) => {
       if (typeof action?.type !== "string") {
@@ -557,6 +583,7 @@ export const createOfflineMiddleware = (
         listenerApi.dispatch(setOnlineStatus(true));
       }
     },
+    // noExplicitAny: RTK Query internal action shape
     // biome-ignore lint/suspicious/noExplicitAny: RTK Query internal action shape
     predicate: (action: any) => {
       if (typeof action?.type !== "string") {

package/src/realtime.test.ts

@@ -1,3 +1,4 @@
+// noExplicitAny: realtime RTK tests mock Socket.io and RTK Query runtime shapes
 // biome-ignore-all lint/suspicious/noExplicitAny: realtime RTK tests mock Socket.io and RTK Query runtime shapes
 import {afterEach, describe, expect, it} from "bun:test";
 import type {Socket} from "socket.io-client";

package/src/sessionApi.test.ts

@@ -0,0 +1,115 @@
+import {afterEach, describe, expect, it, mock} from "bun:test";
+import {configureStore} from "@reduxjs/toolkit";
+
+import {createSessionApi} from "./sessionApi";
+
+type FetchArgs = Parameters<typeof fetch>;
+
+interface RecordedFetch {
+  urls: string[];
+  handler: (input: FetchArgs[0], init: FetchArgs[1]) => Response;
+}
+
+const jsonResponse = (body: unknown, status = 200): Response =>
+  new Response(JSON.stringify(body), {
+    headers: {"Content-Type": "application/json"},
+    status,
+  });
+
+const originalFetch = global.fetch;
+let recorded: RecordedFetch;
+
+const setFetch = (handler: RecordedFetch["handler"]): void => {
+  recorded = {handler, urls: []};
+  global.fetch = mock((input: FetchArgs[0], init: FetchArgs[1]) => {
+    const url =
+      typeof input === "string" ? input : input instanceof Request ? input.url : String(input);
+    recorded.urls.push(url);
+    return Promise.resolve(handler(input, init));
+  }) as unknown as typeof fetch;
+};
+
+const buildStore = () => {
+  const api = createSessionApi({baseUrl: "http://localhost:9999"});
+  const withEndpoints = api.injectEndpoints({
+    endpoints: (build) => ({
+      getThing: build.query<unknown, void>({query: () => "/thing"}),
+      getWithParams: build.query<unknown, void>({
+        query: () => ({params: {ids: {$in: [1, 2]}, status: "active"}, url: "/things"}),
+      }),
+    }),
+    overrideExisting: true,
+  });
+  const store = configureStore({
+    middleware: (getDefaultMiddleware) => getDefaultMiddleware().concat(api.middleware),
+    reducer: {[api.reducerPath]: api.reducer},
+  });
+  return {api, store, withEndpoints};
+};
+
+describe("createSessionApi", () => {
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it("defaults reducerPath to terreno-session", () => {
+    const api = createSessionApi();
+    expect(api.reducerPath).toBe("terreno-session");
+  });
+
+  it("uses a custom reducerPath when provided", () => {
+    const api = createSessionApi({reducerPath: "admin-session"});
+    expect(api.reducerPath).toBe("admin-session");
+  });
+
+  describe("responseHandler", () => {
+    it("returns null for a 204 No Content response", async () => {
+      setFetch(() => new Response(null, {status: 204}));
+      const {store, withEndpoints} = buildStore();
+
+      const result = await store.dispatch(withEndpoints.endpoints.getThing.initiate());
+
+      expect(result.error).toBeUndefined();
+      expect(result.data).toBeNull();
+    });
+
+    it("returns the whole payload for list responses containing `more`", async () => {
+      const payload = {data: [{id: "1"}], more: false, page: 1};
+      setFetch(() => jsonResponse(payload));
+      const {store, withEndpoints} = buildStore();
+
+      const result = await store.dispatch(withEndpoints.endpoints.getThing.initiate());
+
+      expect(result.data).toEqual(payload);
+    });
+
+    it("unwraps the `data` envelope for single-resource responses", async () => {
+      setFetch(() => jsonResponse({data: {id: "42", name: "answer"}}));
+      const {store, withEndpoints} = buildStore();
+
+      const result = await store.dispatch(withEndpoints.endpoints.getThing.initiate());
+
+      expect(result.data).toEqual({id: "42", name: "answer"});
+    });
+
+    it("returns the raw result when there is no `data` envelope or `more` field", async () => {
+      setFetch(() => jsonResponse({id: "7", name: "raw"}));
+      const {store, withEndpoints} = buildStore();
+
+      const result = await store.dispatch(withEndpoints.endpoints.getThing.initiate());
+
+      expect(result.data).toEqual({id: "7", name: "raw"});
+    });
+  });
+
+  it("serializes nested query params with qs", async () => {
+    setFetch(() => jsonResponse({id: "1"}));
+    const {store, withEndpoints} = buildStore();
+
+    await store.dispatch(withEndpoints.endpoints.getWithParams.initiate());
+
+    const requestedUrl = recorded.urls[0];
+    expect(requestedUrl).toContain("ids%5B%24in%5D%5B0%5D=1");
+    expect(requestedUrl).toContain("status=active");
+  });
+});

package/src/sync.test.ts

@@ -0,0 +1,390 @@
+import {describe, expect, it, mock} 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 type {Socket} from "socket.io-client";
+
+import type {RealtimeEvent} from "./realtime";
+import {useSyncConnection} from "./sync";
+
+const REDUCER_PATH = "testApi";
+
+type SocketHandler = (arg?: unknown) => void;
+
+interface FakeSocket {
+  connected: boolean;
+  emit: ReturnType<typeof mock>;
+  on: ReturnType<typeof mock>;
+  off: ReturnType<typeof mock>;
+  trigger: (event: string, arg?: unknown) => void;
+}
+
+const createFakeSocket = (connected: boolean): FakeSocket => {
+  const handlers: Record<string, SocketHandler[]> = {};
+  return {
+    connected,
+    emit: mock(() => {}),
+    off: mock((event: string, cb: SocketHandler) => {
+      handlers[event] = (handlers[event] ?? []).filter((h) => h !== cb);
+    }),
+    on: mock((event: string, cb: SocketHandler) => {
+      handlers[event] = handlers[event] ?? [];
+      handlers[event].push(cb);
+    }),
+    trigger: (event: string, arg?: unknown) => {
+      for (const cb of handlers[event] ?? []) {
+        cb(arg);
+      }
+    },
+  };
+};
+
+interface QueryEntry {
+  status: string;
+  endpointName: string;
+  originalArgs: unknown;
+  data?: Record<string, unknown>;
+}
+
+const createApi = (queries: Record<string, QueryEntry> | null) => {
+  const dataByEndpoint: Record<string, Record<string, unknown>> = {};
+  if (queries) {
+    for (const key of Object.keys(queries)) {
+      const entry = queries[key];
+      if (entry.data) {
+        dataByEndpoint[entry.endpointName] = entry.data;
+      }
+    }
+  }
+
+  const invalidateTags = mock((tags: string[]) => ({payload: tags, type: "api/invalidateTags"}));
+  const updateQueryData = mock(
+    (endpointName: string, _args: unknown, recipe: (draft: Record<string, unknown>) => void) => {
+      const draft = dataByEndpoint[endpointName];
+      if (draft) {
+        recipe(draft);
+      }
+      return {type: "api/updateQueryData"};
+    }
+  );
+
+  const api = {
+    reducerPath: REDUCER_PATH,
+    util: {invalidateTags, updateQueryData},
+  };
+
+  const store = configureStore({
+    middleware: (getDefaultMiddleware) =>
+      getDefaultMiddleware({immutableCheck: false, serializableCheck: false}),
+    reducer: {
+      [REDUCER_PATH]: (state = {queries: queries ?? undefined}) => state,
+    },
+  });
+
+  return {api, invalidateTags, store, updateQueryData};
+};
+
+const renderSync = (
+  socket: FakeSocket | null,
+  api: ReturnType<typeof createApi>["api"],
+  store: ReturnType<typeof configureStore>,
+  options: {tagTypes?: string[]; debug?: boolean} = {}
+) => {
+  const Wrapper: React.FC<{children: React.ReactNode}> = ({children}) =>
+    React.createElement(Provider, {children, store});
+  return renderHook(
+    () =>
+      useSyncConnection({
+        api,
+        debug: options.debug ?? true,
+        socket: socket as unknown as Socket,
+        tagTypes: options.tagTypes ?? ["todos"],
+      }),
+    {wrapper: Wrapper}
+  );
+};
+
+const syncEvent = (overrides: Partial<RealtimeEvent>): RealtimeEvent =>
+  ({
+    collection: "todos",
+    id: "1",
+    method: "update",
+    ...overrides,
+  }) as RealtimeEvent;
+
+describe("useSyncConnection", () => {
+  it("does nothing when there is no socket", () => {
+    const {store, api} = createApi(null);
+    const {result} = renderSync(null, api, store);
+    expect(result.current).toBeUndefined();
+  });
+
+  it("subscribes to model rooms when the socket is already connected", () => {
+    const socket = createFakeSocket(true);
+    const {store, api} = createApi({});
+    const {unmount} = renderSync(socket, api, store, {tagTypes: ["todos", "users"]});
+
+    expect(socket.emit).toHaveBeenCalledWith("subscribe:model", "todos");
+    expect(socket.emit).toHaveBeenCalledWith("subscribe:model", "users");
+    expect(socket.on).toHaveBeenCalledWith("connect", expect.any(Function));
+    expect(socket.on).toHaveBeenCalledWith("sync", expect.any(Function));
+
+    unmount();
+    expect(socket.emit).toHaveBeenCalledWith("unsubscribe:model", "todos");
+    expect(socket.off).toHaveBeenCalledWith("sync", expect.any(Function));
+  });
+
+  it("subscribes on the connect event when not initially connected", () => {
+    const socket = createFakeSocket(false);
+    const {store, api} = createApi({});
+    const {unmount} = renderSync(socket, api, store);
+
+    expect(socket.emit).not.toHaveBeenCalledWith("subscribe:model", "todos");
+
+    act(() => {
+      socket.trigger("connect");
+    });
+    expect(socket.emit).toHaveBeenCalledWith("subscribe:model", "todos");
+
+    // Not connected on cleanup, so no unsubscribe emit.
+    socket.emit.mockClear();
+    unmount();
+    expect(socket.emit).not.toHaveBeenCalledWith("unsubscribe:model", "todos");
+  });
+
+  it("ignores events for collections that are not tracked", () => {
+    const socket = createFakeSocket(true);
+    const {store, api, invalidateTags} = createApi({});
+    renderSync(socket, api, store);
+
+    act(() => {
+      socket.trigger("sync", syncEvent({collection: "other", method: "create"}));
+    });
+    expect(invalidateTags).not.toHaveBeenCalled();
+  });
+
+  it("invalidates tags for create events", () => {
+    const socket = createFakeSocket(true);
+    const {store, api, invalidateTags} = createApi({});
+    renderSync(socket, api, store);
+
+    act(() => {
+      socket.trigger("sync", syncEvent({method: "create"}));
+    });
+    expect(invalidateTags).toHaveBeenCalledWith(["todos"]);
+  });
+
+  it("invalidates tags for update events without data", () => {
+    const socket = createFakeSocket(true);
+    const {store, api, invalidateTags} = createApi({});
+    renderSync(socket, api, store);
+
+    act(() => {
+      socket.trigger("sync", syncEvent({data: undefined, method: "update"}));
+    });
+    expect(invalidateTags).toHaveBeenCalledWith(["todos"]);
+  });
+
+  it("invalidates tags for update events when there are no cached queries", () => {
+    const socket = createFakeSocket(true);
+    const {store, api, invalidateTags} = createApi(null);
+    renderSync(socket, api, store);
+
+    act(() => {
+      socket.trigger("sync", syncEvent({data: {name: "new"}, method: "update"}));
+    });
+    expect(invalidateTags).toHaveBeenCalledWith(["todos"]);
+  });
+
+  it("patches a matching entity inside a cached list query on update", () => {
+    const socket = createFakeSocket(true);
+    const queries = {
+      "getTodos()": {
+        data: {data: [{_id: "1", name: "old", updated: "2026-01-01T00:00:00.000Z"}], total: 1},
+        endpointName: "getTodos",
+        originalArgs: undefined,
+        status: "fulfilled",
+      },
+    };
+    const {store, api, updateQueryData, invalidateTags} = createApi(queries);
+    renderSync(socket, api, store);
+
+    act(() => {
+      socket.trigger(
+        "sync",
+        syncEvent({data: {name: "new", updated: "2026-02-01T00:00:00.000Z"}, method: "update"})
+      );
+    });
+
+    expect(updateQueryData).toHaveBeenCalled();
+    expect(queries["getTodos()"].data.data[0].name).toBe("new");
+    expect(invalidateTags).not.toHaveBeenCalled();
+  });
+
+  it("skips stale updates in a cached list query", () => {
+    const socket = createFakeSocket(true);
+    const queries = {
+      "getTodos()": {
+        data: {data: [{_id: "1", name: "current", updated: "2026-03-01T00:00:00.000Z"}], total: 1},
+        endpointName: "getTodos",
+        originalArgs: undefined,
+        status: "fulfilled",
+      },
+    };
+    const {store, api} = createApi(queries);
+    renderSync(socket, api, store);
+
+    act(() => {
+      socket.trigger(
+        "sync",
+        syncEvent({data: {name: "stale", updated: "2026-01-01T00:00:00.000Z"}, method: "update"})
+      );
+    });
+
+    expect(queries["getTodos()"].data.data[0].name).toBe("current");
+  });
+
+  it("patches a matching single-entity cached query on update", () => {
+    const socket = createFakeSocket(true);
+    const queries = {
+      "getTodoById(1)": {
+        data: {_id: "1", name: "old", updated: "2026-01-01T00:00:00.000Z"},
+        endpointName: "getTodoById",
+        originalArgs: {id: "1"},
+        status: "fulfilled",
+      },
+    };
+    const {store, api, updateQueryData} = createApi(queries);
+    renderSync(socket, api, store);
+
+    act(() => {
+      socket.trigger(
+        "sync",
+        syncEvent({data: {name: "new", updated: "2026-02-01T00:00:00.000Z"}, method: "update"})
+      );
+    });
+
+    expect(updateQueryData).toHaveBeenCalled();
+    expect(queries["getTodoById(1)"].data.name).toBe("new");
+  });
+
+  it("skips stale updates for a single-entity cached query", () => {
+    const socket = createFakeSocket(true);
+    const queries = {
+      "getTodoById(1)": {
+        data: {_id: "1", name: "current", updated: "2026-03-01T00:00:00.000Z"},
+        endpointName: "getTodoById",
+        originalArgs: {id: "1"},
+        status: "fulfilled",
+      },
+    };
+    const {store, api, invalidateTags} = createApi(queries);
+    renderSync(socket, api, store);
+
+    act(() => {
+      socket.trigger(
+        "sync",
+        syncEvent({data: {name: "stale", updated: "2026-01-01T00:00:00.000Z"}, method: "update"})
+      );
+    });
+
+    expect(queries["getTodoById(1)"].data.name).toBe("current");
+    expect(invalidateTags).toHaveBeenCalledWith(["todos"]);
+  });
+
+  it("invalidates tags on update when no cached query matches", () => {
+    const socket = createFakeSocket(true);
+    const queries = {
+      "getOthers()": {
+        data: {data: [{_id: "999", name: "unrelated"}]},
+        endpointName: "getOthers",
+        originalArgs: undefined,
+        status: "fulfilled",
+      },
+      "pending()": {
+        data: {data: [{_id: "1"}]},
+        endpointName: "pending",
+        originalArgs: undefined,
+        status: "pending",
+      },
+    };
+    const {store, api, invalidateTags} = createApi(queries);
+    renderSync(socket, api, store);
+
+    act(() => {
+      socket.trigger("sync", syncEvent({data: {name: "new"}, method: "update"}));
+    });
+
+    expect(invalidateTags).toHaveBeenCalledWith(["todos"]);
+  });
+
+  it("removes a deleted entity from cached list queries and decrements total", () => {
+    const socket = createFakeSocket(true);
+    const queries = {
+      "getTodos()": {
+        data: {
+          data: [
+            {_id: "1", name: "a"},
+            {_id: "2", name: "b"},
+          ],
+          total: 2,
+        },
+        endpointName: "getTodos",
+        originalArgs: undefined,
+        status: "fulfilled",
+      },
+    };
+    const {store, api, updateQueryData} = createApi(queries);
+    renderSync(socket, api, store);
+
+    act(() => {
+      socket.trigger("sync", syncEvent({method: "delete"}));
+    });
+
+    expect(updateQueryData).toHaveBeenCalled();
+    expect(queries["getTodos()"].data.data).toHaveLength(1);
+    expect(queries["getTodos()"].data.total).toBe(1);
+  });
+
+  it("invalidates tags on delete when there are no cached queries", () => {
+    const socket = createFakeSocket(true);
+    const {store, api, invalidateTags} = createApi(null);
+    renderSync(socket, api, store);
+
+    act(() => {
+      socket.trigger("sync", syncEvent({method: "delete"}));
+    });
+    expect(invalidateTags).toHaveBeenCalledWith(["todos"]);
+  });
+
+  it("invalidates tags on delete when no cached query matches", () => {
+    const socket = createFakeSocket(true);
+    const queries = {
+      "getOthers()": {
+        data: {data: [{_id: "999"}]},
+        endpointName: "getOthers",
+        originalArgs: undefined,
+        status: "fulfilled",
+      },
+    };
+    const {store, api, invalidateTags} = createApi(queries);
+    renderSync(socket, api, store);
+
+    act(() => {
+      socket.trigger("sync", syncEvent({method: "delete"}));
+    });
+    expect(invalidateTags).toHaveBeenCalledWith(["todos"]);
+  });
+
+  it("does not log sync details when debug is disabled", () => {
+    const socket = createFakeSocket(true);
+    const {store, api, invalidateTags} = createApi({});
+    renderSync(socket, api, store, {debug: false});
+
+    act(() => {
+      socket.trigger("sync", syncEvent({method: "create"}));
+    });
+    expect(invalidateTags).toHaveBeenCalledWith(["todos"]);
+  });
+});

package/src/sync.ts

@@ -40,7 +40,8 @@ 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
+  // noExplicitAny: RTK Query Api generic requires four app-specific type parameters
+  // biome-ignore lint/suspicious/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[];