refactor: improve public interface + don't expose resolver

Author: mjfaga

.eslintrc.cjs

@@ -12,6 +12,8 @@ module.exports = {
   },
   rules: {
     "@typescript-eslint/no-var-requires": "off",
+    "@typescript-eslint/method-signature-style": "off",
+    "@typescript-eslint/strict-boolean-expressions": "off",
     "promise/param-names": "off",
   },
 };

src/__tests__/reforgeClient.test.ts

@@ -0,0 +1,162 @@
+import { Reforge } from "../reforge";
+import { ConfigType, ConfigValueType } from "../types";
+import type { Config } from "../types";
+import { projectEnvIdUnderTest, irrelevant } from "./testHelpers";
+
+const createSimpleConfig = (key: string, value: string): Config => {
+  return {
+    id: "1",
+    projectId: 1,
+    key,
+    changedBy: undefined,
+    rows: [
+      {
+        properties: {},
+        values: [
+          {
+            criteria: [
+              {
+                propertyName: "user.country",
+                operator: "PROP_IS_ONE_OF" as any,
+                valueToMatch: {
+                  stringList: {
+                    values: ["US"],
+                  },
+                },
+              },
+            ],
+            value: { string: value },
+          },
+          {
+            criteria: [],
+            value: { string: "default" },
+          },
+        ],
+      },
+    ],
+    allowableValues: [],
+    configType: ConfigType.Config,
+    valueType: ConfigValueType.String,
+    sendToClientSdk: false,
+  };
+};
+
+describe("ReforgeClient", () => {
+  describe("withContext", () => {
+    it("returns a context-scoped client that doesn't expose internal resolver", () => {
+      const reforge = new Reforge({ sdkKey: irrelevant });
+      const config = createSimpleConfig("test.key", "us-value");
+      reforge.setConfig([config], projectEnvIdUnderTest, new Map());
+
+      const scopedClient = reforge.withContext({ user: { country: "US" } });
+
+      // Should have the public API methods
+      expect(typeof scopedClient.get).toBe("function");
+      expect(typeof scopedClient.isFeatureEnabled).toBe("function");
+      expect(typeof scopedClient.logger).toBe("function");
+      expect(typeof scopedClient.shouldLog).toBe("function");
+      expect(typeof scopedClient.getLogLevel).toBe("function");
+      expect(typeof scopedClient.withContext).toBe("function");
+      expect(typeof scopedClient.inContext).toBe("function");
+      expect(typeof scopedClient.updateIfStalerThan).toBe("function");
+      expect(typeof scopedClient.addConfigChangeListener).toBe("function");
+
+      // Should NOT expose internal resolver methods
+      expect((scopedClient as any).raw).toBeUndefined();
+      expect((scopedClient as any).set).toBeUndefined();
+      expect((scopedClient as any).keys).toBeUndefined();
+      expect((scopedClient as any).cloneWithContext).toBeUndefined();
+      expect((scopedClient as any).update).toBeUndefined();
+
+      // Should apply context correctly
+      expect(scopedClient.get("test.key")).toBe("us-value");
+    });
+
+    it("allows chaining withContext calls", () => {
+      const reforge = new Reforge({ sdkKey: irrelevant });
+      const config = createSimpleConfig("test.key", "us-value");
+      reforge.setConfig([config], projectEnvIdUnderTest, new Map());
+
+      const client1 = reforge.withContext({ user: { country: "FR" } });
+      expect(client1.get("test.key")).toBe("default");
+
+      const client2 = client1.withContext({ user: { country: "US" } });
+      expect(client2.get("test.key")).toBe("us-value");
+    });
+
+    it("merges context when additional context is provided to methods", () => {
+      const reforge = new Reforge({ sdkKey: irrelevant });
+      const config = createSimpleConfig("test.key", "us-value");
+      reforge.setConfig([config], projectEnvIdUnderTest, new Map());
+
+      const client = reforge.withContext({ user: { name: "Alice" } });
+
+      // Provide additional context that includes the country
+      expect(client.get("test.key", { user: { country: "US" } })).toBe(
+        "us-value"
+      );
+    });
+  });
+
+  describe("inContext", () => {
+    it("provides a context-scoped client to the callback", () => {
+      const reforge = new Reforge({ sdkKey: irrelevant });
+      const config = createSimpleConfig("test.key", "us-value");
+      reforge.setConfig([config], projectEnvIdUnderTest, new Map());
+
+      const result = reforge.inContext(
+        { user: { country: "US" } },
+        (client) => {
+          // Should not expose internal methods
+          expect((client as any).raw).toBeUndefined();
+          expect((client as any).set).toBeUndefined();
+
+          // Should apply context
+          expect(client.get("test.key")).toBe("us-value");
+
+          return "success";
+        }
+      );
+
+      expect(result).toBe("success");
+    });
+
+    it("allows nested inContext calls", () => {
+      const reforge = new Reforge({ sdkKey: irrelevant });
+      const config = createSimpleConfig("test.key", "us-value");
+      reforge.setConfig([config], projectEnvIdUnderTest, new Map());
+
+      reforge.inContext({ user: { country: "FR" } }, (outer) => {
+        expect(outer.get("test.key")).toBe("default");
+
+        outer.inContext({ user: { country: "US" } }, (inner) => {
+          expect(inner.get("test.key")).toBe("us-value");
+        });
+      });
+    });
+  });
+
+  describe("shared state", () => {
+    it("shares telemetry with parent", () => {
+      const reforge = new Reforge({ sdkKey: irrelevant });
+      reforge.setConfig([], projectEnvIdUnderTest, new Map());
+
+      const client = reforge.withContext({ user: { country: "US" } });
+
+      expect(client.telemetry).toBe(reforge.telemetry);
+    });
+
+    it("delegates methods to parent reforge instance", () => {
+      const reforge = new Reforge({ sdkKey: irrelevant });
+      reforge.setConfig([], projectEnvIdUnderTest, new Map());
+
+      const client = reforge.withContext({ user: { country: "US" } });
+
+      // Telemetry is shared
+      expect(client.telemetry).toBe(reforge.telemetry);
+
+      // getLogLevel delegates to parent
+      expect(typeof client.getLogLevel).toBe("function");
+    });
+  });
+});

src/evaluate.ts

@@ -10,14 +10,24 @@ import {
   type HashByPropertyValue,
   type ProjectEnvId,
 } from "./types";
-import type { MinimumConfig, Resolver } from "./resolver";
+import type { MinimumConfig } from "./resolver";
 
 import { type GetValue, unwrap } from "./unwrap";
 import { contextLookup } from "./contextLookup";
 import { sortRows } from "./sortRows";
 import SemanticVersion from "./semanticversion";
 import { isBigInt, jsonStringifyWithBigInt } from "./bigIntUtils";
 
+/**
+ * Minimal interface for resolving segments and encryption keys during evaluation.
+ * This interface is used internally to decouple evaluate.ts from the full Resolver.
+ * @internal
+ */
+interface SegmentResolver {
+  raw(key: string): MinimumConfig | undefined;
+  get(key: string, contexts?: Contexts): unknown;
+}
+
 const getHashByPropertyValue = (
   value: ConfigValue | undefined,
   contexts: Contexts
@@ -102,7 +112,7 @@ const propContainsOneOf = (
 const inSegment = (
   criterion: Criterion,
   contexts: Contexts,
-  resolver: Resolver
+  resolver: SegmentResolver
 ): boolean => {
   const segmentKey = criterion.valueToMatch?.string;
 
@@ -282,7 +292,7 @@ const allCriteriaMatch = (
   value: ConditionalValue,
   namespace: string | undefined,
   contexts: Contexts,
-  resolver: Resolver
+  resolver: SegmentResolver
 ): boolean => {
   if (value.criteria === undefined) {
     return true;
@@ -380,7 +390,7 @@ const matchingConfigValue = (
   projectEnvId: ProjectEnvId,
   namespace: string | undefined,
   contexts: Contexts,
-  resolver: Resolver
+  resolver: SegmentResolver
 ): [number, number, ConfigValue | undefined] => {
   let match: ConfigValue | undefined;
   let conditionalValueIndex: number = -1;
@@ -413,7 +423,7 @@ export interface EvaluateArgs {
   projectEnvId: ProjectEnvId;
   namespace: string | undefined;
   contexts: Contexts;
-  resolver: Resolver;
+  resolver: SegmentResolver;
 }
 
 export interface Evaluation {

src/reforge.ts

@@ -1,6 +1,6 @@
 import { apiClient, type ApiClient } from "./apiClient";
 import { loadConfig } from "./loadConfig";
-import { Resolver, type MinimumConfig, type ResolverAPI } from "./resolver";
+import { Resolver, type MinimumConfig } from "./resolver";
 import { Sources } from "./sources";
 import { jsonStringifyWithBigInt } from "./bigIntUtils";
 import {
@@ -25,6 +25,7 @@ import type {
 import { LOG_LEVEL_RANK_LOOKUP, type makeLogger } from "./logger";
 import { SSEConnection } from "./sseConnection";
 import { TelemetryReporter } from "./telemetry/reporter";
+import { ReforgeClient } from "./reforgeClient";
 
 import type { ContextUploadMode } from "./telemetry/types";
 import { knownLoggers } from "./telemetry/knownLoggers";
@@ -83,7 +84,8 @@ export interface ReforgeInterface {
   ) => boolean;
   logger: (
     loggerName: string,
-    defaultLevel: LogLevel
+    defaultLevel?: LogLevel,
+    contexts?: Contexts | ContextObj
   ) => ReturnType<typeof makeLogger>;
   shouldLog: ({
     loggerName,
@@ -99,7 +101,11 @@ export interface ReforgeInterface {
   getLogLevel: (loggerName: string) => LogLevel;
   telemetry?: Telemetry;
   updateIfStalerThan: (durationInMs: number) => Promise<void> | undefined;
-  withContext: (contexts: Contexts | ContextObj) => ResolverAPI;
+  withContext: (contexts: Contexts | ContextObj) => ReforgeInterface;
+  inContext: <T>(
+    contexts: Contexts | ContextObj,
+    func: (reforge: ReforgeInterface) => T
+  ) => T;
   addConfigChangeListener: (callback: GlobalListenerCallback) => () => void;
 }
 
@@ -129,6 +135,7 @@ interface ConstructorProps {
   onUpdate?: (configs: Array<Config | MinimumConfig>) => void;
 }
 
+
 class Reforge implements ReforgeInterface {
   private readonly sdkKey: string;
   readonly sources: Sources;
@@ -411,17 +418,17 @@ class Reforge implements ReforgeInterface {
 
   inContext<T>(
     contexts: Contexts | ContextObj,
-    func: (reforge: Resolver) => T
+    func: (reforge: ReforgeInterface) => T
   ): T {
     requireResolver(this.resolver);
 
-    return func(this.resolver.cloneWithContext(contexts));
+    return func(new ReforgeClient(this, contexts));
   }
 
-  withContext(contexts: Contexts | ContextObj): ResolverAPI {
+  withContext(contexts: Contexts | ContextObj): ReforgeInterface {
     requireResolver(this.resolver);
 
-    return this.resolver.cloneWithContext(contexts);
+    return new ReforgeClient(this, contexts);
   }
 
   get<K extends keyof TypedNodeServerConfigurationRaw>(
@@ -562,5 +569,4 @@ export {
   type Contexts,
   SchemaType,
   type Provided,
-  Resolver,
 };