Merge branch 'codex/refactor-react-get-types'

Author: sandersonstabo

README.md

@@ -24,3 +24,16 @@ export function Root() {
   );
 }
 ```
+
+You can also pass a client directly when you want to read Barekey values before any provider exists:
+
+```tsx
+import { PublicBarekeyClient } from "@barekey/sdk/public";
+import { useBarekey } from "@barekey/react";
+import barekeyConfig from "../barekey.json" with { type: "json" };
+
+function Bootstrap() {
+  const env = useBarekey(new PublicBarekeyClient({ json: barekeyConfig }));
+  return <div>{env.get("PUBLIC_THEME")}</div>;
+}
+```

spec/index.ts

@@ -3,7 +3,7 @@ import { PublicBarekeyClient } from "@barekey/sdk/public";
 import { Component, createElement } from "react";
 import { act, create, type ReactTestRenderer } from "react-test-renderer";
 
-import { BarekeyProvider, useBarekey } from "../src/index.js";
+import { BarekeyProvider, type BarekeyReactEnv, useBarekey } from "../src/index.js";
 import { resetBarekeyReactCacheForTests } from "../src/cache.js";
 import { resetLeakGuardForTests } from "../src/leak-guard.js";
 
@@ -280,7 +280,7 @@ describe("@barekey/react", () => {
     });
   });
 
-  test("supports reads through a caller-provided public client", async () => {
+  test("supports reads through a caller-provided public client without a provider", async () => {
     (
       globalThis as typeof globalThis & {
         IS_REACT_ACT_ENVIRONMENT?: boolean;
@@ -308,7 +308,7 @@ describe("@barekey/react", () => {
     }) as typeof globalThis.fetch;
 
     function Theme() {
-      const env = useBarekey();
+      const env = useBarekey(client);
       return createElement("span", null, env.get("PUBLIC_THEME"));
     }
 
@@ -325,7 +325,6 @@ describe("@barekey/react", () => {
     await act(async () => {
       renderer = create(
         renderWithClient({
-          client,
           children: createElement(Theme),
         }),
       );
@@ -415,7 +414,103 @@ describe("@barekey/react", () => {
     expect(testDocument.getOverlay()?.innerHTML).toContain("<img src=x onerror=alert("xss")>");
   });
 
-  test("throws a clear error when used outside BarekeyProvider", () => {
+  test("prefers an explicit client over provider context", async () => {
+    (
+      globalThis as typeof globalThis & {
+        IS_REACT_ACT_ENVIRONMENT?: boolean;
+      }
+    ).IS_REACT_ACT_ENVIRONMENT = true;
+    globalThis.fetch = (async (_input, init) => {
+      expect(JSON.parse(String(init?.body ?? ""))).toEqual({
+        orgSlug: "acme",
+        projectSlug: "web-react-explicit",
+        stageSlug: "production",
+        names: ["PUBLIC_THEME"],
+      });
+
+      return jsonResponse({
+        definitions: [
+          {
+            name: "PUBLIC_THEME",
+            kind: "secret",
+            declaredType: "string",
+            visibility: "public",
+            value: "dark",
+          },
+        ],
+      });
+    }) as typeof globalThis.fetch;
+
+    const providerClient = new PublicBarekeyClient({
+      organization: "acme",
+      project: "web-react-provider",
+      environment: "production",
+      baseUrl: "https://api.example.test",
+    });
+    const explicitClient = new PublicBarekeyClient({
+      organization: "acme",
+      project: "web-react-explicit",
+      environment: "production",
+      baseUrl: "https://api.example.test",
+    });
+
+    function Theme() {
+      const env = useBarekey(explicitClient);
+      return createElement("span", null, env.get("PUBLIC_THEME"));
+    }
+
+    let renderer!: ReactTestRenderer;
+    await act(async () => {
+      renderer = create(
+        renderWithClient({
+          client: providerClient,
+          children: createElement(Theme),
+        }),
+      );
+      await Promise.resolve();
+    });
+
+    expect(renderer.toJSON()).toEqual({
+      type: "span",
+      props: {},
+      children: ["dark"],
+    });
+  });
+
+  test("returns a stable env object when the resolved client stays the same", () => {
+    (
+      globalThis as typeof globalThis & {
+        IS_REACT_ACT_ENVIRONMENT?: boolean;
+      }
+    ).IS_REACT_ACT_ENVIRONMENT = true;
+
+    const client = new PublicBarekeyClient({
+      organization: "acme",
+      project: "web-react-stable-env",
+      environment: "production",
+      baseUrl: "https://api.example.test",
+    });
+    const seen: Array<BarekeyReactEnv> = [];
+
+    function StableEnvProbe() {
+      const env = useBarekey(client);
+      seen.push(env);
+      return createElement("span", null, "ok");
+    }
+
+    let renderer!: ReactTestRenderer;
+    act(() => {
+      renderer = create(createElement(StableEnvProbe));
+    });
+    act(() => {
+      renderer.update(createElement(StableEnvProbe));
+    });
+
+    expect(seen).toHaveLength(2);
+    expect(seen[0]).toBe(seen[1]);
+  });
+
+  test("throws a clear error when no client is provided and no provider exists", () => {
     (
       globalThis as typeof globalThis & {
         IS_REACT_ACT_ENVIRONMENT?: boolean;
@@ -440,7 +535,7 @@ describe("@barekey/react", () => {
       type: "span",
       props: {},
       children: [
-        "[barekey/react] useBarekey() must be used within <BarekeyProvider client={new PublicBarekeyClient(...)} ...>.",
+        "[barekey/react] useBarekey() requires a PublicBarekeyClient argument or a parent <BarekeyProvider client={new PublicBarekeyClient(...)} ...>.",
       ],
     });
   });

src/index.ts

@@ -7,6 +7,7 @@ import {
   createElement,
   Suspense,
   useContext,
+  useMemo,
   type ReactElement,
   type ReactNode,
 } from "react";
@@ -54,25 +55,7 @@ export type BarekeyProviderProps = {
 
 const BarekeyContext = createContext<BarekeyReactClient | null>(null);
 
-export function BarekeyProvider(props: BarekeyProviderProps): ReactElement {
-  return createElement(BarekeyContext.Provider, {
-    value: props.client,
-    children: createElement(Suspense, {
-      fallback: props.fallback ?? null,
-      children: props.children,
-    }),
-  });
-}
-
-export function useBarekey() {
-  const client = useContext(BarekeyContext);
-  if (client === null) {
-    throw new Error(
-      "[barekey/react] useBarekey() must be used within <BarekeyProvider client={new PublicBarekeyClient(...)} ...>.",
-    );
-  }
-  const runtimeClient = client;
-
+function createBarekeyEnv(runtimeClient: BarekeyReactClient): BarekeyReactEnv {
   function get<TKey extends BarekeyReactAnyKey>(
     name: TKey,
     options?: BarekeyGetOptions,
@@ -93,3 +76,25 @@ export function useBarekey() {
     get,
   };
 }
+
+export function BarekeyProvider(props: BarekeyProviderProps): ReactElement {
+  return createElement(BarekeyContext.Provider, {
+    value: props.client,
+    children: createElement(Suspense, {
+      fallback: props.fallback ?? null,
+      children: props.children,
+    }),
+  });
+}
+
+export function useBarekey(client?: BarekeyReactClient) {
+  const contextClient = useContext(BarekeyContext);
+  const resolvedClient = client ?? contextClient;
+  if (resolvedClient === null) {
+    throw new Error(
+      "[barekey/react] useBarekey() requires a PublicBarekeyClient argument or a parent <BarekeyProvider client={new PublicBarekeyClient(...)} ...>.",
+    );
+  }
+  const runtimeClient = resolvedClient;
+  return useMemo(() => createBarekeyEnv(runtimeClient), [runtimeClient]);
+}

src/index.typecheck.ts

@@ -1,21 +1,21 @@
-import { PublicBarekeyClient, type Env, type Secret } from "@barekey/sdk/public";
+import { PublicBarekeyClient, type Env } from "@barekey/sdk/public";
 import { createElement } from "react";
 
-import { BarekeyProvider, type BarekeyReactEnv } from "./index.js";
+import { BarekeyProvider, type BarekeyReactEnv, useBarekey } from "./index.js";
 
 declare module "@barekey/sdk/public" {
   interface BarekeyPublicGeneratedTypeMap {
     PUBLIC_THEME: Env<{
-      Mode: Secret;
+      Type: "light" | "dark";
+      Kind: "secret";
       Visibility: "public";
       Rollout: never;
-      Type: "light" | "dark";
     }>;
     PUBLIC_TITLE: Env<{
-      Mode: Secret;
+      Type: string;
+      Kind: "secret";
       Visibility: "public";
       Rollout: never;
-      Type: string;
     }>;
   }
 }
@@ -39,34 +39,47 @@ createElement(BarekeyProvider, {
   client,
   fallback: null,
 });
+const envFromClient = useBarekey(client);
+const knownValueFromClient = envFromClient.get("PUBLIC_THEME");
 
 type _knownValueStaysTyped = Assert<
   IsEqual<
     typeof knownValue,
     Env<{
-      Mode: Secret;
+      Type: "light" | "dark";
+      Kind: "secret";
       Visibility: "public";
       Rollout: never;
-      Type: "light" | "dark";
     }>
   >
 >;
 type _unknownValueFallsBackToUnknown = Assert<IsEqual<typeof unknownValue, unknown>>;
+type _knownValueFromClientStaysTyped = Assert<
+  IsEqual<
+    typeof knownValueFromClient,
+    Env<{
+      Type: "light" | "dark";
+      Kind: "secret";
+      Visibility: "public";
+      Rollout: never;
+    }>
+  >
+>;
 type _tupleValueMapsKnownAndUnknownKeys = Assert<
   IsEqual<
     typeof tupleValue,
     readonly [
       Env<{
-        Mode: Secret;
+        Type: string;
+        Kind: "secret";
         Visibility: "public";
         Rollout: never;
-        Type: string;
       }>,
       Env<{
-        Mode: Secret;
+        Type: "light" | "dark";
+        Kind: "secret";
         Visibility: "public";
         Rollout: never;
-        Type: "light" | "dark";
       }>,
       unknown,
     ]
@@ -77,10 +90,10 @@ type _arrayValueFallsBackToTupleInference = Assert<
     typeof arrayValue,
     readonly [
       Env<{
-        Mode: Secret;
+        Type: string;
+        Kind: "secret";
         Visibility: "public";
         Rollout: never;
-        Type: string;
       }>,
       unknown,
     ]