feat: add scoped clients to server sdks

Author: joker23

packages/sdk/react/__tests__/server/createLDServerSession.test.ts

@@ -150,6 +150,55 @@ it('allFlagsState() forwards options to base client', async () => {
   expect(client.allFlagsState).toHaveBeenCalledWith(context, options);
 });
 
+describe('given a client with forContext', () => {
+  function makeMockScopedBaseClient() {
+    const base = makeMockBaseClient();
+    const forContext = jest.fn((ctx: LDContext) => ({
+      currentContext: () => ctx,
+      boolVariation: (key: string, def: boolean) => base.boolVariation(key, ctx, def),
+      numberVariation: (key: string, def: number) => base.numberVariation(key, ctx, def),
+      stringVariation: (key: string, def: string) => base.stringVariation(key, ctx, def),
+      jsonVariation: (key: string, def: unknown) => base.jsonVariation(key, ctx, def),
+      boolVariationDetail: (key: string, def: boolean) => base.boolVariationDetail(key, ctx, def),
+      numberVariationDetail: (key: string, def: number) =>
+        base.numberVariationDetail(key, ctx, def),
+      stringVariationDetail: (key: string, def: string) =>
+        base.stringVariationDetail(key, ctx, def),
+      jsonVariationDetail: (key: string, def: unknown) => base.jsonVariationDetail(key, ctx, def),
+      allFlagsState: (options?: LDFlagsStateOptions) => base.allFlagsState(ctx, options),
+    }));
+    return { ...base, forContext } as any;
+  }
+
+  it('uses forContext when available', () => {
+    const client = makeMockScopedBaseClient();
+    createLDServerSession(client, context);
+    expect(client.forContext).toHaveBeenCalledWith(context, { wrapperName: 'react-server-sdk' });
+  });
+
+  it('delegates boolVariation through scoped client', async () => {
+    const client = makeMockScopedBaseClient();
+    client.boolVariation.mockResolvedValue(true);
+    const session = createLDServerSession(client, context);
+    const result = await session.boolVariation('my-flag', false);
+    expect(result).toBe(true);
+    expect(client.boolVariation).toHaveBeenCalledWith('my-flag', context, false);
+  });
+
+  it('getContext() returns the scoped client currentContext', () => {
+    const client = makeMockScopedBaseClient();
+    const session = createLDServerSession(client, context);
+    expect(session.getContext()).toEqual(context);
+  });
+
+  it('initialized() delegates to the base client', () => {
+    const client = makeMockScopedBaseClient();
+    client.initialized.mockReturnValue(false);
+    const session = createLDServerSession(client, context);
+    expect(session.initialized()).toBe(false);
+  });
+});
+
 describe('given a browser environment (window defined)', () => {
   let originalWindow: typeof globalThis.window;
 

packages/sdk/react/src/server/LDServerBaseClient.ts

@@ -3,6 +3,8 @@ import {
   LDEvaluationDetailTyped,
   LDFlagsState,
   LDFlagsStateOptions,
+  LDScopedClient,
+  LDScopedClientOptions,
 } from '@launchdarkly/js-server-sdk-common';
 
 /**
@@ -88,4 +90,14 @@ export interface LDServerBaseClient {
    * Builds an object encapsulating the state of all feature flags for a given context.
    */
   allFlagsState(context: LDContext, options?: LDFlagsStateOptions): Promise<LDFlagsState>;
+
+  /**
+   * Creates a scoped client bound to the given evaluation context.
+   *
+   * @remarks
+   * When present, {@link createLDServerSession} will delegate to the scoped client
+   * instead of manually wrapping each method. Clients that do not implement this
+   * method (e.g., edge SDKs) fall back to the manual wrapping behavior.
+   */
+  forContext?(context: LDContext, options?: LDScopedClientOptions): LDScopedClient;
 }

packages/sdk/react/src/server/LDServerSession.ts

@@ -53,6 +53,24 @@ export function createLDServerWrapper(
     );
   }
 
+  if (client.forContext) {
+    const scoped = client.forContext(context, { wrapperName: 'react-server-sdk' });
+    return {
+      initialized: () => client.initialized(),
+      getContext: () => scoped.currentContext(),
+      boolVariation: scoped.boolVariation,
+      numberVariation: scoped.numberVariation,
+      stringVariation: scoped.stringVariation,
+      jsonVariation: scoped.jsonVariation,
+      boolVariationDetail: scoped.boolVariationDetail,
+      numberVariationDetail: scoped.numberVariationDetail,
+      stringVariationDetail: scoped.stringVariationDetail,
+      jsonVariationDetail: scoped.jsonVariationDetail,
+      allFlagsState: scoped.allFlagsState,
+    };
+  }
+
+  // Fallback for clients without forContext (e.g., edge SDKs)
   return {
     initialized: () => client.initialized(),
     getContext: () => context,