allow configuring or disabling visitorKey cookie (#55)

* allow configuring or disabling visitorKey cookie

* use default serializeVisitorKeyCookie for example

Author: dferber90

.changeset/small-tables-know.md

@@ -0,0 +1,7 @@
+---
+"@happykit/flags": minor
+---
+
+allow disabling visitor key cookie
+
+You can now configure or disable the visitor key cookie `@happykit/flags` sets by default. You can pass a `serializeVisitorKeyCookie` function to the options when calling `createUseFlags` and `createGetFlags`.

example/flags/config.ts

@@ -13,4 +13,7 @@ export const config: Configuration<AppFlags> = {
   // You can just delete this line in your own application.
   // It's only here because we use it while working on @happykit/flags itself.
   endpoint: process.env.NEXT_PUBLIC_FLAGS_ENDPOINT,
+
+  // You can uncomment this if you do not want to set the visitorKey cookie
+  // serializeVisitorKeyCookie: () => null,
 };

package/src/client.ts

@@ -23,7 +23,6 @@ import {
 import {
   deepEqual,
   getCookie,
-  serializeVisitorKeyCookie,
   combineRawFlagsWithDefaultFlags,
   ObjectMap,
   has,
@@ -165,134 +164,139 @@ function canSettle<F extends Flags>(state: State<F>) {
   );
 }
 
-/**
- * The reducer returns a tuple of [state, effects].
- *
- * effects is an array of effects to execute. The emitted effects are then later
- * executed in another hook.
- *
- * This pattern is basically a hand-rolled version of
- * https://github.com/davidkpiano/useEffectReducer
- *
- * We use a hand-rolled version to keep the size of this package minimal.
- */
-function reducer<F extends Flags>(
-  tuple: readonly [State<F>, Effect[]],
-  action: Action<F>
-): readonly [State<F>, Effect[]] {
-  const [state /* and effects */] = tuple;
-
-  switch (action.type) {
-    case "evaluate": {
-      const cachedOutcome = cache.get<SuccessOutcome<F>>(action.input);
-
-      const [effects, pending] = createFetchEffects<F>(
-        action.input,
-        state.pending
-      );
-
-      // action.input will always differ from state.input, because we do not
-      // dispatch "evaluate" otherwise
-      return [
-        {
-          name: "evaluating",
-          input: action.input,
-          cachedOutcome,
-          pending,
-        },
-        effects,
-      ];
-    }
-    case "revalidate": {
-      if (state.name === "empty") return tuple;
-
-      const input = action.input || state.input;
-      const [effects, pending] = createFetchEffects<F>(input, state.pending);
-
-      if (state.name === "succeeded")
+function createReducer<F extends Flags>(config: FullConfiguration<F>) {
+  /**
+   * The reducer returns a tuple of [state, effects].
+   *
+   * effects is an array of effects to execute. The emitted effects are then later
+   * executed in another hook.
+   *
+   * This pattern is basically a hand-rolled version of
+   * https://github.com/davidkpiano/useEffectReducer
+   *
+   * We use a hand-rolled version to keep the size of this package minimal.
+   */
+  return function reducer<F extends Flags>(
+    tuple: readonly [State<F>, Effect[]],
+    action: Action<F>
+  ): readonly [State<F>, Effect[]] {
+    const [state /* and effects */] = tuple;
+
+    switch (action.type) {
+      case "evaluate": {
+        const cachedOutcome = cache.get<SuccessOutcome<F>>(action.input);
+
+        const [effects, pending] = createFetchEffects<F>(
+          action.input,
+          state.pending
+        );
+
+        // action.input will always differ from state.input, because we do not
+        // dispatch "evaluate" otherwise
         return [
           {
-            name: "revalidating-after-success",
-            input: state.input,
-            outcome: state.outcome,
-            cachedOutcome: state.cachedOutcome,
+            name: "evaluating",
+            input: action.input,
+            cachedOutcome,
             pending,
           },
           effects,
         ];
+      }
+      case "revalidate": {
+        if (state.name === "empty") return tuple;
 
-      if (state.name === "failed")
-        return [
-          {
-            name: "revalidating-after-failure",
-            input: state.input,
-            outcome: state.outcome,
-            cachedOutcome: state.cachedOutcome,
-            pending,
-          },
-          effects,
-        ];
+        const input = action.input || state.input;
+        const [effects, pending] = createFetchEffects<F>(input, state.pending);
+
+        if (state.name === "succeeded")
+          return [
+            {
+              name: "revalidating-after-success",
+              input: state.input,
+              outcome: state.outcome,
+              cachedOutcome: state.cachedOutcome,
+              pending,
+            },
+            effects,
+          ];
+
+        if (state.name === "failed")
+          return [
+            {
+              name: "revalidating-after-failure",
+              input: state.input,
+              outcome: state.outcome,
+              cachedOutcome: state.cachedOutcome,
+              pending,
+            },
+            effects,
+          ];
+
+        if (state.name === "evaluating")
+          return [
+            {
+              name: "evaluating",
+              input: state.input,
+              outcome: state.outcome,
+              cachedOutcome: state.cachedOutcome,
+              pending,
+            },
+            effects,
+          ];
 
-      if (state.name === "evaluating")
+        return tuple;
+      }
+      case "settle/failure": {
+        if (!canSettle(state)) return tuple;
+
+        // ignore outdated responses
+        if (state.pending?.id !== action.id) return tuple;
+
+        if (action.thrownError) {
+          console.error("@happykit/flags: Failed to load flags");
+          console.error(action.thrownError);
+        }
+
+        const cachedOutcome = cache.get<SuccessOutcome<F>>(action.input);
         return [
           {
-            name: "evaluating",
-            input: state.input,
-            outcome: state.outcome,
-            cachedOutcome: state.cachedOutcome,
-            pending,
+            name: "failed",
+            input: action.input,
+            outcome: action.outcome,
+            cachedOutcome,
           },
-          effects,
+          [],
         ];
-
-      return tuple;
-    }
-    case "settle/failure": {
-      if (!canSettle(state)) return tuple;
-
-      // ignore outdated responses
-      if (state.pending?.id !== action.id) return tuple;
-
-      if (action.thrownError) {
-        console.error("@happykit/flags: Failed to load flags");
-        console.error(action.thrownError);
       }
+      case "settle/success": {
+        if (!canSettle(state)) return tuple;
 
-      const cachedOutcome = cache.get<SuccessOutcome<F>>(action.input);
-      return [
-        {
-          name: "failed",
-          input: action.input,
-          outcome: action.outcome,
-          cachedOutcome,
-        },
-        [],
-      ];
-    }
-    case "settle/success": {
-      if (!canSettle(state)) return tuple;
+        // ignore outdated responses
+        if (state.pending?.id !== action.id) return tuple;
 
-      // ignore outdated responses
-      if (state.pending?.id !== action.id) return tuple;
+        const visitorKey = action.outcome.data.visitor?.key;
+        if (visitorKey) {
+          const visitorKeyCookie = config.serializeVisitorKeyCookie(visitorKey);
+          if (visitorKeyCookie) document.cookie = visitorKeyCookie;
+        }
 
-      const visitorKey = action.outcome.data.visitor?.key;
-      if (visitorKey) document.cookie = serializeVisitorKeyCookie(visitorKey);
+        cache.set(action.input, action.outcome);
 
-      cache.set(action.input, action.outcome);
+        return [
+          {
+            name: "succeeded",
+            input: action.input,
+            outcome: action.outcome,
+          },
+          [],
+        ];
+      }
 
-      return [
-        {
-          name: "succeeded",
-          input: action.input,
-          outcome: action.outcome,
-        },
-        [],
-      ];
+      default:
+        return tuple;
     }
-
-    default:
-      return tuple;
-  }
+  };
 }
 
 function getInput<F extends Flags>({
@@ -409,6 +413,7 @@ export function createUseFlags<F extends Flags>(
   }: FactoryUseFlagOptions = {}
 ) {
   const config = applyConfigurationDefaults(configuration);
+  const reducer = createReducer(config);
 
   return function useFlags(options: UseFlagsOptions<F> = {}): FlagBag<F> {
     useOnce();

package/src/config.ts

@@ -49,4 +49,17 @@ export type Configuration<F extends Flags> = {
    * @default "https://happykit.dev/api/flags"
    */
   endpoint?: string;
+
+  /**
+   * Gets called with a visitorKey and must return a string which can be assigned to `document.cookie` or null.
+   *
+   * The name of the cookie you set within that string must be `hkvk` (short for "happykit visitor key").
+   *
+   * If the option is undefined, it will use the default implementation which sets the cookie for 180 days.
+   * You can override this with your own behavior or write a function which returns null to set no cookie at all.
+   *
+   * @param visitorKey the randomly assigned key of the visitor
+   * @returns null or cookie to set, for example `hkvk=${encodeURIComponent(visitorKey)}; Path=/; Max-Age=15552000; SameSite=Lax`
+   */
+  serializeVisitorKeyCookie?: (visitorKey: string) => string | null;
 };

package/src/internal/apply-configuration-defaults.ts

@@ -2,16 +2,24 @@ import type { Flags, FullConfiguration } from "./types";
 import type { Configuration } from "../config";
 import type { Environment } from "../evaluation-types";
 
+function serializeVisitorKeyCookie(visitorKey: string) {
+  // Max-Age 15552000 seconds equals 180 days
+  return `hkvk=${encodeURIComponent(
+    visitorKey
+  )}; Path=/; Max-Age=15552000; SameSite=Lax`;
+}
+
 export function applyConfigurationDefaults<F extends Flags>(
   incomingConfig: Configuration<F>
 ) {
   if (!incomingConfig) throw new Error("@happykit/flags: config missing");
   if (!incomingConfig.envKey || incomingConfig.envKey.length === 0)
     throw new Error("@happykit/flags: envKey missing");
 
-  const defaults = {
+  const defaults: Partial<Configuration<F>> = {
     endpoint: "https://happykit.dev/api/flags",
     defaultFlags: {} as F,
+    serializeVisitorKeyCookie,
   };
 
   const match = incomingConfig.envKey.match(

package/src/internal/utils.ts

@@ -68,13 +68,6 @@ export function getCookie(
   return null;
 }
 
-export function serializeVisitorKeyCookie(visitorKey: string) {
-  // Max-Age 15552000 seconds equals 180 days
-  return `hkvk=${encodeURIComponent(
-    visitorKey
-  )}; Path=/; Max-Age=15552000; SameSite=Lax`;
-}
-
 // source: https://github.com/lukeed/dequal/blob/master/src/lite.js
 export function deepEqual(objA: any, objB: any) {
   var ctor, len;

package/src/server.ts

@@ -18,7 +18,6 @@ import type {
 } from "./internal/types";
 import {
   has,
-  serializeVisitorKeyCookie,
   combineRawFlagsWithDefaultFlags,
   getCookie,
 } from "./internal/utils";
@@ -247,13 +246,16 @@ export function createGetFlags<F extends Flags>(
       }
 
       if (options.context && has(options.context, "req") && visitorKey) {
-        // always set the cookie so its max age refreshes
-        (
-          options.context as {
+        const visitorKeyCookie = config.serializeVisitorKeyCookie(visitorKey);
+
+        if (visitorKeyCookie) {
+          // always set the cookie so its max age refreshes
+          const context = options.context as {
             req: IncomingMessage;
             res: ServerResponse;
-          }
-        ).res.setHeader("Set-Cookie", serializeVisitorKeyCookie(visitorKey));
+          };
+          context.res.setHeader("Set-Cookie", visitorKeyCookie);
+        }
       }
 
       const evaluated = evaluate({
@@ -321,16 +323,17 @@ export function createGetFlags<F extends Flags>(
               has(options.context, "req") &&
               outcomeData.visitor?.key
             ) {
-              // always set the cookie so its max age refreshes
-              (
-                options.context as {
-                  req: IncomingMessage;
-                  res: ServerResponse;
-                }
-              ).res.setHeader(
-                "Set-Cookie",
-                serializeVisitorKeyCookie(outcomeData.visitor.key)
+              const visitorKeyCookie = config.serializeVisitorKeyCookie(
+                outcomeData.visitor.key
               );
+              // always set the cookie so its max age refreshes
+              const context = options.context as {
+                req: IncomingMessage;
+                res: ServerResponse;
+              };
+              if (visitorKeyCookie) {
+                context.res.setHeader("Set-Cookie", visitorKeyCookie);
+              }
             }
 
             // add defaults to flags here, but not in initialFlagState