@terreno/rtk 0.19.0 → 0.20.0

package/src/useFeatureFlags.ts

@@ -1,5 +1,6 @@
 import type {Api} from "@reduxjs/toolkit/query/react";
-import {useCallback, useEffect, useRef} from "react";
+import {useCallback, useEffect, useMemo, useRef} from "react";
+import {useTerrenoFeatureFlags} from "./useTerrenoFeatureFlags";
 
 interface FlagValues {
   [key: string]: boolean | string | null;
@@ -8,56 +9,19 @@ interface FlagValues {
 // 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 EnhancedFlagsApi = FlagsApi & {useEvaluateFeatureFlagsQuery: any};
-
-/**
- * Cache the enhanced api per (api, basePath). `injectEndpoints` logs a console
- * error in development whenever an endpoint with the same name is re-injected
- * with `overrideExisting: false`, so calling it on every render of every
- * consumer would flood the console. WeakMap-by-api lets the GC reclaim entries
- * when the api object is unreachable.
- */
-const enhancedApiCache = new WeakMap<FlagsApi, Map<string, EnhancedFlagsApi>>();
-
-const getEnhancedApi = (api: FlagsApi, basePath: string): EnhancedFlagsApi => {
-  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) => ({
-      evaluateFeatureFlags: builder.query<FlagValues, void>({
-        query: () => ({
-          method: "GET",
-          url: `${basePath}/evaluate`,
-        }),
-      }),
-    }),
-    overrideExisting: false,
-  }) as EnhancedFlagsApi;
-  byBase.set(basePath, enhanced);
-  return enhanced;
-};
-
 interface UseFeatureFlagsResult {
+  error: unknown;
   flags: FlagValues;
   getFlag: (key: string) => boolean;
   getVariant: (key: string) => string | null;
   isLoading: boolean;
-  error: unknown;
   refetch: () => void;
 }
 
 /**
  * Creates feature flag accessors from an RTK Query API instance.
  *
- * Injects a `GET {basePath}/evaluate` endpoint into the API and returns
+ * Injects a `GET {basePath}/flagConfiguration` endpoint into the API and returns
  * accessors for reading flag values. Fetches once on mount and caches via
  * RTK Query. Both `api` and `basePath` should be stable references.
  *
@@ -70,116 +34,148 @@ interface UseFeatureFlagsResult {
  * ```
  */
 export interface UseFeatureFlagsOptions {
-  /**
-   * Base path for the feature-flags endpoint. Defaults to "/feature-flags".
-   */
   basePath?: string;
-  /**
-   * When true, the underlying evaluate query is not fired. Use this to avoid
-   * fetching before the user is authenticated.
-   */
+  domain?: string;
   skip?: boolean;
+  socket?: {
+    off: (event: string, handler: (...args: unknown[]) => void) => void;
+    on: (event: string, handler: (...args: unknown[]) => void) => void;
+  } | null;
+  socketEventName?: string;
+  userId?: string | null;
 }
 
 interface ResolvedFeatureFlagsOptions {
   basePath: string;
+  domain: string;
   skip: boolean;
+  socket?: UseFeatureFlagsOptions["socket"];
+  socketEventName?: string;
+  userId?: string | null;
 }
 
 /**
  * Normalizes the legacy-compatible `basePathOrOptions` argument into a
- * `{basePath, skip}` pair with defaults applied.
- *
- * - `undefined` -> `{basePath: "/feature-flags", skip: false}`
- * - `string`    -> `{basePath: <string>, skip: false}` (legacy form)
- * - `object`    -> `{basePath: opts.basePath ?? "/feature-flags", skip: opts.skip ?? false}`
+ * `{basePath, skip, ...}` pair with defaults applied.
  */
 export const resolveFeatureFlagsOptions = (
   basePathOrOptions?: string | UseFeatureFlagsOptions
 ): ResolvedFeatureFlagsOptions => {
-  const {basePath = "/feature-flags", skip = false} =
+  const raw =
     typeof basePathOrOptions === "string"
       ? {basePath: basePathOrOptions, skip: false}
       : (basePathOrOptions ?? {});
-  return {basePath, skip};
+  return {
+    basePath: raw.basePath ?? "/feature-flags",
+    domain: raw.domain ?? "feature-flags",
+    skip: raw.skip ?? false,
+    socket: raw.socket,
+    socketEventName: raw.socketEventName,
+    userId: raw.userId,
+  };
 };
 
-// Overloaded signature preserves backwards compatibility with callers that
-// pass a string basePath as the second argument.
-export function useFeatureFlags(
+export const useFeatureFlags = (
   api: FlagsApi,
   basePathOrOptions?: string | UseFeatureFlagsOptions
-): UseFeatureFlagsResult {
-  const {basePath, skip} = resolveFeatureFlagsOptions(basePathOrOptions);
-
-  const enhancedApi = getEnhancedApi(api, basePath);
-  const useEvaluateQuery = enhancedApi.useEvaluateFeatureFlagsQuery;
-  const {data, isLoading, error, refetch} = useEvaluateQuery(undefined, {skip});
-  const evaluateStartedAtRef = useRef<number | null>(null);
+): UseFeatureFlagsResult => {
+  const {basePath, domain, skip, socket, socketEventName, userId} =
+    resolveFeatureFlagsOptions(basePathOrOptions);
+
+  const {
+    client,
+    error,
+    flags: rawFlags,
+    isLoading,
+    refetch,
+  } = useTerrenoFeatureFlags(api, {
+    basePath,
+    domain,
+    skip,
+    socket,
+    socketEventName,
+    userId,
+  });
+
+  const fetchStartedAtRef = useRef<number | null>(null);
 
-  const flags: FlagValues = data ?? {};
-
-  // Log when evaluate request enters loading state so client timing can be measured.
   useEffect((): void => {
-    if (!isLoading || evaluateStartedAtRef.current !== null) {
+    if (!isLoading || fetchStartedAtRef.current !== null) {
       return;
     }
 
-    evaluateStartedAtRef.current = Date.now();
-    console.debug("[feature-flags] evaluate request started", {
+    fetchStartedAtRef.current = Date.now();
+    console.debug("[feature-flags] flagConfiguration request started", {
       basePath,
     });
   }, [basePath, isLoading]);
 
-  // Log evaluate success with duration and number of resolved flag values.
   useEffect((): void => {
-    if (!data || evaluateStartedAtRef.current === null) {
+    if (!error || fetchStartedAtRef.current === null) {
       return;
     }
 
-    const durationMs = Date.now() - evaluateStartedAtRef.current;
-    evaluateStartedAtRef.current = null;
-    console.debug("[feature-flags] evaluate request completed", {
+    const durationMs = Date.now() - fetchStartedAtRef.current;
+    fetchStartedAtRef.current = null;
+    console.debug("[feature-flags] flagConfiguration request failed", {
       basePath,
       durationMs,
-      evaluatedFlagCount: Object.keys(flags).length,
-      evaluatedFlags: flags,
+      error,
     });
-  }, [basePath, data, flags]);
+  }, [basePath, error]);
+
+  const flatFlags = useMemo((): FlagValues => {
+    const out: FlagValues = {};
+    for (const [key, def] of Object.entries(rawFlags)) {
+      const value = def.variants[def.defaultVariant];
+      out[key] = value ?? null;
+    }
+    return out;
+  }, [rawFlags]);
 
-  // Log evaluate failures with duration so request issues can be correlated.
   useEffect((): void => {
-    if (!error || evaluateStartedAtRef.current === null) {
+    if (Object.keys(flatFlags).length === 0 || fetchStartedAtRef.current === null) {
+      return;
+    }
+
+    if (isLoading) {
       return;
     }
 
-    const durationMs = Date.now() - evaluateStartedAtRef.current;
-    evaluateStartedAtRef.current = null;
-    console.debug("[feature-flags] evaluate request failed", {
+    const durationMs = Date.now() - fetchStartedAtRef.current;
+    fetchStartedAtRef.current = null;
+    console.debug("[feature-flags] flagConfiguration request completed", {
       basePath,
       durationMs,
-      error,
+      evaluatedFlagCount: Object.keys(flatFlags).length,
+      evaluatedFlags: flatFlags,
     });
-  }, [basePath, error]);
+  }, [basePath, flatFlags, isLoading]);
 
   const getFlag = useCallback(
     (key: string): boolean => {
-      const value = flags[key];
-      return value === true;
+      return client.getBooleanValue(key, false);
     },
-    [flags]
+    [client]
   );
 
   const getVariant = useCallback(
     (key: string): string | null => {
-      const value = flags[key];
-      if (typeof value === "string") {
-        return value;
+      if (!rawFlags[key]) {
+        return null;
+      }
+      const value = client.getStringValue(key, "");
+      if (value === "") {
+        return null;
       }
-      return null;
+      return value;
     },
-    [flags]
+    [client, rawFlags]
   );
 
-  return {error, flags, getFlag, getVariant, isLoading, refetch};
-}
+  const stableRefetch = useCallback((): void => {
+    void refetch();
+  }, [refetch]);
+
+  return {error, flags: flatFlags, getFlag, getVariant, isLoading, refetch: stableRefetch};
+};

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}
+    );
+  });
+});