@flagward/react 0.2.0 → 0.2.1

package/README.md

@@ -63,27 +63,166 @@ treat any other client-side configuration.
 
 ## Hooks
 
-### `useFlag(key)`
+### Which one
 
-Evaluates a single flag by key.
+Reach for `useFlag`. One flag, one decision, one hook — it is what most
+components need:
+
+```tsx
+const { value, isLoading } = useFlag("new-checkout");
+```
+
+`useFlags` earns its place in three cases:
+
+- **The keys are not known where you write the code** — a debug panel, an admin
+  view, anything that iterates.
+- **You need a flag where a hook cannot go** — inside an event handler, a
+  callback, a conditional branch. Hooks cannot be conditional; `getFlag` can.
+- **A component reads several flags** and one call reads better than five.
+
+### `useFlag(key, context?)`
+
+Evaluates a single flag.
 
 ```tsx
 const { value, isLoading, error } = useFlag("new-dashboard");
 ```
 
 Returns:
-- `value`: `boolean | string | undefined`
+- `value`: `boolean | undefined` — `undefined` while loading, and for a key
+  this environment does not have
 - `isLoading`: `boolean`
 - `error`: `Error | null`
 
+The optional second argument adds to the provider's context for this call
+only. See "Where context comes from" below, which is the part that surprises
+people.
+
 ### `useFlags()`
 
-Returns all flags and helper functions.
+The whole environment at once.
+
+```tsx
+const { flags, isLoading, error, getFlag } = useFlags();
+
+flags;                              // { "new-checkout": true, ... }
+getFlag("show-banner");             // one flag, the provider's context
+getFlag("show-banner", { plan: "pro" });   // one flag, plus this context
+```
+
+`getFlag` is a plain function, so it can be called anywhere — including places
+a hook cannot go.
+
+### Where context comes from
+
+Targeting rules are evaluated against a context, and there are two places it
+can come from. They are not interchangeable:
+
+```tsx
+<FlagwardProvider context={{ plan: "free" }}>   // who the user is
+useFlag("beta", { plan: "pro" })                // just this call
+```
+
+A context passed to `useFlag` belongs to **that call**. It is not published
+anywhere: another component cannot see it, and `useFlags().flags` resolves its
+map against the provider's context alone. So this is not a contradiction —
+
+```tsx
+const { value } = useFlag("beta", { plan: "pro" });   // true
+const { flags } = useFlags();                          // flags.beta === false
+```
+
+— it is two questions with two answers. The call was told `"pro"`; the map was
+not. Deliberately: if a context passed in one component reached another
+component's hook, you would have an invisible channel between parts of an
+application that share nothing.
+
+**So put the user in the provider.** Plan, country, id, locale — whatever your
+rules target — belongs there, where one answer applies everywhere and follows
+the user through signing in and changing plan. Reach for the per-call context
+when what you are evaluating is *not* the current user:
 
 ```tsx
-const { flags, getFlag, isLoading } = useFlags();
+// A list of users. The flag is asked about each row, not about the viewer.
+users.map((u) => <Row key={u.id} badge={getFlag("premium-badge", { plan: u.plan })} />)
+```
 
-const showBanner = getFlag("show-banner");
+### Putting it together
+
+The user lives in the provider, once:
+
+```tsx
+// providers.tsx
+import { FlagwardProvider } from "@flagward/react";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  const { user } = useAuth();
+
+  return (
+    <FlagwardProvider
+      apiKey={import.meta.env.VITE_FLAGWARD_API_KEY}
+      host="https://flags.example.com"
+      context={{ plan: user.plan, country: user.country, id: user.id }}
+    >
+      {children}
+    </FlagwardProvider>
+  );
+}
+```
+
+Signing in or changing plan re-renders this, and every flag in the application
+follows — you do not tell each component separately.
+
+One decision, one flag:
+
+```tsx
+// Checkout.tsx
+function Checkout() {
+  const { value: newCheckout, isLoading } = useFlag("new-checkout");
+
+  if (isLoading) return <LegacyCheckout />;
+
+  return newCheckout ? <NewCheckout /> : <LegacyCheckout />;
+}
+```
+
+A flag inside a handler, where a hook cannot go:
+
+```tsx
+// CheckoutForm.tsx
+function CheckoutForm() {
+  const { getFlag } = useFlags();
+
+  const handleSubmit = (data: FormData) => {
+    if (getFlag("strict-validation") && !isComplete(data)) {
+      return setError("Every field is required.");
+    }
+    submit(data);
+  };
+
+  return <form onSubmit={handleSubmit}>{/* ... */}</form>;
+}
+```
+
+And the one case for a per-call context — the flag is about each row, not about
+whoever is looking:
+
+```tsx
+// UserTable.tsx
+function UserTable({ users }: { users: User[] }) {
+  const { getFlag } = useFlags();
+
+  return (
+    <tbody>
+      {users.map((u) => (
+        <tr key={u.id}>
+          <td>{u.name}</td>
+          <td>{getFlag("premium-badge", { plan: u.plan }) ? "★" : null}</td>
+        </tr>
+      ))}
+    </tbody>
+  );
+}
 ```
 
 ## Provider

package/dist/useFlag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFlag.d.ts","sourceRoot":"","sources":["../src/useFlag.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,WAAW,GAAG,aAAa,CAmC7E"}
+{"version":3,"file":"useFlag.d.ts","sourceRoot":"","sources":["../src/useFlag.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,WAAW,GAAG,aAAa,CA+D7E"}

package/dist/useFlag.js

@@ -1,26 +1,48 @@
-import { useContext } from "react";
+import { useContext, useEffect, useMemo } from "react";
 import { FlagwardContext } from "./context.js";
 import { createLogger, evaluateFlag } from "@flagward/core";
 export function useFlag(key, flagContext) {
     const context = useContext(FlagwardContext);
-    const logger = context.client?.logger ?? createLogger();
-    // Merge provider context with flag-specific context
+    // Memoised so the effect below has a stable dependency. Without a client
+    // this builds a fresh logger, and a new object every render would re-run the
+    // effect on every render for no reason.
+    const logger = useMemo(() => context.client?.logger ?? createLogger(), [context.client]);
     const mergedContext = { ...context.context, ...flagContext };
-    let value;
-    if (!context.client) {
-        logger.error("no-provider", `useFlag("${key}") was called outside FlagwardProvider, so it can only ` +
-            "return undefined. Wrap the tree in <FlagwardProvider>.");
-    }
-    else if (!context.isLoading) {
-        // Evaluated against the data this render was produced from, so the value
-        // shown and the update that caused it can never disagree.
-        value = evaluateFlag(context.flagsData[key], mergedContext);
-        if (value === undefined) {
-            logger.warn(`unknown-flag:${key}`, `Flag "${key}" is not in this environment, so it reads as undefined. ` +
-                "Check the key, and that the flag exists in the environment this " +
-                "API key belongs to.");
+    /**
+     * Resolves the flag, and does nothing else.
+     *
+     * Evaluated against the data this render was produced from, so the value
+     * shown and the update that caused it can never disagree.
+     */
+    const value = !context.client || context.isLoading
+        ? undefined
+        : evaluateFlag(context.flagsData[key], mergedContext);
+    /**
+     * Reports what the caller cannot see, after the render rather than during it.
+     *
+     * Rendering must be a pure calculation. React re-renders on its own schedule
+     * -- a parent updating, an unrelated state change, StrictMode running the
+     * render twice on purpose to expose exactly this -- so a render that writes
+     * to the console produces a number of warnings that reflects React's
+     * scheduling rather than anything that went wrong. The output was bounded
+     * only because the logger deduplicates.
+     *
+     * The unknown-key warning waits for loading to finish. Reporting earlier
+     * would name every flag on every page load, when the only thing wrong is
+     * that the answer has not arrived yet.
+     */
+    useEffect(() => {
+        if (!context.client) {
+            logger.error("no-provider", `useFlag("${key}") was called outside FlagwardProvider, so it can only ` +
+                "return undefined. Wrap the tree in <FlagwardProvider>.");
+            return;
         }
-    }
+        if (context.isLoading || value !== undefined)
+            return;
+        logger.warn(`unknown-flag:${key}`, `Flag "${key}" is not in this environment, so it reads as undefined. ` +
+            "Check the key, and that the flag exists in the environment this " +
+            "API key belongs to.");
+    }, [context.client, context.isLoading, value, key, logger]);
     return {
         value,
         isLoading: context.isLoading,

package/dist/useFlag.js.map

@@ -1 +1 @@
-{"version":3,"file":"useFlag.js","sourceRoot":"","sources":["../src/useFlag.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAU5D,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,WAAyB;IAC5D,MAAM,OAAO,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,MAAM,IAAI,YAAY,EAAE,CAAC;IAExD,oDAAoD;IACpD,MAAM,aAAa,GAAG,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,WAAW,EAAE,CAAC;IAE7D,IAAI,KAA0B,CAAC;IAE/B,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QACpB,MAAM,CAAC,KAAK,CACV,aAAa,EACb,YAAY,GAAG,yDAAyD;YACtE,wDAAwD,CAC3D,CAAC;IACJ,CAAC;SAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QAC9B,yEAAyE;QACzE,0DAA0D;QAC1D,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC,CAAC;QAE5D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,CAAC,IAAI,CACT,gBAAgB,GAAG,EAAE,EACrB,SAAS,GAAG,0DAA0D;gBACpE,kEAAkE;gBAClE,qBAAqB,CACxB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK;QACL,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"useFlag.js","sourceRoot":"","sources":["../src/useFlag.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAU5D,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,WAAyB;IAC5D,MAAM,OAAO,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC;IAE5C,yEAAyE;IACzE,6EAA6E;IAC7E,wCAAwC;IACxC,MAAM,MAAM,GAAG,OAAO,CACpB,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,IAAI,YAAY,EAAE,EAC9C,CAAC,OAAO,CAAC,MAAM,CAAC,CACjB,CAAC;IAEF,MAAM,aAAa,GAAG,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,WAAW,EAAE,CAAC;IAE7D;;;;;OAKG;IACH,MAAM,KAAK,GACT,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,SAAS;QAClC,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC,CAAC;IAE1D;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YACpB,MAAM,CAAC,KAAK,CACV,aAAa,EACb,YAAY,GAAG,yDAAyD;gBACtE,wDAAwD,CAC3D,CAAC;YACF,OAAO;QACT,CAAC;QAED,IAAI,OAAO,CAAC,SAAS,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO;QAErD,MAAM,CAAC,IAAI,CACT,gBAAgB,GAAG,EAAE,EACrB,SAAS,GAAG,0DAA0D;YACpE,kEAAkE;YAClE,qBAAqB,CACxB,CAAC;IACJ,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;IAE5D,OAAO;QACL,KAAK;QACL,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC;AACJ,CAAC"}

package/dist/useFlags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFlags.d.ts","sourceRoot":"","sources":["../src/useFlags.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,WAAW,KAAK,OAAO,GAAG,SAAS,CAAC;CAC1E;AAED,wBAAgB,QAAQ,IAAI,cAAc,CAkCzC"}
+{"version":3,"file":"useFlags.d.ts","sourceRoot":"","sources":["../src/useFlags.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,WAAW,KAAK,OAAO,GAAG,SAAS,CAAC;CAC1E;AAED,wBAAgB,QAAQ,IAAI,cAAc,CAoDzC"}

package/dist/useFlags.js

@@ -1,13 +1,27 @@
-import { useContext } from "react";
+import { useContext, useEffect, useMemo } from "react";
 import { FlagwardContext } from "./context.js";
 import { createLogger, evaluateFlag, toFlagMap } from "@flagward/core";
 export function useFlags() {
     const context = useContext(FlagwardContext);
-    const logger = context.client?.logger ?? createLogger();
-    if (!context.client) {
+    // Memoised so the effect below has a stable dependency. See useFlag.
+    const logger = useMemo(() => context.client?.logger ?? createLogger(), [context.client]);
+    // Reported after the render, not during it: rendering must be a pure
+    // calculation, and React runs it as often as it likes.
+    useEffect(() => {
+        if (context.client)
+            return;
         logger.error("no-provider", "useFlags() was called outside FlagwardProvider, so it can only return " +
             "an empty set. Wrap the tree in <FlagwardProvider>.");
-    }
+    }, [context.client, logger]);
+    /**
+     * Resolves one flag, and reports a key this environment does not have.
+     *
+     * Reporting inline here, where the render moved it into an effect, is not an
+     * inconsistency. This is a function the caller invokes: it runs when asked
+     * to, exactly as often as it is asked, so a warning is a direct answer to a
+     * direct question. A render runs on React's schedule instead, which is why
+     * the reporting had to leave it.
+     */
     const getFlag = (key, flagContext) => {
         const mergedContext = { ...context.context, ...flagContext };
         const value = evaluateFlag(context.flagsData[key], mergedContext);

package/dist/useFlags.js.map

@@ -1 +1 @@
-{"version":3,"file":"useFlags.js","sourceRoot":"","sources":["../src/useFlags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAUvE,MAAM,UAAU,QAAQ;IACtB,MAAM,OAAO,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,MAAM,IAAI,YAAY,EAAE,CAAC;IAExD,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QACpB,MAAM,CAAC,KAAK,CACV,aAAa,EACb,wEAAwE;YACtE,oDAAoD,CACvD,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,GAAW,EAAE,WAAyB,EAAuB,EAAE;QAC9E,MAAM,aAAa,GAAG,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,WAAW,EAAE,CAAC;QAC7D,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC,CAAC;QAElE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,CAAC,IAAI,CACT,gBAAgB,GAAG,EAAE,EACrB,SAAS,GAAG,0DAA0D;gBACpE,kEAAkE;gBAClE,qBAAqB,CACxB,CAAC;QACJ,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC;QACpD,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,OAAO;KACR,CAAC;AACJ,CAAC"}
+{"version":3,"file":"useFlags.js","sourceRoot":"","sources":["../src/useFlags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAUvE,MAAM,UAAU,QAAQ;IACtB,MAAM,OAAO,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC;IAE5C,qEAAqE;IACrE,MAAM,MAAM,GAAG,OAAO,CACpB,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,IAAI,YAAY,EAAE,EAC9C,CAAC,OAAO,CAAC,MAAM,CAAC,CACjB,CAAC;IAEF,qEAAqE;IACrE,uDAAuD;IACvD,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,OAAO,CAAC,MAAM;YAAE,OAAO;QAE3B,MAAM,CAAC,KAAK,CACV,aAAa,EACb,wEAAwE;YACtE,oDAAoD,CACvD,CAAC;IACJ,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAE7B;;;;;;;;OAQG;IACH,MAAM,OAAO,GAAG,CAAC,GAAW,EAAE,WAAyB,EAAuB,EAAE;QAC9E,MAAM,aAAa,GAAG,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,WAAW,EAAE,CAAC;QAC7D,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC,CAAC;QAElE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,CAAC,IAAI,CACT,gBAAgB,GAAG,EAAE,EACrB,SAAS,GAAG,0DAA0D;gBACpE,kEAAkE;gBAClE,qBAAqB,CACxB,CAAC;QACJ,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC;QACpD,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/version.d.ts

@@ -4,5 +4,5 @@
  * GENERATED by scripts/sync-version.mjs from package.json. Do not edit: the
  * next build overwrites it, and a test fails if the two disagree.
  */
-export declare const SDK_VERSION = "0.2.0";
+export declare const SDK_VERSION = "0.2.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -4,5 +4,5 @@
  * GENERATED by scripts/sync-version.mjs from package.json. Do not edit: the
  * next build overwrites it, and a test fails if the two disagree.
  */
-export const SDK_VERSION = "0.2.0";
+export const SDK_VERSION = "0.2.1";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flagward/react",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "React SDK for Flagward - Feature Flags as a Service",
   "type": "module",
   "main": "dist/index.js",