@terreno/rtk 0.13.0 → 0.14.0

package/src/isolated/offlineMiddleware.native.isolated.ts

@@ -0,0 +1,80 @@
+import {describe, expect, it, mock} from "bun:test";
+
+mock.module("react-native", () => ({
+  Platform: {OS: "ios"},
+  StyleSheet: {create: (styles: unknown) => styles},
+}));
+mock.module("../platform", () => ({IsWeb: false}));
+mock.module("../authSlice", () => ({
+  getAuthToken: async () => null,
+  selectCurrentUserId: (state: {auth?: {userId?: string}}) => state.auth?.userId,
+}));
+mock.module("../constants", () => ({
+  baseUrl: "http://localhost:4000",
+  LOGOUT_ACTION_TYPE: "auth/logout",
+}));
+
+let networkListener: ((state: {isConnected?: boolean}) => void) | undefined;
+const removeNetworkListener = mock(() => {});
+mock.module("expo-network", () => ({
+  addNetworkStateListener: (listener: (state: {isConnected?: boolean}) => void) => {
+    networkListener = listener;
+    return {remove: removeNetworkListener};
+  },
+  getNetworkStateAsync: async () => ({isConnected: false}),
+}));
+
+const {configureStore} = await import("@reduxjs/toolkit");
+const {createApi, fetchBaseQuery} = await import("@reduxjs/toolkit/query");
+const {createOfflineMiddleware} = await import("../offlineMiddleware");
+const {selectIsOnline} = await import("../offlineSlice");
+
+const api = createApi({
+  baseQuery: fetchBaseQuery({baseUrl: "http://localhost:4000"}),
+  endpoints: (builder) => ({
+    patchTodosById: builder.mutation({
+      query: (args: {id: string; body: Record<string, unknown>}) => ({
+        body: args.body,
+        method: "PATCH",
+        url: `/todos/${args.id}`,
+      }),
+    }),
+  }),
+  reducerPath: "terreno-rtk-native",
+});
+
+const createNativeStore = () => {
+  const offline = createOfflineMiddleware({
+    // biome-ignore lint/suspicious/noExplicitAny: Generic API type is intentionally broad.
+    api: api as any,
+    endpoints: ["patchTodosById"],
+  });
+
+  return configureStore({
+    middleware: (getDefault) =>
+      getDefault({serializableCheck: false}).concat(api.middleware, offline.middleware),
+    reducer: {
+      [api.reducerPath]: api.reducer,
+      offline: offline.offlineReducer,
+    },
+  });
+};
+
+const waitForEffects = async (): Promise<void> => {
+  await new Promise((resolve) => setTimeout(resolve, 0));
+};
+
+describe("createOfflineMiddleware native network monitoring", () => {
+  it("uses expo-network initial state and subscription updates", async () => {
+    const store = createNativeStore();
+
+    store.dispatch({type: "init-native-network-monitoring"});
+    await waitForEffects();
+
+    expect(selectIsOnline(store.getState())).toBe(false);
+    networkListener?.({isConnected: true});
+    expect(selectIsOnline(store.getState())).toBe(true);
+    networkListener?.({isConnected: false});
+    expect(selectIsOnline(store.getState())).toBe(false);
+  });
+});

package/src/{useUpgradeCheck.mobile.test.ts → isolated/useUpgradeCheck.mobile.isolated.ts}

@@ -1,5 +1,4 @@
 import {afterEach, beforeEach, describe, expect, it, mock} from "bun:test";
-import {act, renderHook, waitFor} from "@testing-library/react-native";
 
 // ---------------------------------------------------------------------------
 // Mutable refs
@@ -8,18 +7,19 @@ let mockBuildNumber: number | undefined = 42;
 
 interface MockVersionCheckResponse {
   message?: string;
+  pollingIntervalMs?: number;
   status: "ok" | "warning" | "required";
   updateUrl?: string;
 }
 const mockUnwrap = mock((): Promise<MockVersionCheckResponse> => Promise.resolve({status: "ok"}));
 const mockTrigger = mock((..._args: unknown[]) => ({unwrap: mockUnwrap}));
 
-mock.module("./emptyApi", () => ({
+mock.module("../emptyApi", () => ({
   useLazyGetVersionCheckQuery: () => [mockTrigger],
 }));
 
 // IsWeb is false to exercise native code paths
-mock.module("./platform", () => ({
+mock.module("../platform", () => ({
   IsWeb: false,
 }));
 
@@ -68,7 +68,16 @@ const warnCalls: unknown[][] = [];
 const originalDebug = console.debug;
 const originalWarn = console.warn;
 
-import {useUpgradeCheck} from "./useUpgradeCheck";
+// Import after all mock.module calls. Using `await import` instead of a
+// top-level static import ensures the mocks (especially for react-native) are
+// already in place when these modules' transitive imports resolve. With a
+// static import, bun 1.3.x has been observed to evaluate the real `react-native`
+// when this file is loaded after another test file already pulled it in, which
+// blows up with `Export named 'AppState' not found`. The
+// `@testing-library/react-native` import is also deferred because it pulls in
+// the real react-native module during its own evaluation.
+const {act, renderHook, waitFor} = await import("@testing-library/react-native");
+const {useUpgradeCheck} = await import("../useUpgradeCheck");
 
 const flushPromises = (): Promise<void> => new Promise((r) => setTimeout(r, 0));
 

package/src/{useUpgradeCheck.test.ts → isolated/useUpgradeCheck.web.isolated.ts}

@@ -1,5 +1,4 @@
 import {afterEach, beforeEach, describe, expect, it, mock} from "bun:test";
-import {act, renderHook, waitFor} from "@testing-library/react-native";
 
 // ---------------------------------------------------------------------------
 // Mutable refs that tests can tweak between runs
@@ -9,19 +8,20 @@ let mockBuildNumber: number | undefined = 42;
 // Trigger + unwrap mocks for useLazyGetVersionCheckQuery.
 interface MockVersionCheckResponse {
   message?: string;
+  pollingIntervalMs?: number;
   status: "ok" | "warning" | "required";
   updateUrl?: string;
 }
 const mockUnwrap = mock((): Promise<MockVersionCheckResponse> => Promise.resolve({status: "ok"}));
 const mockTrigger = mock((..._args: unknown[]) => ({unwrap: mockUnwrap}));
 
-mock.module("./emptyApi", () => ({
+mock.module("../emptyApi", () => ({
   useLazyGetVersionCheckQuery: () => [mockTrigger],
 }));
 
 // IsWeb is always true in tests (Platform.OS mocked as "web" in preload).
 // We cannot change it per-test because bun snapshots module exports.
-mock.module("./platform", () => ({
+mock.module("../platform", () => ({
   IsWeb: true,
 }));
 
@@ -78,8 +78,16 @@ const debugCalls: unknown[][] = [];
 const originalDebug = console.debug;
 const originalWarn = console.warn;
 
-// Now import the hook (after all mock.module calls which are hoisted)
-import {useUpgradeCheck} from "./useUpgradeCheck";
+// Import after all mock.module calls. Using `await import` instead of a
+// top-level static import ensures the mocks (especially for react-native) are
+// already in place when these modules' transitive imports resolve. With a
+// static import, bun 1.3.x has been observed to evaluate the real `react-native`
+// when this file is loaded after another test file already pulled it in, which
+// blows up with `Export named 'AppState' not found`. The
+// `@testing-library/react-native` import is also deferred because it pulls in
+// the real react-native module during its own evaluation.
+const {act, renderHook, waitFor} = await import("@testing-library/react-native");
+const {useUpgradeCheck} = await import("../useUpgradeCheck");
 
 // Helper: flush microtasks (lets .then() chains resolve)
 const flushPromises = (): Promise<void> => new Promise((r) => setTimeout(r, 0));
@@ -310,11 +318,45 @@ describe("useUpgradeCheck", () => {
       expect(capturedIntervalMs).toBe(60_000);
     });
 
-    it("does not set up interval when pollingIntervalMs is omitted", () => {
+    it("does not set up interval when pollingIntervalMs is omitted and server returns none", () => {
       renderHook(() => useUpgradeCheck());
       expect(mockSetInterval).not.toHaveBeenCalled();
     });
 
+    it("adopts server-returned pollingIntervalMs after first response", async () => {
+      mockUnwrap.mockImplementation(() =>
+        Promise.resolve({pollingIntervalMs: 3_600_000, status: "ok" as const})
+      );
+      renderHook(() => useUpgradeCheck());
+
+      await act(async () => {
+        await flushPromises();
+      });
+      // Flush the secondary render triggered by setActivePollingIntervalMs
+      await act(async () => {});
+
+      expect(mockSetInterval).toHaveBeenCalledWith(expect.any(Function), 3_600_000);
+    });
+
+    it("server pollingIntervalMs overrides the local fallback prop", async () => {
+      mockUnwrap.mockImplementation(() =>
+        Promise.resolve({pollingIntervalMs: 1_800_000, status: "ok" as const})
+      );
+      renderHook(() => useUpgradeCheck({pollingIntervalMs: 60_000}));
+
+      // Initial interval from prop
+      expect(mockSetInterval).toHaveBeenCalledWith(expect.any(Function), 60_000);
+
+      await act(async () => {
+        await flushPromises();
+      });
+      // Flush the secondary render triggered by setActivePollingIntervalMs
+      await act(async () => {});
+
+      // Interval restarts with the server-configured value
+      expect(mockSetInterval).toHaveBeenCalledWith(expect.any(Function), 1_800_000);
+    });
+
     it("cleans up interval on unmount", () => {
       const {unmount} = renderHook(() => useUpgradeCheck({pollingIntervalMs: 60_000}));
       unmount();

package/src/mongooseSlice.test.ts

@@ -1,3 +1,4 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 import {describe, expect, it} from "bun:test";
 
 import {type ListResponse, populateId} from "./mongooseSlice";
@@ -38,7 +39,6 @@ describe("populateId", () => {
 
   it("handles sparse arrays without throwing", () => {
     const sparse: ListResponse<{_id: string}> = {
-      // biome-ignore lint/suspicious/noExplicitAny: Simulating malformed API payloads.
       data: [undefined as any, {_id: "found"}],
     };
     expect(populateId("found", sparse)).toEqual({_id: "found"});

package/src/offlineGate.test.ts

@@ -0,0 +1,55 @@
+import {beforeEach, describe, expect, it} from "bun:test";
+import {configureStore} from "@reduxjs/toolkit";
+
+import {configureOfflineMutationEndpoints, shouldDeferOfflineMutation} from "./offlineGate";
+import {offlineReducer, setOnlineStatus} from "./offlineSlice";
+
+const createTestStore = () =>
+  configureStore({
+    reducer: {offline: offlineReducer},
+  });
+
+describe("offlineGate", () => {
+  let store: ReturnType<typeof createTestStore>;
+
+  beforeEach(() => {
+    store = createTestStore();
+    configureOfflineMutationEndpoints([]);
+  });
+
+  describe("configureOfflineMutationEndpoints", () => {
+    it("registers endpoint names", () => {
+      configureOfflineMutationEndpoints(["postTodos", "patchTodosById"]);
+      store.dispatch(setOnlineStatus(false));
+      expect(shouldDeferOfflineMutation("postTodos", store.getState)).toBe(true);
+      expect(shouldDeferOfflineMutation("patchTodosById", store.getState)).toBe(true);
+    });
+
+    it("replaces previous endpoints on re-configure", () => {
+      configureOfflineMutationEndpoints(["postTodos"]);
+      configureOfflineMutationEndpoints(["patchTodosById"]);
+      store.dispatch(setOnlineStatus(false));
+      expect(shouldDeferOfflineMutation("postTodos", store.getState)).toBe(false);
+      expect(shouldDeferOfflineMutation("patchTodosById", store.getState)).toBe(true);
+    });
+  });
+
+  describe("shouldDeferOfflineMutation", () => {
+    it("returns false for unregistered endpoints", () => {
+      configureOfflineMutationEndpoints(["postTodos"]);
+      store.dispatch(setOnlineStatus(false));
+      expect(shouldDeferOfflineMutation("postUsers", store.getState)).toBe(false);
+    });
+
+    it("returns false when online even for registered endpoints", () => {
+      configureOfflineMutationEndpoints(["postTodos"]);
+      expect(shouldDeferOfflineMutation("postTodos", store.getState)).toBe(false);
+    });
+
+    it("returns true when offline for registered endpoints", () => {
+      configureOfflineMutationEndpoints(["postTodos"]);
+      store.dispatch(setOnlineStatus(false));
+      expect(shouldDeferOfflineMutation("postTodos", store.getState)).toBe(true);
+    });
+  });
+});

package/src/offlineGate.ts

@@ -0,0 +1,25 @@
+import {type OfflineState, selectIsOnline} from "./offlineSlice";
+
+let offlineMutationEndpoints = new Set<string>();
+
+/** Register mutation endpoints that should be queued instead of sent while offline. */
+export const configureOfflineMutationEndpoints = (endpoints: string[]): void => {
+  offlineMutationEndpoints = new Set(endpoints);
+};
+
+/**
+ * When true, the base query should return a network error without making a request.
+ * The offline middleware will queue the mutation and apply an optimistic update.
+ */
+export const shouldDeferOfflineMutation = (
+  endpointName: string,
+  // biome-ignore lint/suspicious/noExplicitAny: Redux getState is app-specific
+  getState: () => any
+): boolean => {
+  if (!offlineMutationEndpoints.has(endpointName)) {
+    return false;
+  }
+
+  const state = getState() as {offline: OfflineState};
+  return !selectIsOnline(state);
+};

package/src/offlineMiddleware.test.ts

@@ -0,0 +1,187 @@
+import {describe, expect, it} from "bun:test";
+import {configureStore, type UnknownAction} from "@reduxjs/toolkit";
+import type {Api} from "@reduxjs/toolkit/query/react";
+
+import {
+  buildOptimisticCreateItem,
+  createOfflineMiddleware,
+  isNetworkFetchError,
+  shouldReplayQueuedMutation,
+} from "./offlineMiddleware";
+import {type OfflineState, type QueuedMutation, selectOfflineQueue} from "./offlineSlice";
+
+interface QueryEntry {
+  data?: {data: Record<string, unknown>[]};
+  originalArgs: unknown;
+}
+
+interface TestApiState {
+  queries: Record<string, QueryEntry>;
+}
+
+interface TestState {
+  auth: {userId?: string};
+  offline: OfflineState;
+  testApi: TestApiState;
+}
+
+const LIST_QUERY_ARGS = {};
+const LIST_UPDATED_AT = "2026-05-23T21:00:00.123Z";
+
+const initialTestApiState: TestApiState = {
+  queries: {
+    "getTodos({})": {
+      data: {
+        data: [
+          {
+            _id: "todo-1",
+            title: "Original",
+            updated: LIST_UPDATED_AT,
+          },
+        ],
+      },
+      originalArgs: LIST_QUERY_ARGS,
+    },
+  },
+};
+
+const testApiReducer = (state: TestApiState = initialTestApiState): TestApiState => state;
+
+// biome-ignore lint/suspicious/noExplicitAny: Test double covers only fields used by offline middleware.
+const createTestApi = (): Api<any, any, any, any> => {
+  return {
+    endpoints: {
+      getTodos: {
+        select: (queryArg: unknown) => {
+          return (state: TestState): QueryEntry | undefined => {
+            return Object.values(state.testApi.queries).find(
+              (entry) => entry.originalArgs === queryArg
+            );
+          };
+        },
+      },
+    },
+    reducerPath: "testApi",
+    util: {
+      invalidateTags: () => ({type: "testApi/invalidateTags"}),
+      updateQueryData: () => ({type: "testApi/updateQueryData"}),
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: Test double covers only fields used by offline middleware.
+  } as unknown as Api<any, any, any, any>;
+};
+
+describe("isNetworkFetchError", () => {
+  it("returns true for TypeError error name", () => {
+    expect(isNetworkFetchError({error: {name: "TypeError"}})).toBe(true);
+  });
+
+  it("returns true for network error messages", () => {
+    expect(isNetworkFetchError({error: {message: "Failed to fetch"}})).toBe(true);
+    expect(isNetworkFetchError({error: {message: "fetch failed"}})).toBe(true);
+    expect(isNetworkFetchError({error: {message: "Network Error"}})).toBe(true);
+    expect(isNetworkFetchError({error: {message: "Network unavailable"}})).toBe(true);
+    expect(isNetworkFetchError({error: {message: "Load failed"}})).toBe(true);
+  });
+
+  it("returns true for string error fields", () => {
+    expect(isNetworkFetchError({error: "fetch failed"})).toBe(true);
+    expect(isNetworkFetchError({payload: {error: "network error"}})).toBe(true);
+    expect(isNetworkFetchError({error: "Failed to fetch", status: "FETCH_ERROR"})).toBe(true);
+  });
+
+  it("returns false for non-network errors", () => {
+    expect(isNetworkFetchError({error: "Unauthorized", status: "FETCH_ERROR"})).toBe(false);
+    expect(isNetworkFetchError({error: {message: "Unauthorized"}})).toBe(false);
+    expect(isNetworkFetchError(null)).toBe(false);
+    expect(isNetworkFetchError(undefined)).toBe(false);
+    expect(isNetworkFetchError({})).toBe(false);
+  });
+});
+
+describe("shouldReplayQueuedMutation", () => {
+  const baseMutation: QueuedMutation = {
+    args: {body: {title: "Test"}},
+    endpointName: "postTodos",
+    id: "m1",
+    timestamp: "2026-04-15T10:00:00.000Z",
+    type: "create",
+    userId: "user-a",
+  };
+
+  it("replays only mutations owned by the current user", () => {
+    expect(shouldReplayQueuedMutation(baseMutation, "user-a")).toBe(true);
+    expect(shouldReplayQueuedMutation(baseMutation, "user-b")).toBe(false);
+    expect(shouldReplayQueuedMutation(baseMutation, undefined)).toBe(false);
+  });
+
+  it("does not replay legacy mutations without userId", () => {
+    const legacy = {...baseMutation, userId: undefined};
+    expect(shouldReplayQueuedMutation(legacy, "user-a")).toBe(false);
+  });
+});
+
+describe("buildOptimisticCreateItem", () => {
+  const mutation: QueuedMutation = {
+    args: {body: {title: "New"}},
+    endpointName: "postTodos",
+    id: "queue-1",
+    timestamp: "2026-04-15T10:00:00.000Z",
+    type: "create",
+  };
+
+  it("applies temp ids after body spread so client ids cannot win", () => {
+    const item = buildOptimisticCreateItem(mutation, {
+      _id: "client-id",
+      id: "client-id",
+      title: "New",
+    });
+
+    expect(item._id).toBe("temp-queue-1");
+    expect(item.id).toBe("temp-queue-1");
+    expect(item.title).toBe("New");
+    expect(item.created).toBe(mutation.timestamp);
+    expect(item.updated).toBe(mutation.timestamp);
+  });
+});
+
+describe("offlineMiddleware", () => {
+  it("uses list-cache updated timestamp for queued update conflict headers", async () => {
+    const api = createTestApi();
+    const offline = createOfflineMiddleware({
+      api,
+      endpoints: ["patchTodosById"],
+    });
+    const store = configureStore({
+      middleware: (getDefaultMiddleware) =>
+        getDefaultMiddleware({serializableCheck: false}).concat(offline.middleware),
+      reducer: {
+        auth: (state = {userId: "user-a"}) => state,
+        offline: offline.offlineReducer,
+        testApi: testApiReducer,
+      },
+    });
+
+    const rejectedMutation: UnknownAction = {
+      error: {message: "Network unavailable"},
+      meta: {
+        arg: {
+          endpointName: "patchTodosById",
+          originalArgs: {
+            body: {title: "Queued title"},
+            id: "todo-1",
+          },
+        },
+      },
+      type: "testApi/executeMutation/rejected",
+    };
+
+    store.dispatch(rejectedMutation);
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+    const queue = selectOfflineQueue(store.getState());
+    expect(queue).toHaveLength(1);
+    expect(queue[0].baseUpdatedAt).toBe(LIST_UPDATED_AT);
+    expect(queue[0].timestamp).toBe(LIST_UPDATED_AT);
+    expect(queue[0].userId).toBe("user-a");
+  });
+});