@terreno/rtk 0.18.0 → 0.20.0

package/src/useServerStatus.test.ts

@@ -0,0 +1,266 @@
+import {afterEach, beforeEach, 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 {offlineReducer, setOnlineStatus} from "./offlineSlice";
+import {useServerStatus} from "./useServerStatus";
+
+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;
+};
+
+interface MockWindow {
+  addEventListener: (event: string, handler: () => void) => void;
+  removeEventListener: (event: string, handler: () => void) => void;
+  _listeners: Map<string, Set<() => void>>;
+  _dispatch: (event: string) => void;
+}
+
+const createMockWindow = (): MockWindow => {
+  const listeners = new Map<string, Set<() => void>>();
+  return {
+    _dispatch: (event: string) => {
+      for (const handler of listeners.get(event) ?? []) {
+        handler();
+      }
+    },
+    _listeners: listeners,
+    addEventListener: (event: string, handler: () => void) => {
+      if (!listeners.has(event)) {
+        listeners.set(event, new Set());
+      }
+      listeners.get(event)?.add(handler);
+    },
+    removeEventListener: (event: string, handler: () => void) => {
+      listeners.get(event)?.delete(handler);
+    },
+  };
+};
+
+describe("useServerStatus", () => {
+  let store: ReturnType<typeof createTestStore>;
+  let originalFetch: typeof globalThis.fetch;
+  let mockWindow: MockWindow;
+
+  beforeEach(() => {
+    store = createTestStore();
+    originalFetch = globalThis.fetch;
+    mockWindow = createMockWindow();
+    (globalThis as Record<string, unknown>).window = mockWindow;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("returns initial online state from offlineSlice", () => {
+    globalThis.fetch = mock(
+      async () => new Response("ok", {status: 200})
+    ) as unknown as typeof fetch;
+
+    const {result, unmount} = renderHook(() => useServerStatus({skip: true}), {
+      wrapper: createWrapper(store),
+    });
+
+    expect(result.current.isOnline).toBe(true);
+    expect(result.current.queueLength).toBe(0);
+    expect(result.current.isSyncing).toBe(false);
+    unmount();
+  });
+
+  it("skips polling when skip is true", async () => {
+    const fetchFn = mock(async () => new Response("ok", {status: 200}));
+    globalThis.fetch = fetchFn as unknown as typeof fetch;
+
+    const {unmount} = renderHook(() => useServerStatus({skip: true}), {
+      wrapper: createWrapper(store),
+    });
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    });
+
+    expect(fetchFn).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it("dispatches online status when health check succeeds", async () => {
+    store.dispatch(setOnlineStatus(false));
+    const fetchFn = mock(async () => new Response("ok", {status: 200}));
+    globalThis.fetch = fetchFn as unknown as typeof fetch;
+
+    const {unmount} = renderHook(
+      () =>
+        useServerStatus({
+          healthUrl: "http://localhost:4000/health",
+          pollIntervalMs: 60_000,
+        }),
+      {wrapper: createWrapper(store)}
+    );
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    });
+
+    expect(fetchFn).toHaveBeenCalled();
+    expect(store.getState().offline.isOnline).toBe(true);
+    unmount();
+  });
+
+  it("dispatches offline status when health check returns non-ok", async () => {
+    const fetchFn = mock(async () => new Response("error", {status: 500}));
+    globalThis.fetch = fetchFn as unknown as typeof fetch;
+
+    const {unmount} = renderHook(
+      () =>
+        useServerStatus({
+          healthUrl: "http://localhost:4000/health",
+          pollIntervalMs: 60_000,
+        }),
+      {wrapper: createWrapper(store)}
+    );
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    });
+
+    expect(fetchFn).toHaveBeenCalled();
+    expect(store.getState().offline.isOnline).toBe(false);
+    unmount();
+  });
+
+  it("dispatches offline status when health check throws", async () => {
+    const fetchFn = mock(async () => {
+      throw new Error("Network error");
+    });
+    globalThis.fetch = fetchFn as unknown as typeof fetch;
+
+    const {unmount} = renderHook(
+      () =>
+        useServerStatus({
+          healthUrl: "http://localhost:4000/health",
+          pollIntervalMs: 60_000,
+        }),
+      {wrapper: createWrapper(store)}
+    );
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    });
+
+    expect(fetchFn).toHaveBeenCalled();
+    expect(store.getState().offline.isOnline).toBe(false);
+    unmount();
+  });
+
+  it("does not change status when health succeeds and already online", async () => {
+    const fetchFn = mock(async () => new Response("ok", {status: 200}));
+    globalThis.fetch = fetchFn as unknown as typeof fetch;
+
+    const {unmount} = renderHook(
+      () =>
+        useServerStatus({
+          healthUrl: "http://localhost:4000/health",
+          pollIntervalMs: 60_000,
+        }),
+      {wrapper: createWrapper(store)}
+    );
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    });
+
+    expect(fetchFn).toHaveBeenCalled();
+    expect(store.getState().offline.isOnline).toBe(true);
+    unmount();
+  });
+
+  it("accepts custom health URL", async () => {
+    const fetchFn = mock(async () => new Response("ok", {status: 200}));
+    globalThis.fetch = fetchFn as unknown as typeof fetch;
+
+    const {unmount} = renderHook(
+      () =>
+        useServerStatus({
+          healthUrl: "http://custom-api:3000/ping",
+          pollIntervalMs: 60_000,
+          skip: false,
+        }),
+      {wrapper: createWrapper(store)}
+    );
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    });
+
+    expect(fetchFn).toHaveBeenCalled();
+    const callUrl = (fetchFn.mock.calls[0] as unknown[])[0] as string;
+    expect(callUrl).toBe("http://custom-api:3000/ping");
+    unmount();
+  });
+
+  it("dispatches offline when browser fires offline event", async () => {
+    const fetchFn = mock(async () => new Response("ok", {status: 200}));
+    globalThis.fetch = fetchFn as unknown as typeof fetch;
+
+    const {unmount} = renderHook(
+      () =>
+        useServerStatus({
+          healthUrl: "http://localhost:4000/health",
+          pollIntervalMs: 60_000,
+        }),
+      {wrapper: createWrapper(store)}
+    );
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    });
+
+    expect(store.getState().offline.isOnline).toBe(true);
+
+    act(() => {
+      mockWindow._dispatch("offline");
+    });
+
+    expect(store.getState().offline.isOnline).toBe(false);
+    unmount();
+  });
+
+  it("triggers health check when browser fires online event", async () => {
+    store.dispatch(setOnlineStatus(false));
+    const fetchFn = mock(async () => new Response("ok", {status: 200}));
+    globalThis.fetch = fetchFn as unknown as typeof fetch;
+
+    const {unmount} = renderHook(
+      () =>
+        useServerStatus({
+          healthUrl: "http://localhost:4000/health",
+          pollIntervalMs: 60_000,
+        }),
+      {wrapper: createWrapper(store)}
+    );
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    });
+
+    fetchFn.mockClear();
+
+    await act(async () => {
+      mockWindow._dispatch("online");
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    });
+
+    expect(fetchFn).toHaveBeenCalled();
+    unmount();
+  });
+});

package/src/useTerrenoFeatureFlags.test.ts

@@ -0,0 +1,222 @@
+import {afterEach, beforeEach, describe, expect, it, mock} from "bun:test";
+import EventEmitter from "node:events";
+import {NOOP_PROVIDER, OpenFeature} from "@openfeature/web-sdk";
+import {renderHook, waitFor} from "@testing-library/react-native";
+import React, {StrictMode} from "react";
+
+import {useTerrenoFeatureFlags} from "./useTerrenoFeatureFlags";
+
+type TerrenoFlagConfiguration = Record<
+  string,
+  {
+    defaultVariant: string;
+    disabled: boolean;
+    variants: Record<string, boolean | string>;
+  }
+>;
+
+type QueryResult = {
+  data?: TerrenoFlagConfiguration;
+  error?: unknown;
+  isError?: boolean;
+  isFetching?: boolean;
+  isLoading?: boolean;
+  isSuccess?: boolean;
+};
+
+const boolDef = (variant: "on" | "off") => ({
+  defaultVariant: variant,
+  disabled: false,
+  variants: {off: false, on: true},
+});
+
+const buildApi = (queryResult: QueryResult) => {
+  const refetch = mock(() => {});
+  const useTerrenoFlagConfigurationQuery = mock(() => {
+    const hasData = Boolean(queryResult.data);
+    return {
+      data: queryResult.data,
+      error: queryResult.error,
+      isError: queryResult.isError ?? Boolean(queryResult.error),
+      isFetching: queryResult.isFetching ?? false,
+      isLoading: queryResult.isLoading ?? false,
+      isSuccess: queryResult.isSuccess ?? hasData,
+      refetch,
+    };
+  });
+  const api = {
+    injectEndpoints: mock((opts: {endpoints: (builder: unknown) => void}) => {
+      const builder = {
+        query: (def: {query: () => {method: string; url: string}}) => {
+          def.query();
+          return {useQuery: useTerrenoFlagConfigurationQuery};
+        },
+      };
+      opts.endpoints(builder);
+      return {useTerrenoFlagConfigurationQuery};
+    }),
+  };
+  return {api, refetch, useTerrenoFlagConfigurationQuery};
+};
+
+describe("useTerrenoFeatureFlags", () => {
+  beforeEach(async () => {
+    await OpenFeature.setProviderAndWait("feature-flags", NOOP_PROVIDER);
+    await OpenFeature.setProviderAndWait("custom-ff", NOOP_PROVIDER);
+  });
+
+  afterEach(async () => {
+    await OpenFeature.setProviderAndWait("feature-flags", NOOP_PROVIDER);
+    await OpenFeature.setProviderAndWait("custom-ff", NOOP_PROVIDER);
+  });
+
+  it("sets TypedInMemoryProvider and exposes client values after success", async () => {
+    const {api} = buildApi({data: {alpha: boolDef("on")}});
+    const {result} = renderHook(() =>
+      useTerrenoFeatureFlags(api as never, {domain: "feature-flags", userId: "u1"})
+    );
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+    expect(result.current.client.getBooleanValue("alpha", false)).toBe(true);
+    expect(result.current.flags.alpha?.defaultVariant).toBe("on");
+  });
+
+  it("does not leave loading stuck when skip is true", () => {
+    const {api} = buildApi({data: {alpha: boolDef("on")}});
+    const {result} = renderHook(() =>
+      useTerrenoFeatureFlags(api as never, {domain: "feature-flags", skip: true, userId: "u1"})
+    );
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it("does not leave loading stuck when the flag configuration query errors", () => {
+    const {api} = buildApi({
+      error: new Error("request failed"),
+      isError: true,
+      isLoading: false,
+      isSuccess: false,
+    });
+    const {result} = renderHook(() =>
+      useTerrenoFeatureFlags(api as never, {domain: "feature-flags", userId: "u1"})
+    );
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.error).toBeDefined();
+  });
+
+  it("isolates domains so a custom domain does not read another domain's provider", async () => {
+    const {api} = buildApi({data: {alpha: boolDef("on")}});
+    const {result} = renderHook(() =>
+      useTerrenoFeatureFlags(api as never, {domain: "custom-ff", userId: "u1"})
+    );
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+    const defaultClient = OpenFeature.getClient();
+    expect(defaultClient.getBooleanValue("alpha", false)).toBe(false);
+    expect(result.current.client.getBooleanValue("alpha", false)).toBe(true);
+  });
+
+  it("refetches when the socket receives the configured event", async () => {
+    const socket = new EventEmitter();
+    const {api, refetch} = buildApi({data: {alpha: boolDef("off")}});
+    const {result} = renderHook(() =>
+      useTerrenoFeatureFlags(api as never, {
+        domain: "feature-flags",
+        socket: {
+          off: (ev, fn) => {
+            socket.off(ev, fn);
+          },
+          on: (ev, fn) => {
+            socket.on(ev, fn);
+          },
+        },
+        socketEventName: "featureFlagsChanged",
+        userId: "u1",
+      })
+    );
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+    socket.emit("featureFlagsChanged");
+    expect(refetch).toHaveBeenCalled();
+  });
+
+  it("survives React StrictMode double-mount without throwing", async () => {
+    const {api} = buildApi({data: {alpha: boolDef("on")}});
+    const {result} = renderHook(
+      () => useTerrenoFeatureFlags(api as never, {domain: "feature-flags", userId: "u1"}),
+      {
+        wrapper: ({children}: {children: React.ReactNode}) =>
+          React.createElement(StrictMode, null, children),
+      }
+    );
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+    expect(result.current.client.getBooleanValue("alpha", false)).toBe(true);
+  });
+
+  it("re-applies provider when fetched configuration changes", async () => {
+    const built = buildApi({data: {alpha: boolDef("off")}});
+    const {result, rerender} = renderHook(
+      ({data}: {data: TerrenoFlagConfiguration}) => {
+        built.useTerrenoFlagConfigurationQuery.mockImplementation(() => ({
+          data,
+          error: undefined,
+          isError: false,
+          isFetching: false,
+          isLoading: false,
+          isSuccess: true,
+          refetch: built.refetch,
+        }));
+        return useTerrenoFeatureFlags(built.api as never, {domain: "feature-flags", userId: "u1"});
+      },
+      {initialProps: {data: {alpha: boolDef("off")}}}
+    );
+    await waitFor(() => {
+      expect(result.current.client.getBooleanValue("alpha", false)).toBe(false);
+    });
+    rerender({data: {alpha: boolDef("on")}});
+    await waitFor(() => {
+      expect(result.current.client.getBooleanValue("alpha", false)).toBe(true);
+    });
+  });
+});
+
+describe("useTerrenoFeatureFlags ref-count cleanup", () => {
+  /** Dedicated domain so parallel test files do not hold extra `feature-flags` hook refs. */
+  const refcountTestDomain = "terreno-refcount-test-isolation";
+
+  beforeEach(async () => {
+    await OpenFeature.setProviderAndWait(refcountTestDomain, NOOP_PROVIDER);
+  });
+
+  afterEach(async () => {
+    await OpenFeature.setProviderAndWait(refcountTestDomain, NOOP_PROVIDER);
+  });
+
+  it("installs NOOP provider after the last hook instance unmounts", async () => {
+    const {api} = buildApi({data: {alpha: boolDef("on")}});
+    const {unmount} = renderHook(() =>
+      useTerrenoFeatureFlags(api as never, {domain: refcountTestDomain, userId: "u1"})
+    );
+    await waitFor(
+      () => {
+        expect(OpenFeature.getClient(refcountTestDomain).getBooleanValue("alpha", false)).toBe(
+          true
+        );
+      },
+      {timeout: 5000}
+    );
+    unmount();
+    await waitFor(
+      () => {
+        expect(OpenFeature.getClient(refcountTestDomain).getBooleanValue("alpha", false)).toBe(
+          false
+        );
+      },
+      {timeout: 5000}
+    );
+  });
+});

package/src/useTerrenoFeatureFlags.ts

@@ -0,0 +1,226 @@
+import {NOOP_PROVIDER, OpenFeature, TypedInMemoryProvider} from "@openfeature/web-sdk";
+import type {Api} from "@reduxjs/toolkit/query/react";
+import {useCallback, useEffect, useMemo, useState} from "react";
+
+/** Shape returned by `GET .../flagConfiguration` (OpenFeature static flag map). */
+export interface TerrenoFlagDefinition {
+  defaultVariant: string;
+  disabled: boolean;
+  variants: Record<string, boolean | string>;
+}
+
+export type TerrenoFlagConfiguration = Record<string, TerrenoFlagDefinition>;
+
+export interface UseTerrenoFeatureFlagsOptions {
+  basePath?: string;
+  skip?: boolean;
+  /** Current user id — included in RTK cache key and OpenFeature targeting context. */
+  userId?: string | null;
+  /** Optional socket.io client for live flag refresh. */
+  socket?: {
+    off: (event: string, handler: (...args: unknown[]) => void) => void;
+    on: (event: string, handler: (...args: unknown[]) => void) => void;
+  } | null;
+  socketEventName?: string;
+  /** OpenFeature domain — must match `<OpenFeatureProvider domain>` on the client. */
+  domain?: string;
+}
+
+export interface UseTerrenoFeatureFlagsResult {
+  client: ReturnType<typeof OpenFeature.getClient>;
+  error: unknown;
+  flags: TerrenoFlagConfiguration;
+  isLoading: boolean;
+  refetch: () => unknown;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: RTK Query API generic typing is intentionally flexible here.
+type FlagsApi = Api<any, any, any, any>;
+
+// biome-ignore lint/suspicious/noExplicitAny: Endpoint hook is injected dynamically by RTK Query.
+type EnhancedTerrenoFlagsApi = FlagsApi & {useTerrenoFlagConfigurationQuery: any};
+
+const enhancedApiCache = new WeakMap<FlagsApi, Map<string, EnhancedTerrenoFlagsApi>>();
+
+const getEnhancedApi = (api: FlagsApi, basePath: string): EnhancedTerrenoFlagsApi => {
+  let byBase = enhancedApiCache.get(api);
+  if (!byBase) {
+    byBase = new Map();
+    enhancedApiCache.set(api, byBase);
+  }
+  const cached = byBase.get(basePath);
+  if (cached) {
+    return cached;
+  }
+  const enhanced = api.injectEndpoints({
+    endpoints: (builder) => ({
+      terrenoFlagConfiguration: builder.query<TerrenoFlagConfiguration, {cacheKey: string}>({
+        providesTags: (_result, _err, arg) => [{id: arg.cacheKey, type: "feature-flags"}],
+        query: () => ({
+          method: "GET",
+          url: `${basePath}/flagConfiguration`,
+        }),
+      }),
+    }),
+    overrideExisting: false,
+  }) as EnhancedTerrenoFlagsApi;
+  byBase.set(basePath, enhanced);
+  return enhanced;
+};
+
+/** In-flight `useTerrenoFeatureFlags` instances per OpenFeature domain (for last-unmount NOOP cleanup). */
+const terrenoOpenFeatureHookRefCounts = new Map<string, number>();
+
+/** Last in-flight `setProviderAndWait` per OpenFeature domain (shared across hook instances). */
+const domainProviderSwitchPromises = new Map<string, Promise<void>>();
+
+/**
+ * Wires Terreno's bulk `/flagConfiguration` fetch into OpenFeature's
+ * {@link TypedInMemoryProvider} for the given domain. Prefer OpenFeature React
+ * hooks (`useBooleanFlagValue`, etc.) as children of `<OpenFeatureProvider>`.
+ */
+export const useTerrenoFeatureFlags = (
+  api: FlagsApi,
+  options?: UseTerrenoFeatureFlagsOptions
+): UseTerrenoFeatureFlagsResult => {
+  const basePath = options?.basePath ?? "/feature-flags";
+  const domain = options?.domain ?? "feature-flags";
+  const userId = options?.userId ?? null;
+  const skip = options?.skip === true;
+  const socket = options?.socket ?? null;
+  const socketEventName = options?.socketEventName ?? "featureFlagsChanged";
+
+  const enhancedApi = useMemo(() => getEnhancedApi(api, basePath), [api, basePath]);
+  const useTerrenoFlagConfigurationQuery = enhancedApi.useTerrenoFlagConfigurationQuery;
+  const {
+    data,
+    error,
+    isError,
+    isFetching,
+    isLoading: isQueryLoading,
+    isSuccess,
+    refetch,
+  } = useTerrenoFlagConfigurationQuery({cacheKey: userId ?? ""}, {skip});
+
+  const [providerReady, setProviderReady] = useState<boolean>(skip);
+  const client = useMemo(() => OpenFeature.getClient(domain), [domain]);
+
+  useEffect(() => {
+    const prev = terrenoOpenFeatureHookRefCounts.get(domain) ?? 0;
+    terrenoOpenFeatureHookRefCounts.set(domain, prev + 1);
+    return (): void => {
+      const current = terrenoOpenFeatureHookRefCounts.get(domain) ?? 0;
+      const next = current - 1;
+      if (next <= 0) {
+        terrenoOpenFeatureHookRefCounts.delete(domain);
+        void (async (): Promise<void> => {
+          const pending = domainProviderSwitchPromises.get(domain);
+          if (pending) {
+            await pending;
+          }
+          await OpenFeature.setProviderAndWait(domain, NOOP_PROVIDER);
+        })();
+      } else {
+        terrenoOpenFeatureHookRefCounts.set(domain, next);
+      }
+    };
+  }, [domain]);
+
+  useEffect((): void => {
+    if (skip) {
+      return;
+    }
+    void OpenFeature.setContext(domain, {targetingKey: userId ?? ""});
+  }, [domain, skip, userId]);
+
+  useEffect((): void => {
+    if (skip) {
+      setProviderReady(true);
+      return;
+    }
+    setProviderReady(false);
+  }, [skip, userId]);
+
+  useEffect(() => {
+    if (skip || !isSuccess || !data) {
+      return;
+    }
+
+    let cancelled = false;
+
+    const applyProvider = async (): Promise<void> => {
+      const pending = domainProviderSwitchPromises.get(domain);
+      const run = (async (): Promise<void> => {
+        if (pending) {
+          await pending;
+        }
+        await OpenFeature.setProviderAndWait(domain, new TypedInMemoryProvider(data));
+      })();
+      domainProviderSwitchPromises.set(domain, run);
+      try {
+        await run;
+      } finally {
+        if (domainProviderSwitchPromises.get(domain) === run) {
+          domainProviderSwitchPromises.delete(domain);
+        }
+      }
+      if (!cancelled) {
+        setProviderReady(true);
+      }
+    };
+
+    void applyProvider();
+
+    return (): void => {
+      cancelled = true;
+    };
+  }, [data, domain, isSuccess, skip]);
+
+  useEffect(() => {
+    if (!socket) {
+      return;
+    }
+
+    const handler = (): void => {
+      void refetch();
+    };
+
+    socket.on(socketEventName, handler);
+    return (): void => {
+      socket.off(socketEventName, handler);
+    };
+  }, [refetch, socket, socketEventName]);
+
+  const flags = data ?? {};
+
+  const isLoading = useMemo((): boolean => {
+    if (skip) {
+      return false;
+    }
+    if (isError) {
+      return false;
+    }
+    if (!isSuccess || !data) {
+      return true;
+    }
+    if (isQueryLoading || isFetching) {
+      return true;
+    }
+    if (!providerReady) {
+      return true;
+    }
+    return false;
+  }, [data, isError, isFetching, isQueryLoading, isSuccess, providerReady, skip]);
+
+  const stableRefetch = useCallback((): unknown => {
+    return refetch();
+  }, [refetch]);
+
+  return {
+    client,
+    error,
+    flags,
+    isLoading,
+    refetch: stableRefetch,
+  };
+};